@ngockhoale/ukit 3.4.65 → 3.4.66

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.66 - 2026-10-23
+
+**Handoff hardening: scope-frozen runs, completed-only ARCHIVE, bounded repair, isolated verification.**
+- Stop coordinator: INDEX task rows parse positionally (empty cells keep columns; malformed rows fail closed); an unreadable or vanished archive snapshot no longer falls back to stale task headers; optional `ScopeQueue`/`Cycle` freeze a run to its assigned scope so unrelated queued or archived history cannot prove completion; `Paused: yes` releases continuation without minting completion.
+- Archive writer: canonical `docs/AI_HANDOFF/ARCHIVE/cycle-NN/`; refuses (before any write) symlinked docs/AI_HANDOFF/archive/cycle/INDEX/TASK paths, malformed or unreadable prior snapshots and any task-enumeration error instead of snapshotting a partial cycle; legacy lowercase archives stay read-only.
+- Commands: create queues independent plans instead of overwriting, preserves sources and amendments; fullstack/implement/review commit with `git commit --only` explicit paths (unrelated staged and unstaged owner work preserved, proven against a real Git fixture); failures route to bounded repair or replan instead of blocked; one persisted Recovery exception after escalation; clear pauses and preserves unfinished work and keeps read-back write verification; blocked is reserved for external blockers or genuine owner requirement conflicts.
+- `yarn test:handoff` now runs `tests/handoff/**` in a disposable copy with throwaway HOME, excluded live handoff state (any-case ARCHIVE), vetted symlinks, checked git setup, bounded children and explicit path validation; wired into `release:verify`.
+
 ## 3.4.65 - 2026-10-22
 
 **Configuration capture: Vietnamese comparison is not a mutation order.**

package/manifests/documentation.yaml

@@ -616,6 +616,17 @@ entries:
     validation: [none]
     archive_policy: immutable
     notes: 2026-10-19 captured OMP lifecycle closure and offline verification boundaries
+  - id: docs-analysis-handoff-hardening
+    path: docs/analysis/HANDOFF-HARDENING.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/HANDOFF-HARDENING.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Current owner scope, hardening evidence and remaining release obligations; not runtime state
   - id: docs-analysis-orchestration-final-verification
     path: docs/analysis/ORCHESTRATION-FINAL-VERIFICATION.md
     class: archive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.65",
+  "version": "3.4.66",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -74,7 +74,7 @@
     "release:verify": "node ./scripts/release/verify-release.mjs",
     "test": "vitest run",
     "test:liveness": "vitest run tests/liveness/",
