@ngockhoale/ukit 3.4.46 → 3.4.48

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

@@ -0,0 +1,704 @@
+// playbook-execution.mjs — Round 5 vertical slice: the feature-implementation
+// Playbook as an executable lifecycle (step contract → worker handback →
+// integration verification → review obligation → final acceptance).
+//
+// Pure and deterministic: no ledger I/O, no route reads, no config. The ledger
+// (execution-ledger.mjs) owns persistence and calls these functions at receipt-
+// fold time and at evaluation time; this module never imports the ledger or
+// `index/` (runtime must not static-import index/). Text is never proof: a
+// worker's reply can only be a CLAIM; evidence is the attributed receipts the
+// hook layer recorded (write / verification / source with `agentId`).
+
+import crypto from 'node:crypto';
+import fsSync from 'node:fs';
+import path from 'node:path';
+
+export const FEATURE_PLAYBOOK_ID = 'feature-implementation';
+// Refused main-thread source writes (delegation-gate.mjs) before the run ends as BLOCKED.
+export const DELEGATION_VIOLATION_LIMIT = 3;
+
+// ─── Phase 1: the step contract ─────────────────────────────────────────────
+// ONE registry. execution-ledger.mjs builds its PLAYBOOK_STEP_MAPS entry from
+// this list (conditional steps are filtered out of the unconditional trace), so
+// the step ids/essentiality exist in exactly one place. `mdStep` is the ordinal
+// of the numbered step in playbooks/feature-implementation.md the runtime step
+// realises (null = runtime-only); `mdAnchor` is a word that ordinal must still
+// contain — a drift test fails when the prose is reordered under the map.
+//
+// derive      how buildPlaybookTrace proves it from receipts (existing tokens)
+//             or 'integration' / 'review' for the conditional runtime steps.
+// conditional null = always required; 'delegated' = required once an executor
+//             worker handed back; 'review-required' = required when the review
+//             policy demands an independent review.
+// role/tier   who performs it: executor→code(Tier 2), orchestrator/reviewer→smart(Tier 3).
+// complexity  reasoning complexity of the step; effort is derived from it
+//             (resolveStepEffort) — never from risk and never from tier.
+// delegation  'optional' | 'preferred' | 'never' | 'required'.
+// A worker may execute several compatible steps in one dispatch.
+export const FEATURE_IMPLEMENTATION_STEPS = Object.freeze([
+  Object.freeze({
+    id: 'analog-search', derive: 'pre-source', essential: false, conditional: null,
+    mdStep: 2, mdAnchor: 'analog', role: 'executor', tier: 'code', complexity: 'low', effort: 'medium',
+    delegation: 'optional', dependsOn: Object.freeze([]), evidence: 'source-receipt',
+    acceptance: 'an existing analog was read before the first write, or the skip is justified',
+  }),
+  Object.freeze({
+    id: 'implement', derive: 'write', essential: true, conditional: null,
+    mdStep: 4, mdAnchor: 'implement', role: 'executor', tier: 'code', complexity: 'medium', effort: 'medium',
+    delegation: 'preferred', dependsOn: Object.freeze(['analog-search']), evidence: 'write-receipt',
+    acceptance: 'a successful product write exists for the change',
+  }),
+  Object.freeze({
+    id: 'verify', derive: 'post-verify', essential: true, conditional: null,
+    mdStep: 5, mdAnchor: 'verify', role: 'executor', tier: 'code', complexity: 'low', effort: 'medium',
+    delegation: 'optional', dependsOn: Object.freeze(['implement']), evidence: 'verification-receipt',
+    acceptance: 'a passing verification ran after the first write',
+  }),
+  Object.freeze({
+    id: 'integrate-verify', derive: 'integration', essential: true, conditional: 'delegated',
+    mdStep: null, mdAnchor: null, role: 'orchestrator', tier: 'smart', complexity: 'medium', effort: 'medium',
+    delegation: 'never', dependsOn: Object.freeze(['implement', 'verify']), evidence: 'integration-verification',
+    acceptance: 'a passing verification ran in the integrated session state after every worker change and handback',
+  }),
+  Object.freeze({
+    id: 'review', derive: 'review', essential: true, conditional: 'review-required',
+    mdStep: null, mdAnchor: null, role: 'reviewer', tier: 'smart', complexity: 'medium', effort: 'medium',
+    delegation: 'required', dependsOn: Object.freeze(['integrate-verify']), evidence: 'review-verdict',
+    acceptance: 'an independent reviewer approved the current diff against the request and the verification evidence',
+  }),
+]);
+
+// Numbered steps of the prose with no runtime step above, classified once (no receipt is minted
+// for prose). guidance = no verifiable artifact: reported, never blocks. conditional = mandatory
+// once the route requires `evidence`, proven by that EXISTING evidence predicate.
+export const FEATURE_UNMAPPED_MD_STEPS = Object.freeze([
+  Object.freeze({ mdStep: 1, mdAnchor: 'predicate', class: 'guidance', basis: 'its checkable form is the route completion contract, enforced through steps 4/5; "stated before code" has no receipt' }),
+  Object.freeze({ mdStep: 3, mdAnchor: 'data shape', class: 'guidance', basis: 'a design act with no artifact the runtime can observe' }),
+  Object.freeze({ mdStep: 6, mdAnchor: 'impact', class: 'conditional', evidence: 'impact-evidence', basis: 'mandatory when the route contract demands impact-evidence (map-impact); otherwise the route named no surface' }),
+]);
+// Unnumbered prose paragraphs: constraints/guidance only.
+export const FEATURE_PROSE_GUIDANCE = Object.freeze(['reference reuse', 'reuse-first', 'clone', 'reply:', 'ask the human only']);
+
+// Logical tier an agent is bound to (its `model:` frontmatter). A drift test
+// pins this against .claude/agents/*.md so the map cannot silently diverge.
+export const LOGICAL_TIER_BY_AGENT = Object.freeze({
+  'feature-implementer': 'code',
+  'bug-debugger': 'code',
+  'ukit-small-task-maintainer': 'lite',
+  'code-reviewer': 'smart',
+  'handoff-planner': 'smart',
+  'ukit-vision-analyst': 'vision',
+});
+
+export const ROLE_BY_AGENT = Object.freeze({
+  'feature-implementer': 'executor',
+  'bug-debugger': 'executor',
+  'code-reviewer': 'reviewer',
+  'ukit-small-task-maintainer': 'support',
+  'handoff-planner': 'planner',
+  'ukit-vision-analyst': 'support',
+});
+
+// Whether a per-dispatch reasoning-effort parameter can actually be bound on a
+// host. Claude Code's Agent tool and OMP's task tool accept it; Codex has no
+// per-subagent knob. 'high' is requested ONLY where it can be bound.
+export const HOST_EFFORT_BINDING = Object.freeze({ 'claude-code': 'dispatch-param', omp: 'dispatch-param', codex: 'none' });
+
+export function normalizeHost(harness) {
+  const text = String(harness || '').toLowerCase();
+  if (text.includes('omp') || text.includes('oh-my-pi')) return 'omp';
+  if (text.includes('codex')) return 'codex';
+  return 'claude-code';
+}
+
+/** Steps active for this run: unconditional ones plus the conditional ones whose condition holds. */
+export function activeFeatureSteps({ delegated = false, reviewRequired = false } = {}) {
+  return FEATURE_IMPLEMENTATION_STEPS.filter((step) => step.conditional === null
+    || (step.conditional === 'delegated' && delegated)
+    || (step.conditional === 'review-required' && reviewRequired));
+}
+
+/**
+ * Effort for a step. Medium by default; High only with justified complexity
+ * (the step's own, the route's complexity evidence, or verified failure
+ * evidence) AND native host support. Risk and tier never raise effort.
+ */
+export function resolveStepEffort(step, { host = 'claude-code', complexityHigh = false, failures = 0 } = {}) {
+  const justified = step?.complexity === 'high' || complexityHigh === true || Number(failures) >= 2;
+  const binding = HOST_EFFORT_BINDING[normalizeHost(host)] || 'none';
+  if (!justified) return { effort: 'medium', binding, justified: false, suppressed: false };
+  if (binding === 'none') return { effort: 'medium', binding, justified: true, suppressed: true };
+  return { effort: 'high', binding, justified: true, suppressed: false };
+}
+
+// ─── Phase 2: the trusted handback ──────────────────────────────────────────
+const TASK_MARKER_RE = /\[ukit-task\s+([A-Za-z0-9._-]{1,96})\]/;
+const STEPS_MARKER_RE = /\[ukit-steps\s+([A-Za-z0-9_, -]{1,160})\]/;
+const SCOPE_MARKER_RE = /\[ukit-scope\s+([^\]]{1,480})\]/;
+const SUBTASK_RE = /\[ukit-subtask\s+([A-Za-z0-9_-]+\.(?:\d+|integrate))\]/;
+const AGENT_ID_RE = /^[A-Za-z0-9_-]{4,96}$/;
+const VERDICT_RE = /\b(APPROVED-WITH-MINOR|APPROVED|CHANGES-REQUESTED|CRITICAL)\b/;
+export const REVIEW_VERDICTS = Object.freeze(['APPROVED', 'APPROVED-WITH-MINOR', 'CHANGES-REQUESTED', 'CRITICAL']);
+const APPROVING_VERDICTS = new Set(['APPROVED', 'APPROVED-WITH-MINOR']);
+const MAX_HANDBACKS = 16;
+const MAX_WORKERS = 12;
+const MAX_WORKER_FILES = 24;
+const MAX_WORKER_VERIFICATIONS = 6;
+
+export function sanitizeAgentId(value) {
+  return typeof value === 'string' && AGENT_ID_RE.test(value.trim()) ? value.trim() : null;
+}
+
+const str = (value, max) => (typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : null);
+const count = (value) => (Number.isFinite(Number(value)) && Number(value) >= 0 ? Math.trunc(Number(value)) : null);
+const sha = (text, len = 16) => crypto.createHash('sha256').update(String(text)).digest('hex').slice(0, len);
+
+function replyText(response) {
+  if (typeof response === 'string') return response;
+  if (!response || typeof response !== 'object') return '';
+  if (Array.isArray(response.content)) {
+    return response.content.map((part) => (typeof part === 'string' ? part : part?.text || '')).join('\n');
+  }
+  return [response.result, response.text, response.output].find((v) => typeof v === 'string') || '';
+}
+
+function listOf(raw, max, itemMax) {
+  return String(raw || '').split(',').map((v) => v.trim()).filter(Boolean).slice(0, max).map((v) => v.slice(0, itemMax));
+}
+
+function normalizePathEntry(entry, root) {
+  const text = String(entry || '').trim();
+  if (!text) return null;
+  const abs = path.isAbsolute(text) ? text : path.resolve(root || '.', text);
+  const rel = root ? path.relative(path.resolve(root), abs) : text;
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join('/').slice(0, 200);
+}
+
+/**
+ * Build the bounded handback record from an Agent/Task tool result. Returns
+ * null for a payload that is not a recognisable subagent dispatch. NOTHING in
+ * the reply text can mint evidence: `claimedPass` is derived from prose and is
+ * only ever a claim; `observed` stays null unless the response really carries it.
+ */
+export function buildHandbackRecord({ toolInput, toolResponse, projectRoot, success = true } = {}) {
+  let input = toolInput && typeof toolInput === 'object' && !Array.isArray(toolInput) ? toolInput : null;
+  if (!input) return null;
+  // omp `task` fan-out: {context, tasks:[{agent,name,task}]}. One agent type across all entries is
+  // one dispatch; a mixed fan-out is not recognisable. `name` (and the result's progress[].id,
+  // which echoes it) is chosen by the calling model — never an identity, never read as agentId.
+  if (Array.isArray(input.tasks) && input.tasks.length > 0 && !input.subagent_type && !input.agent) {
+    const agents = new Set(input.tasks.map((t) => str(t?.agent, 64)));
+    if (agents.size !== 1 || agents.has(null)) return null;
+    input = { agent: [...agents][0], prompt: [input.context, ...input.tasks.map((t) => t?.task)].filter((v) => typeof v === 'string').join('\n'), isolation: input.isolation };
+  }
+  const agentType = str(input.subagent_type ?? input.agent ?? input.agent_type, 64);
+  if (!agentType) return null;
+  const resp = toolResponse && typeof toolResponse === 'object' && !Array.isArray(toolResponse) ? toolResponse : {};
+  // OMP returns an asynchronous spawn ACK before the worker completes. Progress IDs
+  // echo caller-chosen names; neither they nor an empty results array are a handback.
+  const asyncState = resp.details?.async?.state ?? resp.async?.state;
+  if (/^(running|pending|queued|started)$/i.test(String(asyncState ?? ''))) return null;
+  const text = replyText(toolResponse);
+  const promptText = [input.prompt, input.description, input.task].filter((v) => typeof v === 'string').join('\n');
+  const agentIdRaw = str(resp.agentId ?? resp.agent_id, 96);
+  const agentId = agentIdRaw && AGENT_ID_RE.test(agentIdRaw) ? agentIdRaw : null;
+  const taskMarker = TASK_MARKER_RE.exec(promptText);
+  const stepsMarker = STEPS_MARKER_RE.exec(promptText);
+  const scopeMarker = SCOPE_MARKER_RE.exec(promptText);
+  const subtask = SUBTASK_RE.exec(promptText);
+  const role = ROLE_BY_AGENT[agentType] || 'support';
+  const failed = success !== true || resp.is_error === true || resp.isError === true
+    || /^(failed|error)$/i.test(String(resp.status || ''));
+  const usage = resp.usage && typeof resp.usage === 'object' ? resp.usage : null;
+  const tokenParts = {
+    input: count(usage?.input_tokens), output: count(usage?.output_tokens),
+    cacheRead: count(usage?.cache_read_input_tokens), cacheCreate: count(usage?.cache_creation_input_tokens),
+    total: count(resp.totalTokens ?? resp.total_tokens),
+  };
+  const hasTokens = Object.values(tokenParts).some((v) => v !== null);
+  let reviewVerdict = null;
+  let findings = [];
+  if (role === 'reviewer' && text) {
+    const labelled = /verdict\W{0,6}(APPROVED-WITH-MINOR|APPROVED|CHANGES-REQUESTED|CRITICAL)/i.exec(text);
+    reviewVerdict = labelled ? labelled[1].toUpperCase() : (VERDICT_RE.exec(text)?.[1] ?? null);
+    findings = text.split(/\r?\n/).map((line) => /^\s*[-*]\s+(.{4,})$/.exec(line)?.[1]).filter(Boolean)
+      .slice(0, 5).map((line) => line.trim().slice(0, 160));
+  }
+  const root = projectRoot ? path.resolve(projectRoot) : null;
+  return {
+    agentId,
+    agentType,
+    subtaskId: subtask ? subtask[1] : null,
+    logicalTier: LOGICAL_TIER_BY_AGENT[agentType] || null,
+    role,
+    // 'native' only when the host returned a real agent id AND later receipts can carry it
+    // (Claude Code stamps agent_id on subagent tool payloads). Otherwise nothing a worker
+    // did is attributable to it — reported, never guessed.
+    attribution: agentId ? 'native' : 'unsupported',
+    taskBinding: taskMarker ? 'marker' : 'live-state',
+    markerTaskId: taskMarker ? taskMarker[1] : null,
+    assignedSteps: stepsMarker ? listOf(stepsMarker[1], 8, 40) : [],
+    scope: scopeMarker ? listOf(scopeMarker[1], 8, 160).map((e) => normalizePathEntry(e, root)).filter(Boolean) : [],
+    isolated: input.isolation === 'worktree',
+    outcome: failed ? 'failed' : 'completed',
+    claimedPass: !failed && /\b(pass(ed|es|ing)?|all green|verified|status:\s*done)\b/i.test(text.slice(-2400)),
+    requested: { model: str(input.model, 64), effort: str(input.effort ?? input.reasoning_effort, 16) },
+    observed: { model: str(resp.model, 64), effort: str(resp.effort, 16) },
+    durationMs: count(resp.totalDurationMs ?? resp.total_duration_ms),
+    toolUses: count(resp.totalToolUseCount ?? resp.total_tool_use_count),
+    tokens: hasTokens ? { ...tokenParts, provenance: 'PROVIDER' } : null,
+    reviewVerdict,
+    findings,
+    digest: sha(`${agentType}\n${String(input.prompt || '').slice(0, 2000)}\n${String(input.description || '')}`),
+  };
+}
+
+/** Re-validates a persisted/journaled handback; unknown shapes yield null. */
+export function sanitizeHandback(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const agentType = str(raw.agentType, 64);
+  if (!agentType) return null;
+  const list = (v, max, itemMax) => (Array.isArray(v) ? v.filter((e) => typeof e === 'string').slice(0, max).map((e) => e.slice(0, itemMax)) : []);
+  const tokens = raw.tokens && typeof raw.tokens === 'object' ? {
+    input: count(raw.tokens.input), output: count(raw.tokens.output), cacheRead: count(raw.tokens.cacheRead),
+    cacheCreate: count(raw.tokens.cacheCreate), total: count(raw.tokens.total),
+    provenance: raw.tokens.provenance === 'PROVIDER' ? 'PROVIDER' : 'UNKNOWN',
+  } : null;
+  return {
+    agentId: str(raw.agentId, 96) && AGENT_ID_RE.test(raw.agentId) ? raw.agentId : null,
+    agentType,
+    subtaskId: str(raw.subtaskId, 80),
+    logicalTier: LOGICAL_TIER_BY_AGENT[agentType] || null,
+    role: ROLE_BY_AGENT[agentType] || 'support',
+    attribution: raw.attribution === 'native' && raw.agentId ? 'native' : 'unsupported',
+    taskBinding: raw.taskBinding === 'marker' ? 'marker' : 'live-state',
+    assignedSteps: list(raw.assignedSteps, 8, 40),
+    scope: list(raw.scope, 8, 200),
+    isolated: raw.isolated === true,
+    outcome: raw.outcome === 'failed' ? 'failed' : 'completed',
+    claimedPass: raw.claimedPass === true,
+    requested: { model: str(raw.requested?.model, 64), effort: str(raw.requested?.effort, 16) },
+    observed: { model: str(raw.observed?.model, 64), effort: str(raw.observed?.effort, 16) },
+    durationMs: count(raw.durationMs),
+    toolUses: count(raw.toolUses),
+    tokens,
+    reviewVerdict: REVIEW_VERDICTS.includes(raw.reviewVerdict) ? raw.reviewVerdict : null,
+    findings: list(raw.findings, 5, 160),
+    digest: str(raw.digest, 32),
+  };
+}
+
+// ─── The run fold (persisted on the ledger as `playbookRun`) ────────────────
+export function emptyPlaybookRun() {
+  return { changeSeq: 0, lastExecutorHandbackSeq: 0, inlineWrites: 0, duplicates: 0, handbacks: [], workers: {}, integration: null, reviewer: null, reviewDecision: null };
+}
+
+function ensureWorker(run, agentId, seq) {
+  if (!run.workers[agentId]) {
+    const keys = Object.keys(run.workers);
+    if (keys.length >= MAX_WORKERS) delete run.workers[keys[0]];
+    run.workers[agentId] = { files: {}, verifications: [], sources: 0, failures: 0, firstSeq: seq, lastSeq: seq };
+  }
+  return run.workers[agentId];
+}
+
+/** Stable fingerprint of what a worker changed: sha over sorted `file:contentSha`. */
+export function workerChangeFingerprint(worker) {
+  const files = worker?.files && typeof worker.files === 'object' ? worker.files : {};
+  const keys = Object.keys(files).sort();
+  return keys.length ? sha(keys.map((k) => `${k}:${files[k] || ''}`).join('\n')) : null;
+}
+
+/**
+ * Fold one receipt into the run. `seq` is the ledger receiptSequence this
+ * receipt was applied at; `bookkeeping` marks a WORKLOG/STATUS-style write that
+ * never invalidates verification. Pure: returns a new run, never mutates.
+ */
+export function foldPlaybookRun(previous, receipt, { seq, bookkeeping = false } = {}) {
+  const run = previous && typeof previous === 'object'
+    ? { ...emptyPlaybookRun(), ...previous, handbacks: [...(previous.handbacks || [])], workers: { ...(previous.workers || {}) } }
+    : emptyPlaybookRun();
+  const ok = receipt?.success === true;
+  if (receipt?.kind === 'write') {
+    if (ok && !bookkeeping) run.changeSeq = seq;
+    if (typeof receipt.agentId === 'string' && receipt.agentId) {
+      const worker = { ...ensureWorker(run, receipt.agentId, seq) };
+      worker.files = { ...worker.files };
+      worker.lastSeq = seq;
+      if (ok && receipt.file && !bookkeeping && String(receipt.file).startsWith('bash-workspace:')) {
+        worker.bash = (worker.bash || 0) + 1; // a Bash-made change: real, but names no file
+      } else if (ok && receipt.file && !bookkeeping) {
+        if (worker.files[receipt.file] !== undefined || Object.keys(worker.files).length < MAX_WORKER_FILES) {
+          worker.files[String(receipt.file).slice(0, 200)] = typeof receipt.contentSha === 'string' ? receipt.contentSha.slice(0, 16) : null;
+        }
+      } else if (!ok) worker.failures += 1;
+      run.workers[receipt.agentId] = worker;
+    } else if (ok && !bookkeeping) {
+      run.inlineWrites += 1;
+    }
+  } else if (receipt?.kind === 'source') {
+    if (ok && typeof receipt.agentId === 'string' && receipt.agentId) {
+      const worker = { ...ensureWorker(run, receipt.agentId, seq) };
+      worker.sources += 1;
+      worker.lastSeq = seq;
+      run.workers[receipt.agentId] = worker;
+    }
+  } else if (receipt?.kind === 'verification') {
+    if (typeof receipt.agentId === 'string' && receipt.agentId) {
+      const worker = { ...ensureWorker(run, receipt.agentId, seq) };
+      worker.verifications = [...worker.verifications,
+        { command: String(receipt.command || '').slice(0, 120), success: ok, seq }].slice(-MAX_WORKER_VERIFICATIONS);
+      if (!ok) worker.failures += 1;
+      worker.lastSeq = seq;
+      run.workers[receipt.agentId] = worker;
+    } else if (!receipt.workspaceRoot) {
+      // A verification in the session root, by the orchestrator: the only kind of
+      // receipt that can become integration evidence. Whether it is CURRENT is
+      // decided at assessment time against changeSeq / lastExecutorHandbackSeq.
+      const kind = receipt.verdict?.kind;
+      if (ok && (kind === 'test-verified' || kind === 'live-verified')) {
+        run.integration = { status: 'verified', atSeq: seq, command: String(receipt.command || '').slice(0, 160), verdictKind: kind, verdict: receipt.verdict, ts: receipt.ts ?? null };
+      } else if (!ok) {
+        run.integration = { status: 'failed', atSeq: seq, command: String(receipt.command || '').slice(0, 160), ts: receipt.ts ?? null };
+      }
+    }
+  } else if (receipt?.kind === 'handback') {
+    const handback = sanitizeHandback(receipt.handback);
+    if (!handback) return run;
+    const key = receipt.toolUseId ? `t:${receipt.toolUseId}` : `d:${handback.digest || ''}:${handback.agentId || ''}`;
+    if (run.handbacks.some((entry) => entry.key === key)) {
+      run.duplicates += 1; // repeated delivery of the same result is a no-op
+      return run;
+    }
+    const worker = handback.agentId ? run.workers[handback.agentId] : null;
+    run.handbacks = [...run.handbacks, {
+      ...handback, key, seq, ts: receipt.ts ?? null,
+      changeFp: workerChangeFingerprint(worker),
+      workspaceFp: typeof receipt.workspaceFp === 'string' ? receipt.workspaceFp.slice(0, 64) : null,
+    }].slice(-MAX_HANDBACKS);
+    if (handback.role === 'executor') run.lastExecutorHandbackSeq = seq;
+    if (handback.role === 'reviewer') {
+      run.reviewer = { verdict: handback.reviewVerdict, findings: handback.findings, seq, agentId: handback.agentId, outcome: handback.outcome };
+    }
+  } else if (receipt?.kind === 'review') {
+    const decision = receipt.review && typeof receipt.review === 'object' ? receipt.review : null;
+    if (decision) {
+      run.reviewDecision = {
+        action: str(decision.action, 32), namedCheck: str(decision.namedCheck, 200),
+        signalsHit: Array.isArray(decision.signalsHit) ? decision.signalsHit.filter((s) => typeof s === 'string').slice(0, 8).map((s) => s.slice(0, 60)) : [],
+        round: count(decision.round) ?? 0, atSeq: seq,
+      };
+    }
+  }
+  return run;
+}
+
+// ─── Phase 2/3: worker + integration assessment ─────────────────────────────
+function inScope(file, scope) {
+  if (!Array.isArray(scope) || scope.length === 0) return true;
+  return scope.some((entry) => file === entry || file.startsWith(`${entry.replace(/\/+$/, '')}/`));
+}
+
+/** Per executor-handback: is the worker's work EVIDENCED by attributed receipts, or only claimed? */
+export function assessWorkers(run) {
+  const handbacks = (run?.handbacks || []).filter((h) => h.role === 'executor');
+  const workers = handbacks.map((h) => {
+    const worker = h.agentId ? run.workers?.[h.agentId] : null;
+    // Only Edit/Write receipts name the file they changed. A Bash-made change (heredoc, redirect, sed -i,
+    // script) is an anonymous workspace delta: it proves SOMETHING changed, never what or by which tool
+    // input, so it cannot stand as a worker's attributed write.
+    const writes = worker ? Object.keys(worker.files || {}).length : 0;
+    const bashWrites = worker ? worker.bash || 0 : 0;
+    const passes = worker ? (worker.verifications || []).filter((v) => v.success).length : 0;
+    const readOnlySteps = h.assignedSteps.length > 0 && h.assignedSteps.every((id) => id === 'analog-search');
+    let state;
+    if (h.outcome === 'failed') state = 'failed';
+    else if (h.isolated) state = 'isolated-unobserved';
+    else if (h.attribution !== 'native') state = 'unobservable';
+    else if (writes === 0 && bashWrites > 0) state = 'bash-unattributed';
+    else if (writes > 0 || passes > 0 || (readOnlySteps && worker?.sources > 0)) state = 'evidenced';
+    else state = 'claim-only';
+    const outOfScope = worker ? Object.keys(worker.files || {}).filter((f) => !inScope(f, h.scope)) : [];
+    return { agentId: h.agentId, agentType: h.agentType, state, writes, claimedPass: h.claimedPass, outOfScope, failures: worker?.failures || 0 };
+  });
+  const count = (state) => workers.filter((w) => w.state === state).length;
+  return {
+    workers,
+    total: workers.length,
+    evidenced: workers.length > 0 && workers.every((w) => w.state === 'evidenced'),
+    claimOnly: count('claim-only'),
+    bashUnattributed: count('bash-unattributed'),
+    unobservable: count('unobservable') + count('isolated-unobserved'),
+    failed: count('failed'),
+    outOfScope: workers.flatMap((w) => w.outOfScope),
+    retries: workers.filter((w) => w.state === 'failed').length,
+  };
+}
+
+/** Sequential vs concurrent from handback intervals [ts - durationMs, ts]; 'unknown' without durations. */
+export function executionMode(run) {
+  const items = (run?.handbacks || []).filter((h) => h.role === 'executor');
+  if (items.length === 0) return 'none';
+  if (items.length === 1) return 'single';
+  if (items.some((h) => h.durationMs === null || !Number.isFinite(h.ts))) return 'unknown';
+  const spans = items.map((h) => [h.ts - h.durationMs, h.ts]).sort((a, b) => a[0] - b[0]);
+  for (let i = 1; i < spans.length; i += 1) if (spans[i][0] < spans[i - 1][1]) return 'concurrent';
+  return 'sequential';
+}
+
+/**
+ * Integration state of the run. Worker PASS and Integration PASS are separate
+ * facts: integration is `verified` only when a passing, current verification ran
+ * in the session root AFTER the last change (any actor) and the last executor
+ * handback, with every worker-written file present and un-contested.
+ */
+export function assessIntegration(run, { cwd, verdictCurrent = null } = {}) {
+  const executors = (run?.handbacks || []).filter((h) => h.role === 'executor');
+  const reasons = [];
+  if (executors.length === 0) return { delegated: false, status: 'not-applicable', reasons, missing: [], conflicts: [] };
+  const writers = new Map();
+  for (const [agentId, worker] of Object.entries(run.workers || {})) {
+    for (const file of Object.keys(worker.files || {})) writers.set(file, [...(writers.get(file) || []), agentId]);
+  }
+  const missing = [];
+  if (cwd) {
+    for (const file of writers.keys()) {
+      try { if (!fsSync.statSync(path.resolve(cwd, file)).isFile()) missing.push(file); } catch { missing.push(file); }
+    }
+  }
+  const conflicts = [...writers.entries()].filter(([, ids]) => new Set(ids).size > 1).map(([file]) => file);
+  const barrier = Math.max(Number(run.changeSeq || 0), Number(run.lastExecutorHandbackSeq || 0));
+  const integration = run.integration;
+  let status;
+  if (conflicts.length) { status = 'conflict'; reasons.push(`conflicting-worker-writes:${conflicts.slice(0, 3).join(',')}`); }
+  else if (missing.length) { status = 'missing'; reasons.push(`missing-from-integration:${missing.slice(0, 3).join(',')}`); }
+  else if (!integration) { status = 'pending'; reasons.push('no-integration-verification'); }
+  else if (integration.status === 'failed') {
+    if (integration.atSeq > barrier) { status = 'failed'; reasons.push('integration-verification-failed'); }
+    else { status = 'pending'; reasons.push('failed-verification-predates-latest-change'); }
+  } else if (integration.atSeq <= Number(run.lastExecutorHandbackSeq || 0)) {
+    status = 'stale'; reasons.push('verification-predates-integrated-changes');
+  } else if (integration.atSeq <= Number(run.changeSeq || 0)) {
+    status = 'stale'; reasons.push('edited-after-verification');
+  } else if (typeof verdictCurrent === 'function' && integration.verdict
+    && verdictCurrent(integration.verdict, { cwd }).current !== true) {
+    status = 'stale'; reasons.push('source-state-changed-since-verification');
+  } else status = 'verified';
+  return { delegated: true, status, reasons, missing, conflicts, verifiedAtSeq: integration?.atSeq ?? null, command: integration?.command ?? null };
+}
+
+// ─── Phase 4: review inputs and obligation ──────────────────────────────────
+/**
+ * Pure mapping from run facts to the EXISTING review policy's inputs. This
+ * module decides nothing: stop-coordinator merges these into its single
+ * evaluateReviewPolicy call (no second decision plane). Non-delegated runs
+ * return {applicable:false} and the policy sees exactly what it saw before.
+ */
+export function playbookReviewInputs({ run, workers, integration, riskHigh = false, routeFixLoopCount = 0 } = {}) {
+  if (!integration?.delegated) return { applicable: false, signals: {}, doneCriteria: [], fixLoopCount: 0, escalationDepth: null };
+  const workerStatus = workers.total === 0 ? 'missing'
+    : workers.evidenced ? 'verified'
+      : workers.claimOnly > 0 ? 'claimed' : 'missing';
+  const integrationStatus = integration.status === 'verified' ? 'verified'
+    : integration.status === 'pending' && run?.integration == null ? 'missing' : 'claimed';
+  const signals = {};
+  if (workers.outOfScope.length > 0) signals['wider-than-goal'] = true;
+  if (integration.conflicts.length > 0 || integration.missing.length > 0) signals['unconfirmed-assumptions'] = true;
+  if ((run?.workers && Object.values(run.workers).reduce((n, w) => n + (w.failures || 0), 0)) >= 3) signals['tool-error-storm'] = true;
+  return {
+    applicable: true,
+    signals,
+    doneCriteria: [
+      { name: 'worker-execution', status: workerStatus },
+      { name: 'integration-verification', status: integrationStatus },
+    ],
+    fixLoopCount: Math.max(Number(routeFixLoopCount) || 0, workers.retries),
+    escalationDepth: riskHigh ? 'review-round' : null,
+  };
+}
+
+/** Dispatch hint for the existing reviewer agent. Effort High only with justified evidence + native support. */
+export function reviewDispatchHint({ decision, workers, integration, host = 'claude-code', riskHigh = false } = {}) {
+  if (decision?.action !== 'independent-review') return null;
+  const suspicious = Array.isArray(decision.signalsHit) && decision.signalsHit.length > 0;
+  const justified = workers.retries >= 2 || (suspicious && (riskHigh || integration.status === 'conflict' || integration.status === 'missing'));
+  const { effort } = resolveStepEffort({ complexity: justified ? 'high' : 'medium' }, { host });
+  return {
+    subagent_type: 'code-reviewer',
+    effort,
+    reason: (decision.namedCheck || 'independent review required by the review policy').slice(0, 240),
+    brief: 'Check (1) the original request, (2) the actual diff of the integrated state, (3) the integration verification evidence. Reply with a Verdict line: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL.',
+  };
+}
+
+/**
+ * Is the review obligation satisfied? finish → not required; run-targeted-check
+ * → pending (a later decision must say finish); independent-review → needs a
+ * reviewer handback with an approving verdict AFTER the last change; escalate →
+ * unsatisfied; inconclusive (round cap) → unverified, never a pass.
+ */
+export function reviewObligation(run, decision) {
+  const action = decision?.action ?? null;
+  if (!action || action === 'finish') return { required: false, satisfied: true, state: 'not-required' };
+  if (action === 'run-targeted-check') return { required: true, satisfied: false, state: 'targeted-check-pending' };
+  if (action === 'escalate') return { required: true, satisfied: false, state: 'escalated' };
+  if (action === 'inconclusive') return { required: true, satisfied: false, state: 'inconclusive' };
+  const reviewer = run?.reviewer;
+  if (reviewer && reviewer.outcome === 'completed' && APPROVING_VERDICTS.has(reviewer.verdict)
+    && reviewer.seq > Number(run.changeSeq || 0)) {
+    return { required: true, satisfied: true, state: 'approved', verdict: reviewer.verdict };
+  }
+  if (reviewer && reviewer.seq > Number(run?.changeSeq || 0) && reviewer.verdict) {
+    return { required: true, satisfied: false, state: 'changes-requested', verdict: reviewer.verdict };
+  }
+  return { required: true, satisfied: false, state: reviewer ? 'review-stale' : 'review-pending' };
+}
+
+// ─── Phase 5: final acceptance ──────────────────────────────────────────────
+/**
+ * The final Playbook verdict, one fact per obligation:
+ *   requiredSteps · workerExecution · integration · review · executor
+ * PASS only when every fact holds. A fact the engine cannot observe makes the
+ * verdict UNVERIFIED with the gap named in `unsupported` — never a silent PASS.
+ * NOT_APPLICABLE for any other playbook: their behaviour is unchanged.
+ */
+export function evaluatePlaybookAcceptance({
+  playbookId, missingSteps = [], requiredSteps = [], run = null, cwd, verdictCurrent = null,
+  reviewDecision = null, delegationRequired = false, host = 'claude-code', contractEvidence = null,
+  delegationBlocked = false,
+} = {}) {
+  if (playbookId !== FEATURE_PLAYBOOK_ID) return { applicable: false, delegated: false, verdict: 'NOT_APPLICABLE', facts: {}, reasons: [], unsupported: [] };
+  const integration = assessIntegration(run || emptyPlaybookRun(), { cwd, verdictCurrent });
+  const workers = assessWorkers(run || emptyPlaybookRun());
+  const delegated = integration.delegated;
+  const reasons = [];
+  const unsupported = [];
+  const attributionSupported = normalizeHost(host) === 'claude-code';
+  const facts = {
+    requiredSteps: { ok: missingSteps.length === 0, required: requiredSteps, missing: missingSteps },
+    workerExecution: { applicable: delegated, ok: !delegated || workers.evidenced, workers: workers.total, claimOnly: workers.claimOnly, unobservable: workers.unobservable, failed: workers.failed },
+    integration: { applicable: delegated, ok: !delegated || integration.status === 'verified', status: integration.status, reasons: integration.reasons },
+    review: { required: false, ok: true, state: 'not-required' },
+    executor: { required: delegationRequired === true, ok: true, inlineWrites: run?.inlineWrites || 0 },
+  };
+  if (missingSteps.length) reasons.push(`missing-required-step:${missingSteps.join(',')}`);
+  if (delegationBlocked) { facts.executor.ok = false; reasons.push('delegation-violation-blocked'); }
+  if (delegationRequired && (!delegated || normalizeHost(host) === 'omp')) {
+    // Inline writes are NEGATIVE evidence the orchestrator itself edited, and that holds on omp too:
+    // its ledgers are session-keyed and a worker runs in its OWN session (live: the main ledger held
+    // only the main's edit/bash calls, the worker's tool calls sat in the worker's ledger). What omp
+    // cannot do is prove POSITIVE worker attribution (no agent type / tool-call correlation reaches
+    // hooks), so absent inline writes it stays UNVERIFIED, never PASS.
+    if ((run?.inlineWrites || 0) > 0 && (attributionSupported || normalizeHost(host) === 'omp')) { facts.executor.ok = false; reasons.push('delegation-required-not-performed'); }
+    else if (!attributionSupported) unsupported.push('executor-attribution');
+  }
+  if (delegated) {
+    if (workers.claimOnly > 0) reasons.push('worker-claim-without-evidence');
+    if (workers.bashUnattributed > 0) reasons.push('worker-bash-write-unattributed');
+    if (workers.failed > 0 && !workers.evidenced) reasons.push('worker-failed');
+    if (workers.unobservable > 0) unsupported.push('worker-attribution');
+    if (!['verified'].includes(integration.status)) reasons.push(...integration.reasons.length ? integration.reasons : [`integration-${integration.status}`]);
+    const analysis = reviewObligation(run, reviewDecision);
+    facts.review = { required: analysis.required, ok: analysis.satisfied, state: analysis.state };
+    if (analysis.required && !analysis.satisfied) {
+      if (analysis.state === 'inconclusive') unsupported.push('review-inconclusive');
+      else reasons.push(`review-${analysis.state}`);
+    }
+  }
+  const verdictOf = () => (reasons.length > 0 ? 'NOT_PASS' : unsupported.length > 0 ? 'UNVERIFIED' : 'PASS');
+  const runtimeSlice = { verdict: verdictOf(), reasons: [...new Set(reasons)], unsupported: [...new Set(unsupported)] };
+  // Full-playbook scope: every contract evidence the route demanded must also be proven, and a
+  // conditional md step (6) that is active must be satisfied. An unknown contract = UNVERIFIED.
+  const required = Array.isArray(contractEvidence?.required) ? contractEvidence.required : null;
+  const missing = Array.isArray(contractEvidence?.missing) ? contractEvidence.missing : [];
+  const conditional = FEATURE_UNMAPPED_MD_STEPS.filter((m) => m.class === 'conditional').map((m) => {
+    const active = required ? required.includes(m.evidence) : null;
+    return { mdStep: m.mdStep, evidence: m.evidence, status: active === null ? 'unknown' : !active ? 'not-applicable' : missing.includes(m.evidence) ? 'missing' : 'verified' };
+  });
+  if (required === null) unsupported.push('contract-evidence-unknown');
+  if (missing.length) reasons.push(`contract-evidence-missing:${missing.join(',')}`);
+  facts.contractEvidence = { known: required !== null, required: required || [], missing };
+  const coverage = {
+    mapped: FEATURE_IMPLEMENTATION_STEPS.map((s) => s.id),
+    conditional,
+    guidance: FEATURE_UNMAPPED_MD_STEPS.filter((m) => m.class === 'guidance').map((m) => m.mdStep),
+    advisory: 'guidance steps carry no receipt; they never block and never count as verified',
+  };
+  return {
+    applicable: true, delegated, scope: 'full-playbook', verdict: verdictOf(), runtimeSlice, coverage, facts,
+    reasons: [...new Set(reasons)], unsupported: [...new Set(unsupported)],
+  };
+}
+
+/** One advisory line for the Stop message / status. Null when nothing to say. */
+export function formatAcceptance(acceptance) {
+  if (!acceptance?.applicable) return null;
+  if (!acceptance.delegated && !acceptance.reasons.includes('delegation-required-not-performed')) return null;
+  const parts = [`playbook acceptance: ${acceptance.verdict}${acceptance.runtimeSlice && acceptance.runtimeSlice.verdict !== acceptance.verdict ? ` (runtime slice: ${acceptance.runtimeSlice.verdict})` : ''}`];
+  if (acceptance.reasons.length) parts.push(`reasons: ${acceptance.reasons.slice(0, 4).join('; ')}`);
+  if (acceptance.unsupported.length) parts.push(`unsupported: ${acceptance.unsupported.join(', ')}`);
+  return parts.join(' — ');
+}
+
+// ─── Phase 6: minimal telemetry summary ─────────────────────────────────────
+/**
+ * Bounded, non-sensitive facts for the `outcome.observed` record: ids and
+ * counts only — no prompts, no file paths, no reply text. `observed` model /
+ * effort stay null unless the host response actually carried them.
+ */
+export function summarizePlaybookRun({ playbookId, taskInstanceId = null, trace = null, run = null, acceptance = null, reviewDecision = null, host = 'claude-code' } = {}) {
+  if (playbookId !== FEATURE_PLAYBOOK_ID || !acceptance?.applicable) return null;
+  const workers = assessWorkers(run || emptyPlaybookRun());
+  const handbacks = (run?.handbacks || []).filter((h) => h.role === 'executor');
+  const sum = (key) => handbacks.reduce((n, h) => n + (h.tokens?.[key] ?? 0), 0);
+  const withTokens = handbacks.filter((h) => h.tokens);
+  const first = handbacks[0] || null;
+  return {
+    playbookId,
+    taskInstanceId: taskInstanceId ? String(taskInstanceId).slice(0, 96) : null,
+    host: normalizeHost(host),
+    stepsRequired: Array.isArray(trace?.requiredSteps) ? trace.requiredSteps.length : 0,
+    stepsDone: Array.isArray(trace?.stepsDone) ? trace.stepsDone.length : 0,
+    workerCount: workers.total,
+    executionMode: executionMode(run),
+    requested: { tier: first?.logicalTier ?? null, model: first?.requested.model ?? null, effort: first?.requested.effort ?? null },
+    // requested = the dispatch parameters the caller passed; resolved = what UKit's step contract
+    // resolves for this host (a hint, not an observation); effective = only what the host response
+    // reported — UNKNOWN when it did not, UNSUPPORTED effort where the host has no per-dispatch knob.
+    resolved: (() => {
+      const r = resolveStepEffort(FEATURE_IMPLEMENTATION_STEPS.find((st) => st.id === 'implement'), { host, failures: workers.retries });
+      return { tier: 'code', effort: r.effort, effortBinding: r.binding };
+    })(),
+    observed: { model: first?.observed.model ?? null, effort: first?.observed.effort ?? null },
+    effective: {
+      model: first?.observed.model ?? 'UNKNOWN',
+      effort: first?.observed.effort ?? (HOST_EFFORT_BINDING[normalizeHost(host)] === 'none' ? 'UNSUPPORTED' : 'UNKNOWN'),
+    },
+    durationMs: handbacks.length && handbacks.every((h) => h.durationMs !== null) ? handbacks.reduce((n, h) => n + h.durationMs, 0) : null,
+    retries: workers.retries,
+    workerOutcomes: { evidenced: workers.workers.filter((w) => w.state === 'evidenced').length, claimOnly: workers.claimOnly, unobservable: workers.unobservable, failed: workers.failed },
+    tokens: withTokens.length ? { input: sum('input'), output: sum('output'), cacheRead: sum('cacheRead'), cacheCreate: sum('cacheCreate'), total: sum('total'), provenance: 'PROVIDER' } : null,
+    integration: acceptance.facts.integration?.status ?? 'not-applicable',
+    review: reviewDecision?.action ?? null,
+    reviewState: acceptance.facts.review?.state ?? null,
+    acceptance: acceptance.verdict,
+  };
+}
+
+/** Cost per VERIFIED completion over a list of `playbook` telemetry summaries (no learning, just arithmetic). */
+export function playbookCostPerVerified(summaries = []) {
+  const rows = (Array.isArray(summaries) ? summaries : []).filter((s) => s && typeof s === 'object');
+  const verified = rows.filter((s) => s.acceptance === 'PASS');
+  const total = (list) => list.reduce((n, s) => n + (s.tokens?.total ?? 0), 0);
+  const known = rows.filter((s) => s.tokens);
+  return {
+    completions: rows.length,
+    verified: verified.length,
+    notVerified: rows.length - verified.length,
+    tokensAll: total(rows),
+    tokensVerified: total(verified),
+    unknownCost: rows.length - known.length,
+    tokensPerVerified: verified.length ? Math.round(total(rows) / verified.length) : null,
+  };
+}