@ngockhoale/ukit 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to UKit are documented here.
 
+## 2.6.0 - 2026-09-18
+
+handoff-fullstack v2 — autonomous create→implement→review loop that runs to 100%
+completion of all unfinished work, with a mandatory detailed SPEC gate.
+
+- **Never-stall Stop gate**: `stop-coordinator.mjs` gained a `handoff-cursor` lane that
+  reads `docs/AI_HANDOFF/RUN.md` and blocks stop while `Phase:` is not `done`/`blocked`,
+  carrying the cursor's `Next:` step. Liveness breaker releases after
+  `handoff.fullstack.stopGateMaxStalledBlocks` (default 12) un-advancing blocks; the lane
+  is advisory-on-failure and `stopGateEnabled` disables it. This fixes the observed
+  stall where runs went idle after a recap.
+- **Mandatory SPEC.md**: `handoff-create` now writes `docs/AI_HANDOFF/SPEC.md` — a
+  15-section template (FRs with Given/When/Then, fullstack scope, data model, API
+  contract, test matrix, acceptance criteria, migration, chosen defaults) — before task
+  files. Tasks carry `Spec references`; `handoff-model-guard.sh` hard-blocks fresh task
+  creation without a filled SPEC (`handoff.fullstack.specRequired=false` bypasses).
+- **Autonomous loop contract**: only `HANDOFF FULLSTACK COMPLETE` / `HANDOFF FULLSTACK
+  BLOCKED` may end a run; `CHECKPOINT — WORK CONTINUING` replaces bare recaps. Phase 0
+  sweeps INDEX, task files, HISTORY/archive, `docs/TASKS.md` Ready-for-AI, and
+  uncommitted WIP. Stuck tasks recover via `cancelled_superseded` + `TASK-xxx-R<n>`
+  replacement tasks. `idleWatchdogMin` (default 5) scheduled wakeups keep the loop
+  alive off-Claude-Code; `quietScansRequired` (default 2) guards completion; Phase F
+  runs docs sync → `archive/cycle-NN/` → `Phase: done` → marker report.
+- **Agent + command wiring**: `handoff-planner` gained legacy-sweep and SPEC-authoring
+  phases; `code-reviewer` reviews SPEC+PLAN against a 7-point spec quality gate;
+  `feature-implementer` treats `Spec references` as outranking task-file wording;
+  `handoff-implement`/`handoff-review` codify spec-is-the-contract and `-R<n>`
+  recovery. `handoff-clear` archives SPEC and must close RUN.md; `handoff-status`
+  reports run phase + spec presence.
+- **Config**: `handoff.fullstack.*` keys (`stopGateEnabled`, `stopGateMaxStalledBlocks`,
+  `quietScansRequired`, `idleWatchdogMin`, `autoArchive`, `specRequired`) with `_help`
+  notes, in both config trees.
+
+## 2.5.1 - 2026-09-18
+
+Post-release fixes from C20 reviewer advisories.
+
+- **`projectImportant` symlink fallback**: the odd-open-error fallback imported
+  `stat` as `lstat`, which follows symlinks — a broken symlink degraded to `missing`
+  and a symlink-to-file to `unreadable` instead of the correct `unsafe-type`
+  (spec §6.1). Now uses real `lstat`; fixed in `src/core/projectImportant.js` and both
+  installed-runtime mirrors (parity-locked).
+- **`inspectProjectImportant` guard**: a non-string `projectRoot` threw `TypeError`
+  before the try block instead of degrading to `unreadable`, violating the
+  "no documented entry point throws" contract. Guard added (src + mirrors).
+- **Uninstall backup exhaustion surfaced**: when all 101 backup-name candidates are
+  occupied, `PROJECT_IMPORTANT.md` was silently preserved without a backup. Now emits
+  a `backupWarnings` line telling the user to free a slot and rerun.
+- **Test tightening**: the packed-install smoke now asserts `project-important.sh`
+  occupies SessionStart index 0 (spec: must run first); corrected a stale "~5%
+  headroom" comment on the unpacked-size ceiling.
+
 ## 2.5.0 - 2026-09-18
 
 C20 feature release (14 handoff tasks + 3-lane review): project-owner instructions via a

