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

package/lib/commands/shepherd.js

@@ -37,13 +37,21 @@ const { gatherMonitorSnapshot } = require('../pr-monitor/gather');
 const { pollEvents } = require('../pr-monitor/monitor');
 const { watchLoop } = require('../pr-monitor/watch');
 const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
+const reconcileExecutor = require('../pr-monitor/reconcile-executor');
 const monitorJournal = require('../pr-monitor/journal');
 const { EVENT_TYPES: T } = require('../pr-monitor/events');
 const { autoShepherdRailEnabled } = require('./ship');
 
 const DEFAULT_RERUN_BUDGET = 3;
 
-const defaultGhRunner = (cmd, a) => execFileSync(cmd, a, { encoding: 'utf8', timeout: 30000 });
+// windowsHide: true on EVERY spawn here is load-bearing, not cosmetic. The
+// shepherd watcher runs detached in the background and re-polls every ~60s; on
+// Windows a child process spawned WITHOUT windowsHide flashes a visible console
+// window each time (Node's default is windowsHide:false). Background work's
+// preferred home is the harness's managed shell (hidden + reaped); a
+// Forge-spawned detached watcher is the no-session fallback and must be
+// COMPLETELY silent — no console window, ever. See kernel issue 931e7924.
+const defaultGhRunner = (cmd, a) => execFileSync(cmd, a, { encoding: 'utf8', timeout: 30000, windowsHide: true });
 
 /**
  * Resolve owner/repo and base branch for the shepherd pass.
@@ -282,7 +290,7 @@ function wireSignals() {
 function defaultListOpenPrs(exec = execFileSync) {
   try {
     const out = exec('gh', ['pr', 'list', '--state', 'open', '--json', 'number', '-q', '.[].number'], {
-      encoding: 'utf8', timeout: 20000, stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8', timeout: 20000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
     });
     return String(out)
       .split(/\r?\n/)
@@ -380,6 +388,28 @@ async function handleWatch(args, projectRoot, deps = {}) {
   };
 }
 
+/**
+ * `forge shepherd daemon` — the SINGLETON reconcile daemon (W-S4b). It acquires
+ * the machine-wide shepherd lease for this repo (exiting immediately if a live
+ * daemon already owns it), heartbeats, and converges the PR world every ~60s:
+ * self-registering hand-opened PRs, restarting killed watchers, reaping verified
+ * orphans, retiring merged/closed PRs. It self-retires (releases the lease, kills
+ * its verified children, exits) once no PRs remain open. Launched detached by the
+ * per-command `fireAndForget` trigger — not meant to be run by hand.
+ *
+ * @param {string} projectRoot
+ * @param {object} [deps] - injected for tests (acquire/heartbeat/gather/etc.).
+ * @returns {Promise<object>} result envelope.
+ */
+async function handleDaemon(projectRoot, deps = {}) {
+  const res = await reconcileExecutor.runDaemon(projectRoot, { ...deps });
+  if (!res.ok) {
+    // A live foreign daemon owns the lease — this invocation is a clean no-op.
+    return { success: true, started: false, reason: res.reason || 'foreign-lease' };
+  }
+  return { success: true, started: true };
+}
+
 /**
  * Command handler.
  *
@@ -401,6 +431,9 @@ async function handler(args, _flags, projectRoot, deps = {}) {
   if (positional[0] === 'watch') {
     return handleWatch(args, projectRoot, deps);
   }
+  if (positional[0] === 'daemon') {
+    return handleDaemon(projectRoot, deps);
+  }
 
   const pr = positional[0];
 
@@ -408,7 +441,7 @@ async function handler(args, _flags, projectRoot, deps = {}) {
     return { success: false, error: 'Usage: forge shepherd <pr> [--auto-rebase] [--bundle --json] [--pull --json]' };
   }
 
-  const gh = deps.gh || ((cmd, a) => execFileSync(cmd, a, { encoding: 'utf8', timeout: 30000 }));
+  const gh = deps.gh || ((cmd, a) => execFileSync(cmd, a, { encoding: 'utf8', timeout: 30000, windowsHide: true }));
   const git = deps.git || gh;
   const buildContext = deps.buildContext || defaultBuildContext;
   const runPass = deps.runPass || runShepherdPass;

package/lib/commands/skill.js

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * Forge Skill Command -- the unified "forge skill <verb>" noun.
+ *
+ * "forge skill for <situation>" is a DETERMINISTIC intent-to-skill router: it reads the canonical
+ * skill catalog (skills/*\/SKILL.md frontmatter) and prints the best-fit Forge skill(s) plus WHY,
+ * as the reasoning fallback for harnesses without a SessionStart hook that can auto-inject the
+ * using-forge dispatch skill. It NEVER opens the kernel and NEVER throws.
+ *
+ * The noun is structured so later waves can add sibling verbs (forge skill eval, forge skill
+ * scores) without a new top-level command -- the owner's command-surface rule: unify related
+ * commands under one self-explanatory noun instead of scattering verbs.
+ *
+ * @module commands/skill
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { routeSkill, loadSkillCatalog } = require('../using-forge');
+const skillEval = require('../skill-eval');
+
+const USAGE = 'Usage: forge skill for "<situation>" [--json]\n' +
+  '       forge skill eval [name] --static [--json]\n' +
+  '       forge skill scores [--json]\n' +
+  '       forge skill coverage [--json]';
+
+/** Extract the situation text (all non-flag args after the verb) and json flag. */
+function parseForArgs(rest, flags) {
+  const positional = rest.filter(a => typeof a === 'string' && !a.startsWith('--'));
+  const json = flags.json === true || flags['--json'] === true || rest.includes('--json');
+  return { situation: positional.join(' ').trim(), json };
+}
+
+/** Render the human-readable routing answer. */
+function formatRouting(result) {
+  const lines = ['Best skill for: "' + result.situation + '"', ''];
+  if (result.unknown) {
+    lines.push(
+      'No confident match. This may not need a Forge skill -- or describe it more concretely.',
+      'Fallbacks: `forge ready` for what to work on, or the kernel skill to see the whole surface.',
+    );
+    return lines.join('\n');
+  }
+  const [top, ...rest] = result.matches;
+  lines.push(
+    '-> ' + top.name + '  (' + top.why + ')',
+    '  Announce: "Using ' + top.name + ' to ..." then follow the skill.',
+  );
+  if (rest.length > 0) {
+    lines.push('', 'Also consider:');
+    for (const m of rest) lines.push('  - ' + m.name + '  (' + m.why + ')');
+  }
+  return lines.join('\n');
+}
+
+/** "forge skill for <situation>" -- deterministic router. */
+function handleFor(rest, flags) {
+  const { situation, json } = parseForArgs(rest, flags);
+  if (!situation) {
+    return { success: false, error: 'Missing situation.\n' + USAGE };
+  }
+  // Read the canonical catalog from the Forge PACKAGE (not projectRoot): a set-up consumer
+  // project has no root skills/, so the routable skills live in the package assets.
+  const catalog = loadSkillCatalog();
+  const result = routeSkill(situation, { catalog });
+  if (json) {
+    return { success: true, result, output: JSON.stringify(result, null, 2) + '\n' };
+  }
+  return { success: true, result, output: formatRouting(result) };
+}
+
+/** Write a scorecard to skills/<name>/evals/scorecard.json (stable 2-space JSON + trailing NL). */
+function writeScorecard(skillsDir, name, card) {
+  const dir = path.join(skillsDir, name, 'evals');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'scorecard.json'), JSON.stringify(card, null, 2) + '\n');
+}
+
+/**
+ * "forge skill eval [name] --static [--json]" -- compute + persist the DETERMINISTIC scorecard(s).
+ * All skills when no name. --static is the only tier today (behavioral is W5); it is accepted (and
+ * implied) so the flag reads honestly and future tiers can branch here.
+ */
+function handleEval(rest, flags, projectRoot) {
+  const json = flags.json === true || flags['--json'] === true || rest.includes('--json');
+  const positional = rest.filter(a => typeof a === 'string' && !a.startsWith('--'));
+  const name = positional[0];
+  const ctx = skillEval.resolveSkillsContext(projectRoot);
+  if (!ctx) {
+    return { success: false, error: 'No canonical skills/ directory found (looked in the project and the packaged Forge root).' };
+  }
+  const { skillsDir, catalog } = ctx;
+  const targets = name
+    ? [name]
+    : fs.readdirSync(skillsDir, { withFileTypes: true })
+        .filter(e => e.isDirectory() && fs.existsSync(path.join(skillsDir, e.name, 'SKILL.md')))
+        .map(e => e.name)
+        .sort();
+
+  const written = [];
+  const cards = {};
+  for (const target of targets) {
+    const card = skillEval.buildScorecard({ skillsDir, name: target, catalog });
+    if (!card) {
+      if (name) return { success: false, error: `Skill '${name}' not found under ${skillsDir}.` };
+      continue;
+    }
+    writeScorecard(skillsDir, target, card);
+    written.push(target);
+    cards[target] = card;
+  }
+
+  if (json) {
+    return { success: true, cards, output: JSON.stringify(name ? cards[name] : cards, null, 2) + '\n' };
+  }
+  const lines = ['Static scorecards written (deterministic tier):'];
+  for (const t of written) lines.push('  ' + t + '  composite=' + cards[t].composite);
+  lines.push('', 'Behavioral tier (recall/precision/chains/outcome/variance) is W5.');
+  return { success: true, cards, output: lines.join('\n') };
+}
+
+/** Render the worst-first league table from a scorecards map. */
+function formatScores(scorecards, gate) {
+  const rows = Object.values(scorecards)
+    .map(c => ({
+      skill: c.skill,
+      composite: c.composite,
+      dq: c.static.description_quality.score,
+      tok: c.static.token_cost.score,
+      caps: c.static.caps.score,
+      fixtures: c.fixtures,
+    }))
+    .sort((a, b) => a.composite - b.composite || a.skill.localeCompare(b.skill));
+
+  const lines = ['Skill scores (static tier — worst first). Composite = 0.5*desc-quality + 0.3*token-cost + 0.2*caps.', ''];
+  lines.push('  COMPOSITE  DESC-Q  TOKEN  CAPS  FIXTURES     SKILL');
+  for (const r of rows) {
+    lines.push(
+      '  ' + String(r.composite).padStart(9) +
+      '  ' + String(r.dq).padStart(6) +
+      '  ' + String(r.tok).padStart(5) +
+      '  ' + String(r.caps).padStart(4) +
+      '  ' + r.fixtures.padEnd(11) +
+      '  ' + r.skill,
+    );
+  }
+  if (gate.warnings.length > 0) {
+    lines.push('', 'Router-reachability warnings (paraphrase gap — W5 judge is the fix, not blocking):');
+    for (const w of gate.warnings) lines.push('  - ' + w.skill + ': ' + w.detail);
+  }
+  lines.push('', gate.passed ? 'CI gate: PASS' : 'CI gate: FAIL (' + gate.failures.length + ')');
+  for (const f of gate.failures) lines.push('  x ' + f.skill + ': ' + f.kind + ' — ' + f.detail);
+  return lines.join('\n');
+}
+
+/** Render the command-coverage section (a summary line + any failures/warnings). */
+function formatCoverage(coverage) {
+  const lines = [
+    'Skill coverage (every registered command must own a skill or be exempt):',
+    '  commands=' + coverage.total + '  mapped=' + coverage.mapped + '  exempt=' + coverage.exempt +
+      '  gaps=' + coverage.failures.length,
+  ];
+  if (coverage.warnings.length > 0) {
+    lines.push('', 'Stale coverage.json entries (non-blocking — remove them):');
+    for (const w of coverage.warnings) lines.push('  - ' + w.command + ': ' + w.kind);
+  }
+  lines.push('', coverage.passed ? 'Coverage gate: PASS' : 'Coverage gate: FAIL (' + coverage.failures.length + ')');
+  for (const f of coverage.failures) lines.push('  x ' + f.command + ': ' + f.kind + ' — ' + f.detail);
+  return lines.join('\n');
+}
+
+/** Build the combined gate error string (static scorecard gate + command-coverage gate). */
+function buildScoresError(gate, coverage) {
+  const parts = [];
+  if (!gate.passed) {
+    parts.push('static gate (' + gate.failures.length + '): ' + gate.failures.map(f => f.skill + ' — ' + f.kind).join('; '));
+  }
+  if (coverage && !coverage.passed) {
+    parts.push('coverage gate (' + coverage.failures.length + '): ' + coverage.failures.map(f => f.command + ' — ' + f.kind).join('; '));
+  }
+  return 'Skill CI gate FAILED — ' + parts.join(' | ');
+}
+
+/** "forge skill scores [--json]" -- the league table. Gate state is drift-aware so it agrees with CI. */
+function handleScores(rest, flags, projectRoot) {
+  const json = flags.json === true || flags['--json'] === true || rest.includes('--json');
+  const ctx = skillEval.resolveSkillsContext(projectRoot);
+  if (!ctx) {
+    return { success: false, error: 'No canonical skills/ directory found (looked in the project and the packaged Forge root).' };
+  }
+  const { skillsDir, catalog, source } = ctx;
+  const scorecards = skillEval.buildAllScorecards(skillsDir, catalog);
+  // Compare the recomputed cards against the COMMITTED artifacts (canonical skills/ AND the
+  // .agents/skills mirror). A stale/missing committed scorecard is drift, so the gate reported here
+  // is FAIL — matching the CI drift test — instead of a hollow PASS over freshly-rebuilt cards.
+  // Gate the mirror by CONTEXT, not existence: a SOURCE checkout (source==='project') is EXPECTED
+  // to ship the committed .agents/skills mirror, so pass mirrorDir UNCONDITIONALLY — a deleted or
+  // never-checked-out mirror then REPORTS drift instead of silently passing. From the PACKAGED root
+  // (source==='package', a consumer install) no mirror ships, so omit the check to avoid false drift.
+  const mirrorDir = source === 'project' ? path.join(path.dirname(skillsDir), '.agents', 'skills') : null;
+  const drift = skillEval.detectScorecardDrift({ skillsDir, freshCards: scorecards, mirrorDir });
+  const gate = skillEval.evaluateGate(scorecards, { drift });
+  // Command-coverage gate (§3.3): a registered command with no owning skill (and not exempt) must
+  // FAIL scores too, so CI running `forge skill scores` catches a new unrouted command — not only
+  // the dedicated `forge skill coverage`.
+  const coverage = skillEval.buildCoverageReport(projectRoot);
+  // The gate verdict MUST drive the command's exit status: a failing gate (scorecard drift, caps
+  // violation, invalid fixtures, OR a coverage gap) returns success:false so the registry runner
+  // exits non-zero and a CI job running `forge skill scores` actually FAILS — instead of exiting 0
+  // while the output says "gate: FAIL". The full league table + gate detail still ride along.
+  const coveragePassed = !coverage || coverage.passed === true;
+  const passed = gate.passed === true && coveragePassed;
+  const gateError = passed ? undefined : buildScoresError(gate, coverage);
+  if (json) {
+    return { success: passed, error: gateError, scorecards, gate, coverage, drift, output: JSON.stringify({ scorecards, gate, coverage, drift }, null, 2) + '\n' };
+  }
+  const text = coverage ? formatScores(scorecards, gate) + '\n\n' + formatCoverage(coverage) : formatScores(scorecards, gate);
+  return { success: passed, error: gateError, scorecards, gate, coverage, drift, output: text };
+}
+
+/** "forge skill coverage [--json]" -- the dedicated command→skill coverage gate. */
+function handleCoverage(rest, flags, projectRoot) {
+  const json = flags.json === true || flags['--json'] === true || rest.includes('--json');
+  const report = skillEval.buildCoverageReport(projectRoot);
+  if (!report) {
+    return { success: false, error: 'No canonical skills/ directory found (looked in the project and the packaged Forge root).' };
+  }
+  const passed = report.passed === true;
+  const gateError = passed
+    ? undefined
+    : 'Skill coverage gate FAILED (' + report.failures.length + '): ' +
+      report.failures.map(f => f.command + ' — ' + f.kind).join('; ');
+  if (json) {
+    return { success: passed, error: gateError, report, output: JSON.stringify(report, null, 2) + '\n' };
+  }
+  return { success: passed, error: gateError, report, output: formatCoverage(report) };
+}
+
+module.exports = {
+  name: 'skill',
+  description: 'Route, evaluate, score, and coverage-check Forge skills (forge skill for | eval | scores | coverage)',
+  usage: USAGE,
+  flags: {
+    '--json': 'Emit the machine-readable result',
+    '--static': 'Score only the deterministic static tier (the only tier today; behavioral is W5)',
+  },
+  // flags is the LAST declared param so its `= {}` default is trailing (SonarCloud S1788). The
+  // registry still passes (args, flags, projectRoot, opts) — the router reads the canonical catalog
+  // from the package root; eval/scores read the canonical skills/ source dir.
+  handler: (args, flags = {}, projectRoot) => {
+    const verb = args[0];
+    if (verb === 'for') {
+      return handleFor(args.slice(1), flags);
+    }
+    if (verb === 'eval') {
+      return handleEval(args.slice(1), flags, projectRoot);
+    }
+    if (verb === 'scores') {
+      return handleScores(args.slice(1), flags, projectRoot);
+    }
+    if (verb === 'coverage') {
+      return handleCoverage(args.slice(1), flags, projectRoot);
+    }
+    if (!verb) {
+      return { success: false, error: 'Missing verb.\n' + USAGE };
+    }
+    return {
+      success: false,
+      error: "Unknown verb '" + verb + "'. Supported: for, eval, scores, coverage.\n" + USAGE,
+    };
+  },
+  // Exposed for unit tests; not part of the CLI surface.
+  _internal: { parseForArgs, formatRouting, handleFor, handleEval, handleScores, handleCoverage, formatScores, formatCoverage },
+};