-    "test:handoff": "node ./bin/ukit install >/dev/null && node --test --test-concurrency=1 'tests/handoff/**/*.test.mjs' 'tests/handoff/**/*.test.js'",
+    "test:handoff": "node ./scripts/test/run-handoff-isolated.mjs",
     "test:watch": "vitest"
   },
   "engines": {

package/scripts/release/verify-release.mjs

@@ -93,6 +93,13 @@ const steps = [
     args: ['vitest', 'run', 'tests/consistency/docContracts.test.js'],
     env: process.env,
   },
+  {
+    // Bounded behavioral lane: runs the handoff suite in a disposable copy (never the checkout).
+    label: 'Handoff isolated lane',
+    command: 'yarn',
+    args: ['test:handoff'],
+    env: process.env,
+  },
   {
     label: 'Core test suite',
     command: 'yarn',

package/scripts/test/run-handoff-isolated.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// Runs the handoff test lane in a disposable copy of the project so `ukit install`
+// (which writes .claude/, .ukit/, .cache/) can never overwrite the source checkout.
+// The child's native exit code is propagated; the copy is removed in every case.
+import { spawnSync } from 'node:child_process';
+import { constants, cpSync, existsSync, lstatSync, mkdtempSync, readdirSync, readlinkSync, realpathSync, rmSync } from 'node:fs';
+import { buildIsolatedEnv } from '../../tests/helpers/testHomeIsolation.mjs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Project root is the directory the runner was invoked from (package.json scripts run at the root).
+const sourceRoot = path.resolve(process.cwd());
+const SKIP_TOP_LEVEL = new Set(['.git', 'node_modules']);
+// Live handoff run/backlog state and runtime caches must never leak into the fixture: a copied
+// RUN.md or queue makes the handoff gates act on the real project's pending work.
+const LIVE_STATE_PREFIXES = [
+  'docs/AI_HANDOFF/RUN.md',
+  'docs/AI_HANDOFF/INDEX.md',
+  'docs/AI_HANDOFF/ACTIVE.md',
+  'docs/AI_HANDOFF/HISTORY.md',
+  'docs/AI_HANDOFF/tasks',
+  'docs/AI_HANDOFF/queued',
+  'docs/AI_HANDOFF/archive',
+  'docs/AI_HANDOFF/ARCHIVE',
+  'docs/AI_HANDOFF/blocked-tests',
+  'docs/AI_HANDOFF/benchmark',
+  '.ukit/storage/cache',
+  '.ukit/storage/security',
+  '.ukit/storage/runs',
+];
+const unsafeSymlinks = [];
+
+function shouldCopy(src) {
+  const rel = path.relative(sourceRoot, src);
+  if (rel === '') return true;
+  const top = rel.split(path.sep)[0];
+  if (SKIP_TOP_LEVEL.has(top)) return false;
+  // Nested worktrees would recursively copy the whole repo again.
+  if (rel.split(path.sep).slice(0, 2).join('/') === '.claude/worktrees') return false;
+  const posixRel = rel.split(path.sep).join('/');
+  // Case-insensitive: ARCHIVE/archive are the same directory on macOS/Windows.
+  const lower = posixRel.toLowerCase();
+  if (LIVE_STATE_PREFIXES.some((p) => lower === p.toLowerCase() || lower.startsWith(`${p.toLowerCase()}/`))) return false;
+  // A symlink must stay inside the tree; otherwise the copy would write through to the owner.
+  if (lstatSync(src).isSymbolicLink()) {
+    const target = readlinkSync(src);
+    const resolved = path.resolve(path.dirname(src), target);
+    const inside = path.relative(sourceRoot, resolved);
+    if (path.isAbsolute(target) || inside.startsWith('..') || path.isAbsolute(inside)) {
+      unsafeSymlinks.push(posixRel);
+      return false;
+    }
+  }
+  if (LIVE_STATE_PREFIXES.some((p) => posixRel === p || posixRel.startsWith(`${p}/`))) return false;
+  return true;
+}
+
+let childEnv = process.env;
+// Hard bound for every child (git, install, the node:test run) so a hung test cannot stall a release.
+const CHILD_TIMEOUT_MS = 20 * 60 * 1000;
+
+function run(cwd, command, args) {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit', env: childEnv, timeout: CHILD_TIMEOUT_MS });
+  if (result.error) {
+    console.error(`[handoff-isolated] failed to start ${command}: ${result.error.message}`);
+    return 1;
+  }
+  if (result.signal) {
+    console.error(`[handoff-isolated] ${command} killed by signal ${result.signal}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+function main() {
+  const copyRoot = mkdtempSync(path.join(os.tmpdir(), 'ukit-handoff-isolated-'));
+  console.log(`[handoff-isolated] copy=${copyRoot}`);
+  // Throwaway HOME so install/tests never touch the caller's real user layer.
+  const homeRoot = mkdtempSync(path.join(os.tmpdir(), 'ukit-handoff-home-'));
+  childEnv = { ...process.env, ...buildIsolatedEnv(homeRoot) };
+  let exitCode = 1;
+  try {
+    cpSync(sourceRoot, copyRoot, { recursive: true, filter: shouldCopy, verbatimSymlinks: true });
+    if (unsafeSymlinks.length > 0) {
+      console.error(`[handoff-isolated] unsafe source symlink (resolves outside the project): ${unsafeSymlinks.join(', ')}`);
+      return;
+    }
+
+    // Several handoff tests call git (worktree add, ls-files, check-ignore). The copy has no
+    // .git, so give it an isolated throwaway repo with the copied tree committed.
+    for (const gitArgs of [
+      ['init', '-q'],
+      ['add', '-A'],
+      ['-c', 'user.email=isolated@ukit.test', '-c', 'user.name=isolated', 'commit', '-q', '-m', 'isolated snapshot'],
+    ]) {
+      const code = run(copyRoot, 'git', gitArgs);
+      if (code !== 0) {
+        console.error(`[handoff-isolated] git snapshot setup failed (git ${gitArgs.find((a) => !a.startsWith('-') && !a.includes('=')) ?? gitArgs[0]} exit ${code})`);
+        exitCode = code;
+        return;
+      }
+    }
+
+    // Dependencies are cloned (copy-on-write where supported) AFTER the snapshot commit so tool
+    // caches written under node_modules can never write through to the source checkout.
+    // UKIT_HANDOFF_DEPS_ROOT lets a worktree without node_modules borrow an installed checkout's.
+    const depsRoot = path.resolve(process.env.UKIT_HANDOFF_DEPS_ROOT || sourceRoot);
+    const sourceModules = path.join(depsRoot, 'node_modules');
+    const copyModules = path.join(copyRoot, 'node_modules');
+    if (existsSync(sourceModules) && !existsSync(copyModules)) {
+      // Vet dependency symlinks too: one that resolves outside node_modules (for example a link
+      // back to the source checkout) would let the copy write through to the owner's tree.
+      const realModules = realpathSync(sourceModules);
+      cpSync(sourceModules, copyModules, {
+        recursive: true,
+        verbatimSymlinks: true,
+        mode: constants.COPYFILE_FICLONE,
+        filter: (src) => {
+          if (!lstatSync(src).isSymbolicLink()) return true;
+          const resolved = path.resolve(path.dirname(src), readlinkSync(src));
+          const rel = path.relative(realModules, resolved);
+          return !path.isAbsolute(readlinkSync(src)) && !rel.startsWith('..') && !path.isAbsolute(rel);
+        },
+      });
+    }
+
+    const installCode = run(copyRoot, process.execPath, [path.join(copyRoot, 'bin', 'ukit'), 'install']);
+    if (installCode !== 0) {
+      console.error(`[handoff-isolated] install failed with exit ${installCode}`);
+      exitCode = installCode;
+    } else {
+      // Optional targeted mode: positional args are handoff test files relative to the project root.
+      const handoffRoot = path.join(copyRoot, 'tests', 'handoff');
+      const targeted = [];
+      for (const rel of process.argv.slice(2)) {
+        const full = path.resolve(copyRoot, rel);
+        const within = path.relative(handoffRoot, full);
+        if (within === '' || within.startsWith('..') || path.isAbsolute(within) || path.isAbsolute(rel)) {
+          console.error(`[handoff-isolated] invalid handoff test path: ${rel}`);
+          exitCode = 2;
+          return;
+        }
+        targeted.push(full);
+      }
+      const testFiles = [];
+      const testDir = path.join(copyRoot, 'tests', 'handoff');
+      if (targeted.length > 0) testFiles.push(...targeted);
+      else if (existsSync(testDir)) collectTests(testDir, testFiles);
+      if (testFiles.length === 0) {
+        console.error('[handoff-isolated] no handoff test files found');
+        exitCode = 1;
+      } else {
+        exitCode = run(copyRoot, process.execPath, ['--test', '--test-concurrency=1', ...testFiles]);
+      }
+    }
+  } finally {
+    // Diagnostic escape hatch: keep the copy for inspection when explicitly requested.
+    if (process.env.UKIT_HANDOFF_KEEP_COPY === '1') {
+      console.log(`[handoff-isolated] keeping copy for inspection: ${copyRoot}`);
+    } else try {
+      rmSync(copyRoot, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`[handoff-isolated] cleanup failed for ${copyRoot}: ${error.message}`);
+    }
+    try { rmSync(homeRoot, { recursive: true, force: true }); } catch {}
+    process.exitCode = exitCode;
+  }
+}
+
+function collectTests(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectTests(full, out);
+    else if (/\.test\.(mjs|js)$/.test(entry.name)) out.push(full);
+  }
+}
+
+main();

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

@@ -210,8 +210,9 @@ verdict block — with these additions:
 
 ### 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.
+- Path to the spec/plan document (e.g. `docs/plans/*.md`). No diff and no executor report.
 - 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`.
+- A plan is not reviewable from SPEC+PLAN alone. Start from the original: `SOURCE.md` (verbatim original bytes; verify the recorded sha256 against them, and for chat input the durable verbatim message origin stands in for the file), then the classification in `LEDGER.md` (every row dispositioned, feasible/adapted rows carry evidence), `NOTES.md` when present (optional source-only notes; a missing note is caught because the chain starts at SOURCE, not at NOTES), the `tasks/TASK-*.md` files of that plan (spec references, acceptance and verification), and the current source the Target Files touch (index-first). Compare the chain SOURCE → classification (LEDGER) → tasks; check NOTES against the same chain. A `feasible`/`adapted` requirement that the ledger or source shows but no task covers is a Completeness finding, unless it is exempt when their queue entry, owner decision, or classification is recorded (deferred, blocker, rejected, proposal, and example rows are not tasks); a task whose verification does not prove its acceptance is a Clarity finding.
 
 ### Review order
 
@@ -239,6 +240,8 @@ Only flag issues that would cause real problems during implementation planning.
 
 Append (do NOT overwrite) this block to the end of the reviewed document under a `## Plan Review Log` section — create the section if it doesn't exist yet, keep all prior round entries:
 
+Every finding bullet is written as `<location> :: <claim>` (location = the SOURCE/LEDGER/NOTES/TASK/SPEC/PLAN line or section it cites; claim = the defect in one sentence). The planner derives the finding signature from this exact pair (lowercased, whitespace collapsed, claim truncated to 120 characters), so keep it stable across rounds for an unchanged defect.
+
 ```
 ### Round <N> — <YYYY-MM-DD> · <your model>
 Status: Approved | Issues Found

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

@@ -284,5 +284,8 @@ budget is the constraint on the whole run. Detail belongs in `PLAN.md`, not in t
 
 - Do NOT implement. Job ends when all tasks are `ready` or `needs_breakdown`.
 - Undone tasks in INDEX.md → continue that cycle; plan only what is still missing. Do not ask whether to start fresh, and do not overwrite task files that already carry an executor report or reviewer verdict.
+- An independent new request is never an overwrite of a ready plan. Overwrite only when the human explicitly names the existing 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. Otherwise write to the queued root.
+- A task that already carries an executor report is superseded, never overwritten: write the replacement as `TASK-<id>-R<n>.md` and keep the original file with its report.
+- Round cap: count only completed reviewer verdicts (`### Round` entries with a `PLAN_REVIEW:` or verdict line). Repair markers (`### Repair <N>`, `### Escalation <N>`) are never counted. When two verdicts exist and no escalation is recorded, record `### Escalation 1 — <reason>`, apply the findings with a changed strategy (`### Repair <N> — changed strategy`), and let the reviewer run once more. If the escalation is already spent, do not request another round: mark still-flagged tasks `needs_breakdown` and write `PLAN_REVIEW: Unresolved — …`, never `Approved`. Identical findings after a repair (the finding signature set is unchanged) are non-progress: do not run another identical loop; retain Unresolved with a precise diagnostic. **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; (3) request 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, do not request another review: retain Unresolved with a precise diagnostic. An owner conflict routes an owner decision. Never mark a plan `Approved` by the cap alone. After every verdict, append `### Signatures Round <N>: <sig>; <sig>; …` where each `<sig>` is the reviewer's `<location> :: <claim>` pair normalized (lowercased, whitespace collapsed, claim first 120 characters). Mandatory overflow (feasible/adapted rows beyond the 10-task dispatch window) is grouped by dependency chain into `queued/<plan-slug>-overflow-<NN>/` (max+1 index; on collision append `-2`, `-3`, …), never a deliberate-future header.
 - Cannot determine test cases → `needs_breakdown` + Discussion thread note. Never mark a task `ready` with vague tests just to keep the pipeline moving — a task with fake tests passes review and ships a bug, which costs far more than one blocked task.
 - You may be invoked unattended. Ask nothing; where the caller allowed questions, that window closed before you were spawned. Resolve ambiguity by reading the codebase, choose the option you would recommend, and record the choice and its rationale in `PLAN.md §3`.

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

@@ -37,54 +37,53 @@ git branch | grep handoff  # every handoff/* branch must be named in the retaine
 An unmerged `handoff/integration` branch is retained the same way: report it with its reason
 (`unmerged history`), never delete it with `-D`.
 
-## Step 2 — Unstage any pending changes
+## Step 2 — Preserve staged owner work
 
-```bash
-git restore --staged . 2>/dev/null || true
-```
+Inspect `git diff --cached --name-only`. Unstage only explicitly identified run-owned
+paths when necessary; leave unrelated staged changes untouched. Clearing does not authorize
+reverting source, discarding dirty files, or changing host permissions.
 
-## Step 3 — Archive whatever is done (best-effort)
+## Step 3 — Preserve open work; archive only verified completion
 
-Read `docs/AI_HANDOFF/INDEX.md` for any tasks that were completed.
-Write `docs/AI_HANDOFF/archive/cycle-NNN.md` (if there is anything worth archiving):
-```
-# 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`.
+Clearing is cancellation or pause, **not completion**. Read INDEX, PLAN, review reports and
+verification/release evidence together. Pending, blocked, pending-review, changes-requested,
+pending-release and failed integration obligations remain open under `docs/AI_HANDOFF/`.
+A `done` summary alone is not proof. Do not move an incomplete cycle into completed history.
 
-After writing the archive file, **verify the write** — read it back and confirm
-the `ABORTED` heading is present; on mismatch or read failure retry once, on
-second failure stop and report (same rule as handoff-fullstack's "State-file
-write verification").
+Only when every assigned obligation has independently verified terminal-success evidence,
+use the fullstack F3 procedure: move the completed task records to
+`docs/AI_HANDOFF/ARCHIVE/cycle-NN/`, run `archive-cycle` before resetting INDEX, preserve
+SPEC/PLAN/LEDGER/source/review/evidence, and verify the resulting snapshot. Never prune prior
+history. Legacy lowercase `archive/` and single-file histories are read-only provenance,
+not authorization to resume old work or proof that the current cycle completed.
 
-## Step 4 — Reset state files
+## Step 4 — Pause, or reset state files, without losing the backlog
 
-```
-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 cursor that is neither `done` nor `blocked`
-           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)
-```
+If unfinished work remains open, keep SPEC, PLAN, LEDGER, INDEX and task reports intact.
+Set `Paused: yes` in RUN.md, keep its actual phase and scope, and record the cancellation
+reason plus the next recovery action. Update ACTIVE.md to say paused, not completed.
+The existing pause marker releases continuation safely; do not manufacture `Phase: done`
+or erase RUN.md to evade a completion predicate.
+
+Only after the completed-cycle archive and evidence are verified may the active planning
+files be reset to their templates and INDEX to its empty header. Preserve `_TEMPLATE.md`,
+queued plans, amendments and every record not included in that completed archive.
 
-Every file rewritten above is a state file — **verify the write** on each:
-read it back and confirm the marker you just wrote (empty INDEX header,
-`_(no active cycle)_`, `Phase: done`). On mismatch or read failure retry the
-write once; on second failure STOP and report — never leave unverified state
-files behind, or the next cycle resumes from stale bytes.
+Every file rewritten above is a state file — **verify the write** on each: read it back and
+confirm the marker you just wrote (`Paused: yes`, the paused ACTIVE.md line, or, after a
+verified completed archive, the empty INDEX header). On mismatch or read failure retry the
+write once; on second failure STOP, report the actual error and retain all recovery records —
+never leave unverified state files behind (same rule as handoff-fullstack's "State-file write
+verification").
 
 ## Step 5 — Report
 
 ```
-Cleared: X receipt-gated tasks removed, staged changes unstaged.
+Cleared: X receipt-gated worktrees removed; unrelated staged changes preserved.
 Retained with reason: <list each surviving worktree/branch and why — receipt missing,
 not approved, FAIL, missing model, dirty vs snapshot, unmerged history>.
-Handoff docs reset. Ready for new cycle.
+Open obligations: <IDs and recovery action; paused, not completed>.
+Completed archive: <verified path, or none>.
 ```
 
 > Claude Code: spawn `ukit-small-task-maintainer` (haiku). omp: the `task` tool with `agent: "ukit-small-task-maintainer"`.

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

@@ -42,11 +42,14 @@ is **not** `done`/`blocked`, a fullstack run is live and owns the canonical plan
   executed.
 - Report the queued path; the live run continues untouched.
 
-**Explicit abandonment is the only way to replace a live run.** Only when the human
-explicitly says to abandon/clear the current run, first run `/ukit:handoff-clear`
-(sets `Phase: done` / removes `RUN.md`), then plan against the canonical files. A mere
-mention of the new work is not abandonment — absent that explicit instruction, always
-take the queued path.
+**Explicit abandonment never overwrites an unfinished canonical run.** Only when the human
+explicitly says to abandon/clear the current run, first run `/ukit:handoff-clear`, which
+sets `Paused: yes` in `RUN.md` and keeps its actual phase and scope, recording the
+cancellation reason and next recovery action (it never sets `Phase: done` and never erases
+`RUN.md`). The paused canonical files are still unfinished: the new request is written under
+the queued root `docs/AI_HANDOFF/queued/<slug>/` and the canonical task files, INDEX, and
+SPEC/PLAN are not overwritten. A mere mention of the new work is not abandonment — absent
+that explicit instruction, always take the queued path.
 
 ### Planning-only output root (decided here, passed to the planner)
 
@@ -102,11 +105,16 @@ the document into a LEDGER, a bounded task set and a queue, and never implements
   under `/ukit:handoff-fullstack` or `/ukit:handoff-implement`.
 - **Queue threshold:** at most 10 tasks in total: all active (`ready`). More than 10: the
   first 10 by dependency order are active and the rest become queued blueprints under
-  `docs/AI_HANDOFF/queued/<slug>/` whose `HANDOFF.md` header carries
-  `QueueIntent: deliberate-future`. Queue contract: the header also carries `QueueOrder: <int>`
-  (drain order, lowest first), `QueueDrain: separate-backlog` and `QueueSource: <R-IDs/epics>`;
-  `/ukit:handoff-fullstack` reports such a blueprint as `Backlog: <slug>`, never folds it into
-  the current cycle, and drains it only when the human names the slug (one blueprint per invocation).
+  `docs/AI_HANDOFF/queued/<slug>/`. Only rows the LEDGER dispositions `deferred` (intentionally
+  later) get a `HANDOFF.md` header carrying `QueueIntent: deliberate-future`. Overflow of
+  `feasible`/`adapted` (mandatory) rows is queued **without** `QueueIntent: deliberate-future`,
+  so the fullstack sweep still folds it in — mandatory work is never silently excluded as
+  deliberate-future. Mandatory overflow carries none of the `Queue*` header lines; it is a legacy
+  blueprint and is consumed like any other queued plan. Queue contract for the deliberate-future kind
+  (LEDGER `deferred` rows only): the header also carries `QueueOrder: <int>` (drain order, lowest
+  first), `QueueDrain: separate-backlog` and `QueueSource: <R-IDs/epics>`; `/ukit:handoff-fullstack`
+  reports such a blueprint as `Backlog: <slug>` and never folds it into the current cycle; it drains
+  only when the human names the slug (one blueprint per invocation).
 
 Model split on Claude Code: haiku/`unic-lite` gathers, opus/`unic-smart` decides, and
 sonnet/`unic-code` implements later; omp maps these to `@smol`/`@slow`/`@default`.
@@ -167,14 +175,16 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 0. **Live-run guard — decide OUTPUT_ROOT first (see "A live fullstack run is never
    overwritten").** If Step 1 reported `RUN.md` with a `Phase:` that is not `done`/`blocked`,
    a fullstack run is live: set `OUTPUT_ROOT = docs/AI_HANDOFF/queued/<slug>/` (`<slug>` =
-   a short kebab name for this work), write ONLY there, and skip steps 1, 6 and 7 — the
-   canonical `RUN.md`/`INDEX.md`/`PLAN.md`/`SPEC.md`/`ACTIVE.md`/`tasks/` stay untouched.
+   a short kebab name for this work; if that directory already exists, append `-2`, `-3`, … —
+   never overwrite an existing blueprint), write ONLY there, and skip steps 1 and 7. Step 6
+   writes the queued root's own draft `INDEX.md`, whose rows are `queued_blueprint`, never
+   `ready`. The canonical `RUN.md`/`INDEX.md`/`PLAN.md`/`SPEC.md`/`ACTIVE.md`/`tasks/` stay untouched.
    Otherwise `OUTPUT_ROOT = docs/AI_HANDOFF/`. Everything below writes under `OUTPUT_ROOT`.
 
 1. Check INDEX.md task statuses (canonical root only — skip when the live-run guard routed
    you to the queued root):
-   - All tasks are `ready` (planning only) → **re-run allowed**: overwrite PLAN.md and TASK-xxx.md freely — this is iterative refinement.
-   - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite**: that cycle is mid-flight and its task files carry executor reports and verdicts. Report which tasks are in flight and point the human at `/ukit:handoff-review` (to finish the cycle) or `/ukit:handoff-clear` (to abandon it). Planning is the one phase where stopping is correct — there is nothing safe to do automatically here.
+   - All tasks are `ready` (planning only) → **only an explicit amendment may overwrite**: when the human names the existing plan to refine: 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>/` under the same root (scan existing rev dirs and take max+1; never reuse or overwrite an existing rev dir). 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** (a different goal, even when the old tasks are all `ready`) is NOT an amendment: write it under the queued root `docs/AI_HANDOFF/queued/<slug>/` and never overwrite the existing canonical plan.
+   - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite** the in-flight cycle: its task files carry executor reports and verdicts. An **independent new request** is still planned and written under the queued root `docs/AI_HANDOFF/queued/<slug>/` (it is never refused for this reason); report which tasks are in flight and point the human at `/ukit:handoff-review` (to finish the cycle) or `/ukit:handoff-clear` (to abandon it). Only an explicit amendment of the in-flight plan is refused, with that pointer.
    - No tasks → fresh cycle, proceed normally.
 
 2. Resolve base branch:
@@ -221,9 +231,12 @@ 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`
 
-6. Update `${OUTPUT_ROOT}INDEX.md` — one row per task, `status=ready`. **Skip entirely when
-   the live-run guard routed you to the queued root** — a blueprint carries no runnable
-   `ready` row; its `HANDOFF.md` activation notes are the record instead.
+6. Update `${OUTPUT_ROOT}INDEX.md` — one row per task. Canonical root: `status=ready`.
+   **Queued root: a draft index with `status=queued_blueprint` rows, never `ready`.** The queued
+   blueprint's own `INDEX.md` and `tasks/` are a draft only: they are not canonical runnable
+   admission. The "first 10 active" rule applies to the canonical root alone; a blueprint's tasks
+   become runnable only when `/ukit:handoff-fullstack` folds them into `docs/AI_HANDOFF/tasks/`
+   and the canonical `INDEX.md`. Its `HANDOFF.md` activation notes are the record of intent.
 
 7. Update `ACTIVE.md` (canonical root only — **skip when queued**; the queued blueprint's
    `HANDOFF.md` replaces it):
@@ -249,14 +262,20 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 
 - 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, and do not stop. 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` listing what changed, then finish.
+- Count completed reviewer verdicts = `### Round` entries that carry a `PLAN_REVIEW:` or verdict line (repair-only `### Round <N> — findings applied …` markers are NOT counted).
+- count ≥ 2 and no escalation recorded yet → **bounded escalation, once, in this run.** Record the escalation in the log as `### Escalation 1 — <reason>` 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 the reviewer 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: continue the independent work (the other tasks, the queued requests), and mark each still-flagged task `needs_breakdown` with its open finding named unless the Recovery exception runs.
+- Verdict `Approved` (in the escalation round or earlier) → append `PLAN_REVIEW: Approved by <reviewer model>` as in step 3 below.
+- Verdict `Issues Found` after the escalation, or an escalation that cannot run → the planner applies the findings to the affected tasks only. Any task still carrying an open finding is `needs_breakdown` (never `ready`), and the footer reads `PLAN_REVIEW: Unresolved — round cap reached, findings applied without independent verification`, never `Approved`. The run then ends the planning step with that explicit state in the report; the `Plan Review Log` and the `needs_breakdown` marks name what is open. Nothing is left silently pending, and no later invocation is required to make progress.
+- 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 triggers the Unresolved path immediately; it is never retried in a loop and never marked 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 stop the loop. An owner conflict routes an owner decision.
 
-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.
+Two independent strong-model passes shape the plan before any code is written, and the escalation
+round gives one more fresh pass on anything still open. A stalled plan is never approved by the cap.
 
 **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 `${OUTPUT_ROOT}PLAN.md` AND `${OUTPUT_ROOT}SPEC.md` (canonical root, or the queued root when one was chosen). 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 `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).
+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 executor report, no diff). 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, that no feasible/adapted row lacks evidence, and 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.