@ngockhoale/ukit 3.4.36 → 3.4.38

package/CHANGELOG.md

@@ -9,6 +9,20 @@ 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.38 - 2026-10-12
+
+**Completion Gate safety closure: mutation orders always get a contract; git sync needs authoritative remote proof.**
+- Issue 1 root cause: `isInformationalPrompt`'s consult-shape (a stray "Should I …?" / "…hay không" / "có phải") overrode a surviving imperative, so a real mutation order routed `informational` with no completion contract and Stop released with a non-blocking "nothing was verified" notice. Fix (router + `route-task.mjs` parity): a consult shape never demotes a prompt that still has a mutation order. Pure consults ("Should I fix X?") stay informational and never demand write evidence.
+- Issue 2: the 3.4.37 `git status -sb` `synced-state` proof read a local tracking ref (stale-able) and is removed. A masked commit/push is now discharged only by a standalone, unmasked `git ls-remote <remote> refs/heads/<branch>` observed after every mutation attempt whose sha equals live HEAD, on the branch's own tracking remote, with a clean worktree (gate-time `gitAuthority`). Remote behind, stale tracking ref, uncommitted changes, wrong remote/branch, forged/piped/failed output, other task/session: BLOCK.
+- Regressions through the real hook chain: `tests/hooks/completionClosure.test.js`; unit: `gitSyncPostcondition.test.js`. No real Windows run.
+
+## 3.4.37 - 2026-10-12
+
+**Completion Gate: a clean, in-sync branch observation discharges a masked commit+push.**
+- Root cause: commit/push run inside a heredoc/`;`/pipe chain correctly mint an exit-unproven (failed) mutation receipt, and no later independent observation could ever discharge the `git-integrity` goal, so a finished, published release kept blocking Stop with `operation-verification`.
+- Fix: a standalone whole-tree `git status -sb` that prints exactly one `## branch...upstream` line (clean, no ahead/behind/gone) after every recorded git mutation attempt is a trusted `synced-state` proof for commit/push goals. Piped/failed/dirty/ahead/behind/no-upstream/earlier/other-task observations never count.
+- Regression: `tests/hooks/gitSyncPostcondition.test.js` (RED on 3.4.36). No real Windows run.
+
 ## 3.4.36 - 2026-10-12
 
 **Completion Gate: a finished task (incl. a release) stays finished across wakeups, compaction and repeated Stops.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.36",
+  "version": "3.4.38",
   "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

