@ngockhoale/ukit 3.0.0 → 3.0.2

package/{templates → template_project}/.claude/ukit/runtime/stop-coordinator.mjs

@@ -16,10 +16,14 @@
  *     `docs/AI_HANDOFF/RUN.md` carries `Phase:` other than `done`/`blocked`, a
  *     handoff-fullstack run is still in flight and the stop is bounced back with
  *     the cursor's `Next:` step — this is what keeps an overnight run moving
- *     after a recap instead of stalling idle. A stalled-cursor breaker releases
- *     the stop if the cursor has not advanced across `stopGateMaxStalledBlocks`
- *     consecutive blocked stops (same liveness shape as the ledger's
- *     noProgressCount breaker);
+ *     after a recap instead of stalling idle. When RUN.md carries an
+ *     `ExitPredicate:` line (mechanic #7), `Phase: done` is accepted only if the
+ *     predicate evaluates true — `all(index:all-done, git:clean,
+ *     file-exists:<relpath>)` terms checked mechanically, no eval, no shell-out.
+ *     A stalled-cursor breaker releases the stop if the cursor has not advanced
+ *     across `stopGateMaxStalledBlocks` consecutive blocked stops (same liveness
+ *     shape as the ledger's noProgressCount breaker), and its advisory reports
+ *     the predicate state so a plateau is visible;
  *   - it merges the three evaluator results with a deterministic owner order —
  *     fail-closed completion failure > completion block > handoff-cursor block >
  *     watchdog block > merged advisory > silent release — and emits AT MOST ONE
@@ -71,7 +75,7 @@
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 
 import { withAsyncLock } from './async-lock.mjs';
 
@@ -447,9 +451,141 @@ function parseRunCursor(text) {
     phase: field('Phase'),
     cursor: field('Cursor'),
     next: field('Next'),
+    exitPredicate: field('ExitPredicate'),
   };
 }
 
+// ─── Exit predicate (mechanic #7 — exit-predicate-first loop) ─────────────
+//
+// The planner writes one `ExitPredicate:` line into RUN.md at P2 and the gate
+// evaluates it mechanically when the cursor claims `Phase: done`. The grammar
+// is deliberately tiny — `all(<term>[,<term>...])` or a single term, where a
+// term is `index:all-done`, `git:clean`, or `file-exists:<relpath>` — so the
+// whole check stays inside the hook deadline: ≤3 file reads + one
+// `git status --porcelain`, no eval, no shell-out of predicate text.
+
+/**
+ * Parse the ExitPredicate expression into a term list. Returns null when the
+ * expression is malformed — a malformed predicate is unsatisfiable, so a run
+ * that wrote garbage cannot claim `done` through it.
+ */
+export function parseExitPredicate(expr) {
+  const trimmed = String(expr || '').trim();
+  if (!trimmed) return null;
+  const inner = trimmed.match(/^all\((.*)\)$/s)?.[1] ?? trimmed;
+  const terms = inner
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+  if (terms.length === 0) return null;
+  const TERM_RE = /^(index:all-done|git:clean|file-exists:[^\s,]+)$/;
+  return terms.every((t) => TERM_RE.test(t)) ? terms : null;
+}
+
+/**
+ * `index:all-done` — every TASK-xxx row in docs/AI_HANDOFF/INDEX.md is in a
+ * terminal-success status (`done` or `cancelled_superseded`). An unreadable or
+ * taskless INDEX cannot prove all-done, so the term fails.
+ */
+async function evalIndexAllDone(projectRoot) {
+  let text;
+  try {
+    text = await fs.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'INDEX.md'), 'utf8');
+  } catch {
+    return { pass: false, detail: 'INDEX.md unreadable' };
+  }
+  const rows = String(text)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => /^\|TASK-/i.test(line));
+  if (rows.length === 0) return { pass: false, detail: 'INDEX.md has no task rows' };
+  const failing = [];
+  for (const row of rows) {
+    const cells = row.split('|').map((c) => c.trim()).filter(Boolean);
+    const status = (cells[4] || '').toLowerCase();
+    if (status !== 'done' && status !== 'cancelled_superseded') {
+      failing.push(`${cells[0]}=${cells[4] || '?'}`);
+    }
+  }
+  return failing.length === 0
+    ? { pass: true, detail: `${rows.length} task row(s) done` }
+    : { pass: false, detail: `not done: ${failing.join(', ')}` };
+}
+
+/**
+ * `git:clean` — `git status --porcelain` is empty. A non-git directory (or a
+ * missing git binary) cannot prove clean, so the term fails without throwing.
+ */
+function evalGitClean(projectRoot) {
+  try {
+    if (!fsSync.existsSync(path.join(projectRoot, '.git'))) {
+      return { pass: false, detail: 'not a git worktree' };
+    }
+    const res = spawnSync('git', ['status', '--porcelain'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 2000,
+    });
+    if (res.error || res.status !== 0) {
+      return { pass: false, detail: 'git status failed' };
+    }
+    return String(res.stdout).trim() === ''
+      ? { pass: true, detail: 'clean' }
+      : { pass: false, detail: 'dirty worktree' };
+  } catch {
+    return { pass: false, detail: 'git status failed' };
+  }
+}
+
+/**
+ * `file-exists:<relpath>` — the repo-relative path exists. Absolute paths and
+ * `..` segments are rejected outright: the predicate may only look inside the
+ * project root.
+ */
+async function evalFileExists(projectRoot, rel) {
+  const segments = String(rel).split(/[\\/]/);
+  if (path.isAbsolute(rel) || segments.includes('..')) {
+    return { pass: false, detail: 'path escapes project root' };
+  }
+  try {
+    await fs.stat(path.join(projectRoot, rel));
+    return { pass: true, detail: 'exists' };
+  } catch {
+    return { pass: false, detail: 'missing' };
+  }
+}
+
+/**
+ * Evaluate the RUN.md `ExitPredicate:` expression. Returns
+ * `{ ok, terms: [{term, pass, detail}] }`; `ok` is false when the expression is
+ * malformed (unsatisfiable). Advisory like the rest of the lane — a thrown
+ * error becomes a failed term, never an exception.
+ */
+async function evaluateExitPredicate(projectRoot, expr) {
+  const terms = parseExitPredicate(expr);
+  if (!terms) {
+    return { ok: false, terms: [{ term: String(expr || '').trim() || '(empty)', pass: false, detail: 'malformed predicate' }] };
+  }
+  const results = [];
+  for (const term of terms) {
+    let r;
+    try {
+      if (term === 'index:all-done') r = await evalIndexAllDone(projectRoot);
+      else if (term === 'git:clean') r = evalGitClean(projectRoot);
+      else r = await evalFileExists(projectRoot, term.slice('file-exists:'.length));
+    } catch (err) {
+      r = { pass: false, detail: `evaluator error: ${err?.message || err}` };
+    }
+    results.push({ term, pass: r.pass, detail: r.detail });
+  }
+  return { ok: results.every((r) => r.pass), terms: results };
+}
+
+/** One-line per-term predicate state for block reasons and stall advisories. */
+function formatPredicateState(result) {
+  return result.terms.map((t) => `${t.term}=${t.pass ? 'pass' : `FAIL (${t.detail})`}`).join(', ');
+}
+
 /**
  * Mutate `.ukit/storage/cache/stop-coordinator/state.json`'s `handoff` slot:
  * { signature, count }. Same signature as last time → count+1; a moved cursor
@@ -506,6 +642,13 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
  * un-advancing cursor has already bounced `maxStalledBlocks` stops in a row
  * (liveness breaker — the gate must never be an unstoppable loop).
  *
+ * Exit predicate (mechanic #7): when RUN.md carries an `ExitPredicate:` line,
+ * `Phase: done` is only accepted if the predicate evaluates true — a `done`
+ * claim with failing terms is bounced back with the per-term state. A missing
+ * predicate keeps the legacy phase-only release; `Phase: blocked` stays
+ * terminal either way. The predicate is never relaxed: the stalled-cursor
+ * advisory reports its state so a plateau is visible, not silent.
+ *
  * Advisory lane: EVERY failure path returns { kind: 'none' }, never throws.
  */
 export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS } = {}) {
@@ -518,21 +661,57 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   } catch {
     return { kind: 'none' };
   }
