@ngockhoale/ukit 3.4.42 → 3.4.44

package/CHANGELOG.md

@@ -9,6 +9,23 @@ 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.44 - 2026-10-14
+
+**Completion Gate scope and permission-choice preservation.**
+- Publish refusals in Vietnamese, including accented/uppercase `chưa`, `không` and `ĐỪNG`, no longer create publication obligations. Real publication requests still require registry evidence and release-tag consistency.
+- Conditional cron cancellation verifies the requested absence using a fresh native observation without inventing successful deletion. Existing in-flight contracts reconcile only the same conditional absence goal; mixed code tasks retain write/verification requirements.
+- Blockers are task-scoped in Stop and unfinished-work detection. Current blockers end explicitly BLOCKED, never COMPLETE; previous-task blockers cannot discharge new-task verification.
+- Preserve the established bypass startup template and explicit user permission choices. Instructions distinguish UKit workflow PLAN from host permission mode; these are preventive boundaries, not a runtime mode lock.
+- **The reported Claude Code extension spontaneous permission-mode switch remains OPEN and is not claimed fixed.** The two VS Code User startup settings configured on the owner's machine are local settings, not distributed by this npm package.
+- Includes the previously unreleased manual-only `/ukit:ci-check` tooling above; this release does not dispatch GitHub Actions.
+
+## 3.4.43 - 2026-10-13
+
+**Completion Gate: an ordered `git tag` is discharged by the tag itself, so the live release Stop is accepted.**
+- Live root cause (3.4.42 still blocked this session): the prompt ordered a tag, so the git-integrity goal required target `tag`. A real tag created inside a compound command (`... && git tag ...; echo $?`) is a masked mutation and records as failed, and the independent remote-parity recovery only accepted `commit`/`push` targets, so `operation-verification` stayed missing although the tag, remote and registry were all correct.
+- Fix: the gate-time git authority also lists the tags that dereference to live HEAD (`git tag --points-at HEAD`, peels annotated tags). When `tag` is a required target, a tag at HEAD plus the existing remote-parity proof (remote sha == HEAD on the tracking remote, clean tree, observed after every mutation attempt) recovers it. No tag at HEAD, a diverged remote, a dirty tree or a later mutation still blocks.
+- Regressions in `tests/hooks/stopHookRelease.test.js`: masked tag with an annotated tag at HEAD -> ACCEPT (fails without the fix); no tag at HEAD -> BLOCK.
+
 ## 3.4.42 - 2026-10-13
 
 **Completion Gate: `cd <repo>; <command>` is a checked command, so a finished release is recognized by the live Stop hook.**

package/manifests/documentation.yaml

@@ -407,6 +407,17 @@ entries:
     load_policy: never
     validation: [none]
     archive_policy: immutable
+  - id: docs-analysis-claude-permission-mode
+    path: docs/analysis/CLAUDE_PERMISSION_MODE.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/CLAUDE_PERMISSION_MODE.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: owner-decides
+    notes: bounded investigation evidence; extension transition remains OPEN
   - id: docs-analysis-subagent-cost-audit
     path: docs/analysis/SUBAGENT-COST-AUDIT.md
     class: archive

package/manifests/instructionRules.yaml

@@ -120,7 +120,10 @@ rules:
       Under orchestration.permissionMode: unattended there is no human in the
       loop — the loop is UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX →
       REVERIFY → COMPLETE, and a turn ends only on COMPLETE evidence, a real
-      external blocker, or a deny decision.
+      external blocker, or a deny decision. Workflow phases do not authorize
+      changing the user-owned host permission mode: internal PLAN is not host
+      Plan Mode. Honor managed policy, newer user choices, and parent/subagent
+      and session boundaries.
     marker_in: [template_project/CLAUDE.md, template_project/AGENTS.md, CLAUDE.md, AGENTS.md]
     anchor: 'no human in the loop'
   - id: UNATTENDED-02

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.42",
+  "version": "3.4.44",
   "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/index/route-resolver.mjs

