@ngockhoale/ukit 3.4.22 → 3.4.23

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.**

package/manifests/platform.full.yaml

@@ -1653,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.22",
+  "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/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.
 
 ---
 

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

@@ -172,49 +172,64 @@ second time is what blows up the orchestrator's context window and kills the run
 
 > **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** open each task in a separate session with the code model.
 
-### 3c — Orchestrator: copy changes to main + IMMEDIATELY delete worktree
+### 3c — Orchestrator: land each task's work (task-scoped, receipt-backed)
+
+Landing uses the shared helper, never an ad-hoc cp loop. `land-worktree.mjs` snapshots
+the source worktree's FINAL content relative to the immutable `$BASE` — committed
+milestone, staged, unstaged and nonignored untracked changes, with deletions, rename
+origins and binary / executable / symlink semantics — and applies that exact delta to the
+destination. It refuses (exit 2, no mutation, no receipt) on a dirty destination, a
+target-path untracked collision, an out-of-scope change or identity drift.
 
 For each task that reported back:
 
 **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 file: 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": "$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; exit 2 → refused (untouched); exit 1 → apply/receipt failure.
+# 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
 ```
 
 **FAIL:**
 ```bash
-git worktree remove .worktrees/task-xxx --force
-git branch -D handoff/task-xxx
+# No landing for a FAIL report — retain the worktree and branch as recovery evidence.
 # update INDEX.md: status → blocked
 ```
 
 **EXECUTOR_MODEL missing:**
 ```bash
-git worktree remove .worktrees/task-xxx --force
-git branch -D handoff/task-xxx
+# No model attestation → no landing authority. Retain the worktree and branch.
 # update INDEX.md: status → needs_executor_report
 ```
 
 **Orchestrator writes INDEX.md** — agents never touch INDEX directly.
-**Worktrees are always deleted immediately** — no exceptions.
+Worktree/branch removal is a separate, receipt-gated step (`cleanup-task-worktree.mjs`) —
+never an unconditional forced removal or branch deletion sitting next to the landing.
 
 ### 3d — Wave boundary: commit + context checkpoint
 
@@ -246,12 +261,18 @@ Then create the next wave's worktrees from `$BASE` and repeat 3a–3c.
 All waves complete. Verify:
 
 ```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 log --oneline -n 10    # one commit per wave
 git status                 # clean, or only trailing edits from the last wave
 ```
 
+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; nothing is removed by force.
+An eligible task is retired only through the shared, receipt-gated helper
+(`node .claude/ukit/index/cleanup-task-worktree.mjs --receipt <json> --approval <json> --apply`).
+
 All changes are committed as **one commit per wave on `$BASE`**, nothing pushed. No branches
 or worktrees remain. Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
 

package/template_project/.claude/hooks/handoff-resume.sh

@@ -196,11 +196,21 @@ async function emitOrdinaryResume(payload, source) {
   // The session's CURRENT handoff intent — structured transcript evidence, the
   // same shared module the Stop gate uses. A session whose latest request is
   // planning (`/ukit:handoff-create`) must never be pushed into implementing a
-  // stale RUN.md, compact or not. `known` false (no transcript path, unreadable,
-  // module absent) keeps the existing resume behaviour.
+  // stale RUN.md, compact or not. `intent` is null when the read was unknown (no
+  // transcript path, unreadable, module absent), which the planning-cursor branch
+  // below treats the same as create — a NONTERMINAL `Command: handoff-create`
+  // cursor is the planner's file, so an unknown read resolves toward planning.
   const { intent } = await readHandoffIntent(
     typeof payload.transcript_path === 'string' ? payload.transcript_path : null,
   );
+  // A NONTERMINAL planning cursor is the one RUN.md the resume lane treats as
+  // planning rather than implementation (TASK-C97-006, FR-M2-003): its `Command`
+  // says a planner owns the file, so any latest intent that is NOT positively
+  // implementation (create, known-null, unknown) gets the planning note. Every
+  // other command — actual fullstack/implement/review — keeps the unchanged
+  // contract, and an unknown intent there still resolves toward the conservative
+  // resume, so a lost read never strands a real run.
+  const planningCursor = field('Command').trim().toLowerCase() === 'handoff-create';
 
   // A brand-new session (startup / clear) did not start this run and may be about
   // something else entirely (e.g. planning). Tell it the run exists, but do NOT
@@ -216,17 +226,32 @@ async function emitOrdinaryResume(payload, source) {
     process.exit(0);
   }
 
-  // Planning intent outranks a live cursor: the user asked this session to plan,
-  // so report the paused run and let the planning continue. This is the one place
-  // an automatic resume must yield — /ukit:handoff-create is planning-only by
-  // contract, and /ukit:handoff-fullstack remains the explicit way to resume.
-  if (intent === 'create') {
+  // Planning outranks a live cursor: the user asked this session to plan (or the
+  // cursor itself is the planner's `handoff-create` RUN.md with no positive
+  // implementation intent), so report the paused run and let the planning
+  // continue. This is the one place an automatic resume must yield —
+  // /ukit:handoff-create is planning-only by contract, and /ukit:handoff-fullstack
+  // remains the explicit way to resume.
+  if (intent === 'create' || (planningCursor && intent !== 'fullstack')) {
+    // The reason is stated honestly either way — the session's own request is
+    // planning (create), or the cursor itself is the planner's `handoff-create`
+    // RUN.md with no positive implementation intent. Neither fabricates ownership.
+    const why = intent === 'create'
+      ? [
+        "but this session's current request",
+        'is planning (/ukit:handoff-create). Stop gate and resume will not force the run here —',
+        'finish the planning first. To resume implementation explicitly, run /ukit:handoff-fullstack;',
+        'to discard the run, /ukit:handoff-clear.',
+      ]
+      : [
+        `and its cursor is planning-only (Command: ${field('Command')}). Neither the Stop gate nor this`,
+        'resume will force implementation here. To resume implementation explicitly, run',
+        '/ukit:handoff-fullstack; to discard the run, /ukit:handoff-clear.',
+      ];
     process.stdout.write([
       'UKit note: docs/AI_HANDOFF/RUN.md has an unfinished handoff-fullstack run '
-        + `(Phase: ${phase}; Next: ${next || 'not recorded'}), but this session's current request`,
-      'is planning (/ukit:handoff-create). Stop gate and resume will not force the run here —',
-      'finish the planning first. To resume implementation explicitly, run /ukit:handoff-fullstack;',
-      'to discard the run, /ukit:handoff-clear.',
+        + `(Phase: ${phase}; Next: ${next || 'not recorded'}),`,
+      ...why,
     ].join('\n') + '\n');
     process.exit(0);
   }

