mandrel 2.66.0 → 2.67.0

package/.agents/workflows/clean-temp.md

@@ -0,0 +1,67 @@
+---
+description: >-
+  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-temp [--execute] [--yes] [--json]
+
+The land-time and boot-time purges only reap what they can attribute: the
+framework's own temp layouts and `temp/scratch/`. Everything else an agent
+dropped at the temp root is reported and left alone, so a busy consumer's temp
+tree grows without bound. `/clean-temp` is the operator's catch-up for that
+backlog. It classifies and deletes through the same temp-retention engine the
+purges use — there is no second walker.
+
+The script documents its own flags:
+`node .agents/scripts/clean-temp.js --help`. Without `--execute` it is a
+**dry-run preview**; nothing is deleted.
+
+## Buckets
+
+Every top-level entry under tempRoot lands in exactly one:
+
+| Bucket | What it holds | Unattended (`--yes`) |
+| --- | --- | --- |
+| **framework** | A framework layout holding artifacts the auto-purge would take — Story-keyed on a closed Story, or past `staleDays`. | Deleted |
+| **closed-issue** | An unrecognized entry whose basename names exactly one issue id, and that issue reads `closed`. | Deleted |
+| **aged** | An unrecognized entry naming no id, or several, older than `staleDays`. | **Never** — an age heuristic has no attribution, so it needs a human |
+| **kept** | Everything else, with the reason: issue open, issue read failed, too recent, reserved, or nothing spent. | Kept |
+
+An id is a standalone run of up to seven digits in the basename. A basename
+naming two ids is never attributed to either — it is treated as id-less.
+
+## Constraint
+
+> [!WARNING] `--execute` deletes files. Interactive runs confirm each bucket;
+> `--yes` deletes the framework and closed-issue buckets only.
+
+- Reads fail safe: an open issue, or one whose read fails, keeps its entry.
+- `qa/`, `cache/`, `*.lock` and `signals.ndjson` at any depth are never
+  deleted.
+- Project-scoped: the script exits 1 without deleting anything when the
+  resolved tempRoot is not inside the project root it was invoked from. It
+  never touches `$TMPDIR` or a sibling checkout.
+
+## Steps
+
+1. Preview and read the table (bucket, entry, size, age, reason):
+
+   ```bash
+   node .agents/scripts/clean-temp.js
+   ```
+
+2. Delete, confirming each bucket:
+
+   ```bash
+   node .agents/scripts/clean-temp.js --execute
+   ```
+
+   Unattended, `--execute --yes` deletes the framework and closed-issue buckets
+   and reports the aged bucket as left for a human. `--json` emits the envelope
+   (per-bucket totals and `bytesReclaimed`) instead of the table.
+
+Going forward, put ad-hoc scratch under `temp/scratch/story-<id>/` (or
+`temp/scratch/` with no Story): a Story's landing reaps its scratch directory,
+and the boot sweep age-floors the rest.

package/.agents/workflows/clean-worktrees.md

