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

package/lib/workflow/enforce-stage.js

@@ -68,6 +68,27 @@ function findLatestStageRun(driver, issueId, stage) {
   }
 }
 
+// (Re-)entering an earlier stage invalidates the work that followed it: any
+// DOWNSTREAM stage previously recorded 'done' is reopened to 'active' so a gated
+// stage (ship/review) re-requires a fresh completion (R2 — the dev<->validate
+// rework loop must not let a stale validate=done pass ship). Reuses the idempotent
+// 'start' write, which keeps the row's id + original started_at but clears its
+// done status. Stages the entered stage does not precede (and non-'done' rows) are
+// left untouched, so forward progression records nothing extra.
+function invalidateDownstreamStages(driver, issueId, stageId, warn) {
+  const index = STAGE_PATH.indexOf(stageId);
+  if (index < 0) {
+    return;
+  }
+  for (let next = index + 1; next < STAGE_PATH.length; next += 1) {
+    const downstream = STAGE_PATH[next];
+    const run = findLatestStageRun(driver, issueId, downstream);
+    if (run?.status === 'done') {
+      recordStageRunSafe(driver, issueId, downstream, 'start', warn);
+    }
+  }
+}
+
 // Decide whether entering stageId is allowed given ONLY the kernel's recorded
 // stage history (used when no inline/file workflow state exists):
 //   - Stateless stages (plan/dev/validate/verify) are always re-entrant, so the
