@ngockhoale/ukit 3.4.66 → 3.4.68

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

@@ -74,7 +74,12 @@ resumable. If compaction does happen, the run resumes from the cursor automatica
 ### Run cursor — write after every step
 
 Maintain `docs/AI_HANDOFF/RUN.md`. Rewrite it (whole file — the fixed field block below,
-exactly as many lines as the fields in play) immediately after every numbered step completes:
+exactly as many lines as the fields in play) immediately after every numbered step completes.
+Before dispatching any mutating worker (including blueprint folding), write and read back the
+P0/P1 cursor with the actual phase, frozen scope, next action and known job references. Do not
+defer cursor creation until P2; omit ExitPredicate until P2 pins it, never invent a satisfied one.
+Reconcile partial writes and existing jobs from that cursor on interruption; never restart the fold blindly.
+
 
 ```
 Command: handoff-fullstack
@@ -92,6 +97,8 @@ RetryFingerprint: <stable id of the failing step>   # optional; retry-loop ident
 RetryCount: <n>   # optional; consecutive attempts of that fingerprint
 ScopePlans: <slug[,slug...]> | none   # optional; history/archive/Ready-for-AI items the invocation authorized
 ScopeQueue: <slug[,slug...]> | none   # optional; the queued blueprints frozen into this run at P2
+TaskScope: cycle-<NN>/TASK-001 = queue:<slug>   # repeat per imported task; cycle-qualified key (TASK ids are reused across cycles); plan:<ScopePlans entry> for an authorized plan
+TaskScope: cycle-<NN>/TASK-001-R1 = repair:TASK-001   # unqualified parent = same cycle; repair:cycle-<NN>/TASK-xxx pins an explicit older-cycle parent
 Authorization: <one line — who authorized the scope and from which invocation>   # optional
 LateCreate: <slug> — <disposition>   # optional; a create that arrived mid-run, never auto-folded
 ```
@@ -104,7 +111,29 @@ session boundaries; they never replace INDEX.md or RUN.md authority.
 
 **Late creates do not expand scope.** A blueprint or Ready-for-AI item that appears mid-run and is
 not in `ScopeQueue`/`ScopePlans` is recorded as `LateCreate:` with disposition `Backlog`. A late create does not expand scope and is never silently folded in. Repairs of work already assigned to this run
-still continue.
+still continue. When folding a blueprint or authorized plan into INDEX, stamp a repeated
+`TaskScope:` line for every assigned task in RUN.md. A repair/replan stamps `repair:<original task>`
+(unqualified parent resolves in the same cycle) or `repair:cycle-<NN>/<original task>` (explicit
+older-cycle parent) and inherits that task's scope, including across repair chains — never
+unrelated late scope.
+
+**Task ids are reused across cycles — qualify scope keys.** Stamp every new `TaskScope:` mapping
+cycle-qualified (`cycle-<NN>/TASK-001`, same spelling the run's `Cycle:` field and claim cycles
+normalize to). A task id reused in a later cycle never overwrites or inherits an earlier cycle's
+scope or repair chain: the current cycle's mapping governs the live INDEX evaluation and each
+archive cycle's mapping governs its ARCHIVE snapshot. Preserve ALL mapping lines on disk across
+compaction, resume and cycle transition — retain the original mapping even after its task closes;
+never rewrite or drop an older cycle's lines when opening the next cycle. Legacy unqualified
+mappings stay honored only while no other cycle qualified the same id; an unqualified mapping that
+collides with a cycle-qualified one is ambiguous and keeps the run in reconciliation instead of
+guessing the old cycle. Completion, blocked and archive predicates use the same membership
+selector: exclude only a task mapped to a different cycle/queue than the one being evaluated, and
+refuse completion while any in-scope mapping is unresolved — unknown, conflicting, malformed,
+cyclic or ambiguous mappings remain included and require reconciliation against the source before
+declaring completion; never guess away unmapped obligations. The resume hook prints a bounded
+slice of the frozen map (the current cycle plus the CurrentTask repair chain, hard-capped); the
+full map is never truncated on disk — read `docs/AI_HANDOFF/RUN.md` for the remainder. Legacy runs
+without frozen scope retain all INDEX rows. The eight-column INDEX format is unchanged.
 
 **Compact-carry fields.** `Acceptance`, `CurrentTask`, `RetryFingerprint` and `RetryCount`
 are what a compacted session carries forward — these four lines plus `Goal`/`Next:`, never
@@ -175,11 +204,13 @@ skipped silently.
 
 `Phase: blocked` is terminal for the run — the machinery (Stop gate, hooks, stop-coordinator)
 all treats it as closed. It is *paused*, not abandoned: an explicit `/ukit:handoff-fullstack`
