@ngockhoale/ukit 3.4.21 → 3.4.23

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.23 - 2026-10-08
+
+**Core hook/gate reliability repairs** (C97; each backed by baseline RED, GREEN and independent different-model review).
+- `stale-spec-check`: containment errors for external/traversal targets are caught at the checker boundary instead of crashing the hook chain.
+- `hook-chain-runner`: bounded failure provenance and diagnostics while staying fail-closed.
+- `docContracts`: `checkRenderVars` and `collectScannableDocs` prune isolated worktree checkouts; the walk skips `node_modules` and breaks symlink cycles by realpath (live-repo contract check 12.4s -> 0.3s).
+- Handoff intent: exact command-suffix boundary, `handoff-implement` recognized, torn newest JSONL entry yields unknown instead of an older opposite intent; `handoff-create`-owned runs stay planning-only through Stop/resume.
+- `protect-files`: backslash path spellings get the same protection as slash paths.
+- `land-worktree`: complete base-relative copy-back (committed, staged, deleted, renamed, newline paths).
+- `cleanup-task-worktree`: receipt-gated, recoverable cleanup with source/destination authority containment; no forced removal.
+- Vision: already-pending unread image is idempotent; a corrupt pending marker is retained with a diagnostic.
+- `output-compression`: a subagent's raw tool output no longer charges the parent's compact-pressure session (hard-cap gates unchanged).
+- Not included: shell create-scope detection (TASK-C97-007) and decision-log lock reclaim (TASK-C97-013) failed final review and were reverted to the 3.4.22 behavior.
+- Packed-artifact size cap raised 3.16 MB -> 3.17 MB.
+
+## 3.4.22 - 2026-10-07
+
+**Windows: `.sh` hooks no longer deny every Edit/Write/Bash.**
+- `.sh` hooks are now launched through Git for Windows bash: `UKIT_BASH_BIN` → `CLAUDE_CODE_GIT_BASH_PATH` →
+  default Git install paths → absolute `PATH` entries. WSL's `bash.exe` and a cwd `bash.exe` are never used.
+- On Windows a `.sh` hook whose bash cannot be found or started is reported as `spawn-unavailable` and warned
+  instead of denying every Edit/Write/Bash. POSIX behaviour is unchanged; timeouts, real blocks, missing gate
+  files and `block-dangerous.sh` stay fail-closed.
+- `ukit doctor` flags Windows hook launch failures.
+- `*.sh` is pinned to LF (repo `.gitattributes` and a shipped `.claude/.gitattributes`) so a CRLF checkout cannot
+  break hook scripts. Troubleshooting added to `docs/INSTALL.md`.
+
 ## 3.4.21 - 2026-10-07
 
 **Hook runtime no longer burns CPU/disk on every tool call** (five measured bugs, C95).

package/manifests/documentation.yaml

@@ -707,6 +707,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: non-.md entry — exists for FR-002 manifest consistency
+  - id: tpl-claude-gitattributes
+    path: template_project/.claude/.gitattributes
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: template_project/.claude/.gitattributes
+    merge_strategy: skip
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: non-.md entry — keeps hook *.sh LF on Windows autocrlf checkouts; exists for FR-002 manifest consistency
 
   # ── repo mirrors (derived from template_project/) ───────────────────────────────
   - id: mirror-claude-dir

package/manifests/platform.full.yaml

@@ -1511,6 +1511,19 @@ items:
     packs:
       - core
 
+  # Ships `*.sh text eol=lf` inside .claude/ only (never the user's root .gitattributes) so
+  # a Windows autocrlf checkout cannot turn hook scripts into CRLF that bash rejects.
+  - id: claude-gitattributes
+    type: config
+    sourceTemplate: .claude/.gitattributes
+    targetPath: .claude/.gitattributes
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-reset-compact-pressure
     type: hook
     sourceTemplate: .claude/hooks/reset-compact-pressure.sh
@@ -1640,6 +1653,35 @@ items:
     packs:
       - core
 
