@ngockhoale/ukit 3.4.25 → 3.4.26

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.26 - 2026-10-08
+
+**P1 fix: completion gate no longer reports `missing write-evidence` for tracked-file changes made through Bash.**
+- `execution-ledger`: a Bash receipt records a git workspace fingerprint (HEAD + hash of `git diff HEAD`, tracked files only). When it differs from the previous receipt, a synthetic write is applied. First observation, git failure/timeout, non-git directories and untracked files record nothing (fail-closed).
+- Strictly read-only Bash (`ls`, `cat`, `git status`, ...) and verification commands absorb the delta into the baseline instead of earning a write, so a background process or subagent edit is not credited to the main agent.
+- Evidence tier: a Bash-derived write is `inferred` (`evidenceTier: 'inferred'`, supporting evidence); only Edit/Write is direct. Inferred writes never satisfy `verification-evidence`.
+- Known limits: the first Bash of a session only seeds the baseline, so a mutation made by that very command is not credited; a delta that coincides with a non-read-only Bash is still attributed to it (inferred, not proof).
+- Regression tests: `tests/hooks/bashMutationEvidence.test.js` (12 cases).
+- Not included: AWAITING_USER stop handling (separate bug); `isVerificationCommand` coverage for commands such as `yarn release:verify`.
+
 ## 3.4.25 - 2026-10-08
 
 **P0 hotfix: Stop hook no longer force-continues a run the user paused or cancelled.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.25",
+  "version": "3.4.26",
   "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/execution-ledger.mjs

@@ -549,6 +549,52 @@ function gitOutput(args, cwd) {
   }
 }
 
