@ngockhoale/ukit 3.0.1 → 3.0.2

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

@@ -59,7 +59,7 @@ resumable. If compaction does happen, the run resumes from the cursor automatica
 
 ### Run cursor — write after every step
 
-Maintain `docs/AI_HANDOFF/RUN.md`. Rewrite it (whole file, 6 lines) immediately after every
+Maintain `docs/AI_HANDOFF/RUN.md`. Rewrite it (whole file, 7 lines) immediately after every
 numbered step completes:
 
 ```
@@ -69,9 +69,15 @@ Base: <BASE branch>
 Phase: <P0|P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R4.5|R5|F|done|blocked>
 Cursor: wave <N> batch <M> — <what just finished>
 Next: <the exact next step to run>
+ExitPredicate: all(<term>[,<term>...])   # written once at P2; never relaxed
 QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 ```
 
+`ExitPredicate` grammar: `all(<term>[,<term>...])` or a single term; terms are
+`index:all-done`, `git:clean`, `file-exists:<relpath>`. The stop gate evaluates it
+mechanically when the cursor claims `Phase: done` — a `done` claim with failing terms
+is bounced back with the per-term state. Keep the line verbatim on every rewrite.
+
 This file is the resume contract. It costs one small write per step and is what turns an
 interrupted run into a continuable one.
 
@@ -172,9 +178,12 @@ The run must keep itself alive without the human watching.
 
 - **Stop gate (Claude Code, automatic):** while `RUN.md` `Phase:` is not `done`/`blocked`,
   `completion-gate.sh` refuses the stop with the cursor's `Next:` step. Recaps and
-  premature stops cannot park the run. A stalled-cursor breaker
+  premature stops cannot park the run. When RUN.md carries `ExitPredicate:`, a
+  `Phase: done` whose predicate fails is refused too — `done` means the predicate
+  evaluates true. A stalled-cursor breaker
   (`handoff.fullstack.stopGateMaxStalledBlocks`, default 12) releases the session if the
-  cursor has genuinely stopped advancing — the escape hatch, not the norm.
+  cursor has genuinely stopped advancing — the escape hatch, not the norm — and its
+  release advisory reports the predicate state, so a plateau is visible, not silent.
 - **Scheduled wakeup (when the harness offers one):** arm it at run start — Claude Code:
   `CronCreate` a ~`handoff.fullstack.idleWatchdogMin`-minute (default 5) session job with
   prompt `Resume HANDOFF FULLSTACK from docs/AI_HANDOFF/RUN.md — continue the Next: step`;
@@ -269,7 +278,13 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    ```
    Then **verify the write** (read back the `Status:` line).
 
-8. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
+8. **Write `ExitPredicate:` into `docs/AI_HANDOFF/RUN.md`** — the mechanical definition of
+   done for this run: `all(<term>[,<term>...])` over `index:all-done`, `git:clean`,
+   `file-exists:<relpath>` (default `all(index:all-done, git:clean)`). Written once,
+   before iteration 1, and **never relaxed** — if the run cannot satisfy it, the plan is
+   wrong, not the gate. Then **verify the write** (read back the `ExitPredicate:` line).
+
+9. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
    `needs_breakdown` tasks + reason.
 
 ### P2.5 — Independent plan review (strong model, separate agent)
@@ -455,7 +470,12 @@ Worktrees are **always deleted immediately** — no exceptions.
 A wave boundary is the only safe place to shed context, because everything of value is
 already on disk (task files hold the full logs, git holds the code). Do all four, in order:
 
-1. **Checkpoint the code** — one commit per wave, so every wave is independently revertible:
+1. **Checkpoint the code — commit-if-advanced.** One commit per wave, so every wave is
+   independently revertible — but only when the wave's diff advances the run's
+   `ExitPredicate` (a task moved toward `done`, a required file appeared, the worktree
+   got cleaner). A wave whose diff does not advance the predicate is **discarded**: its
+   copied-back changes are reverted and nothing is committed. A plateau is not a stop —
+   the run continues to the next wave or fix round; the predicate is never relaxed.
    ```bash
    git add -A && git commit -m "handoff: wave <N> — TASK-00x, TASK-00y"
    ```

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

@@ -54,9 +54,11 @@ If that diff is empty → handoff-implement was not completed. Report which task
 
 **Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next.
 
-**Claude Code — MANDATORY, do this before anything else:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
+**Spawn the review panel — MANDATORY, do this before anything else:** read `modelRoles['review-panel']` from `.ukit/storage/config.json` → `modelRoles` (default `['smart','code','lite']`; omp tier aliases `@smol`/`@default`/`@slow`). For each `pending_review` task in the batch, call the Agent tool **once per panel entry** (in parallel, bounded by `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per panel entry per task) — each member bound to its panel tier and setting `PANEL_MEMBER: <tier>` in its verdict. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the panel tiers and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
 