+  # C97 TASK-C97-009 (MODULE04 FR-M4-004): the task-scoped landing helper that
+  # replaces the unstaged-only cp loop in the fullstack/implement 3c samples.
+  - id: ukit-index-land-worktree-script
+    type: config
+    sourceTemplate: .claude/ukit/index/land-worktree.mjs
+    targetPath: .claude/ukit/index/land-worktree.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  # C97 TASK-C97-010 (MODULE04 FR-M4-003/003a): the receipt-gated recoverable
+  # cleanup helper that replaces the force-remove/-D samples in the fullstack,
+  # implement and clear command docs.
+  - id: ukit-index-cleanup-task-worktree-script
+    type: config
+    sourceTemplate: .claude/ukit/index/cleanup-task-worktree.mjs
+    targetPath: .claude/ukit/index/cleanup-task-worktree.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-stale-spec-check-script
     type: config
     sourceTemplate: .claude/ukit/index/stale-spec-check.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.21",
+  "version": "3.4.23",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/docContracts.js

@@ -92,10 +92,27 @@ async function isDir(absPath) {
 }
 
 // Recursive repo-relative file walk under rootDir/dirRel. `filter` selects
-// files by extension etc. Never throws (unreadable dirs are skipped).
-async function walkFiles(rootDir, dirRel, filter = () => true) {
+// files by extension etc. `pruneDir(rel)` optionally excludes a directory
+// subtree BEFORE descent (default: never prune — unrelated consumers keep the
+// full walk). `dirIs` carries a per-top-level-walk set of descended directory
+// `fs.realpath`s; because `fs.stat` follows symlinks, a symlink cycle (e.g.
+// the live repo's `node_modules/node_modules -> node_modules`, or an
+// exploration worktree symlinked at the repo root) would otherwise grow
+// unbounded — the realpath guard makes every real directory traverse at most
+// once. A directory named `node_modules` is never doc scope, so it is skipped
+// by basename before its installed-tree contents are walked. Never throws
+// (unreadable dirs are skipped).
+async function walkFiles(rootDir, dirRel, filter = () => true, pruneDir = null, dirIs = null) {
+  const dirs = dirIs || new Set();
   const out = [];
   const dirAbs = dirRel ? path.join(rootDir, dirRel) : rootDir;
+  // Seed the starting directory so a child symlink pointing back at it (or at
+  // any ancestor of this walk) is recognized as a cycle immediately.
+  try {
+    dirs.add(await fs.realpath(dirAbs));
+  } catch {
+    /* realpath unavailable — descend without the cycle seed */
+  }
   let names;
   try {
     names = await fs.readdir(dirAbs);
@@ -110,12 +127,36 @@ async function walkFiles(rootDir, dirRel, filter = () => true) {
     } catch {
       continue; // dangling symlink / unreadable
     }
-    if (st.isDirectory()) out.push(...(await walkFiles(rootDir, rel, filter)));
-    else if (filter(name, rel)) out.push(rel);
+    if (st.isDirectory()) {
+      if (pruneDir && pruneDir(rel)) continue;
+      if (name === 'node_modules') continue; // never doc scope — skip the installed tree
+      let real;
+      try {
+        real = await fs.realpath(path.join(rootDir, rel));
+      } catch {
+        continue; // unreadable — nothing to descend
+      }
+      if (dirs.has(real)) continue; // symlink cycle / real directory already walked
+      dirs.add(real);
+      out.push(...(await walkFiles(rootDir, rel, filter, pruneDir, dirs)));
+    } else if (filter(name, rel)) out.push(rel);
   }
   return out;
 }
 
+// SPEC FR-004 (TASK-C97-003): true when `rel` is inside an isolated checkout
+// worktree subtree — `.claude/worktrees/<agent>/` or `.worktrees/<task>/`.
+// Exact path-COMPONENT comparison (not a string prefix), so ordinary lookalike
+// directories such as `.claude/worktrees-not-isolated/` stay in scope.
+function isIsolatedCheckoutSubtree(rel) {
+  const parts = rel.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '.worktrees') return true;
+    if (parts[i] === '.claude' && parts[i + 1] === 'worktrees') return true;
+  }
+  return false;
+}
+
 function makeCheck(id, label, severity, extra) {
   return { id, label, severity, passed: false, ...extra };
 }
