@ngockhoale/ukit 3.4.54 → 3.4.56

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.56 - 2026-10-22
+
+**Completion Gate: a stale self-classified contract is re-derived from the task's own prompt on continuation.**
+- Field case: after the 3.4.55 classifier fix, an in-flight task kept its previously stored MIXED contract (continuations reused `routeSummary.executionContract` verbatim), so the gate still demanded `operation-verification` the user's prompt never ordered.
+- Fix (`persistRouteState` in `skill-router.sh`): on a non-system continuation whose stored contract was classified by the router (`contractOrigin` != `carried-system`, not a status report), the contract is re-classified from `lastExplicitUserPromptText`; it is replaced only when the taskKind differs. Genuine contracts re-classify identically and are kept; system-carried contracts are never touched. No gate loosening, no receipts added.
+- Regression: `tests/hooks/staleContractRederive.test.js` (stale MIXED corrected, genuine MIXED retained, carried-system untouched, new task classified on its own).
+- Verified offline on macOS/Node 22; hook replay, not a live host.
+
+## 3.4.55 - 2026-10-22
+
+**Completion Gate: preference, conditional-future and prohibition-list text is not an order (field false-block).**
+- Field case: an audit prompt saying "Ưu tiên configuration change" (preference) and "Nếu chỉ cần configuration change:" (future branch) was classified `CONFIGURATION`/external, so the Stop gate demanded `operation-verification` for a config edit nobody ordered (task `task-0c7425cb…`, `accepted-count=0`). A follow-up prompt listing what an authorization does NOT allow as bullets ("không cho phép: - restart …") plus "Negative controls: … chỉnh config/restart/deploy" was classified `MIXED`/service-runtime.
+- Fix (`neutralizeNonOrders` in all three classifier copies: `src/core/executionContracts.js`, `route-resolver.mjs` mirror, `skill-router.sh` inline): a config preference, a prohibition-header bullet list (bounded to its own sentence and ended by a blank line) and "negative/positive controls" test-case bullets are neutralized; the audit/inspect/review lead filter now tolerates bullet prefixes. Gate, ledger and loop-breaker logic untouched; genuine config/restart/deploy orders and mixed implementation tasks keep their obligations (negative controls in tests).
+- Regression: `tests/hooks/configPreferenceNotOrder.test.js` (src + installed + hook copy; real prompt fixtures `concurrency-audit-config-preference-prompt.txt`, `authorization-boundary-bullets-prompt.txt`). Independent review found one false negative (header regex swallowed the whole line before it); fixed and pinned.
+- Housekeeping: `docs/STATUS.md` rotated under its 150-line budget (verbatim archive), concurrency audit report registered in `manifests/documentation.yaml`.
+- Verified offline on macOS/Node 22; classifier replay, not a live OMP/Claude Code/Codex session; Windows/Linux not run.
+
 ## 3.4.54 - 2026-10-22
 
 **Completion Gate: a stated prohibition is not an operation order (field false-block).**

package/manifests/documentation.yaml

@@ -440,6 +440,17 @@ entries:
     validation: [manual]
     archive_policy: owner-decides
     notes: bounded investigation evidence; extension transition remains OPEN
+  - id: docs-analysis-agent-concurrency-optimization
+    path: docs/analysis/UKIT_AGENT_CONCURRENCY_OPTIMIZATION.md
+    class: canonical
+    audience: [owner, maintainer]
+    owner: runtime
+    source_of_truth: docs/analysis/UKIT_AGENT_CONCURRENCY_OPTIMIZATION.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: replace-with-snapshot
+    notes: Phase A read-only concurrency audit; provisional metrics labelled, pilot not run
   - id: docs-analysis-subagent-cost-audit
     path: docs/analysis/SUBAGENT-COST-AUDIT.md
     class: archive

package/package.json

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

package/src/core/executionContracts.js

