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

package/scripts/test-profile.js

@@ -159,6 +159,17 @@ function finalizeSignalMetrics(metrics, fileDurations) {
   };
 }
 
+function parseJUnitTestcases(content) {
+  if (typeof content !== 'string') return [];
+  return Array.from(
+    content.matchAll(/<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g),
+    (match) => ({
+      attrs: parseAttributes(match[1] || ''),
+      body: match[2] || '',
+    }),
+  );
+}
+
 function parseJUnitFiles(files) {
   const fileDurations = new Map();
   const timedOutFiles = new Set();
@@ -177,9 +188,7 @@ function parseJUnitFiles(files) {
       suiteDurationMs += Math.round(Number.parseFloat(attrs.time || '0') * 1000);
     }
 
-    for (const caseMatch of content.matchAll(/<testcase\b([^>]*)>([\s\S]*?)<\/testcase>|<testcase\b([^>]*)\/>/g)) {
-      const attrs = parseAttributes(caseMatch[1] || caseMatch[3] || '');
-      const body = caseMatch[2] || '';
+    for (const { attrs, body } of parseJUnitTestcases(content)) {
       const durationMs = Math.round(Number.parseFloat(attrs.time || '0') * 1000);
       const fallbackFile = path.basename(file);
       const testcase = classifyTestcase({
@@ -273,6 +282,7 @@ module.exports = {
   parseArgs,
   parseAttributes,
   parseJUnitFiles,
+  parseJUnitTestcases,
   selectPrimaryBucket,
   walk,
 };

package/scripts/test.js

@@ -4,18 +4,32 @@
  *
  * It runs only the tests affected by known changes when possible and falls back
  * to the full suite for package-level or unknown-file changes.
+ *
+ * Quick lane: `forge push --quick` sets FORGE_PUSH_LANE=quick on the `git push`
+ * it spawns, declaring the lint-only review-cycle lane. The pre-push entry point
+ * honors that declaration and skips the test run with a loud notice, so --quick
+ * is quick end to end instead of only in the step push.js controls. This is not
+ * a hook bypass: branch protection and lint still run, local validation
+ * (`--validate`) ignores the variable entirely, and CI runs the full matrix.
  */
 
-const { execFileSync: defaultExecFileSync, spawnSync: defaultSpawnSync } = require('node:child_process');
+const { EventEmitter } = require('node:events');
+const {
+  execFileSync: defaultExecFileSync,
+  spawn: defaultSpawn,
+} = require('node:child_process');
 const fs = require('node:fs');
 
 const {
   getAffectedTestFiles,
   getChangedFiles,
+  isFullSuiteRequiredFile,
 } = require('../lib/commands/test');
+const { createProcessTree, signalExitCode } = require('./process-tree');
 
 const PACKAGE_LEVEL_PATHS = new Set([
   'package.json',
+  'bun.lock',
   'bun.lockb',
   'pnpm-lock.yaml',
   'yarn.lock',
@@ -29,8 +43,49 @@ const KNOWN_TARGETABLE_PREFIXES = [
   '.github/agentic-workflows/',
   '.github/workflows/',
   'test/',
+  // Source trees with a dedicated suite; see PREFIX_TEST_TARGETS in
+  // lib/commands/test.js for the tests each one resolves to. Without both halves
+  // (targetable here + a resolved test there) a change falls to the full-suite lane.
+  'validation/',
+  'eval/',
+  'rules/',
+  'plugin/',
 ];
 
+// Individually mapped root files (see DIRECT_TEST_CANDIDATES in lib/commands/test.js).
+const KNOWN_TARGETABLE_FILES = new Set([
+  'lefthook.yml',
+  'eslint.config.js',
+  '.coderabbit.yaml',
+  'CODING_STANDARDS.md',
+  '.claude-plugin/marketplace.json',
+  'lib/kernel/schema.js',
+  'lib/kernel/migrations.js',
+  'lib/kernel/sqlite-driver.js',
+  'lib/commands/shepherd.js',
+  'lib/commands/github.js',
+  'lib/github-context.js',
+  'lib/commands/_registry.js',
+  'lib/commands/pr.js',
+  'lib/commands/ship.js',
+  'lib/commands/merge.js',
+  'lib/commands/team.js',
+  'lib/commands/clean.js',
+  'scripts/github-context-bridge.sh',
+  'lib/commands/push.js',
+  'lib/commands/hooks.js',
+  'lib/commands/serve.js',
+  'lib/commands/skill.js',
+  'scripts/lib/behavioral-eval-runtime.js',
+  'web/dashboard/generate-snapshot.mjs',
+  'lib/pr-monitor/watch-owner.js',
+  'lib/pr-monitor/reconcile.js',
+  'lib/pr-monitor/reconcile-executor.js',
+  'lib/pr-monitor/watch-lifecycle.js',
+  'lib/pr-monitor/shepherd-lease.js',
+  'lib/pr-monitor/monitor.js',
+]);
+
 const ALWAYS_RUN_RISK_TEST_TARGETS = [
   // Windows + concurrent filesystem locking has failed post-merge; keep this
   // in the fast PR lane until enough full-matrix runs prove it stable.
@@ -52,18 +107,48 @@ const isWindows = process.platform === 'win32';
 // wedged). Raise it with FORGE_TEST_TIMEOUT_MS for slow machines.
 const DEFAULT_TEST_COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
 
-// Wall-clock budget for the FULL-SUITE fallback lane (`scripts/test-full-suite.js`),
-// which runs on package-level, unmapped, or zero-resolved changes. Unlike a
-// targeted lane, a healthy full suite legitimately takes 5-10 min, so the 5-min
-// fail-fast ceiling would kill a good-but-slow full run. Kept at 10 min to stay
-// aligned with the local-validation budget (VALIDATION_COMMAND_TIMEOUT_MS = 600000
-// in lib/commands/validate.js and its "long enough subprocess timeout for the
-// full local suite" regression test). FORGE_TEST_TIMEOUT_MS still overrides.
-const DEFAULT_FULL_SUITE_TIMEOUT_MS = 10 * 60 * 1000;
+// Measured wall-clock runtime of a HEALTHY, fully passing full suite on a
+// developer Windows machine with pinned Bun 1.3.12 (2026-08-26):
+//
+//   8005 pass, 32 skip, 1 todo, 0 fail — 8038 tests across 594 files [602.43s]
+//
+// Any full-suite budget must clear this by a wide margin. Treat it as a floor to
+// measure against, never as the budget itself.
+const OBSERVED_FULL_SUITE_RUNTIME_MS = 602_430;
+
+// Wall-clock budget for the FULL-SUITE lane (`scripts/test-full-suite.js` and the
+// package-level `test` script run by `forge push`), used on package-level,
+// unmapped, or zero-resolved changes.
+//
+// This ceiling exists to catch an INDEFINITE HANG (issue 8aef79e8: a synchronous
+// git/bash spawn wedged during git mid-push state, observed ~50 min), not to
+// bound normal runtime. So it is sized as ~2x the measured healthy runtime above,
+// not fitted to it. The previous 10-min value was BELOW the 602.43s measurement,
+// so it SIGKILLed passing suites — `forge push` died mid-suite with no summary
+// and never pushed. 25 min is the next round number clearing 2x the measurement
+// (1_204_860 ms). Do not shave this back toward the observed runtime; if a
+// slower machine needs more, raise FORGE_TEST_TIMEOUT_MS (which still overrides)
+// and re-measure before changing this default.
+const DEFAULT_FULL_SUITE_TIMEOUT_MS = 25 * 60 * 1000;
 
 // Conventional shell exit code for a command terminated by a timeout.
 const TIMEOUT_EXIT_CODE = 124;
 
+// Lane declaration set by `forge push --quick` on the spawned `git push`.
+// Only this exact value opts into the lint-only lane.
+const QUICK_LANE_ENV_VAR = 'FORGE_PUSH_LANE';
+const QUICK_LANE_VALUE = 'quick';
+
+/**
+ * Reports whether the environment declares the lint-only quick push lane.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env] Environment to inspect.
+ * @returns {boolean} True when the quick lane is explicitly declared.
+ */
+function isQuickPushLane(env = process.env) {
+  return env[QUICK_LANE_ENV_VAR] === QUICK_LANE_VALUE;
+}
+
 /**
  * Reads and validates the FORGE_TEST_TIMEOUT_MS override, if any.
  *
@@ -87,9 +172,10 @@ function resolveCommandTimeoutMs(env = process.env) {
 }
 
 /**
- * Resolves the wall-clock budget for the full-suite fallback lane. An explicit
+ * Resolves the wall-clock budget for the full-suite lane. An explicit
  * FORGE_TEST_TIMEOUT_MS override wins; otherwise it uses the larger,
- * validation-aligned budget so a healthy-but-slow full run is not failed fast.
+ * measurement-derived budget (~2x OBSERVED_FULL_SUITE_RUNTIME_MS) so a healthy
+ * full run is never failed fast.
  *
  * @param {NodeJS.ProcessEnv} [env=process.env] Environment to read the override from.
  * @returns {number} Timeout in milliseconds (defaults to DEFAULT_FULL_SUITE_TIMEOUT_MS).
@@ -134,9 +220,11 @@ function detectPackageManager() {
 function stripGitHookEnv(sourceEnv = process.env) {
   const env = { ...sourceEnv };
   for (const key of Object.keys(env)) {
-    if (key === 'GIT_DIR' || key === 'GIT_WORK_TREE' || key === 'GIT_INDEX_FILE'
-      || key === 'GIT_OBJECT_DIRECTORY' || key === 'GIT_ALTERNATE_OBJECT_DIRECTORIES'
-      || key === 'GIT_QUARANTINE_PATH') {
+    const normalizedKey = key.toUpperCase();
+    if (normalizedKey === 'GIT_DIR' || normalizedKey === 'GIT_WORK_TREE'
+      || normalizedKey === 'GIT_INDEX_FILE' || normalizedKey === 'GIT_OBJECT_DIRECTORY'
+      || normalizedKey === 'GIT_ALTERNATE_OBJECT_DIRECTORIES'
+      || normalizedKey === 'GIT_QUARANTINE_PATH') {
       delete env[key];
     }
   }
@@ -154,6 +242,10 @@ function isKnownTargetablePath(file) {
     return true;
   }
 
+  if (KNOWN_TARGETABLE_FILES.has(file)) {
+    return true;
+  }
+
   if (file === 'README.md'
     || file === 'bin/forge.js'
     || file === 'bin/forge-cmd.js'
@@ -173,7 +265,11 @@ function isKnownTargetablePath(file) {
     // SKILL_TEST_TARGETS in lib/commands/test.js); a skills-only PR stays on the
     // targeted lane instead of the full suite.
     || file.startsWith('skills/')
-    || file.startsWith('.agents/skills/')) {
+    || file.startsWith('.agents/skills/')
+    // Maintainer-only contributor skills (tracked, never published). They map to
+    // the AGENTS.md docs-bleed gate in lib/commands/test.js, so a contributor-docs
+    // PR stays on the targeted lane instead of the full suite.
+    || file.startsWith('.forge/contributor-skills/')) {
     return true;
   }
 
@@ -219,17 +315,28 @@ function buildTestExecutionPlan(projectRoot, execFileSync = defaultExecFileSync,
     sinceUpstream: options.sinceUpstream !== false,
   };
   const changedFiles = getChangedFiles(execFileSync, diffOptions);
-  const affectedTestTargets = getAffectedTestFiles(projectRoot, execFileSync, fs, diffOptions);
+  const affectedTestTargets = getAffectedTestFiles(projectRoot, execFileSync, fs, {
+    ...diffOptions,
+    changedFiles,
+  });
 
   let runFullSuite = false;
   let runTestEnv = false;
   let runE2E = false;
   let runWorkflowTests = includesWorkflowTarget(affectedTestTargets);
   let hasUnmappedFiles = false;
+  let hasFullSuiteRequiredFiles = false;
+  let hasPackageLevelChanges = false;
   const hasUnknownChangedFiles = changedFiles.length === 0 && affectedTestTargets.length === 0;
 
   for (const file of changedFiles) {
+    if (isFullSuiteRequiredFile(file)) {
+      hasFullSuiteRequiredFiles = true;
+      runFullSuite = true;
+    }
+
     if (PACKAGE_LEVEL_PATHS.has(file) || file.startsWith('packages/')) {
+      hasPackageLevelChanges = true;
       runFullSuite = true;
       runTestEnv = true;
       runE2E = true;
@@ -280,8 +387,10 @@ function buildTestExecutionPlan(projectRoot, execFileSync = defaultExecFileSync,
       ? 'changed files could not be resolved safely'
       : hasZeroResolvedTests
         ? 'known changes did not resolve runnable tests'
-      : runFullSuite
+      : hasPackageLevelChanges
         ? 'package-level changes detected'
+      : hasFullSuiteRequiredFiles
+        ? 'shared authority changes require full unit coverage'
         : 'known changes mapped to targeted tests';
 
   return {
@@ -317,31 +426,78 @@ function classifyPushTests(projectRoot, execFileSync = defaultExecFileSync) {
  *
  * @param {string} command Executable name.
  * @param {string[]} args Command arguments.
- * @param {import('node:child_process').SpawnSyncOptions} [options={}] Spawn options.
- * @param {typeof defaultSpawnSync} [spawnSync=defaultSpawnSync] Process runner.
- * @returns {number} Process exit status, or 1 when no status is reported.
+ * @param {import('node:child_process').SpawnOptions} [options={}] Spawn options.
+ * @param {typeof defaultSpawn} [spawn=defaultSpawn] Process runner.
+ * @returns {Promise<number>} Process exit status, or 1 when no status is reported.
  */
-function runCommand(command, args, options = {}, spawnSync = defaultSpawnSync) {
-  const result = spawnSync(command, args, {
-    stdio: 'inherit',
-    shell: isWindows,
-    ...options,
-  });
-
-  if (result.error) {
-    if (result.error.code === 'ETIMEDOUT') {
-      console.error('');
-      console.error('Test lane exceeded its wall-clock ceiling and was terminated.');
-      console.error('A single test likely hung (e.g. a spawned git/bash call that never returns).');
-      console.error('Adjust the ceiling with FORGE_TEST_TIMEOUT_MS. Failing the run instead of');
-      console.error('blocking the push. See issue 8aef79e8.');
-      console.error('');
-      return TIMEOUT_EXIT_CODE;
+function runCommand(command, args, options = {}, spawn = defaultSpawn) {
+  const { processTree, timeout, killSignal: _killSignal, ...spawnOptions } = options;
+  return new Promise((resolve, reject) => {
+    let child;
+    let settled = false;
+    let timer = null;
+    const reservation = processTree?.reserveChild?.({ kind: 'test-lane', label: command }) || null;
+    let registered = false;
+    const release = () => {
+      if (registered) {
+        processTree?.unregisterChild?.(reservation);
+        registered = false;
+      }
+    };
+    const finish = (status) => {
+      if (settled) return;
+      settled = true;
+      release();
+      resolve(status ?? 1);
+    };
+    const fail = (error) => {
+      if (settled) return;
+      if (timer) clearTimeout(timer);
+      if (error?.code === 'ETIMEDOUT') {
+        processTree?.cleanup?.('SIGKILL');
+        console.error('');
+        console.error('Test lane exceeded its wall-clock ceiling and was terminated.');
+        console.error('A single test likely hung (e.g. a spawned git/bash call that never returns).');
+        console.error('Adjust the ceiling with FORGE_TEST_TIMEOUT_MS. Failing the run instead of');
+        console.error('blocking the push. See issue 8aef79e8.');
+        console.error('');
+        finish(TIMEOUT_EXIT_CODE);
+        return;
+      }
+      settled = true;
+      release();
+      reject(error);
+    };
+    try {
+      child = spawn(command, args, { stdio: 'inherit', shell: isWindows, ...spawnOptions });
+    } catch (error) {
+      fail(error);
+      return;
     }
-    throw result.error;
-  }
-
-  return result.status ?? 1;
+    child.once?.('error', fail);
+    child.once?.('close', (status, signal) => {
+      if (timer) clearTimeout(timer);
+      finish(status ?? signalExitCode(signal));
+    });
+    if (reservation && typeof processTree?.registerChild === 'function') {
+      registered = true;
+      if (!processTree.registerChild(reservation, child)) {
+        processTree.abortChild?.(reservation, child);
+        release();
+        fail(new Error('test lane process could not be registered'));
+        return;
+      }
+    }
+    timer = timeout > 0 ? setTimeout(() => {
+      processTree?.cleanup?.('SIGKILL');
+      try { child.kill?.('SIGKILL'); } catch { /* best effort */ }
+      finish(TIMEOUT_EXIT_CODE);
+    }, timeout) : null;
+    if (!child.once) {
+      if (timer) clearTimeout(timer);
+      finish(child.status ?? 1);
+    }
+  });
 }
 
 /**
@@ -351,51 +507,92 @@ function runCommand(command, args, options = {}, spawnSync = defaultSpawnSync) {
  * @param {Object} [deps={}] Runtime dependencies for tests.
  * @returns {number} Exit status for the executed plan.
  */
-function runTestExecutionPlan(plan, deps = {}) {
-  const spawnSync = deps.spawnSync || defaultSpawnSync;
+async function runTestExecutionPlan(plan, deps = {}) {
+  const usesSpawnSyncAdapter = !deps.spawn && typeof deps.spawnSync === 'function';
+  const spawn = deps.spawn || (usesSpawnSyncAdapter ? (...args) => {
+    const child = new EventEmitter();
+    let result;
+    try {
+      result = deps.spawnSync(...args);
+    } catch (error) {
+      process.nextTick(() => child.emit('error', error));
+      return child;
+    }
+    child.pid = result?.pid || process.pid;
+    process.nextTick(() => {
+      if (result?.error) child.emit('error', result.error);
+      else child.emit('close', result?.status ?? 1, result?.signal);
+    });
+    return child;
+  } : defaultSpawn);
   const pkgManager = deps.pkgManager || detectPackageManager();
   const env = deps.env || stripGitHookEnv(process.env);
+  // The injected synchronous runner has already exited when its adapter returns,
+  // so there is no live child to register or reap through host process probes.
+  const processTree = deps.processTree || (usesSpawnSyncAdapter ? {} : createProcessTree({
+    env,
+    platform: deps.platform,
+  }));
+  let signal = null;
+  const removeSignalHandlers = typeof processTree.installSignalHandlers === 'function'
+    ? processTree.installSignalHandlers((received) => {
+      signal = received;
+    })
+    : () => {};
+  const childEnv = typeof processTree.envFor === 'function' ? processTree.envFor(env) : env;
   const bunCommand = deps.bunCommand || env.BUN_EXE || process.env.BUN_EXE || 'bun';
   const label = deps.label || 'tests';
   const timeout = resolveCommandTimeoutMs(env);
-  const laneOptions = { env, killSignal: 'SIGKILL', timeout };
-  // The full-suite fallback gets a larger, validation-aligned budget so a
+  const laneOptions = { env: childEnv, killSignal: 'SIGKILL', timeout, processTree };
+  // The full-suite fallback gets the larger, measurement-derived budget so a
   // healthy-but-slow full run is not failed fast by the targeted-lane ceiling.
-  const fullSuiteOptions = { env, killSignal: 'SIGKILL', timeout: resolveFullSuiteTimeoutMs(env) };
+  const fullSuiteOptions = {
+    env: childEnv,
+    killSignal: 'SIGKILL',
+    timeout: resolveFullSuiteTimeoutMs(env),
+    processTree,
+  };
 
   console.log(`Running ${label} (${pkgManager})...`);
 
   try {
     if (plan.runFullSuite) {
       console.log(`  Mode: full suite (${plan.reason})`);
-      const status = runCommand('node', ['scripts/test-full-suite.js'], fullSuiteOptions, spawnSync);
+       const status = await runCommand('node', ['scripts/test-full-suite.js'], fullSuiteOptions, spawn);
+      if (signal) return signalExitCode(signal);
       if (status !== 0) return status;
     } else if (plan.testTargets.length > 0) {
       console.log(`  Mode: targeted (${plan.testTargets.length} test file${plan.testTargets.length === 1 ? '' : 's'})`);
       const command = pkgManager === 'bun' ? bunCommand : pkgManager;
-      const status = runCommand(command, ['run', 'test', ...plan.testTargets], laneOptions, spawnSync);
+       const status = await runCommand(command, ['run', 'test', ...plan.testTargets], laneOptions, spawn);
+      if (signal) return signalExitCode(signal);
       if (status !== 0) return status;
     }
 
     if (plan.runE2E) {
       console.log('  Extra: running affected e2e tests');
-      const status = runCommand(bunCommand, ['test', '--timeout', '15000', 'test/e2e/'], laneOptions, spawnSync);
+       const status = await runCommand(bunCommand, ['test', '--timeout', '15000', 'test/e2e/'], laneOptions, spawn);
+      if (signal) return signalExitCode(signal);
       if (status !== 0) return status;
     }
 
     if (!plan.runFullSuite && plan.runTestEnv) {
       console.log('  Extra: running affected edge-case tests');
-      const status = runCommand(bunCommand, ['test', '--timeout', '15000', 'test-env/'], laneOptions, spawnSync);
+       const status = await runCommand(bunCommand, ['test', '--timeout', '15000', 'test-env/'], laneOptions, spawn);
+      if (signal) return signalExitCode(signal);
       if (status !== 0) return status;
     }
 
     console.log('Relevant tests passed');
-    return 0;
+    return signal ? signalExitCode(signal) : 0;
   } catch (error) {
     console.error('');
     console.error(`Failed to run ${label}: ${error.message}`);
     console.error('');
-    return 1;
+    return signal ? signalExitCode(signal) : 1;
+  } finally {
+    removeSignalHandlers();
+    processTree.cleanup?.(signal ? 'SIGKILL' : 'SIGTERM');
   }
 }
 
@@ -406,7 +603,15 @@ function runTestExecutionPlan(plan, deps = {}) {
  * @param {Object} [deps={}] Runtime dependencies for tests.
  * @returns {number} Exit status for pre-push tests.
  */
-function runPrePushTests(projectRoot = process.cwd(), deps = {}) {
+async function runPrePushTests(projectRoot = process.cwd(), deps = {}) {
+  if (isQuickPushLane(deps.env || process.env)) {
+    console.log('');
+    console.log('  quick lane: tests skipped locally — CI runs the full matrix');
+    console.log('  Run `forge push` (no --quick) to test before merge.');
+    console.log('');
+    return 0;
+  }
+
   const execFileSync = deps.execFileSync || defaultExecFileSync;
   const plan = classifyPushTests(projectRoot, execFileSync);
   return runTestExecutionPlan(plan, { ...deps, label: 'pre-push tests' });
@@ -419,26 +624,35 @@ function runPrePushTests(projectRoot = process.cwd(), deps = {}) {
  * @param {Object} [deps={}] Runtime dependencies for tests.
  * @returns {number} Exit status for local validation tests.
  */
-function runLocalValidationTests(projectRoot = process.cwd(), deps = {}) {
+async function runLocalValidationTests(projectRoot = process.cwd(), deps = {}) {
   const execFileSync = deps.execFileSync || defaultExecFileSync;
   const plan = buildTestExecutionPlan(projectRoot, execFileSync, { sinceUpstream: true });
   return runTestExecutionPlan(plan, { ...deps, label: 'local validation tests' });
 }
 
 if (require.main === module) {
-  const exitCode = process.argv.includes('--validate')
-    ? runLocalValidationTests()
-    : runPrePushTests();
-  process.exit(exitCode);
+  (async () => {
+    const exitCode = process.argv.includes('--validate')
+      ? await runLocalValidationTests()
+      : await runPrePushTests();
+    process.exit(exitCode);
+  })().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
 }
 
 module.exports = {
   ALWAYS_RUN_RISK_TEST_TARGETS,
   DEFAULT_FULL_SUITE_TIMEOUT_MS,
   DEFAULT_TEST_COMMAND_TIMEOUT_MS,
+  OBSERVED_FULL_SUITE_RUNTIME_MS,
+  QUICK_LANE_ENV_VAR,
+  QUICK_LANE_VALUE,
   buildTestExecutionPlan,
   classifyPushTests,
   detectPackageManager,
+  isQuickPushLane,
   resolveCommandTimeoutMs,
   resolveFullSuiteTimeoutMs,
   runLocalValidationTests,

package/skills/coverage.json

@@ -58,6 +58,7 @@
     "team": { "exempt": "team skill pending (plan §3.2 B: new `team` skill)" },
 
     "setup": "setup",
+    "github": "setup",
     "init": "setup",
     "upgrade": "setup",
     "doctor": "setup",

package/skills/review/SKILL.md

@@ -1,17 +1,10 @@
 ---
 name: review
+invocation: user
 description: >
-  Forge REVIEW stage — drives an already-open PR to all-green by resolving EVERY piece of
-  feedback: failing GitHub Actions / CI checks, Greptile and CodeRabbit inline comments and
-  summaries, and the SonarCloud quality gate. It fixes the code, replies to each thread and
-  marks it resolved until checks pass, then runs the pre-merge doc gate and hands the PR off
-  for MANUAL merge — never runs `gh pr merge`. Use whenever a PR has review feedback or red
-  checks: "address the review comments on PR #123", "the bots flagged issues / Greptile score
-  is low", "fix the failing checks and resolve the threads", "CodeRabbit and SonarCloud left
-  comments", "get my PR merge-ready". This MUTATING feedback-resolution stage is distinct from
-  shepherd (only WATCHES an open PR, changes nothing), verify (POST-merge CI health check +
-  closing issues), ship (pushes the branch + opens the PR), validate (PRE-PR local
-  type/lint/test/security), and sonarcloud / sonarcloud-analysis (only QUERY SonarCloud data).
+  Drive an already-open PR's feedback and failing checks to all-green, resolve every thread,
+  run the pre-merge doc gate, then stop for manual merge. Use only when the user asks to
+  address PR feedback or checks; never merges or substitutes for Shepherd monitoring.
 allowed-tools: Bash, Read, Edit, Grep, Glob
 next: verify
 terminal: false
@@ -35,6 +28,8 @@ This skill handles ALL issues that arise after creating a pull request.
 
 ## What This Skill Does
 
+Before reviewing a diff, read `CODING_STANDARDS.md` from the repository root and apply every relevant rule.
+
 ### Step 1: Fetch Complete PR Status
 ```bash
 # Get full PR details including all checks

package/skills/review/evals/scorecard.json

@@ -3,9 +3,9 @@
   "fixtures": "present",
   "static": {
     "token_cost": {
-      "desc_chars": 988,
-      "body_lines": 476,
-      "score": 4
+      "desc_chars": 261,
+      "body_lines": 478,
+      "score": 39
     },
     "caps": {
       "desc_within": true,
@@ -37,5 +37,5 @@
     "variance": null,
     "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
   },
-  "composite": 71
+  "composite": 82
 }

package/skills/rollback/SKILL.md

@@ -1,17 +1,10 @@
 ---
 name: rollback
+invocation: user
 description: >
-  Safely revert or undo a change that is already committed or shipped, using non-destructive
-  `git revert` (never `reset --hard`, `push --force`, or `clean`). Drives the interactive
-  `bunx forge rollback` menu: undo the last commit, revert a commit by hash, revert a merged
-  PR (git revert -m 1), restore individual files to a prior version, revert a commit range, or
-  dry-run/preview first. Use when the user says roll back, revert, undo, back out, or restore
-  — e.g. "undo the last commit", "undo that change, the approach was wrong", "back out PR
-  #123", "revert the merge commit", "restore src/auth.js to before my last commit", or when a
-  shipped/merged change broke something and must be pulled back. Do NOT use for: replying to
-  or fixing PR review feedback (review), monitoring an open PR's checks toward merge
-  (shepherd), the post-merge CI health check on master (verify), pushing a branch or opening a
-  PR (ship), or ordinary issue status/field edits (issue-basics).
+  Safely undo committed or shipped changes with non-destructive git revert or restore. Use
+  only when the user explicitly asks to roll back, revert, undo, back out, or restore; never
+  reset hard, force-push, or substitute for PR review, monitoring, or issue status work.
 allowed-tools: Bash, Read, Edit, Grep, Glob
 terminal: true
 ---

package/skills/rollback/evals/scorecard.json

@@ -3,9 +3,9 @@
   "fixtures": "present",
   "static": {
     "token_cost": {
-      "desc_chars": 965,
+      "desc_chars": 266,
       "body_lines": 95,
-      "score": 43
+      "score": 78
     },
     "caps": {
       "desc_within": true,
@@ -37,5 +37,5 @@
     "variance": null,
     "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
   },
-  "composite": 83
+  "composite": 93
 }

package/skills/setup/SKILL.md

@@ -30,6 +30,24 @@ forge setup --path <dir> --dry-run                   # preview against another d
 
 `forge setup` is **interactive by default**. In any automated/agent context pass `--yes` (or `--non-interactive`) so it never blocks on a prompt.
 
+# Optional GitHub accounts per clone
+
+Only when the user opts into multiple accounts: sign in once per account with
+native `gh auth login`, then select inside each intended clone:
+
+```bash
+forge github use <login>       # verify stored account/access before binding this clone
+forge github status           # safe identity and transport diagnostics; --json supported
+forge github run -- <harness>  # explicitly give a trusted child the selected GitHub identity
+forge github unset            # remove this binding, not stored logins
+```
+
+Ordinary setup stays unbound. Never paste or persist tokens, automatically log in
+or switch accounts, or change Git author/remotes/SSH/helper configuration.
+Git transport is separate; HTTPS using `gh auth git-credential` can inherit the
+explicit child session's account. See the repository reference guide
+`docs/reference/github-accounts.md` for concurrent sessions and recovery.
+
 # Initialize a fresh repo
 
 ```bash