-The spawned reviewer agent performs 2a–2d below per task:
+Degenerate panel: if `modelRoles['review-panel']` is empty or has one entry, spawn a single reviewer and require `PANEL_MEMBER: solo` in its verdict.
+
+Each spawned reviewer agent performs 2a–2d below per task:
 
 ### 2a — Model isolation check (always first)
 
@@ -98,6 +100,7 @@ matches the task file's wording.
 VERDICT: approved | approved_minor | changes_requested | critical_block
 REVIEWER_MODEL: <your exact model ID>
 EXECUTOR_MODEL: <from Executor Report>
+PANEL_MEMBER: <panel tier | solo | ->
 VERIFICATION_RERUN: PASS | FAIL
 FINDINGS:
   critical: <file:line — what fails> | none
@@ -116,7 +119,29 @@ BLOCKING: <one line per critical/important finding, or "none">
 ```
 Do not paste the diff, the findings prose, or verification logs back into the orchestrator.
 
-### 2e — Orchestrator updates INDEX.md
+### 2e — Aggregate the panel + lead bucketing
+
+Once every panel member for a task has appended its `## Reviewer Verdict`, run:
+
+```bash
+node .claude/ukit/index/review-panel-aggregate.mjs docs/AI_HANDOFF/tasks/TASK-xxx.md
+```
+
+The script emits an Agreement Map (finding → set of panel members reporting it) and a
+consensus verdict (`approved` when ≥2 members approve and no critical;
+`changes_requested` when ≥1 critical or ≥2 request changes; else `approved_minor`).
+`consensus≥2 identical findings = high signal` — a finding reported by two or more
+members is high-signal. The consensus verdict, not any single member's vote, drives
+`NEXT_STATUS_FOR_INDEX`.
+
+Then the **lead member** (first entry in `modelRoles['review-panel']` = the judgment
+tier) applies the lead-judgment buckets to every finding — **Act on** / **Consider** /
+**Noted** / **Dismissed** — and appends a `## Panel Consensus` block to the task file
+carrying the Agreement Map and the bucketed findings. `Act on` findings feed Step 3's
+auto-fix loop; `Consider`/`Noted`/`Dismissed` are advisory. A high-signal finding must
+not be bucketed below `Consider` without a stated reason.
+
+### 2f — Orchestrator updates INDEX.md
 
 Set `status = NEXT_STATUS_FOR_INDEX`. Orchestrator writes INDEX, not the reviewer.
 
@@ -144,7 +169,7 @@ For round in 1..2:
    ```bash
    git add -A && git commit -m "handoff: fix round <N> — TASK-00x"
    ```
-4. Re-review **only the tasks touched this round**, in parallel, per 2a–2e. The reviewer must
+4. Re-review **only the tasks touched this round**, in parallel, per 2a–2f — panel spawn, aggregation, and lead bucketing included. The reviewers must
    still differ from the executor model and still re-runs verification itself.
 5. Update `INDEX.md` and `RUN.md`. Exit when everything is approved.
 
@@ -190,5 +215,5 @@ Then, as the last line:
 This is the only place this command may ask for a compaction. All state lives in git,
 `INDEX.md` and `RUN.md`, so a compacted or fresh session resumes with nothing lost.
 
-> Orchestrator (this session) handles Step 1, 2e, and 3 directly — those are not delegated.
-> **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model, run 2a–2d per task (one session at a time).
+> Orchestrator (this session) handles Step 1, 2e, 2f, and 3 directly — those are not delegated.
+> **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the strong model, run 2a–2d per task (one session at a time, panel members sequentially), then run `review-panel-aggregate.mjs` and apply the lead buckets yourself.