-re-invocation resumes it as a continuation; `ukit handoff-clear` abandons it. Only when
+re-invocation resumes it as a continuation; `ukit handoff-clear` pauses it (`Paused: yes`, backlog and scope kept, no completion minted). Only when
 `RUN.md` is absent or `Phase: done` does a new request start a fresh cycle.
 
 ### Explicit invocation reacquires ownership
 
+An explicit `/ukit:handoff-fullstack` also lifts a liveness pause: the resume hook rewrites `Paused: yes` to `Paused: no` in `RUN.md`, reads it back, and keeps `Phase:`, scope, and the queue untouched. Ordinary prompts, startup, and clear never lift it.
+
 `/ukit:handoff-create` is planning-only and makes a session's handoff intent *planning* — so
 while the human is planning, neither the Stop gate nor the SessionStart compact/resume hook
 forces a paused run back into implementation. This command is the explicit counter-action:
@@ -226,6 +257,57 @@ Never stop at `recap: ... Next: ...` while unfinished work remains — the Stop
 bounces that stop straight back into the pipeline, so stopping is not even restful; it
 just costs a round-trip.
 
+### Pre-stop reconciliation — decide the stop, never rely on the bounce
+
+The Stop gate is the **backstop, never the plan**. Before ANY turn ends — mid-wave or at
+the end of the pipeline — reconcile the run once, explicitly, against this checklist and
+then choose the ending yourself:
+
+1. **Tasks** — every in-scope task is `done`/`cancelled_superseded`, or its real phase and
+   next step are in the cursor. Nothing is left "almost done" without a record.
+2. **Acceptance** — every done task's acceptance criteria carry verification evidence on
+   disk (command + output). Never waived, never assumed.
+3. **Findings** — every review/plan finding is dispositioned: fixed, or recorded as
+   `changes_requested`/`needs_breakdown` with its open signature. Nothing silently open.
+4. **Jobs** — every spawned agent/background job is awaited through the host's own
+   mechanics (agent task result, background-shell output) and its report is consumed into
+   run state before the next step. NEVER spawn a second job for work a live job is
+   already doing — await the live one and consume its result.
+5. **Independent work** — a blocked or waiting branch never strands independent tasks:
+   they ran first (Autonomy Contract).
+6. **Integration** — landed work is committed (scoped `--only` commits); worktrees and
+   branches are cleaned, or every survivor is named in the retained-reason report.
+7. **Release** — the run's single push (R5) happened, or the reason it did not is named.
+8. **Consumer** — when a task or the goal names consumer/release evidence, it is recorded;
+   a missing consumer gate is work remaining, not a stop.
+9. **Pause** — a pause (`Paused: yes`, set via `ukit handoff-clear` or an explicit user
+   instruction) releases the session: the backlog is retained, completion is never
+   minted, and nothing resumes until an explicit instruction lifts the pause.
+10. **Blocker** — `HANDOFF FULLSTACK BLOCKED` only when every remaining task shares one
+    valid external blocker, evidence and attempted fixes are recorded, and no safe local
+    work exists.
+
+**Turn wait ≠ run done.** If reconciliation leaves a live job running, a host async
+result pending, or any checklist item open, the correct outcome is a **turn wait**: bound
+the wait with the host's own mechanics, write the CHECKPOINT block above (cursor updated:
+YES), and keep the run alive. A turn wait is never `Phase: done` and never claims
+completion. If the wait ends in a compaction, the cursor plus the SessionStart resume
+hook continue the run — never a manual `/compact` instruction loop. If Ready independent
+work exists, select and run it first; a turn wait is only for an actual pending host event
+with no runnable independent scope. **Pause** (`Paused: yes`) and **cancel** are releases,
+not completion: they emit no terminal line and mint nothing. **Blocked** is a terminal
+release, not done: `HANDOFF FULLSTACK BLOCKED` is emitted only when no safe local work
+remains. **Run done** is only §0's `HANDOFF FULLSTACK COMPLETE` after F4, with the checklist
+green item by item. The Final Report states scope-complete and correct termination as two
+separate facts.
+
+**Completed runs are not restarted by their own echo.** If this session is re-invoked (a
+stale watchdog job, a repeated prompt, a queued wakeup) and `RUN.md` still reads
+`Phase: done` with its ExitPredicate satisfied, the invocation is a **no-op**: re-verify
+the predicate cheaply, re-emit the completion report if one is due, disarm the stale
+watchdog job, and stop. A new cycle starts ONLY from a new explicit user request — never
+from the run's own completion echo.
+
 ---
 
 ## Phase 0 — Sweep & Inventory (before planning)