@@ -1121,13 +1121,16 @@ export function classifyTaskSemantics({ promptText = '', targetFile = '' } = {})
     && /\b(?:check|status|report|show|summari[sz]e|result|results|kiem tra|bao cao|trang thai|ket qua)\b/.test(text);
   const readOnly = (/\b(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(text) || statusReport)
     && !sourceOrder && !codeChangeVerb && !operation && !config;
-  const taskKind = operation ? (sourceOrder || (nativeDomain !== 'scheduled-job' && codeChangeVerb) ? 'MIXED' : 'OPERATIONAL')
+  const taskKind = operation ? (sourceOrder || codeChangeVerb ? 'MIXED' : 'OPERATIONAL')
     : config ? 'CONFIGURATION' : readOnly ? 'READ_ONLY' : 'CODE_IMPLEMENTATION';
   const id = text.match(/\b[a-f0-9]{8}(?:[a-f0-9-]{0,28})\b/)?.[0] || null;
   return { taskKind, ...(taskKind === 'READ_ONLY' && statusReport ? { statusReport: true } : {}), ...(config ? { configurationScope: repository ? 'repository' : 'external' } : {}),
     ...(operation && nativeDomain !== 'scheduled-job' ? { operationGoal: nativeOperationGoal(nativeDomain, actionable, text) } : {}),
     ...(operation && nativeDomain === 'scheduled-job' ? { operationGoal: { domain: 'scheduled-job', target: id, desiredState: /\b(?:delete|remove|cancel|xoa|huy|absent|removed|deleted|no longer|khong con)\b/.test(actionable.join(' ')) ? 'absent' : 'present',
-      completionSemantics: /\b(?:ensure|dam bao)\b/.test(text) ? 'ensure-state' : 'execute-and-verify' } } : {}) };
+      completionSemantics: /\b(?:ensure|dam bao)\b/.test(text)
+        || actionable.some((clause) => /\b(?:delete|remove|cancel|xoa|huy)\b/.test(clause)
+          && /\b(?:if\s+(?:it\s+)?(?:still\s+)?exists|if\s+present|neu\s+(?:van\s+|con\s+)?ton tai)\b/.test(clause))
+        ? 'ensure-state' : 'execute-and-verify' } } : {}) };
 }
 
 export function applyTaskSemantics(contract, semantic) {

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

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withAsyncLock, LOCK_MAX_SLICE_MS } from './async-lock.mjs';
 import { cronOperationReceipt, bashOperationReceipt, releaseOperationReceipt } from './cron-operation-adapter.mjs';
-import { operationCompletionPolicy, foldOperationEvidence, compactOperation } from './operation-evidence.mjs';
+import { operationCompletionPolicy, foldOperationEvidence, compactOperation, conditionalAbsenceGoal } from './operation-evidence.mjs';
 
 // Hook-context self-deadline (2.4.1 orphan-leak class): armed ONLY on direct
 // CLI invocation (see isDirectRun below) — never at import time. An import-time