@@ -314,8 +355,17 @@ async function checkRenderVars(rootDir, registry) {
     if (typeof e.path !== 'string' || e.class !== 'derived' || e.path.startsWith('template_project/')) continue;
     // Only .md doc surfaces are render targets — scripts/components/templates
     // inside derived dirs legitimately use {{ }} as their own placeholders.
+    // FR-004: descent prunes exact isolated-checkout subtrees BEFORE walking
+    // (render-only prune; raw nested CHANGELOG/docs placeholders belong to
+    // exploration worktrees, not the current checkout). All other .claude
+    // content, lookalike dirs and root instructions stay enforced.
     if (e.path.endsWith('/')) {
-      for (const f of await walkFiles(rootDir, e.path.slice(0, -1), (n) => n.endsWith('.md'))) {
+      for (const f of await walkFiles(
+        rootDir,
+        e.path.slice(0, -1),
+        (n) => n.endsWith('.md'),
+        isIsolatedCheckoutSubtree,
+      )) {
         targets.add(f);
       }
     } else if (e.path.endsWith('.md')) {
@@ -444,7 +494,11 @@ export async function collectScannableDocs(rootDir, registry) {
     if (typeof e.path === 'string' && e.path.endsWith('/')) dirs.add(e.path.slice(0, -1));
   }
   for (const dirRel of dirs) {
-    for (const f of await walkFiles(rootDir, dirRel, (n) => n.endsWith('.md'))) {
+    // FR-004 (TASK-C97-018): prune isolated-checkout subtrees before descent —
+    // exploration worktrees are not part of the current checkout, and their
+    // own node_modules symlink would otherwise drag the whole installed tree
+    // into the walk. `walkFiles` additionally breaks symlink cycles by realpath.
+    for (const f of await walkFiles(rootDir, dirRel, (n) => n.endsWith('.md'), isIsolatedCheckoutSubtree)) {
       files.add(f);
     }
   }

package/src/core/hookChainDoctor.js

@@ -24,12 +24,31 @@ const FAILURE_OUTCOMES = new Set([
   'output-overflow',
   'error',
   'signal',
+  'spawn-unavailable',
 ]);
 
 // The pre-O6 remedy, kept verbatim: a failure with no gate evidence must read
 // exactly as it did before escalation existed (SPEC §FR-012).
+// SPEC §FR-007: launch failures only arise on win32 (the runner emits
+// `spawn-unavailable` from its bash-launcher path), so there is one remedy.
+const LAUNCH_REMEDY = 'Windows cannot execute .sh hooks directly — install Git for Windows so C:\\Program Files\\Git\\bin\\bash.exe exists, or set UKIT_BASH_BIN to the full path of bash.exe, then restart the session.';
+
+// Legacy pre-fix win32 rows recorded a failed .sh launch as a plain `error`
+// that finished almost instantly.
+const LEGACY_LAUNCH_FAILURE_MAX_MS = 10;
+
 const BASE_REMEDY = 'Inspect recent rows in .ukit/storage/cache/hook-latency/ for the failing scriptName/failureKind and fix or widen the gate budget.';
 
+function isLaunchFailure(entry, platform) {
+  if (!entry || typeof entry !== 'object') return false;
+  if (typeof entry.scriptName !== 'string' || !entry.scriptName.toLowerCase().endsWith('.sh')) return false;
+  if (entry.failureKind === 'spawn-unavailable') return true;
+  return platform === 'win32'
+    && entry.failureKind === 'error'
+    && typeof entry.elapsedMs === 'number'
+    && entry.elapsedMs < LEGACY_LAUNCH_FAILURE_MAX_MS;
+}
+
 function telemetryDirFor(projectRoot) {
   return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
 }
@@ -78,7 +97,7 @@ async function tailLines(filePath, size) {
   }
 }
 
-export async function inspectHookChainHealth({ projectRoot, now = Date.now() } = {}) {
+export async function inspectHookChainHealth({ projectRoot, now = Date.now(), platform = process.platform } = {}) {
   const label = 'hook-chain health';
 
   // Never-fatal posture extends to malformed input: a missing projectRoot is
@@ -106,6 +125,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
   // evidence shapes that prove it, collected in the same pass that counts
   // outcomes so no second read of the rows is needed.
   const gateFailures = new Set();
+  const launchFailures = new Set();
   let budgetExhaustedChains = 0;
 
   for (const file of files) {
@@ -130,6 +150,14 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
       const outcome = typeof row.outcome === 'string' && row.outcome.length > 0 ? row.outcome : 'ok';
       counts[outcome] = (counts[outcome] ?? 0) + 1;
 
+      // .sh launch failures are collected from EVERY row (an exit-code row can
+      // still carry one); they are a different signal from a gate that ran and failed.
+      if (Array.isArray(row.scripts)) {
+        for (const entry of row.scripts) {
+          if (isLaunchFailure(entry, platform)) launchFailures.add(entry.scriptName);
+        }
+      }
+
       // Escalation evidence is only ever read off a FAILING row — a gate that
       // ran fine is not evidence of anything, and SPEC §FR-012 scopes the
       // budget signal to a non-ok row ("a non-ok row ... escalates only when
@@ -155,6 +183,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
         if (!entry || typeof entry !== 'object') continue;
         if (entry.failClosed !== true) continue;
         if (typeof entry.failureKind !== 'string' || entry.failureKind === 'ok') continue;
+        if (entry.failureKind === 'spawn-unavailable') continue; // reported as a launch failure
         gateFailures.add(typeof entry.scriptName === 'string' ? entry.scriptName : 'unknown');
       }
     }
@@ -177,7 +206,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
     .filter((key) => FAILURE_OUTCOMES.has(key) && counts[key] > 0)
     .sort();
 
-  if (failureKinds.length === 0) {
+  if (failureKinds.length === 0 && launchFailures.size === 0) {
     return {
       label,
       passed: true,
@@ -190,7 +219,9 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
   }
 
   const breakdown = failureKinds.map((kind) => `${kind}=${counts[kind]}`).join(', ');
-  const baseDetail = `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`;
+  const baseDetail = failureKinds.length > 0
+    ? `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`
+    : `${counts.rowsScanned} chain row(s) scanned`;
 
   // O6 (SPEC §FR-012): escalate only when a failure actually landed ON a gate —
   // a gate that merely ran is not evidence. The escalation is purely additive:
@@ -207,6 +238,11 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
       `A fail-closed gate actually failed (${gateList.join(', ')}) — that is a real budget or path problem, not a slow advisory hook; widen the failing gate's budget or fix that step.`,
     );
   }
+  const launchList = [...launchFailures].sort();
+  if (launchList.length > 0) {
+    escalations.push(`.sh hook(s) could not be launched: ${launchList.join(', ')}`);
+    advices.push(LAUNCH_REMEDY);
+  }
   if (budgetExhaustedChains > 0) {
     escalations.push(`${budgetExhaustedChains} chain row(s) exhausted the total budget`);
     advices.push(

package/template_project/.claude/.gitattributes

@@ -0,0 +1,2 @@
+# Hook scripts must stay LF: a CRLF checkout makes bash fail on "\r".
+*.sh text eol=lf

package/template_project/.claude/agents/feature-implementer.md

@@ -139,9 +139,16 @@ mode only; daily flow does not get a Progress section.
   reports `undeclared-drift`.
 - **Milestone commit.** The commit lives on your worktree branch only (e.g.
   `handoff/task-xxx`). Use a `-m "milestone: <name>"` message. Never commit outside your
-  worktree, never push. The orchestrator's copy-back step (`git diff --name-only` against
-  base) diffs the working tree, so intermediate commits on the worktree branch are free —
-  **copy-back is unaffected** by milestone commits.
+  worktree, never push. The orchestrator's copy-back step lands the branch's final
+  base-relative snapshot (`land-worktree.mjs` diffs the working tree against the immutable
+  base), so intermediate commits on the worktree branch are free — **copy-back is
+  unaffected** by milestone commits.
+- **Final clean milestone commit (required before PASS).** End your run with one final
+  milestone commit so the worktree's snapshot equals its committed tree — nothing staged,
+  nothing unstaged, no nonignored untracked file left behind. A Git-clean snapshot is what
+  lets a later receipt-gated cleanup remove the worktree without `--force`; a tree dirty
+  against the snapshot is retained with a named reason, never forced. Do not report PASS on
+  a dirty worktree.
 - **Resume.** When a previous run aborted, you will be respawned. Read `## Progress`,
   jump straight to the last entry whose `last-green:` is not `none`, and continue from
   there. Do NOT re-plan, do NOT restart from RED, do NOT re-write tests that already

package/template_project/.claude/commands/ukit/handoff-clear.md

@@ -9,21 +9,34 @@
 
 ---
 
-## Step 1 — Force-remove all handoff worktrees and branches
+## Step 1 — Receipt-gated cleanup of handoff worktrees and branches
+
+**Clearing is not licence to destroy recovery evidence.** Never force-remove a worktree and
+never force-delete a branch — a stuck or abandoned task's unreported work is exactly what
+someone may need to recover. Use the shared, receipt-gated helper: it removes
+**only** the one task named by a verified landing receipt whose result was independently
+Approved and whose source still matches the receipt snapshot and is Git-clean; everything
+else is retained with a named reason.
+
+Every remaining `.worktrees/*` entry and `handoff/*` branch must be named in a
+**retained-reason report** (receipt missing, not approved, FAIL, missing model, dirty vs
+snapshot, unmerged history). Unexplained leftovers fail the gate; nothing is removed by force.
 
 ```bash
-# Remove task worktrees
-git worktree list | grep '.worktrees/task-' | awk '{print $1}' | while read wt; do
-  name=$(basename "$wt")
-  git worktree remove "$wt" --force 2>/dev/null
-  git branch -D "handoff/$name" 2>/dev/null
-done
-git worktree prune
-
-# Remove integration branch if still exists
-git branch -D handoff/integration 2>/dev/null || true
+# For each task worktree, run the receipt-gated cleanup (dry-run first, then --apply):
+node .claude/ukit/index/cleanup-task-worktree.mjs \
+  --receipt <receipt-json> --approval <approval-json>          # dry-run: reports eligible/retained
+node .claude/ukit/index/cleanup-task-worktree.mjs \
+  --receipt <receipt-json> --approval <approval-json> --apply  # removes only that one verified task
+
+# A worktree with NO verified receipt/approval is RETAINED with its reason — list it:
+git worktree list          # every .worktrees/* entry must be named in the retained-reason report
+git branch | grep handoff  # every handoff/* branch must be named in the retained-reason report
 ```
 
+An unmerged `handoff/integration` branch is retained the same way: report it with its reason
+(`unmerged history`), never delete it with `-D`.
+
 ## Step 2 — Unstage any pending changes
 
 ```bash
@@ -68,7 +81,9 @@ files behind, or the next cycle resumes from stale bytes.
 ## Step 5 — Report
 
 ```
-Cleared: X worktrees removed, Y branches deleted, staged changes unstaged.
+Cleared: X receipt-gated tasks removed, staged changes unstaged.
+Retained with reason: <list each surviving worktree/branch and why — receipt missing,
+not approved, FAIL, missing model, dirty vs snapshot, unmerged history>.
 Handoff docs reset. Ready for new cycle.
 ```
 

package/template_project/.claude/commands/ukit/handoff-fullstack.md

@@ -462,43 +462,65 @@ them back a second time is what blows up the orchestrator's context window and k
 run mid-pipeline.
 ```
 
-**3c — Copy changes back + delete worktrees** (orchestrator, after each task reports):
+**3c — Land each task's work + hand off worktree state** (orchestrator, after each task reports):
+
+Landing is **task-scoped, base-relative and receipt-backed** — never an ad-hoc cp loop.
+`land-worktree.mjs` snapshots the source worktree's FINAL content against the immutable
+`$BASE` (committed milestone + staged + unstaged + nonignored untracked), so committed and
+staged work is never dropped, deletions and rename origins are applied, and binary /
+executable / symlink semantics and unusual filenames (space / newline / literal backslash)
+survive. The helper refuses on any destination conflict, scope drift or identity drift
+**before mutating anything** and writes no receipt on refusal.
 
 For **PASS + EXECUTOR_MODEL present:**
 ```bash
+TASK="TASK-xxx"
 WORKTREE=".worktrees/task-xxx"
 
-# Copy modified tracked files to main working tree
-git -C "$WORKTREE" diff --name-only | while read f; do
-  mkdir -p "$(dirname "$f")"
-  cp "$WORKTREE/$f" "$f"
-done
-
-# Copy new untracked files
-git -C "$WORKTREE" ls-files --others --exclude-standard | while read f; do
-  mkdir -p "$(dirname "$f")"
-  cp "$WORKTREE/$f" "$f"
-done
-
-# Delete worktree and branch immediately
-git worktree remove "$WORKTREE" --force
-git branch -D handoff/task-xxx
+# Scope = the exact task-approved target paths (both rename endpoints).
+# Written outside the source worktree AND outside the target set.
+cat > ".worktrees/$TASK-scope.json" <<JSON
+{
+  "schemaVersion": 1,
+  "taskId": "$TASK",
+  "baseCommit": "$(git rev-parse $BASE)",
+  "sourceRoot": "$(git -C "$WORKTREE" rev-parse --show-toplevel)",
+  "destinationRoot": "$(git rev-parse --show-toplevel)",
+  "sourceHead": "$(git -C "$WORKTREE" rev-parse HEAD)",
+  "destinationHead": "$(git rev-parse HEAD)",
+  "targetPaths": ["<each approved path>"]
+}
+JSON
+
+node .claude/ukit/index/land-worktree.mjs \
+  --scope ".worktrees/$TASK-scope.json" \
+  --receipt "docs/AI_HANDOFF/benchmark/$TASK-landing.json"
+# exit 0 → landed (receipt written); exit 2 → refused, both repos untouched;
+# exit 1 → apply/receipt failure, source retained, never a success claim.
+# After each exit-0 landing, checkpoint-commit the landed paths (receipt stays outside the target set)
+# BEFORE landing the next task: the helper refuses a destination with tracked modifications
+# (destination-dirty), so uncommitted landed work would block every later task in the wave.
+git add -- <landed paths> && git commit -m "checkpoint: $TASK landed"
+
+# update INDEX.md: status → pending_review
 ```
 
 For **FAIL:**
 ```bash
-git worktree remove .worktrees/task-xxx --force
-git branch -D handoff/task-xxx
+# Landing is refused by contract (no EXECUTOR_REPORT). Retain the worktree and branch
+# as recovery evidence and mark it in INDEX.md:
+#   status → blocked, reason "FAIL"
 ```
 
 For **EXECUTOR_MODEL missing:**
 ```bash
-git worktree remove .worktrees/task-xxx --force
-git branch -D handoff/task-xxx
-# mark needs_executor_report in INDEX
+# No model attestation → no landing authority. Retain the worktree and branch:
+#   status → needs_executor_report
 ```
 
-Worktrees are **always deleted immediately** — no exceptions.
+A refused or retained worktree keeps its source recovery evidence. Removal is a separate,
+receipt-gated step (`cleanup-task-worktree.mjs`); it is never an unconditional forced
+removal or branch deletion sitting on the same page as the landing.
 
 **3d — Wave boundary: commit + context checkpoint** (orchestrator, after every wave)
 
@@ -546,12 +568,15 @@ logs used to cost. That difference is what makes a multi-wave cycle finish in on
    - EXECUTOR_MODEL missing → `needs_executor_report`
    Then **verify the write** (read back the updated status column).
 
-2. Verify cleanup:
+2. Verify cleanup with the **retained-reason report** — not an only-main assertion:
    ```bash
-   git worktree list           # must show only main worktree
-   git branch | grep handoff   # must be empty
+   git worktree list           # every remaining .worktrees/* entry must be named in the retained-reason report
+   git branch | grep handoff   # every handoff/* branch must be named in the retained-reason report
    git diff --stat             # summary of all uncommitted changes
    ```
+   A **retained-reason report** names every surviving worktree/branch and why it stays
+   (receipt missing, not approved, FAIL, missing model, dirty vs snapshot, unmerged
+   history). Unexplained leftovers fail the gate; nothing is removed by force.
 
 ---
 
@@ -744,19 +769,27 @@ start, and emit the Final Report below.
 Run at the very end of every cycle, regardless of outcome:
 
 ```bash
-git worktree list           # must show ONLY main worktree
-git branch | grep handoff   # must be EMPTY
+git worktree list           # every remaining .worktrees/* entry must be named in the retained-reason report
+git branch | grep handoff   # every handoff/* branch must be named in the retained-reason report
 git status                  # clean (fully approved + pushed) or expected partial state
 ```
 
-If any lingering worktrees or handoff branches found, force-remove them:
+Every remaining `.worktrees/*` entry and every `handoff/*` branch must be named in a
+**retained-reason report**: receipt missing, not approved, FAIL, missing model, dirty vs
+snapshot, unmerged history. Unexplained leftovers fail the gate.
+
+If a lingering worktree carries a verified, independently approved receipt whose source
+still matches the snapshot and is Git-clean, retire it through the shared helper — never by
+forcing it:
+
 ```bash
-# For each lingering worktree/branch:
-git worktree remove .worktrees/<name> --force
-git branch -D handoff/<name>
+# For each lingering task worktree with a verified receipt + approval:
+node .claude/ukit/index/cleanup-task-worktree.mjs \
+  --receipt <receipt-json> --approval <approval-json> --apply
+# Anything without that authority is RETAINED and reported with its reason.
 ```
 
-Re-run assertions after removal to confirm clean state.
+Re-run the assertions after cleanup to confirm the same named-retention state.
 
 ---