feat(skills): skill-flow connectivity gate + closed consumes vocabulary

.github/workflows/validate.yml

@@ -821,6 +821,12 @@ jobs:
           chmod +x scripts/validate-context-map-drift.sh
           bash scripts/validate-context-map-drift.sh
 
+      - name: Validate skill-flow connectivity and closed consumes vocabulary
+        if: needs.changes.outputs.skills == 'true' || needs.changes.outputs.contracts == 'true' || needs.changes.outputs.shell == 'true' || needs.changes.outputs.ci == 'true'
+        run: |
+          chmod +x scripts/validate-skill-flow.sh
+          bash scripts/validate-skill-flow.sh
+
       - name: Verify embedded lib/skills are in sync
         if: needs.changes.outputs.hooks == 'true' || needs.changes.outputs.go == 'true' || needs.changes.outputs.ci == 'true'
         run: |

docs/contracts/context-map.md

@@ -117,6 +117,7 @@ graph LR
   complexity -- "shared-kernel" --> standards
   council -- "shared-kernel" --> standards
   crank -- "shared-kernel" --> standards
+  deps -- "supplier-to" --> vibe
   design -- "shared-kernel" --> standards
   discovery -- "shared-kernel" --> standards
   evolve -- "customer-of" --> rpi
@@ -134,13 +135,17 @@ graph LR
   pr-validate -- "customer-of" --> validation
   pre-mortem -- "shared-kernel" --> standards
   product -- "shared-kernel" --> standards
+  provenance -- "supplier-to" --> trace
   quickstart -- "customer-of" --> rpi
   ratchet -- "shared-kernel" --> standards
+  red-team -- "supplier-to" --> vibe
+  release -- "supplier-to" --> ship-loop
   retro -- "shared-kernel" --> standards
   review -- "customer-of" --> validation
   rpi -- "customer-of" --> crank
   rpi -- "customer-of" --> discovery
   rpi -- "customer-of" --> validation
+  scenario -- "supplier-to" --> validation
   scope -- "supplier-to" --> domain
   security -- "supplier-to" --> vibe
   security-suite -- "supplier-to" --> vibe
@@ -156,6 +161,7 @@ graph LR
   skill-builder -- "customer-of" --> automation-shape-routing
   skill-builder -- "supplier-to" --> skill-auditor
   swarm -- "customer-of" --> crank
+  trace -- "customer-of" --> provenance
   validate -- "customer-of" --> validation
   validation -- "shared-kernel" --> standards
   vibe -- "shared-kernel" --> standards

docs/contracts/skill-flow.md

