@ngockhoale/ukit 3.4.65 → 3.4.66

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

@@ -43,15 +43,29 @@ point in the phases below has a defined automatic resolution. Take it. Specifica
 | Situation | Old behavior | Required behavior now |
 |-----------|--------------|----------------------|
 | Scope spans multiple subsystems | wait for confirmation | decompose into sequential cycles, run cycle 1 now, queue the rest in `INDEX.md` |
-| Plan review returns `Issues Found` | up to 3 rounds, then stop | 1 revision round; if round 2 still has findings, apply them and proceed — log to `## Plan Review Log` |
+| Plan review returns `Issues Found` | up to 3 rounds, then stop | bounded repair + fresh independent escalation per P2.5; unresolved tasks stay `needs_breakdown` with `PLAN_REVIEW: Unresolved`, only independently cleared work proceeds |
 | Two same-wave tasks share a file | STOP | move the later task to the next wave (add the dependency), continue |
 | INDEX has `pending_review`/`blocked` tasks | STOP | **resume** — see Resume below |
 | Reviewer returns `changes_requested`/`critical_block` | report and stop | run the Phase 4 auto-fix loop (max 2 rounds) |
 | Verification command fails | stop | fix and re-verify inside the auto-fix loop |
 
-Escalate to the human **only** for: a blocker outside the repo (missing credential, external
-service down), or a task still failing after both auto-fix rounds. Even then, finish every
-other task first and report what was left undone.
+Escalate to the human **only** for a valid blocker:
+- an external blocker outside the repo (missing credential, external service down, network/API unreachable), or
+- a genuine requirement conflict that only the owner can decide (two owner requirements that cannot both be met).
+
+Even then, finish every independent task first and report what was left undone.
+
+**BLOCKED is reserved for valid blockers. Local failures: route to repair or replan, NEVER BLOCKED.**
+**Internal failures are never blockers.** Failing tests, review findings, and repairs that exhausted
+their cap are internal failures. They get bounded escalation, never an infinite retry, an endless
+replan loop, or a DONE claim:
+1. Retry the same edit at most `orchestration.maxAttemptsPerFailure` (2) times.
+2. Then change strategy: investigate the cause and apply a different fix (`maxRecoveryStrategies`, 2).
+3. Then record progress: note the failure, its attempts and strategies in the task's `## Discussion`
+   thread, mark the task not approved, and continue every independent task.
+
+A stuck task is never approved by cap and is NOT an external block.
+Continue independent tasks while a blocked branch waits.
 
 **Never pause to ask for `/compact`.** Context is managed structurally — subagents write full
 logs to disk and return short summaries (see 3b), and the run cursor makes the pipeline
@@ -70,13 +84,28 @@ Phase: <P0|P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R4.5|R5|F|done|blocked>
 Cursor: wave <N> batch <M> — <what just finished>
 Next: <the exact next step to run>
 ExitPredicate: all(<term>[,<term>...])   # written once at P2; never relaxed
+Cycle: <NN>   # current assigned cycle; preserve through reset/archive and resume
 QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 Acceptance: <the acceptance line the CurrentTask must satisfy>   # optional
 CurrentTask: <TASK-xxx>   # optional; the single task mid-flight right now
 RetryFingerprint: <stable id of the failing step>   # optional; retry-loop identity
 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
