@ngockhoale/ukit 3.4.38 → 3.4.40

package/CHANGELOG.md

@@ -9,6 +9,21 @@ All notable changes to UKit are documented here.
 - New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
 - Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
 
+## 3.4.40 - 2026-10-12
+
+**Completion Gate: a read-only request no longer owes `impact-evidence` it can never produce.**
+- Root cause: a `READ_ONLY` contract (analysis of Markdown/logs/prompt text, read-only production inspection) carried `impact-evidence`, satisfied only by a source-read receipt. Answers drawn from docs, logs or text already in the prompt yield none, so Stop demanded further tool activity and looped into the loop breaker.
+- Fix: for `READ_ONLY` with no named target files and no attempted write, `impact-evidence` is not applicable. A named target still needs its read; any attempted write (unauthorized side effect) keeps the obligation; mutation orders keep write/verification/operation proof.
+- Regressions: `tests/hooks/completionGateRequestScope.test.js` (cross-request scope after an edit request, read-only inspection, missing contract, unauthorized write). Test allowlist gains the runtime-only `docs/AI_HANDOFF/RUN.md` cursor reference.
+
+## 3.4.39 - 2026-10-12
+
+**Completion Gate: unrelated compound commands no longer erase authoritative git evidence; seals honour operation freshness.**
+- Root cause: a compound command such as `git rev-parse HEAD && git status --porcelain && npm view …` was parsed as a whole-tree `git status`, its mixed stdout read as a dirty tree, and that failed state record replaced the earlier valid `git ls-remote` proof (`missing operation-verification`).
+- Fix: a git state observation is only minted from ONE unmasked, transport-successful command; compound/masked/failed ones mint nothing and cannot overwrite proof. A standalone dirty status or a diverged remote still invalidates earlier success.
+- Seals now record the operation sequence: a later git mutation, failed state observation, or remote sha != HEAD voids the seal (previously only content fingerprint did).
+- Regressions: `completionClosure.test.js` (full 7-step sequence through the real hook chain), `gitSyncPostcondition.test.js`. No real Windows run.
+
 ## 3.4.38 - 2026-10-12
 
 **Completion Gate safety closure: mutation orders always get a contract; git sync needs authoritative remote proof.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.38",
+  "version": "3.4.40",
   "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/ukit/runtime/cron-operation-adapter.mjs

@@ -115,6 +115,11 @@ export function bashOperationReceipt(command, response, transportSuccess, goal,
     }
   }
   if (!role) return null;
+  // A git STATE observation is attributable only when it is one unmasked, transport-successful command: in a
+  // compound/masked chain the stdout of its parts is mixed, so it can neither prove nor refute the state and
+  // must not overwrite earlier authoritative evidence. (A standalone dirty status still records as failed.)
+  if (domain === 'git-integrity' && role === 'state'
+    && (masked || transportSuccess !== true || real.filter((seg) => seg && !/^cd\s+\S+$/.test(seg)).length !== 1)) return null;
   const ok = transportSuccess === true && !masked && Boolean(scope) && (role === 'mutation' || proven);
   return { kind: 'operation', success: ok, transportSuccess: transportSuccess === true, harness,
     ...(masked ? { exitStatusUnproven: true } : {}),

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

@@ -3413,6 +3413,16 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
   const operationalTask = operationStatus !== null;
   const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, state, { cwd }));
   if (operationalTask && !operationStatus.complete && !missingEvidence.includes('operation-verification')) missingEvidence.push('operation-verification');
+  // A READ_ONLY request's deliverable is the reply: it may be answered from Markdown, logs or
+  // text already in the prompt, none of which yields a source-read receipt, so impact-evidence
+  // is NOT_APPLICABLE to it when no target files were named (request-scoped — never inherited from an earlier edit request in
+  // the same session). Any attempted write keeps the obligation: an unauthorized side effect
+  // of a read-only request is never treated as irrelevant.
+  if (routeSummary.executionContract?.taskKind === 'READ_ONLY' && effectiveLedger.writeAttempted !== true
+    && !(Array.isArray(routeSummary.expectedSourceFiles) && routeSummary.expectedSourceFiles.length > 0)) {
+    const at = missingEvidence.indexOf('impact-evidence');
+    if (at !== -1) missingEvidence.splice(at, 1);
+  }
   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