-  const { goal, phase, cursor, next } = parseRunCursor(text);
-  if (!phase || /^done\b/i.test(phase) || /^blocked\b/i.test(phase)) {
+  const { goal, phase, cursor, next, exitPredicate } = parseRunCursor(text);
+  // Shared terminal predicate — tests/handoff/cycle21 greps this exact shape across
+  // all four RUN.md consumers; keep `^(done|blocked)` as one expression.
+  const terminal = String(phase).match(/^(done|blocked)\b/i)?.[1]?.toLowerCase() || '';
+  if (!phase || terminal === 'blocked') {
     return { kind: 'none' };
   }
+  if (terminal === 'done') {
+    if (!exitPredicate) return { kind: 'none' }; // legacy phase-only release
+    let predicate;
+    try {
+      predicate = await evaluateExitPredicate(projectRoot, exitPredicate);
+    } catch {
+      return { kind: 'none' }; // advisory lane: evaluator failure never wedges a stop
+    }
+    if (predicate.ok) return { kind: 'none' };
+    const lines = [
+      'UKit handoff run claims `Phase: done` but its ExitPredicate is not satisfied — this',
+      'stop is refused. "Done" means the predicate the planner wrote at P2 evaluates true;',
+      'a plateau is not a stop and the predicate is never relaxed.',
+      '',
+      `  Goal:           ${goal || '(not recorded)'}`,
+      `  ExitPredicate:  ${exitPredicate}`,
+      `  Predicate state: ${formatPredicateState(predicate)}`,
+      '',
+      'CONTINUE IMMEDIATELY: read docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md, finish',
+      'the work the failing terms name (or record the real external blocker and set',
+      '`Phase: blocked`), then rewrite the run cursor.',
+    ];
+    return { kind: 'block', reason: lines.join('\n') };
+  }
 
   const signature = `${phase}|${cursor}|${next}`;
   const streak = await bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs });
   if (streak !== null && streak > gate.maxStalledBlocks) {
+    let predicateState = 'no ExitPredicate recorded';
+    if (exitPredicate) {
+      try {
+        predicateState = formatPredicateState(await evaluateExitPredicate(projectRoot, exitPredicate));
+      } catch {
+        predicateState = 'predicate evaluation failed';
+      }
+    }
     return {
       kind: 'advisory',
       systemMessage:
         `[ukit-stop-coordinator] handoff-cursor released this stop: the run cursor ` +
         `("${signature}") has not advanced across ${streak - 1} consecutive blocked stops ` +
         `(cap ${gate.maxStalledBlocks}), so the gate treats the run as stalled rather than ` +
-        `looping forever. Inspect docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md; ` +
+        `looping forever. ExitPredicate state: ${predicateState}. ` +
+        `Inspect docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md; ` +
         `the run can be resumed with /ukit:handoff-fullstack or cleared with /ukit:handoff-clear.`,
     };
   }

