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

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

@@ -19,9 +19,18 @@ 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]';
 
@@ -77,12 +86,108 @@ function writeScorecard(skillsDir, name, card) {
   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 the only tier today (behavioral is W5); it is accepted (and
- * implied) so the flag reads honestly and future tiers can branch here.
+ * 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) {
+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];
@@ -116,7 +221,7 @@ function handleEval(rest, flags, projectRoot) {
   }
   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.');
+  lines.push('', 'Use --full --tier 30|100|300 for controlled behavioral evidence.');
   return { success: true, cards, output: lines.join('\n') };
 }
 
@@ -243,18 +348,21 @@ module.exports = {
   usage: USAGE,
   flags: {
     '--json': 'Emit the machine-readable result',
-    '--static': 'Score only the deterministic static tier (the only tier today; behavioral is W5)',
+    '--static': 'Score only the deterministic static tier',
+    '--full': 'Run the controlled behavioral evaluation tier',
+    '--tier': `Behavioral corpus tier: ${BEHAVIORAL_TIER_USAGE}`,
   },
-  // 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) => {
+  // 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);
+      return handleEval(args.slice(1), flags, projectRoot, opts);
     }
     if (verb === 'scores') {
       return handleScores(args.slice(1), flags, projectRoot);
@@ -271,5 +379,5 @@ module.exports = {
     };
   },
   // Exposed for unit tests; not part of the CLI surface.
-  _internal: { parseForArgs, formatRouting, handleFor, handleEval, handleScores, handleCoverage, formatScores, formatCoverage },
+  _internal: { parseForArgs, formatRouting, handleFor, handleEval, handleFullEval, handleScores, handleCoverage, formatScores, formatCoverage },
 };

package/lib/commands/status.js