@@ -256,7 +338,15 @@ work, not only the current plan:
    so it is folded in here like any legacy blueprint and is never silently excluded.
    Backlog items do not count toward `index:all-done` / `ExitPredicate`, so they never block completion. Only
    an explicit slug in the invocation drains one (one blueprint per invocation). The
-   create phase of this command applies the same advisor intake as `/ukit:handoff-create`.
+   create phase of this command applies the same advisor intake as `/ukit:handoff-create`
+   — including the SOURCE snapshot (`node .claude/ukit/index/source-snapshot.mjs
+   <original-path> docs/AI_HANDOFF/SOURCE.md`, or `source snapshot MISSING` stated in
+   PLAN/LEDGER when it cannot run) and the plan-count rule: an owner-stated plan count is
+   delivered as that many real plans (the first under the planning root, each further one
+   its own `docs/AI_HANDOFF/queued/<slug>/` blueprint with its own SPEC.md/PLAN.md/tasks/;
+   labels inside one PLAN never satisfy a stated count; verify mechanically with
+   `node .claude/ukit/index/plan-count.mjs docs/AI_HANDOFF <N>` → `PLAN_COUNT: ok (<found>/<N>)`;
+   if impossible, record an explicit owner-decision item).
 6. `git status` / `git diff` — uncommitted work-in-progress that must be finished or
    checkpointed, never silently dropped.
 
@@ -264,10 +354,19 @@ The inventory feeds P2: the planner either schedules every discovered item or re
 it is out of scope (§1/§2 of PLAN.md). Silent omission is a plan defect — a queued
 blueprint dropped without either scheduling or a recorded reason is exactly that defect.
 