package/{templates → template_project}/.claude/ukit/runtime/task-watchdog.mjs

@@ -14,7 +14,7 @@
  * Exports:
  *   DEFAULT_CONFIG                — fail-open defaults; identical to the
  *                                   `handoff.taskBudgets` / `handoff.milestoneIntervalMin`
- *                                   keys seeded into templates/ukit/storage/config.json.
+ *                                   keys seeded into template_project/ukit/storage/config.json.
  *   parseTaskFile(markdown)       — minimal twin of src/core/taskProgressGuard's
  *                                   parser; reads id, status, size, lastProgressIso.
  *   evaluateBudgets(...)          — per in_progress task returns

package/{templates → template_project}/.gitignore

@@ -49,9 +49,9 @@ Thumbs.db
 # legacy: Antigravity adapter removed in v2.2.0; leftovers must stay ignored
 .antigravity/
 # NOTE (C12): runtime dirs (.claude/ .codex/ .omp/ .ukit/) are deliberately NOT
-# ignored here. This file is a per-directory .gitignore for templates/, so an
+# ignored here. This file is a per-directory .gitignore for template_project/, so an
 # unanchored `.claude/` silently hid NEW template files (it swallowed
-# templates/.claude/ukit/index/task-budget-validator.mjs). The root .gitignore
+# template_project/.claude/ukit/index/task-budget-validator.mjs). The root .gitignore
 # already carries the anchored /.claude/ /.codex/ /.omp/ /.ukit/ exclusions.
 opencode.json
 /AGENTS.md