@@ -123,7 +144,12 @@ async function resolveActiveIssueId(driver, branch) {
   try {
     if (typeof driver.listWorktrees === 'function') {
       const rows = driver.listWorktrees() || [];
-      const match = rows.find(row => row && row.branch === branch && row.issue_id);
+      // Match only ACTIVE (live) linkage rows, newest first (listWorktrees orders
+      // registered_at DESC). A stale/superseded registration for a reused branch
+      // name must not rebind stage state to the OLD issue (be18881c). Tolerate a
+      // null state for rows written before the state column was populated.
+      const match = rows.find(row => row && row.branch === branch && row.issue_id
+        && (row.state === 'active' || row.state == null));
       if (match) {
         return match.issue_id;
       }
@@ -141,7 +167,7 @@ async function resolveActiveIssueId(driver, branch) {
 
 // Lazily build a kernel driver from the project root (the real CLI path).
 // Best-effort: returns null when the kernel is unavailable so the caller
-// degrades to legacy file/beads state instead of crashing a stage command.
+// degrades to the legacy file state instead of crashing a stage command.
 async function buildKernelDriver(projectRoot) {
   if (!projectRoot) {
     return null;
@@ -344,7 +370,7 @@ async function enforceStageEntry({
   // B1 — kernel stage-state authority. Injectable for tests; the real CLI sets
   // autoResolveKernel:true so the driver + active issue are resolved from the
   // worktree. When neither a driver nor autoResolveKernel is provided, the
-  // kernel path is inert and behavior matches the legacy file/beads state.
+  // kernel path is inert and behavior matches the legacy file state.
   kernelDriver,
   activeIssueId,
   branch,
@@ -360,9 +386,9 @@ async function enforceStageEntry({
     repairWorkflowRuntimeAssets(projectRoot);
   }
 
-  // Resolve the active issue backend (env > .forge/config.yaml > default 'kernel') so
-  // the runtime gate only treats bd as a hard prerequisite for the beads backend. The
-  // kernel default needs no bd, so stages must run without it.
+  // Resolve the active issue backend (env > .forge/config.yaml > default 'kernel').
+  // The kernel is the only backend and needs no bd, so bd is never a hard
+  // prerequisite and stages must run without it.
   const issueBackend = resolveIssueBackend({ deps: {}, env: process.env, projectRoot, warn: () => {} });
   const runtimeHealth = await resolveStageRuntimeHealth({
     health, checkHealth, projectRoot, issueBackend, commandName, flags, workflowState, repairRuntime,
@@ -391,6 +417,7 @@ async function enforceStageEntry({
   const finish = (result) => {
     if (kernelActive) {
       recordStageRunSafe(driver, issueId, stageId, 'start', warn);
+      invalidateDownstreamStages(driver, issueId, stageId, warn);
       result.recordCompletion = () => recordStageRunSafe(driver, issueId, stageId, 'complete', warn);
     }
     return result;
@@ -401,6 +428,14 @@ async function enforceStageEntry({
     return enforceWithFileState(currentState, stageId, flags, args, finish);
   }
 
+  // B1 — strict mode is the explicit opt-in to the legacy fail-closed behavior:
+  // require prior stages / authoritative state. The default (unset) degrades to a
+  // loud warning and seeds the kernel so future gating gets real data. A recorded
+  // history that CONTRADICTS (e.g. validate started-but-not-done) still throws in
+  // both modes — that rework protection lives in enforceWithKernelState below and
+  // is never weakened by this flag.
+  const strict = process.env.FORGE_STAGE_GATE === 'strict';
+
   // No inline/file state: the kernel is authoritative. Gate on recorded stage
   // completions (tolerant read) so `ship` is reachable from a pure-CLI
   // plan->dev->validate progression with no .forge-state.json.
@@ -409,15 +444,37 @@ async function enforceStageEntry({
     if (decided) {
       return decided;
     }
+    // enforceWithKernelState returned null → the kernel has an issue linked but
+    // NO recorded predecessor (a contradiction would have thrown above). Degrade
+    // to warn + seed unless strict: allow the stage and let finish() record it so
+    // future gating has real history.
+    if (!strict) {
+      warn(
+        `[forge] no recorded workflow history for issue ${issueId} — allowing '${stageId}' ` +
+        `and recording it in the kernel. Set FORGE_STAGE_GATE=strict to require prior stages.`
+      );
+      return finish({ allowed: true, stage: stageId, workflowState: null, degradedGate: 'kernel-empty' });
+    }
   }
 
   if (STATELESS_ENTRY_STAGES.has(stageId)) {
     return finish({ allowed: true, stage: stageId, workflowState: null });
   }
 
+  // No workflow state AND no kernel-linked issue for this branch. Degrade to warn
+  // unless strict so incremental adoption (fresh setup, in-flight branch, manual
+  // commit) is not blocked.
+  if (!strict) {
+    warn(
+      `[forge] no workflow state and no kernel-linked issue for this branch — stage gate skipped for '${stageId}'. ` +
+      `Link an issue with 'forge worktree create <slug>' to enable stage tracking.`
+    );
+    return finish({ allowed: true, stage: stageId, workflowState: null, degradedGate: 'no-kernel-context' });
+  }
+
   throw new Error(
     `Stage ${stageId} requires authoritative workflow state. ` +
-    `Provide --workflow-state or restore ${WORKFLOW_STATE_FILENAME} before continuing.`
+    `Provide --workflow-state or restore ${WORKFLOW_STATE_FILENAME} before continuing (or unset FORGE_STAGE_GATE).`
   );
 }
 

package/lib/workflow/state-manager.js

@@ -98,7 +98,7 @@ function extractWorkflowStateFromIssue(issue = {}) {
   return extractWorkflowStateFromComments(mergedComments);
 }
 
-function readBeadsIssue(issueId, options = {}) {
+function readIssueWorkflowState(issueId, options = {}) {
   if (!issueId) {
     return null;
   }
@@ -127,7 +127,7 @@ function readBeadsIssue(issueId, options = {}) {
   }
 }
 
-function readWorkflowStateFromBeads(issueId, options = {}) {
+function readWorkflowStateFromIssue(issueId, options = {}) {
   if (!issueId) {
     return null;
   }
@@ -150,33 +150,33 @@ function readWorkflowStateFromBeads(issueId, options = {}) {
   // history, so a single read covers both the structured issue and the raw
   // comment text carrying the serialized WorkflowState marker. No separate
   // comment-list read is required.
-  const issue = readBeadsIssue(issueId, { projectRoot: options.projectRoot });
+  const issue = readIssueWorkflowState(issueId, { projectRoot: options.projectRoot });
   return extractWorkflowStateFromIssue(issue);
 }
 
-function loadStateFromBeads(options, projectRoot) {
+function loadStateFromIssue(options, projectRoot) {
   if (options.comments) {
     const state = extractWorkflowStateFromComments(options.comments);
     if (state) {
-      return { state, source: 'beads' };
+      return { state, source: 'issue' };
     }
   }
 
   if (options.issue) {
     const state = extractWorkflowStateFromIssue(options.issue);
     if (state) {
-      return { state, source: 'beads' };
+      return { state, source: 'issue' };
     }
   }
 
   if (options.issueId) {
-    const state = readWorkflowStateFromBeads(options.issueId, {
+    const state = readWorkflowStateFromIssue(options.issueId, {
       comments: options.comments,
       issue: options.issue,
       projectRoot,
     });
     if (state) {
-      return { state, source: 'beads' };
+      return { state, source: 'issue' };
     }
   }
 
@@ -185,21 +185,21 @@ function loadStateFromBeads(options, projectRoot) {
 
 function loadState(projectRoot, options = {}) {
   if (!projectRoot) {
-    const beadsResult = loadStateFromBeads(options, null);
-    return beadsResult || { state: null, source: null };
+    const issueResult = loadStateFromIssue(options, null);
+    return issueResult || { state: null, source: null };
   }
 
-  if (options.preferBeads && (options.comments || options.issue || options.issueId)) {
+  if (options.preferIssueLookup && (options.comments || options.issue || options.issueId)) {
     try {
-      const beadsResult = loadStateFromBeads(options, projectRoot);
-      if (beadsResult) {
-        return beadsResult;
+      const issueResult = loadStateFromIssue(options, projectRoot);
+      if (issueResult) {
+        return issueResult;
       }
     } catch (error) {
-      if (typeof options.onBeadsError === 'function') {
-        options.onBeadsError(error);
+      if (typeof options.onIssueLookupError === 'function') {
+        options.onIssueLookupError(error);
       }
-      // Fall through to the on-disk state file when Beads cannot be read.
+      // Fall through to the on-disk state file when the issue cannot be read.
     }
   }
 
@@ -209,13 +209,13 @@ function loadState(projectRoot, options = {}) {
       const raw = fs.readFileSync(statePath, 'utf8');
       return { state: readWorkflowState(raw), source: 'file' };
     } catch (_parseError) {
-      // File is malformed — fall through to Beads fallback
+      // File is malformed — fall through to the issue-lookup fallback
     }
   }
 
-  const beadsResult = loadStateFromBeads(options, projectRoot);
-  if (beadsResult) {
-    return beadsResult;
+  const issueResult = loadStateFromIssue(options, projectRoot);
+  if (issueResult) {
+    return issueResult;
   }
 
   return { state: null, source: null };
@@ -331,8 +331,8 @@ module.exports = {
   extractWorkflowStateFromIssue,
   initializeState,
   loadState,
-  readBeadsIssue,
-  readWorkflowStateFromBeads,
+  readIssueWorkflowState,
+  readWorkflowStateFromIssue,
   saveState,
   transitionStage,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.1.0-beta.2",
+  "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",
@@ -59,7 +59,7 @@
     "globals": "^17.3.0",
     "js-yaml": "^5.1.0",
     "lefthook": "^2.1.4",
-    "typescript": "5.4.5"
+    "typescript": "7.0.2"
   },
   "keywords": [
     "ai",

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/pr-auto-actions.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pr-auto-actions — the pr-monitor workflow's bridge from the `--pull --json`
+ * verdict payload to Tier-2 auto-action DECISIONS. Reads the payload file the
+ * monitor already wrote (default `pull.json`), asks lib/pr-monitor/auto-actions
+ * (the single, unit-tested decision core) what is safe to do, and emits the
+ * flags to `$GITHUB_OUTPUT` (or stdout locally) for the workflow's action steps.
+ *
+ * This script performs NO GitHub writes and takes NO action — it only decides.
+ * The workflow owns the visible `gh` calls and the per-head-SHA idempotency
+ * markers. Fails CLOSED: an unreadable/malformed payload or any thrown error
+ * yields `update_branch=false` / `rerun=false`.
+ *
+ * Usage: node scripts/pr-auto-actions.js [pull.json] [isFork]
+ *   isFork: "true" when the PR head is a cross-repository fork (skips update).
+ *
+ * @module scripts/pr-auto-actions
+ */
+
+const fs = require('node:fs');
+
+const { decideAutoActions } = require('../lib/pr-monitor/auto-actions');
+
+/**
+ * Append `key=value` lines to `$GITHUB_OUTPUT` when set, else print them. Values
+ * are single-line (booleans / csv / short reasons) so no multiline escaping is
+ * needed; newlines are stripped defensively.
+ *
+ * @param {Record<string,string>} outputs
+ */
+function emitOutputs(outputs) {
+  const target = process.env.GITHUB_OUTPUT;
+  const text = Object.entries(outputs)
+    .map(([k, val]) => `${k}=${String(val).replace(/[\r\n]+/g, ' ')}`)
+    .join('\n') + '\n';
+  if (target) fs.appendFileSync(target, text);
+  else process.stdout.write(text);
+}
+
+/** Read + parse the payload file, returning null (fail-closed) on any error. */
+function readPayload(path) {
+  try {
+    return JSON.parse(fs.readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function main(argv) {
+  const path = argv[2] || 'pull.json';
+  const isFork = String(argv[3] || '').toLowerCase() === 'true';
+
+  const payload = readPayload(path);
+  if (!payload) {
+    // Fail closed: no readable verdict payload → take no action.
+    emitOutputs({
+      update_branch: 'false', update_reason: `no readable payload at ${path}`,
+      rerun: 'false', rerun_run_ids: '', rerun_reason: `no readable payload at ${path}`,
+    });
+    console.log(`auto-actions: no readable payload at ${path} — no action (fail closed)`);
+    return 0;
+  }
+
+  const { updateBranch, rerunFlaky } = decideAutoActions(payload, { isFork });
+  emitOutputs({
+    update_branch: updateBranch.should ? 'true' : 'false',
+    update_reason: updateBranch.reason,
+    rerun: rerunFlaky.should ? 'true' : 'false',
+    rerun_run_ids: (rerunFlaky.runIds || []).join(','),
+    rerun_reason: rerunFlaky.reason,
+  });
+  console.log(`auto-actions: update_branch=${updateBranch.should} (${updateBranch.reason})`);
+  console.log(`auto-actions: rerun=${rerunFlaky.should} (${rerunFlaky.reason})`);
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    process.exit(main(process.argv));
+  } catch (err) {
+    // Absolute fail-closed backstop: never let this script red-X the monitor.
+    emitOutputs({
+      update_branch: 'false', update_reason: `error: ${(err && err.message) || err}`,
+      rerun: 'false', rerun_run_ids: '', rerun_reason: `error: ${(err && err.message) || err}`,
+    });
+    console.log(`auto-actions: error — no action (fail closed): ${(err && err.message) || err}`);
+    process.exit(0);
+  }
+}
+
+module.exports = { emitOutputs, readPayload, main };

package/scripts/pr-verdict-label.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pr-verdict label emitter — maps a canonical merge verdict (from
+ * `forge shepherd <pr> --pull --json`, lib/pr-pull.js) to its single
+ * `pr-verdict:*` label and emits `label` + `all_labels` to `$GITHUB_OUTPUT`
+ * (or stdout locally) for the pr-monitor workflow's reconcile step.
+ *
+ * SINGLE SOURCE: the verdict value and the label vocabulary both come from
+ * lib/pr-pull.js — this script computes NO verdict of its own, so the label can
+ * never disagree with `--pull`. Fails closed to `unknown` on empty input.
+ * Performs NO GitHub writes (the workflow owns the visible `gh` calls).
+ *
+ * Usage: node scripts/pr-verdict-label.js <VERDICT>
+ *
+ * @module scripts/pr-verdict-label
+ */
+
+const fs = require('node:fs');
+
+const { verdictLabel, VERDICT_LABELS } = require('../lib/pr-pull');
+
+/**
+ * Append `key=value` lines to `$GITHUB_OUTPUT` when set, else print them.
+ *
+ * @param {Record<string,string>} outputs
+ */
+function emitOutputs(outputs) {
+  const target = process.env.GITHUB_OUTPUT;
+  const text = Object.entries(outputs).map(([k, val]) => `${k}=${val}`).join('\n') + '\n';
+  if (target) fs.appendFileSync(target, text);
+  else process.stdout.write(text);
+}
+
+function main(argv) {
+  // Fail closed: a missing/empty verdict arg maps to the `unknown` label rather
+  // than erroring — the workflow must still land a label on every pass.
+  const verdict = argv[2] || 'UNKNOWN';
+  const label = verdictLabel(verdict);
+  emitOutputs({ label, all_labels: VERDICT_LABELS.join(',') });
+  console.log(`pr-verdict label: ${label} (verdict ${verdict})`);
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = { emitOutputs, main };

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)" }
+  }
+}