@ngockhoale/ukit 3.4.29 → 3.4.30

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

@@ -307,9 +307,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 = {}) {
@@ -503,15 +521,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));
 }
 
@@ -785,7 +843,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 +873,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,
@@ -1097,6 +1169,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,
@@ -1149,6 +1224,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,
@@ -1573,6 +1654,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
@@ -1861,7 +2143,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 +2248,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 };
 }
@@ -2150,6 +2447,17 @@ export async function recordLedgerEvent(event, {
       if (state && ledger.playbookId !== playbookId) {
         ledger = { ...ledger, playbookId };
       }
+      // 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 };
+      }
       const applied = applyReceiptToLedger(ledger, event.receipt, { vibecode: event.vibecode === true });
       if (!applied) return { committed: false, eventId, reason: 'invalid-receipt' };
       ledger = applied.ledger;
@@ -2671,6 +2979,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 +3031,71 @@ 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 effectiveRequestLedger(state = {}, 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.
@@ -2784,10 +3162,7 @@ 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 missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, state, { cwd }));
   // 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)
@@ -2835,6 +3210,9 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     return { continue: false, notify: false, complete: true, missingEvidence: [], ...writeEvidenceTier(effectiveLedger) };
   }
 
+  const released = 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
@@ -2919,12 +3297,17 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
 
   const gated = 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.`,
     };
   }
 
@@ -3007,6 +3390,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 +3548,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 +3631,21 @@ 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
+  }
   // 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 +3661,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,