package/{templates → template_project}/.omp/RULES.md

@@ -1,5 +1,5 @@
 # .omp/RULES.md — sticky always-apply rules
-<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->
+<!-- generated: template_project/instructions/ — edit sources, then yarn docs:render -->
 
 omp re-attaches this file near every turn from its native location (`.omp/RULES.md` only, never a
 copy elsewhere). It carries the always-apply subset of root `AGENTS.md` that must survive even when

package/{templates → template_project}/.omp/agents/code-reviewer.md

@@ -56,6 +56,8 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 VERDICT: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL
 REVIEWER_MODEL: [model name actually used]
 EXECUTOR_MODEL: [from executor report]
+PANEL_MEMBER: [panel tier — `@slow`/`@default`/`@smol`, or `solo` when the panel degenerates; `-` outside panel runs]
+AGREEMENT_MAP: [lead member only — finding → panel members reporting it, from review-panel-aggregate.mjs output; `-` otherwise]
 VERIFICATION_RERUN:
   command: [exact command]
   result: [N pass / M fail]
@@ -120,6 +122,31 @@ Same model is the most common silent failure. Do not skip this check.
 - Keep the verdict block <= 30 lines. Findings are bullet points, not essays.
 - The same-model refusal above is non-negotiable: bypassing it defeats the entire Quality Gate.
 
+
+## Panel review (diversity review)
+
+When the orchestrator spawns you as one member of the `modelRoles['review-panel']`
+panel (`.ukit/storage/config.json` → `modelRoles`, default `['smart','code','lite']`
+— the omp tier aliases `@slow`/`@default`/`@smol`), everything above applies
+unchanged — same Review order, same severity ladder, same verdict block — with these
+additions:
+
+- Set `PANEL_MEMBER: <tier>` in the verdict to your panel tier (e.g. `@slow`,
+  `@default`, `@smol`). Every member runs the same rubric independently; do not read
+  or wait for other members' verdicts.
+- Leave `AGREEMENT_MAP` as `-` unless you are the **lead member** (the first entry in
+  `modelRoles['review-panel']` = the judgment tier). After the orchestrator runs
+  `node .claude/ukit/index/review-panel-aggregate.mjs <TASK-xxx.md...>` and hands you
+  the output, the lead fills `AGREEMENT_MAP` with the emitted finding → members map
+  and applies the lead-judgment buckets to every finding: **Act on** / **Consider** /
+  **Noted** / **Dismissed**.
+- `consensus≥2 identical findings = high signal`: a finding reported by two or more
+  panel members is high-signal and must not be bucketed below **Consider** without a
+  stated reason.
+- Degenerate panel: if `modelRoles['review-panel']` is empty or has one entry, the
+  panel collapses to a single reviewer — run the normal solo review, set
+  `PANEL_MEMBER: solo`, and note the fallback in `NOTES`.
+
 ## Spec/Plan Review (REVIEW_TARGET_TYPE=spec|plan)
 
 ### Inputs you expect

package/{templates → template_project}/.omp/agents/handoff-planner.md

@@ -75,7 +75,7 @@ verification — link both files' `## Discussion` threads.
 
 ## Phase 0.5 — Write SPEC.md
 
