@ngockhoale/ukit 3.3.2 → 3.4.0

package/template_project/.claude/ukit/runtime/reinject-context.mjs

@@ -100,8 +100,16 @@ async function buildResumableRunLines(projectRoot, state, config) {
     const record = resumed.record;
     if (!record) return [];
     const lines = [];
+    // BL-024 (session-pickup): the state-verify receipt — record-vs-worktree
+    // fingerprint agreement (or the divergent keys) announced before any
+    // resumed plan lines, so a cold pickup never trusts the record silently.
     if (resumed.status === 'stale') {
-      lines.push('- Resumed run: stale — source/index changed since persist; dependent plans were invalidated, completed receipts kept.');
+      const keys = Array.isArray(resumed.changed) && resumed.changed.length > 0
+        ? resumed.changed.join(', ')
+        : 'source/index';
+      lines.push(`- Resumed state verify: stale — recorded fingerprints diverge (${keys}); dependent plans were invalidated, completed receipts kept.`);
+    } else {
+      lines.push('- Resumed state verify: fresh — recorded fingerprints match the live index/config.');
     }
     const phase = String(record.workflow?.phase ?? '').trim();
     if (phase) lines.push(`- Resumed run phase: ${phase}`);

package/template_project/.claude/ukit/runtime/resumable-run.mjs

@@ -445,7 +445,10 @@ function applyInvalidationCodes(record, codes) {
  * Read the C10 record for a task. Never throws on corrupt state.
  *
  * @returns {Promise<{status:'fresh'|'stale'|'invalid'|'absent', record:object|null,
- *   invalidated?:string[], warnings:string[]}>}
+ *   invalidated?:string[], changed?:string[], warnings:string[]}>}
+ *   `changed` lists the source/index/config snapshot keys that diverged from the
+ *   live fingerprint — the state-verify evidence the session-pickup playbook
+ *   consumes (BL-024). Only present once the fingerprint check ran.
  */
 export async function readResumableRun(projectRoot, {
   taskId,
@@ -500,11 +503,93 @@ export async function readResumableRun(projectRoot, {
       status: 'stale',
       record,
       invalidated,
+      changed,
       warnings: [`source/index fingerprint changed (${changed.join(', ')}); dependent plans invalidated`],
     };
   }
 
-  return { status: 'fresh', record: parsed, warnings: [] };
+  return { status: 'fresh', record: parsed, changed, warnings: [] };
+}
+
+// --- suspend (TASK-C86-024, BL-024, CENSUS PB-U20) ----------------------------
+
+/**
+ * The suspend half of the session-pickup contract: checkpoint progress into a
+ * record the pickup `read` consumes. Same merge semantics as route finalize —
+ * the just-completed phase lands in workflow.completedBlocks, plans and
+ * completed receipts carry forward, and a fresh live fingerprint is stamped so
+ * the next resume starts clean. An omitted taskBoundary preserves the existing
+ * record's boundary; an explicit new one starts a fresh record (a different
+ * logical task). Stage 'off' stays fail-closed — suspending writes nothing.
+ */
+export async function suspendResumableRun(projectRoot, {
+  taskId,
+  taskBoundary = null,
+  phase = 'suspended',
+  nextAction = null,
+  completedBlocks = [],
+  signal,
+  deadlineMs = LOCK_MAX_SLICE_MS,
+} = {}) {
+  const boundaryProvided = typeof taskBoundary === 'string' && taskBoundary.length > 0;
+  const resumed = boundaryProvided
+    ? await readResumableRun(projectRoot, { taskId, taskBoundary })
+    : await readResumableRun(projectRoot, { taskId });
+  const previous = resumed.status === 'fresh' || resumed.status === 'stale'
+    ? resumed.record
+    : null;
+  const boundary = boundaryProvided
+    ? taskBoundary
+    : (previous?.taskBoundary ?? 'suspended');
+
+  const carried = [...(previous?.workflow?.completedBlocks ?? [])];
+  const previousPhase = previous?.workflow?.phase;
+  if (previousPhase && previousPhase !== phase && !carried.includes(previousPhase)) {
+    carried.push(previousPhase);
+  }
+  const checkpoint = Array.isArray(completedBlocks) ? completedBlocks : [];
+  const merged = [...new Set([...carried, ...checkpoint])];
+
+  const fingerprint = await resumableRunSourceFingerprint(projectRoot);
+  const record = {
+    schemaVersion: RESUMABLE_RUN_SCHEMA_VERSION,
+    taskId,
+    taskBoundary: boundary,
+    route: previous?.route ?? {
+      routeVersion: 'suspend-cli',
+      mode: 'suspend',
+      rigor: 'unresolved',
+      contractVersion: 'suspend-cli',
+    },
+    budget: previous?.budget ?? { policyVersion: 'suspend-cli', consumed: 0, remaining: 0 },
+    workflow: {
+      workflowId: previous?.workflow?.workflowId ?? 'session-pickup',
+      workflowVersion: previous?.workflow?.workflowVersion ?? 'v1',
+      phase: String(phase ?? 'suspended'),
+      completedBlocks: merged,
+    },
+    invariants: previous?.invariants ?? [],
+    hypotheses: previous?.hypotheses ?? [],
+    decisions: previous?.decisions ?? [],
+    evidenceRefs: previous?.evidenceRefs ?? [],
+    escalationHistory: previous?.escalationHistory ?? [],
+    unresolvedFailures: previous?.unresolvedFailures ?? [],
+    nextAction: typeof nextAction === 'string' && nextAction !== ''
+      ? nextAction.slice(0, MAX_STRING_LENGTH)
+      : null,
+    sourceSnapshot: { ...(previous?.sourceSnapshot ?? {}), ...fingerprint },
+  };
+
+  const write = await writeResumableRun(projectRoot, record, { signal, deadlineMs });
+  return {
+    ok: write.ok === true,
+    status: write.ok ? 'written' : (write.journaled ? 'journaled' : 'skipped'),
+    reason: write.ok || write.journaled ? null : (write.reason ?? 'unknown'),
+    errors: write.errors,
+    journaled: write.journaled === true,
+    path: write.ok ? write.path : resumableRunPath(projectRoot, taskId),
+    record,
+  };
 }
 
 /**
@@ -584,15 +669,74 @@ export async function resumableRunSourceFingerprint(projectRoot, { indexGenerate
 
 // --- CLI (diagnostics) ---------------------------------------------------------
 
+function parseCliFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const match = /^--([\w-]+)$/.exec(argv[i]);
+    if (match) {
+      flags[match[1]] = argv[i + 1] !== undefined ? argv[i + 1] : '';
+      i += 1;
+    }
+  }
+  return flags;
+}
+
 async function main() {
-  const [command, rootArg, taskId] = process.argv.slice(2);
+  const [command, rootArg, taskId, ...rest] = process.argv.slice(2);
   const projectRoot = path.resolve(rootArg || process.cwd());
+  const flags = parseCliFlags(rest);
   if (command === 'read' && taskId) {
-    const result = await readResumableRun(projectRoot, { taskId });
+    // BL-024 (session-pickup): the pickup path's state-verify receipt — compare
+    // the recorded fingerprints against the live index/config so a stale
+    // record reports the divergence instead of being trusted silently.
+    const sourceFingerprint = await resumableRunSourceFingerprint(projectRoot);
+    const result = await readResumableRun(projectRoot, {
+      taskId,
+      taskBoundary: typeof flags.boundary === 'string' && flags.boundary !== ''
+        ? flags.boundary
+        : undefined,
+      sourceFingerprint,
+    });
+    const output = {
+      ...result,
+      stateVerify: {
+        result: result.status === 'fresh' ? 'pass' : 'fail',
+        changed: result.changed ?? [],
+        cursor: result.record
+          ? {
+              phase: result.record.workflow?.phase ?? null,
+              completedBlocks: result.record.workflow?.completedBlocks ?? [],
+              nextAction: result.record.nextAction ?? null,
+            }
+          : null,
+      },
+    };
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    return;
+  }
+  if (command === 'suspend' && taskId) {
+    // BL-024 (PB-U20 suspend half): checkpoint progress into a record the
+    // pickup `read` above consumes — persist + report, never write unlocked.
+    const result = await suspendResumableRun(projectRoot, {
+      taskId,
+      taskBoundary: typeof flags.boundary === 'string' && flags.boundary !== ''
+        ? flags.boundary
+        : null,
+      phase: flags.phase,
+      nextAction: typeof flags.next === 'string' && flags.next !== '' ? flags.next : null,
+      completedBlocks: typeof flags.completed === 'string' && flags.completed !== ''
+        ? flags.completed.split(',').map((entry) => entry.trim()).filter(Boolean)
+        : [],
+    });
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (!result.ok && !result.journaled) process.exitCode = 3;
     return;
   }
-  process.stderr.write('usage: resumable-run.mjs read <projectRoot> <taskId>\n');
+  process.stderr.write(
+    'usage: resumable-run.mjs read <projectRoot> <taskId> [--boundary <id>]\n'
+    + '       resumable-run.mjs suspend <projectRoot> <taskId> [--boundary <id>] '
+    + '[--phase <phase>] [--next <action>] [--completed <a,b,...>]\n',
+  );
   process.exitCode = 2;
 }
 

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -78,6 +78,18 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
 import { withAsyncLock } from './async-lock.mjs';
+// TASK-005 (FR-005): the outcome seam loads LAZILY — a partial install missing
+// observability-emit.mjs must degrade to "no outcome record" (telemetry is
+// advisory), never crash the coordinator at module load.
+let outcomeEmitModulePromise = null;
+function loadOutcomeEmitModule() {
+  if (!outcomeEmitModulePromise) {
+    outcomeEmitModulePromise = import(
+      new URL('./observability-emit.mjs', import.meta.url).href
+    ).catch(() => null);
+  }
+  return outcomeEmitModulePromise;
+}
 
 // Orphan-leak guard (2.4.1 / TASK-025): completion-gate.sh spawns this as
 // `node "$SCRIPT"`, so a host that kills the bash wrapper would reparent a
@@ -357,11 +369,21 @@ export function coordinateStopDecisions({ completion = null, watchdog = null, ha
 }
 
 // ─── Completion evaluator (spawn once) ────────────────────────────────────
-function runEvaluatorChild(scriptPath, input, budgetMs) {
+function runEvaluatorChild(scriptPath, input, budgetMs, { cwd = null } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [scriptPath, '--evaluate-stop'], {
-      // The child gets the same environment plus its own (smaller) self-kill budget.
-      env: { ...process.env, UKIT_HOOK_DEADLINE_MS: String(Math.max(250, budgetMs)) },
+      // The child gets the same environment plus its own (smaller) self-kill
+      // budget, and the caller's project root is pinned twice — cwd AND an
+      // explicit CLAUDE_PROJECT_DIR — because the evaluator resolves its own
+      // root from `CLAUDE_PROJECT_DIR || process.cwd()`: an in-proc caller
+      // (bridge, tests) whose cwd is another project used to evaluate THAT
+      // project's state and silently release the wrong stop.
+      cwd: cwd || undefined,
+      env: {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: cwd || process.env.CLAUDE_PROJECT_DIR || '',
+        UKIT_HOOK_DEADLINE_MS: String(Math.max(250, budgetMs)),
+      },
       stdio: ['pipe', 'pipe', 'pipe'],
     });
     // Tracked so the hook-deadline path can reap a still-running evaluator instead of
@@ -416,10 +438,237 @@ export async function evaluateCompletionPolicy({ projectRoot, rawInput, budgetMs
   } catch {
     throw new Error('completion evaluator unavailable: execution-ledger.mjs is missing (run: ukit install)');
   }
-  const { stdout } = await runEvaluatorChild(ledgerPath, String(rawInput || ''), budgetMs);
+  // TASK-C85-014 (BL-014): consult the verification map BEFORE spawning the
+  // evaluator — the resolved recipe is stamped onto the route state the child
+  // re-reads, so the single authority (the ledger's evaluateCompletion) owns
+  // the verdict either way. Advisory: any failure leaves the gate as before.
+  try {
+    await stampVerificationRecipe({ projectRoot });
+  } catch {}
+  const { stdout } = await runEvaluatorChild(ledgerPath, String(rawInput || ''), budgetMs, { cwd: projectRoot });
   return normalizeEvaluatorStdout(stdout);
 }
 
+// ─── Verification-map recipe consult (C85 TASK-014, BL-014) ────────────────
+// The resolved verification recipe is an advisory INPUT to the completion
+// evaluator, not a second gate: the coordinator reads the route state, loads
+// verification-map.json through the shared index reader, classifies the
+// artifact from the change set, and stamps `routeSummary.verificationRecipe`
+// (+ `routeSummary.artifactClass`) back onto the state file before the
+// evaluator child re-reads it. The stamp persists deliberately — the
+// resume-intent lane (`hasUnfinishedCompletion`) then counts recipe evidence
+// identically across compactions. Map absent/malformed or class unknown →
+// no recipe, and a stale stamp is cleared so behavior returns to pre-map.
+let verificationMapModulePromise = null;
+function loadVerificationMapModule() {
+  if (!verificationMapModulePromise) {
+    verificationMapModulePromise = import(
+      new URL('../index/verification-map.mjs', import.meta.url).href
+    ).catch(() => null);
+  }
+  return verificationMapModulePromise;
+}
+
+function readChangedPathsForRecipe(projectRoot) {
+  try {
+    // -z NUL-terminates entries verbatim — the C-quoted porcelain form
+    // ("src/My Widget.jsx") would misclassify to null downstream (fix round:
+    // review minor). Rename/copy entries emit two fields under -z: `XY to`
+    // then the bare `from` path — the from field is skipped positionally.
+    const out = spawnSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 800,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (out.error || out.status !== 0) return [];
+    const fields = out.stdout.split('\0');
+    const entries = [];
+    for (let i = 0; i < fields.length; i += 1) {
+      const field = fields[i];
+      if (!field || !/^.. /.test(field)) continue;
+      entries.push(field); // raw "XY path" — callers strip the status prefix
+      if (/^[RC]/.test(field)) i += 1; // consume the rename/copy source field
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+async function writeJsonAtomicLocal(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    try { await fs.rm(tempPath, { force: true }); } catch {}
+    throw error;
+  }
+}
+
+// The stamped recipe must round-trip through JSON: a plain data subset, never
+// the reader's full object (which carries no functions anyway, but this keeps
+// the on-disk contract explicit).
+function serializeVerificationRecipe(recipe, artifactClass) {
+  if (!recipe) return null;
+  return {
+    artifactClass,
+    name: recipe.name || null,
+    check: recipe.check || null,
+    harness: recipe.harness || null,
+    fallback: recipe.fallback || null,
+    evidenceRequired: Array.isArray(recipe.evidenceRequired) ? recipe.evidenceRequired : [],
+  };
+}
+
+async function stampVerificationRecipe({ projectRoot }) {
+  const mapModule = await loadVerificationMapModule();
+  if (!mapModule) return; // reader absent (partial install): pre-map behavior
+  const statePath = path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json');
+  let state;
+  try {
+    state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+  } catch {
+    return; // no route state → nothing to stamp
+  }
+  const routeSummary = state?.routeSummary;
+  if (!routeSummary || typeof routeSummary !== 'object') return;
+
+  const changedPaths = readChangedPathsForRecipe(projectRoot)
+    .map((line) => line.replace(/^(..)\s+/, ''));
+  const artifactClass = mapModule.classifyArtifactClass(changedPaths);
+  const map = await mapModule.loadVerificationMap({ projectRoot });
+  const recipe = artifactClass && map
+    ? await mapModule.recipeForArtifact({
+        playbookId: routeSummary.playbookId || null,
+        artifactClass,
+        map,
+      })
+    : null;
+  const serialized = serializeVerificationRecipe(recipe, artifactClass);
+
+  const before = JSON.stringify(routeSummary.verificationRecipe ?? null);
+  const after = JSON.stringify(serialized);
+  if (before === after) return; // no stamp change → no rewrite
+  routeSummary.verificationRecipe = serialized;
+  if (artifactClass) routeSummary.artifactClass = artifactClass;
+  else delete routeSummary.artifactClass;
+  await writeJsonAtomicLocal(statePath, state);
+}
+
+// ─── Review-policy advisory lane (C85 TASK-015, BL-015) ────────────────────
+// "Is one more verification round needed?" becomes a signal decision at the
+// pre-Stop gate. The lane is advisory: the verdict + namedCheck are recorded
+// on the coordinator output and a `kind:'review-policy'` decision receipt is
+// appended for calibration — the completion gate's own block logic and the
+// merged decision are untouched (single Stop authority preserved).
+let reviewPolicyModulePromise = null;
+function loadReviewPolicyModule() {
+  if (!reviewPolicyModulePromise) {
+    reviewPolicyModulePromise = import(
+      new URL('../index/review-policy.mjs', import.meta.url).href
+    ).catch(() => null);
+  }
+  return reviewPolicyModulePromise;
+}
+
+let ledgerReceiptModulePromise = null;
+function loadLedgerReceiptModule() {
+  if (!ledgerReceiptModulePromise) {
+    ledgerReceiptModulePromise = import(
+      new URL('./execution-ledger.mjs', import.meta.url).href
+    ).catch(() => null);
+  }
+  return ledgerReceiptModulePromise;
+}
+
+/**
+ * Evaluate the review decision policy once per stop when a route record
+ * exists, append the calibration receipt, and stamp reviewRounds +
+ * lastReviewPolicy back onto the route state for the next stop's round
+ * accounting. Returns the decision {action, namedCheck?, signalsHit[],
+ * reviewRounds, ...} or null when there is no route record / the module is
+ * absent (partial install). Never throws — an advisory lane must not wedge
+ * the coordinator.
+ *
+ * `completionKind` ('block'|'advisory'|'complete'|null) is the completion
+ * evaluator's verdict, used only to mark which done criteria are evidenced.
+ */
+export async function evaluateStopReviewPolicy({ projectRoot, completionKind = null } = {}) {
+  try {
+    const policyModule = await loadReviewPolicyModule();
+    if (!policyModule || typeof policyModule.evaluateReviewPolicy !== 'function') return null;
+
+    const statePath = path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json');
+    let state;
+    try {
+      state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+    } catch {
+      return null; // no route record → nothing to evaluate
+    }
+    const routeSummary = state?.routeSummary;
+    if (!routeSummary || typeof routeSummary !== 'object') return null;
+
+    // A gate-released stop means the contract's evidence landed ('verified');
+    // otherwise the criteria are unproven — the gate still owns the block, the
+    // policy only reports what the next round would have to check.
+    const evidenceSatisfied = completionKind === 'complete';
+    const requiredTokens = [
+      ...(Array.isArray(routeSummary?.executionContract?.completionEvidence)
+        ? routeSummary.executionContract.completionEvidence
+        : []),
+      ...(Array.isArray(routeSummary?.verificationRecipe?.evidenceRequired)
+        ? routeSummary.verificationRecipe.evidenceRequired
+        : []),
+    ].filter((token) => typeof token === 'string' && token.trim());
+    const doneCriteria = [...new Set(requiredTokens)].map((name) => ({
+      name,
+      status: evidenceSatisfied ? 'verified' : 'missing',
+    }));
+
+    const historySignals = routeSummary.historySignals && typeof routeSummary.historySignals === 'object'
+      ? routeSummary.historySignals
+      : {};
+    const round = Number.isFinite(routeSummary.reviewRounds)
+      ? routeSummary.reviewRounds
+      : 0;
+
+    const ledgerModule = await loadLedgerReceiptModule();
+    const appendDecisionReceipt = ledgerModule?.appendDecisionReceipt;
+
+    const decision = policyModule.evaluateReviewPolicy({
+      signals: routeSummary.suspicionSignals ?? {},
+      doneCriteria,
+      evidenceClasses: [],
+      fixLoopCount: Number.isFinite(historySignals.fixLoopCount) ? historySignals.fixLoopCount : 0,
+      round,
+      cap: policyModule.DEFAULT_REVIEW_ROUND_CAP,
+      projectRoot,
+      appendDecisionReceipt,
+    });
+    if (!decision || typeof decision !== 'object') return null;
+
+    // Persist the round counter + last verdict for the next stop (same atomic
+    // write as the recipe stamp). A stale verdict is honest — it is the last
+    // recorded policy decision, keyed by its action.
+    routeSummary.reviewRounds = Number.isFinite(decision.reviewRounds) ? decision.reviewRounds : round;
+    routeSummary.lastReviewPolicy = {
+      action: decision.action,
+      namedCheck: decision.namedCheck ?? null,
+      signalsHit: Array.isArray(decision.signalsHit) ? decision.signalsHit : [],
+      at: new Date().toISOString(),
+    };
+    await writeJsonAtomicLocal(statePath, state);
+
+    return decision;
+  } catch {
+    return null; // advisory lane: never wedge the coordinator
+  }
+}
+
+
 // ─── Handoff-cursor evaluator (in-process, advisory-on-failure) ───────────
 /**
  * Read `.ukit/storage/config.json` → `handoff.fullstack.stopGate*` merged over
@@ -813,7 +1062,6 @@ export async function runStopCoordinator({
     failures.watchdog = error?.message || String(error);
     process.stderr.write(`[ukit-stop-coordinator] task-watchdog evaluator failed: ${failures.watchdog}\n`);
   }
-
   let handoff = null;
   try {
     handoff = await evaluateHandoffCursor({ projectRoot, now, lockBudgetMs });
@@ -822,7 +1070,76 @@ export async function runStopCoordinator({
     process.stderr.write(`[ukit-stop-coordinator] handoff-cursor evaluator failed: ${failures.handoff}\n`);
   }
 
-  return { skip: null, merged: coordinateStopDecisions({ completion, watchdog, handoff, failures }) };
+  const merged = coordinateStopDecisions({ completion, watchdog, handoff, failures });
+
+  // C85 TASK-015 (BL-015): advisory review-policy verdict. The evaluator runs
+  // only when a route record exists; its action + namedCheck are recorded on
+  // the output and a review-policy receipt lands in decisions.tsv. The gate's
+  // own block logic is unchanged — a non-finish verdict only surfaces as a
+  // systemMessage note, never a block.
+  try {
+    const reviewPolicy = await evaluateStopReviewPolicy({
+      projectRoot,
+      completionKind: completion?.kind ?? null,
+    });
+    if (reviewPolicy) {
+      merged.reviewPolicy = reviewPolicy;
+      if (reviewPolicy.action !== 'finish') {
+        const note = `[ukit-stop-coordinator] review policy (advisory): ${reviewPolicy.action}`
+          + (reviewPolicy.namedCheck ? ` — ${reviewPolicy.namedCheck}` : '')
+          + (Array.isArray(reviewPolicy.signalsHit) && reviewPolicy.signalsHit.length
+            ? ` (signals: ${reviewPolicy.signalsHit.join(', ')})` : '');
+        merged.systemMessage = merged.systemMessage
+          ? `${merged.systemMessage}\n${note}`
+          : note;
+      }
+    }
+  } catch { /* advisory verdicts never affect the stop decision */ }
+
+  // TASK-005 (FR-005): the coordinator's terminal verdict lands ONE
+  // `outcome.observed` record per coordinated stop — the merged evaluator
+  // decision is the session's honest outcome at this stop. Fire-and-forget:
+  // awaited inside the emit module's own 250ms bound; any failure returns
+  // null and never changes the decision the caller is about to emit.
+  {
+    const stopOutcomeVerdict = merged.decision === 'block' ? 'BLOCKED'
+      : typeof merged.systemMessage === 'string' && merged.systemMessage ? 'INCONCLUSIVE'
+      : 'VERIFIED';
+    // runId joins ledger-emitted outcomes on the same session identity the
+    // ledger derives (run-<session>); transcript-only payloads hash the path
+    // instead of leaking it; 'no-session' stays null (missing-data contract).
+    const outcomePayload = sessionKey === 'no-session'
+      ? payload
+      : (typeof payload?.session_id === 'string' && payload.session_id
+        ? { session_id: sessionKey }
+        : { transcript_path: sessionKey });
+    try {
+      const emitModule = await loadOutcomeEmitModule();
+      if (!emitModule || typeof emitModule.buildOutcomeObservedRecord !== 'function'
+        || typeof emitModule.emitOutcomeObserved !== 'function') {
+        return { skip: null, merged };
+      }
+      const outcomeRecord = emitModule.buildOutcomeObservedRecord({
+        outcome: {
+          verdict: stopOutcomeVerdict,
+          source: 'stop-coordinator',
+          routeId: null,
+          routeFingerprint: null,
+          ledgerKey: null,
+          runId: emitModule.outcomeRunId(outcomePayload),
+          evidenceIds: [],
+          cost: { latencyMs: null, rounds: null },
+          reviewActions: [],
+        },
+        projectRoot,
+        payload: typeof payload?.session_id === 'string' && payload.session_id ? payload : outcomePayload,
+        env: process.env,
+      });
+      await emitModule.emitOutcomeObserved({ projectRoot, record: outcomeRecord, deadlineMs: 200 });
+    } catch { /* telemetry never blocks or delays the stop decision */ }
+  }
+
+  return { skip: null, merged };
 }
 
 // ─── CLI ──────────────────────────────────────────────────────────────────

