@ngockhoale/ukit 3.4.29 → 3.4.31

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

@@ -7,6 +7,8 @@ import fsSync from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withAsyncLock, LOCK_MAX_SLICE_MS } from './async-lock.mjs';
+import { cronOperationReceipt } from './cron-operation-adapter.mjs';
+import { operationCompletionPolicy, foldOperationEvidence, compactOperation } from './operation-evidence.mjs';
 
 // Hook-context self-deadline (2.4.1 orphan-leak class): armed ONLY on direct
 // CLI invocation (see isDirectRun below) — never at import time. An import-time
@@ -307,9 +309,27 @@ export async function readRouteState(projectRoot, payload = {}) {
   const state = await readJson(path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json'), null);
   const sessionId = explicitSessionId(payload);
   const stateSessionId = explicitSessionId(state || {});
-  if (!state || !sessionId) return state;
-  if (!stateSessionId) return null;
-  return stateSessionId === sessionId ? state : null;
+  if (!state || !sessionId) {
+    // The shared file is single-slot: with no shared file there is still a per-session record.
+    return sessionId ? readSessionRouteState(projectRoot, sessionId) : state;
+  }
+  if (stateSessionId === sessionId) return state;
+  // Shared file missing an owner or owned by another session (a concurrent session routed
+  // after this one): recover this session's own record instead of declaring the route lost.
+  return readSessionRouteState(projectRoot, sessionId);
+}
+
+// Per-session route-state sidecar (written by skill-router.sh and route-task.mjs next to the
+// shared single-slot file). Owner is re-verified from the embedded sessionId, so a misfiled or
+// tampered record can never be adopted by another session.
+export async function readSessionRouteState(projectRoot, sessionId) {
+  const id = String(sessionId || '').trim();
+  if (!id) return null;
+  const state = await readJson(
+    path.join(projectRoot, '.ukit', 'storage', 'cache', 'route-state', `${safeSegment(id)}.json`),
+    null,
+  );
+  return state && explicitSessionId(state) === id ? state : null;
 }
 
 export async function readExecutionLedger(projectRoot, payload = {}) {
@@ -327,7 +347,11 @@ function explicitPromptKey(routeState = {}) {
   return promptKeyFromText(routeState?.routingContext?.lastExplicitUserPromptText);
 }
 
-function hasUnfinishedCompletion(state = {}, ledger = {}) {
+export function hasUnfinishedCompletion(state = {}, ledger = {}, { cwd } = {}) {
+  if (state?.routeSummary?.executionContract?.taskKind) {
+    const result = evaluateCompletion({ state, ledger, cwd });
+    return result.complete !== true && (result.missingEvidence || []).length > 0 && !ledger.blocker;
+  }
   if (ledger?.blocker) return false;
   const mode = state?.routeSummary?.executionMode || state?.routeSummary?.approachSelector?.executionMode;
   if (!IMPLEMENT_MODES.has(mode)) return false;
@@ -366,7 +390,7 @@ export async function readResumableExecution(projectRoot, payload = {}) {
   if (!state || !ledger || !ledger.sessionId || ledger.sessionId !== sessionId
     || ledger.sessionKey !== safeSegment(sessionId) || !ledger.requestKey
     || !ledger.promptKey || !promptKey || ledger.promptKey !== promptKey
-    || !hasUnfinishedCompletion(state, ledger)) {
+    || !hasUnfinishedCompletion(state, ledger, { cwd: projectRoot })) {
     return null;
   }
   return { state, ledger, sessionId };
@@ -392,9 +416,11 @@ export async function readResumeIntent(projectRoot, payload = {}, { consume = fa
   // resumes; a genuinely different prompt produces a different promptKey and stays dead.
   if (!state || !ledger || ledger.sessionId !== sessionId
     || ledger.sessionKey !== safeSegment(sessionId)
+    || ((state.taskInstanceId || intent.taskInstanceId)
+      && (!state.taskInstanceId || state.taskInstanceId !== intent.taskInstanceId || ledger.taskInstanceId !== intent.taskInstanceId))
     || promptKey !== intent.promptKey
     || ledger.promptKey !== intent.promptKey
-    || !hasUnfinishedCompletion(state, ledger)) {
+    || !hasUnfinishedCompletion(state, ledger, { cwd: projectRoot })) {
     return null;
   }
   if (consume) {
@@ -410,7 +436,7 @@ export async function writeResumeIntent(projectRoot, payload = {}, { now = Date.
   const ledger = await readExecutionLedger(projectRoot, payload);
   const promptKey = explicitPromptKey(state || {});
   if (!state || !ledger || ledger.sessionId !== sessionId || !promptKey
-    || ledger.promptKey !== promptKey || !ledger.requestKey || !hasUnfinishedCompletion(state, ledger)) {
+    || ledger.promptKey !== promptKey || !ledger.requestKey || !hasUnfinishedCompletion(state, ledger, { cwd: projectRoot })) {
     return null;
   }
   const intent = {
@@ -418,6 +444,7 @@ export async function writeResumeIntent(projectRoot, payload = {}, { now = Date.
     sessionKey: safeSegment(sessionId),
     sessionHash: resumeSessionHash(sessionId),
     promptKey,
+    taskInstanceId: state.taskInstanceId || null,
     requestKey: ledger.requestKey,
     routeFingerprint: state.fingerprint || null,
     createdAt: now,
@@ -503,15 +530,55 @@ function extractExitCode(payload = {}) {
 
 // The trailing boundary accepts shell terminators (`;`, `&`, `|`, `)`) so
 // `yarn release:verify; echo "exit=$?"` — the real-exit-code idiom — still mints a receipt.
-function isVerificationCommand(command) {
-  const text = String(command || '').trim();
-  if (!text) return false;
+// Blank out quoted literals so `echo '(jest passed)'` / `git commit -m "run yarn test"` do not
+// look like a runner invocation. A `bash|sh|zsh -c '<script>'` wrapper really executes its
+// quoted script, so that script is tested on its own (bounded recursion).
+function maskQuotedLiterals(text) {
+  let out = '';
+  let quote = null;
+  let escaped = false;
+  for (const char of text) {
+    if (escaped) { escaped = false; if (!quote) out += char; continue; }
+    if (char === '\\' && quote !== "'") { escaped = true; if (!quote) out += char; continue; }
+    if (quote) { if (char === quote) { quote = null; out += char; } continue; }
+    if (char === "'" || char === '"') { quote = char; out += char; continue; }
+    out += char;
+  }
+  return out;
+}
+
+function insideQuote(text, index) {
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < index; i += 1) {
+    const char = text[i];
+    if (escaped) { escaped = false; continue; }
+    if (char === '\\' && quote !== "'") { escaped = true; continue; }
+    if (quote) { if (char === quote) quote = null; continue; }
+    if (char === "'" || char === '"') quote = char;
+  }
+  return quote !== null;
+}
+
+const SHELL_C_WRAPPER = /(?:^|[\s;&|({])(?:ba|z|da|k)?sh\s+(?:-o\s+\w+\s+|-[a-z]+\s+)*-[a-z]*c\s+(?:'([^']*)'|"((?:[^"\\]|\\.)*)")/gi;
+
+function isVerificationCommand(command, depth = 0) {
+  const raw = String(command || '').trim();
+  if (!raw) return false;
+  if (depth < 2) {
+    for (const match of raw.matchAll(SHELL_C_WRAPPER)) {
+      // A wrapper that is itself inside a quoted literal (`git commit -m "sh -c 'yarn test'"`) ran nothing.
+      if (insideQuote(raw, match.index)) continue;
+      if (isVerificationCommand(match[1] ?? match[2] ?? '', depth + 1)) return true;
+    }
+  }
+  const text = maskQuotedLiterals(raw);
   return [
-    /(?:^|\s|\.bin\/)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$|[;&|)])/i,
-    /(?:^|\s)(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(?:test|lint|typecheck|check|build)(?:\s|$|[;&|)])/i,
-    /(?:^|\s)(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+release:verify(?:\s|$|[;&|)])/i,
-    /(?:^|\s|\.bin\/)(?:tsc|eslint|biome|ruff|mypy)(?:\s|$|[;&|)])/i,
-    /(?:^|\s)node\s+--check(?:\s|$|[;&|)])/i,
+    /(?:^|[\s({]|\.bin\/)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$|[;&|)])/i,
+    /(?:^|[\s({])(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(?:test(?::[\w:.-]+)?|lint|typecheck|check|build)(?:\s|$|[;&|)])/i,
+    /(?:^|[\s({])(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+release:verify(?:\s|$|[;&|)])/i,
+    /(?:^|[\s({]|\.bin\/)(?:tsc|eslint|biome|ruff|mypy)(?:\s|$|[;&|)])/i,
+    /(?:^|[\s({])node\s+--check(?:\s|$|[;&|)])/i,
   ].some((pattern) => pattern.test(text));
 }
 
@@ -591,9 +658,9 @@ function compactReceipt(receipt) {
     kind: receipt.kind,
     success: receipt.success,
   };
-  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error', 'verdict', 'evidence', 'evidenceSurface', 'class', 'status', 'detail', 'exitStatusUnproven']) {
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error', 'verdict', 'evidence', 'evidenceSurface', 'class', 'status', 'detail', 'operation', 'transportSuccess', 'taskInstanceId', 'sessionKey', 'sequence', 'exitStatusUnproven']) {
     if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
-      compact[key] = receipt[key];
+      compact[key] = key === 'operation' ? compactOperation(receipt[key]) : receipt[key];
     }
   }
   return compact;
@@ -673,6 +740,27 @@ function workspaceFingerprint(cwd) {
   }
 }
 
+// Verification currency excludes UKit's mutable receipts/router state, not source files.
+function verificationDirtyFingerprint(cwd) {
+  try {
+    const paths = ['.', ':(exclude).ukit/storage/**', ':(exclude).claude/ukit/skill-router-state.json'];
+    const options = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500, maxBuffer: 16 * 1024 * 1024 };
+    const diff = execFileSync('git', ['diff', 'HEAD', '--no-ext-diff', '--', ...paths], options);
+    const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z', '--', ...paths], options);
+    const hash = crypto.createHash('sha256').update(diff);
+    let bytes = diff.length + untracked.length;
+    for (const file of untracked.toString('utf8').split('\0').filter(Boolean).sort()) {
+      const absolute = path.resolve(cwd, file);
+      const stat = fsSync.lstatSync(absolute);
+      bytes += stat.size;
+      if (bytes > options.maxBuffer || (!stat.isFile() && !stat.isSymbolicLink())) return null;
+      const content = stat.isSymbolicLink() ? fsSync.readlinkSync(absolute) : fsSync.readFileSync(absolute);
+      hash.update(`\0${file}\0`).update(content);
+    }
+    return hash.digest('hex');
+  } catch { return null; }
+}
+
 // A workspace delta cannot be attributed to the Bash call that happened to observe it: a
 // background process or a subagent may have changed the tree in between. The classifier below
 // only ever REMOVES credit — a command it recognises as strictly read-only never receives a
@@ -736,7 +824,8 @@ function gitPatchId(diffText) {
 // SPEC §2.2 — is this verdict still valid at the current head?
 // Returns { status, current, headSha } where status is one of:
 //   'current' | 'stale' | 'stale-recoverable' | 'untracked' (no git / no sha data).
-// Cost: one `rev-parse` fast path; when head moved, one `git diff` + one `patch-id`.
+// Cost: rev-parse plus a bounded diff/untracked snapshot for new verdicts;
+// when head moved, the existing diff/patch-id comparison also applies.
 export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
   if (!verdict || typeof verdict !== 'object') {
     return { status: 'untracked', current: false, headSha: null };
@@ -750,6 +839,9 @@ export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
     cwd = verdict.workspaceRoot;
   }
   const currentHead = gitOutput(['rev-parse', 'HEAD'], cwd);
+  if (verdict.headSha && Object.hasOwn(verdict, 'dirtyFp') && (!verdict.dirtyFp || verificationDirtyFingerprint(cwd) !== verdict.dirtyFp)) {
+    return { status: 'stale', current: false, headSha: currentHead };
+  }
   if (!currentHead) {
     // No git repo (or git unavailable): currency cannot be proven either way —
     // null-safe per spec non-goals; do not invent staleness on lanes without git.
@@ -785,7 +877,21 @@ export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
 // (a hook or subagent can attest its own kind/verifier); otherwise the kind is
 // derived from the command shape — test runners prove `test-verified`, a run that
 // only type-checks/lints is honestly `check-only`.
-const TEST_RUNNER_COMMAND = /(?:^|\s|\.bin\/)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?:\s|$)/i;
+const TEST_RUNNER_COMMAND = /(?:^|[\s({]|\.bin\/)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?:\s|$)/i;
+// Package-script gates that actually execute tests: `test`, `test:<suite>` and the
+// project's `release:verify` gate. Static-check / fixture-mutating variants
+// (`test:types`, `test:lint`, `test:update-snapshots`, `test:watch`, ...) stay check-only.
+const TEST_SCRIPT_COMMAND = /(?:^|[\s;&|(])(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(test(?::[\w:.-]+)?|release:verify)(?=$|[\s;&|)])/gi;
+const NON_TEST_SCRIPT_SUFFIX = /(?:^|:)(?:types?|typecheck|tsc|lint|format|fmt|snapshots?|update[\w-]*|watch|coverage-?report|clean|setup|fixtures?)(?::|$)/i;
+
+function isTestGateCommand(command) {
+  const text = String(command || '');
+  if (TEST_RUNNER_COMMAND.test(text)) return true;
+  for (const m of text.matchAll(TEST_SCRIPT_COMMAND)) {
+    if (!NON_TEST_SCRIPT_SUFFIX.test(m[1])) return true;
+  }
+  return false;
+}
 
 function mintVerificationVerdict(receipt, payload, projectRoot, sessionRoot = projectRoot) {
   const supplied = payload?.verdict && typeof payload.verdict === 'object' ? payload.verdict : {};
@@ -801,7 +907,7 @@ function mintVerificationVerdict(receipt, payload, projectRoot, sessionRoot = pr
   let kind = supplied.kind;
   if (!VERDICT_KINDS.has(kind)) {
     if (receipt.success !== true) kind = 'failed';
-    else kind = TEST_RUNNER_COMMAND.test(receipt.command || '') ? 'test-verified' : 'check-only';
+    else kind = isTestGateCommand(receipt.command) ? 'test-verified' : 'check-only';
   }
   return {
     kind,
@@ -813,6 +919,7 @@ function mintVerificationVerdict(receipt, payload, projectRoot, sessionRoot = pr
     headSha: headSha || null,
     baseSha: baseSha || null,
     patchId,
+    ...(headSha ? { dirtyFp: verificationDirtyFingerprint(cwd) } : {}),
     ts: supplied.ts || new Date().toISOString(),
   };
 }
@@ -1044,11 +1151,15 @@ function progressDigest(ledger = {}) {
 // A genuinely different prompt keeps a clean slate so old work never satisfies a new
 // request's completion gate.
 function carriedEvidenceLedger(fresh, current) {
-  if (!current || !fresh.promptKey || !current.promptKey || current.promptKey !== fresh.promptKey) {
+  if (!current || (fresh.taskInstanceId || current.taskInstanceId
+    ? !fresh.taskInstanceId || fresh.taskInstanceId !== current.taskInstanceId
+    : !fresh.promptKey || !current.promptKey || current.promptKey !== fresh.promptKey)) {
     return fresh;
   }
   return {
     ...fresh,
+    operationBank: current.operationBank || {},
+    receiptSequence: current.receiptSequence || 0,
     sourceSucceeded: fresh.sourceSucceeded || current.sourceSucceeded === true,
     // targeted-verification evidence (2.3.0) must survive the same re-key carry as the
     // coarse flags, or the stricter gates re-demand evidence mid-request — the exact
@@ -1097,6 +1208,9 @@ function carriedEvidenceLedger(fresh, current) {
     // too — dropping a blocker on re-key would resume the exact loop it recorded.
     failedVerificationStreak: current.failedVerificationStreak || null,
     playbookId: fresh.playbookId || current.playbookId || null,
+    playbookReason: fresh.playbookReason || current.playbookReason || null,
+    taskType: fresh.taskType || current.taskType || null,
+    playbookTrace: current.playbookTrace || fresh.playbookTrace || null,
     // The bug-fix floor bank is monotone request-scoped evidence — a same-prompt
     // re-key must keep it or the gate would re-demand repro receipts mid-request.
     bugFixFloor: current.bugFixFloor || fresh.bugFixFloor || null,
@@ -1138,6 +1252,7 @@ function freshLedger(payload, routeState, harness) {
     harness,
     requestKey: routeState?.requestKey || null,
     promptKey: evidencePromptKey(routeState),
+    taskInstanceId: routeState?.taskInstanceId || null,
     routeFingerprint: routeState?.fingerprint || null,
     // TASK-009 (BL-011): the routed playbook rides the ledger so the bug-fix
     // completion floor can classify repro receipts at apply time — including
@@ -1149,6 +1264,12 @@ function freshLedger(payload, routeState, harness) {
     // TASK-008 (BL-010): latest-per-class playbook-finding statuses, banked
     // outside the evictable receipt window.
     playbookFindings: null,
+    // Playbook trace bookkeeping: the routed selection reason, the route's
+    // proportionality signal, and the derived bounded step trace (persisted at
+    // receipt-apply time). null until a playbook is routed.
+    playbookReason: null,
+    taskType: null,
+    playbookTrace: null,
     sourceSucceeded: false,
     sourceFiles: [],
     writeAttempted: false,
@@ -1157,6 +1278,8 @@ function freshLedger(payload, routeState, harness) {
     verificationSucceeded: false,
     verificationFailed: false,
     receipts: [],
+    receiptSequence: 0,
+    operationBank: {},
     blocker: null,
     verdict: null,
     verdictHistory: [],
@@ -1197,7 +1320,7 @@ const MAX_JOURNAL_SEEN = 64;
 const MAX_JOURNAL_RECORDS = 128;
 const MAX_JOURNAL_QUARANTINE_LINES = 32;
 const LEDGER_EVENT_TYPES = new Set(['receipt', 'continuation', 'notified', 'stop-progress', 'resumable-run']);
-const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding', 'workspace']);
+const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding', 'workspace', 'operation']);
 
 function journalPathFor(target) {
   return `${target}.journal`;
@@ -1232,6 +1355,8 @@ async function mergeContinuationSidecar(ledger, target) {
     return ledger;
   }
   if (!sidecar || typeof sidecar !== 'object') return ledger;
+  if (ledger && (ledger.taskInstanceId || sidecar.taskInstanceId)
+    && (!ledger.taskInstanceId || ledger.taskInstanceId !== sidecar.taskInstanceId)) return ledger;
   const sidecarAt = Number(sidecar.lastContinuationAt) || 0;
   if (!ledger) {
     const hasState = sidecarAt > 0
@@ -1240,6 +1365,7 @@ async function mergeContinuationSidecar(ledger, target) {
     if (!hasState) return null;
     return {
       requestKey: sidecar.requestKey ?? null,
+      taskInstanceId: sidecar.taskInstanceId || null,
       promptKey: sidecar.promptKey ?? null,
       continuationRequestKey: sidecar.requestKey ?? null,
       continuationCount: Number(sidecar.continuationCount) || 0,
@@ -1282,7 +1408,9 @@ async function bumpContinuationSidecar(target, event, { signal, deadlineMs } = {
     { signal, deadlineMs: deadlineMs ?? LOCK_MAX_SLICE_MS },
     async () => {
       try {
-        const base = (await mergeContinuationSidecar(await readJson(target, null), target)) || {};
+        const stored = (await mergeContinuationSidecar(await readJson(target, null), target)) || {};
+        const base = event.taskInstanceId && stored.taskInstanceId !== event.taskInstanceId
+          ? { taskInstanceId: event.taskInstanceId } : stored;
         const applied = event.type === 'notified'
           ? { ...base, notified: true, updatedAt: Date.now() }
           : applyContinuationToLedger(base, event);
@@ -1296,6 +1424,7 @@ async function bumpContinuationSidecar(target, event, { signal, deadlineMs } = {
         await writeJsonAtomic(sidecarPath, {
           requestKey: event?.requestKey ?? applied.requestKey ?? applied.continuationRequestKey ?? null,
           promptKey: event?.promptKey ?? applied.promptKey ?? null,
+          taskInstanceId: event?.taskInstanceId || applied.taskInstanceId || null,
           continuationCount: Number(applied.continuationCount) || 0,
           noProgressCount: Number(applied.noProgressCount) || 0,
           lastProgressDigest: applied.lastProgressDigest ?? null,
@@ -1316,7 +1445,7 @@ function newEventId() {
   return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
 }
 
-const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'workspaceRoot', 'workspaceHeadTs', 'bashReadOnly', 'exitStatusUnproven'];
+const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'workspaceRoot', 'workspaceHeadTs', 'bashReadOnly', 'exitStatusUnproven', 'detail', 'operation', 'transportSuccess', 'taskInstanceId', 'sessionKey', 'sequence'];
 
 // TASK-009 (BL-011): evidence attestations are whitelisted verbatim — class /
 // surface / result / claim, the ARCH §Evidence Schema fields a receipt may
@@ -1340,7 +1469,7 @@ function sanitizeReceiptForJournal(receipt) {
   const clean = {};
   for (const key of JOURNAL_RECEIPT_FIELDS) {
     if (receipt && receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
-      clean[key] = receipt[key];
+      clean[key] = key === 'operation' ? compactOperation(receipt[key]) : receipt[key];
     }
   }
   const evidence = sanitizeEvidenceForJournal(receipt && receipt.evidence);
@@ -1378,6 +1507,7 @@ function buildJournalRecord({ event, eventId, payload, routeState }) {
     sessionKey: sessionIdentity(payload),
     sessionId: explicitSessionId(payload),
     requestKey: routeState?.requestKey ?? null,
+    taskInstanceId: routeState?.taskInstanceId || null,
     promptKey: evidencePromptKey(routeState),
     type: event.type,
     event: event.type === 'receipt'
@@ -1474,6 +1604,10 @@ async function quarantineJournalLines(target, lines) {
 // Uniform applier: returns { ledger, value } or null when the record is unappliable
 // (the caller quarantines it instead of applying it).
 function applyJournalRecord(ledger, record) {
+  const sameTask = ledger.taskInstanceId || record.taskInstanceId
+    ? Boolean(ledger.taskInstanceId && ledger.taskInstanceId === record.taskInstanceId)
+    : Boolean(ledger.requestKey && ledger.requestKey === record.requestKey && (ledger.promptKey || null) === (record.promptKey || null));
+  if (!sameTask) return null;
   if (record.type === 'receipt') {
     return applyReceiptToLedger(ledger, record.event?.receipt, { vibecode: record.event?.vibecode === true });
   }
@@ -1573,6 +1707,207 @@ async function drainJournal(target, { ledger, payload, signal, deadlineMs }) {
   return { ledger: next, applied, quarantined: malformed.length, commit };
 }
 
+// --- Playbook execution trace (observable progress, no LLM) ---------------------
+// A playbook is a text cue; the only durable signal of "was it followed" is the
+// receipt stream the hooks already record. This section folds that stream into
+// a bounded, deterministic `playbookTrace` record:
+//   loaded        — a Read receipt hit playbooks/<id>.md
+//   stepsDone     — receipt-derived evidence per the playbook's step map
+//   stepsSkipped  — non-essential steps on a simple/trivial route, justified
+//   outputs       — bounded list of written targets
+//   verification  — 'pending' | 'passed' | 'failed' | 'n/a'
+// No LLM call, no new store: everything derives from ledger.receipts plus the
+// route signals stamped beside them (playbookReason, taskType). The record is
+// persisted on the ledger at receipt-apply time so `ukit status` and the stop
+// message read it without re-deriving an evictable receipt window. Session and
+// request scoping are inherited from the ledger itself: a ledger only ever
+// holds its own session's receipts, and evaluateCompletion derives from the
+// same-request effective ledger, so another session's or patch's evidence can
+// never satisfy a step.
+
+const PLAYBOOK_TRACE_EVIDENCE_MAX = 200;
+const MAX_PLAYBOOK_OUTPUTS = 8;
+const PROPORTIONATE_JUSTIFICATION = 'proportionate: simple task';
+const PROPORTIONATE_TASK_TYPES = new Set(['simple', 'trivial']);
+
+// Per-playbook step maps. `derive` names the receipt shape that evidences the
+// step: 'pre-fail' (a failed verification before the first write), 'pre-source'
+// (a Read/Grep/Glob of a non-playbook file before the first write), 'write'
+// (the first write receipt), 'post-verify' (a passing verification receipt
+// after the first write). `essential: false` marks the pre-work a proportionate
+// (simple/trivial) route may skip — the fix/implement and verify core never
+// auto-skips. Playbooks outside this map keep the trace bookkeeping (loaded,
+// outputs, reason) but invent no requirements.
+const PLAYBOOK_STEP_MAPS = {
+  'bug-fix': [
+    { id: 'reproduce', derive: 'pre-fail', essential: true },
+    { id: 'locate', derive: 'pre-source', essential: false },
+    { id: 'fix', derive: 'write', essential: true },
+    { id: 'verify', derive: 'post-verify', essential: true },
+  ],
+  'feature-implementation': [
+    { id: 'analog-search', derive: 'pre-source', essential: false },
+    { id: 'implement', derive: 'write', essential: true },
+    { id: 'verify', derive: 'post-verify', essential: true },
+  ],
+  migration: [
+    { id: 'schema-inspect', derive: 'pre-source', essential: false },
+    { id: 'write', derive: 'write', essential: true },
+    { id: 'verify', derive: 'post-verify', essential: true },
+  ],
+};
+
+function playbookStepsFor(playbookId) {
+  const steps = playbookId ? PLAYBOOK_STEP_MAPS[String(playbookId)] : null;
+  return Array.isArray(steps) ? steps : [];
+}
+
+function boundedTraceText(value) {
+  const text = String(value ?? '').trim();
+  return text ? text.slice(0, PLAYBOOK_TRACE_EVIDENCE_MAX) : null;
+}
+
+function isPlaybookRead(file, playbookId) {
+  if (!file || !playbookId) return false;
+  const normalized = String(file).replace(/\\/g, '/');
+  return normalized === `playbooks/${playbookId}.md`
+    || normalized.endsWith(`/playbooks/${playbookId}.md`);
+}
+
+/**
+ * Derive the playbook trace for `playbookId` from the ledger's own evidence.
+ * Pure and deterministic: identical ledger in, identical trace out. A null
+ * playbookId yields the not-applicable trace (no requirements) — the greeting /
+ * informational shape.
+ */
+export function buildPlaybookTrace(ledger = {}, playbookId = null) {
+  const id = playbookId || null;
+  if (!id) {
+    return {
+      playbookId: null,
+      reason: 'not-applicable',
+      selectedAt: null,
+      requiredSteps: [],
+      stepsDone: [],
+      stepsSkipped: [],
+      outputs: [],
+      verification: 'n/a',
+      loaded: false,
+    };
+  }
+  const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
+  const steps = playbookStepsFor(id);
+  const firstWriteIndex = receipts.findIndex((receipt) => receipt?.kind === 'write');
+  const stepEvidence = new Map();
+  let loaded = false;
+  let anyVerificationFailed = false;
+  const outputs = [];
+
+  receipts.forEach((receipt, index) => {
+    if (!receipt || typeof receipt !== 'object') return;
+    if (receipt.kind === 'source') {
+      const playbookRead = isPlaybookRead(receipt.file, id);
+      if (playbookRead) loaded = true;
+      const beforeWrite = firstWriteIndex === -1 || index < firstWriteIndex;
+      // The playbook file itself is process, not target code — it loads the
+      // trace but never satisfies a locate/analog-search step.
+      if (beforeWrite && !playbookRead && !stepEvidence.has('pre-source')) {
+        stepEvidence.set('pre-source', { at: receipt.ts, evidence: boundedTraceText(receipt.file) });
+      }
+      return;
+    }
+    if (receipt.kind === 'write') {
+      const file = boundedTraceText(receipt.file);
+      if (file && !outputs.includes(file) && outputs.length < MAX_PLAYBOOK_OUTPUTS) {
+        outputs.push(file);
+      }
+      if (!stepEvidence.has('write')) {
+        stepEvidence.set('write', { at: receipt.ts, evidence: boundedTraceText(receipt.file) });
+      }
+      return;
+    }
+    if (receipt.kind === 'verification') {
+      const evidence = { at: receipt.ts, evidence: boundedTraceText(receipt.command) };
+      if (receipt.success !== true) {
+        anyVerificationFailed = true;
+        if ((firstWriteIndex === -1 || index < firstWriteIndex) && !stepEvidence.has('pre-fail')) {
+          stepEvidence.set('pre-fail', evidence);
+        }
+        return;
+      }
+      if (firstWriteIndex !== -1 && index > firstWriteIndex && !stepEvidence.has('post-verify')) {
+        stepEvidence.set('post-verify', evidence);
+      }
+    }
+  });
+
+  const stepsDone = [];
+  const stepsSkipped = [];
+  for (const step of steps) {
+    const hit = stepEvidence.get(step.derive);
+    if (hit) {
+      stepsDone.push({
+        id: step.id,
+        at: hit.at ?? null,
+        ...(hit.evidence ? { evidence: hit.evidence } : {}),
+      });
+    } else if (step.essential === false && PROPORTIONATE_TASK_TYPES.has(ledger.taskType)) {
+      stepsSkipped.push({ id: step.id, justification: PROPORTIONATE_JUSTIFICATION });
+    }
+  }
+  const verification = steps.length === 0
+    ? 'n/a'
+    : stepEvidence.has('post-verify') ? 'passed'
+      : anyVerificationFailed ? 'failed'
+        : 'pending';
+  return {
+    playbookId: id,
+    reason: boundedTraceText(ledger.playbookReason) || 'routed',
+    selectedAt: Number.isFinite(ledger.startedAt) ? ledger.startedAt : receipts[0]?.ts ?? null,
+    requiredSteps: steps.map((step) => step.id),
+    stepsDone,
+    stepsSkipped,
+    outputs,
+    verification,
+    loaded,
+  };
+}
+
+/** Required steps neither done nor proportionately skipped — the advisory list. */
+export function playbookTraceMissingSteps(trace = {}) {
+  const done = new Set((Array.isArray(trace.stepsDone) ? trace.stepsDone : []).map((step) => step?.id));
+  const skipped = new Set((Array.isArray(trace.stepsSkipped) ? trace.stepsSkipped : []).map((step) => step?.id));
+  return (Array.isArray(trace.requiredSteps) ? trace.requiredSteps : [])
+    .filter((id) => !done.has(id) && !skipped.has(id));
+}
+
+/** 'playbook bug-fix: 3/4 steps, missing: verify' — null for no-playbook traces. */
+export function formatPlaybookTrace(trace = {}) {
+  if (!trace || !trace.playbookId) return null;
+  const required = Array.isArray(trace.requiredSteps) ? trace.requiredSteps : [];
+  const missing = playbookTraceMissingSteps(trace);
+  const base = `playbook ${trace.playbookId}: ${(Array.isArray(trace.stepsDone) ? trace.stepsDone : []).length}/${required.length} steps`;
+  return missing.length > 0 ? `${base}, missing: ${missing.join(', ')}` : base;
+}
+
+/**
+ * Status/reporting view for `ukit status` and the `--playbook-status` CLI:
+ * routed playbook id, the persisted trace, and its one-line summary.
+ */
+export async function playbookStatus(projectRoot, payload = {}) {
+  const state = await readRouteState(projectRoot, payload);
+  const ledger = (await readExecutionLedger(projectRoot, payload)) || {};
+  const playbookId = state?.routeSummary?.playbookId || ledger?.playbookId || null;
+  const trace = buildPlaybookTrace(ledger, playbookId);
+  return {
+    playbookId,
+    playbookReason: ledger?.playbookReason || state?.routeSummary?.playbookReason || null,
+    taskType: ledger?.taskType || state?.routeSummary?.taskType || null,
+    trace,
+    summary: formatPlaybookTrace(trace),
+  };
+}
+
 // --- TASK-009 (BL-011): bug-fix completion floor --------------------------------
 // A green verdict on a `playbookId: bug-fix` route requires verbatim
 // `repro-before` (failing) + `repro-after` (passing) evidence receipts on the
@@ -1815,7 +2150,11 @@ function applyReceiptToLedger(ledger, receipt, options = {}) {
 
 function applyReceiptCore(ledger, receipt, { vibecode = false } = {}) {
   if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
-  const next = { ...ledger };
+  const next = { ...ledger, receiptSequence: Number(ledger.receiptSequence || 0) + 1 };
+  if (receipt.kind === 'operation') receipt = { ...receipt, sequence: next.receiptSequence };
+  if (receipt.kind === 'operation') {
+    next.operationBank = foldOperationEvidence(ledger.operationBank, receipt, ledger);
+  }
   if (receipt.kind === 'source') {
     next.sourceSucceeded = next.sourceSucceeded || receipt.success;
     if (receipt.success && receipt.file) {
@@ -1861,7 +2200,16 @@ function applyReceiptCore(ledger, receipt, { vibecode = false } = {}) {
     // ones are kept in a bounded history so "one rebuild restores currency" has data.
     if (receipt.verdict && typeof receipt.verdict === 'object') {
       const history = Array.isArray(next.verdictHistory) ? next.verdictHistory : [];
-      next.verdictHistory = [...history, ...(next.verdict ? [next.verdict] : [])].slice(-MAX_VERDICT_HISTORY);
+      const merged = [...history, ...(next.verdict ? [next.verdict] : [])];
+      let kept = merged.slice(-MAX_VERDICT_HISTORY);
+      // A later failed/unproven/check-only run must never push the last satisfying (real PASS)
+      // verdict out of the bounded window — currency, not recency of failures, decides it.
+      if (!kept.some((v) => VERDICT_SATISFYING_KINDS.has(v?.kind))
+        && !VERDICT_SATISFYING_KINDS.has(receipt.verdict.kind)) {
+        const lastPass = [...merged].reverse().find((v) => VERDICT_SATISFYING_KINDS.has(v?.kind));
+        if (lastPass) kept = [lastPass, ...kept.slice(1)];
+      }
+      next.verdictHistory = kept;
       next.verdict = receipt.verdict;
     }
 
@@ -1957,6 +2305,12 @@ function applyReceiptCore(ledger, receipt, { vibecode = false } = {}) {
   }
 
   next.receipts = appendReceipt(next.receipts, receipt);
+  // Playbook trace: re-derived from the ledger's own receipts on every applied
+  // receipt (live and journaled replay alike) so the persisted record never
+  // shows an evictable window. Only playbook-routed ledgers grow the field.
+  if (next.playbookId) {
+    next.playbookTrace = buildPlaybookTrace(next, next.playbookId);
+  }
   next.updatedAt = Date.now();
   return { ledger: next, value: null };
 }
@@ -2032,12 +2386,16 @@ function liveBaseLedger(event, current, payload, routeState, harness, fallbackLe
     // live requestKey the only safe move is to keep appending to the current ledger.
     const nextRequestKey = routeState?.requestKey || null;
     if (current && !nextRequestKey) return { ...current, harness: current.harness || harness };
-    if (!current || current.requestKey !== nextRequestKey) {
+    if (!current || current.requestKey !== nextRequestKey
+      || (current.taskInstanceId || null) !== (routeState?.taskInstanceId || null)) {
       return carriedEvidenceLedger(freshLedger(payload, routeState, harness), current);
     }
     return { ...current, harness: current.harness || harness };
   }
-  return current || fallbackLedger || freshLedger(payload, null, 'unknown');
+  if (current && routeState?.taskInstanceId && current.taskInstanceId !== routeState.taskInstanceId) {
+    return freshLedger(payload, routeState, harness);
+  }
+  return current || (fallbackLedger?.sessionKey ? fallbackLedger : null) || freshLedger(payload, routeState, harness);
 }
 
 // --- TASK-005 (FR-005, BL-007): outcome.observed terminal emissions ---------
@@ -2127,12 +2485,24 @@ export async function recordLedgerEvent(event, {
   const target = ledgerPath(projectRoot, payload);
   // Hoisted so the post-commit outcome emitter sees the same state snapshot
   // the lock callback evaluated (a fresh read could observe a re-route).
-  let lockedRouteState = routeState || null;
+  let lockedRouteState = routeState || await readRouteState(projectRoot, payload);
+  if (event.type === 'receipt' && event.receipt?.kind === 'operation') {
+    if (event.receipt.taskInstanceId && event.receipt.taskInstanceId !== lockedRouteState?.taskInstanceId) {
+      return { rejected: true, eventId, reason: 'receipt-task-mismatch' };
+    }
+    event = { ...event, receipt: { ...event.receipt,
+      taskInstanceId: lockedRouteState?.taskInstanceId || null, sessionKey: sessionIdentity(payload) } };
+  }
   // The descriptor the post-commit emitter must fire (lock-local `value` is
   // nested two levels deep in the lock result — a hoisted ref is clearer).
   let emittedOutcome = null;
   const outcome = await withLedgerLock(target, { signal, deadlineMs }, async () => {
-    const state = routeState || await readRouteState(projectRoot, payload);
+    const liveState = await readRouteState(projectRoot, payload);
+    if (lockedRouteState?.taskInstanceId && liveState?.taskInstanceId
+      && lockedRouteState.taskInstanceId !== liveState.taskInstanceId) {
+      return { committed: false, rejected: true, eventId, reason: 'active-task-changed' };
+    }
+    const state = liveState || lockedRouteState;
     lockedRouteState = state || null;
     const current = await readExecutionLedger(projectRoot, payload);
     let ledger = liveBaseLedger(event, current, payload, state, harness, fallbackLedger);
@@ -2150,7 +2520,24 @@ export async function recordLedgerEvent(event, {
       if (state && ledger.playbookId !== playbookId) {
         ledger = { ...ledger, playbookId };
       }
-      const applied = applyReceiptToLedger(ledger, event.receipt, { vibecode: event.vibecode === true });
+      // Playbook trace signals: the selection reason and the route's taskType
+      // (proportionality) ride the same route summary. Persisted so the trace
+      // derives identically on journaled replays, where no route state is passed.
+      const playbookReason = state?.routeSummary?.playbookReason || null;
+      if (state && playbookReason && ledger.playbookReason !== playbookReason) {
+        ledger = { ...ledger, playbookReason };
+      }
+      const routeTaskType = state?.routeSummary?.taskType || null;
+      if (state && routeTaskType && ledger.taskType !== routeTaskType) {
+        ledger = { ...ledger, taskType: routeTaskType };
+      }
+      if (event.receipt.taskInstanceId && event.receipt.taskInstanceId !== state?.taskInstanceId) {
+        return { committed: false, rejected: true, eventId, reason: 'receipt-task-mismatch' };
+      }
+      const stampedReceipt = event.receipt.kind === 'operation'
+        ? { ...event.receipt, taskInstanceId: state?.taskInstanceId || null, sessionKey: sessionIdentity(payload) }
+        : event.receipt;
+      const applied = applyReceiptToLedger(ledger, stampedReceipt, { vibecode: event.vibecode === true });
       if (!applied) return { committed: false, eventId, reason: 'invalid-receipt' };
       ledger = applied.ledger;
       // TASK-005 (FR-005): completion receipts (write/verification terminal
@@ -2289,7 +2676,7 @@ export async function recordLedgerEvent(event, {
 
   // Fail-closed: the acquisition budget expired or the wait aborted. The main ledger is
   // NEVER mutated unlocked — journal the event once; the next acquired lock reconciles it.
-  const record = buildJournalRecord({ event, eventId, payload, routeState: routeState || null });
+  const record = buildJournalRecord({ event, eventId, payload, routeState: lockedRouteState || null });
   const journalResult = await appendJournalRecord(target, record, { signal, deadlineMs });
   if (journalResult.ok) return { journaled: true, eventId };
   // F-4: continuation/notified are counter state, not journal rows — a journal-full
@@ -2297,7 +2684,7 @@ export async function recordLedgerEvent(event, {
   // MAX_CONTINUATIONS fires late/never. Land the tick in the sidecar the evaluator
   // merges; only a sidecar write failure is a real rejection.
   if (event.type === 'continuation' || event.type === 'notified') {
-    const sidecar = await bumpContinuationSidecar(target, event);
+    const sidecar = await bumpContinuationSidecar(target, { ...event, taskInstanceId: lockedRouteState?.taskInstanceId || null });
     if (sidecar.ok) return { counted: true, eventId, reason: journalResult.reason };
   }
   return { rejected: true, eventId, reason: journalResult.reason };
@@ -2373,7 +2760,7 @@ export async function recordExecutionReceipt({
 } = {}) {
   if (!projectRoot || !toolName) return { rejected: true, eventId: null };
   const routeState = await readRouteState(projectRoot, payload);
-  const failed = explicitError(payload);
+  const failed = payload.hook_event_name === 'PostToolUseFailure' || explicitError(payload);
   const exitCode = extractExitCode(payload);
   const success = !failed && (exitCode === null || exitCode === 0);
   const toolInput = payload.tool_input || {};
@@ -2391,7 +2778,10 @@ export async function recordExecutionReceipt({
     exitCode,
   };
 
-  if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
+  const operationReceipt = cronOperationReceipt(toolName, toolInput, payload.tool_response ?? payload.tool_output ?? payload.tool_result, success, { sessionId: explicitSessionId(payload), harness });
+  if (operationReceipt) {
+    Object.assign(receipt, operationReceipt);
+  } else if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
     receipt.kind = 'source';
     receipt.file = toolInput.file_path || toolInput.path || null;
   } else if (toolName === 'Edit' || toolName === 'Write') {
@@ -2510,6 +2900,9 @@ function requiredEvidence(state = {}) {
   const required = Array.isArray(contractEvidence) && contractEvidence.length > 0
     ? [...contractEvidence]
     : [...(routeSummary.completionState?.missingEvidence || [])];
+  const contract = routeSummary.executionContract;
+  const operationOnly = contract?.taskKind === 'OPERATIONAL'
+    || (contract?.taskKind === 'CONFIGURATION' && contract.configurationScope === 'external');
   // 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.
@@ -2517,7 +2910,7 @@ function requiredEvidence(state = {}) {
   // 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');
+    required.push(operationOnly ? 'operation-verification' : 'verification-evidence');
   }
   // TASK-C85-014 (BL-014): a resolved verification-map recipe rides the route
   // summary (stamped by stop-coordinator's recipe consult). Its
@@ -2535,7 +2928,20 @@ function requiredEvidence(state = {}) {
 
 function evidenceSatisfied(evidence, ledger = {}, state = {}, { cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
-  if (evidence === 'write-evidence') return ledger.writeSucceeded === true;
+  if (evidence === 'operation-verification') {
+    return operationCompletionPolicy(scopedContract(state, ledger), null, ledger)?.complete === true;
+  }
+  if (evidence === 'write-evidence') {
+    const expected = routeSummary.expectedSourceFiles || [];
+    if (routeSummary.executionContract?.taskKind && expected.length) {
+      const bank = evidenceBank(ledger, 'bankedWrites');
+      return expected.some((file) => typeof file === 'string' && (
+        bank[evidenceBankKey(file)] === true
+        || (cwd && bank[evidenceBankKey(path.resolve(cwd, file))] === true)
+      ));
+    }
+    return ledger.writeSucceeded === true;
+  }
   if (evidence === 'verification-evidence') {
     // SPEC-typed-verdicts §2.3: when a verdict record exists it governs — only a
     // CURRENT test-verified/live-verified verdict satisfies the gate. A stale or
@@ -2671,6 +3077,12 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}, {
         }
       }
     }
+    // A pipe-masked run is UNPROVEN, not failed: name the real gap (no provable exit status)
+    // instead of telling the model to "fix the failure" of a run that may have passed.
+    const lastVerification = [...(ledger.receipts || [])].reverse().find((r) => r?.kind === 'verification');
+    if (!instruction && ledger.verificationFailed && lastVerification?.exitStatusUnproven === true) {
+      instruction = `The last verification (\`${String(lastVerification.command || '').slice(0, 80)}\`) ran in a pipeline, so its exit status is unproven. Re-run it without the pipe, or with \`set -o pipefail\`, and inspect the exit code.`;
+    }
     if (!instruction && ledger.verificationFailed) {
       instruction = 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';
     } else if (!instruction) {
@@ -2717,7 +3129,83 @@ function writeEvidenceTier(ledger = {}) {
   return ledger.inferredWrite === true && ledger.directWrite !== true ? { evidenceTier: 'inferred' } : {};
 }
 
-export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
+// Lazy: a missing/unloadable intent module must degrade to the strict gate, never crash Stop.
+async function resolveStopPhase(transcriptPath) {
+  try {
+    const mod = await import(new URL('./handoff-intent.mjs', import.meta.url).href);
+    return await mod.resolveStopPhase(transcriptPath);
+  } catch {
+    return null;
+  }
+}
+export { resolveStopPhase };
+
+// Planning artifacts (docs/, tests/) are the only writes a handoff-create session may make.
+const PLANNING_WRITE_PATH = /(?:^|\/)(?:docs|tests?)\//;
+function wroteOutsidePlanningScope(ledger) {
+  return (ledger?.receipts || []).some((r) => r?.kind === 'write'
+    && typeof r.file === 'string' && r.file
+    && !r.file.startsWith('bash-workspace:')
+    && !PLANNING_WRITE_PATH.test(r.file.replace(/\\/g, '/')));
+}
+
+/**
+ * Command-authority valve (RC-A). `phase` is the session's CURRENT handoff intent from
+ * handoff-intent.mjs: 'create' is planning-only, 'review'/'neutral' (review, status, clear)
+ * carry no implementation debt unless a write actually happened. The gate must never turn
+ * a planning-only session into an "Edit/Write now" instruction. implement/fullstack keep
+ * the normal gate. Returns a release decision or null.
+ */
+function phaseRelease(phase, ledger, missingEvidence) {
+  if (!missingEvidence.some((item) => item === 'write-evidence' || item === 'verification-evidence')) return null;
+  if (phase === 'create' && !wroteOutsidePlanningScope(ledger)) {
+    return {
+      continue: false,
+      notify: true,
+      gateRelease: 'planning-only',
+      phase,
+      missingEvidence,
+      reason: 'UKit completion gate: handoff-create is planning-only, so write/verification evidence is not expected. Stop once the plan, spec and tasks are written; implementation needs /ukit:handoff-implement or /ukit:handoff-fullstack.',
+    };
+  }
+  if ((phase === 'review' || phase === 'neutral') && ledger?.writeAttempted !== true) {
+    return {
+      continue: false,
+      notify: true,
+      gateRelease: 'phase-no-mutation',
+      phase,
+      missingEvidence,
+      reason: `UKit completion gate: this ${phase === 'review' ? 'handoff-review' : 'handoff status/clear'} session made no change, so write/verification evidence is not expected. A review fix needs an actual edit plus a passing verification.`,
+    };
+  }
+  return null;
+}
+
+// Request identity is the prompt (see evidencePromptKey): the router re-keys requestKey on
+// every Edit/Write, so a requestKey mismatch alone must not discard the evidence — and the
+// continuation budget — the request already accumulated. A different prompt keeps a clean slate.
+// Shared by the completion contract and the playbook advisory so both judge the same
+// request-scoped ledger (another prompt's evidence never counts).
+function scopedContract(state, ledger) {
+  const contract = state?.routeSummary?.executionContract;
+  if (!contract?.operationGoal) return contract;
+  const session = state?.sessionId || ledger?.sessionId;
+  return { ...contract, operationGoal: { ...contract.operationGoal,
+    scope: contract.operationGoal.scope || (session ? `session:${session}` : null) } };
+}
+
+function effectiveRequestLedger(state = {}, ledger = {}) {
+  if (state?.sessionId && ledger?.sessionId && state.sessionId !== ledger.sessionId) return {};
+  if (state?.taskInstanceId || ledger?.taskInstanceId) {
+    return state?.taskInstanceId && state.taskInstanceId === ledger?.taskInstanceId ? ledger : {};
+  }
+  const sameRequest = !ledger?.requestKey || !state?.requestKey
+    || ledger.requestKey === state.requestKey
+    || (ledger.promptKey && evidencePromptKey(state) === ledger.promptKey);
+  return sameRequest ? ledger : {};
+}
+
+function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null } = {}) {
   const routeSummary = state?.routeSummary || {};
   // Explicit vibecode autonomy: the user asked UKit to run one prompt to a finished result,
   // so the completion gate keeps pushing instead of releasing at the continuation cap.
@@ -2752,7 +3240,13 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     // success — there is nothing to report. The CLI's lost-route path handles the case where
     // THIS session has ledger activity but the state vanished; callers that pass no state
     // (e.g. the omp bridge for a session it does not own) must not be force-notified.
-    return { continue: false, notify: false, missingEvidence: [] };
+    // A prompt that ORDERED a mutation but routed no contract (no skill matched) was never
+    // verified — release, but say so; read-only/informational prompts stay silent.
+    if (state?.routingContext?.mutationOrder === true) {
+      return { continue: false, notify: true, complete: false, gateRelease: 'no-routable-contract', missingEvidence: [],
+        reason: 'UKit completion gate: this request ordered a change but no completion contract was routed, so nothing was verified. Treat the work as unverified; if it is unfinished, re-send the task in a new message.' };
+    }
+    return { continue: false, notify: false, complete: false, gateRelease: 'no-routable-contract', missingEvidence: [] };
   }
   // An informational turn carries no completion contract of its own. Two paths land here:
   // a fully-routed informational prompt (routeSummary.executionMode === 'informational',
@@ -2765,8 +3259,8 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   // evidence the old contract demands. Release silently — the carried routeSummary stays
   // on disk, so the previous contract still survives until a real route replaces it.
   if (
-    mode === 'informational'
-    || state?.routingContext?.executionMode === 'informational'
+    !routeSummary.executionContract?.taskKind && (mode === 'informational'
+    || state?.routingContext?.executionMode === 'informational')
   ) {
     return { continue: false, notify: false, complete: true, missingEvidence: [] };
   }
@@ -2784,11 +3278,12 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   // Request identity is the prompt (see evidencePromptKey): the router re-keys requestKey on
   // every Edit/Write, so a requestKey mismatch alone must not discard the evidence — and the
   // continuation budget — the request already accumulated. A different prompt keeps a clean slate.
-  const sameRequest = !ledger?.requestKey || !state?.requestKey
-    || ledger.requestKey === state.requestKey
-    || (ledger.promptKey && evidencePromptKey(state) === ledger.promptKey);
-  const effectiveLedger = sameRequest ? ledger : {};
+  const effectiveLedger = effectiveRequestLedger(state, ledger);
+  const operationStatus = operationCompletionPolicy(scopedContract(state, effectiveLedger),
+    null, effectiveLedger);
+  const operationalTask = operationStatus !== null;
   const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, state, { cwd }));
+  if (operationalTask && !operationStatus.complete && !missingEvidence.includes('operation-verification')) missingEvidence.push('operation-verification');
   // TASK-009 (BL-011): the bug-fix floor. On a `playbookId: bug-fix` route a
   // green verdict requires verbatim repro-before (fail) + repro-after (pass)
   // receipts on the same surface plus a named root cause in the exec-ledger —
@@ -2832,9 +3327,13 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     // Silent success: the route is present and every required evidence is satisfied. Marked
     // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
     // bare loud else would turn a clean stop into user-visible noise.
-    return { continue: false, notify: false, complete: true, missingEvidence: [], ...writeEvidenceTier(effectiveLedger) };
+    return { continue: false, notify: false, complete: true, missingEvidence: [], ...(operationalTask ? { gateRelease: 'native-operation-verified', operationProof: operationStatus.operationProof } : writeEvidenceTier(effectiveLedger)) };
   }
 
+  const released = routeSummary.executionContract?.taskKind
+    ? null : phaseRelease(phase, effectiveLedger, missingEvidence);
+  if (released) return released;
+
   // `find-cause` can validly end clean: an investigation may establish that no actionable
   // defect exists. Its contract says a FIX cannot be claimed without write + verification;
   // it does not make a mutation mandatory. Treating missing evidence as an unconditional
@@ -2855,6 +3354,7 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
       || routeSummary.executionContract.completionRule === 'never-claim-fixed-without-write-and-verification');
   if (
     findCauseNoMutationContract
+    && !routeSummary.executionContract?.taskKind
     && playbookId !== BUGFIX_PLAYBOOK_ID
     && !effectiveLedger.writeAttempted
     && !effectiveLedger.verificationFailed
@@ -2877,7 +3377,8 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   // satisfied), no mutation was attempted, and no verification failed; anything less has
   // concrete unfinished work and keeps recovering.
   if (
-    mode === 'map-impact'
+    !routeSummary.executionContract?.taskKind
+    && mode === 'map-impact'
     && !missingEvidence.includes('impact-evidence')
     && effectiveLedger.writeAttempted !== true
     && effectiveLedger.verificationFailed !== true
@@ -2904,7 +3405,8 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   const readOnlyPrompt = state?.routingContext?.mutationOrder === false
     || state?.routingContext?.planOnly === true;
   if (
-    readOnlyPrompt
+    !routeSummary.executionContract?.taskKind
+    && readOnlyPrompt
     && !effectiveLedger.writeAttempted
     && missingEvidence.some((item) => item === 'write-evidence' || item === 'verification-evidence')
   ) {
@@ -2917,14 +3419,19 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     };
   }
 
-  const gated = IMPLEMENT_MODES.has(mode);
+  const gated = Boolean(routeSummary.executionContract?.taskKind) || IMPLEMENT_MODES.has(mode);
   if (!gated) {
+    // Advisory, not a gate message: nothing was written, so verification was never owed.
+    const noWriteAdvisory = !effectiveLedger.writeAttempted && missingEvidence.every((item) => item === 'verification-evidence');
     return {
       continue: false,
       notify: true,
       missingEvidence,
+      ...(noWriteAdvisory ? { gateRelease: 'advisory-no-write' } : {}),
       ...(playbookId === BUGFIX_PLAYBOOK_ID ? { outcome: 'inconclusive' } : {}),
-      reason: `UKit completion gate: missing ${missingEvidence.join(', ')}. This mode does not auto-continue; tell the user what is unfinished.`,
+      reason: noWriteAdvisory
+        ? `UKit note: no files were changed in this session, so ${missingEvidence.join(', ')} is not expected (advisory only; nothing to verify).`
+        : `UKit completion gate: missing ${missingEvidence.join(', ')}. This mode does not auto-continue; tell the user what is unfinished.`,
     };
   }
 
@@ -2992,7 +3499,9 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   }
 
   const finalAttempt = !vibecode && continuationCount === MAX_CONTINUATIONS - 1;
-  const instruction = recoveryInstruction(missingEvidence, effectiveLedger, routeSummary, { cwd });
+  const instruction = operationalTask
+    ? 'Inspect native mutation receipts and verify the requested operational state; do not fabricate source edits or source-test evidence.'
+    : recoveryInstruction(missingEvidence, effectiveLedger, routeSummary, { cwd });
   return {
     continue: true,
     missingEvidence,
@@ -3007,6 +3516,34 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   };
 }
 
+// Playbook trace advisory (observability only). A routed playbook other than
+// bug-fix — whose floor stays the one hard gate — whose required steps are
+// neither receipt-done nor proportionately skipped, on a request that already
+// attempted a write, gets one ADVISORY line at the released stop. It never
+// changes the decision (continue/notify/missingEvidence untouched): no new
+// continuation loop, no hard block. A no-write release (answer/plan/review, or
+// a proportionate trivial route) stays advisory-free.
+function playbookStopAdvisory({ state = {}, ledger = {} } = {}, result = {}) {
+  if (!result || result.continue === true) return null;
+  const routeSummary = state?.routeSummary || {};
+  const playbookId = routeSummary.playbookId || null;
+  if (!playbookId || playbookId === BUGFIX_PLAYBOOK_ID) return null;
+  const effectiveLedger = effectiveRequestLedger(state, ledger);
+  if (effectiveLedger.writeAttempted !== true) return null;
+  const trace = buildPlaybookTrace(effectiveLedger, playbookId);
+  if (playbookTraceMissingSteps(trace).length === 0) return null;
+  return `UKit playbook note: ${formatPlaybookTrace(trace)} (advisory).`;
+}
+
+export function evaluateCompletion(args = {}) {
+  const result = evaluateCompletionContract(args);
+  try {
+    const advisory = playbookStopAdvisory(args, result);
+    if (advisory) return { ...result, playbookAdvisory: advisory };
+  } catch { /* the advisory never breaks the gate */ }
+  return result;
+}
+
 export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null, promptKey = null, { signal, deadlineMs } = {}) {
   // Locked (and fail-closed) via recordLedgerEvent: parallel subagents firing Stop hooks
   // share one ledger file, and a stale-snapshot rewrite would reset each other's
@@ -3137,7 +3674,8 @@ async function runEvaluateStop() {
     return;
   }
 
-  const result = evaluateCompletion({ state, ledger, cwd: projectRoot });
+  const phase = await resolveStopPhase(payload?.transcript_path);
+  const result = evaluateCompletion({ state, ledger, cwd: projectRoot, phase });
 
   // TASK-C85-019 fix C: a mutating-mode route released by a no-mutation valve
   // while evidence is missing is the anomaly signal for misrouted advisory
@@ -3219,12 +3757,22 @@ async function runEvaluateStop() {
   if (result.capped || result.notify) {
     // Non-blocking endings (non-gated modes, an invisible blocker, an evidence-less route, or
     // cap reached after the final notice) must still tell the user what is unfinished — a
-    // silent end is indistinguishable from a stall.
+    // silent end is indistinguishable from a stall. A playbook advisory rides the SAME
+    // single line (evaluator stdout is parsed first-line-wins by the stop coordinator).
+    const message = result.playbookAdvisory ? `${result.reason} ${result.playbookAdvisory}` : result.reason;
     process.stderr.write(`[ukit-completion] ${result.reason}\n`);
-    process.stdout.write(`${JSON.stringify({ systemMessage: result.reason })}\n`);
+    process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
     return;
   }
-  if (result.complete) return; // silent success: route present, all evidence satisfied
+  if (result.complete) {
+    // A satisfied route stays a silent success — unless the routed playbook has
+    // steps missing, where the trace advisory IS the one-line release message.
+    if (result.playbookAdvisory) {
+      process.stdout.write(`${JSON.stringify({ systemMessage: result.playbookAdvisory })}\n`);
+    }
+    return; // silent success: route present, all evidence satisfied
+  }
+  if (result.gateRelease === 'no-routable-contract') return; // Advisory release, never VERIFIED.
   // Defensive final else: no evaluation result may ever end a routed stop silently.
   const fallback = `UKit completion gate: the stop was evaluated without a decision (missing evidence: ${(result.missingEvidence || []).join(', ') || 'none'}). If work is unfinished, re-send the task in a new message.`;
   process.stderr.write(`[ukit-completion] ${fallback}\n`);
@@ -3240,6 +3788,14 @@ async function main() {
   }
   const payload = JSON.parse((await readStdin()) || '{}');
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
+  if (process.argv.includes('--playbook-status')) {
+    // Reporting path for `ukit status`: { playbookId, playbookReason, taskType,
+    // trace, summary } for this session's routed playbook (not-applicable when
+    // no playbook is routed).
+    const status = await playbookStatus(projectRoot, payload);
+    process.stdout.write(`${JSON.stringify(status)}\n`);
+    return;
+  }
   if (process.argv.includes('--record')) {
     const receiptResult = await recordExecutionReceipt({
       projectRoot,