forge-workflow 0.1.0-beta.3 → 0.1.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Local runtime control plane for AI-assisted engineering workflows, gates, evidence, and all AI agents",
   "bin": {
     "forge": "bin/forge.js",

package/rules/using-forge.md

@@ -0,0 +1,24 @@
+---
+description: "Always: before any response, if a Forge skill could apply, invoke it (or run forge skill for)"
+alwaysApply: true
+globs: []
+---
+
+# Using Forge (skill dispatch — auto-trigger)
+
+**Before ANY response or action** — including clarifying questions, exploring the
+codebase, or checking files — if there is even a **1% chance** a Forge skill
+applies to what you are doing, invoke that skill first. Then announce
+`Using [skill] to [purpose]` and follow it.
+
+- Not sure which skill fits? Run `forge skill for "<what you are about to do>"`
+  for the deterministic best-fit, or read the routing table in the dispatch skill.
+- Common routes: build/scope a feature -> plan; implement a task -> dev; fix a
+  failing test -> dev (debug first); run checks/lint/tests -> validate; open a PR
+  -> ship; address review feedback -> review; where am I -> status.
+
+This rule is a **thin pointer**. The full 1%-rule, red-flags table, subagent
+escape hatch, and routing table live in the **`using-forge` dispatch skill**,
+installed into your agent's own skill surface by `forge setup` (for Cursor:
+`.cursor/skills/using-forge/SKILL.md`) — invoke it by name, or run
+`forge skill for "<situation>"`. Do not duplicate that policy here.

package/scripts/forge-team/index.sh

@@ -4,7 +4,6 @@
 # Subcommands:
 #   workload    Show team workload by developer
 #   epic        Epic progress rollup
-#   dashboard   Team health dashboard
 #   add         Add developer to team map
 #   verify      Check 1:1 Beads<>GitHub enforcement
 #   sync        Manual GitHub<>Beads sync
@@ -22,7 +21,6 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 [[ -f "$SCRIPT_DIR/lib/identity.sh" ]] && source "$SCRIPT_DIR/lib/identity.sh"
 [[ -f "$SCRIPT_DIR/lib/workload.sh" ]] && source "$SCRIPT_DIR/lib/workload.sh"
 [[ -f "$SCRIPT_DIR/lib/epic.sh" ]] && source "$SCRIPT_DIR/lib/epic.sh"
-[[ -f "$SCRIPT_DIR/lib/dashboard.sh" ]] && source "$SCRIPT_DIR/lib/dashboard.sh"
 [[ -f "$SCRIPT_DIR/lib/hooks.sh" ]] && source "$SCRIPT_DIR/lib/hooks.sh"
 [[ -f "$SCRIPT_DIR/lib/verify.sh" ]] && source "$SCRIPT_DIR/lib/verify.sh"
 [[ -f "$SCRIPT_DIR/lib/claim.sh" ]] && source "$SCRIPT_DIR/lib/claim.sh"
@@ -34,7 +32,6 @@ FORGE_SCRIPTS="$(cd "$SCRIPT_DIR/.." && pwd)"
 # ── Stub implementations ──
 # cmd_workload provided by lib/workload.sh
 # cmd_epic provided by lib/epic.sh
-# cmd_dashboard provided by lib/dashboard.sh
 cmd_add() { auto_detect_identity "$@"; }
 # cmd_verify provided by lib/verify.sh
 cmd_sync() { forge_team_sync "$@"; }
@@ -47,7 +44,6 @@ Usage: forge team <subcommand> [args...]
 Subcommands:
   workload [--developer=<user>] [--me]  Show team workload
   epic <issue-id>                        Epic progress rollup
-  dashboard                              Team health dashboard
   add [--github=<user>]                  Add developer to team map
   verify                                 Check 1:1 Beads<>GitHub sync
   sync                                   Manual GitHub<>Beads sync
@@ -69,7 +65,6 @@ main() {
   case "$subcommand" in
     workload)   cmd_workload "$@" ;;
     epic)       cmd_epic "$@" ;;
-    dashboard)  cmd_dashboard "$@" ;;
     add)        cmd_add "$@" ;;
     verify)     cmd_verify "$@" ;;
     sync)       cmd_sync "$@" ;;

package/scripts/forge-team/tests/dispatcher.test.sh