-> **Never overwrite a live run to consume a queued blueprint.** A blueprint is folded in
-> only through P2's normal plan-write path, and only when no run is mid-flight; on a
-> Resume (RUN.md `Phase:` not `done`/`blocked`) the run continues from its own cursor and
-> leaves the queued blueprint untouched for the next cycle.
+**Resume gates before planning.** If INDEX.md has `needs_breakdown` rows and PLAN.md has no
+`PLAN_REVIEW: Approved`, a previous planning run died before both gates completed: do NOT
+re-intake the request, do NOT re-run the advisor chain, do NOT rewrite SPEC/PLAN/tasks, and
+never overwrite the existing plan on this path. Run only the missing gates on the existing
+plan — the per-task validator (`--record`, P2 step 5) for tasks lacking a recorded
+`Validator:` line, and the P2.5 independent review — then flip per the ready gate and
+continue from P3. If a gate cannot run, leave the statuses as they are and name the missing
+gate in INDEX.md and ACTIVE.md.
+
+> **Never overwrite a live run to consume a queued blueprint.** Fold only through P2's
+> normal plan-write path. On Resume, continue an already-authorized fold recorded in the
+> cursor's frozen scope and `Next:`; reconcile partial writes and existing jobs first.
+> Do not admit unrelated queued blueprints: leave those untouched for the next cycle.
 
 **Recovery rule — stuck task records.** For every `pending`, stale `in_progress`, or
 `blocked` task whose record cannot be cleanly resumed (invalid state, orphaned worktree
@@ -294,10 +393,12 @@ The run must keep itself alive without the human watching.
   (`handoff.fullstack.stopGateMaxStalledBlocks`, default 12) releases the session if the
   cursor has genuinely stopped advancing — the escape hatch, not the norm — and its
   release advisory reports the predicate state, so a plateau is visible, not silent.
-- **Scheduled wakeup (when the harness offers one):** arm it at run start — Claude Code:
-  `CronCreate` a ~`handoff.fullstack.idleWatchdogMin`-minute (default 5) session job with
-  prompt `Resume HANDOFF FULLSTACK from docs/AI_HANDOFF/RUN.md — continue the Next: step`;
-  `/loop`-style tools: the equivalent interval. Cancel/let it expire once `Phase: done`.
+- **Scheduled wakeup (when the harness offers one):** use the supported host event wait, not
+  a polling job. Do not create a duplicate job: arm at most one resume wakeup while a real
+  host event is pending, and cancel it on pause, cancel, blocker, or completion
+  (`Phase: done` / `blocked` / `Paused: yes`). Claude Code's supported mechanics are the
+  Stop gate and SessionStart resume hook; `CronCreate` is used only when the harness offers no
+  event wait.
 - **Harnesses with neither:** treat EVERY activation as a watchdog recovery turn — read
   RUN.md first, rescan the inventory, continue `Next:`.
 
@@ -335,14 +436,20 @@ Return a compact summary. Do NOT write any files yet.
 The planner agent does the following (use P1 summary — do NOT re-read files):
 
 1. **Guard — check INDEX statuses:**
-   - All tasks are `ready` (planning only) → **only an explicit amendment may overwrite**: when the human explicitly names this plan to amend, first copy every prior file (PLAN.md, SPEC.md, LEDGER.md, NOTES.md, SOURCE.md, tasks/TASK-*.md, when present) to the next unused `amendments/rev-<NN>/` (scan existing rev dirs, take max+1, never reuse one). Then compose the revised PLAN.md in full: carry the existing `## Amendment History` forward and append this amendment's entry (prior review rounds and verdicts; prior requirement, decision and task versions with what changed and why; each change's `invalidated` evidence: tasks, executor reports, verdicts that no longer hold). Write the revised PLAN.md only after that entry is in the composed text, so the overwrite can never drop the history. An **independent new request** is NOT an amendment: write its plan under `docs/AI_HANDOFF/queued/<slug>/` (the queued lane, see Phase 0) and never overwrite the existing canonical plan.
+   - **Resume gates — `needs_breakdown` rows and PLAN.md without `PLAN_REVIEW: Approved`:**
+     a previous planning run died before both gates. Never re-intake and never rewrite
+     SPEC/PLAN/tasks, never overwrite the existing plan. Run only the missing gates on the
+     existing plan — the per-task validator (`--record`, step 5 below) for tasks lacking a
+     recorded `Validator:` line and the P2.5 independent review — flip per the ready gate,
+     and report; the orchestrator continues from P3.
+   - All tasks are `ready` (planning only) → **only an explicit amendment may overwrite**: when the human explicitly names this plan to amend, first copy every prior file (PLAN.md, SPEC.md, LEDGER.md, NOTES.md, SOURCE.md, tasks/TASK-*.md, when present) to the next unused `amendments/rev-<NN>/` (scan existing rev dirs, take max+1, never reuse one). Then run the mechanical guard ONCE — `node .claude/ukit/index/amend-guard.mjs docs/AI_HANDOFF PLAN.md SPEC.md`, naming every file about to be rewritten — and proceed only on `AMEND_GUARD: ok` (the checker is mechanical; its invocation is prose). Then compose the revised PLAN.md in full: carry the existing `## Amendment History` forward and append this amendment's entry (prior review rounds and verdicts; prior requirement, decision and task versions with what changed and why; each change's `invalidated` evidence: tasks, executor reports, verdicts that no longer hold). Write the revised PLAN.md only after that entry is in the composed text, so the overwrite can never drop the history. An **independent new request** is NOT an amendment: write its plan under `docs/AI_HANDOFF/queued/<slug>/` (the queued lane, see Phase 0) and never overwrite the existing canonical plan.
    - Any task has status `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite, and do not stop either.** Mid-flight work exists. Skip the rest of P2 entirely, write the run cursor with `Phase: I1`, and hand control back to the orchestrator to resume from Phase 3 with the surviving tasks (see Resume in the Autonomy Contract). Overwriting is what is unsafe here — stopping is not required.
    - No tasks → fresh cycle, proceed.
 
-2. **Resolve base branch:**
-   ```bash
-   BASE=$(git symbolic-ref --short HEAD)
-   ```
+2. **Resolve base branch:** run ONE simple command — `git symbolic-ref --short HEAD` — and
+   use the printed branch name as a literal (`<base-branch>`) in ACTIVE.md's `Base:` line
+   and in every later command (worktree creation, final push). No assignment, no command
+   substitution, no compound.
 
 3. **Write `docs/AI_HANDOFF/SPEC.md`** — the detailed implementation spec, from
    `template_project/docs/AI_HANDOFF/SPEC.md`'s section list (or RULES.md §Spec). It must be
@@ -370,16 +477,36 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    Every task MUST have:
    - Spec references (SPEC.md section IDs this task implements)
    - Target Files (exact paths — no two tasks in same wave share a file)
-   - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this)
-   - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds)
+   - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this; a source delivery-order qualifier like "after import works" IS a dependency, name its source line)
+   - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds; every Expected is ONE deterministic outcome, never "X or nothing")
    - Test Files (exact paths)
-   - Verification Commands (runnable shell commands)
+   - Verification Commands (runnable shell commands that run the tests — grepping a doc for a literal line such as `Coverage: N/N` is not evidence)
    - Acceptance Criteria (verifiable checklist)
    Missing any field → status `needs_breakdown`, never `ready`.
-
-6. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`. Every
+   Write every task file `Status: needs_breakdown` — `ready` is a verdict, not a default —
+   and run the task-budget validator on each file as ONE simple command per task, from the
+   project root, literal path, no `cd`, no loop, no shell variables, no pipes, no compound:
+   ```
+   node .claude/ukit/index/task-budget-validator.mjs docs/AI_HANDOFF/tasks/TASK-001.md
+   ```
+   Repeat the command per task file (eight tasks = eight separate calls). `VERDICT:
+   needs_breakdown` → split further, or record a one-line dismissal in the task's
+   `## Discussion`. Nothing is `ready` until P2.5 returns `Approved`.
+   Right after each `VERDICT: ok`, record it from the tool itself with ONE simple command
+   per task — `node .claude/ukit/index/task-budget-validator.mjs --record docs/AI_HANDOFF/tasks/TASK-001.md` — which re-validates and appends
+   `Validator: ok <YYYY-MM-DD> <tool-version>` to that task's `## Discussion` thread
+   (atomic temp-file + rename, existing BOM and line endings preserved, idempotent — a
+   second run never duplicates the line — and it refuses a non-ok verdict, so a
+   `needs_breakdown` file is never recorded). A dismissal stays a hand-written one-liner:
+   `Validator: dismissed <YYYY-MM-DD> — <reason>`. Verdicts live on disk, not in session
+   memory: compaction must not erase a gate.
+
+6. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, starting
+   `status=needs_breakdown`; P2.5's `Approved` verdict is what sets `ready` (every
    unfinished item from the Phase 0 sweep is either a row here or superseded by a
