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

package/lib/commands/ship.js

@@ -12,8 +12,9 @@ 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 { resolveBaseRemote, resolveBaseBranch } = require('../base-remote');
 
 const AUTO_SHEPHERD_RAIL = 'rail.auto_shepherd';
 
@@ -65,72 +66,6 @@ function getQuietGitExecOptions(cwd = process.cwd()) {
 	return { ...getGitExecOptions(cwd), stdio: 'pipe' };
 }
 
-function resolveRemoteHeadTarget(exec = execFileSync, cwd = process.cwd(), remoteName) {
-	try {
-		const symbolicRef = exec('git', ['symbolic-ref', `refs/remotes/${remoteName}/HEAD`], getQuietGitExecOptions(cwd)).trim();
-		if (!symbolicRef) {
-			return null;
-		}
-		exec('git', ['rev-parse', '--verify', symbolicRef], getQuietGitExecOptions(cwd));
-		return symbolicRef;
-	} catch (_error) {
-		return null;
-	}
-}
-
-function remoteHasTrackingBase(exec = execFileSync, cwd = process.cwd(), remoteName) {
-	if (resolveRemoteHeadTarget(exec, cwd, remoteName)) {
-		return true;
-	}
-
-	for (const candidate of ['main', 'master']) {
-		try {
-			exec('git', ['rev-parse', '--verify', `refs/remotes/${remoteName}/${candidate}`], getQuietGitExecOptions(cwd));
-			return true;
-		} catch (_error) {
-			// Probe next candidate.
-		}
-	}
-
-	return false;
-}
-
-function resolveBaseRemote(exec = execFileSync, cwd = process.cwd()) {
-	for (const candidate of ['upstream', 'origin']) {
-		try {
-			exec('git', ['remote', 'get-url', candidate], getQuietGitExecOptions(cwd));
-			if (remoteHasTrackingBase(exec, cwd, candidate)) {
-				return candidate;
-			}
-		} catch (_error) {
-			// Probe next candidate.
-		}
-	}
-
-	return 'origin';
-}
-
-function resolveBaseBranch(exec = execFileSync, cwd = process.cwd(), remoteName = resolveBaseRemote(exec, cwd)) {
-	const symbolicRef = resolveRemoteHeadTarget(exec, cwd, remoteName);
-	if (symbolicRef) {
-		const match = new RegExp(`^refs/remotes/${remoteName}/(.+)$`).exec(symbolicRef);
-		if (match && match[1]) {
-			return match[1];
-		}
-	}
-
-	for (const candidate of ['main', 'master']) {
-		try {
-			exec('git', ['rev-parse', '--verify', `refs/remotes/${remoteName}/${candidate}`], getQuietGitExecOptions(cwd));
-			return candidate;
-		} catch (_error) {
-			// Probe next candidate.
-		}
-	}
-
-	return 'master';
-}
-
 function refreshBaseReference(exec = execFileSync, cwd = process.cwd(), remoteName, baseBranch) {
 	exec(
 		'git',
@@ -457,10 +392,13 @@ function validatePRTitle(title) {
 
 async function createPR(options) { // NOSONAR S3776
 	const { title, body, dryRun = false, exec = execFileSync, cwd = process.cwd() } = options;
+	const gh = options.githubContext?.bound
+		? (args, runOptions) => options.githubContext.runGh(args, runOptions)
+		: (args, runOptions) => exec('gh', args, runOptions);
 	const titleValidation = validatePRTitle(title);
 	if (!titleValidation.valid) return { success: false, error: titleValidation.error };
 	try {
-		exec('gh', ['--version'], { ...getGhCheckOptions(), cwd });  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		gh(['--version'], { ...getGhCheckOptions(), cwd });
 	} catch (error) {
 		if (isCommandNotFound(error)) {
 			return { success: false, error: 'GitHub CLI (gh) not found. Install from: https://cli.github.com/' };
@@ -495,7 +433,7 @@ async function createPR(options) { // NOSONAR S3776
 		return { success: true, message: '[DRY RUN] Would create PR with title: ' + title, prUrl: 'https://github.com/owner/repo/pull/1' };
 	}
 	try {
-		const result = exec('gh', ['pr', 'create', '--title', title, '--body', body], getGitExecOptions(cwd));  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		const result = gh(['pr', 'create', '--title', title, '--body', body], getGitExecOptions(cwd));
 		const urlMatch = /https:\/\/github\.com\/[^\s]+/.exec(result);
 		const prUrl = urlMatch ? urlMatch[0] : null;
 		const numberMatch = /\/pull\/(\d+)/.exec(result);
@@ -511,34 +449,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 +523,12 @@ async function executeShip(options) {
 			testScenarios,
 			coverage,
 		});
-		const result = await createPR({ title, body: prBody, dryRun });
+		const result = await createPr({
+			title, body: prBody, dryRun,
+			exec: options.exec, cwd: options.cwd || projectRoot, githubContext: options.githubContext,
+		});
 		if (!result.success) return result;
-		maybeStartPrWatcher({ dryRun, prNumber: result.prNumber, startWatcher, railEnabled });
+		maybeTriggerShepherdAfterShip({ dryRun, projectRoot, fireAndForget: trigger });
 		return {
 			success: true,
 			prUrl: result.prUrl,
@@ -604,12 +542,19 @@ async function executeShip(options) {
 
 module.exports = {
 	name: 'ship',
+	githubAuth: true,
 	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,
+			exec: deps.exec,
+			cwd: deps.cwd || projectRoot,
+			githubContext: deps.githubContext,
+			createPr: deps.createPr,
 		});
 		if (!result.success) {
 			return result;
@@ -623,7 +568,7 @@ module.exports = {
 			output: lines.join('\n'),
 		};
 	},
-	maybeStartPrWatcher,
+	maybeTriggerShepherdAfterShip,
 	autoShepherdRailEnabled,
 	extractKeyDecisions,
 	extractTestScenarios,

package/lib/commands/skill.js

@@ -19,9 +19,19 @@ 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 { createGithubContext } = require('../github-context');
+
+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 +87,115 @@ 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;
+    let githubContext;
+    try {
+      githubContext = (opts.prepareGithubContext || createGithubContext)(projectRoot);
+    } catch {
+      return { success: false, error: 'Unable to prepare GitHub account context. Run forge github status for guidance.' };
+    }
+    const resolved = await resolver({
+      projectRoot,
+      skillName: name,
+      skillPath: path.join(ctx.skillsDir, name, 'SKILL.md'),
+      tier,
+      env: opts.env || process.env,
+      ...(githubContext.bound ? { deps: { runGh: githubContext.runGh } } : {}),
+    });
+    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 +229,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 +356,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 +387,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/team.js

@@ -1,7 +1,25 @@
 const { existsSync } = require('node:fs');
 const { execFileSync } = require('node:child_process');
 const path = require('node:path');
-const { getPackageRoot } = require('../package-root');
+const { getPackageRoot, isCompiledBinary } = require('../package-root');
+const { firstPositionalIndex, stripGlobalFlags } = require('../global-flags');
+
+function teamArguments(args) {
+  const subcommandIndex = firstPositionalIndex(args);
+  if (subcommandIndex === -1) return stripGlobalFlags(args);
+  const result = stripGlobalFlags(args.slice(0, subcommandIndex));
+  // Path is routing metadata anywhere; other flags after the subcommand belong to Team.
+  for (let index = subcommandIndex; index < args.length; index++) {
+    const arg = args[index];
+    if (arg.startsWith('--path=')) continue;
+    if (arg === '-p' || arg === '--path') {
+      if (args[index + 1] !== undefined && !args[index + 1].startsWith('-')) index++;
+    } else {
+      result.push(arg);
+    }
+  }
+  return result;
+}
 
 // Resolve bash binary from fixed, known locations only (no PATH search).
 // SonarCloud S4036: PATH must not be searched for OS commands.
@@ -22,28 +40,49 @@ function _resolveBash() {
   return '/usr/bin/bash';
 }
 
-function handleTeam(args) {
+function handleTeam(args, projectRoot = process.cwd(), deps = {}) {
   // Route through the asset root so `forge team` finds the script in BOTH channels:
   // the on-disk package (npm/npx) and a compiled binary (extracted embed dir).
-  const scriptPath = path.join(getPackageRoot(), 'scripts', 'forge-team', 'index.sh');
+  const packageRoot = getPackageRoot();
+  const scriptPath = path.join(packageRoot, 'scripts', 'forge-team', 'index.sh');
   const bashPath = _resolveBash();
+  const runFile = deps.execFileSync || execFileSync;
+  const options = { stdio: 'inherit' };
+  if (deps.githubContext?.bound) {
+    // Bash also runs Git/Forge/helpers. Only the re-entering gh bridge may resolve credentials.
+    const compiled = (deps.isCompiledBinary || isCompiledBinary)();
+    const env = { ...(deps.env || process.env) };
+    for (const key of Object.keys(env)) {
+      if (['gh_token', 'github_token', 'gh_host'].includes(key.toLowerCase())) delete env[key];
+    }
+    options.cwd = projectRoot;
+    options.env = {
+      ...env,
+      GH_CMD: path.join(packageRoot, 'scripts', 'github-context-bridge.sh').replaceAll('\\', '/'),
+      FORGE_GITHUB_RUNTIME: process.execPath.replaceAll('\\', '/'),
+      FORGE_GITHUB_ENTRY: compiled ? '' : path.join(packageRoot, 'bin', 'forge.js').replaceAll('\\', '/'),
+    };
+  }
 
   try {
-    execFileSync(bashPath, [scriptPath, ...args], {
-      stdio: 'inherit',
-    });
+    runFile(bashPath, [scriptPath, ...teamArguments(args)], options);
   } catch (err) {
     process.exit(err.status || 1);
   }
 }
 
-async function handler(args = []) {
-  handleTeam(args);
+async function handler(args, _flags, projectRoot, deps = {}) {
+  handleTeam(args || [], projectRoot, deps);
   return { success: true };
 }
 
 module.exports = {
   name: 'team',
+  githubAuth: (args = []) => {
+    const teamArgs = teamArguments(args);
+    return ['add', 'verify', 'sync', 'claim'].includes(teamArgs[0])
+      || (teamArgs[0] === 'workload' && teamArgs.slice(1).some(arg => arg.replace(/\r$/, '') === '--me'));
+  },
   description: 'Team coordination workflows and sync utilities',
   handler,
   handleTeam