@@ -751,12 +751,28 @@ function formatStatus(result) {
 module.exports = {
 	name: 'status',
 	description: 'One-glance orientation: where you are, what to run next, and your work',
-	usage: 'forge status [--full] [--json]',
+	usage: 'forge status [-v|--verbose] [--full] [--json]',
 	flags: {
+		'-v, --verbose': 'Print the full session-entry briefing (replaces the deprecated `forge prime`)',
 		'--full': 'Also show blocked, stale, and recently completed issues',
 		'--json': 'Emit the machine-readable status envelope',
 	},
 	handler: async (args, flags, projectRoot) => {
+		// git-status-v semantics: bare status is the short pulse, -v is the long form.
+		// `--verbose` also arrives as flags.verbose from the global CLI flag parser.
+		const statusArgs = Array.isArray(args) ? args : [];
+		if (flags?.verbose === true || statusArgs.includes('-v') || statusArgs.includes('--verbose')) {
+			// Required lazily so the short pulse never loads the briefing's module graph.
+			const { renderBriefing } = require('./prime');
+			// The briefing reads --json from args (same as prime), so fold in the flag
+			// forms the short pulse accepts or `-v` would silently drop them.
+			const wantsJson = flags?.json === true || flags?.['--json'] === true;
+			const briefingArgs = wantsJson && !statusArgs.includes('--json')
+				? [...statusArgs, '--json']
+				: statusArgs;
+			return renderBriefing(briefingArgs, projectRoot || process.cwd());
+		}
+
 		// 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

package/lib/commands/test.js

@@ -5,7 +5,6 @@
  *
  * Wraps test execution with smart defaults:
  * - Auto-detects package manager from lockfiles
- * - Checks Beads (Dolt) connectivity, sets BEADS_SKIP_TESTS if unavailable
  * - Supports --affected flag to run only tests for changed files
  *
  * Security: Uses execFileSync for subprocess calls (OWASP A03)
@@ -17,6 +16,8 @@ const { execFileSync: defaultExecFileSync, spawnSync: defaultSpawnSync } = requi
 const defaultFs = require('node:fs');
 const path = require('node:path');
 
+const { selectDocAssertingTests } = require('../doc-assertions');
+
 /** @type {Array<[string, string]>} Lockfile → package manager mapping (order matters) */
 const LOCKFILE_MAP = [
 	['bun.lockb', 'bun'],
@@ -26,12 +27,10 @@ const LOCKFILE_MAP = [
 ];
 
 const DEFAULT_TIMEOUT = 120000;
-const BEADS_CHECK_TIMEOUT = 3000;
 const DIRECT_TEST_CANDIDATES = Object.freeze({
 	'bin/forge.js': [
 		'test/cli-flags.test.js',
 		'test/forge-cli-registry.test.js',
-		'test/setup-github-sync.test.js',
 		'test/setup-runtime-flags.test.js',
 	],
 	// The second CLI surface (command descriptions + shepherd wiring). Without an
@@ -41,6 +40,13 @@ const DIRECT_TEST_CANDIDATES = Object.freeze({
 		'test/forge-cmd-shepherd.test.js',
 	],
 	'bin/forge-preflight.js': ['test/bin/forge-preflight.test.js'],
+	// The CI entry point is covered by the doc-assertion regression suite; without
+	// this entry it resolves to zero tests and forces the full suite.
+	// (lib/doc-assertions.js resolves via the lib/ -> test/ convention below.)
+	'scripts/doc-asserting-tests.js': [
+		'test/doc-assertions.test.js',
+		'test/scripts/doc-asserting-tests.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 /
@@ -84,22 +90,6 @@ function detectPackageManager(projectRoot, fs) {
 	return 'npm';
 }
 
-/**
- * Check if Beads (bd CLI) is reachable.
- *
- * @param {Function} execFileSync - Injected execFileSync
- * @returns {boolean} true if bd is available
- */
-function checkBeadsConnectivity(execFileSync) {
-	try {
-		execFileSync('bd', ['list', '--limit=1'], { timeout: BEADS_CHECK_TIMEOUT });
-		return true;
-	} catch (_e) { // NOSONAR S2486
-		/* intentional: bd not installed or unreachable */
-		return false;
-	}
-}
-
 function resolveBaseBranch(execFileSync) {
 	let baseBranch = 'main';
 	try {
@@ -196,6 +186,16 @@ function getAffectedTestFiles(projectRoot, execFileSync, fs = defaultFs, options
 		}
 	}
 
+	// Markdown changes must also run the suites that assert on that markdown's
+	// CONTENT (README size badge, AGENTS.md convention, docs consistency). The
+	// static mapping above only knows the docs-consistency suite, so a docs PR
+	// used to merge green and break master for the next code PR (issue 63556816).
+	// The set is derived from the test sources, so new markdown-reading suites are
+	// picked up without editing a list here.
+	for (const candidate of selectDocAssertingTests(changedFiles, projectRoot, fs)) {
+		testFiles.add(candidate);
+	}
+
 	return Array.from(testFiles).sort((left, right) => left.localeCompare(right));
 }
 
@@ -291,7 +291,7 @@ module.exports = {
 	 * @param {Object} [deps.fs] - fs module
 	 * @param {Function} [deps.execFileSync] - child_process.execFileSync
 	 * @param {Function} [deps.spawnSync] - child_process.spawnSync
-	 * @returns {Promise<{ success: boolean, exitCode: number, beadsSkipped: boolean }>}
+	 * @returns {Promise<{ success: boolean, exitCode: number }>}
 	 */
 	async handler(_args, flags, projectRoot, deps = {}) {
 		const fs = deps.fs || defaultFs;
@@ -313,19 +313,10 @@ module.exports = {
 			}
 		} catch (_e) { /* intentional: package.json missing or unreadable, use default timeout */ } // NOSONAR S2486
 
-		// 3. Check Beads connectivity
-		const beadsAvailable = checkBeadsConnectivity(execFileSync);
-		const beadsSkipped = !beadsAvailable;
-
-		const extraEnv = {};
-		if (beadsSkipped) {
-			extraEnv.BEADS_SKIP_TESTS = '1';
-		}
-
-		// 4. Build test command args
+		// 3. Build test command args
 		let testArgs = ['run', 'test'];
 
-		// 5. --affected flag: find changed test files
+		// 4. --affected flag: find changed test files
 		if (flags['--affected'] || flags.affected) {
 			const affectedTests = getAffectedTestFiles(projectRoot, execFileSync, fs, {
 				sinceUpstream: flags.sinceUpstream || flags['--since-upstream'],
@@ -336,9 +327,9 @@ module.exports = {
 			// If no affected tests found, fall back to running all tests
 		}
 
-		// 6. Run tests
+		// 5. Run tests
 		const result = spawnSync(pkgManager, testArgs, {
-			env: { ...process.env, ...extraEnv },
+			env: { ...process.env },
 			timeout,
 			stdio: 'inherit',
 			shell: process.platform === 'win32',
@@ -349,7 +340,6 @@ module.exports = {
 		return {
 			success: exitCode === 0,
 			exitCode,
-			beadsSkipped,
 		};
 	},
 };