-   `-R<n>` recovery row.
+   `-R<n>` recovery row). If the run ends before both gates completed (budget exhausted,
+   command denied, interruption), the rows stay `needs_breakdown`, and INDEX.md and
+   ACTIVE.md must say which gate is missing.
    Then **verify the write** (read back the new rows).
 
 7. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
@@ -390,6 +517,10 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
+   When the gates have not all passed, write the honest state instead:
+   `Status: planning_incomplete — tasks not ready: <validator | plan review>` (a
+   human-readable ACTIVE.md marker only — machine readers parse INDEX.md rows and
+   task-file `- Status:` lines, never write `planning_incomplete` into those).
    Then **verify the write** (read back the `Status:` line).
 
 8. **Write `ExitPredicate:` into `docs/AI_HANDOFF/RUN.md`** — the mechanical definition of
@@ -419,9 +550,9 @@ The gate still does its job: two independent opus passes plus one escalation pas
 
 **Claude Code — MANDATORY, do this before anything else in P2.5:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the paths to `docs/AI_HANDOFF/PLAN.md` AND `docs/AI_HANDOFF/SPEC.md`. This MUST be a separate agent invocation from P2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
 
-1. Reviewer reads `SPEC.md` + `PLAN.md` plus the plan's sources, starting from the original: `SOURCE.md` (the verbatim original bytes; verify the recorded sha256 against them; for chat input, the durable verbatim message origin stands in for the file), then `LEDGER.md` (classification of every requirement), `NOTES.md` (optional source-only notes, when present; a missing note is caught because the chain starts at SOURCE, not at NOTES), the `tasks/TASK-*.md` files of the plan, and the current source the plan's Target Files touch (no diff, no executor report). It compares the chain SOURCE → classification (LEDGER) → tasks (acceptance and verification), and NOTES are checked against the same chain. Each `feasible`/`adapted` row maps to a task with acceptance and a verification command; it checks that every `feasible`/`adapted` row and every requirement not explicitly deferred, blocked, or classified as rejected/proposal/example is covered by a task with acceptance and verification, and checks Completeness / Consistency / Clarity / Scope / YAGNI plus the spec quality gate — every requirement testable, every fullstack layer covered, dependencies explicit, legacy sweep included, no vague instruction left ("improve UI" without defined behavior fails) — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
+1. Reviewer reads `SPEC.md` + `PLAN.md` plus the plan's sources, starting from the original: `SOURCE.md` (the verbatim original bytes; verify the recorded sha256 against them; for chat input, the durable verbatim message origin stands in for the file), then `LEDGER.md` (classification of every requirement), `NOTES.md` (optional source-only notes, when present; a missing note is caught because the chain starts at SOURCE, not at NOTES), the `tasks/TASK-*.md` files of the plan, and the current source the plan's Target Files touch (no diff, no executor report). It compares the chain SOURCE → classification (LEDGER) → tasks (acceptance and verification), and NOTES are checked against the same chain. Each `feasible`/`adapted` row maps to a task with acceptance and a verification command; it checks that every `feasible`/`adapted` row and every requirement not explicitly deferred, blocked, or classified as rejected/proposal/example is covered by a task with acceptance and verification, and checks Completeness / Consistency / Clarity / Scope / YAGNI plus the spec quality gate — every requirement testable, every fullstack layer covered, dependencies explicit, legacy sweep included, no vague instruction left ("improve UI" without defined behavior fails) — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and returns its verdict block; the planner appends it with `Edit` to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
 2. `Issues Found` → route back to P2: `handoff-planner` revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for one more P2.5 review round — subject to the loop cap above.