@@ -211,10 +211,17 @@ function neutralizeNonOrders(text) {
   let source = String(text).replace(/```[\s\S]*?```/g, ' ').replace(/^[ \t]*>.*$/gm, ' ');
   if (VERIFICATION_GOAL.test(source)) source = source.replace(GOAL_LABEL, ' ').replace(CONDITIONAL_BRANCH, '\n').replace(DISPOSABLE_SETUP, ' ');
   return source
+    // A list item that DESCRIBES test cases ("Negative controls: yêu cầu thực sự chỉnh config/restart/deploy ...") is
+    // specification of the work, not an order; it runs to the next bullet or blank line.
+    .replace(/^[ \t]*(?:[-*+\u2022]|\d+[.)])[ \t]*(?:negative|positive)\s+controls?\b[^\n]*(?:\n(?![ \t]*(?:[-*+\u2022]|\d+[.)])|[ \t]*\n)[^\n]*)*/gm, ' ')
+    // A header that negates the list under it ("Authorization ... không cho phép:", "Prohibitions:", "not allowed:")
+    // makes every bullet an item of the prohibition, not an order.
+    .replace(/(?:^|(?<=[.;][ \t]))[^.;\n]*\b(?:khong\s+(?:cho\s+phep|duoc|lam)|(?:does|do|did|is|are)\s+not\s+(?:allow|permit|authori[sz]e)\w*|not\s+(?:allowed|permitted|authori[sz]ed)|prohibitions?|prohibited(?:\s+actions?)?|forbidden(?:\s+actions?)?|banned|must\s+not\s+do)\s*:[ \t]*(?:\n[ \t]*(?:[-*+\u2022]|\d+[.)])[^\n]*)+/gm, ' ')
     .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|must\\s+not|never|shall\\s+not)\\s+[^.;\\n]*?(?=(?<!,)\\s+(?:and|va)\\s+(?:${NON_ORDER_VERBS})\\b|\\s+(?:but|nhung|then|however)\\b|[.;\\n]|$)`, 'g'), ' ')
     .replace(new RegExp(`\\b(?:khong|chua)\\s+[^.;\\n]*?(?=\\s+(?:nhung|tuy nhien)\\b|[.;\\n]|$)`, 'g'), ' ')
     .replace(/"[^"\n]*\s[^"\n]*"|`[^`\n]*\s[^`\n]*`|\u201c[^\u201d\n]*\u201d/g, ' ')
-    .replace(/\b(?:neu\s+(?:phai|can|thieu|khong du|bang chung chua du)(?![^.;\n]*\b(?:restart|deploy|xoa|delete|remove|cancel)\b)|if\s+(?:needed|necessary|required|evidence is insufficient))\b[^.;\n]*/g, ' ')
+    .replace(/\b(?:uu tien|prefer(?:red)?)\s+(?:a\s+|an\s+)?(?:configuration|config|cau hinh)\s+(?:change|changes|update|thay doi)\b/g, ' ')
+    .replace(/\b(?:neu\s+(?:chi\s+)?(?:phai|can|thieu|khong du|bang chung chua du)(?![^.;\n]*\b(?:restart|deploy|xoa|delete|remove|cancel)\b)|if\s+(?:needed|necessary|required|evidence is insufficient))\b[^.;\n]*/g, ' ')
     .replace(/[^.;\n]*\b(?:nao|gi|sao|the nao|bao nhieu)\b[^.;\n]*\?/g, ' ')
     .replace(/\bchinh\s+(?:xac|sach)\b|\b(?:phuong an|cach|de xuat|ban)\s+(?:sua|fix)\b|\b(?:diem|cho|muc|phan)\s+(?:phai|can|nen)\s+(?:sua|fix)\b/g, ' ')
     .replace(/\bwrite\s*\/\s*verification\b|\bverification\s*\/\s*write\b|\bwrite\s+(?:or|and)\s+verification\b/g, ' ')
@@ -291,7 +298,7 @@ export function classifyTaskSemantics({ promptText = '', targetFile = '' } = {})
   const text = neutralizeBannedLists(neutralizeNonOrders(String(promptText).normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[đĐ]/g, 'd').toLowerCase()));
   const clauses = text.split(/\s*(?:[;\n,]|\.(?:\s+|$)|\band\b|\bthen\b|\bva\b)\s*/);
   const actionable = clauses.map((clause) => clause.split(/\bwithout\b/)[0]).filter((clause) => !/\b(?:do not|don't|never|khong|dung)\b/.test(clause)
-    && !/^\s*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
+    && !/^[\s*+•>\d.)-]*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
   if (declaredReadOnly(promptText, releasePolicy)) return { taskKind: 'READ_ONLY' };
   const sourceOrder = actionable.some((clause) => /\b(?:implement|fix(?:es)?|apply|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause)
     && /\b(?:source|code|logic|scheduler|implementation|ma nguon)\b|\.[cm]?[jt]sx?\b/.test(clause));

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

@@ -1893,10 +1893,17 @@ function neutralizeNonOrders(text) {
   let source = String(text).replace(/```[\s\S]*?```/g, ' ').replace(/^[ \t]*>.*$/gm, ' ');
   if (VERIFICATION_GOAL.test(source)) source = source.replace(GOAL_LABEL, ' ').replace(CONDITIONAL_BRANCH, '\n').replace(DISPOSABLE_SETUP, ' ');
   return source
+    // A list item that DESCRIBES test cases ("Negative controls: yêu cầu thực sự chỉnh config/restart/deploy ...") is
+    // specification of the work, not an order; it runs to the next bullet or blank line.
+    .replace(/^[ \t]*(?:[-*+\u2022]|\d+[.)])[ \t]*(?:negative|positive)\s+controls?\b[^\n]*(?:\n(?![ \t]*(?:[-*+\u2022]|\d+[.)])|[ \t]*\n)[^\n]*)*/gm, ' ')
+    // A header that negates the list under it ("Authorization ... không cho phép:", "Prohibitions:", "not allowed:")
+    // makes every bullet an item of the prohibition, not an order.
+    .replace(/(?:^|(?<=[.;][ \t]))[^.;\n]*\b(?:khong\s+(?:cho\s+phep|duoc|lam)|(?:does|do|did|is|are)\s+not\s+(?:allow|permit|authori[sz]e)\w*|not\s+(?:allowed|permitted|authori[sz]ed)|prohibitions?|prohibited(?:\s+actions?)?|forbidden(?:\s+actions?)?|banned|must\s+not\s+do)\s*:[ \t]*(?:\n[ \t]*(?:[-*+\u2022]|\d+[.)])[^\n]*)+/gm, ' ')
     .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|must\\s+not|never|shall\\s+not)\\s+[^.;\\n]*?(?=(?<!,)\\s+(?:and|va)\\s+(?:${NON_ORDER_VERBS})\\b|\\s+(?:but|nhung|then|however)\\b|[.;\\n]|$)`, 'g'), ' ')
     .replace(new RegExp(`\\b(?:khong|chua)\\s+[^.;\\n]*?(?=\\s+(?:nhung|tuy nhien)\\b|[.;\\n]|$)`, 'g'), ' ')
     .replace(/"[^"\n]*\s[^"\n]*"|`[^`\n]*\s[^`\n]*`|\u201c[^\u201d\n]*\u201d/g, ' ')