package/package.json

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

package/src/core/projectImportant.js

@@ -17,7 +17,7 @@
  */
 
 import fs from 'node:fs';
-import { open, stat as lstat, readFile } from 'node:fs/promises';
+import { open, lstat, readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import {
@@ -112,6 +112,9 @@ function invalidResult(state) {
  */
 export async function inspectProjectImportant(options = {}) {
   const { projectRoot, config } = options;
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return invalidResult('unreadable');
+  }
   const target = path.join(projectRoot, PROJECT_IMPORTANT_FILENAME);
 
   let handle;

package/src/core/uninstall.js

@@ -89,6 +89,10 @@ async function planImportantBackup(projectRoot) {
   }
 
   plan.exhausted = true;
+  plan.backupWarnings.push(
+    `[UKit] Backup name space exhausted (${IMPORTANT_BACKUP_COLLISION_LIMIT + 1} candidates in use); `
+      + `${PROJECT_IMPORTANT_FILENAME} preserved in place without a backup. Free a backup slot and rerun \`ukit uninstall\`.`,
+  );
   return plan;
 }
 

package/templates/.claude/agents/code-reviewer.md

@@ -127,17 +127,28 @@ Same model is the most common silent failure. Do not skip this check.
 ### Inputs you expect
 
 - Path to the spec/plan document (e.g. `docs/plans/*.md`). No diff, no task file, no executor report — review the document itself.
+- When invoked from the handoff pipeline you get BOTH `docs/AI_HANDOFF/SPEC.md` and `docs/AI_HANDOFF/PLAN.md`. Review them as one unit: the spec is the contract, the plan is the decomposition. Verdicts still append to PLAN.md's `## Plan Review Log`.
 
 ### Review order
 
 | Category | What to look for |
 |---|---|
 | Completeness | TODO/TBD/placeholders, incomplete sections |
-| Consistency | internal contradictions, conflicting requirements |
+| Consistency | internal contradictions, conflicting requirements; SPEC and PLAN contradicting each other |
 | Clarity | requirements ambiguous enough to cause a wrong build |
 | Scope | focused enough for one plan, not silently covering multiple subsystems |
 | YAGNI | unrequested features, over-engineering |
 
+**Handoff spec quality gate** (only when reviewing `docs/AI_HANDOFF/SPEC.md`):
+
+1. Every functional requirement is testable — Given/When/Then or a command, never "should work".
+2. Every applicable fullstack layer is covered or explicitly `N/A` with a reason.
+3. Every FR traces forward to plan scope; nothing in the plan is unbacked by the spec.
+4. Dependencies between parts are explicit.
+5. Legacy/unfinished work discovered by the Phase 0 sweep is either planned or recorded out-of-scope.
+6. Rollback/migration impact is addressed when data or schema changes.
+7. No vague instruction survives — "improve UI", "faster", "better UX" without defined behavior fails Clarity.
+
 Only flag issues that would cause real problems during implementation planning. Approve unless there are serious gaps that would lead to a flawed plan.
 
 ### Output

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

@@ -19,8 +19,10 @@ reasoning to the parent agent so it can decide whether to re-route.
 **In Handoff mode you are running unattended — ask nothing.** You were spawned by an
 orchestrator driving a pipeline; there is no human in your conversation to answer, and a
 question there is silently dropped while the run stalls. Resolve ambiguity in this order:
-the task file → `PLAN.md` → the surrounding code's existing patterns → the choice you would
-recommend. Record what you chose and why in the task's `## Discussion` thread. Only a blocker
+the task file → the `Spec references` sections of `SPEC.md` → `PLAN.md` → the surrounding
+code's existing patterns → the choice you would recommend. The spec is the contract; if the
+task file and spec disagree, implement the spec and note it in the task's `## Discussion`
+thread. Record what you chose and why in that thread. Only a blocker
 outside the repo (missing credential, unreachable service) justifies reporting `FAIL` early —
 and even then, report it, don't ask about it.
 

package/templates/.claude/agents/handoff-planner.md

@@ -55,6 +55,35 @@ Before writing any path or command into `PLAN.md` or a task file, verify it:
 If something cannot be verified, say so in the task's `## Discussion` rather than guessing.
 A stated unknown costs the executor one read; a wrong path costs it a round.
 
+## Phase 0 — Legacy sweep (before writing anything)
+
+The plan owns ALL unfinished work, not only the new request. Scan and fold in:
+
+- `INDEX.md` rows that are not `done`/`cancelled_superseded`.
+- Task files in stale `in_progress` / `blocked` / `changes_requested` /
+  `needs_executor_report` / `needs_breakdown` from dead sessions.
+- `docs/AI_HANDOFF/HISTORY.md` + `archive/` — cycles closed with leftovers.
+- `docs/TASKS.md` — `Ready for AI` items are newly-assigned work.
+- `git status` — uncommitted work-in-progress (finish or checkpoint, never drop silently).
+
+Every discovered item becomes either a task row in the new plan or an explicitly recorded
+out-of-scope line in PLAN.md §2. Silent omission is a plan defect.
+
+**Recovery:** a stuck task record that cannot be cleanly resumed (orphaned worktree,
+contradicting reports, invalid state) is marked `cancelled_superseded` and replaced by
+`TASK-xxx-R1` (`-R2`, …) carrying the same spec references, acceptance criteria and
+verification — link both files' `## Discussion` threads.
+
+## Phase 0.5 — Write SPEC.md
+
+Write `docs/AI_HANDOFF/SPEC.md` from the template at `templates/docs/AI_HANDOFF/SPEC.md`
+(15 sections). The spec is the contract executors implement against — concrete enough that
+nothing is guessed: exact paths, module and API names, schemas, validation rules,
+permissions, empty/error states, migration behavior, test expectations. Every section is
+filled or marked `N/A — <reason>`; every open question is resolved to a chosen default
+recorded in §14. A vague line ("improve UI", "make it faster" with no number) is a spec
+defect — fix it before writing tasks.
+
 ## Phase 1 — Write PLAN.md
 
 Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
@@ -101,6 +130,7 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 
 | Field | Rule |
 |-------|------|
+| Spec references | SPEC.md section/FR IDs this task implements — every task traces to the spec |
 | Target Files | Exact paths — no two tasks in same wave share a file |
 | Dependencies | `TASK-xxx` or `none` — wave order is inferred from this |
 | Test Cases | Type \| Test Name \| Expected — ≥1 happy + ≥2 edge cases of different kinds |
@@ -160,6 +190,7 @@ most chains are ordering preferences that a wide wave 1 would satisfy just as we
 ```
 Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <current HEAD branch>
 Goal: <1 sentence>
+Spec: docs/AI_HANDOFF/SPEC.md
 Tasks: <N> total
 Status: planning_done — ready for executor
 ```
@@ -179,6 +210,8 @@ catches it:
 2. Does every task trace back to something in §1/§6? A task nothing asks for is scope creep — cut it.
 3. Do the tasks together actually deliver §1's success definition, or only the easy part of it? State the gap if there is one.
 4. Is the *unhappy* path planned — errors, empty input, permissions, migration of existing data — or only the feature?
+4b. Does every task carry `Spec references` into SPEC.md, and does every SPEC.md FR trace to at least one task? A spec section no task implements is a silent hole.
+4c. Did the Phase 0 sweep leave anything unplanned — stale tasks, legacy leftovers, Ready-for-AI items, uncommitted WIP — without a §2 out-of-scope line?
 
 **Correctness — is anything wrong?**
 5. Every `Target Files` path verified per Grounding? Any `(new)` file marked as such?
@@ -195,7 +228,7 @@ catches it:
 Append the result to `PLAN.md`:
 ```
 ## Planner Self-Audit
-Checklist: 12/12 pass
+Checklist: 14/14 pass
 Fixed during audit: <what you changed, or "nothing">
 Known gaps: <what you deliberately left out and why, or "none">
 ```
@@ -209,6 +242,8 @@ Keep the returned message under 25 lines — the caller may be an orchestrator w
 budget is the constraint on the whole run. Detail belongs in `PLAN.md`, not in the reply.
 
 - Task count + IDs
+- Spec path + one-line coverage statement (`SPEC.md §5 FR-001→TASK-003`, …)
+- Recovery/superseded pairs (`TASK-007 → TASK-007-R1`) | none
 - Dependency graph (text form: TASK-001 → TASK-003, TASK-002 independent)
 - Wave plan: `wave 1: N tasks | wave 2: M tasks` — flag it if the graph is mostly a chain
 - Self-audit result + any `Known gaps`

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

@@ -37,6 +37,7 @@ Write `docs/AI_HANDOFF/archive/cycle-NNN.md` (if there is anything worth archivi
 ```
 # Cycle NNN — <YYYY-MM-DD> — ABORTED
 ## Summary: cycle was cleared before completion
+## Spec: <copy SPEC.md — or note its path if archived separately>
 ## Tasks: <copy INDEX.md table as-is>
 ```
 If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
@@ -45,8 +46,11 @@ If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY
 
 ```
 PLAN.md  → "# PLAN\n_(empty)_"
+SPEC.md  → restore the untouched template (keep section headings, clear content)
 INDEX.md → empty table header only
 ACTIVE.md → "# ACTIVE\n_(no active cycle)_"
+RUN.md   → set `Phase: done` (or delete) — a live non-done cursor makes the Stop gate
+           refuse the next session's stops; clearing a cycle MUST close the cursor.
 tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
 ```
 

package/templates/.claude/commands/ukit/handoff-create.md

@@ -69,7 +69,21 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    BASE=$(git symbolic-ref --short HEAD)
    ```
 
-3. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
+3. Write `docs/AI_HANDOFF/SPEC.md` — the detailed implementation spec (BẮT BUỘC before tasks).
+   Follow `docs/AI_HANDOFF/SPEC.md`'s template sections (or `templates/docs/AI_HANDOFF/SPEC.md`
+   on a fresh tree): problem/context, goals, non-goals, user journeys, functional requirements
+   with Given/When/Then + error cases, fullstack scope (backend, schema/migrations, API
+   contract, UI+state, integration, security, performance, observability, deploy/rollback),
+   data model, edge cases, test matrix, acceptance criteria, migration steps, open questions
+   with chosen defaults, review checklist.
+
+   The spec must be concrete enough that an executor implements it WITHOUT guessing: exact
+   file paths, module names, API methods, statuses, schemas, validation rules, permissions,
+   empty/error states, migration behavior, and test expectations. Open questions are
+   resolved to a chosen default recorded inline — the plan phase is the only question
+   window, so anything left "TBD" becomes a guess downstream.
+
+4. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
    - §1 Intent — problem + success definition
    - §2 Scope — in / out of scope. **Add a constraint**: same-wave tasks must not modify the same file (prevents merge conflicts). If two tasks need the same file, make one depend on the other.
    - §3 Approach — solution, trade-offs, alternatives rejected
@@ -83,8 +97,9 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    PLANNER_MODEL: <your exact model ID>
    ```
 
-4. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
+5. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
    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, not stored separately)
    - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds)
@@ -93,18 +108,19 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    - Acceptance Criteria (verifiable checklist)
    Missing any field → status: `needs_breakdown`, never `ready`
 
-5. Update `INDEX.md` — one row per task, `status=ready`
+6. Update `INDEX.md` — one row per task, `status=ready`
 
-6. Update `ACTIVE.md`:
+7. Update `ACTIVE.md`:
    ```
    Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <BASE>
    Goal: <1 sentence>
+   Spec: docs/AI_HANDOFF/SPEC.md
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
    Note: wave structure is inferred from task Dependencies fields — not stored here.
 
-7. Report: task IDs, dependency graph, any `needs_breakdown` + reason
+8. Report: task IDs, dependency graph, any `needs_breakdown` + reason
 
 > **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the strong model, execute steps 1–7 above yourself.
 
@@ -121,9 +137,9 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 Two independent strong-model passes shape the plan before any code is written — that gate is
 intact. What it no longer does is hand a stalled plan back and wait.
 
-**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the path to `docs/AI_HANDOFF/PLAN.md`. This MUST be a separate agent invocation from Step 2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
+**Claude Code — MANDATORY, do this before anything else:** 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 Step 2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
 
-1. Reviewer reads `PLAN.md` only (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI — 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` (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, no vague instruction left — 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 Step 2: planner revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for another Step 2.5 review (this becomes the next round). Do NOT commit or hand off to executor on `Issues Found`.
 3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed.
 

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

@@ -66,9 +66,10 @@ numbered step completes:
 Command: handoff-fullstack
 Goal: <one sentence from the **Problem / feature** section above>
 Base: <BASE branch>
-Phase: <P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R5|done>
+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>
+QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 ```
 
 This file is the resume contract. It costs one small write per step and is what turns an
@@ -86,6 +87,89 @@ Only when `RUN.md` is absent or `Phase: done` does a new request start a fresh c
 
 ---
 
+## §0 — Completion contract (terminal outputs)
+
+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
+  `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
+emit a checkpoint it MUST use this shape and be followed by immediate work:
+
+```
+CHECKPOINT — WORK CONTINUING
+Cycle:
+Completed since last checkpoint:
+Currently executing:
+Exact next action:
+Verification status:
+Run cursor updated: YES
+```
+
+Never stop at `recap: ... Next: ...` while unfinished work remains — the Stop gate now
+bounces that stop straight back into the pipeline, so stopping is not even restful; it
+just costs a round-trip.
+
+---
+
+## Phase 0 — Sweep & Inventory (before planning)
+
+Before Phase 1, build the authoritative task inventory — the run owns **all** unfinished
+work, not only the current plan:
+
+1. `docs/AI_HANDOFF/INDEX.md` — every task not `done`/`cancelled_superseded`.
+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.
+5. `git status` / `git diff` — uncommitted work-in-progress that must be finished or
+   checkpointed, never silently dropped.
+
+The inventory feeds P2: the planner either schedules every discovered item or records why
+it is out of scope (§1/§2 of PLAN.md). Silent omission is a plan defect.
+
+**Recovery rule — stuck task records.** For every `pending`, stale `in_progress`, or
+`blocked` task whose record cannot be cleanly resumed (invalid state, orphaned worktree
+gone, contradicting reports):
+
+1. Inspect code/tests/git to see what is actually missing.
+2. Recoverable → finish the original task in place.
+3. Not recoverable → mark the old row `cancelled_superseded`, create `TASK-xxx-R1`
+   (`-R2`, …) with the same spec references, acceptance criteria and verification, link
+   both files' `## Discussion` threads, and execute the replacement in this cycle.
+4. Never leave stranded work merely because a task record was pending.
+
+---
+
+## Watchdog — surviving idle and new assignments
+
+The run must keep itself alive without the human watching.
+
+- **Stop gate (Claude Code, automatic):** while `RUN.md` `Phase:` is not `done`/`blocked`,
+  `completion-gate.sh` refuses the stop with the cursor's `Next:` step. Recaps and
+  premature stops cannot park the run. A stalled-cursor breaker
+  (`handoff.fullstack.stopGateMaxStalledBlocks`, default 12) releases the session if the
+  cursor has genuinely stopped advancing — the escape hatch, not the norm.
+- **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`.
+- **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
+scan in RUN.md as `QuietScans: <n>/<required>`. A scan that finds anything resets the
+counter and starts a new cycle automatically.
+
+---
+
 ## Phase 1+2 — Plan (strong model)
 
 ### P1 — Read context (lite model)
@@ -117,7 +201,15 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    BASE=$(git symbolic-ref --short HEAD)
    ```
 
-3. **Write `docs/AI_HANDOFF/PLAN.md`** — all 6 sections mandatory:
+3. **Write `docs/AI_HANDOFF/SPEC.md`** — the detailed implementation spec, from
+   `templates/docs/AI_HANDOFF/SPEC.md`'s section list (or RULES.md §Spec). It must be
+   concrete enough that an executor implements without guessing: exact paths, module and
+   API names, schemas, validation rules, permissions, empty/error states, migration
+   behavior, and test expectations — every applicable section filled, open questions
+   resolved to chosen defaults recorded inline. Implementation begins from SPEC+PLAN,
+   never from the raw request.
+
+4. **Write `docs/AI_HANDOFF/PLAN.md`** — all 6 sections mandatory:
    - §1 Intent — problem + success definition
    - §2 Scope — in / out of scope; same-wave tasks must not modify the same file (prevents merge conflicts)
    - §3 Approach — solution, trade-offs, alternatives rejected
@@ -131,8 +223,9 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    PLANNER_MODEL: <your exact model ID>
    ```
 
-4. **Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`...** from `_TEMPLATE.md`.
+5. **Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`...** from `_TEMPLATE.md`.
    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)
@@ -141,17 +234,21 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    - Acceptance Criteria (verifiable checklist)
    Missing any field → status `needs_breakdown`, never `ready`.
 
-5. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`.
+6. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`. Every
+   unfinished item from the Phase 0 sweep is either a row here or superseded by a
+   `-R<n>` recovery row.
 
-6. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
+7. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
    ```
    Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <BASE>
    Goal: <1 sentence>
+   Spec: docs/AI_HANDOFF/SPEC.md
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
 
-7. **Report:** task IDs, dependency graph, any `needs_breakdown` tasks + reason.
+8. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
+   `needs_breakdown` tasks + reason.
 
 ### P2.5 — Independent plan review (strong model, separate agent)
 
@@ -164,9 +261,9 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
 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.
 
-**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 path to `docs/AI_HANDOFF/PLAN.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.
+**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 `PLAN.md` only (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI — 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` 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).
 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.
 
@@ -510,9 +607,50 @@ Force-push stays denied, so this can only ever 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.
-Name the blocked tasks in the Final Report.
+Name the blocked tasks in the Final Report. Tasks that stayed `blocked` only because their
+record was unrecoverable get the Phase 0 recovery treatment — `cancelled_superseded` plus a
+`-R<n>` replacement — before the run may close.
+
+Do NOT set `Phase: done` yet — Phase F still has to close the books.
+
+---
+
+## Phase F — Finalize: quiet period, docs, archive
+
+### F1 — Quiet-period scan
+
+Run the sweep from Phase 0 again (INDEX, task files, `docs/TASKS.md`, git status).
+`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.
+
+### F2 — Docs sync
+
+Update only the docs the change actually touched: `docs/WORKLOG.md` (always — one entry
+for the cycle), plus `docs/PROJECT.md` / `docs/CODE_MAP.md` / `docs/CHANGELOG.md` when the
+cycle changed architecture, surface area, or shipped behavior. Record: behavior
+implemented, API/schema/UI changes, migration steps, config changes, verification
+evidence, rollback notes.
+
+### F3 — Archive the cycle
 
-Finally set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
+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>/`.
+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).
+4. Commit the docs + archive changes:
+   `git add -A && git commit -m "handoff: finalize + archive cycle <ID>"`
+
+### 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.
 
 ---
 
