mandrel 2.66.0 → 2.67.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/docs/agentrc-reference.json

@@ -87,7 +87,8 @@
         "orchestrationLogs": true,
         "validationEvidence": true,
         "auditResults": true,
-        "planDirs": true
+        "planDirs": true,
+        "scratch": true
       }
     },
     "deliverRunner": {

package/.agents/docs/configuration.md

@@ -139,13 +139,14 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
 | `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. |
 | `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. |

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

@@ -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

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.',
+    ],
+  },
+});