-    .replace(/\b(?:neu\s+(?:phai|can|thieu|khong du|bang chung chua du)(?![^.;\n]*\b(?:restart|deploy|xoa|delete|remove|cancel)\b)|if\s+(?:needed|necessary|required|evidence is insufficient))\b[^.;\n]*/g, ' ')
+    .replace(/\b(?:uu tien|prefer(?:red)?)\s+(?:a\s+|an\s+)?(?:configuration|config|cau hinh)\s+(?:change|changes|update|thay doi)\b/g, ' ')
+    .replace(/\b(?:neu\s+(?:chi\s+)?(?:phai|can|thieu|khong du|bang chung chua du)(?![^.;\n]*\b(?:restart|deploy|xoa|delete|remove|cancel)\b)|if\s+(?:needed|necessary|required|evidence is insufficient))\b[^.;\n]*/g, ' ')
     .replace(/[^.;\n]*\b(?:nao|gi|sao|the nao|bao nhieu)\b[^.;\n]*\?/g, ' ')
     .replace(/\bchinh\s+(?:xac|sach)\b|\b(?:phuong an|cach|de xuat|ban)\s+(?:sua|fix)\b|\b(?:diem|cho|muc|phan)\s+(?:phai|can|nen)\s+(?:sua|fix)\b/g, ' ')
     .replace(/\bwrite\s*\/\s*verification\b|\bverification\s*\/\s*write\b|\bwrite\s+(?:or|and)\s+verification\b/g, ' ')
