@ngockhoale/ukit 3.4.67 → 3.4.69

package/src/core/runInstallPipeline.js

@@ -442,13 +442,26 @@ export async function runInstallPipeline({
   const trackedSettings = (Array.isArray(installMetaData?.files) ? installMetaData.files : [])
     .some((e) => (typeof e === 'string' ? e : e?.p) === '.claude/settings.json');
   const settingsMigration = { pending: trackedSettings && !installMetaData?.settingsDefaultsMigration };
-  const diffResults = await diffInstallPlan(plan, { ompOwnership, settingsMigration });
+  const recordedManagedHashes = new Map(
+    (Array.isArray(installMetaData?.files) ? installMetaData.files : [])
+      .filter((e) => e && typeof e === 'object' && typeof e.h === 'string')
+      .map((e) => [path.join(pathConfig.projectRoot, e.p), e.h]),
+  );
+  // CR-13 provenance: sha256 of each `.ukit-new` sidecar UKit itself wrote.
+  // Absent record = the file is not UKit's; never overwrite or remove it.
+  const recordedSidecarHashes = new Map(
+    Object.entries(installMetaData?.sidecars ?? {})
+      .filter(([p, h]) => typeof p === 'string' && typeof h === 'string')
+      .map(([p, h]) => [path.join(pathConfig.projectRoot, p), h]),
+  );
+  const diffResults = await diffInstallPlan(plan, { ompOwnership, settingsMigration, recordedManagedHashes });
   const plannedSummary = summarizeDiff(diffResults);
 
   if (!dryRun) {
-    const { writes, skippedUpdates, skippedByAction } = await applyDiffResults(diffResults, {
+    const { writes, skippedUpdates, skippedByAction, sidecarHashes } = await applyDiffResults(diffResults, {
       backupRoot: pathConfig.backupRoot,
       projectRoot: pathConfig.projectRoot,
+      recordedSidecarHashes,
     });
 
     for (const entry of diffResults) {
@@ -550,8 +563,23 @@ export async function runInstallPipeline({
     // adjusted counts never go negative.
     const summary = adjustSummaryForSkips(plannedSummary, skippedByAction, skippedUpdates);
 
+    const managedHashes = Object.fromEntries(
+      diffResults
+        .filter((e) => e.managedHash && ['create', 'update', 'unchanged'].includes(e.action))
+        .map((e) => [path.relative(pathConfig.projectRoot, e.targetPath).split(path.sep).join('/'), e.managedHash]),
+    );
+    // Sidecar provenance map (relative path → sha256 UKit wrote this run). Written
+    // only after apply succeeded, so a failed create never claims ownership.
+    const sidecarRecords = Object.fromEntries(
+      Object.entries(sidecarHashes).map(([absPath, h]) => [
+        path.relative(pathConfig.projectRoot, absPath).split(path.sep).join('/'),
+        h,
+      ]),
+    );
     await writeInstallMetadata({
       installMetaPath: pathConfig.installMetaPath,
+      managedHashes,
+      sidecarHashes: sidecarRecords,
       packageVersion,
       manifest,
       stackContext,

package/src/core/uninstall.js

@@ -1,5 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { loadManifest } from '../manifest/loadManifest.js';
 import {
   cleanupEmptyParents,
   copyFileRawExclusive,
@@ -243,6 +246,76 @@ async function hasSymlinkedParent(projectRoot, absolutePath) {
   return false;
 }
 
+// CR-13: managed AI_HANDOFF templates are tracked with an optional sha256 (`h`). An
+// owner-edited copy (hash differs, or no hash and bytes differ from the shipped template)
+// must survive uninstall. The managed set is DERIVED from the manifest's
+// managedChildStrategies, never hardcoded, so a new managed child is covered automatically.
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+async function managedTemplateMap() {
+  const manifest = await loadManifest(path.join(PACKAGE_ROOT, 'manifests', 'platform.full.yaml'));
+  const map = new Map(); // project-relative target path -> shipped template absolute path
+  for (const item of manifest.items ?? manifest.files ?? []) {
+    for (const [childKey, strategy] of Object.entries(item.managedChildStrategies ?? {})) {
+      if (strategy !== 'managed_template') continue;
+      map.set(
+        path.posix.join(item.targetPath, childKey),
+        path.join(PACKAGE_ROOT, 'template_project', item.sourceTemplate, childKey),
+      );
+    }
+  }
+  return map;
+}
+
+const sha256Hex = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+// lstat-first sidecar inspection shared by the tracked-entry loop and dry-run listing:
+// a symlink/non-regular file is never read through or claimed as UKit's.
+async function readSidecarState(sidecarPath) {
+  let stat;
+  try {
+    stat = await fs.lstat(sidecarPath);
+  } catch (error) {
+    return error?.code === 'ENOENT' ? { state: 'absent' } : { state: 'unreadable' };
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    return { state: 'non-regular' };
+  }
+  try {
+    const bytes = await fs.readFile(sidecarPath);
+    return { state: 'file', hash: sha256Hex(bytes) };
+  } catch {
+    return { state: 'unreadable' };
+  }
+}
+
+// true = owner-edited (keep it). Missing/non-regular entries are not "owner content"
+// and fall through to the normal removal path (which refuses real directories).
+async function isOwnerEditedManagedFile(absolutePath, relativePath, managedMap, recordedHash) {
+  const isManaged = managedMap.has(relativePath);
+  if (!isManaged && typeof recordedHash !== 'string') {
+    return false;
+  }
+  let stat;
+  try {
+    stat = await fs.lstat(absolutePath);
+  } catch {
+    return false;
+  }
+  if (!stat.isFile()) {
+    return false;
+  }
+  const current = await fs.readFile(absolutePath);
+  if (typeof recordedHash === 'string') {
+    return sha256Hex(current) !== recordedHash;
+  }
+  // Legacy managed entry with no recorded hash: compare against the shipped template bytes.
+  // If the template cannot be read, keep the file rather than risk deleting owner content.
+  const templateAbs = managedMap.get(relativePath);
+  const shipped = await fs.readFile(templateAbs).catch(() => null);
+  return shipped === null || !current.equals(shipped);
+}
+
 // Hardcoded fallback for installs that predate file tracking (no 'files' field
 // in install.json). New installs always have a 'files' list, so this fallback
 // only applies when upgrading from a very old UKit version.
@@ -349,6 +422,8 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
   // actually created. Fall back to the hardcoded list for old installs.
   let regularPaths;
   let linkPaths;
+  const preservedOwnerEdited = [];
+  const preservedSidecars = [];
 
   const stateDir = path.join(projectRoot, '.claude', 'ukit', '.ukit');
 
@@ -383,8 +458,10 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
         continue;
       }
 
-      trackedEntries.push({ absolutePath, normalizedRelative, type });
+      const recordedHash = typeof entry === 'object' && typeof entry?.h === 'string' ? entry.h : null;
+      trackedEntries.push({ absolutePath, normalizedRelative, type, recordedHash });
     }
+    const managedMap = await managedTemplateMap();
 
     const trackedLinkRelativePaths = [
       ...new Set(trackedEntries.filter((entry) => entry.type === 'link').map((entry) => entry.normalizedRelative)),
@@ -405,7 +482,30 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
         continue;
       }
 
-      regularPaths.push({ abs: entry.absolutePath, recursive: false });
+      // CR-13: an owner-edited managed template is kept byte-identical and reported.
+      const ownerEdited = await isOwnerEditedManagedFile(
+        entry.absolutePath,
+        entry.normalizedRelative,
+        managedMap,
+        entry.recordedHash,
+      );
+      if (ownerEdited) {
+        preservedOwnerEdited.push(entry.absolutePath);
+      } else {
+        regularPaths.push({ abs: entry.absolutePath, recursive: false });
+      }
+      // CR-13: a `.ukit-new` sidecar is removed ONLY when install.json recorded the
+      // sha256 of exactly these bytes. The filename is not provenance: an owner-authored
+      // or owner-modified `.ukit-new` is preserved (and reported), never deleted.
+      const sidecarAbs = `${entry.absolutePath}.ukit-new`;
+      const sidecarRel = `${entry.normalizedRelative}.ukit-new`;
+      const recordedSidecarHash = installData.sidecars?.[sidecarRel];
+      const sidecarState = await readSidecarState(sidecarAbs);
+      if (sidecarState.state === 'file' && typeof recordedSidecarHash === 'string' && recordedSidecarHash === sidecarState.hash) {
+        regularPaths.push({ abs: sidecarAbs, recursive: false });
+      } else if (sidecarState.state !== 'absent') {
+        preservedSidecars.push(sidecarAbs);
+      }
     }
 
     if (invalidPaths.length > 0) {
@@ -492,6 +592,8 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
       preservedPaths: importantPlan.preservedPaths,
       backupWarnings: importantPlan.backupWarnings,
       skippedSymlinkParents,
+      preservedOwnerEdited,
+      preservedSidecars,
     };
   }
 
@@ -569,5 +671,7 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     preservedPaths: importantPlan.preservedPaths,
     backupWarnings: importantPlan.backupWarnings,
     skippedSymlinkParents,
+    preservedOwnerEdited,
+    preservedSidecars,
   };
 }

package/src/manifest/validateManifest.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 
 const VALID_ITEM_TYPES = new Set(['command', 'skill', 'agent', 'hook', 'config', 'link']);
-const VALID_MERGE_STRATEGIES = new Set(['overwrite_with_backup', 'skip', 'append', 'prepend', 'merge_env_overwrite_with_backup']);
+const VALID_MERGE_STRATEGIES = new Set(['overwrite_with_backup', 'skip', 'append', 'prepend', 'merge_env_overwrite_with_backup', 'managed_template']);
 const VALID_ITEM_LEVELS = new Set(['project', 'user']);
 
 function isPlainObject(value) {
@@ -96,6 +96,30 @@ export function validateManifest(manifest) {
       );
     }
 
+    if (item.managedChildStrategies !== undefined) {
+      // CR-13: per-child strategies for a directory sourceTemplate. Keys are paths
+      // RELATIVE to targetPath (never absolute, never escaping it) and every value
+      // must be a real strategy — a typo like `managed_templet` must fail loudly
+      // instead of silently behaving like the default (owner-preserving) strategy.
+      if (!isPlainObject(item.managedChildStrategies)) {
+        errors.push(`${prefix}.managedChildStrategies must be an object of relative child path → strategy.`);
+      } else {
+        for (const [childKey, strategy] of Object.entries(item.managedChildStrategies)) {
+          const childPrefix = `${prefix}.managedChildStrategies["${childKey}"]`;
+          if (childKey.trim() === '' || path.isAbsolute(childKey) || /^[A-Za-z]:[\\/]/.test(childKey)) {
+            errors.push(`${childPrefix} key must be a non-empty relative path.`);
+          } else if (containsPathTraversal(childKey)) {
+            errors.push(`${childPrefix} key must not contain path traversal segments.`);
+          }
+          if (!VALID_MERGE_STRATEGIES.has(strategy)) {
+            errors.push(
+              `${childPrefix} has invalid strategy '${String(strategy)}' — must be one of: ${Array.from(VALID_MERGE_STRATEGIES).join(', ')}`,
+            );
+          }
+        }
+      }
+    }
+
     if (item.level !== undefined && !VALID_ITEM_LEVELS.has(item.level)) {
       errors.push(`${prefix}.level must be one of: ${Array.from(VALID_ITEM_LEVELS).join(', ')}`);
     }

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

@@ -102,7 +102,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
@@ -128,9 +134,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
@@ -140,10 +148,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
@@ -211,7 +218,7 @@ verdict block — with these 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
@@ -236,9 +243,15 @@ verdict block — with these 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/.claude/agents/handoff-planner.md

@@ -31,6 +31,16 @@ 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>)`. 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.
@@ -43,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
@@ -70,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`
@@ -121,6 +149,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
@@ -153,7 +196,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`
@@ -163,13 +208,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.
 
@@ -189,6 +258,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
@@ -199,7 +273,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:
 ```
@@ -209,6 +292,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
@@ -254,11 +341,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">
 ```
@@ -284,7 +373,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.