@@ -0,0 +1,63 @@
+---
+description: >-
+  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`.
+---
+
+# /clean-worktrees [--execute] [--yes] [--json]
+
+Every Story worktree carries its own `node_modules`, so a worktree left behind
+costs gigabytes. Workflow boot already removes `.worktrees/story-<id>` trees
+whose Story is closed or `agent::done` (the boot sweep in
+[`boot-sweep.js`](../scripts/boot-sweep.js)); `/clean-worktrees` is the
+**recovery tool** for everything that sweep does not own — the backlog, trees
+on non-Story branches, directories git no longer registers, and detached
+trees such as the Claude Code app's `.claude/worktrees/*`.
+
+The enumeration, classification and removal live in
+[`clean-worktrees.js`](../scripts/clean-worktrees.js), which documents its own
+flags: `node .agents/scripts/clean-worktrees.js --help`.
+
+## Steps
+
+1. **Preview.** Run `node .agents/scripts/clean-worktrees.js` (dry-run, the
+   default). It prints one row per worktree — class, path, size, branch/HEAD,
+   action — and removes nothing. Show the operator the table.
+2. **Confirm.** Ask the operator which candidates to remove. Do not proceed
+   on your own judgment.
+3. **Remove.** Re-run with `--execute`. In a terminal it asks per entry;
+   `--execute --yes` removes every non-`detached` candidate without asking.
+   `--json` emits the envelope, including `bytesReclaimed`.
+
+## Classes
+
+| Class | Candidate when |
+| --- | --- |
+| `closed-story` | `.worktrees/story-<id>` on `story-<id>` whose Story is closed or `agent::done`. |
+| `merged-branch` | Any other branch whose PR is MERGED and whose HEAD is the merged head. |
+| `orphan-dir` | A directory under `.worktrees/` that `git worktree list` does not register. |
+| `detached` | A registered worktree with a detached HEAD. |
+
+Everything else is **kept** with its reason: the main checkout, an open Story,
+an unmerged branch, a dirty tree, unpushed commits, a tree in use.
+
+## Constraint
+
+> [!WARNING] `--execute` deletes worktree directories. Without it the script
+> only previews.
+
+- **Project-scoped.** Only worktrees inside the invoking checkout's project
+  root are candidates; one registered elsewhere is reported, never removed.
+- **Unique work survives.** A dirty tree, or a HEAD no remote-tracking ref
+  contains, is never removed.
+- **Live trees survive.** The tree this process runs from is never removed;
+  on macOS and Linux a tree any live process uses is refused outright.
+- **`detached` needs a person.** A detached tree carries no Story label and a
+  live session may own it (a blanket prune once destroyed a live delivery's
+  worktree), so it is removed only on a per-entry interactive yes — never
+  under `--yes`.
+- **Removal goes through the worktree removal seam** (Windows lock retry and
+  the pending-cleanup hand-off), never raw deletion.
+- **Branches are untouched.** Deleting local or remote branches is
+  [`/clean-git`](clean-git.md)'s job.

package/.agents/workflows/git-deliver.md

@@ -77,7 +77,7 @@ node .agents/scripts/boot-sweep.js \
   --current "$(git rev-parse --abbrev-ref HEAD)"
 ```
 
-The safe subset of the `/git-cleanup` phases: fast-forwards the base branch,
+The safe subset of the `/clean-git` phases: fast-forwards the base branch,
 prunes stale remote-tracking refs, and reaps merged branches. It never
 touches the stash, never reaps a candidate with unpushed work / dirty
 worktree / open parent ticket, and always exits `0` — a failed sweep is

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -95,7 +95,7 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      without being respawned; a stale or absent stamp reports `spawn: true` and
      the command runs for real. The credited run itself is stated once, in
      [`deliver-digest.md`](deliver-digest.md) § 5.
-   + Emits **one** verdict file under `temp/` conforming to
+   + Emits **one** verdict file under `temp/scratch/story-<id>/` conforming to
      [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json):
      one `{ index, criterion, verdict: met|partial|unmet, evidence,
      verifyEvidence[] }` record per `acceptance[]` item, in acceptance-array
@@ -137,4 +137,5 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      (transition to `agent::blocked`) and post a `friction` comment naming the
      unmet criteria and their evidence. Never silently proceed to close.
 
-Write the verdict under `temp/` only — it is a scratch artifact.
+Write the verdict under `temp/scratch/story-<id>/` only — a scratch artifact
+the Story's landing reaps.

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -48,7 +48,7 @@ presence, so re-running init on a partially-initialized Story is idempotent.
 ### Merged-`story-*` sweep
 
 Between the fetch and the branch seed, init runs the same primitive as
-`<agentRoot>/scripts/git-cleanup.js` scoped to `story-*` in
+`<agentRoot>/scripts/clean-git.js` scoped to `story-*` in
 `--execute --remote` mode, excluding this run's `story-<id>`, reaping merged
 siblings' local refs, `origin/` refs and stale tracking refs in one pass.
 
@@ -539,7 +539,7 @@ once per project to delete the conflicting bot workflows entirely.
 > cause), or after a manual merge on a `--no-wait-merge` run:
 
 ```bash
-node .agents/scripts/git-cleanup.js \
+node .agents/scripts/clean-git.js \
   --execute \
   --remote \
   --yes \

package/docs/CHANGELOG.md

@@ -15,6 +15,19 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.67.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.66.0...mandrel-v2.67.0) (2026-09-26)
+
+
+### ⚠ BREAKING CHANGES
+
+* the /git-cleanup slash command is now /clean-git, and .agents/scripts/git-cleanup.js is now .agents/scripts/clean-git.js. Update any operator scripts or runbooks that invoke the old names.
+
+### Added
+
+* add /clean-temp and a reapable scratch layout for agent-authored temp files ([#5459](https://github.com/dsj1984/mandrel/issues/5459)) ([#5464](https://github.com/dsj1984/mandrel/issues/5464)) ([0e9ae9b](https://github.com/dsj1984/mandrel/commit/0e9ae9b7e53ceffc7561bea99f76c60e06bc1169))
+* add /clean-worktrees and re-wire the closed-Story worktree sweep into boot ([#5460](https://github.com/dsj1984/mandrel/issues/5460)) ([#5463](https://github.com/dsj1984/mandrel/issues/5463)) ([bbd946e](https://github.com/dsj1984/mandrel/commit/bbd946e94f636956690f07a8f29ecc64170dce02))
+* rename /git-cleanup to /clean-git ([#5461](https://github.com/dsj1984/mandrel/issues/5461)) ([#5466](https://github.com/dsj1984/mandrel/issues/5466)) ([104c60d](https://github.com/dsj1984/mandrel/commit/104c60d9c0baffece7d30c17ff7520d2f9db112e))
+
 ## [2.66.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.65.0...mandrel-v2.66.0) (2026-09-26)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.66.0",
+  "version": "2.67.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",