@@ -3793,14 +3803,39 @@ async function readSeal(projectRoot, payload, taskInstanceId) {
   return seal && typeof seal === 'object' ? seal : null;
 }
 
-async function writeSeal(projectRoot, payload, state, result) {
+// Operation freshness of a seal: the newest operation-proof sequence at seal time. After it, any NEW mutation
+// attempt, any failed state observation, or a remote observation whose sha is no longer HEAD voids the seal
+// (successful unrelated observations do not). Content fingerprint alone cannot see remote/mutation changes.
+function operationSeq(ledger) {
+  let max = 0;
+  for (const [key, entry] of Object.entries(ledger?.operationBank || {})) {
+    if (key === 'seenToolUseIds' || key === 'overflow') continue;
+    for (const proof of [entry?.mutation, entry?.state]) if (Number.isSafeInteger(proof?.sequence)) max = Math.max(max, proof.sequence);
+  }
+  return max;
+}
+function sealOperationsFresh(seal, ledger, projectRoot) {
+  const since = Number.isSafeInteger(seal?.opSeq) ? seal.opSeq : 0;
+  const head = gitOutput(['rev-parse', 'HEAD'], projectRoot);
+  for (const [key, entry] of Object.entries(ledger?.operationBank || {})) {
+    if (key === 'seenToolUseIds' || key === 'overflow') continue;
+    if (entry?.mutation?.sequence > since) return false;
+    const st = entry?.state;
+    if (!st) continue;
+    if (st.sequence > since && st.success !== true) return false;
+    if (st.operation?.remoteSync && st.operation.remoteSync.sha !== head) return false;
+  }
+  return !ledger?.operationBank?.overflow;
+}
+
+async function writeSeal(projectRoot, payload, state, result, ledger) {
   const taskInstanceId = state?.taskInstanceId;
   const contentFp = contentFingerprint(projectRoot);
   if (!taskInstanceId || !contentFp || result.complete !== true) return;
   if (!(requiredEvidence(state).length > 0)) return;
   const file = sealPath(projectRoot, payload);
   const seals = await readJson(file, {}) || {};
-  seals[taskInstanceId] = { contentFp, headSha: gitOutput(['rev-parse', 'HEAD'], projectRoot), ts: Date.now() };
+  seals[taskInstanceId] = { contentFp, headSha: gitOutput(['rev-parse', 'HEAD'], projectRoot), opSeq: operationSeq(ledger), ts: Date.now() };
   const keep = Object.entries(seals).sort((a, b) => (b[1]?.ts || 0) - (a[1]?.ts || 0)).slice(0, SEAL_MAX);
   await fs.mkdir(path.dirname(file), { recursive: true });
   await writeJsonAtomic(file, Object.fromEntries(keep));
@@ -3843,12 +3878,12 @@ async function runEvaluateStop() {
   if (result.continue === true && !result.finalNotice) {
     try {
       const seal = await readSeal(projectRoot, payload, state?.taskInstanceId);
-      if (seal?.contentFp && contentFingerprint(projectRoot) === seal.contentFp) {
+      if (seal?.contentFp && contentFingerprint(projectRoot) === seal.contentFp && sealOperationsFresh(seal, ledger, projectRoot)) {
         result = { continue: false, notify: false, complete: true, missingEvidence: [], gateRelease: 'sealed-complete' };
       }
     } catch { /* a seal read failure keeps the strict gate */ }
   } else if (result.complete === true && (!result.gateRelease || result.gateRelease === 'native-operation-verified')) {
-    try { await writeSeal(projectRoot, payload, state, result); } catch { /* advisory */ }
+    try { await writeSeal(projectRoot, payload, state, result, ledger); } catch { /* advisory */ }
   }
 
   // TASK-C85-019 fix C: a mutating-mode route released by a no-mutation valve