@ngockhoale/ukit 3.4.67 → 3.4.68

package/template_project/.claude/ukit/runtime/task-record-reconciliation.mjs

@@ -0,0 +1,46 @@
+// Conservative task-record comparison only. Evidence must be independently loaded and
+// authenticated by the caller; this function grants neither completion nor cleanup.
+import crypto from 'node:crypto';
+
+const sha = (text) => crypto.createHash('sha256').update(text).digest('hex');
+const fail = (reason) => { throw new Error(reason); };
+const statusLine = /^- Status: `([^`\r\n]+)`\r?$/gm;
+const verdicts = (text) => [...text.matchAll(/^VERDICT:\s*([^\r\n]+)/gm)].map((m) => m[1].trim());
+
+export function reconcileTaskRecord(source, destination, proof, evidence) {
+  if (typeof source !== 'string' || typeof destination !== 'string' || !proof || !(evidence instanceof Map)) fail('invalid-proof');
+  const srcStatus = [...source.matchAll(statusLine)];
+  const dstStatus = [...destination.matchAll(statusLine)];
+  if (srcStatus.length !== 1 || dstStatus.length !== 1) fail('status-ambiguous');
+  let preserved = source;
+  let status = null;
+  if (srcStatus[0][1] !== dstStatus[0][1]) {
+    const p = proof.status;
+    // This narrow repair may retain a blocked integration, never promote delivery.
+    if (!p || p.before !== srcStatus[0][1] || p.after !== dstStatus[0][1] || p.after !== 'blocked') fail('status-unsupported');
+    const ev = evidence.get(p.evidence);
+    if (typeof ev !== 'string' || !ev.includes(dstStatus[0][0])) fail('status-evidence-missing');
+    preserved = source.slice(0, srcStatus[0].index) + dstStatus[0][0] + source.slice(srcStatus[0].index + srcStatus[0][0].length);
+    status = { ...p };
+  }
+  // All source bytes other than the separately evidenced status MUST be preserved.
+  // That includes requirements, AC, dependencies, executor reports and old verdicts.
+  if (!destination.startsWith(preserved)) fail('protected-content-changed');
+  const additions = proof.additions;
+  if (!Array.isArray(additions) || additions.map((p) => p.text).join('') !== destination.slice(preserved.length)) fail('unexplained-addition');
+  const knownVerdicts = new Set(verdicts(source));
+  const checked = [];
+  for (const p of additions) {
+    if (!p || typeof p.text !== 'string' || !p.text.trim()) fail('invalid-addition');
+    const ev = evidence.get(p.evidence);
+    if (typeof ev !== 'string' || !ev.includes(p.text)) fail('addition-evidence-missing');
+    const headings = [...p.text.matchAll(/^#{1,6}\s+(.+)$/gm)].map((m) => m[1]);
+    if (!headings.length || headings.some((h) => !/^(?:Reviewer Verdict|Recovery (?:evidence|persistence|integration debt)|Owner-bound integration blocker)(?:\s|$)/.test(h))) fail('metadata-section-unsupported');
+    for (const v of verdicts(p.text)) {
+      if (knownVerdicts.size && !knownVerdicts.has(v)) fail('verdict-changed');
+      knownVerdicts.add(v);
+    }
+    checked.push({ sha256: sha(p.text), evidence: p.evidence });
+  }
+  return { kind: 'history-progression', sourceSha256: sha(source), destinationSha256: sha(destination), protectedSha256: sha(preserved), status, additions: checked, completion: false, cleanupEligible: false };
+}

package/template_project/.claude/ukit/runtime/task-watchdog.mjs

@@ -136,6 +136,9 @@ export async function readState(statePath) {
     return {
       firstSeen: isPlainObject(parsed?.firstSeen) ? { ...parsed.firstSeen } : {},
       hardBlocks: isPlainObject(parsed?.hardBlocks) ? { ...parsed.hardBlocks } : {},
+      // Cycle stamp (stale-state across cycles): surfaced so the evaluator can
+      // detect anchors left by a PREVIOUS cycle on a reused task id.
+      ...(typeof parsed?.cycle === 'string' ? { cycle: parsed.cycle } : {}),
     };
   } catch {
     return { firstSeen: {}, hardBlocks: {} };
@@ -393,18 +396,37 @@ export function pickLastGreen(task) {
  *   listInProgressTasks(projectRoot))
  * @param {number} [options.lockBudgetMs] - per-acquisition lock budget; the
  *   coordinator passes a short slice so two acquisitions fit the hook deadline
+ * @param {string} [options.cycle] - the run's current cycle (`Cycle:` from RUN.md,
+ *   `cycle-NN`/`NN`). Task ids restart per cycle, so anchors recorded under a
+ *   DIFFERENT cycle say nothing about this cycle's tasks: the state's
+ *   firstSeen/hardBlocks are reset and re-stamped before evaluation. Absent or
+ *   unparseable → legacy cycle-blind behavior (state kept as-is).
  */
-export async function evaluateStopWatchdog({ projectRoot, now = Date.now(), config = null, tasks = null, lockBudgetMs } = {}) {
+export async function evaluateStopWatchdog({ projectRoot, now = Date.now(), config = null, tasks = null, lockBudgetMs, cycle } = {}) {
   if (!config) config = await loadConfig(path.join(projectRoot, '.ukit', 'storage', 'config.json'));
   if (!tasks) tasks = await listInProgressTasks(projectRoot);
 
   const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'task-watchdog', 'state.json');
   const state = await readState(statePath);
+  // Same identity rule as the claim stamps (resumable-run.mjs normalizeClaimCycle):
+  // `cycle-NN`/`NN` → `cycle-NN`, anything else → no scoping this pass.
+  const cycleMatch = String(cycle ?? '').trim().match(/^(?:cycle-)?(\d+)$/i);
+  const cycleTag = cycleMatch ? `cycle-${cycleMatch[1].padStart(2, '0')}` : null;
+  // A missing stamp (pre-upgrade state) resets too: the only legacy window is
+  // the upgrade transition, and a fresh clock under-enforces mildly where a
+  // stale one false-trips a brand-new task. Same-cycle stamps keep everything.
+  const staleCycle = cycleTag !== null && state.cycle !== cycleTag;
   const lockOptions = Number.isFinite(lockBudgetMs) ? { deadlineMs: lockBudgetMs } : {};
 
   // Anchor firstSeen via one lock-scoped read-modify-write (TASK-024 semantics).
   try {
     await mutateWatchdogState(statePath, (fresh) => {
+      if (staleCycle) {
+        // New cycle: the reused ids are NEW tasks — fresh clocks, fresh caps.
+        fresh.firstSeen = {};
+        fresh.hardBlocks = {};
+      }
+      if (cycleTag !== null) fresh.cycle = cycleTag;
       for (const task of tasks) {
         try {
           ensureFirstSeen(fresh, task.id, now);
@@ -413,7 +435,11 @@ export async function evaluateStopWatchdog({ projectRoot, now = Date.now(), conf
     }, lockOptions);
   } catch {}
 
-  const evals = evaluateBudgets({ tasks, state, now, config });
+  // A successful reset above re-anchored everything at `now`; evaluate against
+  // the reset view even if the lock failed (empty view → `now` anchors, which
+  // can only under-report, never falsely trip a fresh cycle's task).
+  const effectiveState = staleCycle ? { firstSeen: {}, hardBlocks: {} } : state;
+  const evals = evaluateBudgets({ tasks, state: effectiveState, now, config });
   const hardResults = evals.filter((r) => r.phase === 'hard');
   const softResults = evals.filter((r) => r.phase === 'soft');
 

package/template_project/.claude/ukit/runtime/worktree-allocation.mjs

@@ -0,0 +1,75 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { withAsyncLock } from './async-lock.mjs';
+import { readTaskClaim, taskClaimsPath } from './resumable-run.mjs';
+
+const exec = promisify(execFile);
+
+// Run-owned owner authorization, not a host permission override. Agent isolation
+// remains forbidden: only the orchestrator's explicit allocation uses this path.
+export function allocationPolicy(cursor, taskId) {
+  if (!/^TASK-\d+$/.test(taskId)) throw new Error('invalid task id');
+  if (!/^Worktree-Policy:[ \t]*existing-only\b/m.test(cursor)) throw new Error('existing-only policy required');
+  const cycles = [...cursor.matchAll(/^Cycle:[ \t]*(\d+)[ \t]*$/gm)];
+  if (cycles.length !== 1) throw new Error('ambiguous cycle');
+  const cycle = cycles[0][1];
+  const entries = [...cursor.matchAll(/^Worktree-Allow:[ \t]*(\S+)[ \t]+(\S+)[ \t]+(\S+)[ \t]+(\S+)[ \t]*$/gm)].filter(m => m[1] === taskId);
+  if (!entries.length) throw new Error('task allocation not authorized');
+  if (entries.length !== 1) throw new Error('ambiguous allocation authorization');
+  const [, , branch, relativePath, authorization] = entries[0];
+  const slug = taskId.toLowerCase();
+  if (branch !== `handoff/${slug}`) throw new Error('invalid task branch');
+  if (relativePath !== `.worktrees/${slug}`) throw new Error('invalid task path');
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$/.test(authorization)) throw new Error('invalid authorization reference');
+  const scope = new RegExp(`^TaskScope:[ \\t]*cycle-${cycle}/${taskId}[ \\t]*=[ \\t]*(?:plan|queue):[a-zA-Z0-9_-]+[ \\t]*$`, 'm');
+  if (!scope.test(cursor)) throw new Error('task outside frozen scope');
+  return { taskId, branch, relativePath, authorization, cycle };
+}
+
+async function absent(file) {
+  try { await fs.lstat(file); return false; } catch (e) { if (e.code === 'ENOENT') return true; throw e; }
+}
+
+export async function allocateTaskWorktree(projectRoot, taskId, { git = null } = {}) {
+  const root = await fs.realpath(projectRoot);
+  const runGit = git ?? (async (args) => {
+    const result = await exec('git', ['-C', root, ...args], { timeout: 30_000, maxBuffer: 1024 * 1024 });
+    return result.stdout.trim();
+  });
+  const outcome = await withAsyncLock(taskClaimsPath(root), { deadlineMs: 3000 }, async () => {
+    const cursor = await fs.readFile(path.join(root, 'docs/AI_HANDOFF/RUN.md'), 'utf8');
+    const policy = allocationPolicy(cursor, taskId);
+    const claim = await readTaskClaim(root, taskId);
+    if (claim.unreadable || claim.claimed) throw new Error('task claim present or unreadable; allocation refused');
+    const parent = path.join(root, '.worktrees');
+    if (!(await absent(parent))) {
+      const stat = await fs.lstat(parent);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('unsafe worktree parent');
+    }
+    const destination = path.join(root, policy.relativePath);
+    if (!(await absent(destination))) throw new Error('worktree path already exists');
+    const intentDir = path.join(root, '.ukit/storage/runs/worktree-allocations');
+    await fs.mkdir(intentDir, { recursive: true });
+    if (await fs.realpath(intentDir) !== intentDir) throw new Error('unsafe allocation intent path');
+    const intentPath = path.join(intentDir, `${policy.cycle}-${taskId}.json`);
+    if (!(await absent(intentPath))) throw new Error('allocation intent already exists; inspect history, never allocate again');
+    const base = await runGit(['rev-parse', '--verify', 'HEAD']);
+    if (!/^[a-f0-9]{40,64}$/.test(base)) throw new Error('invalid base commit');
+    let branchExists = false;
+    try { await runGit(['show-ref', '--verify', '--quiet', `refs/heads/${policy.branch}`]); branchExists = true; }
+    catch (e) { if (e.code !== 1) throw e; }
+    if (branchExists) throw new Error('task branch already exists');
+    const intent = { v: 1, ...policy, claim, base, status: 'intent', ts: Date.now() };
+    const handle = await fs.open(intentPath, 'wx');
+    try { await handle.writeFile(`${JSON.stringify(intent, null, 2)}\n`); await handle.sync(); }
+    finally { await handle.close(); }
+    // Keep the exclusive intent even on failure/timeout. An ambiguous git result
+    // is recovery debt, not permission to allocate another worktree.
+    await runGit(['worktree', 'add', '-b', policy.branch, destination, base]);
+    return { ...intent, path: destination, intentPath };
+  });
+  if (!outcome.ok) throw new Error('claims busy; no allocation');
+  return outcome.value;
+}

package/template_project/.codex/README.md

@@ -177,3 +177,28 @@ Skills are shared from `.claude/skills/` via symlink at `.codex/skills/`.
 - No unrelated changes
 - Verification executed and reported
 - Docs updated when source truth changed
+
+## Handoff Planning Gates
+
+When a handoff create/planner/fullstack session plans work under `docs/AI_HANDOFF/`, the
+gates are mechanical and read from disk, never from session memory:
+
+- Tasks are born `needs_breakdown`. A task flips to `ready` only after BOTH gates: the
+  task-budget validator's `VERDICT: ok` recorded on disk (the tool writes it —
+  `node .claude/ukit/index/task-budget-validator.mjs --record docs/AI_HANDOFF/tasks/TASK-001.md`)
+  AND the independent plan review's `PLAN_REVIEW: Approved` in PLAN.md.
+- Before any flip, `node .claude/ukit/index/ready-gate.mjs docs/AI_HANDOFF` must print
+  `READY_GATE: ok` — it re-checks both gates plus INDEX/task agreement from disk.
+- An owner document is persisted verbatim BEFORE planning reads it:
+  `node .claude/ukit/index/source-snapshot.mjs <original-path> docs/AI_HANDOFF/SOURCE.md`
+  (exclusive create, never overwrites; if it cannot run, state `source snapshot MISSING`).
+- Implementation lands through the receipt-backed helper, never a manual copy:
+  `node .claude/ukit/index/land-worktree.mjs --scope <scope.json> --receipt <receipt.json>`.
+- Overwriting PLAN/SPEC/LEDGER needs an `amendments/rev-<NN>/` copy first, verified with
+  `node .claude/ukit/index/amend-guard.mjs`.
+
+Every one of these is a bare single `node` command — no `cd`, no `$()` substitution, no
+compound — so the same instructions pass host permission checks on Claude Code, Codex and
+omp alike. On Codex this whole gate set is instruction-mediated only: there is no pre-tool
+hook surface, so nothing is hard-blocked — follow the verdicts recorded on disk instead of
+trusting session memory.

package/template_project/.omp/RULES.md

@@ -12,8 +12,7 @@ nothing else is loaded. Keep this short: every line here is a per-turn tax.
 - **Non-trivial / risky** (auth, migration, shared runtime, data-loss, flaky) — index-first, then
   activate the matching skill, then verify.
 
-Pick the lane before the first tool call. Skipping this is what turns a direct chat into a
-scattershot one.
+Pick the lane before the first tool call — skipping this is what turns a direct chat into a scattershot one.
 
 ## 2. Execution Contract
 
@@ -33,9 +32,9 @@ files before widening further. These node scripts work unchanged under omp.
 
 ## 5. Auto-activate skills
 
-Skills live in `.claude/skills/` and omp reads them through its `claude` discovery provider — no
-mirror under `.omp/`. On any non-trivial task, and again after the first tool calls reveal what the
-work really is, read the matching `SKILL.md` without being asked. Users never name skills.
+Skills live in `.claude/skills/`, read by omp through its `claude` discovery provider — no mirror under
+`.omp/`. On any non-trivial task — and again after the first tool calls reveal the real work — read the
+matching `SKILL.md` without being asked. Users never name skills.
 
 ## 6. Delegate to bind a model tier
 
@@ -43,36 +42,37 @@ Your own model does not change mid-turn. A tier only applies when work is handed
 `.omp/agents/`, whose `model:` field (`@smol` / `@default` / `@slow` / `@vision`) resolves through
 `modelRoles` in `.omp/config.yml`.
 
-- `tiny-fix` → `@smol` · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` →
-  `@default` · `review-release` → `@slow`
-- Images: `@vision` only. `@default`/`@slow` cannot see images on the UNIC gateway and must never
-  guess at their contents — hand every image to `ukit-vision-analyst` first.
+- `tiny-fix` → `@smol` · `local-fix`/`local-build`/`shared-edit`/`find-cause`/`map-impact` → `@default` · `review-release` → `@slow`
+- Images: `@vision` only — `@default`/`@slow` cannot see images on the UNIC gateway; hand every image to `ukit-vision-analyst` first.
 
 Doing everything inline is what makes UKit look like it only has one model. Keep direct execution
 for trivial/simple work; delegate when the tier differs or a noisy lane would flood this context.
 
 ## 7. Safe Patch
 