-Write `docs/AI_HANDOFF/SPEC.md` from the template at `templates/docs/AI_HANDOFF/SPEC.md`
+Write `docs/AI_HANDOFF/SPEC.md` from the template at `template_project/docs/AI_HANDOFF/SPEC.md`
 (15 sections). The spec is the contract executors implement against — concrete enough that
 nothing is guessed: exact paths, module and API names, schemas, validation rules,
 permissions, empty/error states, migration behavior, test expectations. Every section is
@@ -134,7 +134,7 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 | Dependencies | `TASK-xxx` or `none` — wave order is inferred from this |
 | Test Cases | Type \| Test Name \| Expected — ≥1 happy + ≥2 edge cases of different kinds |
 | Test Files | Exact test file paths to create/modify |
-| 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`; `templates/.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 |
+| 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`.
@@ -195,6 +195,21 @@ Status: planning_done — ready for executor
 ```
 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
+keeps it verbatim on every cursor rewrite):
+
+```
+ExitPredicate: all(index:all-done, git:clean)
+```
+
+Grammar: `all(<term>[,<term>...])` or a single term; terms are `index:all-done`,
+`git:clean`, `file-exists:<relpath>` (repo-relative, no `..` segments). Default to
+`all(index:all-done, git:clean)`; add `file-exists:` terms only for artifacts the plan
+itself must produce. The stop gate evaluates this mechanically when the cursor claims
+`Phase: done` — a `done` claim with failing terms is bounced back with the per-term
+state. **Never relax the predicate mid-run**: if the run cannot satisfy it, the plan is
+wrong — fix the plan, not the gate.
+
 ## Self-Audit — run before reporting, every time
 
 The downstream pipeline is unattended: an incomplete or wrong plan is not caught by a human

package/{templates → template_project}/.omp/config.yml

@@ -57,7 +57,7 @@ tools:
     computer: allow
 
 bash:
-  # Translated from templates/.claude/hooks/block-dangerous.sh's DANGEROUS_PATTERNS array.
+  # Translated from template_project/.claude/hooks/block-dangerous.sh's DANGEROUS_PATTERNS array.
   # `deny`/`prompt` fire on the WHOLE command or on ANY compound segment (e.g. `foo && rm -rf /`
   # still hits the `rm -rf /*` entry below) — so a `deny` entry below the trailing allow still
   # catches it. `allow` only ever matches an ENTIRE, non-compound command, so the trailing "*"
@@ -121,9 +121,9 @@ memory:
 # Auto-compact must trigger BEFORE context-hardcap-gate.sh starts blocking tool
 # calls (compact.hardCapTokens, default 500000). Rendered at install time from the
 # same derived number as env.CLAUDE_CODE_AUTO_COMPACT_WINDOW in
-# templates/.claude/settings.json (70% of hardCapTokens), so omp and Claude Code
+# template_project/.claude/settings.json (70% of hardCapTokens), so omp and Claude Code
 # cannot drift apart and retuning both is a single edit to
-# templates/ukit/storage/config.json.
+# template_project/ukit/storage/config.json.
 #
 # Key VERIFIED against omp v17.4.2 (2026-08-22): `compaction.thresholdTokens` is a
 # fixed token limit for context maintenance and overrides the percentage threshold

package/{templates → template_project}/AGENTS.md

@@ -1,5 +1,5 @@
 # AGENTS.md — {{project.name}}
-<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->
+<!-- generated: template_project/instructions/ — edit sources, then yarn docs:render -->
 
 ## Core Rule
 <!-- RULES: CORE-01 CORE-02 -->
@@ -64,7 +64,7 @@
 - Missing/corrupt runtime or stale workspace → rerun `ukit install`.
 
 ## Skill Quality (maintainer-only)
