mandrel 2.66.0 → 2.68.0

package/.agents/agents/acceptance-critic.md

@@ -98,8 +98,8 @@ For each acceptance item:
 
 ## Verdict schema (MUST)
 
-Write **one** verdict file under `temp/` (e.g.
-`temp/acceptance-verdict-<storyId>-r<round>.json`) conforming to
+Write **one** verdict file under `temp/scratch/story-<storyId>/` (e.g.
+`temp/scratch/story-<storyId>/acceptance-verdict-r<round>.json`) conforming to
 [`acceptance-eval-verdict.schema.json`](../schemas/acceptance-eval-verdict.schema.json):
 one `criteria[]` record per acceptance item, in acceptance-array order, with
 `index` being the criterion's position in that array.

package/.agents/agents/story-worker.md

@@ -87,14 +87,16 @@ names. A null digest path means no docs mandate.
 
 `single-story-close.js` runs the canonical close-validation chain
 (**typecheck, lint, test, format, maintainability, coverage, crap**) and is
-the authoritative gate — do not pre-run it. The **one** exception is the
-full suite: after the self-eval loop's last fix commit, run it once in
+the authoritative gate — do not pre-run it. Two exceptions, both run in
 `<workCwd>` exactly as
-[`deliver-digest.md`](../workflows/helpers/deliver-digest.md) § 5 states it —
-that section is the rule's only home, so read the invocation there rather
-than from a copy here.
-
-If the suite outruns the host's sync Bash ceiling, dispatch it in the
+[`deliver-digest.md`](../workflows/helpers/deliver-digest.md) § 5 states them:
+the **blocking** lint + quality-preview preflight, then the one credited run
+(the coverage capture or the test depositor, as § 5 picks), once after the
+self-eval loop's last fix commit, then the `--seat-missing` baseline seat
+before push. That section is their only home, so read the invocations there
+rather than from a copy here.
+
+If the run outruns the host's sync Bash ceiling, dispatch it in the
 **background**: its completion re-invokes you. Never spawn a task to poll or
 `sleep`-loop against it; a waiter with a wrong condition outlives the agent.
 An exit code is never evidence a gate did work — its **output** is. Redraft
@@ -142,11 +144,13 @@ the remote ref moved — then return: a turn that ends unpushed reads as
 unfinished work. The orchestrator runs
 `single-story-close.js` in its own session, serialized against your
 siblings. Do not open the PR, flip `agent::done`, or spawn a child to
-close for you. If the push fails, take the blocked path above.
+close for you. If the push fails, take the blocked path above. After
+the push, compute the held review and fix a CRITICAL before returning
+([`deliver-reference.md`](../workflows/helpers/deliver-reference.md) § Held review).
 
 ## Return contract — the hand-off report
 
 A short, literal hand-off your caller can act on: Story id, `workCwd`,
-branch, pushed head SHA, self-eval verdict, `verify[]` evidence. Say the
-branch is pushed and unclosed. Never hand-compose a terminal envelope —
-inventing one makes an unlanded Story look landed.
+branch, pushed head SHA, self-eval verdict, `verify[]` evidence, review
+tally. Say the branch is pushed and unclosed. Never hand-compose a
+terminal envelope — inventing one makes an unlanded Story look landed.

package/.agents/docs/agentrc-reference.json

@@ -87,7 +87,8 @@
         "orchestrationLogs": true,
         "validationEvidence": true,
         "auditResults": true,
-        "planDirs": true
+        "planDirs": true,
+        "scratch": true
       }
     },
     "deliverRunner": {
@@ -124,7 +125,9 @@
               "functions": 90
             }
           },