-Prefer unique current-file anchors over line numbers or stale pasted blocks. Never silently merge a
-stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
-endings.
+Prefer unique current-file anchors over line numbers or stale pasted blocks; never silently merge a
+stale spec — re-read current source and confirm before applying. Preserve existing BOM and line endings.
 
 ## 8. Handoff runs never park mid-cycle
 
 While `docs/AI_HANDOFF/RUN.md` `Phase:` is not `done`/`blocked`, a handoff-fullstack run is
 still in flight: a recap or checkpoint is progress output, never a stopping point. Continue
 the cursor's `Next:` step; only `HANDOFF FULLSTACK COMPLETE` or `HANDOFF FULLSTACK BLOCKED`
-ends the run. `handoff-clear` must close the cursor (`Phase: done` or delete) or the gate
-keeps the next session running too.
+ends the run; `handoff-clear` must close the cursor or the gate keeps the next session running.
+Before any stop, reconcile task/AC/findings/jobs/independent work/integration/release/consumer/
+pause/blocker; the Stop gate is the backstop; a turn wait is not run done; a blocker releases only
+with no READY independent work. Planning gates are mechanical, disk-read: `needs_breakdown`
+tasks flip `ready` only on a recorded validator `VERDICT: ok` + `PLAN_REVIEW: Approved`, with
+`node .claude/ukit/index/ready-gate.mjs docs/AI_HANDOFF` printing `READY_GATE: ok` before the
+flip; owner docs persist via `source-snapshot.mjs`, work lands via `land-worktree.mjs` — all bare
+single `node` commands.
 
 ## 9. Never end a turn silently
 
 Ending a turn with no output is a defect, not a pause. If you stop before the work is finished, the