package/template_project/.claude/hooks/protect-files.sh

@@ -102,7 +102,15 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
-BASENAME=$(basename "$FILE_PATH")
+# TASK-C97-008 (FR-M3-002): match backslash / Windows-shaped spellings the same
+# as forward-slash ones. Normalize separators for LEXICAL basename/component
+# matching ONLY — no filesystem resolution, no path writes, and no native
+# Windows claim. `${var//pat/rep}` is a bash builtin, so this holds with or
+# without jq. The original path stays in the stderr diagnostic; stdout keeps the
+# generic reason and never exposes it.
+MATCH_PATH="${FILE_PATH//\\//}"
+
+BASENAME=$(basename "$MATCH_PATH")
 
 # Allow .env.example explicitly
 if [[ "$BASENAME" == ".env.example" ]]; then
@@ -112,7 +120,7 @@ fi
 # Match exact sensitive filenames and directory components, never arbitrary substrings:
 # `.env.d.ts` and `app.envrc` are source files, not secrets. The old `*".env"*`
 # check blocked both, which could appear as a mysterious stopped edit.
-PATH_SLASHED="/${FILE_PATH#/}"
+PATH_SLASHED="/${MATCH_PATH#/}"
 PROTECTED_MATCH=""
 case "$BASENAME" in
   .env|.env.local|.env.production|package-lock.json|yarn.lock)

package/template_project/.claude/hooks/vision-router.sh

@@ -326,6 +326,13 @@ async function readTextSafe(filePath) {
   const pendingMarkers = Array.isArray(extractorJson?.pendingMarkers)
     ? extractorJson.pendingMarkers
     : [];
+  // Additive (SPEC FR-M5-001 §7/§8): a currently-named input whose marker already
+  // existed is NOT newly armed, so it must not drive the NEW hint. It is still a
+  // KNOWN local ref, so it must not fall through to the unresolved-path advisory
+  // either. Absent (older extractor) degrades to [], i.e. today's behavior.
+  const alreadyPending = Array.isArray(extractorJson?.alreadyPending)
+    ? extractorJson.alreadyPending
+    : [];
   const analyzed = Array.isArray(extractorJson?.alreadyAnalyzed) ? extractorJson.alreadyAnalyzed : [];
   const sessionId = typeof extractorJson?.sessionId === 'string' && extractorJson.sessionId
     ? extractorJson.sessionId
@@ -334,9 +341,12 @@ async function readTextSafe(filePath) {
   const armedRefs = new Set(
     pendingMarkers.filter((m) => typeof m?.ref === 'string').map((m) => m.ref)
   );
+  const pendingRefs = new Set(
+    alreadyPending.filter((m) => typeof m?.ref === 'string').map((m) => m.ref)
+  );
   const analyzedRefs = new Set(analyzed.filter((a) => typeof a?.ref === 'string').map((a) => a.ref));
   const unresolvedLocal = localMatches.filter(
-    (m) => !armedRefs.has(m.trim()) && !analyzedRefs.has(m.trim())
+    (m) => !armedRefs.has(m.trim()) && !pendingRefs.has(m.trim()) && !analyzedRefs.has(m.trim())
   );
   const cases = [];
   if (pendingMarkers.some((m) => !m?.source)) cases.push('pasted image');