@@ -348,6 +348,7 @@ function explicitPromptKey(routeState = {}) {
 }
 
 export function hasUnfinishedCompletion(state = {}, ledger = {}, { cwd } = {}) {
+  ledger = effectiveRequestLedger(state, ledger);
   if (state?.routeSummary?.executionContract?.taskKind) {
     const result = evaluateCompletion({ state, ledger, cwd });
     return result.complete !== true && (result.missingEvidence || []).length > 0 && !ledger.blocker;
@@ -3268,8 +3269,18 @@ function scopedContract(state, ledger) {
   const contract = state?.routeSummary?.executionContract;
   if (!contract?.operationGoal) return contract;
   const session = state?.sessionId || ledger?.sessionId;
-  return { ...contract, operationGoal: { ...contract.operationGoal,
-    scope: contract.operationGoal.scope || (session ? `session:${session}` : null) } };
+  let goal = contract.operationGoal;
+  // In-flight contracts retain their original semantics across tool reroutes. Reconcile
+  // the conditional-absence correction only for the same native goal; never change
+  // targets or discard the contract's existing code/verification obligations.
+  if (goal.domain === 'scheduled-job' && goal.desiredState === 'absent'
+    && goal.completionSemantics === 'execute-and-verify') {
+    if (conditionalAbsenceGoal(state?.routingContext?.lastExplicitUserPromptText, goal.target)) {
+      goal = { ...goal, completionSemantics: 'ensure-state' };
+    }
+  }
+  return { ...contract, operationGoal: { ...goal,
+    scope: goal.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).
@@ -3280,7 +3291,10 @@ function gitAuthority(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 };
+  // Tags that dereference (`--points-at` peels annotated tags) to live HEAD: a masked `git tag` is recovered by
+  // this independent local state, exactly like a masked push is recovered by remote parity.
+  const tagsAtHead = (gitOutput(['tag', '--points-at', 'HEAD'], cwd) || '').split('\n').map((t) => t.trim()).filter(Boolean).slice(0, 16);
+  return { head, branch, remote, tagsAtHead, clean: dirty === null && gitOutput(['rev-parse', '--git-dir'], cwd) !== null };
 }
 function withGitAuthority(ledger, cwd) {
   const gitAuth = ledger && Object.keys(ledger).length ? gitAuthority(cwd) : null;
@@ -3305,10 +3319,11 @@ function effectiveRequestLedger(state = {}, ledger = {}) {
 // 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 = {}) {
-  const text = String(state?.routingContext?.lastExplicitUserPromptText || '').toLowerCase();
+  const text = String(state?.routingContext?.lastExplicitUserPromptText || '')
+    .normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[đĐ]/g, 'd').toLowerCase();
   if (!/\bnpm\s+publish\b/.test(text)) return false;
   return text.split(/[\n;.,]|\bthen\b|\band\b/).some((clause) => /\bnpm\s+publish\b/.test(clause)
-    && !/\b(?:do not|don't|never|without|not yet|dry-run|khong|dung)\b|--dry-run/.test(clause));
+    && !/\b(?:do not|don't|never|without|not yet|dry-run|khong|dung|chua)\b|--dry-run/.test(clause));
 }
 
 function releasePublicationMissing(state, ledger, cwd) {
@@ -3335,17 +3350,26 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
   const vibecode = routeSummary.autonomyLevel === 'vibecode';
   const mode = routeSummary.executionMode || routeSummary.approachSelector?.executionMode || null;
   const evidence = requiredEvidence(state);
-  if (ledger?.blocker) {
+  // Request-scoped blocker: the stored session ledger persists until the new request's first
+  // receipt re-keys it, so the RAW `ledger.blocker` can still be the PREVIOUS task's escape.
+  // Scope the check to the effective request ledger — a stale blocker must never release the
+  // new task's gate (its verification debt stays enforced below) — while the current task's
+  // own blocker still ends the run truthfully: complete:false + outcome:'blocked', never a
+  // fabricated complete and never another continuation loop.
+  const requestLedger = effectiveRequestLedger(state, ledger);
+  if (requestLedger?.blocker) {
     // A blocker minted by the gate itself (verification loop) is the run's exit path — it
     // must be user-visible or the release is indistinguishable from a stall. A blocker
     // minted by a permission decision is already named in the model's own reply and stays
     // silent here.
-    if (ledger.blocker.visible === true) {
+    if (requestLedger.blocker.visible === true) {
       return {
         continue: false,
         notify: true,
+        complete: false,
+        outcome: 'blocked',
         missingEvidence: [],
-        reason: `UKit stopped automatic recovery: ${ledger.blocker.detail || 'a recorded blocker ended this run.'}`,
+        reason: `UKit stopped automatic recovery: ${requestLedger.blocker.detail || 'a recorded blocker ended this run.'}`,
       };
     }
     // An invisible blocker (e.g. a permission decision the model already named in its own
@@ -3354,8 +3378,10 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
     return {
       continue: false,
       notify: true,
+      complete: false,
+      outcome: 'blocked',
       missingEvidence: [],
-      reason: `UKit stopped automatic recovery: ${ledger.blocker.detail || 'a recorded blocker ended this run.'}`,
+      reason: `UKit stopped automatic recovery: ${requestLedger.blocker.detail || 'a recorded blocker ended this run.'}`,
     };
   }
   if (!state || !state.routeSummary) {

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

@@ -66,6 +66,17 @@ export function foldOperationEvidence(bank = {}, receipt, ledger) {
     [key]: { ...prior, [op.role]: proof } };
 }
 
+export function conditionalAbsenceGoal(promptText, target) {
+  if (typeof target !== 'string' || !/^[a-f0-9]{8}(?:[a-f0-9-]{0,28})$/.test(target)) return false;
+  const text = String(promptText || '').normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '').replace(/đ/g, 'd').toLowerCase();
+  return text.split(/[\n;.,]/).some((clause) => clause.split(/\s+/).some((word) => word === target)
+    && /\b(?:cron|scheduled\s+job)\b/.test(clause)
+    && /\b(?:delete|remove|cancel|xoa|huy)\b/.test(clause)
+    && !/\b(?:do not|don't|never|khong|dung)\b/.test(clause)
+    && /\b(?:if\s+(?:it\s+)?(?:still\s+)?exists|if\s+present|neu\s+(?:van\s+|con\s+)?ton tai)\b/.test(clause));
+}
+
 export function operationEvidenceStatus(goal, ledger = {}) {
   if (!goal || typeof goal.domain !== 'string' || !goal.domain || typeof goal.desiredState !== 'string'
     || !goal.desiredState || (goal.target !== null && (typeof goal.target !== 'string' || !goal.target))
@@ -95,7 +106,7 @@ export function operationEvidenceStatus(goal, ledger = {}) {
   // `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')
+    && requiredTargets.every((t) => t === 'commit' || t === 'push' || (t === 'tag' && Array.isArray(auth.tagsAtHead) && auth.tagsAtHead.length > 0))
     && attempts.every((r) => (Number.isSafeInteger(op.remoteSync.observedSequence) ? op.remoteSync.observedSequence : 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' };
@@ -104,7 +115,10 @@ export function operationEvidenceStatus(goal, ledger = {}) {
   if (goal.domain === 'git-integrity' && validRemoteSync(op.remoteSync) && auth
     && (op.remoteSync.sha !== auth.head || op.remoteSync.ref !== `refs/heads/${auth.branch}`
       || (auth.remote && op.remoteSync.remote !== auth.remote))) return incomplete;
-  if (goal.completionSemantics === 'ensure-state' && attempts.length === 0) {
+  // Ensuring a state does not promise execution. A fresh native observation after
+  // every attempt proves the postcondition even when an already-absent delete failed.
+  if (goal.completionSemantics === 'ensure-state'
+    && attempts.every((proof) => Number.isSafeInteger(proof.sequence) && observation.sequence > proof.sequence)) {
     return { complete: true, operationProof: 'desired-state-only' };
   }
   if (!proofs.every((proof) => proof?.success && proof.toolUseId && observation.toolUseId

package/template_project/AGENTS.md

@@ -106,6 +106,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
 ## Unattended Completion Loop
 <!-- RULE: UNATTENDED-01 -->
 - `orchestration.permissionMode: unattended` = no human in the loop — UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny.
+- UKit workflow phases are not host permissions: host permission mode remains user-owned (including Bypass, Default/Ask and Plan). PLAN is not a request to enter host Plan Mode; planning/review/handoff must not switch modes unless the user explicitly requests that transition. Respect host approval and managed policy; never restore an older mode over a newer user choice; subagent mode must not change the parent or another session.
 <!-- RULE: UNATTENDED-02 -->
 - `maxAttemptsPerFailure: 2`, `maxRecoveryStrategies: 2` distinct fix strategies before reassessing — retry the same edit, then fix the cause differently; never loop one strategy.
 <!-- RULE: UNATTENDED-03 -->

package/template_project/CLAUDE.md

@@ -106,6 +106,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
 ## Unattended Completion Loop
 <!-- RULE: UNATTENDED-01 -->
 - `orchestration.permissionMode: unattended` = no human in the loop — UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny.
+- UKit workflow phases are not host permissions: host permission mode remains user-owned (including Bypass, Default/Ask and Plan). PLAN is not a request to enter host Plan Mode; planning/review/handoff must not switch modes unless the user explicitly requests that transition. Respect host approval and managed policy; never restore an older mode over a newer user choice; subagent mode must not change the parent or another session.
 <!-- RULE: UNATTENDED-02 -->
 - `maxAttemptsPerFailure: 2`, `maxRecoveryStrategies: 2` distinct fix strategies before reassessing — retry the same edit, then fix the cause differently; never loop one strategy.
 <!-- RULE: UNATTENDED-03 -->

package/template_project/instructions/core.md

@@ -103,6 +103,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
 ## Unattended Completion Loop
 <!-- RULE: UNATTENDED-01 -->
 - `orchestration.permissionMode: unattended` = no human in the loop — UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny.
+- UKit workflow phases are not host permissions: host permission mode remains user-owned (including Bypass, Default/Ask and Plan). PLAN is not a request to enter host Plan Mode; planning/review/handoff must not switch modes unless the user explicitly requests that transition. Respect host approval and managed policy; never restore an older mode over a newer user choice; subagent mode must not change the parent or another session.
 <!-- RULE: UNATTENDED-02 -->
 - `maxAttemptsPerFailure: 2`, `maxRecoveryStrategies: 2` distinct fix strategies before reassessing — retry the same edit, then fix the cause differently; never loop one strategy.
 <!-- RULE: UNATTENDED-03 -->