@@ -539,17 +677,40 @@ Re-run assertions after removal to confirm clean state.
 
 ## Final Report
 
+The ONLY legal first lines are:
+
+```
+HANDOFF FULLSTACK COMPLETE
+```
+or, when every remaining task shares one external blocker and no safe local work exists
+(RUN.md set to `Phase: blocked` first):
+```
+HANDOFF FULLSTACK BLOCKED
+```
+
+Then the body:
+
 ```
-handoff-fullstack complete:
   Cycle: <ID>
+  Spec: docs/AI_HANDOFF/SPEC.md
   Tasks: <N> approved, <M> blocked
+  Recovery/superseded: <TASK-xxx→TASK-xxx-R1, …> | none
+  Newly assigned processed: <n> | none
+  Quiet scans: <n>/<required>
   Fix rounds used: <0|1|2>
+  Verification: <commands + results>
   Git: <K> wave commits + pushed to <branch>
+  Docs updated: <files>
+  Archive: docs/AI_HANDOFF/archive/cycle-<NN>/
   Worktrees: all cleaned
   Branches: all cleaned
+  Remaining tasks: NONE | <list>
   Blocked (needs you): <TASK-xxx — one-line reason> | none
 ```
 
+A blocked report additionally lists: blocked tasks, exact blocker + evidence, attempted
+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

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