-last thing you emit is one short line naming what is unfinished and what you need. Silence is never
-a status — the user cannot distinguish it from a crash.
-
-> Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
-> On a non-UNIC provider, edit only the cost tiers `smol`/`default`/`slow` — never `vision`
-> (`unic-vision`) or `decision` (`unic-decision`, the LOCAL JEV/Lava typed-decision model —
-> `docs/pstack/UNIC_DECISION_GUIDE.md`); both are capability lanes. Aliases `lite`/`code`/`smart`
-> map smol↔lite, default↔code, slow↔smart — edit each alongside its tier.
+last line you emit names what is unfinished and what you need. Silence is never a status.
+
+> Maintainer note, not a per-turn rule: `modelRoles` ships UNIC gateway names; on a non-UNIC
+> provider edit only cost tiers `smol`/`default`/`slow` — never `vision` (`unic-vision`) or
+> `decision` (`unic-decision`, LOCAL JEV/Lava typed-decision — `docs/pstack/UNIC_DECISION_GUIDE.md`);
+> both capability lanes. Aliases lite/code/smart = smol/default/slow — edit alongside its tier.

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

@@ -101,7 +101,13 @@ decision owned by the local decision model when staged. Read
 Model isolation is preserved: the verdict pass runs on the local unic-decision
 model, so reviewer ≠ executor still stands.
 
