forge-workflow 0.1.0-beta.4 → 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];
     }
   }
@@ -317,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);
+    }
+  });
 }
 
 /**
@@ -351,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');
   }
 }
 
@@ -406,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' });
@@ -419,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/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

package/skills/review/evals/scorecard.json

@@ -3,9 +3,9 @@
   "fixtures": "present",
   "static": {
     "token_cost": {
-      "desc_chars": 988,
+      "desc_chars": 261,
       "body_lines": 476,
-      "score": 4
+      "score": 40
     },
     "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/shepherd/SKILL.md

@@ -6,8 +6,8 @@ description: >
   open PR, converges CI check state into kernel verdicts, re-runs flaky required
   checks, reaps orphan watchers, and self-retires when no PRs remain; one-shot
   passes (forge shepherd <pr>) exist for a single bounded check. Use when a PR was
-  just opened or shipped; when a session starts with open PRs (start the daemon in
-  a background shell — the singleton lease makes a duplicate start a safe no-op);
+  just opened or shipped; when a session starts with open PRs (Forge automatically
+  wakes the singleton; the lease makes a duplicate start a safe no-op);
   when the user asks "why isn't my PR merging", "what's
   blocking the PR", "is the PR ready", "did a check fail / go red"; when asked to
   "keep watching / keep an eye on / babysit my PRs"; or to read PR verdicts
@@ -34,15 +34,18 @@ Forge owns your open PRs. A singleton daemon converges every open PR toward merg
 - User asks about **one PR, right now** ("is #212 ready?", "why is this blocked?") → **one-shot** (`forge shepherd <pr> --pull`).
 - Anything **ongoing** — "keep", "until it merges", "watch", "babysit", multiple PRs, or a session that starts with PRs already open → **ensure the daemon is running**.
 
-## Session-start ritual
+## Automatic attachment
 
-When a session starts and the repo has open PRs, ensure the daemon is running:
+Forge wakes the singleton after a successful supported session start, every
+successful push, and every successful non-dry-run ship. Push does not require a
+locally resolved PR number; the daemon enumerates all open and draft PRs itself.
+Ordinary commands do not launch it.
 
-```bash
-forge shepherd daemon    # start it in the HARNESS BACKGROUND SHELL
-```
-
-The daemon is a **repo singleton** guarded by an O_EXCL lease, so you do NOT need a liveness check first — a second start when one is already running simply exits (the lease is already held). Start it in the harness background shell (Claude Code / Codex background-shell) so it is session-scoped and reaped with the session. NEVER launch a detached spawn from the agent: the detached path is Forge's bare-CLI fallback only. (Automatic per-command launch and a `forge prime` daemon-liveness line are planned follow-ups — W-S4c/W-S5 — not yet wired; until then you start the daemon explicitly as above.)
+The daemon is a **repo singleton** guarded by an O_EXCL lease, so no liveness
+check is needed first. Forge prefers a supplied harness background shell; its
+bare-CLI detached fallback launches from the stable common repository root, not
+the current disposable worktree. Agents never launch a detached spawn directly.
+(A `forge prime` daemon-liveness line remains the separate W-S5 follow-up.)
 
 ## Reading verdicts (the common case)
 
@@ -69,8 +72,8 @@ forge shepherd events <pr> --since <seq>   # only the new events since sequence
 
 | Situation | Command |
 | --- | --- |
-| PR just opened / shipped | ensure `forge shepherd daemon` running |
-| Session starts, open PRs exist, daemon dead | `forge shepherd daemon` (background shell) |
+| PR just opened / shipped | automatic singleton wake; read with `forge shepherd <pr> --pull` |
+| Session starts with open PRs | automatic singleton wake |
 | "Why isn't my PR merging / what's blocking it" | `forge shepherd <pr> --pull` |
 | "Is the PR ready?" | `forge shepherd <pr> --pull` (read `MERGE_READY`) |
 | "A check failed / went red" | `forge shepherd <pr> --pull --json` (read `failures[]`) |
@@ -95,11 +98,14 @@ forge shepherd events <pr> --since <seq>   # only the new events since sequence
 ## Kill-switches
 
 ```bash
-FORGE_SHEPHERD_DISABLE=1        # env: makes the shepherd trigger inert (once the auto-fire wiring lands, W-S4c)
-forge gate disable rail.auto_shepherd   # config gate honored by the trigger + ship/push arming
+FORGE_SHEPHERD_DISABLE=1              # env: makes automatic firing inert
+forge gate disable rail.auto_shepherd # config gate honored by every automatic seam
 ```
 
-Both leave the manual `forge shepherd` surface usable; they only stop the automatic daemon fire.
+CI/test (`NODE_ENV=test`, `BUN_ENV=test`, `CI`, `GITHUB_ACTIONS`, or
+`GITLAB_CI`), dry-run, uninitialized repositories, and disabled paths return
+before lease, Kernel-state, or process work. All leave the manual
+`forge shepherd` surface usable; they only stop automatic daemon fire.
 
 ## State
 

package/skills/shepherd/evals/scorecard.json

@@ -3,8 +3,8 @@
   "fixtures": "present",
   "static": {
     "token_cost": {
-      "desc_chars": 997,
-      "body_lines": 86,
+      "desc_chars": 987,
+      "body_lines": 92,
       "score": 43
     },
     "caps": {

package/skills/ship/SKILL.md

@@ -1,18 +1,10 @@
 ---
 name: ship
+invocation: user
 description: >
-  Forge SHIP stage: push the validated feature branch and open a PR populated from the
-  project's OWN PR template (design-doc link, Forge issue IDs, real test/commit data), then
-  hand off for MANUAL merge; never merges or auto-merges. Use once /validate passes and you
-  want a PR on the board. Triggers: "ship it", "ship this branch", "open the PR", "push and
-  open a PR", "gh pr create", "checks passed, now cut the PR". Runs branch-freshness +
-  parallel-PR merge-sim checks, force-with-lease push, records the ship->review handoff, then
-  stops. One stage only; not for: the whole plan->dev->validate->ship->review pipeline or
-  drive-to-done (smith); type-check/lint/tests/security first (validate); addressing PR
-  comments or resolving Greptile/SonarCloud/CodeRabbit threads on an existing PR (review);
-  babysitting an open PR toward merge (shepherd); post-merge CI health check + closing issues
-  (verify); reverting an already-shipped change (rollback). If the PR already exists, this is
-  not the skill.
+  Push a validated feature branch and open its PR from the project's template, then stop for
+  manual merge. Use only when the user asks to ship or open the PR after validation; never
+  merges, auto-merges, reviews an existing PR, or replaces end-to-end Smith.
 allowed-tools: Bash, Read, Edit, Grep, Glob
 next: review
 terminal: false

package/skills/ship/evals/scorecard.json

@@ -3,9 +3,9 @@
   "fixtures": "present",
   "static": {
     "token_cost": {
-      "desc_chars": 993,
+      "desc_chars": 254,
       "body_lines": 237,
-      "score": 28
+      "score": 64
     },
     "caps": {
       "desc_within": true,
@@ -37,5 +37,5 @@
     "variance": null,
     "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
   },
-  "composite": 78
+  "composite": 89
 }

package/skills/worktree/SKILL.md

@@ -71,7 +71,12 @@ forge clean                      # remove worktrees whose branches merged; FF th
 forge clean --dry-run            # show what would be removed, change nothing
 ```
 
-`forge clean` is **squash-aware** — it detects branches that merged via squash, not just fast-forward merges.
+`forge clean` is **squash-aware** — it detects branches that merged via squash, not just fast-forward merges. Removing a merged worktree also closes the kernel issue the branch was linked to, citing the merge as evidence.
+
+Two things it will never touch, because closing an issue is irreversible (`done` is terminal):
+
+- **A branch with no commits of its own.** A freshly created worktree points at a default-branch commit, which git alone reads as "merged". That is unstarted work — it is kept, and its issue stays open.
+- **A worktree it skipped.** Uncommitted changes hold a worktree back, and a held-back worktree never has its issue closed.
 
 ### `forge clean` footguns
 

package/skills/worktree/evals/scorecard.json

@@ -4,8 +4,8 @@
   "static": {
     "token_cost": {
       "desc_chars": 1013,
-      "body_lines": 70,
-      "score": 44
+      "body_lines": 75,
+      "score": 43
     },
     "caps": {
       "desc_within": true,