@@ -60,7 +60,7 @@ assert_output_contains "unknown subcommand shows error" "unknown subcommand" bas
 # Test 4: Each stub subcommand is reachable (exits 0)
 echo ""
 echo "-- stub subcommands reachable --"
-for cmd in workload epic dashboard add verify sync claim; do
+for cmd in workload epic add verify sync claim; do
   assert_exit "$cmd exits 0" 0 bash "$DISPATCHER" "$cmd"
   assert_output_contains "$cmd outputs stub message" "not implemented" bash "$DISPATCHER" "$cmd"
 done

package/scripts/forge-team/tests/workflow-integration.test.sh

@@ -17,7 +17,6 @@ assert_contains_file() {
 echo "── /status integration ──"
 STATUS="$SCRIPT_DIR/.claude/commands/status.md"
 assert_contains_file "status calls workload --me" "forge-team.*workload.*--me" "$STATUS"
-assert_contains_file "status calls dashboard" "forge-team.*dashboard" "$STATUS"
 
 echo ""
 echo "── /plan integration ──"

package/scripts/test.js

@@ -156,6 +156,8 @@ function isKnownTargetablePath(file) {
 
   if (file === 'README.md'
     || file === 'bin/forge.js'
+    || file === 'bin/forge-cmd.js'
+    || file === 'bin/forge-preflight.js'
     || file === 'QUICKSTART.md'
     || file === 'CHANGELOG.md'
     || file === 'AGENTS.md'
@@ -166,7 +168,12 @@ function isKnownTargetablePath(file) {
     || file.startsWith('docs/guides/')
     || file.startsWith('docs/plans/')
     || file.startsWith('docs/reference/')
-    || file.startsWith('docs/work/')) {
+    || file.startsWith('docs/work/')
+    // Skill sources + their committed mirror map to the skill suite (see
+    // SKILL_TEST_TARGETS in lib/commands/test.js); a skills-only PR stays on the
+    // targeted lane instead of the full suite.
+    || file.startsWith('skills/')
+    || file.startsWith('.agents/skills/')) {
     return true;
   }
 

package/skills/claim-safety/SKILL.md

@@ -14,10 +14,14 @@ description: >
   and NOT for read-only selecting or ranking the next ready issue without claiming (that is
   triage-ready).
 allowed-tools: Read, Bash(forge:*)
+next: dev
+terminal: false
 ---
 
 # Claim safety — claim, then prove you own the lease
 
+> **Chain:** once you have PROVEN the lease (`forge issue owns <id>` exits 0), continue to `dev` to work the issue (`smith` proceeds into plan/dev after this proof). Usable standalone whenever ownership is in question.
+
 Claiming is not owning. The Forge kernel keys a claim's idempotency on
 `claim.create:<issue_id>:<actor>`, so a **same-key duplicate replay returns
 `ok:true`** echoing the *current* call's `claim_id`. A genuine cross-actor

package/skills/claim-safety/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "claim-safety",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 995,
+      "body_lines": 88,
+      "score": 43
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/skills/coverage.json

@@ -0,0 +1,83 @@
+{
+  "version": 1,
+  "description": "Command -> owning-skill coverage map (plan 2026-07-20-next-phase-plan.md §3.3). Every registered user-facing command MUST map to an existing skill OR carry an explicit { exempt: <reason> }. Enforced by the coverage gate (lib/skill-eval.js evaluateCoverage, surfaced by `forge skill coverage`/`forge skill scores`, gated in test/skill-eval.test.js). Exempts reference the pending skill from plan §3.2 and are tightened as those skills land.",
+  "commands": {
+    "plan": "plan",
+    "dev": "dev",
+    "validate": "validate",
+    "ship": "ship",
+    "shepherd": "shepherd",
+    "status": "status",
+    "prime": "status",
+    "orient": "hermes-forge",
+    "recap": "hermes-forge",
+    "remember": "memory",
+    "recall": "memory",
+    "memory": "memory",
+    "ready": "triage-ready",
+    "blocked": "triage-ready",
+    "claim": "claim-safety",
+    "claims": "claim-safety",
+    "issue": "issue-basics",
+    "issues": "issue-basics",
+    "create": "issue-basics",
+    "close": "issue-basics",
+    "comment": "issue-basics",
+    "show": "issue-basics",
+    "update": "issue-basics",
+    "list": "issue-basics",
+    "skill": "using-forge",
+
+    "worktree": "worktree",
+    "clean": "worktree",
+    "orphans": { "exempt": "full ownership (command-name routing + `forge issue orphans` guidance in the issue-basics body) pending — issue e1e33cf8; issue-basics does not yet document it, so mapping now would be a hollow claim" },
+    "rollback": "rollback",
+    "review": "review",
+    "verify": "verify",
+    "check": { "exempt": "legacy alias for `validate` (renamed in PR #50) — bin/forge-cmd.js VALID_COMMANDS only; owned by the `validate` skill" },
+    "docs": { "exempt": "bin/forge.js-direct; AGENTS.md/docs management — owning skill pending (coverage pass, plan §3.2)" },
+    "reset": "setup",
+    "reinstall": "setup",
+
+    "gate": "gates",
+    "control": "gates",
+    "doc-gate": "gates",
+
+    "adapter": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "add": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "new": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "audit": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "role": { "exempt": "extensions skill pending — role/skill binding (plan §3.2 B)" },
+
+    "export": "portability",
+    "migrate": "portability",
+    "sync": { "exempt": "cloud-native external-platform sync (ADR-0004); a local no-op with no value until a server backend is configured — skill deferred (issue 666f4b4c)" },
+
+    "inbox": { "exempt": "team skill pending (plan §3.2 B: new `team` skill)" },
+    "serve": { "exempt": "team skill pending (plan §3.2 B: new `team` skill)" },
+    "team": { "exempt": "team skill pending (plan §3.2 B: new `team` skill)" },
+
+    "setup": "setup",
+    "init": "setup",
+    "upgrade": "setup",
+    "doctor": "setup",
+    "hooks": "setup",
+    "recommend": "setup",
+
+    "push": { "exempt": "ship skill push/preflight extension pending (plan §3.2 B)" },
+    "preflight": { "exempt": "ship skill push/preflight extension pending (plan §3.2 B)" },
+    "pr": { "exempt": "ship/shepherd PR-lifecycle extension pending (plan §3.2)" },
+    "merge": { "exempt": "ship/shepherd PR-lifecycle extension pending (plan §3.2)" },
+
+    "patch": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "stage": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "explain": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "options": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "insights": { "exempt": "kernel skill fold pending — kernel evidence inspection (plan §3.2 C)" },
+
+    "lint": { "exempt": "internal quality plumbing; skill assignment pending (coverage pass)" },
+    "release": { "exempt": "internal release plumbing; skill assignment pending (coverage pass)" },
+    "test": { "exempt": "internal test-runner plumbing; skill assignment pending (coverage pass)" },
+    "stale": { "exempt": "internal stale-detection plumbing; skill assignment pending (coverage pass)" }
+  }
+}

package/skills/dev/SKILL.md

@@ -13,12 +13,16 @@ description: >
   opening the PR (ship), for addressing PR review feedback (review), or for orchestrating
   several stages / taking an issue end-to-end to a merged PR (smith).
 allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+next: validate
+terminal: false
 ---
 
 Implement each task from the /plan task list using a subagent-driven loop: implementer → spec compliance reviewer → code quality reviewer per task.
 
 # Dev
 
+> **Chain (HARD-GATE):** the ONLY skill you invoke after `dev` is `validate`. Never open a PR straight from `dev`.
+
 This skill reads the task list created by `/plan` and implements each task using a three-stage subagent loop. TDD is enforced inside each implementer subagent.
 
 ## Usage

package/skills/dev/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "dev",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 962,
+      "body_lines": 328,
+      "score": 20
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 76
+}

package/skills/gates/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: gates
+description: >
+  Toggle Forge's workflow gates and rails — strong-but-toggleable enforcement. `forge gate
+  enable|disable <gate-id>` flips `workflow.gates.<id>.enabled` in `.forge/config.yaml`; the
+  installed git hooks read resolved config at run time, so disabling a rail makes them
+  genuinely inert. `forge gate approve|reject <issue> <gate>` records durable human-gate
+  approval events; `forge gate status`/`check` query them; `forge control <id>
+  <mandatory|optional|permission>` sets tri-state DECLARED intent (writes the same `enabled`
+  field — no independent runtime enforcement). Use when the user says "disable the gate",
+  "turn off TDD enforcement", "the tdd intent rail is blocking me", "toggle or enable a
+  gate", "loosen enforcement", or "approve a human gate". Common default-ON toggleable rails:
+  `rail.tdd_intent`, `rail.kernel_tracking`, `rail.auto_shepherd` — e.g. `forge gate disable
+  rail.tdd_intent`. NOT for addressing PR review feedback (review), NOT the status snapshot
+  of work in flight (status).
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Forge's gates and rails are **default-strong but toggleable**. The `gates` skill is how you flip one off (or back on), record a human-gate approval, and see enforcement state. The stored truth is one field — `workflow.gates.<id>.enabled` — and the installed hooks read the resolved config at run time, so a disabled rail is genuinely inert, not cosmetically off.
+
+# Toggling gates and rails
+
+## When to use
+
+- "Disable the gate", "turn off TDD enforcement", "the tdd intent rail is blocking me".
+- "Toggle / enable a gate", "loosen enforcement for this repo".
+- "Approve a human gate" (record a durable approval event on an issue).
+
+## Toggle a gate or rail (the enforcement switch)
+
+```bash
+forge gate disable <gate-id>     # set workflow.gates.<id>.enabled = false in .forge/config.yaml
+forge gate enable  <gate-id>     # set it back to true
+```
+
+An unknown gate id — or disabling a **locked** gate — errors **before** anything is written, never mid-run. Because the hooks resolve config at run time, the flip takes effect immediately with no reinstall.
+
+### Common rails (default-ON, toggleable)
+
+| Rail | What it enforces | Turn off with |
+| --- | --- | --- |
+| `rail.tdd_intent` | Pre-commit TDD gate (source changed ⇒ tests changed). The `minimal` adoption profile ships it off. | `forge gate disable rail.tdd_intent` |
+| `rail.kernel_tracking` | "File every issue" — nothing discussed goes missing. | `forge gate disable rail.kernel_tracking` |
+| `rail.auto_shepherd` | The autonomous PR-shepherd daemon fire. | `forge gate disable rail.auto_shepherd` |
+
+The `gate.*` and `rail.*` id namespaces are disjoint, so `forge gate enable|disable` governs both through one flat surface.
+
+## Human-gate approval events
+
+```bash
+forge gate approve <issue-id> <gate-id>                     # record a durable gate.approved event
+forge gate reject  <issue-id> <gate-id>                     # record gate.rejected
+forge gate status  <issue-id>                               # list recorded events for that issue (resume-safe)
+forge gate check   <issue-id> <gate-id>                     # exit 0 iff gate DISABLED or an approval exists on that issue
+```
+
+`check` is the reusable enforcement primitive a stage skill calls: it passes when the gate is disabled or an approval event has been recorded for that specific issue id (approvals are issue-scoped, so pass the same `<issue-id>` you approved against). Events are durable on the issue, so they survive a compaction or crash.
+
+## Tri-state control (declared intent)
+
+```bash
+forge control <gate-id|rail-id> <mandatory|optional|permission>
+forge control status [--json]
+```
+
+`forge control` sets the **declared intent** vocabulary and writes the **same** `enabled` field that `forge gate` writes — there is deliberately no parallel key. It is a view/intent layer: today no runtime consumer denies purely on a control flag (MCP/rules/skills are presence-only and refused). For actually turning enforcement off, use `forge gate disable`.
+
+## The doc-update gate
+
+```bash
+forge gate doc <detect|check|init|...>     # = forge doc-gate (run `forge doc-gate --help`)
+```
+
+The doc-update gate folds under this noun as `forge gate doc`; bare `forge doc-gate` stays as a back-compat alias.
+
+## Adjacent skills
+
+- Addressing PR review feedback / resolving threads → `review`.
+- The snapshot of where the project stands and what's in flight → `status`.

package/skills/gates/evals/evals.json

@@ -0,0 +1,38 @@
+[
+  {
+    "query": "Disable the tdd gate for this repo.",
+    "should_trigger": true
+  },
+  {
+    "query": "Turn off TDD enforcement — the tdd intent rail is blocking my commit.",
+    "should_trigger": true
+  },
+  {
+    "query": "Toggle the kernel tracking rail off for now.",
+    "should_trigger": true
+  },
+  {
+    "query": "Enable a gate that I disabled earlier and loosen enforcement.",
+    "should_trigger": true
+  },
+  {
+    "query": "Approve the human gate on this issue so the stage can proceed.",
+    "should_trigger": true
+  },
+  {
+    "query": "Disable the auto shepherd rail so no PR daemon fires.",
+    "should_trigger": true
+  },
+  {
+    "query": "Address the CodeRabbit review feedback and resolve the threads.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow and what work is in flight right now?",
+    "should_trigger": false
+  },
+  {
+    "query": "Run the tests and lint before I push.",
+    "should_trigger": false
+  }
+]

package/skills/gates/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "gates",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 994,
+      "body_lines": 63,
+      "score": 45
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 6,
+    "reachable": true,
+    "keyword_alignment": 1
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 84
+}

package/skills/hermes-forge/SKILL.md

@@ -26,6 +26,7 @@ metadata:
   author: forge
   version: "1.0.0"
   roadmap: forge-2agy.9.7.x
+chainExempt: true
 ---
 
 # Hermes ⇄ Forge consumption contract

package/skills/hermes-forge/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "hermes-forge",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 993,
+      "body_lines": 157,
+      "score": 36
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 81
+}

package/skills/issue-basics/SKILL.md

@@ -14,6 +14,7 @@ description: >
   the plan->dev->validate->ship pipeline or open a PR (use smith or stage skills); does NOT
   report the current stage or what's in flight (use status).
 allowed-tools: Read, Bash(forge:*)
+terminal: true
 ---
 
 # Issue basics — the CRUD floor

package/skills/issue-basics/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "issue-basics",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 991,
+      "body_lines": 95,
+      "score": 42
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 0,
+    "reachable": false,
+    "keyword_alignment": 0
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 63
+}

package/skills/kernel/SKILL.md

@@ -14,6 +14,7 @@ description: >
   merged PR under gates → `smith`; token-bounded state for the Hermes harness →
   `hermes-forge`.
 allowed-tools: Read, Bash(forge:*)
+terminal: true
 ---
 
 # Forge kernel surface
@@ -56,6 +57,43 @@ mutating it — a claim returning ok:true does not by itself prove ownership).
 status → plan → dev → validate → ship → review → verify
 ```
 
+### Chain map (each skill declares its successor)
+
+Every skill carries chain metadata in its frontmatter (`next`, `terminal`,
+`subskills`, `handoffs`); each workflow STAGE skill additionally carries a
+HARD-GATE chain line in its body, so each stage announces the next one. The
+linear ladder:
+
+| Skill | `next` | `terminal` |
+|-------|--------|-----------|
+| `plan` | `dev` | `false` |
+| `dev` | `validate` | `false` |
+| `validate` | `ship` | `false` |
+| `ship` | `review` | `false` |
+| `review` | `verify` | `false` |
+| `verify` | `ship` | `false` |
+
+The `next` column is each stage's DEFAULT / critical-path successor (`plan`
+composes `research`; `ship` and `review` also carry a `shepherd` handoff). The
+actual successor after `ship`, `review`, and `verify` is classification-dependent
+— see the note below. `verify`'s `next` (`ship`) is the `docs`-only pre-ship
+reuse; in every other flow nothing follows `verify`.
+
+Feeders into the chain: `triage-ready` → `claim-safety` → `dev` (rank the pick,
+prove the live lease, then work it). `research` is standalone / callable
+mid-workflow and returns to its CALLER (no forced `next`); it is also a `subskill`
+of `plan`. The `smith` orchestrator composes the six stages (`subskills`).
+Utility/terminal skills (`status`, `shepherd`, `kernel`, `issue-basics`, `memory`,
+`rollback`, `research`, `sonarcloud`, `sonarcloud-analysis`,
+`parallel-deep-research`, `using-forge`) declare no forward-stage `next`. Meta
+skills (`hermes-forge`) are chain-exempt.
+
+The stage `next` values above are the DEFAULT / critical-path successors. The
+actual successor after `ship`, `review`, and `verify` is
+classification-dependent — the authoritative matrix is `lib/workflow/stages.js`
+(Simple/Hotfix/Refactor end at `ship`; Standard ends at `review`; Critical runs
+through `verify`; the `docs` classification reuses `verify` → `ship`).
+
 ## Orchestrator super-skill
 
 `smith` is the flagship: a thin orchestrator that COMPOSES the skills above into