-          "coveragePath": "coverage/coverage-final.json"
+          "coveragePath": "coverage/coverage-final.json",
+          "captureScope": "full",
+          "timeoutMs": 600000
         },
         "crap": {
           "enabled": true,

package/.agents/docs/configuration.md

@@ -136,16 +136,17 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `execution` | No | `object` | — | Serialization of the full-suite spawns delivery drives. |
-| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
+| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
 | `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
 | `docsFreshness.paths` | No | `array<string>` | `["README.md"]` | Repo-relative documentation paths the audit-documentation lens adds to its target set. |
-| `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path. |
+| `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so unrecognized files under tempRoot are reported with their size and left alone (`/clean-temp` is the operator path for them). signals.ndjson is never purged by any path. |
 | `tempRetention.enabled` | No | `boolean` | `true` | Master switch. Default true — reclaiming a landed Story's gate transcripts and validation evidence is the behaviour, and this knob turns it off. When false every purge path is a reported no-op. |
 | `tempRetention.classes` | No | `object` | — | Per-class opt-out. Each defaults to true; set one false to keep that family while the rest are purged. |
 | `tempRetention.classes.orchestrationLogs` | No | `boolean` | `true` | <tempRoot>/orchestration/*.log — close gate transcripts and terse-result detail dumps. |
 | `tempRetention.classes.validationEvidence` | No | `boolean` | `true` | Per-Story validation-evidence.json, lifecycle.ndjson, and manifest.md under the standalone and per-run story trees. |
 | `tempRetention.classes.auditResults` | No | `boolean` | `true` | <tempRoot>/audits/ — audit lens reports. |
 | `tempRetention.classes.planDirs` | No | `boolean` | `true` | <tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded. |
+| `tempRetention.classes.scratch` | No | `boolean` | `true` | <tempRoot>/scratch/ — agent-authored scratch. `scratch/story-<id>/` is purged when that Story lands; any other `scratch/` entry is age-floored. |
 | `deliverRunner` | No | `object` | — | Bounded-concurrency knob for the /mandrel-deliver fan-out. |
 | `deliverRunner.concurrencyCap` | No | `integer` | `3` | Maximum ready Stories dispatched by /mandrel-deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff. |
 | `deliverRunner.footprintGuard` | No | `"enforce"` \| `"advisory"` | `"enforce"` | How a file-footprint collision affects dispatch. 'enforce' (default, and the behaviour to keep unless you have a reason) withholds a Story whose footprint races a peer admitted this beat or one still in flight — the guard encodes delivery-time-only knowledge (open implementation windows, foreign leases, ground that moved since planning) that no depends_on edge can carry. 'advisory' still DETECTS every collision and reports each would-be withhold in the tick envelope, but lets dispatch follow the declared depends_on edges alone — a deliberate throughput trade for a run whose ordering is fully declared. See stories-wave-tick.js and helpers/deliver-reference.md. |
@@ -168,6 +169,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
 | `quality.gates.coverage.floors` | No | `object<map>` | `{"*":{"lines":90,"branches":85,"functions":90}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
 | `quality.gates.coverage.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer. |
 | `quality.gates.coverage.coveragePath` | No | `string` | `"coverage/coverage-final.json"` | Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. |
+| `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | What coverage-capture runs. `full` (default) runs `npm run test:coverage`. `affected` runs the consumer-owned `npm run test:coverage:affected` with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite. |
+| `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure. |
 | `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
 | `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
 | `quality.gates.crap.baselinePath` | No | `string` | `"baselines/crap.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
@@ -364,6 +367,39 @@ A config still carrying the retired key is a hard validation failure; the
   Extend the list-valued gate keys with the deep-merge extender form (see
   [How to extend](#how-to-extend)).
 
+#### `delivery.quality.gates.coverage.captureScope` — delta refresh
+
+Under `captureScope: "affected"`, a capture stamp records the commit it
+measured. When close's base-sync merges `main` into the Story branch, the
+next capture re-measures only the merged commits' tests instead of the
+Story's whole affected scope: it runs `npm run test:coverage:affected` with
+`MANDREL_COVERAGE_BASE_REF` set to the **stamped commit**, drops the prior
+rows of the delta's files, merges the new rows over the prior artifact and
+stamps the merged tree fresh. It holds the full-suite lock like any capture,
+and a red delta refresh fails the capture — it never falls back to a wider
+run.
+
+A delta refresh runs only when **every** condition holds; otherwise the
+capture behaves exactly as before (the Story's affected scope, or the full
+suite when the script is absent):
+
+- the stamp is stale by content digest, and records a `commit` (a stamp
+  written before this field existed never qualifies) that is an ancestor of
+  `HEAD`;
+- `captureScope` is `affected` and the `test:coverage:affected` script
+  exists;
+- the worktree is clean, and the delta (`git diff --name-only <commit> HEAD`)
+  is non-empty and shares no path with the Story's change set;
+- the delta touches no coverage-determining config: `package.json`, a
+  lockfile, `tsconfig*.json`, or a vitest / jest / c8 / nyc config;
+- a prior artifact exists to merge over.
+
+Any git error or unresolvable input fails closed to the ordinary capture.
+Every freshness log line names the stamp's scope, the required scope and the
+verdict (`fresh`, `stale`, `scope-mismatch`, `missing`, or `delta-refresh`
+with the delta's file count), so an unexpected full re-run is explainable
+from the log alone. `captureScope: "full"` is unaffected.
+
 #### `delivery.worktreeIsolation` — node_modules strategies
 
 When `enabled: true`, each Story runs in its own worktree under

package/.agents/docs/workflows.md

@@ -32,7 +32,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (29)
+## Commands (31)
 
 | Command | Description |
 | --- | --- |
@@ -55,7 +55,9 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
 | `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /mandrel-plan --seed-file or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
-| `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
+| `/clean-git` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
+| `/clean-temp` | Clear the temp-tree backlog the land-time purge cannot attribute: sort every top-level entry under the project's tempRoot into framework, closed-issue, aged and kept buckets, preview by default, and delete only confirmed buckets. |
+| `/clean-worktrees` | Reclaim disk from dead worktrees: list every worktree of this project as a removal candidate (closed Story, merged branch, orphaned directory, detached HEAD) or as kept with a reason, then remove candidates only on `--execute`. |
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/mandrel-deliver` | Unified delivery entry point. Takes Story ids or a plain-language prompt, derives which path the work belongs on, and lands it via the single deliver-story engine — story-<id> → PR → main. |
 | `/mandrel-plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default; splits into N>1 only under the default-single split policy. |

package/.agents/instructions.md

@@ -181,7 +181,8 @@ never delivered): `/mandrel-plan` offers one above 2 Stories and
 
 All temporary files, scratch scripts, and intermediate outputs MUST
 live in the gitignored workspace-root `/temp/` directory — do NOT commit
-anything under it.
+anything under it. Put ad-hoc scratch in `temp/scratch/story-<id>/` (or
+`temp/scratch/` with no Story), the layout the temp purge reaps.
 
 ---
 

package/.agents/rules/git-conventions-reference.md

@@ -96,13 +96,13 @@ signature is worth naming:
 
 **Invariant (stated in the core): the delivering flow owns tidying the local
 checkout — reaping its own merged refs and fast-forwarding the base branch.
-`/git-cleanup` is a recovery tool, not a routine chore.** The outcome every
+`/clean-git` is a recovery tool, not a routine chore.** The outcome every
 delivering flow (`/mandrel-deliver`, `/git-deliver`) guarantees, with the mechanics
-owned by `boot-sweep.js` / `git-cleanup.js`:
+owned by `boot-sweep.js` / `clean-git.js`:
 
 - **`main` is fast-forwarded** by the flow itself in its cleanup phase, so the
   next init seeds from a current base. No workflow ends by telling the operator
-  to run `/git-cleanup` to catch up.
+  to run `/clean-git` to catch up.
 - **Merged local refs are reaped** at the next workflow boot's protected sweep
   (`boot-sweep.js`) — every local branch whose PR is already merged, skipping
   any candidate with unpushed work, a dirty worktree, or a still-open parent
@@ -112,9 +112,9 @@ owned by `boot-sweep.js` / `git-cleanup.js`:
   weaker content-equivalence signal (`detectedBy: 'content-merged'` — content
   already landed in the base by another route, with no merged PR or git
   ancestry of its own) is **never** reaped by the boot sweep; it is surfaced
-  under `contentMerged` for the operator to send to `/git-cleanup` for a
+  under `contentMerged` for the operator to send to `/clean-git` for a
   confirmed, eyeballed reap.
-- **`/git-cleanup` is recovery, not routine.** Run it by hand only for a state
+- **`/clean-git` is recovery, not routine.** Run it by hand only for a state
   the automated hygiene does not cover — triaging stashes, reaping across
   non-standard namespaces, or `--remote` pruning after a force-push. Reaching
   for it after every routine delivery signals the owning flow's hygiene step

package/.agents/rules/git-conventions.md

@@ -56,7 +56,7 @@ subject referencing the Story via `(refs #<storyId>)` — see
 **The delivering flow owns tidying the local checkout** — it
 fast-forwards the base branch itself and reaps its own merged refs on
 the next workflow boot (the `boot-sweep.js` protected sweep).
-`/git-cleanup` is a recovery tool, not a routine chore — never end a
+`/clean-git` is a recovery tool, not a routine chore — never end a
 workflow by telling the operator to run it. Scope rules and the
 shared-checkout contention guard:
 [`git-conventions-reference.md` § Local checkout hygiene](git-conventions-reference.md).

package/.agents/schemas/agentrc.schema.json

@@ -359,7 +359,7 @@
           "properties": {
             "fullSuiteLock": {
               "type": "boolean",
-              "description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
+              "description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
               "default": true
             }
           },
@@ -386,7 +386,7 @@
         },
         "tempRetention": {
           "type": "object",
-          "description": "Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path.",
+          "description": "Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so unrecognized files under tempRoot are reported with their size and left alone (`/clean-temp` is the operator path for them). signals.ndjson is never purged by any path.",
           "properties": {
             "enabled": {
               "type": "boolean",
@@ -416,6 +416,11 @@
                   "type": "boolean",
                   "description": "<tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded.",
                   "default": true
+                },
+                "scratch": {
+                  "type": "boolean",
+                  "description": "<tempRoot>/scratch/ — agent-authored scratch. `scratch/story-<id>/` is purged when that Story lands; any other `scratch/` entry is age-floored.",
+                  "default": true
                 }
               },
               "additionalProperties": false
@@ -595,6 +600,19 @@
                       "minLength": 1,
                       "description": "Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads.",
                       "default": "coverage/coverage-final.json"
+                    },
+                    "captureScope": {
+                      "type": "string",
+                      "enum": ["full", "affected"],
+                      "description": "What coverage-capture runs. `full` (default) runs `npm run test:coverage`. `affected` runs the consumer-owned `npm run test:coverage:affected` with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite.",
+                      "default": "full"
+                    },
+                    "timeoutMs": {
+                      "type": "integer",
+                      "minimum": 60000,
+                      "maximum": 7200000,
+                      "description": "Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure.",
+                      "default": 600000
                     }
                   },
                   "additionalProperties": false

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -200,7 +200,29 @@
       "required": ["waitedSeconds", "expired"],
       "properties": {
         "waitedSeconds": { "type": "number", "minimum": 0 },
-        "expired": { "type": "boolean" }
+        "expired": { "type": "boolean" },
+        "holder": {
+          "type": "object",
+          "description": "Story #5485 — the live holder an expired wait gave up on, read from the lockfile: its owner id, pid and lock age. Each field is null when the lockfile did not say.",
+          "required": ["ownerId", "pid", "ageSeconds"],
+          "properties": {
+            "ownerId": { "type": ["string", "null"] },
+            "pid": { "type": ["integer", "null"], "minimum": 1 },
+            "ageSeconds": { "type": ["number", "null"], "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "suiteTimings": {
+      "type": ["object", "null"],
+      "description": "Story #5485 — the close's one full-suite run split into three separate figures: lockWaitMs (queued on the host full-suite lock), hostWaitMs (spawn until the suite signalled MANDREL_SUITE_READY_FILE; null when it did not use the handshake) and testRunMs (the test phase the coverage.timeoutMs kill bound applies to). null when no full suite ran in this close.",
+      "required": ["lockWaitMs", "hostWaitMs", "testRunMs"],
+      "properties": {
+        "lockWaitMs": { "type": "number", "minimum": 0 },
+        "hostWaitMs": { "type": ["number", "null"], "minimum": 0 },
+        "testRunMs": { "type": "number", "minimum": 0 }
       },
       "additionalProperties": false
     },

package/.agents/schemas/validation-evidence.schema.json

@@ -41,10 +41,12 @@
               "check-baselines-independent",
               "check-baselines-coverage",
               "quality-preview",
+              "quality-preview-mi",
+              "quality-preview-crap",
               "check-maintainability",
               "check-crap"
             ],
-            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-baselines-independent` / `check-baselines-coverage` are the split pair the gate registers as when its enabled-kind set resolves (Story #5172), with `check-baselines` kept as both the unsplit fail-closed fallback and the historical name; `quality-preview` replays the pre-push CRAP-scope preview at close, registered beside `coverage-capture` (Story #5378); `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
+            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-baselines-independent` / `check-baselines-coverage` are the split pair the gate registers as when its enabled-kind set resolves (Story #5172), with `check-baselines` kept as both the unsplit fail-closed fallback and the historical name; `quality-preview-mi` / `quality-preview-crap` replay the pre-push quality preview at close as its two halves — the MI half in the parallel partition, the CRAP half serial behind `coverage-capture` (Story #5471) — with `quality-preview` kept as the historical name of the unsplit gate (Story #5378); `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
           },
           "commitSha": {
             "type": "string",

package/.agents/scripts/boot-sweep.js

@@ -3,13 +3,18 @@
 
 /**
  * boot-sweep.js — non-interactive *protected* merged-branch sweep over
- * `sweepMergedBranches` (flags: see HELP). Unlike `git-cleanup --branches` it
+ * `sweepMergedBranches` (flags: see HELP). Unlike `clean-git --branches` it
  * always skips a branch with unpushed work, a dirty worktree or an open
  * parent Story. Best-effort: failures land in the envelope, exit is always 0.
  *
+ * After the branch sweep it runs the closed-Story worktree sweep
+ * (`sweepStaleStoryWorktrees`) under the same lock: `.worktrees/story-<id>`
+ * trees whose Story is closed or `agent::done` are removed; an open Story's
+ * tree and the tree this process runs from are never touched.
+ *
  * `content-merged` branches (merge-tree equivalence — no merge check ever
  * validated their exact diff) are never reaped here, only reported for
- * `/git-cleanup`.
+ * `/clean-git`.
  */
 
 import path from 'node:path';
@@ -18,9 +23,13 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
+import { sweepStaleStoryWorktrees } from './lib/orchestration/plan-runner/worktree-sweep.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
-import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
+import {
+  acquireSweepLock,
+  resolveSweepLockPath,
+} from './lib/single-story-sweep/sweep-lock.js';
 import { sweepMergedBranches } from './lib/single-story-sweep.js';
 import { sweepTempRetention } from './lib/temp-retention.js';
 
@@ -46,10 +55,13 @@ Runs the protected merged-branch boot sweep non-interactively: reaps every
 local branch whose PR is MERGED and whose HEAD matches the merged headRefOid,
 skipping any candidate the protection partition flags (unpushed work, dirty
 worktree, still-open parent Story), then fast-forwards the base branch.
+Then removes every .worktrees/story-<id> tree whose Story is closed or
+agent::done (never an open Story's, never the tree this process runs from);
+the outcome lands under "worktreeSweep".
 Branches detected only via the weaker content-equivalence signal
 (detectedBy: 'content-merged') are never reaped here — they are reported
 under "contentMerged" (and a routing hint in the summary line) for the
-operator to send to /git-cleanup.
+operator to send to /clean-git.
 
 Options:
   --include <glob>     Branch glob to sweep (repeatable). Default: story-*
@@ -60,6 +72,63 @@ Options:
   --json               Emit the result envelope as JSON.
 `;
 
+/**
+ * The closed-Story worktree sweep under the shared sweep lock; never throws.
+ * A contended lock skips it — the holder's next boot picks the trees up.
+ * Shared with `single-story-init.js`, whose boot never reaches
+ * {@link runBootSweep}: one sweep, one lock, two callers. `keepPaths` joins
+ * the sweep's running-tree guard — init passes the tree it is about to
+ * work in, so the Story being initialized is never removed.
+ *
+ * @param {{
+ *   root: string,
+ *   provider: object,
+ *   lockPath: string,
+ *   lockTimeoutMs: number,
+ *   sweepFn?: Function,
+ *   acquireLockFn?: Function,
+ *   logger: object,
+ *   logTag?: string,
+ *   keepPaths?: string[],
+ * }} args
+ * @returns {Promise<object>} `{ ok, reaped, skipped, reason?, error? }`.
+ */
+export async function runWorktreeSweep({
+  root,
+  provider,
+  lockPath,
+  lockTimeoutMs,
+  sweepFn = sweepStaleStoryWorktrees,
+  acquireLockFn = acquireSweepLock,
+  logger,
+  logTag = '[boot-sweep]',
+  keepPaths = [],
+}) {
+  const lock = acquireLockFn({ lockPath, timeoutMs: lockTimeoutMs });
+  if (!lock.acquired) {
+    return { ok: true, reason: `lock-${lock.reason}`, reaped: [], skipped: [] };
+  }
+  try {
+    const result = await sweepFn({
+      provider,
+      repoRoot: root,
+      runningPaths: keepPaths,
+      logger: {
+        info: (m) => logger.info?.(`${logTag} ${m}`),
+        warn: (m) => logger.warn?.(`${logTag} ${m}`),
+        error: (m) => logger.warn?.(`${logTag} ${m}`),
+      },
+    });
+    return { ok: true, ...result };
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    logger.warn?.(`${logTag} worktree sweep threw (host continues): ${msg}`);
+    return { ok: false, error: msg, reaped: [], skipped: [] };
+  } finally {
+    lock.release();
+  }
+}
+
 /**
  * Run the protected boot sweep; never throws.
  *
@@ -73,11 +142,13 @@ Options:
  *   injectedConfig?: object,
  *   injectedProvider?: object,
  *   injectedSweep?: Function,
+ *   worktreeSweepFn?: Function,
+ *   acquireLockFn?: Function,
  *   purgeFn?: Function,
  *   logger?: { info?: Function, warn?: Function },
  * }} [args]
  * @returns {Promise<object>} the {@link sweepMergedBranches} envelope plus
- *   `tempPurge`.
+ *   `worktreeSweep` and `tempPurge`.
  */
 export async function runBootSweep({
   cwd,
@@ -89,6 +160,8 @@ export async function runBootSweep({
   injectedConfig,
   injectedProvider,
   injectedSweep,
+  worktreeSweepFn = sweepStaleStoryWorktrees,
+  acquireLockFn = acquireSweepLock,
   purgeFn = sweepTempRetention,
   logger = Logger,
 } = {}) {
@@ -130,6 +203,16 @@ export async function runBootSweep({
       lockTimeoutMs,
     });
 
+    const worktreeSweep = await runWorktreeSweep({
+      root,
+      provider,
+      lockPath,
+      lockTimeoutMs,
+      sweepFn: worktreeSweepFn,
+      acquireLockFn,
+      logger,
+    });
+
     // Temp-retention catch-up: reaped branches are confirmed merges, so their
     // artifacts are spent; the age floor collects the rest.
     const purge = await purgeFn({
@@ -138,7 +221,7 @@ export async function runBootSweep({
       label: 'boot-sweep',
       logger,
     });
-    return { ...result, tempPurge: purge };
+    return { ...result, worktreeSweep, tempPurge: purge };
   } catch (err) {
     const msg = err?.message ?? String(err);
     logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);
@@ -157,7 +240,7 @@ export async function runBootSweep({
 }
 
 /**
- * One-line summary; a nonzero `contentMerged` count adds a `/git-cleanup` hint.
+ * One-line summary; a nonzero `contentMerged` count adds a `/clean-git` hint.
  *
  * @param {{ localDeleted: number, remoteDeleted: number, protected?: Array, contentMerged?: Array }} result
  * @returns {string}
@@ -165,11 +248,16 @@ export async function runBootSweep({
 export function buildSummaryLine(result) {
   const protectedCount = result.protected?.length ?? 0;
   const contentMergedCount = result.contentMerged?.length ?? 0;
+  const worktreesReaped = result.worktreeSweep?.reaped?.length ?? 0;
+  const worktreeSuffix =
+    worktreesReaped > 0
+      ? `; removed ${worktreesReaped} closed-Story worktree(s)`
+      : '';
   const contentMergedSuffix =
     contentMergedCount > 0
-      ? `; ${contentMergedCount} content-merged branch(es) left for /git-cleanup`
+      ? `; ${contentMergedCount} content-merged branch(es) left for /clean-git`
       : '';
-  return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${contentMergedSuffix}.`;
+  return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${worktreeSuffix}${contentMergedSuffix}.`;
 }
 
 /**

package/.agents/scripts/{git-cleanup.js → clean-git.js}

@@ -100,10 +100,10 @@ async function main() {
 }
 
 runAsCli(import.meta.url, main, {
-  source: 'git-cleanup',
+  source: 'clean-git',
   usage: {
     invocation:
-      'node .agents/scripts/git-cleanup.js [--execute] [--yes] [--json] [phase flags] [filters]',
+      'node .agents/scripts/clean-git.js [--execute] [--yes] [--json] [phase flags] [filters]',
     summary:
       'Tidy the local checkout in four phases — fast-forward the base branch, prune stale remote refs, reap merged branches, triage stashes. Dry-run unless --execute.',
     flags: [

package/.agents/scripts/clean-temp.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/* node:coverage ignore file -- thin CLI shell; the engine is lib/clean-temp.js */
+
+/**
+ * `/clean-temp` — preview (default) or delete spent entries under the
+ * project's tempRoot. Thin shell over `lib/clean-temp.js`.
+ *
+ * Exit codes: 0 clean or dry-run, 1 refused (tempRoot outside the project
+ * root) or a deletion failed.
+ */
+
+import { runCleanTemp } from './lib/clean-temp.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { promptYesNo } from './lib/orchestration/git-cleanup/phases/prompts.js';
+import { createProvider } from './lib/provider-factory.js';
+
+/* node:coverage ignore next */
+async function main() {
+  const { exitCode } = await runCleanTemp({
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    loadConfig: (projectRoot) => resolveConfig({ cwd: projectRoot }),
+    getProvider: createProvider,
+    confirm: promptYesNo,
+    write: (text) => process.stdout.write(text),
+    writeErr: (text) => process.stderr.write(text),
+  });
+  return exitCode;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'clean-temp',
+  propagateExitCode: true,
+  usage: {
+    invocation:
+      'node .agents/scripts/clean-temp.js [--execute] [--yes] [--json] [--cwd <path>]',
+    summary:
+      "Sort every top-level entry under the project's tempRoot into framework / closed-issue / aged / kept buckets. Dry-run unless --execute.",
+    flags: [
+      ['--execute', 'Delete the confirmed buckets (default is a dry run).'],
+      [
+        '--yes',
+        'Skip the per-bucket prompts; deletes framework and closed-issue only — aged is never deleted unattended.',
+      ],
+      ['--json', 'Emit the result envelope as JSON.'],
+      ['--cwd <path>', 'Project directory (default: process cwd).'],
+    ],
+    notes: [
+      'Refuses (exit 1) when the resolved tempRoot is not inside the project root.',
+      'qa/, cache/, *.lock and signals.ndjson (at any depth) are never deleted.',
+    ],
+  },
+});