-### Output (append to task file as `## Reviewer Verdict`)
+### Output (return `## Reviewer Verdict` to the orchestrator)
+
+You are read-only: return the complete verdict block below, never shell-append it (`cat >>`,
+heredoc, `tee`, `sed -i`). The orchestrator appends your complete verdict block with `Edit`
+to the task file, preserving prior rounds, then updates INDEX serially. Do not edit INDEX.
+Use Read/Grep/Glob for inspection; Bash verification is one simple command per call with
+absolute paths (no `cd … &&`/`;` prefix, loops or compound writes).
 
 ```
 ## Reviewer Verdict
@@ -127,9 +133,11 @@ NEXT_STATUS_FOR_INDEX: approved | approved_minor | changes_requested | critical_
 NOTES: [1-2 sentences for human reviewer if needed]
 ```
 
-After writing the verdict, update `docs/AI_HANDOFF/INDEX.md` row for this task: set Status = NEXT_STATUS_FOR_INDEX, set Reviewer = your model name.
+The orchestrator persists this block before aggregation or status changes; it sets the INDEX
+status from NEXT_STATUS_FOR_INDEX and Reviewer from your model name. No independent verdict
+is on disk until that append succeeds.
 
-**Then return to the orchestrator at most 6 lines** — the full verdict is already on disk:
+**Include this short routing header before your complete verdict block**:
 
 ```
 TASK: TASK-xxx
@@ -139,10 +147,9 @@ VERIFICATION_RERUN: PASS | FAIL | NOT_RUN | N/A (+ one-line reason for NOT_RUN/N
 BLOCKING: <one line per critical/important finding, or "none">
 ```
 
