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

package/lib/commands/shepherd.js

@@ -37,13 +37,22 @@ 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 brokerMod = require('../kernel/broker');
 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.
@@ -189,7 +198,18 @@ async function buildMonitorContext(pr, projectRoot, deps) {
     if (!validation.valid) {
       return { error: `Invalid pr-state adapter: ${validation.errors.join('; ')}` };
     }
-    dir = dir || monitorJournal.journalDir({ root: projectRoot || process.cwd(), repo: ctx.repo, pr: ctx.pr });
+    let gitCommonDir = deps.gitCommonDir;
+    if (!gitCommonDir) {
+      try {
+        const resolveGitCommonDir = deps.resolveGitCommonDir || brokerMod.resolveGitCommonDir;
+        gitCommonDir = resolveGitCommonDir(projectRoot || process.cwd(), { warn: () => {} });
+      } catch {
+        /* unavailable common-dir keeps the legacy per-root journal fallback */
+      }
+    }
+    dir = dir || monitorJournal.journalDir({
+      root: projectRoot || process.cwd(), gitCommonDir, repo: ctx.repo, pr: ctx.pr,
+    });
     gather = gather || (() => gatherMonitorSnapshot({ ...ctx, adapter, self: deps.self }));
     enrich = enrich || makeCheckFailureEnricher({
       ...ctx,
@@ -282,7 +302,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 +400,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 +443,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 +453,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/ship.js

@@ -12,7 +12,7 @@ const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
+const { fireAndForget } = require('../pr-monitor/reconcile-executor');
 const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
 
 const AUTO_SHEPHERD_RAIL = 'rail.auto_shepherd';
@@ -511,34 +511,31 @@ async function createPR(options) { // NOSONAR S3776
 }
 
 /**
- * Best-effort, non-blocking auto-start of the constant PR monitor once a real PR
- * exists. Skipped on a dry run or when no PR number is known. MUST NEVER fail
- * ship: `startWatcher` (startPrWatcherDetached) already never throws, and this
- * guard keeps even a surprise error from surfacing to the ship caller.
+ * Best-effort wake of the repository-wide singleton after a successful real ship.
+ * The shared trigger owns containment and gate checks; dry-run skips before it.
  *
- * Gated by the default-ON `rail.auto_shepherd` rail: when a maintainer has
- * disabled it (`forge gate disable rail.auto_shepherd`), the watcher is skipped
- * so the auto-start is honestly toggleable. The rail check is fail-open and
- * wrapped in the same try/catch, so neither a disabled rail nor a config-read
- * error ever fails ship.
- *
- * @param {{ dryRun: boolean, prNumber?: string|number, startWatcher: Function, railEnabled?: Function }} params
+ * @param {{ dryRun: boolean, projectRoot?: string, fireAndForget?: Function }} params
  * @returns {{ started: boolean, reason?: string }}
  */
-function maybeStartPrWatcher({ dryRun, prNumber, startWatcher, railEnabled = autoShepherdRailEnabled }) {
-	if (dryRun || !prNumber) return { started: false, reason: 'skipped' };
+function maybeTriggerShepherdAfterShip({ dryRun, projectRoot = process.cwd(), fireAndForget: trigger = fireAndForget }) {
+	if (dryRun) return { started: false, reason: 'skipped' };
 	try {
-		if (!railEnabled(process.cwd())) {
-			return { started: false, reason: 'rail.auto_shepherd disabled' };
-		}
-		return startWatcher({ prNumber, cwd: process.cwd() });
+		trigger({ projectRoot, dryRun });
+		return { started: true };
 	} catch (err) {
 		return { started: false, reason: err.message };
 	}
 }
 
 async function executeShip(options) {
-	const { featureSlug, title, dryRun = false, startWatcher = startPrWatcherDetached, railEnabled = autoShepherdRailEnabled } = options || {};
+	const {
+		featureSlug,
+		title,
+		dryRun = false,
+		projectRoot = process.cwd(),
+		fireAndForget: trigger = fireAndForget,
+		createPr = createPR,
+	} = options || {};
 
 	// Validate feature slug
 	if (!featureSlug || typeof featureSlug !== 'string' || featureSlug.trim() === '') {
@@ -588,9 +585,9 @@ async function executeShip(options) {
 			testScenarios,
 			coverage,
 		});
-		const result = await createPR({ title, body: prBody, dryRun });
+		const result = await createPr({ title, body: prBody, dryRun });
 		if (!result.success) return result;
-		maybeStartPrWatcher({ dryRun, prNumber: result.prNumber, startWatcher, railEnabled });
+		maybeTriggerShepherdAfterShip({ dryRun, projectRoot, fireAndForget: trigger });
 		return {
 			success: true,
 			prUrl: result.prUrl,
@@ -605,11 +602,13 @@ async function executeShip(options) {
 module.exports = {
 	name: 'ship',
 	description: 'Create a pull request from validated feature work',
-	handler: async (args, flags = {}) => {
+	handler: async (args, flags = {}, projectRoot = process.cwd(), deps = {}) => {
 		const result = await executeShip({
 			featureSlug: args[0],
 			title: args[1],
 			dryRun: Boolean(flags.dryRun || flags['--dry-run']),
+			projectRoot,
+			fireAndForget: deps.fireAndForget,
 		});
 		if (!result.success) {
 			return result;
@@ -623,7 +622,7 @@ module.exports = {
 			output: lines.join('\n'),
 		};
 	},
-	maybeStartPrWatcher,
+	maybeTriggerShepherdAfterShip,
 	autoShepherdRailEnabled,
 	extractKeyDecisions,
 	extractTestScenarios,

package/lib/commands/skill.js

@@ -0,0 +1,383 @@
+'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 { runBehavioralEvaluation } = require('../../scripts/lib/behavioral-eval-runner');
+const { resolveBehavioralEvaluation } = require('../../scripts/lib/behavioral-eval-runtime');
+const { loadPromotionEvidence } = require('../../scripts/lib/promotion-evidence-loader');
+const { scorePromotion } = require('../../scripts/lib/promotion-scorecard');
+
+const BEHAVIORAL_TIERS = Object.freeze([30, 100, 300]);
+const BEHAVIORAL_TIER_VALUES = new Set(BEHAVIORAL_TIERS.map(String));
+const BEHAVIORAL_TIER_USAGE = BEHAVIORAL_TIERS.join('|');
+
+const USAGE = 'Usage: forge skill for "<situation>" [--json]\n' +
+  '       forge skill eval [name] --static [--json]\n' +
+  `       forge skill eval <name> --full --tier ${BEHAVIORAL_TIER_USAGE} [--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');
+}
+
+function readFlagValue(rest, flags, name) {
+  const direct = flags[name] ?? flags[`--${name}`];
+  if (direct !== undefined && direct !== true) return direct;
+  const exact = rest.indexOf(`--${name}`);
+  if (exact >= 0) return rest[exact + 1];
+  const prefix = `--${name}=`;
+  const joined = rest.find(arg => typeof arg === 'string' && arg.startsWith(prefix));
+  return joined ? joined.slice(prefix.length) : undefined;
+}
+
+function hasFlag(rest, flags, name) {
+  return flags[name] === true || flags[`--${name}`] === true ||
+    rest.includes(`--${name}`) || rest.some(arg => typeof arg === 'string' && arg.startsWith(`--${name}=`));
+}
+
+function positionalArgs(rest, valueFlags = []) {
+  const positional = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (typeof arg !== 'string') continue;
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+    const flagName = arg.slice(2).split('=', 1)[0];
+    if (valueFlags.includes(flagName) && !arg.includes('=')) index += 1;
+  }
+  return positional;
+}
+
+async function handleFullEval(rest, flags, projectRoot, opts) {
+  const json = hasFlag(rest, flags, 'json');
+  const tierValue = readFlagValue(rest, flags, 'tier');
+  const name = positionalArgs(rest, ['tier'])[0];
+  if (!name) return { success: false, error: 'Behavioral evaluation requires a skill name.\n' + USAGE };
+  const tier = Number(tierValue);
+  if (!BEHAVIORAL_TIER_VALUES.has(String(tierValue))) {
+    return { success: false, error: `Behavioral evaluation requires --tier ${BEHAVIORAL_TIER_USAGE}.\n` + USAGE };
+  }
+
+  const ctx = skillEval.resolveSkillsContext(projectRoot);
+  if (!ctx || !fs.existsSync(path.join(ctx.skillsDir, name, 'SKILL.md'))) {
+    return { success: false, error: `Skill '${name}' not found.` };
+  }
+
+  const scoreResult = (result) => {
+    const loaded = loadPromotionEvidence({ tier, findings: result.findings });
+    const scorecard = scorePromotion({ tier, pairs: loaded.ok ? loaded.pairs : [] });
+    if (!loaded.ok) scorecard.reasons = [loaded.reason];
+    return { ...result, scorecard };
+  };
+  const formatResult = (result) => {
+    const successfulScore = tier === BEHAVIORAL_TIERS[0] || result.scorecard.status === 'PASS';
+    const success = result.status === 'PASS' && successfulScore;
+    let error;
+    if (!success) {
+      error = result.status !== 'PASS'
+        ? `Behavioral evaluation ${result.status}.`
+        : `Promotion ${result.scorecard.phase || 'evaluation'} ${result.scorecard.status}.`;
+    }
+    const output = json
+      ? JSON.stringify(result, null, 2) + '\n'
+      : `Behavioral evaluation: ${result.status}\nTier: ${tier}\n` +
+        `Completed: ${result.completedRuns}/${result.expectedRuns}\n` +
+        `Promotion: ${result.scorecard.phase || 'unavailable'} / ${result.scorecard.status}`;
+    return { success, error, behavioral: result, output };
+  };
+
+  const runner = opts.runBehavioralEvaluation || runBehavioralEvaluation;
+  let behavioralOptions = opts.behavioralOptions || {};
+  if (!opts.runBehavioralEvaluation || opts.resolveBehavioralEvaluation) {
+    const resolver = opts.resolveBehavioralEvaluation || resolveBehavioralEvaluation;
+    const resolved = await resolver({
+      projectRoot,
+      skillName: name,
+      skillPath: path.join(ctx.skillsDir, name, 'SKILL.md'),
+      tier,
+      env: opts.env || process.env,
+    });
+    if (!resolved.ok) return formatResult(scoreResult(resolved.result));
+    behavioralOptions = { ...resolved.options, ...behavioralOptions };
+  }
+  const result = scoreResult(await runner({
+    ...behavioralOptions,
+    projectRoot,
+    skillName: name,
+    tier,
+  }));
+  return formatResult(result);
+}
+
+/**
+ * "forge skill eval [name] --static [--json]" -- compute + persist the DETERMINISTIC scorecard(s).
+ * All skills when no name. --static is accepted and implied; behavioral execution is isolated
+ * behind the explicit --full branch above so existing static scoring remains unchanged.
+ */
+function handleEval(rest, flags, projectRoot, opts = {}) {
+  const full = hasFlag(rest, flags, 'full');
+  if (full) return handleFullEval(rest, flags, projectRoot, opts);
+  if (readFlagValue(rest, flags, 'tier') !== undefined) {
+    return { success: false, error: '--tier is valid only with --full.\n' + USAGE };
+  }
+  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('', 'Use --full --tier 30|100|300 for controlled behavioral evidence.');
+  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',
+    '--full': 'Run the controlled behavioral evaluation tier',
+    '--tier': `Behavioral corpus tier: ${BEHAVIORAL_TIER_USAGE}`,
+  },
+  // The registry passes (args, flags, projectRoot, opts). Only the trailing `opts` carries a
+  // default so SonarCloud S1788 stays satisfied; `flags` is normalized in the body. The router
+  // reads the canonical catalog from the package root; eval/scores read the canonical skills dir.
+  handler: (args, rawFlags, projectRoot, opts = {}) => {
+    const flags = rawFlags || {};
+    const verb = args[0];
+    if (verb === 'for') {
+      return handleFor(args.slice(1), flags);
+    }
+    if (verb === 'eval') {
+      return handleEval(args.slice(1), flags, projectRoot, opts);
+    }
+    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, handleFullEval, handleScores, handleCoverage, formatScores, formatCoverage },
+};