@ngockhoale/ukit 3.4.56 → 3.4.57

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.57 - 2026-10-22
+
+**Completion Gate: background launch acknowledgements are not verification evidence; stale-contract reconciliation covers all obligation fields and the Stop boundary.**
+- Bug: a host-backgrounded Bash runner (`run_in_background`) answers with a launch acknowledgement (`backgroundTaskId` / "Command running in background with ID: …") that carries no exit status, yet the ledger minted a `test-verified` verdict from it. The ack now records an `unproven` verification receipt (`exitStatusUnproven`, not success); a foreground exit status is still required. Completion of the background job is a separate host event and is not accepted as evidence by this change.
+- Stale contract (3.4.56 follow-up): reconciliation now compares kind plus `operationGoal` / `configurationScope` / `releasePolicy` / `reportArtifact` and replaces classifier-owned fields wholesale (no leaked stale `operationGoal`); the Stop evaluator (`execution-ledger.mjs --evaluate-stop`) also reconciles in memory, so read-only / Bash-only tasks (which never trigger the router) no longer stay stuck. Only `contractOrigin: classified` contracts are eligible; system-carried and status-report contracts, and genuine MIXED/OPERATIONAL contracts, are unchanged.
+- Regression: `tests/hooks/backgroundLaunchAckNotEvidence.test.js`, extended `tests/hooks/staleContractRederive.test.js`.
+- Verified offline on macOS/Node 22; replay, not a live host.
+
 ## 3.4.56 - 2026-10-22
 
 **Completion Gate: a stale self-classified contract is re-derived from the task's own prompt on continuation.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.56",
+  "version": "3.4.57",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/template_project/.claude/hooks/skill-router.sh

@@ -3930,7 +3930,10 @@ function applyTaskSemantics(contract, semantic) {
       && !storedContract.statusReport && previous.routingContext?.lastExplicitUserPromptText) {
       try {
         const fresh = classifyTaskSemantics({ promptText: previous.routingContext.lastExplicitUserPromptText, targetFile: persisted.routingContext?.targetFile });
-        if (fresh?.taskKind && fresh.taskKind !== storedContract.taskKind) semanticFromPrompt = fresh;
+        // Compare every classifier-owned obligation field, not just the kind: a stale operationGoal /
+        // configurationScope / releasePolicy under an unchanged kind is the same false-obligation bug.
+        const sig = (c) => JSON.stringify([c?.taskKind, c?.operationGoal ?? null, c?.configurationScope ?? null, c?.releasePolicy?.kind ?? null, c?.reportArtifact ?? null]);
+        if (fresh?.taskKind && sig(fresh) !== sig(storedContract)) semanticFromPrompt = fresh;
       } catch {}
     }
     const semantic = semanticFromPrompt