-Do not paste the diff, the findings prose, or verification output into the returned message.
-The orchestrator is driving a whole pipeline in one context window and re-reads what it needs
-from the task file; pasted reviewer logs are a common reason a run exhausts its context and
-dies before the cycle finishes.
+Return the bounded verdict block (≤30 lines) with actionable findings, not the diff or raw
+verification logs. The complete block is necessary for persistence by the read-only caller contract.
+For panel lead bucketing, likewise return the Panel Consensus block for serial persistence.
 
 **You may be running unattended.** Findings do not end the run — the caller feeds them to an
 auto-fix round and re-review. So write findings that a fresh executor can act on with no human
@@ -212,7 +219,7 @@ additions:
 ### Inputs you expect
 
 - 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`.
+- 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. Return the verdict for the planner to 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
@@ -237,9 +244,15 @@ additions:
 
 Only flag issues that would cause real problems during implementation planning. Approve unless there are serious gaps that would lead to a flawed plan.
 
+### Inspection commands (plan/spec review)
+
+Read documents with `Read`/`Grep`/`Glob`. When Bash is needed, issue one simple read-only command per call
+using absolute paths: no `cd … ;`/`cd … &&` prefixes, `for` loops, `;` or `&&` sequences, or `{a,b}` globs.
+The host permission layer asks approval for such compound commands and an unattended review cannot answer it.
+
 ### Output
 
-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:
+Produce this block as the final part of your reply, verbatim. You have no `Write`/`Edit` tool and must not append it with a shell command (`cat >>`, heredoc, `tee`, `sed -i`): the planning-only guard refuses shell writes. The calling planner appends it (append, do NOT overwrite) to the end of the reviewed document under a `## Plan Review Log` section — creating the section if it doesn't exist yet, keeping 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.
 

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