-3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed to P3.
+3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer. Before any flip, run the mechanical ready gate ONCE — `node .claude/ukit/index/ready-gate.mjs docs/AI_HANDOFF` — and require `READY_GATE: ok`; any `tasks not ready: …` / `index/task mismatch …` line names the exact gap to fix and re-run, and no task flips while it fails. That verdict is the second readiness gate: flip ONLY the tasks whose task file's `## Discussion` records `Validator: ok <date>` (or `Validator: dismissed <date> — <reason>`) to `Status: ready` in that task file and in `INDEX.md` — re-read each task file from disk to decide, never from session memory; a task without the recorded `Validator:` line stays `needs_breakdown` (a verdict held only in the session does not count) — and set ACTIVE.md to `Status: planning_done — ready for executor` — P3 and the I-phase only ever collect `ready` tasks, so a skipped flip stalls the whole run. Then proceed to P3.
 
 > **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model in a **separate** chat/session from P2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
 
@@ -515,11 +646,20 @@ leaves worktrees behind. Batching only ever narrows a wave, never reorders acros
 
 For each wave:
 
-**3a — Create worktrees** (one per task, from `$BASE`):
+**3a — Create worktrees** (one per task, from the `<base-branch>` literal recorded at P2 — ACTIVE.md `Base:`):
+Under `Worktree-Policy: existing-only`, raw worktree mutation and Agent isolation remain forbidden.
+Only an explicit owner-authorized RUN.md entry such as
+`Worktree-Allow: TASK-003 handoff/task-003 .worktrees/task-003 owner-20261025`
+permits that frozen task through `node .claude/ukit/index/allocate-task-worktree.mjs <absolute-project-root> TASK-003`.
+The helper exclusively records task/branch/path/claim/base before allocation under the claims lock;
+an existing intent refuses reallocation even after failure. Resume only that task's verified retained
+worktree; never repurpose/delete a tree, allocate reviewer/investigator trees, or infer cleanup permission.
+Without this restricted policy, use the normal command:
 ```bash
-git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
-# (omit -b if branch already exists)
+git worktree add -b handoff/task-xxx .worktrees/task-xxx <base-branch>
 ```
+(Omit `-b` when the branch already exists. One simple command per worktree — no variable,
+no compound.)
 
 **3b — Run the batch in parallel** — one code-model agent per task in the batch (at most `handoff.maxParallelAgents`), each in its own worktree. Each agent:
 ```
@@ -527,12 +667,12 @@ Read docs/AI_HANDOFF/tasks/TASK-xxx.md
 
 TDD — mandatory:
   1. Write tests from §Test Cases
-     cd .worktrees/task-xxx && <test command>
+     run <test command> from the worktree root (your cwd IS .worktrees/task-xxx — no cd)
      Confirm RED — paste the actual failing output, don't just assert it happened
      (immediately GREEN → test is wrong — flag this)
   2. Implement → run → confirm GREEN
   3. Run §Verification Commands inside the worktree:
-     cd .worktrees/task-xxx && <each verification command>
+     run <each verification command> from the worktree root — no cd, no compound
      Paste full output.
 
 Milestone commits INSIDE your own worktree (e.g. `handoff/task-xxx`) are REQUIRED by the
@@ -570,45 +710,67 @@ run mid-pipeline.
 
 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
+`<base-branch>` head (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"
-
-# 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 --only -m "checkpoint: $TASK landed" -- <landed paths>
-
-# update INDEX.md: status → pending_review
-```
+
+1. Write the scope file with the **Write tool** (never a shell heredoc, no variable) to
+   `docs/AI_HANDOFF/benchmark/TASK-xxx-scope.json` — every field a literal. Get each value with ONE simple
+   command and paste the printed output: `git rev-parse <base-branch>` (baseCommit),
+   `git -C .worktrees/task-xxx rev-parse --show-toplevel` (sourceRoot),
+   `git rev-parse --show-toplevel` (destinationRoot),
+   `git -C .worktrees/task-xxx rev-parse HEAD` (sourceHead), `git rev-parse HEAD`
+   (destinationHead).
+   ```json
+   {
+     "schemaVersion": 1,
+     "taskId": "TASK-xxx",
+     "baseCommit": "<base-branch head sha>",
+     "sourceRoot": "<absolute worktree root>",
+     "destinationRoot": "<absolute project root>",
+     "sourceHead": "<worktree HEAD sha>",
+     "destinationHead": "<project HEAD sha>",
+     "targetPaths": ["<each approved path>"]
+   }
+   ```
+   Scope = the exact task-approved target paths (both rename endpoints); the file is
+   written outside the source worktree AND outside the target set. This is coordinator metadata,
+   not task implementation: keep it in the docs benchmark directory so the main-session
+   ownership guard remains intact.
+2. Land with ONE simple command, literal paths:
+   `node .claude/ukit/index/land-worktree.mjs --scope docs/AI_HANDOFF/benchmark/TASK-xxx-scope.json --receipt docs/AI_HANDOFF/benchmark/TASK-xxx-landing.json`
+   — exit 0 → landed (receipt written); exit 2 → refused, both repos untouched; exit 1 →
+   apply/receipt failure, source retained, never a success claim. Landing is self-fencing: it reads the destination claims store under the claims lock held through apply+receipt, and exits 2 `worker-not-terminated` while any delegated worker claim for the task remains (handback must release it; lease expiry does not), or `claims-unreadable`/`claims-busy` (fail closed). Never fabricate a claim or receipt to pass.
+3. 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.
+   ```bash
+   git add -- <landed paths>
+   git commit --only -m "checkpoint: TASK-xxx landed" -- <landed paths>
+   ```
+4. Update INDEX.md: status → pending_review (the orchestrator writes it; agents never do).
+
+**Already-applied / divergent-history recovery:** normal landing steps above do not turn
+all exit-0 helper results into landed status. `--adopt-applied` requires complete source
+snapshot blob+mode equality. Where preserved task-record history differs, do not repeat a
+known-failing adoption, copy metadata, omit scope, or fabricate a landed receipt. Explicit
+owner-authorized recovery uses `--reconcile-metadata <proof-json> --preflight --scope
+<scope-json> --receipt <new-json>` for ALL affected full scopes first, then the same command
+without `--preflight`. File evidence is hash-pinned and colocated with the proof in its audit
+directory; independently audit semantic provenance, which hashes alone cannot establish.
+Consume `receiptKind: metadata-reconciliation`, `status: reconciled` only with
+`completion:false`, `cleanupEligible:false` and matching current HEAD/snapshot/scope.
+It resolves specifically verified integration-history debt, NOT task completion or normal
+landing. Retain blocked status until independent current-source review and missing gates
+justify progression; continue those gates on destination source without another equality
+adoption attempt. No automatic pending_review/done, cleanup, archive or completion authority
+comes from reconciliation. Preserve both histories and source worktrees; separate acceptance,
+archive and cleanup gates and owner prohibitions remain binding.
 
 For **FAIL:**
 ```bash
@@ -701,10 +863,9 @@ git status       # should show modified/new files, no handoff branches/worktrees
 git diff --stat  # summary of all changes
 ```
 