@@ -1936,7 +1943,7 @@ function classifyTaskSemantics({ promptText = '', targetFile = '' } = {}) {
   const text = neutralizeNonOrders(String(promptText).normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[đĐ]/g, 'd').toLowerCase());
   const clauses = text.split(/\s*(?:[;\n,]|\.(?:\s+|$)|\band\b|\bthen\b|\bva\b)\s*/);
   const actionable = clauses.map((clause) => clause.split(/\bwithout\b/)[0]).filter((clause) => !/\b(?:do not|don't|never|khong|dung)\b/.test(clause)
-    && !/^\s*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
+    && !/^[\s*+•>\d.)-]*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
   const sourceOrder = actionable.some((clause) => /\b(?:implement|fix(?:es)?|apply|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause)
     && /\b(?:source|code|logic|scheduler|implementation|ma nguon)\b|\.[cm]?[jt]sx?\b/.test(clause));
   const codeChangeVerb = actionable.some((clause) => /\b(?:implement|fix(?:es)?|apply|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause));
@@ -3913,7 +3920,22 @@ function applyTaskSemantics(contract, semantic) {
       }
       if (previous.requestKey) persisted.requestKey = previous.requestKey;
     }
-    const semantic = continuingTask && previous.routeSummary?.executionContract?.taskKind
+    // A stored contract this router classified itself (never a carried-system one) is a cache of
+    // classifyTaskSemantics(lastExplicitUserPromptText): when the classifier has since been fixed
+    // the cache is stale and would keep enforcing evidence the user's own prompt never ordered.
+    // Re-derive from the task's own prompt; genuine contracts re-classify identically and stay.
+    let semanticFromPrompt = null;
+    const storedContract = previous.routeSummary?.executionContract;
+    if (continuingTask && !systemOriginTurn && storedContract?.taskKind && previous.contractOrigin !== 'carried-system'
+      && !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;
+      } catch {}
+    }
+    const semantic = semanticFromPrompt
+      ? semanticFromPrompt
+      : continuingTask && previous.routeSummary?.executionContract?.taskKind
       ? previous.routeSummary.executionContract
       : classifyTaskSemantics({ promptText: extractPrompt(payload) || persisted.routingContext?.lastExplicitUserPromptText, targetFile: persisted.routingContext?.targetFile });
     const informationalTurn = !continuingTask && persisted.routingContext?.executionMode === 'informational'

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