@@ -2068,6 +2068,9 @@ function applyTaskSemantics(contract, semantic) {
       || /\b(?:chua|duoc khong|dung khong|khong nhi|nhi|roi)\s*[.!?]*\s*$/.test(folded)
       || (!politeAsk && /\b(?:khong|không)\s*[?.!]?\s*$/.test(folded))
       || /\bchi\s+(?:hoi|tu\s+van|giai\s+thich|xem)\b/.test(folded);
+      // P1: a consult-shaped clause ("Should I also bump…?", a Vietnamese tail) must never demote a prompt that
+      // still carries a real imperative order — otherwise the order loses its completion contract.
+      if (consultShape && hasMutationOrder({ promptText, commandText })) return false;
     if (scores) {
       if (!consultShape && (
         scores.implementSignal

package/template_project/.claude/ukit/index/route-task.mjs

@@ -4325,6 +4325,9 @@ function isInformationalPrompt({
     || /\b(?:chua|duoc khong|dung khong|khong nhi|nhi|roi)\s*[.!?]*\s*$/.test(folded)
     || (!politeAsk && /\b(?:khong|không)\s*[?.!]?\s*$/.test(folded))
     || /\bchi\s+(?:hoi|tu\s+van|giai\s+thich|xem)\b/.test(folded);
+    // P1: a consult-shaped clause ("Should I also bump…?", a Vietnamese tail) must never demote a prompt that
+    // still carries a real imperative order — otherwise the order loses its completion contract.
+    if (consultShape && hasMutationOrder({ promptText, commandText })) return false;
   if (scores) {
     if (!consultShape && (
       scores.implementSignal

package/template_project/.claude/ukit/runtime/cron-operation-adapter.mjs

@@ -51,6 +51,10 @@ const GIT_MUTATION = /^git\s+(?:push|commit|clean|reset|merge|rebase|stash|tag|c
 const GIT_VERB = /^git\s+(push|commit|clean|reset|merge|rebase|stash|tag|checkout|restore|pull|cherry-pick|branch)\b/;
 const GIT_STATE = /^git\s+(?:fsck\b|diff\s+(?:--check|--exit-code|--quiet)\b|status\s+(?:--porcelain|-s|--short)\b)/;
 const SERVICE_MUTATION = /^(?:docker(?:\s+compose)?|docker-compose)\s+(?:restart|up|down|stop|start|build)\b|^(?:sudo\s+)?systemctl\s+(?:restart|start|stop|reload)\b|^pm2\s+(?:restart|reload|start)\b|^kubectl\s+(?:rollout|apply)\b|^launchctl\s+kickstart\b|^(?:\.\/)?(?:scripts\/)?deploy[\w.-]*(?:\s|$)|^(?:npm|yarn|pnpm)\s+(?:run\s+)?deploy\b/;
+// Authoritative remote observation: `git ls-remote <remote> refs/heads/<branch>` asks the remote itself (a local
+// tracking ref / `git status -sb` can be stale). The gate later requires that sha to equal live HEAD on the
+// branch's own tracking remote with a clean tree, so a masked commit/push is recovered without re-running it.
+const GIT_LS_REMOTE = /^git\s+ls-remote\s+(\S+)\s+(refs\/heads\/\S+)\s*$/;
 const DRY_RUN = /(?:^|\s)(?:--dry-run|--check|--no-act|-n)(?:\s|=|$)/;
 const CURL = /^curl\s/;
 function requiredTargetOf(segment, required) {
@@ -68,11 +72,20 @@ export function bashOperationReceipt(command, response, transportSuccess, goal,
   const real = command.split('&&').map((seg) => seg.trim());
   const text = responseText(response);
   const hasOutputField = typeof response === 'string' || typeof response?.stdout === 'string' || typeof response?.output === 'string';
-  let role = null; let proven = false; let target = null;
+  let role = null; let proven = false; let target = null; let remoteSync = null;
   for (const seg of real) {
     if (!seg || /^cd\s+\S+$/.test(seg) || DRY_RUN.test(seg.replace(/'[^']*'|"[^"]*"/g, '""'))) continue;
     if (domain === 'git-integrity') {
-      if (GIT_STATE.test(seg)) {
+      const lsRemote = seg.match(GIT_LS_REMOTE);
+      if (lsRemote) {
+        const lines = text.split('\n').map((l) => l.trimEnd()).filter(Boolean);
+        const hit = hasOutputField && lines.length === 1 ? lines[0].match(/^([0-9a-f]{40}|[0-9a-f]{64})\t(refs\/heads\/\S+)$/) : null;
+        role = 'state';
+        if (hit && hit[2] === lsRemote[2] && lsRemote[1].length <= 256 && lsRemote[2].length <= 256) {
+          remoteSync = { remote: lsRemote[1], ref: hit[2], sha: hit[1] };
+          proven = true;
+        }
+      } else if (GIT_STATE.test(seg)) {
         const wanted = goal.check;
         const kind = /\bfsck\b/.test(seg) ? 'fsck' : /\bdiff\b/.test(seg) ? 'diff-check' : 'status';
         // `-- <pathspec>` / extra paths narrow the check; only a whole-tree status proves a clean tree.
@@ -106,7 +119,7 @@ export function bashOperationReceipt(command, response, transportSuccess, goal,
   return { kind: 'operation', success: ok, transportSuccess: transportSuccess === true, harness,
     ...(masked ? { exitStatusUnproven: true } : {}),
     operation: { domain, role, scope, target: role === 'state' ? null : target,
-      ...(role === 'state' ? { state: 'verified', complete: ok } : {}) } };
+      ...(role === 'state' ? { state: 'verified', complete: ok, ...(remoteSync && ok ? { remoteSync } : {}) } : {}) } };
 }
 
 // Release evidence: `npm publish` and `npm view <pkg> version` as REAL Bash tool results. The command must

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

@@ -3004,7 +3004,7 @@ function requiredEvidence(state = {}) {
 function evidenceSatisfied(evidence, ledger = {}, state = {}, { cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
   if (evidence === 'operation-verification') {
-    return operationCompletionPolicy(scopedContract(state, ledger), null, ledger)?.complete === true;
+    return operationCompletionPolicy(scopedContract(state, ledger), null, withGitAuthority(ledger, cwd))?.complete === true;
   }
   if (evidence === 'write-evidence') {
     const expected = routeSummary.expectedSourceFiles || [];
@@ -3272,6 +3272,21 @@ function scopedContract(state, ledger) {
     scope: contract.operationGoal.scope || (session ? `session:${session}` : null) } };
 }
 
+// Gate-time local git truth for the remote-parity proof (cwd-bound, so it lives here, not in the pure evidence module).
+function gitAuthority(cwd) {
+  if (!cwd) return null;
+  const head = gitOutput(['rev-parse', 'HEAD'], cwd);
+  const branch = gitOutput(['symbolic-ref', '--short', 'HEAD'], cwd);
+  if (!head || !branch) return null;
+  const remote = gitOutput(['config', `branch.${branch}.remote`], cwd);
+  const dirty = gitOutput(['status', '--porcelain'], cwd);
+  return { head, branch, remote, clean: dirty === null && gitOutput(['rev-parse', '--git-dir'], cwd) !== null };
+}
+function withGitAuthority(ledger, cwd) {
+  const gitAuth = ledger && Object.keys(ledger).length ? gitAuthority(cwd) : null;
+  return gitAuth ? { ...ledger, gitAuthority: gitAuth } : ledger;
+}
+
 function effectiveRequestLedger(state = {}, ledger = {}) {
   if (state?.sessionId && ledger?.sessionId && state.sessionId !== ledger.sessionId) return {};
   if (state?.taskInstanceId || ledger?.taskInstanceId) {
@@ -3394,7 +3409,7 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
   // continuation budget — the request already accumulated. A different prompt keeps a clean slate.
   const effectiveLedger = effectiveRequestLedger(state, ledger);
   const operationStatus = operationCompletionPolicy(scopedContract(state, effectiveLedger),
-    null, effectiveLedger);
+    null, withGitAuthority(effectiveLedger, cwd));
   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');

package/template_project/.claude/ukit/runtime/operation-evidence.mjs

@@ -1,5 +1,6 @@
 // Adapter-normalized proof only; neither native output nor agent prose is evidence here.
 const MAX_OPERATIONS = 16;
+const validRemoteSync = (r) => Boolean(r) && typeof r === 'object' && ['remote', 'ref', 'sha'].every((k) => typeof r[k] === 'string' && r[k].length > 0 && r[k].length <= 256);
 export function compactOperation(operation) {
   if (!operation || typeof operation !== 'object' || Array.isArray(operation)) return { invalid: true };
   const bounded = (value) => typeof value === 'string' && value.length > 0 && value.length <= 256;
@@ -12,7 +13,7 @@ export function compactOperation(operation) {
   return { domain: operation.domain, scope: operation.scope, role: operation.role, target: operation.target,
     ...(operation.state !== undefined ? { state: operation.state } : {}),
     ...(operation.presentTargets !== undefined ? { presentTargets: operation.presentTargets === null ? null : [...operation.presentTargets] } : {}),
-    complete: operation.complete === true };
+    complete: operation.complete === true, ...(validRemoteSync(operation.remoteSync) ? { remoteSync: { ...operation.remoteSync } } : {}) };
 }
 export function foldOperationEvidence(bank = {}, receipt, ledger) {
   const raw = receipt?.operation;
@@ -46,6 +47,7 @@ export function foldOperationEvidence(bank = {}, receipt, ledger) {
       ...(op.state !== undefined ? { state: op.state } : {}),
       ...(op.presentTargets !== undefined ? { presentTargets: [...op.presentTargets] } : {}),
       complete: op.complete === true,
+      ...(validRemoteSync(op.remoteSync) ? { remoteSync: { ...op.remoteSync } } : {}),
     } };
   return { ...bank, seenToolUseIds: receipt.toolUseId ? [...seen, receipt.toolUseId] : seen,
     [key]: { ...prior, [op.role]: proof } };
@@ -75,6 +77,15 @@ export function operationEvidenceStatus(goal, ledger = {}) {
     && (absent || (!Object.hasOwn(op || {}, 'presentTargets') && op?.target === goal.target));
   if (!observation?.success || !observation.toolUseId || !Number.isSafeInteger(observation.sequence)
     || op.complete !== true || !stateMatches) return incomplete;
+  // Independent postcondition (masked/failed commit+push recovery): the REMOTE itself (git ls-remote, observed
+  // after every mutation attempt) must report live HEAD on this branch's own tracking remote, with a clean tree.
+  // `ledger.gitAuthority` is the gate-time local truth; without it (or on any mismatch) nothing is proven.
+  const auth = ledger.gitAuthority;
+  if (goal.domain === 'git-integrity' && validRemoteSync(op.remoteSync) && auth && auth.clean === true
+    && requiredTargets.every((t) => t === 'commit' || t === 'push')
+    && attempts.every((r) => observation.sequence > r.sequence)
+    && op.remoteSync.sha === auth.head && op.remoteSync.ref === `refs/heads/${auth.branch}`
+    && op.remoteSync.remote === auth.remote) return { complete: true, operationProof: 'remote-parity' };
   if (goal.completionSemantics === 'ensure-state' && attempts.length === 0) {
     return { complete: true, operationProof: 'desired-state-only' };
   }