-Because 3d commits each wave, the changes under review are in **commits since the plan commit**, not only in the working tree. Resolve the review range once and use it everywhere below:
+Because 3d commits each wave, the changes under review are in **commits since the plan commit**, not only in the working tree. Resolve the review range once: run ONE simple command — `git log --format=%H --grep='^handoff: plan' -n 1` — and use the printed hash as a literal (`<plan-commit>`) everywhere below:
 ```bash
-PLAN_COMMIT=$(git log --format=%H --grep='^handoff: plan' -n 1)
-git diff $PLAN_COMMIT   # all handoff changes: committed waves + anything uncommitted
+git diff <plan-commit>   # all handoff changes: committed waves + anything uncommitted
 ```
 
 Classify the review by what the diff can show — an empty diff is NOT automatically "implement incomplete":
@@ -720,7 +881,7 @@ Never make fake edits or fake tests to satisfy an empty diff, and never lower ac
 
 **Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
-**Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewers return the complete verdict block (≤30 lines), without shell writes; the orchestrator appends it with `Edit` to the task file, preserving prior rounds, before aggregation or status updates. No reviewer writes INDEX or task files; serial persistence avoids shared-write races. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
 
 The spawned reviewer agent reads `EXECUTOR_MODEL` from each task file `## Executor Report`:
 