@@ -30,6 +30,17 @@ what you must avoid, not the work itself. Write the remaining modules into `PLAN
 explicitly out-of-scope-for-this-cycle, and add one `queued` row per module to `INDEX.md` so
 the next cycle picks them up. Order modules so the one others depend on is planned first.
 
+**Plan count is a deliverable.** When the owner source states a number of plans or separate
+plans ("at least two plans", "plan A and plan B"), deliver exactly that many real plan units
+in the Handoff-supported layout: the first plan canonical (SPEC.md + PLAN.md + tasks/ under
+OUTPUT_ROOT), each further plan as its own `docs/AI_HANDOFF/queued/<slug>/` blueprint with
+its own SPEC.md, PLAN.md, INDEX.md (rows `queued_blueprint`), HANDOFF.md and tasks/ — the
+queued-README layout. Group labels ("group A/B") inside one PLAN.md never satisfy a stated
+count. Verify the count mechanically before reporting: `node .claude/ukit/index/plan-count.mjs docs/AI_HANDOFF <N>` (the planning root, the stated count) must print
+`PLAN_COUNT: ok (<found>/<N>)`.
+count. If the layout genuinely cannot carry the count, record an explicit owner-decision
+item (a NOTES.md `question` entry naming the decision) instead of silently collapsing it.
+
 The caller may be running unattended (`/ukit:handoff-fullstack`). Stopping to ask means the
 run dies and the human returns hours later to a question, which is the failure mode this
 whole pipeline exists to prevent.
@@ -42,7 +53,7 @@ resolved. Executors then burn a whole round discovering it.
 
 Before writing any path or command into `PLAN.md` or a task file, verify it:
 
-- **Target Files** — for each path, confirm it exists (`ls`/Glob), or that its parent
+- **Target Files** — for each path, confirm it exists (Glob), or that its parent
   directory exists and the file is genuinely new. Mark new files `(new)` explicitly.
 - **Verification Commands** — read `package.json` `scripts` (or the stack's equivalent) and
   use the script names that are actually defined. Do not write `npm test` when the repo uses
@@ -69,11 +80,29 @@ The plan owns ALL unfinished work, not only the new request. Scan and fold in:
 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.
 
+**Resume gates — `needs_breakdown` rows with no `PLAN_REVIEW: Approved` in PLAN.md:** a
+previous planning run died before the gates. Do NOT re-intake or rewrite SPEC/PLAN/tasks on
+this path; run only the missing gates — the per-task validator (`--record`, below) for
+tasks lacking a recorded `Validator:` line — and report back for the review + flip. Never
+overwrite the existing plan on this path.
+
 **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.
 
+**Source snapshot — when the request comes from an owner document.** Before chunking any
+advisor / roadmap source, persist it verbatim with ONE simple command, literal paths:
+
+```
+node .claude/ukit/index/source-snapshot.mjs <original-path> docs/AI_HANDOFF/SOURCE.md
+```
+
+(under the queued root, pass that root's SOURCE.md path literally). It records the origin
+path, the sha256 of the original bytes and a byte-identical copy, and refuses to overwrite
+an existing snapshot. If it cannot run (denial, budget), PLAN.md and LEDGER.md must state
+`source snapshot MISSING` explicitly — never cite only a mutable path as the "source".
+
 ## Phase 0.5 — Write SPEC.md
 
 Write `docs/AI_HANDOFF/SPEC.md` from the template at `template_project/docs/AI_HANDOFF/SPEC.md`
@@ -86,13 +115,16 @@ defect — fix it before writing tasks.
 
 ## Phase 1 — Write PLAN.md
 
-Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
+Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
 
 ```
 §1 Intent       — what problem, what success looks like
 §2 Scope        — in-scope / out-of-scope
                   CONSTRAINT: tasks in the same wave must not modify the same file.
                   If two tasks need the same file → make one depend on the other.
+                  Global constraints — version floors, dependency limits, naming/copy
+                  rules, platform requirements as one-line constraints; every TASK-xxx.md
+                  inherits §2 by reference — do not repeat them inside each task.
 §3 Approach     — technical solution, trade-offs, alternatives rejected
 §4 Test Plan    — happy path × N + ≥2 edge cases of DIFFERENT kinds (e.g. null/empty AND
                   boundary/concurrent — two near-duplicate cases do not satisfy this) +
@@ -104,9 +136,6 @@ Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
                   command. If the project genuinely has none, state that explicitly —
                   do not omit silently.
 §6 Acceptance   — checklist of done criteria (prefer verifiable/command-based criteria)