@@ -59,8 +59,12 @@ If this file already exists with `Phase:` not `done` when the command starts, th
 
 Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
 Read `docs/AI_HANDOFF/INDEX.md` → collect `ready` tasks (or the specific task named in the request above).
-If there are no `ready` tasks, check for `changes_requested`/`blocked` ones and run those
-instead. Only if nothing is actionable → report and stop.
+If there are no `ready` tasks, check for `changes_requested`/`blocked`/stale `in_progress`
+ones and run those instead. A stuck record that cannot resume (orphaned worktree,
+contradicting reports) gets the recovery treatment: mark it `cancelled_superseded`, create
+`TASK-xxx-R1` with the same spec references/acceptance/verification, and run the
+replacement — never leave stranded work just because a record was pending.
+Only if nothing is actionable → report and stop.
 
 Verify working tree state:
 ```bash
@@ -125,6 +129,9 @@ Each spawned agent works independently in its own worktree — **NO git commit,
 
 ```
 Read docs/AI_HANDOFF/tasks/TASK-xxx.md
+Read the SPEC.md sections named in the task's `Spec references` — the spec is the contract;
+the task file is the slice. If they disagree, implement the spec and note it in the task's
+## Discussion.
 
 TDD — mandatory:
   1. Write tests from §Test Cases

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