@@ -0,0 +1,90 @@
+# Skill-Flow Connectivity Contract
+
+> Gate: `scripts/validate-skill-flow.sh` (CI job `validate-skill-flow`).
+> Allowlist: `scripts/skill-flow-standalone.txt`.
+> Source of truth: `skills/*/SKILL.md` frontmatter.
+> Sibling: `scripts/audit-skill-metadata.sh` owns `context_rel.with` resolution;
+> this contract owns the `consumes` vocabulary and connectivity.
+
+## Why this exists
+
+"Do all skills flow together?" was unanswerable until this gate. Skill
+dependencies are declared in **three overlapping frontmatter fields** that
+historically drifted apart:
+
+| Field | Meaning | Read by context-map? |
+|-------|---------|----------------------|
+| `consumes` | upstream inputs (skill slug, external input, or produced artifact) | yes (data-flow table) |
+| `context_rel` | DDD bounded-context relationship (`kind` + `with`) | yes (mermaid graph) |
+| `metadata.dependencies` | upstream skill slugs | **no** |
+
+Because the three are not reconciled, a skill can look "orphaned" in one field
+while being well-connected in another (e.g. `trace` declares no `consumes` but
+depends on `provenance` via `metadata.dependencies`). This contract defines a
+single connectivity model that spans all three and a closed vocabulary for
+`consumes`.
+
+## Rules (enforced — gate fails on violation)
+
+### 1. Closed `consumes` vocabulary
+
+Every `consumes` token MUST resolve to exactly one of:
+
+1. a **peer skill slug** (a directory under `skills/`), or
+2. a **whitelisted external input**, or
+3. an **artifact produced by some skill** (appears in another skill's `produces`).
+
+Anything else is a typo or an undeclared dependency and fails the gate.
+
+**External inputs** (the closed whitelist — extend deliberately, in both
+`scripts/validate-skill-flow.sh` and this doc):
+
+| Token | What it is |
+|-------|-----------|
+| `repo-context` | the repository working tree / source under analysis |
+| `external-api` | an upstream API or doc site outside the corpus |
+| `bd` | the beads issue store |
+| `github-pr` | a GitHub pull request under review |
+| `onboard` | the session onboarding handshake |
+
+### 2. `metadata.dependencies` resolution
+
+Every `metadata.dependencies` entry MUST name an existing skill slug.
+
+### 3. Connectivity (no silent orphans)
+
+A skill is **connected** if it shares at least one skill-to-skill edge with a
+peer, counting all three layers (`consumes` skill-slugs, `context_rel.with`
+skill-slugs, `metadata.dependencies`). A skill with **zero** skill-to-skill
+edges is an **orphan** and fails the gate **unless** it is listed in
+`scripts/skill-flow-standalone.txt` with a rationale.
+
+Standalone skills are intentional leaves: boundary adapters (`push`,
+`openai-docs`), orchestration/install adapters (`codex-team`,
+`session-bootstrap`), and human-facing explainers (`using-agentops`). Listing a
+skill there asserts "this is a leaf by design." If it later gains an edge, the
+gate reports a **stale allowlist entry** — remove it.
+
+## Reported, not enforced (informational)
+
+The gate prints (without failing) two reconciliation signals:
+
+- **`consumes` vs `metadata.dependencies` disagreement** — the two skill-slug
+  fields that should agree but historically drifted. Reconciling them (picking
+  one canonical field) is tracked work, not a blocker.
+- **Dead-end produced artifacts** — artifacts in some skill's `produces` that no
+  skill `consumes`. Most are output-type annotations (`result.json`,
+  `verdict.json`, `stdout`), not edges, so this is informational.
+
+## How to fix a failure
+
+```bash
+bash scripts/validate-skill-flow.sh          # human-readable findings
+bash scripts/validate-skill-flow.sh --json   # machine-readable verdict
+```
+
+- **consumes-vocabulary**: fix the typo, or declare the producer, or (if it is a
+  genuinely new external input) add it to the whitelist above and in the script.
+- **metadata-dependencies**: point at a real skill slug or drop the entry.
+- **orphan**: wire a real `context_rel`/`consumes`/`metadata.dependencies` edge,
+  or add the slug to `scripts/skill-flow-standalone.txt` with a one-line reason.

docs/documentation-index.md

@@ -276,6 +276,7 @@ Bridge / framing docs:
 - [Local Pre-Push Gate Retirement](contracts/local-pre-push-gate-retirement.md) — ADR (soc-g2r9): CI is the sole authoritative push gate; `scripts/pre-push-gate.sh` and its helpers are retired in follow-up waves; AP#7 mechanical enforcement migrates from pre-push to a validate.yml job
 - [Skill Dispositions (yaml)](contracts/skill-dispositions.yaml) — Canonical per-skill domain/disposition/rationale data; source-of-truth for `agentops-skill-domain-map.md`. Hand-edits to the .md forbidden — edit yaml and run `scripts/generate-skill-domain-map.sh` (golden-file gate, soc-zxia.3)
 - [Context Map](contracts/context-map.md) — Auto-generated bounded-context map of skills by hexagonal role with relationship and data-flow views (see ADR-0001)
+- [Skill-Flow Connectivity](contracts/skill-flow.md) — Closed `consumes` vocabulary + cross-layer connectivity model (`consumes`/`context_rel`/`metadata.dependencies`); gate `scripts/validate-skill-flow.sh` (`validate-skill-flow`) fails on unresolved tokens or un-allowlisted orphans; standalone leaves in `scripts/skill-flow-standalone.txt`
 - [PMF Evidence Gate](contracts/pmf-evidence.md) — Public docs (PRODUCT.md, README, launch artifacts) must promote `.agents/` evidence to `docs/evidence/<bead-id>/` via `scripts/export-evidence.sh`; `scripts/check-pmf-evidence.sh` is the gate (soc-m6v5.8)
 - [Skill Domain Map](contracts/skill-domain-map.md) — V0 DDD map assigning every shared skill to one explicit skill domain with ports, artifacts, and adapters
 - [Registry as derived artifact](contracts/registry-as-derived.md) — Design contract (soc-jbea, status:design): move `registry.json` out of version control to eliminate sibling-PR conflict cascade (40-50% of waste in the 2026-05-20 PR-cleanup session per Council 220-240). Same pattern for `skills-codex/.agentops-manifest.json` and `skills-codex/*/.agentops-generated.json`. Implementation deferred to soc-jbea.1 through soc-jbea.7.

scripts/skill-flow-standalone.txt

@@ -0,0 +1,35 @@
+# skill-flow-standalone.txt — intentionally-standalone skills.
+#
+# Skills listed here are permitted to have ZERO skill-to-skill edges (no peer
+# referenced in consumes/context_rel/metadata.dependencies, and not referenced
+# by any peer). They are boundary adapters, meta-tooling, or human-facing
+# explainers that legitimately do not participate in the inter-skill flow.
+#
+# Enforced by scripts/validate-skill-flow.sh. Adding a skill here is a
+# deliberate act: it asserts "this skill is a leaf by design." If a skill here
+# later gains an edge, the gate flags it as a stale entry — remove it.
+#
+# Contract: docs/contracts/skill-flow.md
+# Format: one skill slug per line; everything after '#' is a comment.
+
+# --- knowledge / .agents boundary writers (emit .agents/research/*.md; the
+#     flywheel reads them out-of-band, not via a declared skill edge) ---
+curate                    # mine transcripts/.agents/bd/git into knowledge diffs
+dream                     # retired pointer; out-of-session compounding via Gas City
+handoff                   # write compact session handoff notes
+reverse-engineer-rpi      # reverse-engineer product specs into research notes
+
+# --- external-boundary adapters (driven adapters to systems outside the corpus) ---
+openai-docs               # reads upstream OpenAI docs (external-api)
+pr-research               # researches an upstream OSS repo (external-api)
+status                    # reports bd work status (external bd store)
+push                      # commits/pushes git-changes (terminal VCS sink)
+
+# --- orchestration / install adapters (drive other agents or install artifacts) ---
+codex-team                # coordinate multiple Codex agents (orchestration)
+session-bootstrap         # universal init entry point (customer-of AGENTS*.md docs)
+system-tuning             # restore system responsiveness (process/host hygiene)
+
+# --- human-facing explainers (documentation skills, no pipeline role) ---
+using-agentops            # explain AgentOps workflows
+using-gc                  # explain running AgentOps on the Gas City substrate