-§7 Global Constraints — one line each: version floors, dependency limits, naming/copy
-                  rules, platform requirements. Every TASK-xxx.md inherits this section
-                  by reference — do not repeat these constraints inside each task.
 ```
 
 **§4 is non-negotiable.** No test plan = plan not ready.
@@ -123,6 +152,21 @@ file that already ends with the footer above; refine it with `Edit` afterwards.
 validates `PLANNER_MODEL` on that write, so a refusal surfaces before you spend a long drafting
 pass — never draft the whole plan in your head/scratch and attempt the first write last.
 
+## Create files with Write/Edit only — never shell writes
+
+`handoff-create` is planning-only and the model-tier guard refuses shell writes (`mkdir` + heredoc,
+`cat > file`, `tee`, `echo >`, `sed -i`, compound `&&` chains that write). Create every plan, task, SPEC,
+LEDGER, NOTES, INDEX and ACTIVE file with the `Write` tool (it creates missing parent directories) and
+change existing files with `Edit`. Use Bash only for read-only inspection and the literal-path helper
+commands this document names. This is the guard's own documented path, not a workaround, so choosing it
+up front is required; only a refusal of a `Write`/`Edit` call triggers the report-and-stop rule below.
+
+The same applies to the reviewer's round block and to `docs/WORKLOG.md`: the `code-reviewer` returns its
+`### Round <N>` block in its reply (it has no write tool), and you add it to `PLAN.md`'s `## Plan Review Log`
+with `Edit`; append the WORKLOG entry with `Edit` too. For inspection use one simple read-only command per
+call (or `Read`/`Grep`/`Glob`) — no `cd … &&` chains, `for` loops, `;` sequences or `{a,b}` globs, which the
+host permission layer asks approval for and an unattended run cannot answer.
+
 ## Blocked write = report, never retry or respawn
 
 If a `Write`/`Edit`/`Bash` call is refused (`BLOCKED …`, `hook error`, "denied by your
@@ -155,7 +199,9 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 | Verification Commands | Runnable shell commands — MUST include the project's lint/typecheck command if one exists (see §5 rule above). Apply the "Test selection" resolution order from docs/AI_HANDOFF/RULES.md: `src/`/`scripts/` targets → the `tests` array in `.cache/index/tests-map.json`; `template_project/.claude/**`/`.claude/**` targets → path convention (hooks → `tests/hooks/` + `tests/handoff/cycle*/`; manifest/settings → `tests/manifest/`; runtime `.mjs` mirrors → `tests/core/*Parity*` + `tests/index/`); if both resolve to fewer than one test file the task MUST fall back to `yarn test:release-core` — never the full suite by default, never an empty selection |
 | Acceptance Criteria | Verifiable checklist |
 
-Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
+Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`. Every task is
+created `needs_breakdown` anyway — the two gates in "Task-budget validator" below (validator
+verdict + review Approved) are what promote it to `ready`.
 
 **Wave logic (for your reference when splitting):**
 - Wave 1 = tasks with `Dependencies: none`
@@ -165,13 +211,37 @@ Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
 
 ### Task-budget validator — gate before any task becomes `ready`
 
-Before marking a task `ready`, run the task-budget validator on the file you just wrote:
+Write every task file `Status: needs_breakdown` first — `ready` is a verdict, not a
+default. A task becomes `ready` only when BOTH gates pass:
+
+1. the task-budget validator printed `VERDICT: ok` for that file (or a one-line dismissal
+   is recorded in its `## Discussion` thread), and
+2. the independent plan review (Step 2.5 of `/ukit:handoff-create`, P2.5 of fullstack)
+   ended `Approved`.
+
+Run the validator per task file, right after writing it, as ONE simple command from the
+project root — one command per file, each with its literal path:
 
 ```
-node .claude/ukit/index/task-budget-validator.mjs docs/AI_HANDOFF/tasks/TASK-xxx.md
+node .claude/ukit/index/task-budget-validator.mjs docs/AI_HANDOFF/tasks/TASK-001.md
+node .claude/ukit/index/task-budget-validator.mjs docs/AI_HANDOFF/tasks/TASK-002.md
 ```
 
-The validator's first stdout line is `VERDICT: ok` or `VERDICT: needs_breakdown`, followed by `REASON:` lines. It always exits 0 (advisory). When the verdict is `needs_breakdown`, either split the task into smaller TASK files until each one passes, or record a one-line dismissal in that task's `## Discussion` thread explaining why the violation is acceptable. A `ready` task whose validator verdict is `needs_breakdown` is not actually ready — Phase 3 (state file write) must follow a `VERDICT: ok` (or a documented dismissal).
+No `cd` prefix, no `for`/`while` loop, no shell variable, no glob, no pipe, and no `&&`/`;` compound —
+host permission checks reject those SHAPES ("cat reads a file by a relative path after a
+cd in a compound command", "A variable in this command can't be checked before it runs"),
+so a loop-shaped batch burns the round and the gate never runs. Eight tasks = eight
+separate calls. Read files with the Read/Glob/Grep tools, never `cat`/`head`/`sed`
+compounds.
+
+The validator's first stdout line is `VERDICT: ok` or `VERDICT: needs_breakdown`, followed by `REASON:` lines. It always exits 0 (advisory). When the verdict is `needs_breakdown`, either split the task into smaller TASK files until each one passes, or record a one-line dismissal in that task's `## Discussion` thread explaining why the violation is acceptable.
+
+Persist every verdict the moment it exists: right after each `VERDICT: ok` — and right after recording a one-line dismissal — append the verdict to that task file's `## Discussion` thread as one line, `Validator: ok <YYYY-MM-DD>` or `Validator: dismissed <YYYY-MM-DD> — <reason>`. Record the ok verdict from the tool itself with ONE simple command per task — `node .claude/ukit/index/task-budget-validator.mjs --record docs/AI_HANDOFF/tasks/TASK-001.md` — which re-validates and appends `Validator: ok <YYYY-MM-DD> <tool-version>` to the thread (atomic temp-file + rename, existing BOM and line endings preserved, idempotent, and it refuses a non-ok verdict — a `needs_breakdown` file is never recorded); the dismissal line stays hand-written. Verdicts live on disk, not in session memory: compaction must not erase a gate, and the later flip-to-ready step reads the task files from disk, never your session memory.
+
+If the run is interrupted (budget exhausted, command denied, crash) before both gates
+pass, the tasks STAY `needs_breakdown` — INDEX.md and ACTIVE.md must name which gate is
+missing. A batch that never saw a `VERDICT: ok` is never `ready`, no matter how complete
+the files look.
 
 Numeric thresholds and the minute table live in `src/core/taskBudgetValidator.js` and the shipped CLI twin. Do not restate them here — `tests/consistency/configDocsSync.test.js` greps this file for stale numbers and will fail if a threshold is hard-coded. Reference the validator / PLAN §3 instead.
 
@@ -191,6 +261,11 @@ dependency means B imports a symbol A creates, or B tests behavior A implements.
 - "Both touch the same area of the codebase" — irrelevant unless they touch the same *file*.
 - "A should be reviewed before B starts" — that is what the review phase is for.
 
+One counter-case cuts the other way: when the OWNER SOURCE states a delivery-order
+qualifier — "after import works", "once search lands" — that is a real dependency, not an
+ordering preference. Encode it in `Dependencies` and name the source line in the task's
+Spec references. Dropping it silently ships B before its precondition exists.
+
 Same-file collisions are the one real constraint, and they are cheap to design around: split
 along file boundaries so each task owns its files outright. If two pieces of work truly must
 edit one file, prefer merging them into a single task over chaining two — one task with two
@@ -201,7 +276,16 @@ most chains are ordering preferences that a wide wave 1 would satisfy just as we
 
 ## Phase 3 — Update state files
 
-**INDEX.md** row per task: `| TASK-001 | <name> | ready | none | - |`
+**INDEX.md** row per task — write `needs_breakdown` at creation, flip to `ready` only after
+both gates pass (validator `VERDICT: ok` per task + plan review `Approved`):
+`| TASK-001 | <name> | needs_breakdown | none | - |`
+Flip by re-reading the task files from disk: only a task whose `## Discussion` records
+`Validator: ok <date>` (or `Validator: dismissed <date> — <reason>`) flips to `ready`; a
+task without the recorded `Validator:` line stays `needs_breakdown` — a verdict held only
+in the session does not count. Run the mechanical gate once before flipping any row —
+`node .claude/ukit/index/ready-gate.mjs docs/AI_HANDOFF` (the planning root when queued) —
+and flip only on `READY_GATE: ok`; a `tasks not ready:` or `index/task mismatch` line
+names the gap to fix first. Never flip while the gate fails.
 
 **ACTIVE.md** — store base branch + cycle info:
 ```
@@ -211,6 +295,10 @@ Spec: docs/AI_HANDOFF/SPEC.md
 Tasks: <N> total
 Status: planning_done — ready for executor
 ```
+When any task is still non-ready (a gate missing), write the honest state instead:
+`Status: planning_incomplete — tasks not ready: <validator | plan review>` (a
+human-readable ACTIVE.md marker only — machine readers parse INDEX.md rows and
+task-file `- Status:` lines, never write `planning_incomplete` into those).
 Wave structure is NOT stored here — inferred from task `Dependencies` fields at runtime.
 
 **RUN.md** — write the run's `ExitPredicate:` line before iteration 1 (the orchestrator
@@ -256,11 +344,13 @@ catches it:
 10. Does each test case state a concrete `Expected` value, not "works correctly" or "returns successfully"? A test whose expectation cannot fail is not a test.
 11. Bugfix task → is there a regression test that fails against today's code?
 12. Could every listed test pass against an empty implementation? If so, the test cases describe nothing and must be rewritten.
+13. Does every test case expect ONE deterministic outcome? "X or nothing" ("returns the rows or an empty list") is two expectations in one — pin the expected value or split the test; a disjunctive expectation cannot fail for the right reason.
+14. Is every Verification Command an executable proof that runs the tests? Grepping a doc for a literal line (e.g. `Coverage: 20/20`) proves only that the line exists — disposition bookkeeping is not implementation evidence and never substitutes for a test run.
 
 Append the result to `PLAN.md`:
 ```
 ## Planner Self-Audit
-Checklist: 14/14 pass
+Checklist: 16/16 pass
 Fixed during audit: <what you changed, or "nothing">
 Known gaps: <what you deliberately left out and why, or "none">
 ```
@@ -286,7 +376,7 @@ 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.
+- 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 run `node .claude/ukit/index/amend-guard.mjs docs/AI_HANDOFF PLAN.md SPEC.md` (naming every file you will rewrite) and proceed only on `AMEND_GUARD: ok` — the checker is mechanical (the rev copy exists on disk); its invocation is prose. Then compose the revised PLAN.md in full: carry the existing `## Amendment History` forward and append this amendment's entry (prior review rounds and verdicts; prior requirement, decision and task versions with what changed and why; each change's `invalidated` evidence: tasks, executor reports, verdicts that no longer hold). Write the revised PLAN.md only after that entry is in the composed text. 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.

package/template_project/.omp/hooks/pre/ukit-bridge.js

@@ -74,7 +74,7 @@ export const HOOK_EVENT_MAP = {
     // Delegation result: releases the per-task execution claim taken by the pre-call guard.
     'MultiEdit|NotebookEdit|Agent|Task': ['record-execution.mjs'],
   },
-  before_agent_start: ['sensitive-data-guard.mjs', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
+  before_agent_start: ['sensitive-data-guard.mjs', 'record-execution.mjs', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
   'session.compacting': ['reinject-context.sh'],
   // TASK-003 (FR-003): the in-proc emit step runs LAST — project-important.sh
   // owns the mandate-first lead (TASK-042 contract); the emit is advisory,