@@ -86,7 +86,10 @@ git status              # overview of modified/new/deleted files
 ```
 
 Review as one unified diff — correctness, regression risk, security, edge cases, maintainability.
-Cross-reference with each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md`.
+Cross-reference each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md` AND the
+`Spec references` sections it names in `docs/AI_HANDOFF/SPEC.md` — spec compliance is the
+primary correctness bar; a diff that drifts from the spec's contract fails even when it
+matches the task file's wording.
 
 ### 2d — Append verdict to each task file
 

package/templates/.claude/commands/ukit/handoff-status.md

@@ -12,8 +12,10 @@ Read and display current handoff state. Do NOT modify any files.
 
 1. `docs/AI_HANDOFF/ACTIVE.md` → cycle ID, goal, base branch
 2. `docs/AI_HANDOFF/INDEX.md` → all tasks + statuses
-3. `git worktree list` → open worktrees
-4. `git branch | grep handoff/` → open handoff branches
+3. `docs/AI_HANDOFF/RUN.md` → fullstack run cursor: `Phase:` ≠ `done`/`blocked` means a run is live and the Stop gate is holding the session to it
+4. `docs/AI_HANDOFF/SPEC.md` → spec exists/fresh (one line)
+5. `git worktree list` → open worktrees
+6. `git branch | grep handoff/` → open handoff branches
 
 ## Report
 
@@ -21,6 +23,8 @@ Read and display current handoff state. Do NOT modify any files.
 ━━━ Handoff Status ━━━━━━━━━━━━━━━━━━━━━━━━
 Cycle:  <ID>   Base: <branch>   Date: <date>
 Goal:   <goal>
+Run:    <Phase — or "no live cursor">
+Spec:   <present | missing>
 
 Tasks:
   ✅ done          TASK-001  <name>