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

package/scripts/test.js

@@ -4,15 +4,27 @@
  *
  * 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,
 } = require('../lib/commands/test');
+const { createProcessTree, signalExitCode } = require('./process-tree');
 
 const PACKAGE_LEVEL_PATHS = new Set([
   'package.json',
@@ -64,6 +76,21 @@ const DEFAULT_FULL_SUITE_TIMEOUT_MS = 10 * 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.
  *
@@ -134,9 +161,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];
     }
   }
@@ -156,6 +185,8 @@ function isKnownTargetablePath(file) {
 
   if (file === 'README.md'
     || file === 'bin/forge.js'
+    || file === 'bin/forge-cmd.js'
+    || file === 'bin/forge-preflight.js'
     || file === 'QUICKSTART.md'
     || file === 'CHANGELOG.md'
     || file === 'AGENTS.md'
@@ -166,7 +197,12 @@ function isKnownTargetablePath(file) {
     || file.startsWith('docs/guides/')
     || file.startsWith('docs/plans/')
     || file.startsWith('docs/reference/')
-    || file.startsWith('docs/work/')) {
+    || file.startsWith('docs/work/')
+    // Skill sources + their committed mirror map to the skill suite (see
+    // 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/')) {
     return true;
   }
 
@@ -310,31 +346,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);
+    }
+  });
 }
 
 /**
@@ -344,51 +427,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 };
+  const laneOptions = { env: childEnv, killSignal: 'SIGKILL', timeout, processTree };
   // The full-suite fallback gets a larger, validation-aligned 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');
   }
 }
 
@@ -399,7 +523,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' });
@@ -412,26 +544,34 @@ 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,
+  QUICK_LANE_ENV_VAR,
+  QUICK_LANE_VALUE,
   buildTestExecutionPlan,
   classifyPushTests,
   detectPackageManager,
+  isQuickPushLane,
   resolveCommandTimeoutMs,
   resolveFullSuiteTimeoutMs,
   runLocalValidationTests,

package/skills/claim-safety/SKILL.md

@@ -14,10 +14,14 @@ description: >
   and NOT for read-only selecting or ranking the next ready issue without claiming (that is
   triage-ready).
 allowed-tools: Read, Bash(forge:*)
+next: dev
+terminal: false
 ---
 
 # Claim safety — claim, then prove you own the lease
 
+> **Chain:** once you have PROVEN the lease (`forge issue owns <id>` exits 0), continue to `dev` to work the issue (`smith` proceeds into plan/dev after this proof). Usable standalone whenever ownership is in question.
+
 Claiming is not owning. The Forge kernel keys a claim's idempotency on
 `claim.create:<issue_id>:<actor>`, so a **same-key duplicate replay returns
 `ok:true`** echoing the *current* call's `claim_id`. A genuine cross-actor

package/skills/claim-safety/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "claim-safety",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 995,
+      "body_lines": 88,
+      "score": 43
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/skills/coverage.json

@@ -0,0 +1,83 @@
+{
+  "version": 1,
+  "description": "Command -> owning-skill coverage map (plan 2026-07-20-next-phase-plan.md §3.3). Every registered user-facing command MUST map to an existing skill OR carry an explicit { exempt: <reason> }. Enforced by the coverage gate (lib/skill-eval.js evaluateCoverage, surfaced by `forge skill coverage`/`forge skill scores`, gated in test/skill-eval.test.js). Exempts reference the pending skill from plan §3.2 and are tightened as those skills land.",
+  "commands": {
+    "plan": "plan",
+    "dev": "dev",
+    "validate": "validate",
+    "ship": "ship",
+    "shepherd": "shepherd",
+    "status": "status",
+    "prime": "status",
+    "orient": "hermes-forge",
+    "recap": "hermes-forge",
+    "remember": "memory",
+    "recall": "memory",
+    "memory": "memory",
+    "ready": "triage-ready",
+    "blocked": "triage-ready",
+    "claim": "claim-safety",
+    "claims": "claim-safety",
+    "issue": "issue-basics",
+    "issues": "issue-basics",
+    "create": "issue-basics",
+    "close": "issue-basics",
+    "comment": "issue-basics",
+    "show": "issue-basics",
+    "update": "issue-basics",
+    "list": "issue-basics",
+    "skill": "using-forge",
+
+    "worktree": "worktree",
+    "clean": "worktree",
+    "orphans": { "exempt": "full ownership (command-name routing + `forge issue orphans` guidance in the issue-basics body) pending — issue e1e33cf8; issue-basics does not yet document it, so mapping now would be a hollow claim" },
+    "rollback": "rollback",
+    "review": "review",
+    "verify": "verify",
+    "check": { "exempt": "legacy alias for `validate` (renamed in PR #50) — bin/forge-cmd.js VALID_COMMANDS only; owned by the `validate` skill" },
+    "docs": { "exempt": "bin/forge.js-direct; AGENTS.md/docs management — owning skill pending (coverage pass, plan §3.2)" },
+    "reset": "setup",
+    "reinstall": "setup",
+
+    "gate": "gates",
+    "control": "gates",
+    "doc-gate": "gates",
+
+    "adapter": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "add": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "new": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "audit": { "exempt": "extensions skill pending (plan §3.2 B: new `extensions` skill)" },
+    "role": { "exempt": "extensions skill pending — role/skill binding (plan §3.2 B)" },
+
+    "export": "portability",
+    "migrate": "portability",
+    "sync": { "exempt": "cloud-native external-platform sync (ADR-0004); a local no-op with no value until a server backend is configured — skill deferred (issue 666f4b4c)" },
+
+    "inbox": { "exempt": "team skill pending (plan §3.2 B: new `team` skill)" },
+    "serve": { "exempt": "team skill pending (plan §3.2 B: new `team` skill)" },
+    "team": { "exempt": "team skill pending (plan §3.2 B: new `team` skill)" },
+
+    "setup": "setup",
+    "init": "setup",
+    "upgrade": "setup",
+    "doctor": "setup",
+    "hooks": "setup",
+    "recommend": "setup",
+
+    "push": { "exempt": "ship skill push/preflight extension pending (plan §3.2 B)" },
+    "preflight": { "exempt": "ship skill push/preflight extension pending (plan §3.2 B)" },
+    "pr": { "exempt": "ship/shepherd PR-lifecycle extension pending (plan §3.2)" },
+    "merge": { "exempt": "ship/shepherd PR-lifecycle extension pending (plan §3.2)" },
+
+    "patch": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "stage": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "explain": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "options": { "exempt": "kernel skill fold pending (plan §3.2 C: fold into `kernel`)" },
+    "insights": { "exempt": "kernel skill fold pending — kernel evidence inspection (plan §3.2 C)" },
+
+    "lint": { "exempt": "internal quality plumbing; skill assignment pending (coverage pass)" },
+    "release": { "exempt": "internal release plumbing; skill assignment pending (coverage pass)" },
+    "test": { "exempt": "internal test-runner plumbing; skill assignment pending (coverage pass)" },
+    "stale": { "exempt": "internal stale-detection plumbing; skill assignment pending (coverage pass)" }
+  }
+}

package/skills/dev/SKILL.md

@@ -13,12 +13,16 @@ description: >
   opening the PR (ship), for addressing PR review feedback (review), or for orchestrating
   several stages / taking an issue end-to-end to a merged PR (smith).
 allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+next: validate
+terminal: false
 ---
 
 Implement each task from the /plan task list using a subagent-driven loop: implementer → spec compliance reviewer → code quality reviewer per task.
 
 # Dev
 
+> **Chain (HARD-GATE):** the ONLY skill you invoke after `dev` is `validate`. Never open a PR straight from `dev`.
+
 This skill reads the task list created by `/plan` and implements each task using a three-stage subagent loop. TDD is enforced inside each implementer subagent.
 
 ## Usage

package/skills/dev/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "dev",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 962,
+      "body_lines": 328,
+      "score": 20
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 76
+}

package/skills/gates/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: gates
+description: >
+  Toggle Forge's workflow gates and rails — strong-but-toggleable enforcement. `forge gate
+  enable|disable <gate-id>` flips `workflow.gates.<id>.enabled` in `.forge/config.yaml`; the
+  installed git hooks read resolved config at run time, so disabling a rail makes them
+  genuinely inert. `forge gate approve|reject <issue> <gate>` records durable human-gate
+  approval events; `forge gate status`/`check` query them; `forge control <id>
+  <mandatory|optional|permission>` sets tri-state DECLARED intent (writes the same `enabled`
+  field — no independent runtime enforcement). Use when the user says "disable the gate",
+  "turn off TDD enforcement", "the tdd intent rail is blocking me", "toggle or enable a
+  gate", "loosen enforcement", or "approve a human gate". Common default-ON toggleable rails:
+  `rail.tdd_intent`, `rail.kernel_tracking`, `rail.auto_shepherd` — e.g. `forge gate disable
+  rail.tdd_intent`. NOT for addressing PR review feedback (review), NOT the status snapshot
+  of work in flight (status).
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Forge's gates and rails are **default-strong but toggleable**. The `gates` skill is how you flip one off (or back on), record a human-gate approval, and see enforcement state. The stored truth is one field — `workflow.gates.<id>.enabled` — and the installed hooks read the resolved config at run time, so a disabled rail is genuinely inert, not cosmetically off.
+
+# Toggling gates and rails
+
+## When to use
+
+- "Disable the gate", "turn off TDD enforcement", "the tdd intent rail is blocking me".
+- "Toggle / enable a gate", "loosen enforcement for this repo".
+- "Approve a human gate" (record a durable approval event on an issue).
+
+## Toggle a gate or rail (the enforcement switch)
+
+```bash
+forge gate disable <gate-id>     # set workflow.gates.<id>.enabled = false in .forge/config.yaml
+forge gate enable  <gate-id>     # set it back to true
+```
+
+An unknown gate id — or disabling a **locked** gate — errors **before** anything is written, never mid-run. Because the hooks resolve config at run time, the flip takes effect immediately with no reinstall.
+
+### Common rails (default-ON, toggleable)
+
+| Rail | What it enforces | Turn off with |
+| --- | --- | --- |
+| `rail.tdd_intent` | Pre-commit TDD gate (source changed ⇒ tests changed). The `minimal` adoption profile ships it off. | `forge gate disable rail.tdd_intent` |
+| `rail.kernel_tracking` | "File every issue" — nothing discussed goes missing. | `forge gate disable rail.kernel_tracking` |
+| `rail.auto_shepherd` | The autonomous PR-shepherd daemon fire. | `forge gate disable rail.auto_shepherd` |
+
+The `gate.*` and `rail.*` id namespaces are disjoint, so `forge gate enable|disable` governs both through one flat surface.
+
+## Human-gate approval events
+
+```bash
+forge gate approve <issue-id> <gate-id>                     # record a durable gate.approved event
+forge gate reject  <issue-id> <gate-id>                     # record gate.rejected
+forge gate status  <issue-id>                               # list recorded events for that issue (resume-safe)
+forge gate check   <issue-id> <gate-id>                     # exit 0 iff gate DISABLED or an approval exists on that issue
+```
+
+`check` is the reusable enforcement primitive a stage skill calls: it passes when the gate is disabled or an approval event has been recorded for that specific issue id (approvals are issue-scoped, so pass the same `<issue-id>` you approved against). Events are durable on the issue, so they survive a compaction or crash.
+
+## Tri-state control (declared intent)
+
+```bash
+forge control <gate-id|rail-id> <mandatory|optional|permission>
+forge control status [--json]
+```
+
+`forge control` sets the **declared intent** vocabulary and writes the **same** `enabled` field that `forge gate` writes — there is deliberately no parallel key. It is a view/intent layer: today no runtime consumer denies purely on a control flag (MCP/rules/skills are presence-only and refused). For actually turning enforcement off, use `forge gate disable`.
+
+## The doc-update gate
+
+```bash
+forge gate doc <detect|check|init|...>     # = forge doc-gate (run `forge doc-gate --help`)
+```
+
+The doc-update gate folds under this noun as `forge gate doc`; bare `forge doc-gate` stays as a back-compat alias.
+
+## Adjacent skills
+
+- Addressing PR review feedback / resolving threads → `review`.
+- The snapshot of where the project stands and what's in flight → `status`.

package/skills/gates/evals/evals.json

@@ -0,0 +1,38 @@
+[
+  {
+    "query": "Disable the tdd gate for this repo.",
+    "should_trigger": true
+  },
+  {
+    "query": "Turn off TDD enforcement — the tdd intent rail is blocking my commit.",
+    "should_trigger": true
+  },
+  {
+    "query": "Toggle the kernel tracking rail off for now.",
+    "should_trigger": true
+  },
+  {
+    "query": "Enable a gate that I disabled earlier and loosen enforcement.",
+    "should_trigger": true
+  },
+  {
+    "query": "Approve the human gate on this issue so the stage can proceed.",
+    "should_trigger": true
+  },
+  {
+    "query": "Disable the auto shepherd rail so no PR daemon fires.",
+    "should_trigger": true
+  },
+  {
+    "query": "Address the CodeRabbit review feedback and resolve the threads.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow and what work is in flight right now?",
+    "should_trigger": false
+  },
+  {
+    "query": "Run the tests and lint before I push.",
+    "should_trigger": false
+  }
+]