+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
 ```
 
+**Scope fields are additive and optional, and they survive compaction.** After a compact, the SessionStart resume hook carries `ScopePlans` / `ScopeQueue` / `Authorization` unchanged, so the run never re-derives its scope. A RUN.md without them behaves exactly as before:
+`ScopeQueue` absent means every queued blueprint counts toward the run-all backlog (legacy).
+When `ScopeQueue` is present, only the listed slugs count; a blueprint queued after the run froze
+its scope never extends that run. These fields carry the run's authorized scope across compact and
+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.
+
 **Compact-carry fields.** `Acceptance`, `CurrentTask`, `RetryFingerprint` and `RetryCount`
 are what a compacted session carries forward — these four lines plus `Goal`/`Next:`, never
 the full subagent prompts. The SessionStart resume hook prints them verbatim after a
@@ -174,8 +203,10 @@ This run has exactly **two** legal ways to end:
 
 - `HANDOFF FULLSTACK COMPLETE` — the completion gate in Phase F passed. First line of the
   final report, verbatim.
-- `HANDOFF FULLSTACK BLOCKED` — every remaining task depends on the same external blocker
-  (missing credential, dead service, permission wall) AND no safe local work exists. Write
+- `HANDOFF FULLSTACK BLOCKED` — every remaining task depends on the same valid blocker (an external
+  blocker such as a missing credential, dead service, or permission wall, or a genuine requirement
+  conflict that needs the owner's decision) AND no safe local work exists. Internal failures
+  never qualify. Write
   `Phase: blocked` to RUN.md before emitting it so the Stop gate releases the session.
 
 Nothing else ends the run. A recap is a progress notification, not a stopping point. If you
@@ -206,8 +237,11 @@ work, not only the current plan:
 2. `docs/AI_HANDOFF/tasks/TASK-*.md` — stale `in_progress` from a dead session, `blocked`,
    `changes_requested`, `needs_executor_report`, `needs_breakdown`.
 3. Previous cycles — `docs/AI_HANDOFF/HISTORY.md` and `archive/` for cycles closed with
-   unfinished tasks; their leftovers join THIS cycle.
-4. `docs/TASKS.md` — `Ready for AI` items are newly-assigned work; fold them into the plan.
+   unfinished tasks. Their leftovers join THIS cycle ONLY when named by the invocation or listed
+   in the run's `ScopePlans:` field (see the RUN cursor). Unnamed history/archive leftovers are
+   reported as `Backlog:` and are never auto-imported.
+4. `docs/TASKS.md` — `Ready for AI` items are newly-assigned work. Fold one into the plan only when the
+   invocation names it or it is listed in `ScopePlans:`; otherwise report it as `Backlog:`.
 5. `docs/AI_HANDOFF/queued/*/` — dormant blueprints. A planning run that could **not**
    touch the canonical plan (a live run was in flight) queues its SPEC/PLAN/tasks under
    `docs/AI_HANDOFF/queued/<slug>/` instead of overwriting (see `/ukit:handoff-create`).
@@ -216,7 +250,10 @@ work, not only the current plan:
    overwrite a blueprint — a blueprint the run decides to defer stays queued.
    Blueprints WITHOUT the `QueueIntent` metadata are still folded in as described above.
    A blueprint whose header carries `QueueIntent: deliberate-future` is the exception: it is
-   **not folded** in; report it as `Backlog: <slug>` and leave it untouched.
+   **not folded** in; report it as `Backlog: <slug>` and leave it untouched. Only blueprints
+   whose LEDGER rows are `deferred` carry that header. Mandatory overflow (`feasible`/`adapted`
+   rows queued by create because the plan exceeded 10 tasks) is queued WITHOUT `QueueIntent`,
+   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`.
@@ -264,11 +301,15 @@ The run must keep itself alive without the human watching.
 - **Harnesses with neither:** treat EVERY activation as a watchdog recovery turn — read
   RUN.md first, rescan the inventory, continue `Next:`.
 
-**Quiet-period rule.** The run may finish only after the backlog is empty AND
-`handoff.fullstack.quietScansRequired` (default 2) consecutive watchdog scans find no new
-assignment, no recoverable task, and no uncommitted intended change. Record each quiet
+**Quiet-period rule.** The run may finish only after the frozen assigned scope is empty AND
+`handoff.fullstack.quietScansRequired` (default 2) consecutive watchdog scans find, within that
+frozen scope only, no new assignment, no recoverable task, and no uncommitted intended change.
+Work outside the frozen scope (a queued blueprint not in `ScopeQueue`, an unnamed history item) is
+never counted by a quiet scan. Record each quiet
 scan in RUN.md as `QuietScans: <n>/<required>`. A scan that finds anything resets the
-counter and starts a new cycle automatically.
+counter. A new in-scope recoverable task (assigned or repair of assigned work) starts work in this
+run. A late create outside `ScopeQueue`/`ScopePlans` is recorded as `LateCreate:` (Backlog) and does
+not start a new cycle.
 
 ---
 
@@ -294,7 +335,7 @@ 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) → re-run is allowed: overwrite `PLAN.md` and `TASK-xxx.md` freely (iterative refinement).
+   - 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.
    - 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.
 
@@ -362,18 +403,23 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
 
 ### P2.5 — Independent plan review (strong model, separate agent)
 
-**Loop cap — check first:** count `### Round` entries in PLAN.md's `## Plan Review Log` (0 if the section doesn't exist yet).
+**Loop cap — check first:** count completed reviewer verdicts in PLAN.md's `## Plan Review Log` = `### Round` entries that carry a `PLAN_REVIEW:` or verdict line (repair-only `### Repair <N>` / `### Escalation <N>` markers are NOT counted; 0 if the section doesn't exist yet).
 
 - count = 0 → run the review below.
 - count = 1 and the round returned `Issues Found` → planner revises once, then run **one** more review round.
-- count ≥ 2 → do NOT invoke the reviewer again. **Do not stop and do not ask the human.** Have the planner apply every outstanding finding directly to `PLAN.md` and the affected `TASK-xxx.md` files, append `### Round <N> — findings applied without re-review` to the Plan Review Log listing what was changed, then proceed to P3.
+- count ≥ 2 and no escalation recorded yet → **bounded escalation, once, without a human, in this run.** Record `### Escalation 1 — <reason>` in the Plan Review Log before the reviewer runs. The planner applies the outstanding findings with a **changed strategy** (different decomposition or task split, not a re-run of the same edit) and appends `### Repair <N> — changed strategy`. Then invoke `code-reviewer` **once more** as a fresh independent smart-tier review (new agent, no prior context) and append its verdict as `### Round <N>`.
+- count ≥ 2 and an escalation is already recorded → the escalation is spent. No further reviewer round runs except the **Recovery exception** below. Do not wait: proceed to P3 for the tasks that are `ready`, and mark each still-flagged task `needs_breakdown` with its open finding named unless the Recovery exception runs.
+  - `Approved` (escalation round or earlier) → proceed to P3 with the normal `PLAN_REVIEW: Approved by <reviewer model>` footer.
+  - `Issues Found` after the escalation, or an escalation that cannot run → any task still carrying an open finding is `needs_breakdown` (never `ready`); the footer records `PLAN_REVIEW: Unresolved — round cap reached, findings applied without independent verification` (never `Approved`), and the Final Report names each `needs_breakdown` task with its open finding. Independent work on the other tasks continues in this run.
+- Finding signature: each open finding is identified by `<location>` (the file and section or line the reviewer cites) plus its normalized claim (lowercased, whitespace collapsed, first 120 characters). The reviewer's verdict lists each finding with that location and claim, and after every verdict the planner appends `### Signatures Round <N>: <sig>; <sig>; …` to the Plan Review Log, so the set is persisted per plan.
+- Non-progress rule: a repair whose open-signature set equals the previous round's `### Signatures` set is non-progress and goes straight to the Unresolved path. It is never retried in a loop and never reported as DONE. **Recovery exception (explicit, at most once per plan):** it runs only when the escalation is spent, the latest verdict is still `Issues Found`, the latest repair changed the signature set, and the Plan Review Log has no `### Recovery 1 — consumed` marker. Then, in order: (1) append `### Recovery 1 — consumed <YYYY-MM-DD>` before any other work; (2) run a root-cause investigation and a different decomposition (at most one further recovery round); (3) run one fresh independent review of the changed artifact and append its verdict as `### Round <N>`. The marker is never removed or re-created. If the marker already exists, or the signature set is unchanged, no further review runs: retain Unresolved with a precise diagnostic and continue with the other tasks. An owner conflict routes an owner decision.
+- The Plan Review Log and `needs_breakdown` marks keep the open state visible, so no plan is left silently pending.
 
-The gate still does its job — two independent opus passes shape the plan before a line of code
-is written. What it no longer does is hand a stalled plan back to a human who isn't there.
+The gate still does its job: two independent opus passes plus one escalation pass shape the plan before a line of code is written.
 
 **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` only (no diff, no task files, no executor report), 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 appends its verdict 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.
 
@@ -383,7 +429,8 @@ is written. What it no longer does is hand a stalled plan back to a human who is
 
 **Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` (omp: the `task` tool with `agent: "ukit-small-task-maintainer"`) for this commit step (lite tier — haiku/unic-lite). Run:
 ```bash
-git add docs/AI_HANDOFF/ && git commit -m "handoff: plan — <goal>"
+git add -- <explicit assigned plan paths>
+git commit --only -m "handoff: plan — <goal>" -- <explicit assigned plan paths>
 ```
 
 Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan in git before any implementation begins.
@@ -417,11 +464,20 @@ Verify working tree is clean after the plan commit:
 git status   # must be clean — plan commit already done in P3
 ```
 
-If the working tree is dirty, do not stop. Commit the stragglers as a checkpoint so they stay
-recoverable and the wave copy-back starts from a known state:
+If the working tree is dirty, do not stop. Classify each dirty path first:
+- **Run-owned** — a path the run itself wrote in this cycle (its PLAN/SPEC/task files, RUN.md,
+  INDEX.md, ACTIVE.md, or a path listed in the task's `Target Files`). Only these are checkpointed.
+- **Foreign dirty** — anything else (another owner's WIP, unrelated files). Never stage, commit, or
+  revert it. Record it in RUN.md under `Foreign dirty:` and leave it in place.
+
+Checkpoint only the run-owned paths, by explicit name, so the wave copy-back starts from a known
+state without absorbing unrelated owner changes:
 ```bash
-git add -A && git commit -m "handoff: checkpoint before implement"
+git add -- <run-owned paths>
+git commit --only -m "handoff: checkpoint before implement" -- <run-owned paths>
 ```
+Never `git add -A` (or `git add .`) for a checkpoint: it sweeps foreign dirty paths into the
+run's commit.
 
 ### I2 — Infer wave groups
 
@@ -548,7 +604,8 @@ node .claude/ukit/index/land-worktree.mjs \
 # 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"
+git add -- <landed paths>
+git commit --only -m "checkpoint: $TASK landed" -- <landed paths>
 
 # update INDEX.md: status → pending_review
 ```
@@ -557,7 +614,8 @@ For **FAIL:**
 ```bash
 # 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"
+#   status → in_progress for bounded fix/investigate, then replan if needed.
+# Only an external blocker or genuine owner-decision conflict justifies blocked.
 ```
 
 For **EXECUTOR_MODEL missing:**
@@ -582,7 +640,8 @@ already on disk (task files hold the full logs, git holds the code). Do all four
    copied-back changes are reverted and nothing is committed. A plateau is not a stop —
    the run continues to the next wave or fix round; the predicate is never relaxed.
    ```bash
-   git add -A && git commit -m "handoff: wave <N> — TASK-00x, TASK-00y"
+   git add -- <run-owned paths of this wave>
+   git commit --only -m "handoff: wave <N> — TASK-00x, TASK-00y" -- <run-owned paths of this wave>   # foreign index entries stay unchanged
    ```
    Do not push here; the single push happens at R5.
 
@@ -612,7 +671,7 @@ logs used to cost. That difference is what makes a multi-wave cycle finish in on
 
 1. Update `docs/AI_HANDOFF/INDEX.md`:
    - PASS tasks → `pending_review`
-   - FAIL tasks → `blocked`
+   - FAIL tasks → `in_progress` for bounded fix/investigate/replan; `blocked` only with a recorded external blocker or owner-decision conflict
    - EXECUTOR_MODEL missing → `needs_executor_report`
    Then **verify the write** (read back the updated status column).
 
@@ -739,28 +798,32 @@ For round in 1..2:
    - the same ≤10-line return contract as 3b.
 3. Copy back and delete worktrees per 3c. Commit the round:
    ```bash
-   git add -A && git commit -m "handoff: fix round <N> — TASK-00x"
+   git add -- <run-owned paths of this round>
+   git commit --only -m "handoff: fix round <N> — TASK-00x" -- <run-owned paths of this round>
    ```
 4. Re-review **only the tasks touched this round**, in parallel, per R2–R4. A reviewer must
    still differ from the executor model, and still re-runs verification itself.
 5. Update `INDEX.md` and `RUN.md`. If everything is now approved, exit the loop.
 
-After round 2, any task still not approved is genuinely stuck: leave it `blocked`, record why
-in its `## Discussion` thread, and carry it into the Final Report. **Every other task still
+After round 2, any task still not approved is a local failure (NOT an external block): record
+the failure and the attempted strategies in its `## Discussion` thread and carry it into the
+Final Report. Route it to replan in the next cycle; never approve it by cap. **Every other task still
 proceeds to R5** — one stubborn task must never hold the whole cycle hostage.
 
 ### R5 — Commit + push (orchestrator)
 
 R4.5 has already run, so by this point every task is either approved or genuinely stuck.
 
-Update `docs/AI_HANDOFF/INDEX.md`: approved tasks → `done`; anything still failing after both
-fix rounds → `blocked`.
+Update `docs/AI_HANDOFF/INDEX.md`: approved tasks with acceptance met → `done`;
+local failures remain `in_progress`/`changes_requested` with bounded recovery diagnostics.
+Only an external blocker or genuine owner-decision conflict is `blocked`.
 
 Commit whatever remains uncommitted (the per-wave commits from 3d are already in), then push
 once — this is the run's only push:
 
 ```bash
-git add -A && git commit -m "handoff: implement <goal>"   # skip if nothing left to commit
+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
 ```
 
@@ -782,11 +845,13 @@ Do NOT set `Phase: done` yet — Phase F still has to close the books.
 
 ### F1 — Quiet-period scan
 
-Run the sweep from Phase 0 again (INDEX, task files, `docs/TASKS.md`, git status).
+Run the Phase 0 sweep again within the frozen assigned scope recorded in RUN.md
+(ScopePlans/ScopeQueue, canonical assigned tasks and intended changes only). Do not import
+`docs/TASKS.md`, history, late independent plans or unrelated dirty files.
 `handoff.fullstack.quietScansRequired` (default 2) consecutive scans must each find:
-no unfinished task, no new assignment, no uncommitted intended change. Record each scan
-in RUN.md (`QuietScans: <n>/<required>`). Anything found resets the counter — fold it in
-through the normal pipeline and keep going.
+no unfinished in-scope task, review/integration/delivery debt or uncommitted intended change.
+Record each scan in RUN.md (`QuietScans: <n>/<required>`). In-scope findings reset the counter;
+repair them through the normal pipeline. Independent out-of-scope work does not extend this run.
 
 ### F2 — Docs sync
 
@@ -798,37 +863,47 @@ evidence, rollback notes.
 
 ### F3 — Archive the cycle
 
-When `handoff.fullstack.autoArchive` is true (default), archive per `handoff-clear`
-conventions so a future session needs no transcript to understand the cycle:
-
-1. Move the completed cycle's records (PLAN.md, SPEC.md, task files, ACTIVE.md snapshot)
-   into `docs/AI_HANDOFF/archive/cycle-<NN>/`, then — BEFORE resetting `INDEX.md` — run
-   `node .claude/ukit/runtime/resumable-run.mjs archive-cycle . <NN>`. It writes the verified
-   INDEX rows to `archive/cycle-<NN>/INDEX.md` and stamps each terminal task header, so the
-   stop predicate reads the INDEX status, not a stale executor-written header. It is
-   idempotent; after an interrupted archive just run it again.
-2. If `archive/` holds more than 3 cycle folders → fold the oldest into a one-line
-   summary in `HISTORY.md` and remove it.
-3. Reset `ACTIVE.md` to its empty template; clear `INDEX.md` rows to a fresh header;
-   remove `tasks/TASK-*.md`; clear `PLAN.md`/`SPEC.md` (templates stay).
-   **Predicate terms:** the stop gate's `index:all-done` accepts a header-only INDEX when
-   every task in `archive/cycle-<NN>/` is terminal-success (`done`/`cancelled_superseded`)
-   according to that cycle's INDEX snapshot (legacy archives without one fall back to the task
-   header). A finalized cycle is NOT run-all completion: under `GoalScope: run-all` the
-   predicate still fails while `queued/<slug>/` blueprints (not `QueueIntent:
-   deliberate-future`) remain. Keep archived task files until the goal is complete. When the
-   `ExitPredicate` contains `verify:pass`, run the final verification command through the
-   shell in THIS session after the last edit (the receipt is per-session; a pipe without
-   `pipefail` is unproven).
-   Then **verify the write** on each reset file (read back the empty header /
-   template marker).
-4. Commit the docs + archive changes:
-   `git add -A && git commit -m "handoff: finalize + archive cycle <ID>"`
+When `handoff.fullstack.autoArchive` is true (default), archive only a genuinely completed
+cycle. Pending, blocked, pending-review, changes-requested, pending-release or failed
+integration work remains open. Task status alone cannot replace independent review,
+integration and any owner-required release/consumer evidence. Do not archive to escape a gate.
+
+1. Select a new unused `docs/AI_HANDOFF/ARCHIVE/cycle-<NN>/` for this completed cycle;
+   never merge into an unrelated prior cycle. Record `Cycle: <NN>` and the recovery step in RUN.md;
+   retain it after INDEX reset so the runtime checks this archive, not unrelated history.
+   Move only its completed task records first, preserving PLAN.md, SPEC.md, LEDGER.md,
+   SOURCE.md, NOTES.md (or equivalent classifications), amendments, reviews, verification
+   and delivery evidence plus ACTIVE.md. Preserve queued and unrelated active records.
+   BEFORE resetting INDEX.md, run
+   `node .claude/ukit/runtime/resumable-run.mjs archive-cycle . <NN>`.
+   Verify `ok: true`, the expected task IDs/statuses in `ARCHIVE/cycle-<NN>/INDEX.md`,
+   and the preserved records. On snapshot failure retain the live INDEX and recovery
+   cursor; investigate/fix, never reset or treat the failure as completion. Resume an
+   interrupted move using that same recorded destination, not a new cycle or blind overwrite.
+2. Never prune completed history or replace detailed evidence with a summary. Legacy
+   lowercase `archive/` remains read-only provenance; do not silently migrate or reactivate it.
+3. Only after the snapshot and evidence are verified, reset records wholly represented
+   in that archive to templates and remove only their INDEX rows. Do not wildcard-delete
+   task files or erase remaining open records. Verify each reset marker and retained ID.
+   **Predicate terms:** evaluate the current assigned scope, not unrelated historical
+   success. A finalized cycle is NOT run-all completion: unfinished frozen ScopeQueue
+   blueprints still require the next cycle. Out-of-scope late creates and deliberate-future
+   blueprints remain preserved, not silently admitted. When `ExitPredicate` contains
+   `verify:pass`, run final verification through the shell in THIS session after the last
+   edit (the receipt is per-session; a pipe without `pipefail` is unproven).
+4. Commit only the enumerated run-owned docs/archive paths and tracked task deletions
+   from the move (`git add -- <explicit run-owned paths>`). Foreign staged or dirty paths
+   stay untouched; never an unscoped stage-all. Keep the recorded archive destination in
+   RUN.md so completion verification and recovery use this cycle's evidence.
 
 ### F4 — Close the run
 
-Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`, disarm any watchdog job armed at the
-start, and emit the Final Report below.
+Only after the entire assigned scope is complete — canonical tasks, every unfinished
+blueprint in frozen ScopeQueue, independent review, integration and required release/consumer
+verification — set `Phase: done` in `docs/AI_HANDOFF/RUN.md`, disarm any watchdog job armed
+at the start, and emit the Final Report below. A completed cycle with assigned queue work
+remaining instead advances RUN.md to that next cycle; it does not close the run. Open local
+recovery work retains its real phase and next diagnostic step, never a false completion.
 
    Then **verify the write** (read back `Phase: done`) — a lost cursor write
    leaves the next session resuming a finished run.
@@ -890,7 +965,7 @@ Then the body:
   Verification: <commands + results>
   Git: <K> wave commits + pushed to <branch>
   Docs updated: <files>
-  Archive: docs/AI_HANDOFF/archive/cycle-<NN>/
+  Archive: docs/AI_HANDOFF/ARCHIVE/cycle-<NN>/ | not archived — <reason>
   Worktrees: all cleaned
   Branches: all cleaned
   Remaining tasks: NONE | <list>

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

@@ -25,9 +25,9 @@ resolution — take it, and note it in the wave summary:
 
 | Situation | Required behavior |
 |-----------|------------------|
-| Working tree dirty at Step 1 | commit a checkpoint, continue |
+| Working tree dirty at Step 1 | scoped checkpoint of run-owned paths only (`git commit --only -- <paths>`), unrelated changes untouched, continue |
 | Two same-wave tasks share a file | move the later task to the next wave, continue |
-| A task's agent reports FAIL | leave it `blocked`, finish every other task, report at the end |
+| A task's agent reports FAIL | bounded local fix/investigate (max 2 distinct strategies, then replan); `blocked` only for external blocker or genuine owner-decision conflict; finish every other task, report at the end |
 | Context warning fires | collapse the finished wave to one line per task, continue |
 | No `ready` tasks but `changes_requested` ones exist | treat those as the work — this is a fix pass |
 
@@ -71,11 +71,16 @@ Verify working tree state:
 git status
 ```
 
-If the working tree is dirty, do not stop — commit a checkpoint so the wave copy-back starts
-from a known state and the pre-existing edits stay recoverable:
+If the working tree is dirty, do not stop — checkpoint **only the run-owned paths** (the Target
+Files of the `ready` tasks plus `RUN.md`/`INDEX.md`/task files). Never `git add -A`: unrelated
+modified or already-staged owner changes stay exactly as they are.
 ```bash
-git add -A && git commit -m "handoff: checkpoint before implement"
+git status --porcelain
+git add -- <run-owned paths>
+git commit --only -m "handoff: checkpoint before implement" -- <run-owned paths>
 ```
+`--only` commits just the listed paths and leaves other index entries staged. Do not unstage,
+revert or commit unrelated changes.
 
 ## Step 2 — Build wave groups
 
@@ -210,7 +215,8 @@ node .claude/ukit/index/land-worktree.mjs \
 # 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"
+git add -- <landed paths>
+git commit --only -m "checkpoint: $TASK landed" -- <landed paths>
 
 # update INDEX.md: status → pending_review
 ```
@@ -218,7 +224,11 @@ git add -- <landed paths> && git commit -m "checkpoint: $TASK landed"
 **FAIL:**
 ```bash
 # No landing for a FAIL report — retain the worktree and branch as recovery evidence.
-# update INDEX.md: status → blocked
+# Bounded local recovery first: diagnose from the executor report, then retry with a
+# different strategy (max 2 distinct strategies), or replan the task as TASK-xxx-R<n>.
+# update INDEX.md: status → in_progress (fix round) — NOT blocked for a local failure.
+# `blocked` only when the blocker is external (credential, dead service, network) or a
+# genuine requirement conflict needs the owner; record that reason in ## Discussion.
 ```
 
 **EXECUTOR_MODEL missing:**
@@ -236,10 +246,13 @@ never an unconditional forced removal or branch deletion sitting next to the lan
 A wave boundary is the only safe place to shed context, because everything of value is
 already on disk (task files hold the full logs, git holds the code). Do all four, in order:
 
-1. **Checkpoint the code** — one commit per wave, so every wave is independently revertible:
+1. **Checkpoint the code** — one commit per wave, so every wave is independently revertible.
+   Stage and commit only this wave's landed paths (the receipt-listed targets), never `git add -A`:
    ```bash
-   git add -A && git commit -m "handoff: wave <N> — TASK-00x, TASK-00y"
+   git add -- <wave landed paths>
+   git commit --only -m "handoff: wave <N> — TASK-00x, TASK-00y" -- <wave landed paths>
    ```
+   Unrelated staged or modified owner changes are left as they are.
    Do not push. `/ukit:handoff-review` owns that decision.
 
 2. **Update the run cursor** — rewrite `docs/AI_HANDOFF/RUN.md` with `Cursor: wave <N> done`,
@@ -273,8 +286,10 @@ snapshot, unmerged history. Unexplained leftovers fail the gate; nothing is remo
 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`.
+All changes are committed as **one commit per wave on `$BASE`**, nothing pushed. Worktrees and
+branches are retired only through the receipt-gated helper; any that remain are named in the
+retained-reason report. Set `Phase: done` in `docs/AI_HANDOFF/RUN.md` only when no task is
+still open.
 
 ## Step 5 — Report
 
@@ -283,7 +298,7 @@ Wave summary:
   Wave 1: TASK-001 [pending_review], TASK-002 [blocked]
   Wave 2: TASK-003 [pending_review]
 Commits: <K> wave commits on <BASE>, not pushed
-All worktrees and branches removed.
+Retained (receipt-gated cleanup): <worktree/branch — reason> | none
 Blocked (needs you): <TASK-xxx — one-line reason> | none
 ```
 

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

@@ -206,25 +206,33 @@ For round in 1..2:
      to the task file;
    - a ≤10-line return contract (`TASK` / `STATUS` / `EXECUTOR_MODEL` / `FILES` / `VERIFY` /
      `NOTE`) — no pasted logs.
-3. Copy changes back, delete worktrees, then checkpoint:
+3. Copy changes back, then checkpoint only the fix-round paths (never `git add -A`). Worktree
+   removal is a separate receipt-gated step (`cleanup-task-worktree.mjs`), not a forced delete:
    ```bash
-   git add -A && git commit -m "handoff: fix round <N> — TASK-00x"
+   git add -- <fix-round landed paths>
+   git commit --only -m "handoff: fix round <N> — TASK-00x" -- <fix-round landed paths>
    ```
 4. Re-review **only the tasks touched this round**, in parallel, per 2a–2f — panel spawn, aggregation, and lead bucketing included. The reviewers must
    still differ from the executor model and still re-runs verification itself.
 5. Update `INDEX.md` and `RUN.md`. Exit when everything is approved.
 
-After round 2, a task still failing is genuinely stuck: leave it `blocked`, record why in its
-`## Discussion` thread, and name it in the report. **Every other task still proceeds to Step
+After round 2, a task still failing gets one bounded investigate/replan pass (a new strategy or a
+`TASK-xxx-R<n>` replacement, never a silent loop). Only an external blocker or a genuine
+requirement conflict that needs the owner justifies `blocked`; record the reason in its
+`## Discussion` thread and name it in the report. A local test or review failure alone is not
+`blocked`. **Every other task still proceeds to Step
 4** — one stubborn task must not hold the rest hostage.
 
 ## Step 4 — Commit + push
 
-Update `INDEX.md`: approved tasks → `done`; still-failing tasks → `blocked`.
+Update `INDEX.md`: approved tasks with acceptance met → `done`; still-failing tasks stay at their last non-approved
+status (`changes_requested`/`critical_block`) with the bounded investigate/replan reason in `## Discussion`.
+`blocked` is set only for an external blocker or a genuine requirement conflict that needs the owner.
 
-Commit anything left uncommitted, then push once:
+Commit only the review-owned paths that are still uncommitted (never `git add -A`), then push once:
 ```bash
-git add -A && git commit -m "handoff: review <goal>"   # skip if nothing left to commit
+git add -- <review-owned paths>
+git commit --only -m "handoff: review <goal>" -- <review-owned paths>   # skip if nothing left to commit
 git push origin $BASE
 ```
 
@@ -234,7 +242,9 @@ run never stalls at the last step. Force-push stays denied, so this can only fas
 If some tasks are `blocked`, still push: the approved work is reviewed, tested and
 committed, and the per-wave commits make any subset revertible.
 
-Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
+Set `Phase: done` in `docs/AI_HANDOFF/RUN.md` only after all assigned work and required
+integration/delivery verification are complete. Otherwise retain the actual phase, scope and
+next repair step; a partial review or push does not complete the run.
 
 ## Step 5 — Report
 

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

@@ -223,6 +223,11 @@ async function emitOrdinaryResume(payload, source) {
   const currentTask = field('CurrentTask');
   const retryFingerprint = field('RetryFingerprint');
   const retryCount = field('RetryCount');
+  // Optional durable scope carry (additive). Printed verbatim so compact never re-derives the
+  // authorized scope; the hook only echoes them — it never widens authority from them.
+  const scopePlans = field('ScopePlans');
+  const scopeQueue = field('ScopeQueue');
+  const authorization = field('Authorization');
 
   // The session's CURRENT handoff intent — structured transcript evidence, the
   // same shared module the Stop gate uses. A session whose latest request is
@@ -297,6 +302,9 @@ async function emitOrdinaryResume(payload, source) {
     ...(acceptance ? [`  Acceptance: ${acceptance}`] : []),
     ...(currentTask ? [`  CurrentTask: ${currentTask}`] : []),
     ...(retryFingerprint ? [`  RetryFingerprint: ${retryFingerprint} (RetryCount: ${retryCount || '0'})`] : []),
+    ...(scopePlans ? [`  ScopePlans: ${scopePlans}`] : []),
+    ...(scopeQueue ? [`  ScopeQueue: ${scopeQueue}`] : []),
+    ...(authorization ? [`  Authorization: ${authorization}`] : []),
     '',
     'This is a CONTINUATION, not a new cycle. Do not re-plan, do not overwrite PLAN.md or the',
     'task files, and do not ask the user whether to continue — they already asked for a',

package/template_project/.claude/skills/advisor-plan/REFERENCE.md

@@ -20,11 +20,16 @@ Dispositions (exactly one per row):
 - `deferred` - intentionally later; names its queue entry (the blueprint slug).
 - `blocker` - cannot proceed; names the missing precondition. An unreadable or empty source is `R-000 | blocker`.
 
+Prohibitions are confirmed exclusions: a source "must not" / "never" rule is recorded as a confirmed exclusion with its rationale. If it is enforceable in scope, it is a `feasible` or `adapted` row whose acceptance includes a referenced negative test (a test that proves the forbidden behaviour is absent). No new taxonomy is needed for this.
+
+The `10` limit is a dispatch and context window, not a classification. Queued drafts carry no runnable rows; their INDEX rows are `queued_blueprint`.
+
 Footer (required, last lines of the file):
 
 ```
 Coverage: N/N rows dispositioned
-Note: disposition coverage is not implementation coverage.
+Executable coverage: M/K feasible|adapted rows carry an executable acceptance and test/verification command
+Note: disposition coverage is not implementation coverage; executable coverage is counted separately.
 ```
 
 A row without a disposition means the ledger is unfinished. A claim of "100% implemented" is a defect.
@@ -68,7 +73,33 @@ QueueDrain: separate-backlog
 QueueSource: <ledger R-IDs or epic ids, e.g. R-003, R-007 / COW-300>
 ```
 
-A blueprint with `QueueIntent: deliberate-future` is reported as backlog by fullstack and is not folded into the current cycle. A blueprint without the line keeps the legacy fold-in behaviour. The contract is documented in `docs/AI_HANDOFF/queued/README.md`.
+Two queue kinds share the `queued/` lane and must not be confused:
+
+- **Mandatory overflow** (`feasible`/`adapted` rows beyond the 10-task threshold): queued WITHOUT `QueueIntent` (no `Queue*` header line at all). Fullstack folds it into the cycle like a legacy blueprint; it is consumable work, never excluded.
+- **Deliberate-future** (`deferred` rows only): carries the four `Queue*` lines above. Fullstack reports it as `Backlog: <slug>`, never folds it, and drains it only when the human names the slug.
+
+A blueprint without the line keeps the legacy fold-in behaviour. The contract is documented in `docs/AI_HANDOFF/queued/README.md`.
+
+**Mandatory overflow naming (default):** group overflow tasks by dependency chain (a task and everything it depends on that is also overflow form one group). Each group is one blueprint: `queued/<plan-slug>-overflow-<NN>/`, where `<plan-slug>` is the plan's slug and `<NN>` is the next unused two-digit index under that plan (scan existing `overflow-*` dirs, take max+1). Never reuse or overwrite an existing blueprint dir; on any collision append `-2`, `-3`, … to the directory name. Each blueprint's `HANDOFF.md` lists its R-IDs and task IDs.
+
+## Source snapshot
+
+Before chunking, persist the original verbatim: `${OUTPUT_ROOT}SOURCE.md` holds the original path, the `sha256` of the original file's bytes (not of this wrapper or any metadata header), and an unmodified copy of those bytes. For chat or pasted input with no file, record the durable verbatim message origin (message id or transcript path plus the exact text) in place of the path. Gatherers and planners cite `SOURCE.md` lines; no model paraphrase replaces it. The reviewer starts its chain from `SOURCE.md` and re-hashes the original bytes.
+
+## Source-only notes
+
+File: `${OUTPUT_ROOT}NOTES.md` (the semantic record is mandatory: every classification, exclusion, and rationale is recorded durably, and this file is the default home for the non-task items; an equivalent name is acceptable, and the file is written only when such items exist). Non-requirement material that a ledger row cannot carry. Each entry names its source (`doc §… L…`, or the human's words) and one kind:
+
+| Kind | Meaning |
+|------|---------|
+| `confirmed` | requirement or exclusion the human confirmed, with its rationale and a verbatim owner quote |
+| `example` | illustration only; not a requirement |
+| `proposal` | suggested approach not yet chosen |
+| `assumption` | default taken where the source is silent; names the default |
+| `question` | open question; names the resolution used or "open" |
+| `rejected` / `superseded` | choice dropped, with the reason and the replacing row or task |
+
+Rules: never drop an entry because it is not a task; a `rejected`/`superseded` entry stays so the rationale survives a replan. Replans append, never rewrite, prior entries.
 
 ## Chunking