package/template_project/.claude/ukit/index/handoff-doc-validator.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// handoff-doc-validator.mjs — TASK-004 / Cycle C50 (shipped CLI twin)
+//
+// Self-contained twin of src/core/handoffDocValidator.js for user installs (no `src/`).
+// The logic below is a literal port — keep the two files behavior-identical when editing.
+//
+// REAL GATE — unlike task-budget-validator.mjs (advisory, always exit 0), this
+// script exits 1 on any violation. Do not "fix" the exit code.
+//
+// Usage:
+//   node .claude/ukit/index/handoff-doc-validator.mjs <file.md> [file.md...]
+//
+// Kind detection per file: basename PLAN.md → 'plan'; TASK-*.md → 'task';
+// otherwise content sniffing (`## §1` → plan, `## Goal` → task, else
+// executor-report). Task files carrying `## Executor Report` are also checked
+// against the report header contract.
+//
+// Output:
+//   `PASS <file>` when clean; one `FAIL <file>: <rule>` line per violation.
+//   Exit 0 when every file passes, 1 otherwise, 2 on usage/read errors.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+const PLAN_SECTIONS = ['§1', '§2', '§3', '§4', '§5', '§6'];
+
+const TASK_SECTIONS = [
+  'Goal',
+  'Target Files',
+  'Test Cases',
+  'Test Files',
+  'Verification Commands',
+  'Acceptance Criteria',
+  'Dependencies',
+  'Interfaces',
+];
+
+const REPORT_FIELDS = ['EXECUTOR_TOOL', 'EXECUTOR_MODEL', 'EXECUTOR_SUBAGENT', 'RED_OUTPUT'];
+
+// Section helpers. Any line starting with `## ` opens a section; the body runs
+// until the next `## ` line or EOF. Returns [{ name, body, pos }] in file order.
+function splitSections(markdown) {
+  const sections = [];
+  const lines = String(markdown).split('\n');
+  let current = null;
+  lines.forEach((line, idx) => {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      current = { name: m[1], body: '', pos: idx };
+      sections.push(current);
+    } else if (current) {
+      current.body += line + '\n';
+    }
+  });
+  return sections;
+}
+
+// Positions of `## §<n>` headings, keyed by the literal token ('§1'..'§6').
+// A heading matches when its name starts with the token (`## §1 Intent`).
+function planSectionPositions(sections) {
+  const positions = new Map();
+  for (const s of sections) {
+    for (const token of PLAN_SECTIONS) {
+      if (!positions.has(token) && s.name.startsWith(token)) positions.set(token, s.pos);
+    }
+  }
+  return positions;
+}
+
+function hasSection(sections, name) {
+  return sections.some((s) => s.name === name || s.name.startsWith(`${name} `) || s.name.startsWith(`${name}(`));
+}
+
+function getSection(sections, name) {
+  return sections.find((s) => s.name === name || s.name.startsWith(`${name} `) || s.name.startsWith(`${name}(`));
+}
+
+function validatePlan(markdown) {
+  const failures = [];
+  const sections = splitSections(markdown);
+  const positions = planSectionPositions(sections);
+
+  for (const token of PLAN_SECTIONS) {
+    if (!positions.has(token)) failures.push(`missing required section heading "## ${token}"`);
+  }
+
+  // Order check over the sections that exist: each must appear after the
+  // highest position seen so far.
+  let maxPos = -1;
+  for (const token of PLAN_SECTIONS) {
+    const pos = positions.get(token);
+    if (pos === undefined) continue;
+    if (pos < maxPos) {
+      failures.push(`section order violation: "## ${token}" appears after a later section`);
+    } else {
+      maxPos = pos;
+    }
+  }
+
+  const report = getSection(sections, 'Planner Report');
+  if (!report) {
+    failures.push('missing required section "## Planner Report"');
+  } else if (!/^PLANNER_MODEL\s*:/m.test(report.body)) {
+    failures.push('missing required field "PLANNER_MODEL:" inside "## Planner Report"');
+  }
+
+  return failures;
+}
+
+function validateExecutorReportFields(markdown, prefix) {
+  const failures = [];
+  for (const field of REPORT_FIELDS) {
+    if (!new RegExp(`^${field}\\s*:`, 'm').test(markdown)) {
+      failures.push(`${prefix}missing required field "${field}:"`);
+    }
+  }
+  return failures;
+}
+
+function validateTask(markdown) {
+  const failures = [];
+  const sections = splitSections(markdown);
+
+  for (const name of TASK_SECTIONS) {
+    if (!hasSection(sections, name)) failures.push(`missing required section "## ${name}"`);
+  }
+  if (!/^\s*-?\s*Status\s*:/m.test(markdown)) {
+    failures.push('missing required field "Status:"');
+  }
+
+  // A task file that already carries an Executor Report must satisfy the
+  // report header contract too (FR-007).
+  const report = getSection(sections, 'Executor Report');
+  if (report) {
+    failures.push(...validateExecutorReportFields(report.body, 'executor-report: '));
+  }
+
+  return failures;
+}
+
+export function validateHandoffDoc(markdown, kind) {
+  const text = String(markdown ?? '');
+  let failures;
+  if (kind === 'plan') failures = validatePlan(text);
+  else if (kind === 'task') failures = validateTask(text);
+  else if (kind === 'executor-report') failures = validateExecutorReportFields(text, '');
+  else failures = [`unknown kind "${kind}" (expected plan|task|executor-report)`];
+  return { ok: failures.length === 0, failures };
+}
+
+// CLI-only helpers below (not part of the canonical module).
+
+function detectKind(filePath, markdown) {
+  const base = path.basename(filePath);
+  if (/^PLAN\.md$/i.test(base)) return 'plan';
+  if (/^TASK-.*\.md$/i.test(base)) return 'task';
+  if (/^##\s+§1/m.test(markdown)) return 'plan';
+  if (/^##\s+Goal\b/m.test(markdown)) return 'task';
+  return 'executor-report';
+}
+
+function main() {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.error('usage: handoff-doc-validator.mjs <file.md> [file.md...]');
+    process.exit(2);
+  }
+  let failed = false;
+  for (const file of files) {
+    let markdown;
+    try {
+      markdown = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      console.log(`FAIL ${file}: unreadable (${err.message})`);
+      failed = true;
+      continue;
+    }
+    const { ok, failures } = validateHandoffDoc(markdown, detectKind(file, markdown));
+    if (ok) {
+      console.log(`PASS ${file}`);
+    } else {
+      failed = true;
+      for (const f of failures) console.log(`FAIL ${file}: ${f}`);
+    }
+  }
+  process.exit(failed ? 1 : 0);
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main();
+}

package/template_project/.claude/ukit/index/review-panel-aggregate.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// review-panel-aggregate.mjs — TASK-004 / Cycle C50 (shipped CLI twin)
+//
+// Self-contained twin of src/core/reviewPanelAggregate.js for user installs (no `src/`).
+// The logic below is a literal port — keep the two files behavior-identical when editing.
+//
+// ADVISORY — always exits 0. Aggregation output feeds the lead reviewer's
+// AGREEMENT_MAP field and the orchestrator's INDEX status update; it must never
+// break a pipeline.
+//
+// Usage:
+//   node .claude/ukit/index/review-panel-aggregate.mjs <TASK-xxx.md> [TASK-xxx.md...]
+//
+// Reads every `## Reviewer Verdict` block from the given task files, then prints:
+//   AGREEMENT_MAP: finding → member, member   (one line per finding)
+//   HIGH_SIGNAL:   finding → member, member   (≥2 members or any critical)
+//   UNPARSED:      <file>#verdict[<i>]         (blocks with no VERDICT line)
+//   VERDICT: approved | approved_minor | changes_requested
+
+import fs from 'node:fs';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+const SEVERITIES = ['critical', 'important', 'minor'];
+
+// Parse one `## Reviewer Verdict` block (format: code-reviewer.md §Output).
+// Returns null when no recognizable VERDICT line exists — the block is then
+// counted as absent and named in `unparsed`.
+export function parseVerdictBlock(text) {
+  const src = String(text ?? '');
+  const verdictMatch = src.match(/^VERDICT\s*:\s*(APPROVED-WITH-MINOR|APPROVED|CHANGES-REQUESTED|CRITICAL)\s*$/im);
+  if (!verdictMatch) return null;
+
+  const memberMatch = src.match(/^PANEL_MEMBER\s*:\s*(\S+)\s*$/im);
+  const member = memberMatch && memberMatch[1] !== '-' ? memberMatch[1] : null;
+
+  const findings = { critical: [], important: [], minor: [] };
+  const findingsMatch = src.match(/^FINDINGS:\s*$/im);
+  if (findingsMatch) {
+    const rest = src.slice(findingsMatch.index + findingsMatch[0].length);
+    let severity = null;
+    for (const line of rest.split('\n')) {
+      if (/^\S/.test(line)) break; // next top-level field ends FINDINGS
+      const sev = line.match(/^\s{2}(critical|important|minor)\s*:/);
+      if (sev) {
+        severity = sev[1];
+        continue;
+      }
+      const item = line.match(/^\s{4}-\s+(.+?)\s*$/);
+      if (item && severity) {
+        const text2 = item[1];
+        if (text2 !== 'none' && text2 !== '-') findings[severity].push(text2);
+      }
+    }
+  }
+
+  return { member, verdict: verdictMatch[1].toUpperCase(), findings };
+}
+
+// Normalize a finding bullet for identity comparison: two members report the
+// "identical finding" when the normalized text matches.
+function normalizeFinding(text) {
+  return String(text).replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+export function aggregatePanelVerdicts(verdicts) {
+  const list = Array.isArray(verdicts) ? verdicts : [];
+  const parsed = [];
+  const unparsed = [];
+
+  list.forEach((block, i) => {
+    const p = parseVerdictBlock(block);
+    if (p) parsed.push({ ...p, label: p.member || `verdict[${i}]` });
+    else unparsed.push(`verdict[${i}]`);
+  });
+
+  // Agreement Map: finding → set of panel members reporting it.
+  const map = new Map(); // normalized → { finding, members:Set, critical:boolean }
+  for (const p of parsed) {
+    for (const sev of SEVERITIES) {
+      for (const f of p.findings[sev]) {
+        const key = normalizeFinding(f);
+        let entry = map.get(key);
+        if (!entry) {
+          entry = { finding: f, members: new Set(), critical: sev === 'critical' };
+          map.set(key, entry);
+        }
+        entry.members.add(p.label);
+        if (sev === 'critical') entry.critical = true;
+      }
+    }
+  }
+
+  const agreementMap = [...map.values()].map((e) => ({
+    finding: e.finding,
+    members: [...e.members],
+  }));
+  const highSignal = [...map.values()]
+    .filter((e) => e.members.size >= 2 || e.critical)
+    .map((e) => ({ finding: e.finding, members: [...e.members] }));
+
+  const approvals = parsed.filter((p) => p.verdict === 'APPROVED').length;
+  const changeRequests = parsed.filter((p) => p.verdict === 'CHANGES-REQUESTED').length;
+  const hasCritical =
+    parsed.some((p) => p.verdict === 'CRITICAL') || parsed.some((p) => p.findings.critical.length > 0);
+
+  let verdict;
+  if (hasCritical || changeRequests >= 2) verdict = 'changes_requested';
+  else if (approvals >= 2) verdict = 'approved';
+  else verdict = 'approved_minor';
+
+  return { agreementMap, verdict, highSignal, unparsed };
+}
+
+// CLI-only helpers below (not part of the canonical module).
+
+// Extract every `## Reviewer Verdict` block from a task file. A block runs from
+// its heading to the next `## ` heading or EOF.
+function extractVerdictBlocks(markdown) {
+  const blocks = [];
+  const re = /^##\s+Reviewer Verdict\s*$/gm;
+  let m;
+  while ((m = re.exec(markdown)) !== null) {
+    const start = m.index;
+    const rest = markdown.slice(start + m[0].length);
+    const next = rest.search(/^##\s+/m);
+    blocks.push(next === -1 ? rest : rest.slice(0, next));
+  }
+  return blocks;
+}
+
+function main() {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.error('usage: review-panel-aggregate.mjs <TASK-xxx.md> [TASK-xxx.md...]');
+    process.exit(0); // advisory — never break a pipeline
+  }
+
+  const blocks = [];
+  const labels = [];
+  for (const file of files) {
+    let markdown;
+    try {
+      markdown = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      console.log(`UNPARSED: ${file} (unreadable: ${err.message})`);
+      continue;
+    }
+    for (const block of extractVerdictBlocks(markdown)) {
+      labels.push(file);
+      blocks.push(block);
+    }
+  }
+
+  const { agreementMap, verdict, highSignal, unparsed } = aggregatePanelVerdicts(blocks);
+
+  console.log('AGREEMENT_MAP:');
+  for (const e of agreementMap) console.log(`  ${e.finding} → ${e.members.join(', ')}`);
+  if (agreementMap.length === 0) console.log('  (none)');
+  console.log('HIGH_SIGNAL:');
+  for (const e of highSignal) console.log(`  ${e.finding} → ${e.members.join(', ')}`);
+  if (highSignal.length === 0) console.log('  (none)');
+  if (unparsed.length === 0) console.log('UNPARSED: (none)');
+  for (const u of unparsed) {
+    const idx = Number(u.slice('verdict['.length, -1));
+    console.log(`UNPARSED: ${labels[idx] ?? '?'}#${u}`);
+  }
+  console.log(`VERDICT: ${verdict}`);
+  process.exit(0);
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main();
+}

package/template_project/.claude/ukit/index/route-task.mjs

@@ -70,6 +70,7 @@ export const ROUTE_MUTABILITIES = new Set(['read-only', 'mutating', 'mixed']);
 export const ROUTE_RIGOR_LEVELS = new Set(['R0', 'R1', 'R2', 'R3', 'R4']);
 export const ROUTE_MODEL_TIERS = new Set(['lite', 'code', 'smart']);
 export const ROUTE_RISK_FLOORS = new Set(['none', 'high-risk']);
+export const ROUTE_EFFORTS = new Set(['low', 'medium', 'high']);
 // SPEC §5 FR-003: fixed table order — codes are emitted and printed in this order.
 // The first six raise the floor to 'high-risk'; the last two are informational only.
 export const ROUTE_RISK_REASON_CODES = Object.freeze([
@@ -354,6 +355,37 @@ function formatRiskFloorSegment(riskFloor = null) {
   return printed.length > 0 ? `risk=${riskFloor.floor}(${printed.join(',')})` : null;
 }
 
+// FR-001 (M01.2' limits fragment): compile the contract's numeric budget keys
+// into an advisory map. Only finite numbers survive — a non-numeric or missing
+// key is simply absent. Zero is a real budget ("no read passes"), never
+// filtered. Same key set as the ceremonyBudget.limits builder below.
+export function deriveCeremonyLimits(executionContract = null) {
+  if (executionContract === null || typeof executionContract !== 'object') {
+    return {};
+  }
+  return Object.fromEntries(
+    ['maxReadPasses', 'maxContextPulls', 'maxReadPassesBeforeReassess']
+      .filter((key) => Number.isFinite(executionContract[key]))
+      .map((key) => [key, executionContract[key]]),
+  );
+}
+
+// Route-line segment (FR-002): fixed reads,ctx,reassess order; only present
+// keys print. Empty/absent map → null so the segment never appears.
+export function formatLimitsSegment(limits = null) {
+  if (limits === null || typeof limits !== 'object') {
+    return null;
+  }
+  const parts = [
+    ['reads', 'maxReadPasses'],
+    ['ctx', 'maxContextPulls'],
+    ['reassess', 'maxReadPassesBeforeReassess'],
+  ]
+    .filter(([, key]) => Number.isFinite(limits[key]))
+    .map(([label, key]) => `${label}:${limits[key]}`);
+  return parts.length > 0 ? `limits=${parts.join(',')}` : null;
+}
+
 // FR-004 (M01.3'): Fast Path eligibility predicate. Returns null when no riskFloor
 // was supplied — eligibility must never be derived without the floor check, so a
 // missing floor means "not computed", not "none". Eligible iff the lane is
@@ -460,6 +492,10 @@ function buildResolvedRouteFields({
   completionState = null,
   riskFloor = null,
 } = {}) {
+  // Decision table v2 (FR-001/FR-002): tier + effort resolve together from the
+  // contract lane and the additive riskFloor. The router cannot observe host
+  // binding capabilities, so the emitted pair is advisory text by definition.
+  const tierDecision = resolveModelTier({ executionMode, riskFloor });
   const signalText = buildNormalizedRouteSignalText(routingContext.promptText, routingContext.commandText);
   const deliveryOnly = isDeliveryOnlyRequest({
     signalText,
@@ -484,7 +520,8 @@ function buildResolvedRouteFields({
       riskFloor: riskFloor?.floor ?? null,
       phase: null,
       contractVersion: ROUTE_CONTRACT_VERSION,
-      modelTier: executionContract?.modelTier ?? null,
+      modelTier: tierDecision.tier,
+      effort: tierDecision.effort,
     },
     evidence: {
       observations: [],
@@ -567,6 +604,10 @@ export function validateResolvedRoute(route = null) {
     if (route.execution.modelTier !== null && !ROUTE_MODEL_TIERS.has(route.execution.modelTier)) {
       errors.push(`execution.modelTier must be null or one of: ${[...ROUTE_MODEL_TIERS].join(', ')}.`);
     }
+    if (route.execution.effort !== null && route.execution.effort !== undefined
+      && !ROUTE_EFFORTS.has(route.execution.effort)) {
+      errors.push(`execution.effort must be null or one of: ${[...ROUTE_EFFORTS].join(', ')}.`);
+    }
   }
   if (!isObject(route.evidence)) {
     errors.push('evidence must be an object.');
@@ -2879,6 +2920,12 @@ function buildRouteSummary({
       })
     : null;
   const riskSegment = formatRiskFloorSegment(riskFloor);
+  // FR-003 (M01.2' limits fragment): the rigor advisory — emitted whenever
+  // rigor.stage is on, independent of fastPath/escalation. Stage off → no
+  // segment, byte-identical route.
+  const limitsSegment = resolveRouteStage(runtimeConfig, 'rigor') !== 'off'
+    ? formatLimitsSegment(deriveCeremonyLimits(executionContract))
+    : null;
   // FR-004 (M01.3'): fastPath is emitted whenever its own stage is on — the field
   // is always set then (eligible or not) so telemetry/harness can read it; the
   // route-line segment prints only for eligible routes.
@@ -2951,6 +2998,7 @@ function buildRouteSummary({
     formatCompactSegment('styles', styleFiles),
     editGuardHint ? `editGuard=${editGuardHint}` : null,
     riskSegment,
+    limitsSegment,
     fastPathSegment,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
@@ -3442,6 +3490,45 @@ function buildExecutionContract(executionMode = null) {
   return contracts[executionMode] ? { ...contracts[executionMode] } : null;
 }
 
+// Decision table v2 (V3_RESHAPE §5): the contracts table's modelTier column is the
+// base row; resolveModelTier adds the (riskFloor, hostCapabilities) columns.
+// Deterministic — no registry, no leases, no outbound capability calls.
+// Literal mirror of src/core/executionContracts.js resolveModelTier; parity is
+// locked by tests/consistency/executionContractSync.test.js.
+const MODEL_TIER_ORDER = ['lite', 'code', 'smart'];
+const MODEL_TIER_EFFORT = {
+  lite: 'low',
+  code: 'medium',
+  smart: 'high',
+};
+
+/**
+ * Resolves {tier, effort, advisoryOnly} for a route. A 'high-risk' floor escalates
+ * the tier one band (lite→code→smart, capped at smart) and forces effort 'high'.
+ * Unknown mode → {tier:null, effort:null, advisoryOnly:true}. Missing/unknown
+ * riskFloor → 'none'. Missing hostCapabilities → advisoryOnly:true (the route text
+ * is all the host gets when it cannot bind model and effort).
+ */
+export function resolveModelTier({
+  executionMode = null,
+  riskFloor = null,
+  hostCapabilities = null,
+} = {}) {
+  const baseTier = buildExecutionContract(executionMode)?.modelTier ?? null;
+  if (!baseTier) {
+    return { tier: null, effort: null, advisoryOnly: true };
+  }
+  const highRisk = riskFloor?.floor === 'high-risk';
+  const tier = highRisk
+    ? MODEL_TIER_ORDER[Math.min(MODEL_TIER_ORDER.indexOf(baseTier) + 1, MODEL_TIER_ORDER.length - 1)]
+    : baseTier;
+  return {
+    tier,
+    effort: highRisk ? 'high' : MODEL_TIER_EFFORT[tier],
+    advisoryOnly: !(hostCapabilities?.canBindModel === true && hostCapabilities?.canBindEffort === true),
+  };
+}
+
 function buildApproachSelectorResult({
   executionMode = null,
   executionScores = null,
@@ -3726,7 +3813,8 @@ export function computeRiskEscalation({
   previousRouteSummary = null,
   config = null,
 } = {}) {
-  if (resolveRouteStage(config, 'escalation') === 'off') {
+  const stage = resolveRouteStage(config, 'escalation');
+  if (stage === 'off') {
     return null;
   }
   const sourceFlags = config?.routing?.escalation?.sources ?? {};
@@ -3747,7 +3835,7 @@ export function computeRiskEscalation({
   const level = RISK_ESCALATION_LEVELS[derivedLevel] >= previousLevel
     ? derivedLevel
     : previous.level;
-  return { level, sources };
+  return { level, sources, stage };
 }
 
 // FR-005: buildRouteSummary runs before riskEscalation exists, so the