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

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

@@ -3,6 +3,7 @@
 const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const { detectDefaultBranch } = require('../beads-sync-scaffold');
 
 /**
  * Forge Worktree Command
@@ -53,6 +54,40 @@ function branchExists(branchName, runFile) {
   }
 }
 
+/**
+ * True when a git ref resolves to a commit (branch, tag, remote-tracking ref, or SHA).
+ * @param {string} ref - The ref to check
+ * @param {string} projectRoot - Repo root to run git in
+ * @param {Function} runFile - execFileSync function (for DI)
+ * @returns {boolean}
+ */
+function refExists(ref, projectRoot, runFile) {
+  try {
+    runFile('git', ['-C', projectRoot, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch (_err) { /* intentional: ref does not resolve */ // NOSONAR S2486
+    return false;
+  }
+}
+
+/**
+ * Resolve the base ref a NEW worktree branch should fork from. Defaults to the
+ * repo's DEFAULT branch (NOT the checkout's current HEAD) so a worktree created
+ * off a WIP branch never silently inherits unrelated commits. Prefers the remote
+ * default (`origin/<default>`) when present, else the local default branch, and
+ * falls back to the detected name so git surfaces a clear error if neither exists.
+ * @param {string} projectRoot - Repo root
+ * @param {Function} runFile - execFileSync function (for DI)
+ * @returns {string} The base ref to pass to `git worktree add ... <base>`
+ */
+function resolveDefaultBase(projectRoot, runFile) {
+  const def = detectDefaultBranch(projectRoot, { _exec: runFile });
+  const originRef = `origin/${def}`;
+  if (refExists(originRef, projectRoot, runFile)) return originRef;
+  if (refExists(def, projectRoot, runFile)) return def;
+  return def;
+}
+
 /**
  * True when a link failure is a privilege/support problem (Windows without the
  * symlink privilege, restricted FS) rather than a real error. In that case we
@@ -278,6 +313,14 @@ async function handleCreate(slug, flags, projectRoot, opts) {
 
   const worktreePath = path.resolve(worktreesDir, slug);
 
+  // Validate an explicit --base up front so a bad ref errors BEFORE anything is
+  // created (no branch, no worktree dir). Base only applies when creating a NEW
+  // branch; an existing branch is checked out as-is.
+  const explicitBase = flags['--base'] || null;
+  if (explicitBase && !refExists(explicitBase, projectRoot, runFile)) {
+    return { success: false, error: `Invalid --base: ref '${explicitBase}' not found. Verify it exists (git rev-parse --verify ${explicitBase}).` };
+  }
+
   // Step 0: Check if worktree already exists
   if (fsApi.existsSync(worktreePath)) {
     // A pre-existing worktree may be checked out on a different branch than the
@@ -303,12 +346,17 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   // Step 1: Ensure .worktrees/ dir exists
   fsApi.mkdirSync(worktreesDir, { recursive: true });
 
-  // Step 2: Create git worktree
+  // Step 2: Create git worktree. For a NEW branch, fork from an explicit --base or
+  // the repo's DEFAULT branch — NOT the checkout's current HEAD — so the worktree
+  // never silently inherits unrelated WIP commits (B2). An existing branch is
+  // checked out as-is (no base applies).
   const hasBranch = branchExists(branchName, runFile);
+  let base = null;
   if (hasBranch) {
     runFile('git', ['worktree', 'add', worktreePath, branchName], { stdio: 'pipe' });
   } else {
-    runFile('git', ['worktree', 'add', worktreePath, '-b', branchName], { stdio: 'pipe' });
+    base = explicitBase || resolveDefaultBase(projectRoot, runFile);
+    runFile('git', ['worktree', 'add', worktreePath, '-b', branchName, base], { stdio: 'pipe' });
   }
 
   // Step 3: Populate node_modules (link to the shared install, else install).
@@ -329,14 +377,19 @@ async function handleCreate(slug, flags, projectRoot, opts) {
   const linkage = await registerWorktreeLinkage({ projectRoot, worktreePath, branch: branchName, issueId, workFolder, opts });
   const backing = await autoFileBackingIssue({ projectRoot, worktreePath, branch: branchName, issueId, opts });
 
+  // Report the base so the fork point is never silent. `base` is null when an
+  // existing branch was checked out (no fork happened).
+  const baseNote = base ? `based on ${base}` : `existing branch ${branchName}`;
   return {
     success: true,
     worktreePath,
     branch: branchName,
+    base,
     depsLinked: deps.linked,
     depsInstalled: deps.installed,
     linkage,
     backing,
+    output: `Created worktree ${worktreePath} on ${branchName} (${baseNote}).`,
   };
 }
 
@@ -353,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
@@ -383,8 +462,8 @@ async function handleRemove(slug, projectRoot, opts) {
 }
 
 // Long flags that take a value, in both `--flag value` and `--flag=value` forms.
-const WORKTREE_VALUE_FLAGS = ['--branch', '--issue', '--work-folder'];
-const WORKTREE_USAGE_HINT = 'Usage: forge worktree create <slug> [--branch <name>] [--issue <id>] [--work-folder <path>]';
+const WORKTREE_VALUE_FLAGS = ['--branch', '--issue', '--work-folder', '--base'];
+const WORKTREE_USAGE_HINT = 'Usage: forge worktree create <slug> [--branch <name>] [--base <ref>] [--issue <id>] [--work-folder <path>]';
 
 function parseWorktreeArgs(args, flags) {
   const positional = [];
@@ -429,6 +508,7 @@ module.exports = {
   usage: 'forge worktree <create|remove|list> <slug>',
   flags: {
     '--branch': 'Custom branch name (default: feat/<slug>)',
+    '--base': 'Base ref a new branch forks from (default: the repo default branch, e.g. origin/main)',
     '--issue': 'Kernel issue id to link this worktree to (records issue → worktree)',
     '--work-folder': 'Repo-relative work-folder this issue owns (records worktree → work-folder + drops a .forge-issue marker)',
   },
@@ -486,5 +566,7 @@ module.exports = {
     setupWorktreeDeps,
     runInstall,
     autoFileBackingIssue,
+    refExists,
+    resolveDefaultBase,
   },
 };