package/template_project/.codex/README.md

@@ -80,6 +80,14 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - If verification is needed, prefer `node .codex/ukit/index/verify-context.mjs ...`.
 - **Treat helper commands as internal orchestration.** Run them yourself when needed; never ask end users to run them.
 
+## Enforcement Ceiling + Playbooks (Codex contract)
+
+- Codex exposes **no hook surface** — routing, gates, and playbooks reach you only as instructions in this file. Every playbook-covered ask resolves to either a measured live path or this advisory fallback; nothing here is hard-blocked.
+- Natural prompts route through `node .codex/ukit/index/route-task.mjs "<prompt>"` — the same route record as the other engines, invoked by instruction, not by hook.
+- When a route returns a `playbookId`, read the playbook file `~/.ukit/playbooks/<id>.md` before implementing, and follow its steps.
+- Outcome records for codex-engine runs carry `enforcement: advisory` — the honest marker that nothing was enforced.
+- Honest ceiling: the codex lane caps at **SHADOW/advisory**. Report advisory, never a live-enforcement claim.
+
 ## UKit Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.

package/template_project/.omp/hooks/pre/ukit-bridge.js

@@ -63,7 +63,11 @@ export const HOOK_EVENT_MAP = {
   },
   before_agent_start: ['sensitive-data-guard.mjs', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
   'session.compacting': ['reinject-context.sh'],
-  session_start: ['project-important.sh', 'auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh'],
+  // TASK-003 (FR-003): the in-proc emit step runs LAST — project-important.sh
+  // owns the mandate-first lead (TASK-042 contract); the emit is advisory,
+  // <250ms, and writes the session's `execution.started` record after the
+  // context-producing scripts.
+  session_start: ['project-important.sh', 'auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh', 'observability-emit.mjs'],
   // TASK-002 (cycle 45): omp emits `session_stop` (no `session_end`); the chain
   // runs only on RELEASED stops inside runSessionStop — never on blocked or
   // dedupe-skipped stops, since `ukit memory episode` dedupes on meta.ledgerKey
@@ -135,6 +139,9 @@ export const ADVISORY_SCRIPTS = new Set([
   'reset-compact-pressure.sh',
   'handoff-resume.sh',
   'session-episode.sh',
+  // TASK-003 (FR-003): session-start emit step, advisory — a telemetry fault
+  // can never block or delay session start.
+  'observability-emit.mjs',
 ]);
 
 function classifyFailure(scriptName) {

package/template_project/ukit/README.md

@@ -23,7 +23,7 @@ UKit state lives at two levels:
   `ukit install` and **never overwritten** afterwards — every user item is
   `mergeStrategy: skip`. Per `manifests/platform.user.yaml` the seeds are:
   `README.md`, `storage/config.json`, `playbooks/bug-fix.md`,
-  `playbooks/issue-implementation.md`.
+  `playbooks/feature-implementation.md`.
 
 Precedence (per key / per id):
 

package/template_project/ukit/storage/config.json

@@ -97,6 +97,11 @@
       "stage": "default"
     }
   },
+  "crossCheck": {
+    "enabled": true,
+    "byRole": {},
+    "byModel": {}
+  },
   "decisionPlane": {
     "enabled": true,
     "stage": "default",
@@ -229,6 +234,7 @@
     "escalation": {
       "enabled": true,
       "debugLoopThreshold": 2,
+      "laneDeepening": true,
       "tierOrder": [
         "lite",
         "code",
@@ -422,6 +428,20 @@
       "stage": "default"
     }
   },
+  "subagentOrchestrator": {
+    "telemetry": {
+      "stage": "off"
+    },
+    "referenceHandoff": {
+      "stage": "off"
+    },
+    "roleAdvice": {
+      "stage": "off"
+    },
+    "contextSelection": {
+      "stage": "off"
+    }
+  },
   "safePatch": {
     "enabled": true,
     "strictSharedRisk": true,