@@ -1108,10 +1108,17 @@ function neutralizeNonOrders(text) {
   let source = String(text).replace(/```[\s\S]*?```/g, ' ').replace(/^[ \t]*>.*$/gm, ' ');
   if (VERIFICATION_GOAL.test(source)) source = source.replace(GOAL_LABEL, ' ').replace(CONDITIONAL_BRANCH, '\n').replace(DISPOSABLE_SETUP, ' ');
   return source
+    // A list item that DESCRIBES test cases ("Negative controls: yêu cầu thực sự chỉnh config/restart/deploy ...") is
+    // specification of the work, not an order; it runs to the next bullet or blank line.
+    .replace(/^[ \t]*(?:[-*+\u2022]|\d+[.)])[ \t]*(?:negative|positive)\s+controls?\b[^\n]*(?:\n(?![ \t]*(?:[-*+\u2022]|\d+[.)])|[ \t]*\n)[^\n]*)*/gm, ' ')
+    // A header that negates the list under it ("Authorization ... không cho phép:", "Prohibitions:", "not allowed:")
+    // makes every bullet an item of the prohibition, not an order.
+    .replace(/(?:^|(?<=[.;][ \t]))[^.;\n]*\b(?:khong\s+(?:cho\s+phep|duoc|lam)|(?:does|do|did|is|are)\s+not\s+(?:allow|permit|authori[sz]e)\w*|not\s+(?:allowed|permitted|authori[sz]ed)|prohibitions?|prohibited(?:\s+actions?)?|forbidden(?:\s+actions?)?|banned|must\s+not\s+do)\s*:[ \t]*(?:\n[ \t]*(?:[-*+\u2022]|\d+[.)])[^\n]*)+/gm, ' ')
     .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|must\\s+not|never|shall\\s+not)\\s+[^.;\\n]*?(?=(?<!,)\\s+(?:and|va)\\s+(?:${NON_ORDER_VERBS})\\b|\\s+(?:but|nhung|then|however)\\b|[.;\\n]|$)`, 'g'), ' ')
     .replace(new RegExp(`\\b(?:khong|chua)\\s+[^.;\\n]*?(?=\\s+(?:nhung|tuy nhien)\\b|[.;\\n]|$)`, 'g'), ' ')
     .replace(/"[^"\n]*\s[^"\n]*"|`[^`\n]*\s[^`\n]*`|\u201c[^\u201d\n]*\u201d/g, ' ')
-    .replace(/\b(?:neu\s+(?:phai|can|thieu|khong du|bang chung chua du)(?![^.;\n]*\b(?:restart|deploy|xoa|delete|remove|cancel)\b)|if\s+(?:needed|necessary|required|evidence is insufficient))\b[^.;\n]*/g, ' ')
+    .replace(/\b(?:uu tien|prefer(?:red)?)\s+(?:a\s+|an\s+)?(?:configuration|config|cau hinh)\s+(?:change|changes|update|thay doi)\b/g, ' ')
+    .replace(/\b(?:neu\s+(?:chi\s+)?(?:phai|can|thieu|khong du|bang chung chua du)(?![^.;\n]*\b(?:restart|deploy|xoa|delete|remove|cancel)\b)|if\s+(?:needed|necessary|required|evidence is insufficient))\b[^.;\n]*/g, ' ')
     .replace(/[^.;\n]*\b(?:nao|gi|sao|the nao|bao nhieu)\b[^.;\n]*\?/g, ' ')
     .replace(/\bchinh\s+(?:xac|sach)\b|\b(?:phuong an|cach|de xuat|ban)\s+(?:sua|fix)\b|\b(?:diem|cho|muc|phan)\s+(?:phai|can|nen)\s+(?:sua|fix)\b/g, ' ')
     .replace(/\bwrite\s*\/\s*verification\b|\bverification\s*\/\s*write\b|\bwrite\s+(?:or|and)\s+verification\b/g, ' ')
@@ -1188,7 +1195,7 @@ export function classifyTaskSemantics({ promptText = '', targetFile = '' } = {})
   const text = neutralizeBannedLists(neutralizeNonOrders(String(promptText).normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[đĐ]/g, 'd').toLowerCase()));
   const clauses = text.split(/\s*(?:[;\n,]|\.(?:\s+|$)|\band\b|\bthen\b|\bva\b)\s*/);
   const actionable = clauses.map((clause) => clause.split(/\bwithout\b/)[0]).filter((clause) => !/\b(?:do not|don't|never|khong|dung)\b/.test(clause)
-    && !/^\s*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
+    && !/^[\s*+•>\d.)-]*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
   if (declaredReadOnly(promptText, releasePolicy)) return { taskKind: 'READ_ONLY' };
   const sourceOrder = actionable.some((clause) => /\b(?:implement|fix(?:es)?|apply|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause)
     && /\b(?:source|code|logic|scheduler|implementation|ma nguon)\b|\.[cm]?[jt]sx?\b/.test(clause));