@ngockhoale/ukit 3.4.44 → 3.4.46

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

@@ -2225,6 +2225,8 @@ function applyReceiptCore(ledger, receipt, { vibecode = false } = {}) {
   if (receipt.kind === 'operation') {
     next.operationBank = foldOperationEvidence(ledger.operationBank, receipt, ledger);
   }
+  if (receipt.releasePreflight) next.releasePreflight = { ...receipt.releasePreflight, sequence: next.receiptSequence };
+  if (receipt.kind === 'write' && receipt.success) next.releasePreflight = null;
   if (receipt.kind === 'source') {
     next.sourceSucceeded = next.sourceSucceeded || receipt.success;
     if (receipt.success && receipt.file) {
@@ -2848,6 +2850,12 @@ export async function recordExecutionReceipt({
     exitCode,
   };
 
+  const policy = routeState?.routeSummary?.executionContract?.releasePolicy;
+  if (toolName === 'Bash' && !bashScope.foreign && policy?.kind === 'conditional-release'
+    && String(toolInput.command || '').trim() === policy.preflight && Number.isInteger(exitCode)) {
+    receipt.releasePreflight = { command: policy.preflight, failed: exitCode !== 0, exitCode,
+      taskInstanceId: routeState.taskInstanceId, workspaceFp };
+  }
   const toolResponse = payload.tool_response ?? payload.tool_output ?? payload.tool_result;
   const nativeGoal = routeState?.routeSummary?.executionContract?.operationGoal;
   const operationReceipt = cronOperationReceipt(toolName, toolInput, toolResponse, success, { sessionId: explicitSessionId(payload), harness })
@@ -2863,6 +2871,14 @@ export async function recordExecutionReceipt({
   } else if (toolName === 'Edit' || toolName === 'Write') {
     receipt.kind = 'write';
     receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
+    // External scratch artifacts are not product mutations. Keep them out of write debt/proof entirely;
+    // otherwise a /tmp report resurrects implementation obligations on a read-only investigation.
+    if (typeof receipt.file === 'string') {
+      const relative = path.relative(path.resolve(projectRoot), path.resolve(projectRoot, receipt.file));
+      if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return { rejected: true, eventId: null, reason: 'outside-product-workspace' };
+      }
+    }
   } else if (toolName === 'Bash' && !bashScope.foreign && (isVerificationCommand(toolInput.command) || evidence)) {
     // TASK-009 (BL-011): a Bash command carrying an evidence attestation
     // records as a verification receipt even when the command is not a known
@@ -3004,6 +3020,14 @@ function requiredEvidence(state = {}) {
 
 function evidenceSatisfied(evidence, ledger = {}, state = {}, { cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
+  if (evidence === 'report-artifact') {
+    const artifact = routeSummary.executionContract?.reportArtifact;
+    if (!cwd || typeof artifact !== 'string') return false;
+    const target = path.resolve(cwd, artifact);
+    const bank = evidenceBank(ledger, 'bankedWrites');
+    if (bank[evidenceBankKey(artifact)] !== true && bank[evidenceBankKey(target)] !== true) return false;
+    try { return fsSync.statSync(target).isFile() && fsSync.statSync(target).size > 0; } catch { return false; }
+  }
   if (evidence === 'operation-verification') {
     return operationCompletionPolicy(scopedContract(state, ledger), null, withGitAuthority(ledger, cwd))?.complete === true;
   }
@@ -3315,7 +3339,8 @@ function effectiveRequestLedger(state = {}, ledger = {}) {
 // Release postcondition. A request that ORDERS `npm publish` is complete only when trusted receipts
 // (real Bash results recorded by the adapter - never agent prose) show the registry serving exactly the
 // package.json version, and the local Git state agrees: a local release tag, if present, must DEREFERENCE
-// (`^{commit}`, never the annotated tag-object SHA) to HEAD. A failed/missing publish with no registry proof
+// (`^{commit}`, never the annotated tag-object SHA) to HEAD, or to an ancestor of HEAD with no shipped change
+// since (publishedReleaseDrifted). A failed/missing publish with no registry proof
 // stays missing. A registry that already serves the version counts as published, so a finished release is
 // never re-published just to satisfy the gate.
 function promptOrdersNpmPublish(state = {}) {
@@ -3339,10 +3364,73 @@ function releasePublicationMissing(state, ledger, cwd) {
   if (view?.operation?.state !== wanted) return 'release-publication';
   const tagCommit = gitOutput(['rev-parse', '--verify', '--quiet', `v${pkg.version}^{commit}`], cwd);
   const head = gitOutput(['rev-parse', 'HEAD'], cwd);
-  if (tagCommit && head && tagCommit !== head) return 'release-publication';
+  // A repository that tags its releases (any v<semver> tag exists) must have tagged THIS version: without the
+  // tag there is no immutable identity to tie the published artifact to. A repository that never tags keeps
+  // the registry receipt as its only proof (the pre-P1 behaviour) instead of being blocked forever.
+  if (!tagCommit && head && repoTagsReleases(cwd)) return 'release-publication';
+  if (tagCommit && head && (tagCommit !== head || workingTreeShippedChange(pkg, tagCommit, cwd)) && publishedReleaseDrifted(pkg, tagCommit, head, cwd)) return 'release-publication';
   return null;
 }
 
+// P1-B: the published release is identified by the IMMUTABLE tag commit, not by the moving HEAD. A later
+// commit must not invalidate a verified publication, but HEAD may only be ahead of the tag when (a) the tag
+// commit is an ancestor of HEAD, (b) package.json AT THE TAG carries the published version, and (c) nothing
+// the package ships changed between tag and HEAD (docs/tests/ledger-only follow-ups are fine; unshipped
+// source is not). Every git failure is fail-closed: unknown means drifted.
+function gitSucceeds(args, cwd) {
+  try {
+    execFileSync('git', args, { cwd, stdio: ['ignore', 'ignore', 'ignore'], timeout: 5000 });
+    return true;
+  } catch { return false; }
+}
+
+function packageFilePattern(entry) {
+  const negated = entry.startsWith('!');
+  let body = (negated ? entry.slice(1) : entry).replace(/^\.?\//, '');
+  const dir = body.endsWith('/');
+  if (dir) body = body.slice(0, -1);
+  const source = body.split('**').map((part) => part.split('*')
+    .map((seg) => seg.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*');
+  return { negated, regex: new RegExp(`^${source}(?:/.*)?$`) };
+}
+
+function shippedByPackage(pkg, file) {
+  if (/^(?:package\.json|readme(?:\.[a-z]+)?|license(?:\.[a-z]+)?|licence(?:\.[a-z]+)?|changelog(?:\.[a-z]+)?)$/i.test(file)) return true;
+  if (!Array.isArray(pkg?.files)) return true; // no allow-list: npm ships everything, so any change is shipped code
+  const patterns = pkg.files.filter((entry) => typeof entry === 'string' && entry.trim()).map(packageFilePattern);
+  const included = patterns.some((p) => !p.negated && p.regex.test(file));
+  return included && !patterns.some((p) => p.negated && p.regex.test(file));
+}
+
+function publishedReleaseDrifted(pkg, tagCommit, head, cwd) {
+  if (!gitSucceeds(['merge-base', '--is-ancestor', tagCommit, head], cwd)) return true;
+  let taggedVersion = null;
+  try {
+    taggedVersion = JSON.parse(gitOutput(['show', `${tagCommit}:package.json`], cwd) || 'null')?.version ?? null;
+  } catch { return true; }
+  if (taggedVersion !== pkg.version) return true;
+  let changed = null;
+  try {
+    changed = execFileSync('git', ['diff', '--name-only', '-z', tagCommit, head], { cwd, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch { return true; }
+  if (String(changed).split('\0').filter(Boolean).some((file) => shippedByPackage(pkg, file))) return true;
+  return workingTreeShippedChange(pkg, tagCommit, cwd);
+}
+
+function repoTagsReleases(cwd) {
+  const tags = gitOutput(['tag', '--list', 'v[0-9]*'], cwd);
+  return Boolean(tags && tags.trim());
+}
+
+// Uncommitted edits (tracked or untracked) to shipped files are not the published artifact either.
+function workingTreeShippedChange(pkg, tagCommit, cwd) {
+  try {
+    const tracked = execFileSync('git', ['diff', '--name-only', '-z', tagCommit], { cwd, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    return `${tracked}${untracked}`.split('\0').filter(Boolean).some((file) => shippedByPackage(pkg, file));
+  } catch { return true; }
+}
+
 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,
@@ -3449,6 +3537,23 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
     const at = missingEvidence.indexOf('impact-evidence');
     if (at !== -1) missingEvidence.splice(at, 1);
   }
+  const releasePolicy = routeSummary.executionContract?.releasePolicy;
+  const preflight = effectiveLedger?.releasePreflight;
+  if (['MIXED', 'OPERATIONAL'].includes(routeSummary.executionContract?.taskKind)
+    && releasePolicy?.kind === 'conditional-release' && preflight?.failed === true
+    && preflight.command === releasePolicy.preflight && preflight.taskInstanceId === state.taskInstanceId
+    && (!preflight.workspaceFp || preflight.workspaceFp === workspaceFingerprint(cwd))
+    && !missingEvidence.some((item) => item !== 'operation-verification' && item !== 'verification-evidence')) {
+    return { continue: false, notify: true, complete: false, outcome: 'blocked',
+      releaseOutcome: 'RELEASE_NO_GO', missingEvidence: [],
+      reason: `RELEASE_NO_GO: owned preflight ${preflight.command} failed (exit ${preflight.exitCode}); publication is prohibited by this task's conditional release policy. No release was completed.` };
+  }
+  if (releasePolicy?.kind === 'conditional-release'
+    && !(preflight?.failed === false && preflight.command === releasePolicy.preflight
+      && preflight.taskInstanceId === state.taskInstanceId
+      && (!preflight.workspaceFp || preflight.workspaceFp === workspaceFingerprint(cwd)))) {
+    missingEvidence.push('release-preflight');
+  }
   const releaseMissing = releasePublicationMissing(state, effectiveLedger, cwd);
   if (releaseMissing) missingEvidence.push(releaseMissing);
   // TASK-009 (BL-011): the bug-fix floor. On a `playbookId: bug-fix` route a
@@ -3667,7 +3772,7 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
 
   const finalAttempt = !vibecode && continuationCount === MAX_CONTINUATIONS - 1;
   const instruction = missingEvidence.includes('release-publication')
-    ? 'The release is not proven published: run `npm publish` once if the registry does not yet serve this version, then confirm with `npm view <package> version` (must equal package.json) and that the release tag dereferences to HEAD. Do not republish a version the registry already serves.'
+    ? 'The release is not proven published: run `npm publish` once if the registry does not yet serve this version, then confirm with `npm view <package> version` (must equal package.json) and that the release tag dereferences to HEAD (or to an ancestor of HEAD with no shipped change since). Never move the tag. Do not republish a version the registry already serves. Accepted evidence: a Bash result of exactly `npm view <package> version` (optionally `2>&1`, optionally after `cd <dir> &&`) that exited 0 and printed a bare semver. Rejected as unproven: the same command behind `| tail/head/cat`, `;`, `||` or inside a compound (a pipeline hides the exit status), dry runs, prose claims. Re-run the bare command once; do not republish.'
     : 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 });
@@ -3706,6 +3811,20 @@ function playbookStopAdvisory({ state = {}, ledger = {} } = {}, result = {}) {
 
 export function evaluateCompletion(args = {}) {
   const result = evaluateCompletionContract(args);
+  // Explain the verdict from the SAME task-scoped snapshot used by the verifier. These are proof summaries,
+  // not an alternative evidence source; a diagnostic must never satisfy or relax an obligation.
+  const owned = effectiveRequestLedger(args.state, args.ledger) || {};
+  const diagnostics = {
+    taskInstanceId: args.state?.taskInstanceId || null,
+    contract: args.state?.routeSummary?.executionContract?.taskKind || args.state?.routeSummary?.taskKind || args.state?.routeSummary?.executionMode || null,
+    unmetObligations: result.missingEvidence || [],
+    acceptedEvidence: result.complete === true || result.missingEvidence?.length
+      ? requiredEvidence(args.state).filter((item) => !(result.missingEvidence || []).includes(item)) : [],
+    observedEvidence: [owned.sourceSucceeded && 'source-read', owned.writeSucceeded && 'write-receipt', owned.verificationSucceeded && 'verification-receipt'].filter(Boolean),
+    rejectedEvidence: args.ledger && owned !== args.ledger ? ['ledger-task-ownership-mismatch'] : [],
+  };
+  result.diagnostics = diagnostics;
+  if (result.reason) result.reason += ` [task=${diagnostics.taskInstanceId || 'unknown'} contract=${diagnostics.contract || 'unknown'} accepted-count=${diagnostics.acceptedEvidence.length} rejected=${diagnostics.rejectedEvidence.join(',') || 'none'}]`;
   try {
     const advisory = playbookStopAdvisory(args, result);
     if (advisory) return { ...result, playbookAdvisory: advisory };

package/template_project/.claude/ukit/runtime/handoff-intent.mjs

@@ -38,6 +38,8 @@
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
 // The `(?![\w-])` closer is the exact token boundary: a command name followed by
@@ -273,15 +275,164 @@ export function classifyHandoffLine(line) {
   }
 }
 
+const SCAN_CHUNK = 4 * 1024 * 1024;
+const INTENT_CACHE_VERSION = 1;
+const RUNTIME_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+// The shipped template tree must never grow runtime state: only an installed project gets a default cache.
+const DEFAULT_INTENT_CACHE_DIR = path.basename(RUNTIME_ROOT) === 'template_project' ? null : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '.ukit', 'storage', 'cache', 'handoff-intent');
+const EVIDENCE_MARKERS = ['handoff-create', 'handoff-fullstack', 'handoff-implement', 'handoff-review', 'handoff-status', 'handoff-clear', 'HANDOFF RESUME'];
+
+/**
+ * Walk the byte range [lo, hi) NEWEST line first, in bounded chunks, and stop at the
+ * first line that carries a handoff intent. `hi` must be EOF or a line boundary. `lo`
+ * is a line boundary only when `loIsBoundary`; otherwise the fragment cut by `lo` is
+ * not a whole entry and is dropped. `reached` is the lowest absolute byte offset up to
+ * which every line was fully examined; `lastNL` the highest newline seen (so callers
+ * can persist a line-aligned offset and never cache a half-written trailing record).
+ * @returns {{status:'found'|'done'|'torn'|'timeout', intent?:string, evidence?:{pos:number,len:number}, reached:number, lastNL:number}}
+ */
+async function scanBack(handle, hi, lo, loIsBoundary, deadline) {
+  let pos = hi;
+  let carry = Buffer.alloc(0);
+  let lastNL = -1;
+  let reached = hi;
+  while (pos > lo) {
+    if (Date.now() > deadline) return { status: 'timeout', reached, lastNL };
+    const start = Math.max(lo, pos - SCAN_CHUNK);
+    const chunk = Buffer.allocUnsafe(pos - start);
+    const { bytesRead } = await handle.read(chunk, 0, chunk.length, start);
+    if (bytesRead !== chunk.length) return { status: 'timeout', reached, lastNL };
+    const buf = carry.length ? Buffer.concat([chunk, carry]) : chunk;
+    if (lastNL < 0) {
+      const i = buf.lastIndexOf(10);
+      if (i >= 0) lastNL = start + i;
+    }
+    let base = start;
+    let region = buf;
+    if (start > 0 && !(loIsBoundary && start === lo)) {
+      // This chunk begins mid-line: the head fragment belongs to the next lower chunk.
+      const nl = buf.indexOf(10);
+      if (nl < 0) { carry = buf; pos = start; continue; }
+      carry = buf.subarray(0, nl);
+      region = buf.subarray(nl + 1);
+      base = start + nl + 1;
+      reached = base;
+    } else {
+      carry = Buffer.alloc(0);
+      reached = start;
+    }
+    let end = region.length;
+    for (;;) {
+      const i = end > 0 ? region.lastIndexOf(10, end - 1) : -1;
+      const lineBuf = region.subarray(i + 1, end);
+      if (lineBuf.length) {
+        const line = lineBuf.toString('utf8');
+        // Cheap prefilter — skip JSON.parse for lines that cannot be evidence.
+        if (EVIDENCE_MARKERS.some((m) => line.includes(m))) {
+          // This is the NEWEST line carrying intent evidence. A host append can be
+          // cut mid-record (killed turn, torn write), leaving it unparseable. Skipping
+          // it would fall through to an OLDER — possibly OPPOSITE — intent (a torn
+          // `handoff-implement` after a create released a real fullstack run). An
+          // incomplete newest evidence-bearing record is UNDETERMINED, not "no
+          // intent": the caller stays fail-closed (MODULE02-SPEC FR-M2-002).
+          let entry;
+          try { entry = JSON.parse(line); } catch { return { status: 'torn', reached, lastNL }; }
+          const intent = classifyHandoffEntry(entry);
+          if (intent) return { status: 'found', intent, evidence: { pos: base + i + 1, len: lineBuf.length }, reached, lastNL };
+          // Complete record with no recognised intent (tool output, foreign envelope):
+          // not evidence — keep walking older lines.
+        }
+      }
+      if (i < 0) break;
+      end = i;
+    }
+    pos = start;
+  }
+  return { status: 'done', reached, lastNL };
+}
+
+const fp = (buf) => createHash('sha1').update(buf).digest('hex');
+
+async function readBytes(handle, pos, len) {
+  const buf = Buffer.allocUnsafe(len);
+  const { bytesRead } = await handle.read(buf, 0, len, pos);
+  return bytesRead === len ? buf : null;
+}
+
+/**
+ * Load the per-transcript incremental state and prove it still describes THIS file:
+ * same head bytes (rotation / session reuse), same bytes just below the cached offset
+ * (in-place rewrite), size not below the offset (truncation), and any cached intent
+ * line re-read and re-classified. Anything malformed, stale or unverifiable returns
+ * null so the caller re-scans from scratch — a bad cache can only cost time, and can
+ * never turn an inconclusive scan into a conclusive one.
+ */
+async function loadIntentCache(file, handle, size, maxBytes) {
+  try {
+    const c = JSON.parse(await fs.readFile(file, 'utf8'));
+    if (!c || c.v !== INTENT_CACHE_VERSION) return null;
+    const ints = [c.offset, c.coveredFrom, c.headLen, c.tailLen];
+    if (!ints.every((n) => Number.isSafeInteger(n) && n >= 0)) return null;
+    if (c.offset > size || size - c.offset > maxBytes || c.coveredFrom > c.offset) return null;
+    if (c.headLen > Math.min(size, 4096) || c.tailLen > c.offset) return null;
+    const head = await readBytes(handle, 0, c.headLen);
+    if (!head || fp(head) !== c.headFp) return null;
+    const tail = await readBytes(handle, c.offset - c.tailLen, c.tailLen);
+    if (!tail || fp(tail) !== c.tailFp) return null;
+    let intent = null;
+    let evidence = null;
+    if (c.intent) {
+      const ev = c.evidence;
+      if (!ev || !Number.isSafeInteger(ev.pos) || !Number.isSafeInteger(ev.len) || ev.pos < c.coveredFrom || ev.pos + ev.len >= c.offset) return null;
+      const raw = await readBytes(handle, ev.pos, ev.len);
+      if (!raw || classifyHandoffLine(raw.toString('utf8')) !== c.intent) return null;
+      intent = c.intent;
+      evidence = { pos: ev.pos, len: ev.len };
+    }
+    return { offset: c.offset, coveredFrom: c.coveredFrom, intent, evidence };
+  } catch {
+    return null;
+  }
+}
+
+async function saveIntentCache(file, handle, st) {
+  try {
+    if (!(st.coveredFrom <= st.offset)) return;
+    const headLen = Math.min(4096, st.offset);
+    const tailLen = Math.min(256, st.offset);
+    const head = await readBytes(handle, 0, headLen);
+    const tail = await readBytes(handle, st.offset - tailLen, tailLen);
+    if (!head || !tail) return;
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify({
+      v: INTENT_CACHE_VERSION, offset: st.offset, coveredFrom: st.coveredFrom,
+      headLen, headFp: fp(head), tailLen, tailFp: fp(tail),
+      intent: st.intent || null, evidence: st.intent ? st.evidence : null,
+    }), 'utf8');
+    await fs.rename(tmp, file);
+  } catch { /* best effort: the next call just re-scans */ }
+}
+
 /**
  * Read a session transcript and return its MOST RECENT handoff intent.
+ *
+ * Bounded per call: at most `maxBytes` examined within `budgetMs`. When `cacheDir` is
+ * given, progress is kept per transcript as a line-aligned offset + the newest intent
+ * line found + the lowest byte covered, so later calls scan only the appended bytes and
+ * (for a transcript larger than `maxBytes`) backfill one more window below the covered
+ * region until the whole file is proven to hold no intent. Hooks never rescan the whole
+ * transcript, yet an oversized session still becomes conclusive. Without `cacheDir` the
+ * scan is stateless (tail window only).
  * @returns {Promise<{ intent: 'fullstack'|'create'|null, known: boolean }>}
  *   `known=false` means the scan could not be completed (no path, unreadable,
- *   budget overrun); callers keep their existing blocking behaviour there.
+ *   budget overrun, torn newest evidence, region not yet covered); callers keep
+ *   their existing blocking behaviour there.
  */
 export async function transcriptHandoffIntent(transcriptPath, {
   budgetMs = INTENT_SCAN_BUDGET_MS,
   maxBytes = INTENT_SCAN_MAX_BYTES,
+  cacheDir = undefined,
 } = {}) {
   if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) {
     return { intent: null, known: false };
@@ -289,58 +440,60 @@ export async function transcriptHandoffIntent(transcriptPath, {
   let handle;
   try {
     handle = await fs.open(transcriptPath, 'r');
-    const stat = await handle.stat();
-    const size = Number(stat.size) || 0;
-    const start = Math.max(0, size - maxBytes);
+    const size = Number((await handle.stat()).size) || 0;
     const deadline = Date.now() + budgetMs;
-    const chunk = Buffer.allocUnsafe(Math.min(Math.max(1, size - start), 4 * 1024 * 1024));
-    let text = '';
-    let pos = start;
-    while (pos < size) {
-      if (Date.now() > deadline) return { intent: null, known: false };
-      const toRead = Math.min(chunk.length, size - pos);
-      const { bytesRead } = await handle.read(chunk, 0, toRead, pos);
-      if (!bytesRead) break;
-      text += chunk.toString('utf8', 0, bytesRead);
-      pos += bytesRead;
-    }
-    let lines = text.split('\n');
-    // A tail window starts mid-line: the first fragment is not a whole entry.
-    if (start > 0) lines = lines.slice(1);
-    for (let i = lines.length - 1; i >= 0; i -= 1) {
-      const line = lines[i];
-      if (!line) continue;
-      // Cheap prefilter — skip JSON.parse for lines that cannot be evidence.
-      // `handoff-implement` is included: an implement invocation after a create
-      // must be seen as the NEWEST intent, not lost to the older create line.
-      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('handoff-implement') && !line.includes('handoff-review') && !line.includes('handoff-status') && !line.includes('handoff-clear') && !line.includes('HANDOFF RESUME')) {
-        continue;
+    // One shared mechanism for every caller (Claude hook, omp bridge, Stop coordinator):
+    // an oversized transcript gets the incremental cache by default, rooted at this
+    // runtime's own project (<root>/.claude/ukit/runtime -> <root>/.ukit/storage/cache).
+    // `cacheDir:false|null` forces a stateless scan; small transcripts never need one.
+    if (cacheDir === undefined) cacheDir = size > maxBytes ? (process.env.UKIT_INTENT_CACHE_DIR || DEFAULT_INTENT_CACHE_DIR) : null;
+    const cacheFile = cacheDir ? path.join(cacheDir, `${fp(Buffer.from(path.resolve(transcriptPath))).slice(0, 24)}.json`) : null;
+    const cache = cacheFile ? await loadIntentCache(cacheFile, handle, size, maxBytes) : null;
+
+    let offset;
+    let covered;
+    let intent = null;
+    let evidence = null;
+    let persist = false;
+    // Step A: bytes the cache has not seen (the whole tail window on a cold start).
+    const a = await scanBack(handle, size, cache ? cache.offset : Math.max(0, size - maxBytes), Boolean(cache), deadline);
+    if (a.status === 'torn') return { intent: null, known: false };
+    if (cache) {
+      offset = a.lastNL >= 0 ? a.lastNL + 1 : cache.offset;
+      covered = cache.coveredFrom;
+      if (a.status === 'found') {
+        if (a.evidence.pos + a.evidence.len < offset) { intent = a.intent; evidence = a.evidence; persist = true; }
+        else intent = a.intent; // still being appended: answer now, cache once the line is complete
+      } else if (a.status === 'done') {
+        intent = cache.intent; evidence = cache.evidence; persist = offset !== cache.offset;
+      } else {
+        return { intent: null, known: false };
       }
-      // This is the NEWEST line carrying intent evidence. A host append can be
-      // cut mid-record (killed turn, torn write), leaving this line as unparseable
-      // JSON. Skipping it like any other non-qualifying line would fall through to
-      // an OLDER — possibly OPPOSITE — intent and misreport the session's current
-      // ownership (a torn `handoff-implement` after a create released a real
-      // fullstack run). An incomplete newest evidence-bearing record is therefore
-      // UNDETERMINED, not "no intent": return unknown so fail-closed callers keep
-      // their blocking/conservative posture (MODULE02-SPEC FR-M2-002).
-      let entry;
-      try {
-        entry = JSON.parse(line);
-      } catch {
+    } else {
+      offset = a.lastNL >= 0 ? a.lastNL + 1 : size;
+      covered = a.status === 'found' ? a.evidence.pos : a.reached;
+      if (a.status === 'found') { intent = a.intent; evidence = a.evidence; persist = a.evidence.pos + a.evidence.len < offset; }
+      else persist = a.lastNL >= 0 && covered <= offset;
+      if (a.status === 'timeout') {
+        if (persist && cacheFile) await saveIntentCache(cacheFile, handle, { offset, coveredFrom: covered, intent: null });
         return { intent: null, known: false };
       }
-      const intent = classifyHandoffEntry(entry);
-      if (intent) return { intent, known: true };
-      // Complete record that carries no recognised intent (tool output, a foreign
-      // envelope, a malformed-but-whole unrelated line): not evidence — keep
-      // walking older lines.
     }
-    // Nothing found. Only a scan of the WHOLE transcript proves "no handoff
-    // intent"; a tail window that missed it (the invoking turn usually appears
-    // once, near the start of an omp session) cannot, so it stays unknown and
-    // callers keep blocking.
-    return { intent: null, known: start === 0 };
+    // Step B: nothing newer — extend coverage one bounded window further down.
+    if (!intent && covered > 0) {
+      const room = Math.max(0, maxBytes - (size - (cache ? cache.offset : Math.max(0, size - maxBytes))));
+      if (room > 0) {
+        const b = await scanBack(handle, covered, Math.max(0, covered - room), false, deadline);
+        if (b.status === 'torn') return { intent: null, known: false };
+        if (b.status === 'found') { intent = b.intent; evidence = b.evidence; covered = b.evidence.pos; persist = true; }
+        else { covered = b.reached; persist = true; }
+      }
+    }
+    if (persist && cacheFile) await saveIntentCache(cacheFile, handle, { offset, coveredFrom: covered, intent, evidence });
+    // Only a scan of the WHOLE transcript proves "no handoff intent"; an uncovered
+    // region (the invoking turn usually appears once, near the start of an omp
+    // session) stays unknown and callers keep blocking.
+    return { intent, known: Boolean(intent) || covered === 0 };
   } catch {
     return { intent: null, known: false };
   } finally {

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

@@ -1176,7 +1176,7 @@ export async function runSessionStop(
     // Command authority (RC-A): same shared phase signal the Claude Stop path uses, so a
     // handoff-create/review session is never pushed toward Edit/Write on omp either.
     const phase = await resolveStopPhase(payload.transcript_path);
-    evaluation = evaluateCompletion({ state, ledger, phase });
+    evaluation = evaluateCompletion({ state, ledger, phase, cwd: projectRoot });
   } catch (error) {
     // BUG-C22-05: fail-closed like the shell gate (continue the turn), but only up
     // to the configured consecutive-crash cap — a persistently broken evaluator