+// Verifiable Bash-mutation evidence: a Bash command is never a write by itself. It counts
+// only when the TRACKED git workspace fingerprint (HEAD + content hash of `git diff HEAD`)
+// differs from the one recorded at the previous receipt. Any git failure, timeout or
+// oversize diff yields null, and null never creates evidence (fail-closed). Untracked files
+// are deliberately excluded: runtime state under .ukit/ would otherwise look like a change.
+function workspaceFingerprint(cwd) {
+  if (!cwd) return null;
+  try {
+    const run = (args) => execFileSync('git', args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    const head = String(run(['rev-parse', 'HEAD'])).trim();
+    if (!head) return null;
+    const diffHash = crypto.createHash('sha256').update(run(['diff', 'HEAD', '--no-ext-diff'])).digest('hex');
+    return `${head.slice(0, 12)}:${diffHash.slice(0, 16)}`;
+  } catch {
+    return null;
+  }
+}
+
+// A workspace delta cannot be attributed to the Bash call that happened to observe it: a
+// background process or a subagent may have changed the tree in between. The classifier below
+// only ever REMOVES credit — a command it recognises as strictly read-only never receives a
+// delta write (the delta is absorbed into the baseline). It never grants credit by itself;
+// unrecognised commands are merely eligible, and their write stays tier "inferred".
+const READ_ONLY_BASH = new Set([
+  'ls', 'cat', 'head', 'tail', 'wc', 'pwd', 'echo', 'printf', 'grep', 'rg', 'cd', 'which',
+  'stat', 'file', 'diff', 'sort', 'uniq', 'date', 'env', 'true', 'test', '[', 'basename', 'dirname',
+]);
+const READ_ONLY_GIT = new Set(['status', 'diff', 'log', 'show', 'rev-parse', 'ls-files', 'blame', 'describe', 'merge-base']);
+
+function isReadOnlyBashCommand(command) {
+  const text = String(command || '').trim();
+  if (!text || /[>`]|\$\(|<\(|\btee\b|\s-i\b|--in-place|-exec\b|-delete\b/.test(text)) return false;
+  return text.split(/&&|\|\||;|\||\n/).every((segment) => {
+    const words = segment.trim().split(/\s+/).filter(Boolean);
+    while (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) words.shift();
+    if (words.length === 0) return false;
+    if (words[0] === 'git') return READ_ONLY_GIT.has(words.find((w, i) => i > 0 && !w.startsWith('-')) || '');
+    return READ_ONLY_BASH.has(words[0]);
+  });
+}
+
 // A diff whose changed paths are all tests/docs/lint-format config is
 // stale-but-recoverable: one rebuild at current head restores currency.
 const RECOVERABLE_DIFF_PATH = /(^|\/)(docs\/|[^/]*\.md$)|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|specs?|__tests__)\/|(?:^|\/)\.?eslint|\.prettierrc|biome\.json|\.editorconfig|tsconfig.*\.json$/i;
@@ -899,6 +945,11 @@ function carriedEvidenceLedger(fresh, current) {
       || current.targetedVerificationSucceeded === true,
     sourceFiles: [...new Set([...(current.sourceFiles || []), ...(fresh.sourceFiles || [])])]
       .slice(-MAX_SOURCE_FILES),
+    // Workspace baseline for Bash-mutation attribution: same-prompt re-keys keep it (the router
+    // re-keys on every tool call); a different prompt returns `fresh` above and re-seeds.
+    workspaceFp: current.workspaceFp || fresh.workspaceFp || null,
+    inferredWrite: fresh.inferredWrite === true || current.inferredWrite === true,
+    directWrite: fresh.directWrite === true || current.directWrite === true,
     writeAttempted: fresh.writeAttempted || current.writeAttempted === true,
     writeSucceeded: fresh.writeSucceeded || current.writeSucceeded === true,
     verificationAttempted: fresh.verificationAttempted || current.verificationAttempted === true,
@@ -1032,7 +1083,7 @@ const MAX_JOURNAL_SEEN = 64;
 const MAX_JOURNAL_RECORDS = 128;
 const MAX_JOURNAL_QUARANTINE_LINES = 32;
 const LEDGER_EVENT_TYPES = new Set(['receipt', 'continuation', 'notified', 'stop-progress', 'resumable-run']);
-const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding']);
+const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding', 'workspace']);
 
 function journalPathFor(target) {
   return `${target}.journal`;
@@ -1151,7 +1202,7 @@ function newEventId() {
   return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
 }
 
-const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope'];
+const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'bashReadOnly'];
 
 // TASK-009 (BL-011): evidence attestations are whitelisted verbatim — class /
 // surface / result / claim, the ARCH §Evidence Schema fields a receipt may
@@ -1605,7 +1656,36 @@ function applyBugFixFloorReceipt(ledger, receipt) {
   return receipt;
 }
 
-function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
+// Folds the workspace fingerprint into the ledger, then applies the receipt itself. A
+// successful Bash receipt whose fingerprint moved since the last receipt is additionally
+// applied as a synthetic write (fingerprint equality is the only evidence — never the
+// command text). A first observation only seeds the baseline.
+function applyReceiptToLedger(ledger, receipt, options = {}) {
+  if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
+  const fp = typeof receipt.workspaceFp === 'string' && receipt.workspaceFp ? receipt.workspaceFp : null;
+  let base = ledger;
+  if (fp) {
+    const prior = ledger?.workspaceFp || null;
+    base = { ...ledger, workspaceFp: fp };
+    if (prior && prior !== fp && receipt.kind === 'workspace' && receipt.toolName === 'Bash' && receipt.success === true && receipt.bashReadOnly !== true) {
+      const applied = applyReceiptCore(base, {
+        ts: receipt.ts,
+        kind: 'write',
+        toolName: 'Bash',
+        toolUseId: receipt.toolUseId,
+        success: true,
+        exitCode: receipt.exitCode,
+        file: `bash-workspace:${fp}`,
+        detail: 'bash-workspace-delta',
+      }, options);
+      if (applied) base = applied.ledger;
+    }
+  }
+  if (receipt.kind === 'workspace') return { ledger: base, value: null };
+  return applyReceiptCore(base, receipt, options);
+}
+
+function applyReceiptCore(ledger, receipt, { vibecode = false } = {}) {
   if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
   const next = { ...ledger };
   if (receipt.kind === 'source') {
@@ -1616,6 +1696,10 @@ function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
   } else if (receipt.kind === 'write') {
     next.writeAttempted = true;
     next.writeSucceeded = next.writeSucceeded || receipt.success;
+    // Evidence tier: a fingerprint-derived Bash delta is inferred (supporting) evidence; only a
+    // tool-attributed Edit/Write is direct.
+    if (receipt.detail === 'bash-workspace-delta') next.inferredWrite = true;
+    else if (receipt.success) next.directWrite = true;
     // A mutation attempt between failures breaks the "no change in between" loop shape.
     if (next.failedVerificationStreak) next.failedVerificationStreak = null;
     // TASK-026 fix round 1: bank the FIRST successful write to this target. Later replays of
@@ -2166,6 +2250,7 @@ export async function recordExecutionReceipt({
   const success = !failed && (exitCode === null || exitCode === 0);
   const toolInput = payload.tool_input || {};
   const evidence = receiptEvidenceAttestation(payload, toolInput);
+  const workspaceFp = workspaceFingerprint(projectRoot);
   const receipt = {
     ts: Date.now(),
     toolName,
@@ -2203,10 +2288,18 @@ export async function recordExecutionReceipt({
     if (isVerificationCommand(toolInput.command)) {
       receipt.verdict = mintVerificationVerdict(receipt, payload, projectRoot);
     }
+  } else if (toolName === 'Bash' && workspaceFp) {
+    // Any other Bash: no evidence of its own. The receipt only carries the workspace
+    // fingerprint so a verifiable tracked-file change can be attributed at apply time.
+    receipt.kind = 'workspace';
   } else {
     // Untracked tool: no event, no lock, no write — same as the old unlocked early return.
     return { rejected: true, eventId: null };
   }
+  if (workspaceFp) {
+    receipt.workspaceFp = workspaceFp;
+    if (toolName === 'Bash' && isReadOnlyBashCommand(toolInput.command)) receipt.bashReadOnly = true;
+  }
   if (evidence) {
     receipt.evidence = evidence;
   }
@@ -2474,6 +2567,12 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}, {
   return instruction ?? 'Complete the current routed milestone before stopping.';
 }
 
+// Write evidence that exists only as a Bash workspace delta is supporting evidence, labelled so
+// consumers never mistake it for tool-attributed proof. It never satisfies verification.
+function writeEvidenceTier(ledger = {}) {
+  return ledger.inferredWrite === true && ledger.directWrite !== true ? { evidenceTier: 'inferred' } : {};
+}
+
 export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
   // Explicit vibecode autonomy: the user asked UKit to run one prompt to a finished result,
@@ -2581,6 +2680,7 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
         complete: true,
         outcome: 'verified',
         missingEvidence: [],
+        ...writeEvidenceTier(effectiveLedger),
       };
     }
   }
@@ -2588,7 +2688,7 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     // Silent success: the route is present and every required evidence is satisfied. Marked
     // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
     // bare loud else would turn a clean stop into user-visible noise.
-    return { continue: false, notify: false, complete: true, missingEvidence: [] };
+    return { continue: false, notify: false, complete: true, missingEvidence: [], ...writeEvidenceTier(effectiveLedger) };
   }
 
   // `find-cause` can validly end clean: an investigation may establish that no actionable