-- Editing `templates/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
+- Editing `template_project/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
 
 ## UKit v{{ukit.version}} Shared Runtime
 - Runtime state: `.ukit/storage/`; `config.json` holds toggles (compact, token pipeline, router, memory, validation, Safe Patch). `ukit memory recall "<task>"` before asking users to restate decisions; `learn`/`promote`/`episode` manage memory; inspect via `ukit status` / `ukit memory export`. Route memory: `.claude/ukit/skill-router-state.json` (`previous-context`/`recent-output` first); cache: `.ukit/storage/cache/output-history.json` + `retriever-lanes.jsonl` + `tee/`. Hooks degrade to exit 0; missing/corrupt runtime → rerun `ukit install`.

package/{templates → template_project}/CLAUDE.md

@@ -1,5 +1,5 @@
 # CLAUDE.md — {{project.name}}
-<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->
+<!-- generated: template_project/instructions/ — edit sources, then yarn docs:render -->
 
 ## Core Rule
 <!-- RULES: CORE-01 CORE-02 -->
@@ -64,7 +64,7 @@
 - Missing/corrupt runtime or stale workspace → rerun `ukit install`.
 
 ## Skill Quality (maintainer-only)
-- Editing `templates/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
+- Editing `template_project/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
 
 ## UKit v{{ukit.version}} Shared Runtime
 - Runtime state: `.ukit/storage/`; `config.json` holds toggles (compact, token pipeline, router, memory, validation, Safe Patch). `ukit memory recall "<task>"` before asking users to restate decisions; `learn`/`promote`/`episode` manage memory; inspect via `ukit status` / `ukit memory export`. Route memory: `.claude/ukit/skill-router-state.json` (`previous-context`/`recent-output` first); cache: `.ukit/storage/cache/output-history.json` + `retriever-lanes.jsonl` + `tee/`. Hooks degrade to exit 0; missing/corrupt runtime → rerun `ukit install`.

package/{templates → template_project}/docs/AI_HANDOFF/RULES.md

@@ -170,7 +170,7 @@ chạy **đến khi không còn gì để làm**:
 Resolution order — exactly three steps, in this order. A task's Verification Commands MUST NOT default to the full suite:
 
 1. Target File under `src/` or `scripts/` → read `.cache/index/tests-map.json` and take the `tests` array for that `sourceFile`.
-2. Target File under `templates/.claude/**` or `.claude/**` → `tests-map.json` has no coverage of these paths, so use the path convention: hooks → `tests/hooks/` + `tests/handoff/cycle*/`; manifest/settings → `tests/manifest/`; runtime `.mjs` mirrors → `tests/core/*Parity*` + `tests/index/`.
+2. Target File under `template_project/.claude/**` or `.claude/**` → `tests-map.json` has no coverage of these paths, so use the path convention: hooks → `tests/hooks/` + `tests/handoff/cycle*/`; manifest/settings → `tests/manifest/`; runtime `.mjs` mirrors → `tests/core/*Parity*` + `tests/index/`.
 3. **Mandatory non-empty floor** — if steps 1–2 resolve to fewer than one test file, the task MUST fall back to `yarn test:release-core`. An empty selection is never permitted. This floor is a fallback for a single task's narrowed selection, not a default — most tasks resolve via steps 1–2 and never reach it.
 
 **Wave/cycle boundary regression net** — the three steps above narrow one task's Verification Commands only; they are not a substitute for full-suite coverage. A full `yarn test` run at each wave/cycle boundary MUST happen and is the regression net for every per-task narrowed selection made under this policy. `code-reviewer.md`'s "wave-boundary full `yarn test` ... is the regression net" sentence refers to this paragraph.

package/{templates → template_project}/docs/UKIT_INTERNALS.md

@@ -58,7 +58,7 @@ the root contract is the only carrier — keep both in sync with
 
 ## Skill Quality (maintainer-only)
 
-- When editing a template skill/agent under `templates/.claude/`, read
+- When editing a template skill/agent under `template_project/.claude/`, read
   `.claude/skills/skill-quality/SKILL.md` before shipping the change.
 
 ## Shared Runtime — detail
@@ -289,12 +289,12 @@ Internals: `src/core/permissionPolicy.js` compiles the semantic policy (preceden
   line). To surface diagnostics from an earlier step, have the step that owns the
   verdict include them.
 - The same test also guards the settings↔bridge mirror: `HOOK_EVENT_MAP` in