package/lib/commands/status.js

@@ -18,7 +18,7 @@ const {
 const {
 	loadState,
 	extractWorkflowStateFromComments,
-	readWorkflowStateFromBeads,
+	readWorkflowStateFromIssue,
 } = require('../workflow/state-manager');
 const { secureExecFileSync } = require('../shell-utils.js');
 
@@ -140,12 +140,12 @@ function analyzeChecks(context) {
 }
 
 /**
- * Analyze Beads issue state
- * @param {object} beadsIssue - Beads issue object
- * @returns {object} Beads analysis
+ * Analyze kernel issue state
+ * @param {object} issueRecord - kernel issue record
+ * @returns {object} issue analysis
  */
-function analyzeBeads(beadsIssue) {
-	if (!beadsIssue) {
+function analyzeIssue(issueRecord) {
+	if (!issueRecord) {
 		return {
 			hasActiveIssue: false,
 			issueStatus: null,
@@ -155,10 +155,10 @@ function analyzeBeads(beadsIssue) {
 
 	return {
 		hasActiveIssue: true,
-		issueStatus: beadsIssue.status,
-		issueType: beadsIssue.type,
-		isInProgress: beadsIssue.status === 'in_progress',
-		isClosed: beadsIssue.status === 'closed',
+		issueStatus: issueRecord.status,
+		issueType: issueRecord.type,
+		isInProgress: issueRecord.status === 'in_progress',
+		isClosed: issueRecord.status === 'closed',
 	};
 }
 
@@ -178,7 +178,7 @@ function calculateConfidence(factors, stage) {
 		files: 30,
 		pr: 25,
 		checks: 15,
-		beads: 10,
+		issue: 10,
 	};
 
 	// Branch state
@@ -235,16 +235,16 @@ function calculateConfidence(factors, stage) {
 		score += weights.checks / 2; // Partial match
 	}
 
-	// Beads issue
-	maxScore += weights.beads;
-	if (factors.beads.isInProgress && stage >= 2 && stage <= 7) {
-		score += weights.beads; // Active work
-	} else if (factors.beads.isClosed && stage >= 8) {
-		score += weights.beads; // Closed for late stages
-	} else if (!factors.beads.hasActiveIssue && stage === 1) {
-		score += weights.beads; // No issue for fresh start
+	// Issue state
+	maxScore += weights.issue;
+	if (factors.issue.isInProgress && stage >= 2 && stage <= 7) {
+		score += weights.issue; // Active work
+	} else if (factors.issue.isClosed && stage >= 8) {
+		score += weights.issue; // Closed for late stages
+	} else if (!factors.issue.hasActiveIssue && stage === 1) {
+		score += weights.issue; // No issue for fresh start
 	} else {
-		score += weights.beads / 2; // Partial match
+		score += weights.issue / 2; // Partial match
 	}
 
 	const percentage = Math.round((score / maxScore) * 100);
@@ -275,21 +275,21 @@ function detectStage(context) {
 	const fileFactors = analyzeFiles(context);
 	const prFactors = analyzePR(context.pr);
 	const checkFactors = analyzeChecks(context);
-	const beadsFactors = analyzeBeads(context.beadsIssue);
+	const issueFactors = analyzeIssue(context.issueRecord);
 
 	const factors = {
 		branch: branchFactors,
 		files: fileFactors,
 		pr: prFactors,
 		checks: checkFactors,
-		beads: beadsFactors,
+		issue: issueFactors,
 	};
 
 	// Stage detection logic
 	let stage;
 
 	// Stage 9: PR merged, verify docs
-	if (prFactors.prMerged && beadsFactors.isClosed) {
+	if (prFactors.prMerged && issueFactors.isClosed) {
 		stage = 9;
 	}
 	// Stage 8: PR approved, ready to merge
@@ -317,7 +317,7 @@ function detectStage(context) {
 		stage = 3;
 	}
 	// Stage 2: Research in progress
-	else if (beadsFactors.issueType === 'research' && beadsFactors.isInProgress) {
+	else if (issueFactors.issueType === 'research' && issueFactors.isInProgress) {
 		stage = 2;
 	}
 	// Stage 1: Fresh project (default)
@@ -612,7 +612,7 @@ function resolveWorkflowState(inputs) {
 			issueId: inputs.issueId,
 			issue: inputs.issue,
 			comments: inputs.bdComments,
-			preferBeads: inputs.preferBeads,
+			preferIssueLookup: inputs.preferIssueLookup,
 		});
 
 		return { workflowState: state, fallbackReason: null };
@@ -649,7 +649,7 @@ function buildAuthoritativeStatus(workflowState) {
 			branch: {},
 			pr: {},
 			checks: { allChecksPass: workflowState.completedStages.includes('validate') },
-			beads: { hasActiveIssue: true },
+			issue: { hasActiveIssue: true },
 		},
 	};
 }
@@ -757,9 +757,14 @@ module.exports = {
 		'--json': 'Emit the machine-readable status envelope',
 	},
 	handler: async (args, flags, projectRoot) => {
+		// Injectable snapshot read, same convention as setup.js's `options.commandRunner`
+		// (lib/commands/setup.js:223): a real default with a test-supplied override. Tests
+		// need a snapshot with controlled ids and orderings, which a seeded kernel cannot
+		// give them — the kernel stamps its own updated_at.
+		const readSnapshot = flags?.readStatusSnapshot || readStatusSnapshot;
 		const inputs = parseStatusInputs(args, flags);
 		const isZeroArgStatus = !inputs.issueId && !inputs.workflowState && !inputs.bdComments;
-		inputs.preferBeads = !isZeroArgStatus && Boolean(inputs.issueId || inputs.bdComments);
+		inputs.preferIssueLookup = !isZeroArgStatus && Boolean(inputs.issueId || inputs.bdComments);
 		if (!inputs.projectRoot && projectRoot) {
 			inputs.projectRoot = projectRoot;
 		}
@@ -769,11 +774,11 @@ module.exports = {
 
 		if (isZeroArgStatus) {
 			context = detectRepoContext(effectiveProjectRoot);
-			// Read from the active issue backend (Kernel by default; Beads only when
-			// explicitly selected). Previously hard-wired to the retired Beads
+			// Read from the Kernel, the only issue backend. Previously hard-wired to
+			// the retired Beads
 			// issues.jsonl, which is empty on a kernel-default repo — so the flagship
 			// view showed "Ready: none" despite a populated kernel (bug 40f35797).
-			snapshot = await readStatusSnapshot(effectiveProjectRoot, {
+			snapshot = await readSnapshot(effectiveProjectRoot, {
 				now: inputs.now,
 				staleAfterDays: inputs.staleAfterDays,
 				issueBackend: inputs.issueBackend,
@@ -834,7 +839,7 @@ module.exports = {
 	extractWorkflowStateFromComments,
 	resolveWorkflowState,
 	parseStatusInputs,
-	readWorkflowStateFromBeads,
+	readWorkflowStateFromIssue,
 	detectStage,
 	detectRepoContext,
 	discoverCurrentIssue,
@@ -842,7 +847,7 @@ module.exports = {
 	analyzeFiles,
 	analyzePR,
 	analyzeChecks,
-	analyzeBeads,
+	analyzeIssue,
 	calculateConfidence,
 	formatStatus,
 	extractDesignSlugs,

package/lib/commands/test.js

@@ -34,12 +34,40 @@ const DIRECT_TEST_CANDIDATES = Object.freeze({
 		'test/setup-github-sync.test.js',
 		'test/setup-runtime-flags.test.js',
 	],
+	// The second CLI surface (command descriptions + shepherd wiring). Without an
+	// entry here it resolves to zero tests and pushes fall back to the full suite.
+	'bin/forge-cmd.js': [
+		'test/cli/forge-cmd.test.js',
+		'test/forge-cmd-shepherd.test.js',
+	],
+	'bin/forge-preflight.js': ['test/bin/forge-preflight.test.js'],
 	'lib/lefthook-check.js': ['test/lefthook-check.test.js', 'test/runtime-health.test.js'],
 	'lib/runtime-health.js': ['test/runtime-health.test.js'],
+	// skill-eval hosts the accuracy-lint detectors (auditCommandDocumentation /
+	// auditRouterPrecision), so edits there must also run their detector suite.
+	'lib/skill-eval.js': ['test/skill-eval.test.js', 'test/skill-accuracy.test.js'],
 	'lib/upgrade-safety.js': ['test/commands/upgrade.test.js'],
 	'scripts/test.js': ['test/scripts/test-runner.test.js'],
 });
 
+// Skill sources (canonical `skills/**` and the committed `.agents/skills/**` mirror)
+// map to the fast skill suite. This is what keeps a skills-only PR on the targeted
+// lane instead of the full ~1500-test suite. `skills-sync-drift` guards the mirror.
+const SKILL_TEST_TARGETS = Object.freeze([
+	'test/skills-structure.test.js',
+	'test/skill-coverage.test.js',
+	'test/skill-eval.test.js',
+	'test/skill-accuracy.test.js',
+	'test/skill-dispatch-parity.test.js',
+	'test/using-forge.test.js',
+	'test/structural/skills-sync-drift.test.js',
+	'test/skills/chain-integrity.test.js',
+	'test/skills/skills-sync.test.js',
+	'test/skills/stage-skills.test.js',
+	'test/skills/using-forge-skill.test.js',
+	'test/skills/context-cost.test.js',
+]);
+
 /**
  * Detect the package manager by checking which lockfile exists.
  *
@@ -183,6 +211,10 @@ function getTestCandidatesForChangedFile(file) {
 		return [file];
 	}
 
+	if (file.startsWith('skills/') || file.startsWith('.agents/skills/')) {
+		return [...SKILL_TEST_TARGETS];
+	}
+
 	if (file === 'README.md'
 		|| file === 'QUICKSTART.md'
 		|| file === 'CHANGELOG.md'

package/lib/commands/worktree.js

@@ -406,12 +406,38 @@ async function handleList(projectRoot, opts) {
       const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
       driver = (await buildMigratedKernelIssueDeps({ projectRoot })).kernelDriver;
     }
-    return { success: true, worktrees: driver.listWorktrees({}) };
+    // `forge worktree remove` / `forge clean` delete the checkout but do not yet
+    // reconcile the kernel_worktrees registry (issue ceeef92f), so the raw registry
+    // can still list already-removed paths. Filter to worktrees that still exist on
+    // disk so `forge worktree list` never surfaces stale entries agents could act on.
+    const existsSync = (opts._fs && opts._fs.existsSync) || require('node:fs').existsSync;
+    const worktrees = driver.listWorktrees({}).filter((w) => w && w.path && existsSync(w.path));
+    return { success: true, worktrees, output: renderWorktreeList(worktrees) };
   } catch (error) {
     return { success: false, error: error.message, worktrees: [] };
   }
 }
 
+/**
+ * Render the worktree registry as human-readable text for the CLI. The dispatcher
+ * prints only `result.output`, so without this `forge worktree list` is silent.
+ * @param {Array<object>} worktrees - Rows from driver.listWorktrees()
+ * @returns {string} One line per worktree (path, branch, linked issue, state).
+ */
+function renderWorktreeList(worktrees) {
+  if (!Array.isArray(worktrees) || worktrees.length === 0) {
+    return 'No worktrees registered.';
+  }
+  const lines = worktrees.map((w) => {
+    const parts = [w.path || '(unknown path)'];
+    if (w.branch) parts.push(`branch: ${w.branch}`);
+    if (w.issue_id) parts.push(`issue: ${w.issue_id}`);
+    if (w.state) parts.push(w.state);
+    return `  ${parts.join('  |  ')}`;
+  });
+  return `Registered worktrees (${worktrees.length}):\n${lines.join('\n')}`;
+}
+
 /**
  * Handle the "remove" subcommand.
  * @param {string} slug - Worktree slug