@ngockhoale/ukit 3.0.1 → 3.0.2

package/template_project/.claude/ukit/runtime/execution-ledger.mjs

@@ -1634,7 +1634,10 @@ function requiredEvidence(state = {}) {
   // FR-006 (M01.4' tail): a route persisted with a high riskEscalation must re-verify at
   // Stop even when its own contract only demands write evidence. The route state is the
   // carrier — no config read here; absent/malformed/non-high fields are a no-op.
-  if (routeSummary.riskEscalation?.level === 'high') {
+  // C48 FR-004: a record stamped `stage: 'shadow'` is advisory-only and does not demand
+  // verification-evidence; a missing or malformed stage fails closed (enforcing) so
+  // pre-C48 persisted records keep re-verifying until re-stamped.
+  if (routeSummary.riskEscalation?.level === 'high' && routeSummary.riskEscalation?.stage !== 'shadow') {
     required.push('verification-evidence');
   }
   return [...new Set(required)];

package/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/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/template_project/.omp/agents/handoff-planner.md

@@ -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/template_project/ukit/storage/config.json

@@ -85,9 +85,9 @@
   },
   "routing": {
     "routeSchema": { "stage": "off" },
-    "rigor": { "stage": "off" },
-    "fastPath": { "stage": "off" },
-    "escalation": { "stage": "off" }
+    "rigor": { "stage": "shadow" },
+    "fastPath": { "stage": "shadow" },
+    "escalation": { "stage": "shadow" }
   },
   "modelRoles": {
     "code": "code",