-  `templates/.omp/hooks/pre/ukit-bridge.js` must equal the settings chain args 1:1
+  `template_project/.omp/hooks/pre/ukit-bridge.js` must equal the settings chain args 1:1
   per event/matcher.
 
 ## Compressed contract detail (cycle 45 diet)
 
-Detail dropped from `templates/instructions/core.md` during the ~25% system-prompt diet; semantics unchanged.
+Detail dropped from `template_project/instructions/core.md` during the ~25% system-prompt diet; semantics unchanged.
 
 - **Prompt Caching one-liners** — CTX-01 deterministic segment bytes · CTX-02 keep roles and order · CTX-03 keep tool IDs and continuation state · CTX-04 no clock/random IDs in static blocks · CTX-05 compaction starts a new epoch · CTX-06 never change data to match a cache · CTX-07 no unconfirmed cache fields · CTX-08 tool-result reuse needs valid freshness · CTX-09 missing usage is unknown, not zero · CTX-10 never cut a required check to reduce calls. Full ruleset: `docs/PROMPT_CACHING.md`.
 - **Common skill triggers** — review/audit/diff/PR → `code-review` · bug/error/crash/triage → `debugging-toolkit` · test/spec/coverage → `testing-quality` · docs/README/changelog/`docs/` edits → `docs-quality` · open-ended/status/continue/queued task → `next-step` · wrap up/`docs/STATUS.md` → `update-status` · auth/security/token/permission/risky → `discover-security` · stale workspace/reinstall/cleanup → `repo-maintenance` (all under `.claude/skills/<name>/SKILL.md`).

package/{templates → template_project}/instructions/core.md

@@ -61,7 +61,7 @@
 - Missing/corrupt runtime or stale workspace → rerun `ukit install`.
 
 ## Skill Quality (maintainer-only)
-- Editing `templates/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
+- Editing `template_project/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
 
 ## UKit v{{ukit.version}} Shared Runtime
 - Runtime state: `.ukit/storage/`; `config.json` holds toggles (compact, token pipeline, router, memory, validation, Safe Patch). `ukit memory recall "<task>"` before asking users to restate decisions; `learn`/`promote`/`episode` manage memory; inspect via `ukit status` / `ukit memory export`. Route memory: `.claude/ukit/skill-router-state.json` (`previous-context`/`recent-output` first); cache: `.ukit/storage/cache/output-history.json` + `retriever-lanes.jsonl` + `tee/`. Hooks degrade to exit 0; missing/corrupt runtime → rerun `ukit install`.

package/{templates → template_project}/instructions/layout.yaml

@@ -6,9 +6,9 @@ description: >-
   verbatim with no ## prefix) and `*` (all ## sections of the source in file
   order). Every source ## section must be referenced by ≥1 output (FR-006).
 outputs:
-  - target: templates/CLAUDE.md
+  - target: template_project/CLAUDE.md
     h1: '# CLAUDE.md — {{project.name}}'
-    banner: '<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->'
+    banner: '<!-- generated: template_project/instructions/ — edit sources, then yarn docs:render -->'
     resolve_vars: false
     sections:
       - { from: core, heading: Core Rule }
@@ -38,9 +38,9 @@ outputs:
       - { from: core, heading: Handoff Fullstack Rules }
       - { from: core, heading: Compact Instructions }
     trailer: '{{codegraphSection}}'
-  - target: templates/AGENTS.md
+  - target: template_project/AGENTS.md
     h1: '# AGENTS.md — {{project.name}}'
-    banner: '<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->'
+    banner: '<!-- generated: template_project/instructions/ — edit sources, then yarn docs:render -->'
     resolve_vars: false
     sections:
       - { from: core, heading: Core Rule }
@@ -71,16 +71,16 @@ outputs:
       - { from: core, heading: Handoff Fullstack Rules }
       - { from: core, heading: Compact Instructions }
     trailer: '{{codegraphSection}}'