@@ -742,7 +903,7 @@ If any command fails → `VERDICT: CRITICAL` (`NEXT_STATUS_FOR_INDEX: critical_b
 ### R4 — Review unified diff + append verdict (strong model)
 
 ```bash
-git diff $PLAN_COMMIT   # every handoff change: committed waves + working tree
+git diff <plan-commit>   # every handoff change: committed waves + working tree
 git status              # overview of modified/new/deleted files
 ```
 
@@ -750,7 +911,7 @@ Review as one unified diff — correctness, regression risk, security, edge case
 
 Stage gate (unic-decision): reviewers still generate findings; when `decisionPlane.families.review.stage` is not `off`, the emitted verdict goes through `node .claude/ukit/index/review-verdict.mjs` (`review.verdict.v1`; `--panel` for `review.panel-verdict.v1`/`review.finding-bucket.v1`) — the deterministic severity aggregate stays authoritative at `off` or on adapter failure.
 
-Append verdict to each task file:
+Return the verdict for orchestrator persistence to each task file:
 ```
 ## Reviewer Verdict
 VERDICT: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL
@@ -758,6 +919,10 @@ REVIEWER_MODEL: <your exact model ID>
 EXECUTOR_MODEL: <from Executor Report>
 REVIEW_KIND: product | integration-evidence | status-only
 VERIFICATION_RERUN: PASS | FAIL | NOT_RUN | N/A
+  command: <exact command, or ->
+  result: <actual pass/fail counts or NOT_RUN/N/A with reason>
+TEST_PLAN_COVERAGE: all-followed | partial — <gaps> | missing — <gaps>
+NOTES: <acceptance limitations, or none>
 FINDINGS:
   critical: <file:line — what fails> | none
   important: <file:line — risk> | none
@@ -767,7 +932,7 @@ NEXT_STATUS_FOR_INDEX: approved | approved_minor | changes_requested | critical_
 
 `VERDICT:` uses the aggregator's canonical hyphen vocabulary — underscore spellings (`changes_requested`, `critical_block`, `approved_with_minor`) parse to the same verdicts, so a blocking reviewer is never dropped as unparsed. `NOT_RUN` = the required re-run never executed in your session; `FAIL` = it executed and failed; either blocks approval. `N/A` is legitimate only when this review has no executable required checks (`command: -` or none) — an `N/A` beside a declared executable `command:` counts as `NOT_RUN`. `REVIEW_KIND` comes from the R1 classification; it scopes only the implementation-TDD evidence (new tests + RED_OUTPUT) — required executable checks and the task's original acceptance criteria are never waived, and approving an evidence review never marks product acceptance met.
 
-Then return to the orchestrator **at most 6 lines** — the full verdict is already on disk:
+Return this routing header followed by the complete verdict block above; the orchestrator persists the block with `Edit` before reading it back and advancing R4.5:
 ```
 TASK: TASK-xxx
 VERDICT: approved | approved_minor | changes_requested | critical_block
@@ -776,7 +941,7 @@ VERIFICATION_RERUN: PASS | FAIL | NOT_RUN | N/A (+ one-line reason)
 BLOCKING: <one line per critical/important finding, or "none">
 ```
 The return `VERDICT:` carries the NEXT_STATUS_FOR_INDEX vocabulary; the on-disk block's `VERDICT:` field uses the canonical hyphen vocabulary above.
-Do not paste the diff, the findings prose, or verification logs back into the orchestrator.
+Return actionable findings inside the bounded block, not the diff or raw verification logs.
 
 ### R4.5 — Auto-fix loop (max 2 rounds)
 
@@ -824,12 +989,14 @@ once — this is the run's only push:
 ```bash
 git add -- <run-owned paths>
 git commit --only -m "handoff: implement <goal>" -- <run-owned paths>   # skip if nothing left to commit
-git push origin $BASE
+git push origin <base-branch>
 ```
 
-Replace `<goal>` with the one-sentence goal from ACTIVE.md. Push without asking — `git push`
-is in the settings `allow` list precisely so a one-shot run never stalls at the last step.
-Force-push stays denied, so this can only ever fast-forward.
+Replace `<goal>` with the one-sentence goal from ACTIVE.md. Push only when the user's explicit
+delivery scope authorizes it, and only within the host's permissions. A settings `allow` entry
+is host configuration, not user authorization to publish, so it never licenses a push by itself.
+Without explicit delivery scope the run commits locally and records "not pushed" in the Final
+Report. Force-push stays denied, so any push can only fast-forward.
 
 **If some tasks are `blocked`:** still push. The approved work is reviewed, tested, and
 committed; withholding it helps no one, and the per-wave commits make any subset revertible.
@@ -977,10 +1144,11 @@ fixes, local work completed, and the recovery instructions for the next session.
 
 Then, as the last line of the run:
 
-> Cycle finished. Run `/compact` before starting the next cycle — this session is carrying
-> the whole pipeline's history and the next cycle deserves a clean window.
+> Cycle finished. State is in git, `INDEX.md` and `RUN.md`; the next cycle continues from
+> the cursor (a `/compact` is optional and never required, and never asked while assigned
+> queue work remains).
 
-This is the **only** place in the pipeline that may ask for a compaction. Asking at a cycle
-boundary costs nothing: all state is in git, `INDEX.md` and `RUN.md`, so a compacted or
+Do not make a manual `/compact` mandatory at the cycle boundary; compaction is a host choice.
+Asking at a cycle boundary costs nothing: all state is in git, `INDEX.md` and `RUN.md`, so a compacted or
 brand-new session picks the next cycle up with no loss. Asking mid-cycle is forbidden — see
 the Autonomy Contract.