@ngockhoale/ukit 3.4.22 → 3.4.24

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');