-  - target: templates/.omp/RULES.md
+  - target: template_project/.omp/RULES.md
     h1: '# .omp/RULES.md — sticky always-apply rules'
-    banner: '<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->'
+    banner: '<!-- generated: template_project/instructions/ — edit sources, then yarn docs:render -->'
     resolve_vars: false
     sections:
       - { from: 'overlay:omp-rules', heading: __preamble__ }
       - { from: 'overlay:omp-rules', heading: '*' }
   - target: CLAUDE.md
     h1: '# CLAUDE.md — @ngockhoale/ukit'
-    banner: '<!-- generated: templates/instructions/ + repo overlay — edit sources, then yarn docs:render -->'
+    banner: '<!-- generated: template_project/instructions/ + repo overlay — edit sources, then yarn docs:render -->'
     resolve_vars: true
     sections:
       - { from: 'overlay:repo', heading: Release Policy (mandatory — never replace) }
@@ -113,7 +113,7 @@ outputs:
     trailer: '{{codegraphSection}}'
   - target: AGENTS.md
     h1: '# AGENTS.md — @ngockhoale/ukit'
-    banner: '<!-- generated: templates/instructions/ + repo overlay — edit sources, then yarn docs:render -->'
+    banner: '<!-- generated: template_project/instructions/ + repo overlay — edit sources, then yarn docs:render -->'
     resolve_vars: true
     sections:
       - { from: 'overlay:repo', heading: Release Policy (mandatory — never replace) }

package/{templates → template_project}/instructions/overlays/claude.md

@@ -1,3 +1,3 @@
 <!-- Claude-only overlay. Intentionally carries no ## sections today: every
-     section of templates/CLAUDE.md is shared core. Kept as a comment-only
+     section of template_project/CLAUDE.md is shared core. Kept as a comment-only
      source so the overlay allowlist mechanism is exercised (SPEC §7.5). -->

package/{templates → template_project}/instructions/overlays/repo.md

@@ -6,4 +6,4 @@
 - **npm and git always hold the same latest version.** After publish, `npm view @ngockhoale/ukit version` must equal the `package.json` version; if they ever diverge, publishing wins and happens first.
 - **Never ask the user for npm publish permission** — approval is permanently granted for this package. Use `npm publish --dry-run` for pre-verification, then run the real publish in the same cycle.
 - Users update with `ukit update`, which pulls from npm — an unpublished fix reaches no one. Git is code history/tracking only; npm is the distribution channel.
-- **Repo-only rule:** this policy applies to the UKit development repo itself and must NEVER be added to `templates/CLAUDE.md` / `templates/AGENTS.md` (it must not ship to installed projects). Mirrored at the top of root CLAUDE.md + AGENTS.md; those copies can be wiped by a `ukit update` run inside this repo — if missing, restore them from this section.
+- **Repo-only rule:** this policy applies to the UKit development repo itself and must NEVER be added to `template_project/CLAUDE.md` / `template_project/AGENTS.md` (it must not ship to installed projects). Mirrored at the top of root CLAUDE.md + AGENTS.md; those copies can be wiped by a `ukit update` run inside this repo — if missing, restore them from this section.

package/{templates → template_project}/ukit/storage/config.json

@@ -84,7 +84,10 @@
     "defaultModel": "claude-sonnet-5"
   },
   "routing": {
-    "routeSchema": { "stage": "off" }
+    "routeSchema": { "stage": "off" },
+    "rigor": { "stage": "shadow" },
+    "fastPath": { "stage": "shadow" },
+    "escalation": { "stage": "shadow" }
   },
   "modelRoles": {
     "code": "code",

package/template_project/ukit/storage/memory/projects/.gitkeep

@@ -0,0 +1,2 @@
+,
+    'template_project/ukit/storage/memory/sessions/.gitkeep': 

package/templates/ukit/storage/memory/projects/.gitkeep

@@ -1,2 +0,0 @@
-,
-    'templates/ukit/storage/memory/sessions/.gitkeep':