@@ -3968,6 +3971,13 @@ function applyTaskSemantics(contract, semantic) {
       delete persisted.routeSummary.continuationState;
     } else if (semantic.taskKind !== 'CODE_IMPLEMENTATION' || persisted.routeSummary) {
       persisted.routeSummary ||= { executionMode: 'local-build' };
+      if (semanticFromPrompt && persisted.routeSummary.executionContract) {
+        // Re-derivation replaces the classifier-owned obligation fields wholesale: applyTaskSemantics
+        // spreads the old contract first, so a stale operationGoal / releasePolicy would survive.
+        const kept = { ...persisted.routeSummary.executionContract };
+        for (const key of ['operationGoal', 'configurationScope', 'releasePolicy', 'reportArtifact', 'verificationOnly', 'statusReport']) delete kept[key];
+        persisted.routeSummary.executionContract = kept;
+      }
       // A carried status-report contract must not leak its empty evidence / flag onto a
       // turn that is not itself a status lookup: rebuild the base contract instead.
       const carriedStatus = persisted.routeSummary.executionContract?.statusReport === true && !semantic.statusReport;

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

@@ -774,12 +774,24 @@ function maskedVerificationStage(command, depth = 0) {
 }
 
 // Announce through the in-proc hook emitter only (never fd 1 from library callers).
+// Host launch acknowledgement of a backgrounded Bash call (Claude Code: structured
+// `backgroundTaskId`, or the fixed "running in background" text). Structured field first.
+function isBackgroundLaunchAck(response) {
+  if (response && typeof response === 'object' && !Array.isArray(response)) {
+    if (typeof response.backgroundTaskId === 'string' && response.backgroundTaskId) return true;
+    if (response.exitCode !== undefined && response.exitCode !== null) return false;
+    return isBackgroundLaunchAck(response.stdout ?? response.output ?? response.content);
+  }
+  return typeof response === 'string'
+    && /^\s*Command running in background with ID: \S+/.test(response);
+}
+
 function noteUnprovenExitStatus(stage) {
   if (!ledgerMessageEmitter) return;
   const message =
     `UKit execution-ledger: runner exit status is unproven for \`${stage}\` — `
     + 'the shell wrapper may mask or skip the runner; it is NOT counted as passing verification. '
-    + 'Re-run the bare verification command in the same workspace, without loops, backgrounding or status-swallowing consumers.';
+    + 'Re-run the bare verification command in the same workspace, in the foreground (a host background launch acknowledgement carries no exit status), without loops or status-swallowing consumers.';
   try {
     ledgerMessageEmitter(`${JSON.stringify({ systemMessage: message })}\n`);
   } catch { /* an emitter failure never loses the ledger event */ }
@@ -3134,8 +3146,12 @@ export async function recordExecutionReceipt({
       taskInstanceId: routeState.taskInstanceId, workspaceFp };
   }
   const toolResponse = payload.tool_response ?? payload.tool_output ?? payload.tool_result;
+  // A host-backgrounded Bash call answers immediately with a launch acknowledgement: the
+  // command has not finished, so that response carries no exit status. It must never mint
+  // verification or operation evidence (completion arrives later, outside this tool event).
+  const backgroundLaunchAck = toolName === 'Bash' && isBackgroundLaunchAck(toolResponse);
   const nativeGoal = routeState?.routeSummary?.executionContract?.operationGoal;
-  const operationReceipt = cronOperationReceipt(toolName, toolInput, toolResponse, success, { sessionId: explicitSessionId(payload), harness })
+  const operationReceipt = backgroundLaunchAck ? null : cronOperationReceipt(toolName, toolInput, toolResponse, success, { sessionId: explicitSessionId(payload), harness })
     || (toolName === 'Bash' && !bashScope.foreign
       ? (bashOperationReceipt(toolInput.command, toolResponse, success, nativeGoal, { sessionId: explicitSessionId(payload), harness })
         || releaseOperationReceipt(toolInput.command, toolResponse, success, { sessionId: explicitSessionId(payload), harness }))
@@ -3166,7 +3182,11 @@ export async function recordExecutionReceipt({
     receipt.command = String(toolInput.command || '').trim();
     // A pipe-masked runner status (exit 0 from `| tail`) is not evidence of a pass.
     const maskedStage = isVerificationCommand(toolInput.command) ? maskedVerificationStage(toolInput.command) : null;
-    if (maskedStage && receipt.success) {
+    if (backgroundLaunchAck && receipt.success) {
+      receipt.success = false;
+      receipt.exitStatusUnproven = true;
+      noteUnprovenExitStatus(`${String(toolInput.command || '').trim().slice(0, 60)} (background launch)`);
+    } else if (maskedStage && receipt.success) {
       receipt.success = false;
       receipt.exitStatusUnproven = true;
       noteUnprovenExitStatus(maskedStage);
@@ -4467,6 +4487,26 @@ async function writeSeal(projectRoot, payload, state, result, ledger) {
   await writeJsonAtomic(file, Object.fromEntries(keep));
 }
 
+const CLASSIFIER_OWNED_FIELDS = ['operationGoal', 'configurationScope', 'releasePolicy', 'reportArtifact', 'verificationOnly', 'statusReport'];
+const contractSignature = (c) => JSON.stringify([c?.taskKind, c?.operationGoal ?? null, c?.configurationScope ?? null, c?.releasePolicy?.kind ?? null, c?.reportArtifact ?? null]);
+
+// Re-derive a router-classified contract from the task's own explicit prompt. Only a contract
+// this router classified itself (contractOrigin 'classified') is eligible: system-carried,
+// status-report and prompt-less states keep their stored contract. Fail-safe: any error keeps it.
+export async function reconcileStaleContract(projectRoot, state) {
+  try {
+    const stored = state?.routeSummary?.executionContract;
+    const prompt = state?.routingContext?.lastExplicitUserPromptText;
+    if (!stored?.taskKind || stored.statusReport || state.contractOrigin !== 'classified' || typeof prompt !== 'string' || !prompt.trim()) return state;
+    const resolver = await import(new URL('../index/route-resolver.mjs', import.meta.url).href);
+    const fresh = resolver.classifyTaskSemantics({ promptText: prompt, targetFile: state.routingContext?.targetFile });
+    if (!fresh?.taskKind || contractSignature(fresh) === contractSignature(stored)) return state;
+    const base = { ...stored };
+    for (const key of CLASSIFIER_OWNED_FIELDS) delete base[key];
+    return { ...state, routeSummary: { ...state.routeSummary, executionContract: resolver.applyTaskSemantics(base, fresh) } };
+  } catch { return state; }
+}
+
 async function runEvaluateStop() {
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   let payload;
@@ -4500,7 +4540,11 @@ async function runEvaluateStop() {
   }
 
   const phase = await resolveStopPhase(payload?.transcript_path);
-  let result = evaluateCompletion({ state, ledger, cwd: projectRoot, phase });
+  // The router only re-runs on prompt submit and Edit/Write, so a read-only / Bash-only task
+  // never heals a contract classified by an older classifier. Reconcile it from the task's own
+  // prompt at the gate boundary (in memory; the stored route state is left untouched).
+  const reconciled = await reconcileStaleContract(projectRoot, state);
+  let result = evaluateCompletion({ state: reconciled, ledger, cwd: projectRoot, phase });
   if (result.continue === true && !result.finalNotice) {
     try {
       const seal = await readSeal(projectRoot, payload, state?.taskInstanceId);