@ngockhoale/ukit 3.5.7 → 3.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,34 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.5.9 - 2026-11-18
6
+
7
+ Playbooks now reach the agent. A telemetry review of 164 Claude Code sessions (1,426 unique prompts) found the playbook feature had no effect: only 9% of prompts got a playbook, 79% were dropped as ambiguous (for example bug-fix + release), and no session ever opened a playbook file, because the prompt hook never printed one and route-task pointed at a relative path that does not exist in projects. No new command was added; the change is in what the existing hooks and instructions deliver. No host was run live; the checks are unit, parity and hook-process tests.
8
+
9
+ - **The playbook text is injected with the route.** On a prompt turn the Claude Code / omp router prints the matched playbook body (frontmatter stripped, capped at 2,400 characters with a pointer to the full file) inside `<ukit-playbook id="…">`, with the instruction to copy its numbered steps as the first todos, keep skipped steps as `skip: <reason>` / `n/a: <reason>`, and end with its Reply contract. `route-task.mjs` (Codex and print consumers) prints the same block and drops the duplicate workflow lines when it does.
10
+ - **Ambiguous prompts get candidates instead of nothing.** When two or more playbooks match, the router lists up to four candidates and the absolute `~/.ukit/playbooks/<id>.md` path to read after picking by primary intent.
11
+ - **The intent → playbook map is part of the always-loaded instructions.** CLAUDE.md and AGENTS.md gain a "Playbooks (automatic — no command)" section; omp's RULES.md gains the same rule in one line. Plain continuations and trivial edits still need no playbook; `/ukit:handoff-*` commands keep their own phases.
12
+ - **Handoff executors use playbooks too.** `/ukit:handoff-implement` and `/ukit:handoff-fullstack` executor briefs tell defect, performance and migration tasks to copy the matching playbook steps; the brief still wins on commits, TDD and the report shape.
13
+ - **Route audit rows record why no playbook was chosen** (`playbookReason`, `playbookCandidates`) so the hit rate can be re-measured.
14
+ - **Questions no longer get a build playbook.** A Vietnamese question whose clause ends in "vậy." or "không," (for example "học hỏi gì thêm từ pstack vậy. apply có tốt hơn không, …") routed to small-feature and then the Stop gate asked for edits; it now routes investigation. "thêm" counts as the order "add" only when it leads its clause ("thêm nút Save…", "giúp tôi thêm…"); as "more/additional" ("tích hợp thêm ý tưởng", "thêm cũng có nghĩa là more") it no longer mints a build playbook.
15
+
16
+ Known limits: ambiguous prompts are not ranked yet; `~/.ukit/playbooks` seeds are never refreshed by `ukit update`, so older personal copies keep their older text.
17
+
18
+ ## 3.5.8 - 2026-11-16
19
+
20
+ Bug-fix release: one defect seen right after 3.5.7 shipped, fixed at its cause. No host (Claude Code, Codex, omp) was run live and nothing was run on Windows; the checks are unit tests and real hook processes (prompt router, evidence recorder, Stop gate) in a temporary project.
21
+
22
+ - **Fix: asking how the work is going is no longer treated as an order to change code.** A prompt such as "Chạy có vẻ lâu rồi nè, không biết có tiến triển gì không … nếu có tiến triển thì tiếp tục làm, nếu lặp lại vô nghĩa thì báo tôi" was routed as a code task, and when it arrived after the task had finished, the Stop gate refused a correct progress report and asked for an edit and a test run. Two things caused it and both are fixed:
23
+ - The Vietnamese syllables "triển" and "khai" on their own were expanded to implement/build/ship, so "tiến triển" (progress) selected the delivery skill. Only the full words are expanded now: "triển khai" (implement/deploy/ship), "phát triển" (develop/build), "khai báo" (declare).
24
+ - "chạy", "tạo" and "cài/cải" counted as orders wherever they appeared. They now count only in an order position — with an object or an imperative particle ("chạy lại test", "tạo file x", "cài lodash đi") — and not as a description ("chạy có vẻ lâu rồi", "đang chạy", "mục tiêu của tạo ra UKit là cải tiến …"). In English, a change word used as a noun after the/a/this/my/… ("How is the progress on the build?", "Any update on the fix?") is no longer an order either; "fix the build", "run the build and fix failures", "do that update now" and "do the fix" behave as in 3.5.7. Delete/remove words are never softened.
25
+ - **Fix: "tiếp tục …" with a remark attached keeps the running task.** "tiếp tục. không dừng, nhớ check cái idle cho tôi" or "nếu có tiến triển thì tiếp tục làm, …" sent while a task was in flight started a new task and parked the running one's obligations. A continuation clause inside a longer prompt now binds to the live task, the same as a bare "tiếp tục". It never revives a parked task, and it does not apply when any part of the prompt orders something: "tiếp tục, push luôn", "tiếp tục, commit đi" or "nếu ok thì push rồi tiếp tục" start a new task with the checks that order needs, as in 3.5.7.
26
+ - **Known limits, not fixed here.**
27
+ - Some plain statements that order nothing ("Đã làm phải có hiệu quả.") still print a code-task route line, because the classifier's default kind is "code change". The Stop gate does not demand an edit for them when nothing was ordered and nothing was written.
28
+ - Some English questions whose change word is not behind the/a/this/… as a noun — "did you get the build?", "when did you start the build?" — are still read as an order, and the Stop gate asks for edit and test evidence, exactly as in 3.5.7.
29
+ - "để chạy test" on its own is not counted as an order (the purpose-clause rule strips it) although it still owes test evidence; "tiếp tục push lên main" written as one clause starts a new task that asks for edit evidence instead of push evidence. Both behave exactly as in 3.5.7.
30
+ - A noun that is also an operation word ("cái tag v3.5.7", "release notes", "giá đang lên") after "tiếp tục," starts a new task instead of continuing — the same result as 3.5.7, and it never drops an obligation.
31
+ - A prompt with no skill match can still be labelled a broader edit mode than it deserves (a tie between zero scores is pushed upward); the routed and the no-route paths use two slightly different "is this informational" checks.
32
+
5
33
  ## 3.5.7 - 2026-11-16
6
34
 
7
35
  Bug-fix release: eight defects found while shipping 3.5.6, each fixed at its cause. No host (Claude Code, Codex, omp) was run live and nothing was run on Windows; the checks are unit tests and real hook processes on this repository.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.7",
3
+ "version": "3.5.9",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -6,6 +6,11 @@ const GENERIC_STOPWORDS = new Set([
6
6
  ]);
7
7
 
8
8
  const VIETNAMESE_PHRASE_ALIASES = [
9
+ // Bigrams only: the unigrams "trien"/"khai" also fold "tiến triển" (progress) / "khai" in unrelated
10
+ // words onto implement/build/ship, which selected the delivery skill for progress questions (3.5.8).
11
+ { regex: /\btrien khai\b/gu, expansions: ['implement', 'deploy', 'ship'] },
12
+ { regex: /\bphat trien\b/gu, expansions: ['develop', 'build'] },
13
+ { regex: /\bkhai bao\b/gu, expansions: ['declare'] },
9
14
  { regex: /\bbo nho dem\b/gu, expansions: ['cache'] },
10
15
  { regex: /\bduong dan\b/gu, expansions: ['route', 'path'] },
11
16
  { regex: /\bxac thuc\b/gu, expansions: ['auth', 'authentication'] },
@@ -78,8 +83,6 @@ const VIETNAMESE_TOKEN_ALIASES = new Map([
78
83
  ['component', ['component']],
79
84
  ['test', ['test', 'testing']],
80
85
  ['soat', ['review', 'audit']],
81
- ['trien', ['implement', 'build', 'ship']],
82
- ['khai', ['implement', 'build', 'ship']],
83
86
  ['kho', ['store', 'storage']],
84
87
  ['ghi', ['write', 'record']],
85
88
  ['doc', ['read']],
@@ -49,7 +49,7 @@ export const PLAYBOOK_ID_ALIASES = Object.freeze({
49
49
  // --- Shared signal vocabulary ------------------------------------------------
50
50
  // Compiled once; every row's discriminator reads the same normalized signals so
51
51
  // confusable pairs split on the discriminator column, never trigger text.
52
- const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b/i;
52
+ const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b|(?<![\p{L}\p{N}_])(?:viết|viet)(?![\p{L}\p{N}_])/iu;
53
53
  // Vietnamese words never match `\b` (JS word chars are ASCII-only — 'sửa' ends
54
54
  // in a non-word char, 'đổi' starts with one), so the diacritic alternates use
55
55
  // explicit lookarounds instead. Same word list as the original literal.
@@ -397,6 +397,20 @@ function matchFirst(text, regexes) {
397
397
  return -1;
398
398
  }
399
399
 
400
+ // "thêm" is both the order "add" and the adverb "more/additional". The order
401
+ // leads its clause ("thêm nút Save", "giúp tôi thêm …"); the adverb trails a
402
+ // verb/noun ("học hỏi gì thêm", "tích hợp thêm ý tưởng") or is the word under
403
+ // discussion ("thêm cũng có nghĩa là more"). Only the order counts as create.
404
+ const THEM_ORDER_LEAD = new Set(['hãy', 'hay', 'giúp', 'giùm', 'cho', 'tôi', 'mình', 'em', 'anh', 'bạn', 'và', 'rồi', 'thì', 'cần', 'lại', 'luôn', 'lòng', 'please']);
405
+ function stripAdverbialThem(text) {
406
+ return text
407
+ .replace(/(^|[\s.,;:!?])thêm(?=\s+(?:cũng|có nghĩa|nghĩa là|là|nữa)(?![\p{L}\p{N}_]))/giu, '$1 ')
408
+ .replace(/(?<!\S)(\S{1,40})(\s+)thêm(?![\p{L}\p{N}_])/giu, (match, prev, space) => {
409
+ if (/[.,;:!?]$/.test(prev) || THEM_ORDER_LEAD.has(prev.toLowerCase())) return match;
410
+ return `${prev}${space} `;
411
+ });
412
+ }
413
+
400
414
  async function buildRouteSignals({
401
415
  signalText,
402
416
  rawPromptText = '',
@@ -411,10 +425,14 @@ async function buildRouteSignals({
411
425
  // because no consult pattern consumes its clause.
412
426
  const verbScanText = signalText
413
427
  .replace(/(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+[^\n?]*/g, ' ')
414
- .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s*[?.!]?\s*$/g, ' ')
415
- .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ');
428
+ .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s{0,16}[?.!]?\s{0,16}$/g, ' ')
429
+ .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ')
430
+ // A mid-prompt question clause ("học hỏi gì thêm … vậy.", "apply có tốt hơn
431
+ // không, …") is an ask too — only true question particles close it here
432
+ // ('rồi' stays out: "fix X rồi, chạy test" means "then").
433
+ .replace(/[^\n.,;?]{0,80}(?:\b(?:không|khong|chưa|chua|được không|duoc khong|đúng không|dung khong|nhỉ)|(?<![A-Za-z0-9_])vậy)\s*[?.!,;]/g, ' ');
416
434
  const changeIdx = verbScanText.search(CHANGE_VERB_RE);
417
- const createIdx = verbScanText.search(CREATE_VERB_RE);
435
+ const createIdx = stripAdverbialThem(verbScanText).search(CREATE_VERB_RE);
418
436
  const explainIdx = signalText.search(EXPLAIN_ASK_RE);
419
437
  const defectIdx = signalText.search(DEFECT_TRIGGER_RE);
420
438
  const checkIdx = signalText.search(CHECK_VERB_RE);
@@ -422,7 +440,7 @@ async function buildRouteSignals({
422
440
  const consultLead = /(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+/
423
441
  .test(signalText)
424
442
  || /\b(?:co|có)\s+(?:nên|nen|cần|can|phải|phai)\s+/.test(signalText)
425
- || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s*[?.!]?\s*$/.test(signalText);
443
+ || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
426
444
  const firstVerbIdx = [changeIdx, createIdx].filter((i) => i !== -1).sort((a, b) => a - b)[0] ?? -1;
427
445
  const explanationAsk = explainIdx !== -1 && (firstVerbIdx === -1 || explainIdx < firstVerbIdx);
428
446
  const changeRequested = !consultLead && firstVerbIdx !== -1 && (explainIdx === -1 || firstVerbIdx < explainIdx);
@@ -440,7 +458,7 @@ async function buildRouteSignals({
440
458
  || /\b(how|why|what|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(signalText)
441
459
  || /(?:có|co)\s+(?:phải|phai)\s+/.test(signalText)
442
460
  || /(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|thế nào|the nao|như thế nào|nhu the nao|tại sao|tai sao|là gì|la gi|bao giờ|bao gio|khi nào|khi nao|ở đâu|o dau|không biết|khong biet)/.test(signalText)
443
- || /(?:chưa|chua|đúng không|dung khong|không|khong)\s*[?.!]?\s*$/.test(signalText);
461
+ || /(?:chưa|chua|đúng không|dung khong|không|khong)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
444
462
  const questionAsk = questionShaped && !changeRequested;
445
463
  const referenceTarget = REFERENCE_TARGET_RE.test(signalText);
446
464
  const cloneIntent = CLONE_INTENT_RE.test(signalText);
@@ -623,6 +641,34 @@ export async function loadRegistry({ projectRoot = null, homeDir = null, builtin
623
641
  return records;
624
642
  }
625
643
 
644
+ // Delivery: the playbook body (frontmatter stripped, CRLF normalized) for
645
+ // injection into the routed turn. Bounded so a hand-edited user playbook can
646
+ // never flood the context; null on any read/parse failure (fail-open).
647
+ export const PLAYBOOK_BODY_MAX_CHARS = 2400;
648
+ export async function readPlaybookBody(filePath, { maxChars = PLAYBOOK_BODY_MAX_CHARS } = {}) {
649
+ if (typeof filePath !== 'string' || filePath === '') return null;
650
+ let raw;
651
+ try {
652
+ raw = await fs.readFile(filePath, 'utf8');
653
+ } catch {
654
+ return null;
655
+ }
656
+ const text = String(raw).replace(/\r\n/g, '\n');
657
+ let body = text;
658
+ if (text.startsWith('---\n')) {
659
+ const fenceIndex = text.indexOf('\n---', 3);
660
+ if (fenceIndex === -1) return null;
661
+ body = text.slice(fenceIndex + 4).replace(/^\n/, '');
662
+ }
663
+ // A body cannot close the <ukit-playbook> wrapper early.
664
+ body = body.trim().replace(/<\/ukit-playbook>/gi, '&lt;/ukit-playbook>');
665
+ if (body === '') return null;
666
+ if (body.length <= maxChars) return body;
667
+ // Cut on a code-point boundary (never split a surrogate pair).
668
+ const cut = Array.from(body.slice(0, maxChars + 1)).slice(0, -1).join('').slice(0, maxChars);
669
+ return `${cut.trimEnd()}\n[…truncated — full text: ${filePath}]`;
670
+ }
671
+
626
672
  function findRegistryRecord(records, playbookId) {
627
673
  const direct = records.find((r) => r.frontmatterValid && r.playbookId === playbookId);
628
674
  if (direct) return direct;
@@ -814,5 +860,11 @@ export async function resolvePlaybookRoute({
814
860
  fastPath: resolution.fastPath ?? null,
815
861
  reason: resolution.reason ?? null,
816
862
  playbookLoad: resolution.reason === 'playbook-missing' ? 'missing' : null,
863
+ // Delivery fields: the resolved file lets the hook inject the playbook body
864
+ // (agents never Read a relative `playbooks/<id>.md` that does not exist in
865
+ // the project); ambiguous candidates let the agent pick instead of losing
866
+ // the playbook entirely (pstack posture — the model chooses on ties).
867
+ file: resolution.file ?? null,
868
+ candidates: Array.isArray(resolution.candidates) ? resolution.candidates : null,
817
869
  };
818
870
  }
@@ -443,6 +443,10 @@ export async function deriveTaskRoute({
443
443
  routeSummary.workGroup = playbookResolution.workGroup;
444
444
  routeSummary.playbookReason = playbookResolution.reason;
445
445
  routeSummary.playbookLoad = playbookResolution.playbookLoad;
446
+ // Playbook delivery parity with route-task.mjs: file/body/candidates ride
447
+ // the route so the printed state carries the playbook text itself.
448
+ routeSummary.playbookFile = playbookResolution.file ?? null;
449
+ routeSummary.playbookCandidates = Array.isArray(playbookResolution.candidates) ? playbookResolution.candidates : null;
446
450
  // BL-010 (ARCH Task Contract): `path` = direct|handoff; `fastPathKind` is
447
451
  // the ARCH `none|small-feature|bug-fix` enum — named Kind because
448
452
  // routeSummary.fastPath already carries the FR-004 eligibility object.
@@ -1017,7 +1021,9 @@ function isInformationalPrompt({
1017
1021
  }
1018
1022
  // C85-019: consult-shape also overrides the vocabulary vetoes — the
1019
1023
  // mutation/debug/lỗi words are the question's SUBJECT, not the ask.
1020
- const implementWords = /(?<![A-Za-z0-9_])(implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|build|chạy|cài)(?![A-Za-z0-9_])/.test(raw);
1024
+ // chạy/tạo/cài are judged by the shared position rule (ambiguousVerbOrder), not by bare presence.
1025
+ const implementWords = /(?<![A-Za-z0-9_])(implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|xóa|đổi|thay thế|cập nhật|viết|build)(?![A-Za-z0-9_])/.test(softenEnglishNouns(raw))
1026
+ || ambiguousVerbOrder(raw);
1021
1027
  if (implementWords && !consultShape) return false;
1022
1028
  const investigationWords = /\b(why|debug|triage|root cause|investigate|tại sao)\b/.test(raw);
1023
1029
  if (investigationWords && !consultShape) return false;
@@ -1211,7 +1217,51 @@ export function classifyAdvisorRequest({ promptText = '', commandText = '' } = {
1211
1217
  // folding, so "Cái này là gì, tại sao…" is not read as an install order (3.4.81 telemetry audit).
1212
1218
  function maskTonedNonVerbs(text = '') {
1213
1219
  return String(text ?? '').normalize('NFC')
1214
- .replace(/(?<![\p{L}\p{N}_])(?:cái|chính|việt|cháy|chảy|đợi|đời|đối|đội|đôi|đói|sữa|thèm)(?![\p{L}\p{N}_])/giu, ' _ ');
1220
+ .replace(/(?<![\p{L}\p{N}_])(?:cái|cải|cãi|chính|việt|cháy|chảy|đợi|đời|đối|đội|đôi|đói|sữa|thèm)(?![\p{L}\p{N}_])/giu, ' _ ');
1221
+ }
1222
+ // Position rule for the closed set of verbs that tone-fold onto an order verb but are ordinary
1223
+ // aspect/nominal words in progress talk: ch\u1ea1y (run / is running), t\u1ea1o (create / the creation of),
1224
+ // c\u1ea3i/c\u00e0i (improve / install). Input is folded (accent-free, lowercase) text. A verb is an ORDER when it
1225
+ // has an object or an imperative particle; it is NOT an order after a nominaliser/preposition/copula/
1226
+ // aspect marker (PREV = cua, viec, su, khi, dang) or when only a stative/degree complement follows
1227
+ // (co ve + lau, mai, hoai, cham, nhanh, xong, roi, duoc, qua, rat, hoi, ne, then end of clause or a conjunction).
1228
+ // Imperative particles (di, luon, ngay, giup, gium, ho, nhe) within 3 tokens always keep it an order.
1229
+ // Non-orders become " _ "; orders are untouched. English: a mutation word right after a determiner/possessive is
1230
+ // a noun ("the build"), unless a light verb stands before the determiner ("do the build", "finish that update").
1231
+ // Destructive verbs (x\u00f3a, delete, drop, reset) are deliberately not in this set.
1232
+ // Three copies (taskRouting.js, route-task.mjs, skill-router.sh) \u2014 keep them identical.
1233
+ function softenEnglishNouns(text = '') {
1234
+ return String(text).replace(/(?<!\b(?:do|does|doing|perform|finish|complete|handle|start|get|try)\s+)\b(the|a|an|any|this|that|these|those|my|our|your|its|their|his|her)\s+(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|rename|change|write|build|make|install|run|deploy|execute|edit)\b/gi, '$1 _ ');
1235
+ }
1236
+ function softenAmbiguousVerbs(folded = '') {
1237
+ const PREV = new Set(['cua', 'viec', 'su', 'khi', 'dang']);
1238
+ const PARTICLE = new Set(['di', 'luon', 'ngay', 'giup', 'gium', 'ho', 'nhe']);
1239
+ const COMPLEMENT = new Set(['lau', 'mai', 'hoai', 'cham', 'nhanh', 'xong', 'roi', 'duoc', 'qua', 'rat', 'hoi', 'ne']);
1240
+ const CONJ = new Set(['ma', 'nhung', 'va', 'thi', 'hay', 'nen', 'khong', 'chua', 'but', 'and', 'so']);
1241
+ // Each occurrence is judged on its own (a clause can hold several: "tạo ra Ukit là cải tiến ...").
1242
+ // English: a mutation token right after a determiner/possessive is a noun ("the build", "my fix"), never an
1243
+ // order. Only that token is softened, so "run the build" / "fix the build" still order through the verb.
1244
+ // delete/remove are never softened.
1245
+ return softenEnglishNouns(folded).replace(/\b(chay|tao|cai)\b/g, (match, verb, offset, whole) => {
1246
+ const prev = whole.slice(0, offset).trimEnd().split(/\s+/).pop() || '';
1247
+ const tokens = (whole.slice(offset + match.length).split(/[.,;!?\n]/)[0] || '').split(/\s+/).filter(Boolean);
1248
+ if (tokens.slice(0, 3).some((token) => PARTICLE.has(token))) return match;
1249
+ if (PREV.has(prev)) return ' _ ';
1250
+ let index = 0;
1251
+ let consumed = 0;
1252
+ while (index < tokens.length) {
1253
+ if (tokens[index] === 'co' && tokens[index + 1] === 've') { index += 2; consumed += 1; continue; }
1254
+ if (COMPLEMENT.has(tokens[index])) { index += 1; consumed += 1; continue; }
1255
+ break;
1256
+ }
1257
+ if (consumed > 0 && (index >= tokens.length || CONJ.has(tokens[index]))) return ' _ ';
1258
+ return match;
1259
+ });
1260
+ }
1261
+ // The shared predicate: does any ambiguous verb in this text still stand as an order?
1262
+ function ambiguousVerbOrder(text = '') {
1263
+ const folded = maskTonedNonVerbs(text).toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/\u0111/g, 'd');
1264
+ return /\b(?:chay|tao|cai)\b/.test(softenAmbiguousVerbs(folded));
1215
1265
  }
1216
1266
  function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
1217
1267
  const folded = `${maskTonedNonVerbs(promptText)}\n${commandText ?? ''}`
@@ -1219,7 +1269,7 @@ function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
1219
1269
  .normalize('NFD')
1220
1270
  .replace(/[\u0300-\u036f]/g, '')
1221
1271
  .replace(/\u0111/g, 'd');
1222
- const trimmed = folded.trim();
1272
+ const trimmed = softenAmbiguousVerbs(folded.trim());
1223
1273
  if (!trimmed) return false;
1224
1274
  // C85-019c: clause strips must stop BEFORE a conjunction-joined imperative
1225
1275
  // — "giữ nguyên header và sửa lỗi login" keeps 'và sửa lỗi' as a surviving
@@ -692,6 +692,10 @@ no compound.)
692
692
  ```
693
693
  Read docs/AI_HANDOFF/tasks/TASK-xxx.md
694
694
 
695
+ Playbook — if the task is a defect, read bug-fix.md from ~/.ukit/playbooks/ (perf:
696
+ performance.md, migration: migration.md) and copy its numbered steps into your todos (skip:/n/a: <reason>,
697
+ never drop one). This brief wins on conflict: no commits, TDD and the report shape below.
698
+
695
699
  TDD — mandatory:
696
700
  1. Write tests from §Test Cases
697
701
  run <test command> from the worktree root (your cwd IS .worktrees/task-xxx — no cd)
@@ -150,6 +150,10 @@ Read the SPEC.md sections named in the task's `Spec references` — the spec is
150
150
  the task file is the slice. If they disagree, implement the spec and note it in the task's
151
151
  ## Discussion.
152
152
 
153
+ Playbook — if the task is a defect, read bug-fix.md from ~/.ukit/playbooks/ (perf:
154
+ performance.md, migration: migration.md) and copy its numbered steps into your todos (skip:/n/a: <reason>,
155
+ never drop one). This brief wins on conflict: no commits, TDD and the report shape below.
156
+
153
157
  TDD — mandatory:
154
158
  1. Write tests from §Test Cases
155
159
  run <test command> from the worktree root (your cwd IS .worktrees/task-xxx — no cd)
@@ -1444,6 +1444,34 @@ function applyTaskSemantics(contract, semantic) {
1444
1444
  }
1445
1445
  return tierLaneModule;
1446
1446
  }
1447
+ // Playbook delivery (pstack port): the selected playbook body rides the
1448
+ // prompt turn verbatim — telemetry showed agents never Read a playbook file
1449
+ // from a "read playbooks/<id>.md" cue (relative path absent in projects).
1450
+ // Ambiguous routes list the candidates so the agent picks one instead of the
1451
+ // playbook silently vanishing. Prompt turns only; fail-open.
1452
+ async function writePlaybookLines(summary) {
1453
+ try {
1454
+ if (summary?.playbookId && summary.playbookFile) {
1455
+ const registry = await loadPlaybookRegistry();
1456
+ const body = typeof registry?.readPlaybookBody === 'function'
1457
+ ? await registry.readPlaybookBody(summary.playbookFile)
1458
+ : null;
1459
+ if (body) {
1460
+ process.stdout.write(`[ukit-skill-router] Playbook: ${summary.playbookId} — copy its numbered steps verbatim as your first todos; a step you skip stays with "skip: <reason>", a step that does not apply stays with "n/a: <reason>"; end with its Reply contract.\n<ukit-playbook id="${summary.playbookId}">\n${body}\n</ukit-playbook>\n`);
1461
+ return;
1462
+ }
1463
+ }
1464
+ const candidates = Array.isArray(summary?.playbookCandidates)
1465
+ ? summary.playbookCandidates.filter((id) => typeof id === 'string' && id && id !== 'handoff-cycle').slice(0, 4)
1466
+ : [];
1467
+ if (!summary?.playbookId && summary?.playbookReason === 'ambiguous-route' && candidates.length > 1) {
1468
+ const dir = path.join(os.homedir(), '.ukit', 'playbooks');
1469
+ process.stdout.write(`[ukit-skill-router] Playbook candidates: ${candidates.join(', ')} — pick the one matching the user's primary intent, Read ${dir}/<id>.md and follow its steps (or note "playbook: none — <reason>").\n`);
1470
+ }
1471
+ } catch {
1472
+ // delivery is advisory — never break routing
1473
+ }
1474
+ }
1447
1475
  function writeTierLaneLines(summary, taskId) {
1448
1476
  if (summary?.playbookId === 'bug-fix') {
1449
1477
  process.stdout.write('[ukit-skill-router] Bug-fix evidence (include in any worker prompt): before editing, run the failing repro once and keep its failing result; after the fix re-run that same command and keep the passing result; state the root cause with UKIT_EVIDENCE="class=root-cause;claim=<mechanism>" on a Bash call. A worker\'s own runs count for this task only through its host-linked session.\n');
@@ -1584,7 +1612,7 @@ function applyTaskSemantics(contract, semantic) {
1584
1612
  // bundle the hook spreads into routeSummary — hook and helper emit the
1585
1613
  // identical playbookId/workGroup. Missing registry degrades to
1586
1614
  // playbookId: null (the state still carries the field for parity).
1587
- const playbook = { playbookId: null, workGroup: null, playbookReason: null, playbookLoad: null, path: null, fastPathKind: null };
1615
+ const playbook = { playbookId: null, workGroup: null, playbookReason: null, playbookLoad: null, path: null, fastPathKind: null, playbookFile: null, playbookCandidates: null };
1588
1616
  try {
1589
1617
  const registry = await loadPlaybookRegistry();
1590
1618
  if (registry && typeof registry.resolvePlaybookRoute === 'function') {
@@ -1607,6 +1635,10 @@ function applyTaskSemantics(contract, semantic) {
1607
1635
  // resolver's FR-004 fastPath eligibility object intact (M03).
1608
1636
  playbook.path = resolution.path ?? null;
1609
1637
  playbook.fastPathKind = resolution.fastPath ?? null;
1638
+ // Delivery fields: the resolved file (body injected on the prompt turn)
1639
+ // and ambiguous candidates (agent picks — never silently drop).
1640
+ playbook.playbookFile = resolution.file ?? null;
1641
+ playbook.playbookCandidates = Array.isArray(resolution.candidates) ? resolution.candidates : null;
1610
1642
  }
1611
1643
  } catch {
1612
1644
  playbook.playbookReason = 'registry-error';
@@ -1671,6 +1703,10 @@ function applyTaskSemantics(contract, semantic) {
1671
1703
  if (routeSummary.playbookReason === undefined) {
1672
1704
  routeSummary.playbookReason = fields.playbookReason ?? null;
1673
1705
  }
1706
+ if (!onlyMissing || routeSummary.playbookFile === undefined) {
1707
+ routeSummary.playbookFile = fields.playbookFile ?? null;
1708
+ routeSummary.playbookCandidates = fields.playbookCandidates ?? null;
1709
+ }
1674
1710
  if (routeSummary.playbookLoad === undefined) {
1675
1711
  routeSummary.playbookLoad = fields.playbookLoad ?? null;
1676
1712
  }
@@ -1686,6 +1722,7 @@ function applyTaskSemantics(contract, semantic) {
1686
1722
  if (!routeSummary || !prev?.playbookId) return;
1687
1723
  if (!taskId || previousState.taskInstanceId !== taskId) return;
1688
1724
  if (!routeSummary.playbookId) {
1725
+ // playbookFile is deliberately NOT inherited: a continuation turn must not re-inject the body.
1689
1726
  for (const key of ['playbookId', 'workGroup', 'playbookReason', 'playbookLoad', 'path', 'fastPathKind']) {
1690
1727
  if (prev[key] !== undefined && prev[key] !== null) routeSummary[key] = prev[key];
1691
1728
  }
@@ -3109,7 +3146,9 @@ function applyTaskSemantics(contract, semantic) {
3109
3146
  return false;
3110
3147
  }
3111
3148
  }
3112
- const implementWords = /(?<![A-Za-z0-9_])(implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|build|chạy|cài)(?![A-Za-z0-9_])/.test(raw);
3149
+ // chạy/tạo/cài are judged by the shared position rule (ambiguousVerbOrder), not by bare presence.
3150
+ const implementWords = /(?<![A-Za-z0-9_])(implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|xóa|đổi|thay thế|cập nhật|viết|build)(?![A-Za-z0-9_])/.test(softenEnglishNouns(raw))
3151
+ || ambiguousVerbOrder(raw);
3113
3152
  if (implementWords && !consultShape) return false;
3114
3153
  const investigationWords = /\b(why|debug|triage|root cause|investigate|tại sao)\b/.test(raw);
3115
3154
  if (investigationWords && !consultShape) return false;
@@ -3229,7 +3268,51 @@ function applyTaskSemantics(contract, semantic) {
3229
3268
  // folding, so "Cái này là gì, tại sao…" is not read as an install order (3.4.81 telemetry audit).
3230
3269
  function maskTonedNonVerbs(text = '') {
3231
3270
  return String(text ?? '').normalize('NFC')
3232
- .replace(/(?<![\p{L}\p{N}_])(?:cái|chính|việt|cháy|chảy|đợi|đời|đối|đội|đôi|đói|sữa|thèm)(?![\p{L}\p{N}_])/giu, ' _ ');
3271
+ .replace(/(?<![\p{L}\p{N}_])(?:cái|cải|cãi|chính|việt|cháy|chảy|đợi|đời|đối|đội|đôi|đói|sữa|thèm)(?![\p{L}\p{N}_])/giu, ' _ ');
3272
+ }
3273
+ // Position rule for the closed set of verbs that tone-fold onto an order verb but are ordinary
3274
+ // aspect/nominal words in progress talk: ch\u1ea1y (run / is running), t\u1ea1o (create / the creation of),
3275
+ // c\u1ea3i/c\u00e0i (improve / install). Input is folded (accent-free, lowercase) text. A verb is an ORDER when it
3276
+ // has an object or an imperative particle; it is NOT an order after a nominaliser/preposition/copula/
3277
+ // aspect marker (PREV = cua, viec, su, khi, dang) or when only a stative/degree complement follows
3278
+ // (co ve + lau, mai, hoai, cham, nhanh, xong, roi, duoc, qua, rat, hoi, ne, then end of clause or a conjunction).
3279
+ // Imperative particles (di, luon, ngay, giup, gium, ho, nhe) within 3 tokens always keep it an order.
3280
+ // Non-orders become " _ "; orders are untouched. English: a mutation word right after a determiner/possessive is
3281
+ // a noun ("the build"), unless a light verb stands before the determiner ("do the build", "finish that update").
3282
+ // Destructive verbs (x\u00f3a, delete, drop, reset) are deliberately not in this set.
3283
+ // Three copies (taskRouting.js, route-task.mjs, skill-router.sh) \u2014 keep them identical.
3284
+ function softenEnglishNouns(text = '') {
3285
+ return String(text).replace(/(?<!\b(?:do|does|doing|perform|finish|complete|handle|start|get|try)\s+)\b(the|a|an|any|this|that|these|those|my|our|your|its|their|his|her)\s+(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|rename|change|write|build|make|install|run|deploy|execute|edit)\b/gi, '$1 _ ');
3286
+ }
3287
+ function softenAmbiguousVerbs(folded = '') {
3288
+ const PREV = new Set(['cua', 'viec', 'su', 'khi', 'dang']);
3289
+ const PARTICLE = new Set(['di', 'luon', 'ngay', 'giup', 'gium', 'ho', 'nhe']);
3290
+ const COMPLEMENT = new Set(['lau', 'mai', 'hoai', 'cham', 'nhanh', 'xong', 'roi', 'duoc', 'qua', 'rat', 'hoi', 'ne']);
3291
+ const CONJ = new Set(['ma', 'nhung', 'va', 'thi', 'hay', 'nen', 'khong', 'chua', 'but', 'and', 'so']);
3292
+ // Each occurrence is judged on its own (a clause can hold several: "tạo ra Ukit là cải tiến ...").
3293
+ // English: a mutation token right after a determiner/possessive is a noun ("the build", "my fix"), never an
3294
+ // order. Only that token is softened, so "run the build" / "fix the build" still order through the verb.
3295
+ // delete/remove are never softened.
3296
+ return softenEnglishNouns(folded).replace(/\b(chay|tao|cai)\b/g, (match, verb, offset, whole) => {
3297
+ const prev = whole.slice(0, offset).trimEnd().split(/\s+/).pop() || '';
3298
+ const tokens = (whole.slice(offset + match.length).split(/[.,;!?\n]/)[0] || '').split(/\s+/).filter(Boolean);
3299
+ if (tokens.slice(0, 3).some((token) => PARTICLE.has(token))) return match;
3300
+ if (PREV.has(prev)) return ' _ ';
3301
+ let index = 0;
3302
+ let consumed = 0;
3303
+ while (index < tokens.length) {
3304
+ if (tokens[index] === 'co' && tokens[index + 1] === 've') { index += 2; consumed += 1; continue; }
3305
+ if (COMPLEMENT.has(tokens[index])) { index += 1; consumed += 1; continue; }
3306
+ break;
3307
+ }
3308
+ if (consumed > 0 && (index >= tokens.length || CONJ.has(tokens[index]))) return ' _ ';
3309
+ return match;
3310
+ });
3311
+ }
3312
+ // The shared predicate: does any ambiguous verb in this text still stand as an order?
3313
+ function ambiguousVerbOrder(text = '') {
3314
+ const folded = maskTonedNonVerbs(text).toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/\u0111/g, 'd');
3315
+ return /\b(?:chay|tao|cai)\b/.test(softenAmbiguousVerbs(folded));
3233
3316
  }
3234
3317
  function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
3235
3318
  const folded = `${publicationScope(maskTonedNonVerbs(promptText)).text}\n${commandText ?? ''}`
@@ -3237,7 +3320,7 @@ function applyTaskSemantics(contract, semantic) {
3237
3320
  .normalize('NFD')
3238
3321
  .replace(/[\u0300-\u036f]/g, '')
3239
3322
  .replace(/\u0111/g, 'd');
3240
- const trimmed = folded.trim();
3323
+ const trimmed = softenAmbiguousVerbs(folded.trim());
3241
3324
  if (!trimmed) return false;
3242
3325
  if (ordersPublication(promptText)) return true;
3243
3326
  if (!String(commandText ?? '').trim() && (declaredReadOnly(promptText, classifyTaskSemantics({ promptText }).releasePolicy)
@@ -3465,7 +3548,6 @@ function applyTaskSemantics(contract, semantic) {
3465
3548
  // it with hasMutationOrder keeps "sửa file cho tôi?" mutating while
3466
3549
  // "lỗi này chưa nhỉ" / "should I fix the hook?" consult. A targetFile
3467
3550
  // still vetoes.
3468
- const consultationImplementWords = /(?<![A-Za-z0-9_])(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|chạy|cài)(?![A-Za-z0-9_])/.test(trimmedPromptText);
3469
3551
  const consultationOnlySignal = questionShapedPrompt
3470
3552
  && !hasMutationOrder({ promptText, commandText })
3471
3553
  && !targetFile;
@@ -4109,6 +4191,8 @@ function applyTaskSemantics(contract, semantic) {
4109
4191
  fastPathKind: routeSummary.fastPathKind ?? null,
4110
4192
  ...(routeSummary.playbookReason ? { playbookReason: routeSummary.playbookReason } : {}),
4111
4193
  ...(routeSummary.playbookLoad ? { playbookLoad: routeSummary.playbookLoad } : {}),
4194
+ ...(routeSummary.playbookFile ? { playbookFile: routeSummary.playbookFile } : {}),
4195
+ ...(Array.isArray(routeSummary.playbookCandidates) && routeSummary.playbookCandidates.length ? { playbookCandidates: routeSummary.playbookCandidates } : {}),
4112
4196
  completionState: routeSummary.completionState || null,
4113
4197
  continuationState: routeSummary.continuationState || null,
4114
4198
  delegateHint: routeSummary.delegateHint || null,
@@ -4213,6 +4297,11 @@ function applyTaskSemantics(contract, semantic) {
4213
4297
  playbookId: routeSummary.playbookId ?? null,
4214
4298
  workGroup: routeSummary.workGroup ?? null,
4215
4299
  playbookLoad: routeSummary.playbookLoad ?? null,
4300
+ // Telemetry: why a playbook did or did not resolve (ambiguous-route,
4301
+ // no-route-match, playbook-missing …) + the tied candidates, so the
4302
+ // selector hit rate is measurable from route-audit alone.
4303
+ playbookReason: routeSummary.playbookReason ?? null,
4304
+ playbookCandidates: Array.isArray(routeSummary.playbookCandidates) ? routeSummary.playbookCandidates.slice(0, 8) : null,
4216
4305
  // BL-010: direct/handoff path + fast-path enum on the audit row so the
4217
4306
  // eval join can assert `direct, fastPath=small-feature` (E-01).
4218
4307
  path: routeSummary.path ?? null,
@@ -4760,7 +4849,7 @@ function applyTaskSemantics(contract, semantic) {
4760
4849
  // its own: mutationOrder recomputed from a file path / the word "continue" / guidance
4761
4850
  // wording says nothing about what the user ordered, so the original prompt's stamp
4762
4851
  // stays authoritative.
4763
- if ((!extractPrompt(payload) || continuationPrompt || systemOriginTurn || guidanceTurn) && typeof previous.routingContext.mutationOrder === 'boolean') {
4852
+ if ((!extractPrompt(payload) || continuationPrompt || embeddedContinuationPrompt || systemOriginTurn || guidanceTurn) && typeof previous.routingContext.mutationOrder === 'boolean') {
4764
4853
  persisted.routingContext.mutationOrder = previous.routingContext.mutationOrder;
4765
4854
  }
4766
4855
  }
@@ -5443,7 +5532,45 @@ function applyTaskSemantics(contract, semantic) {
5443
5532
  const owned = targets(previous.routingContext?.lastExplicitUserPromptText);
5444
5533
  return wanted.size > 0 && [...wanted].every((target) => owned.has(target));
5445
5534
  })();
5446
- const continuingTask = Boolean(previous.taskInstanceId && (payload.tool_name || handoffExpansion || continuationPrompt || ownerResumeTurn || systemOriginTurn || guidanceTurn));
5535
+ // Clause-level continuation ("nếu có tiến triển thì tiếp tục làm", "tiếp tục. không dừng, nhớ check ..."):
5536
+ // at least one clause is a bare continuation (optionally behind a conditional head) and EVERY other
5537
+ // clause is a non-order by the same predicate that stamps mutationOrder. It binds only to a LIVE contract
5538
+ // of this session (never to suspendedContract: only the whole-string explicit continuation restores that),
5539
+ // mints nothing when there is none, and never overrides an owner STOP. Any ordering clause -> fresh task.
5540
+ const embeddedContinuationPrompt = (() => {
5541
+ if (explicitContinuationPrompt || payload.tool_name || ownerControlTurn || !sessionId || !previous.taskInstanceId) return false;
5542
+ if (!previous.routeSummary?.executionContract?.completionEvidence?.length || previous.routeSummary.executionContract.statusReport) return false;
5543
+ const raw = extractPrompt(payload);
5544
+ if (!raw.trim() || raw.length > 1200) return false;
5545
+ const fold = (text) => String(text ?? '').normalize('NFD').replace(/\p{M}+/gu, '').replace(/đ/gi, 'd').toLowerCase();
5546
+ const CONT ='(?:continue|resume|keep going|go on|proceed|tiep tuc|lam tiep)(?:\\s+(?:lam|viec|di|nhe|nao|nua|a|ha|please|pls|now|then|it|that|going|on|working))*';
5547
+ // Group 1 = the conditional head. A head that itself carries an order ("neu xong thi sua ham login roi
5548
+ // tiep tuc") is not a bare continuation: the head is checked WITHOUT the conditional strip hasMutationOrder applies.
5549
+ const bare = new RegExp(`^(?:(?:neu|if|khi|when)\\s+(.{1,80}?)\\s+(?:(?:thi|then)\\s+)?)?${CONT}\\s*$`);
5550
+ const clauses = raw.split(/[.!?;\n,]+/).map((clause) => clause.trim()).filter(Boolean);
5551
+ if (clauses.length < 2 && !clauses.some((clause) => !new RegExp(`^${CONT}\\s*$`).test(fold(clause)) && bare.test(fold(clause)))) return false;
5552
+ let continuation = false;
5553
+ // Any mutation verb in the head disqualifies it (hasMutationOrder would strip a conditional tail, and reads
5554
+ // "xong thi sua ham login roi" as already done). Ambiguous verbs go through the same position rule.
5555
+ // The head is a CONDITION only: a consequent inside it ("thi ..."/"then ...") is an action riding the old task,
5556
+ // and publication/operation verbs (push, commit, publish, release, merge, tag, restart) count as orders too.
5557
+ const HEAD_VERB = /\b(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|push|commit|publish|release|merge|tag|rebase|restart|sua|them|tao|xoa|doi|cap\s+nhat|viet|chay|cai|chinh|trien\s+khai|cau\s+hinh|dang\s+len)\b/;
5558
+ // ONE predicate for "this text carries an order": a mutation order, a publication order, or an operation verb.
5559
+ // It judges the head AND every non-continuation clause (a plain "push luon" is OPERATIONAL, not a bare continuation).
5560
+ const OP_VERB = /\b(?:push|commit|publish|release|merge|tag|rebase|restart|dang\s+len)\b/;
5561
+ const carriesOrder = (text) => hasMutationOrder({ promptText: text, commandText: '' }) || ordersPublication(text) || OP_VERB.test(softenAmbiguousVerbs(fold(text)));
5562
+ for (const clause of clauses) {
5563
+ const match = bare.exec(fold(maskTonedNonVerbs(clause)));
5564
+ if (match) {
5565
+ if (match[1] && (/\b(?:thi|then)\b/.test(match[1]) || HEAD_VERB.test(softenAmbiguousVerbs(match[1])) || carriesOrder(match[1]))) return false;
5566
+ continuation = true;
5567
+ continue;
5568
+ }
5569
+ if (carriesOrder(clause)) return false;
5570
+ }
5571
+ return continuation && !carriesOrder(raw);
5572
+ })();
5573
+ const continuingTask = Boolean(previous.taskInstanceId && (payload.tool_name || handoffExpansion || continuationPrompt || embeddedContinuationPrompt || ownerResumeTurn || systemOriginTurn || guidanceTurn));
5447
5574
  // An owner prompt that explicitly resumes the previous checkpoint (names its background job id or commit)
5448
5575
  // still mints a fresh task id - the contract may legitimately differ (e.g. a new deploy authorization) -
5449
5576
  // but records a bounded single-hop predecessor link so the ledger can reconcile current evidence. A
@@ -6227,6 +6354,9 @@ function applyTaskSemantics(contract, semantic) {
6227
6354
  process.stdout.write(`[ukit-skill-router] Delegate: ${routeSummary.delegateHint}\n`);
6228
6355
  }
6229
6356
  writeTierLaneLines(routeSummary, taskInstanceId);
6357
+ if (!payload.tool_name && promptText && routingContext.taskType !== 'trivial') {
6358
+ await writePlaybookLines(routeSummary);
6359
+ }
6230
6360
  if (
6231
6361
  routeSummary.helperHint
6232
6362
  && !routeSummary.nextActionCommand
@@ -201,6 +201,11 @@ const GENERIC_STOPWORDS = new Set([
201
201
  'neu', 'nhung', 'nua', 'roi', 'toi', 'tren', 'truoc', 'va', 'voi',
202
202
  ]);
203
203
  const VIETNAMESE_PHRASE_ALIASES = [
204
+ // Bigrams only: the unigrams "trien"/"khai" also fold "tiến triển" (progress) / "khai" in unrelated
205
+ // words onto implement/build/ship, which selected the delivery skill for progress questions (3.5.8).
206
+ { regex: /\btrien khai\b/gu, expansions: ['implement', 'deploy', 'ship'] },
207
+ { regex: /\bphat trien\b/gu, expansions: ['develop', 'build'] },
208
+ { regex: /\bkhai bao\b/gu, expansions: ['declare'] },
204
209
  { regex: /\bbo nho dem\b/gu, expansions: ['cache'] },
205
210
  { regex: /\bduong dan\b/gu, expansions: ['route', 'path'] },
206
211
  { regex: /\bxac thuc\b/gu, expansions: ['auth', 'authentication'] },
@@ -272,8 +277,6 @@ const VIETNAMESE_TOKEN_ALIASES = new Map([
272
277
  ['component', ['component']],
273
278
  ['test', ['test', 'testing']],
274
279
  ['soat', ['review', 'audit']],
275
- ['trien', ['implement', 'build', 'ship']],
276
- ['khai', ['implement', 'build', 'ship']],
277
280
  ['kho', ['store', 'storage']],
278
281
  ['ghi', ['write', 'record']],
279
282
  ['doc', ['read']],
@@ -48,7 +48,7 @@ export const PLAYBOOK_ID_ALIASES = Object.freeze({
48
48
  // --- Shared signal vocabulary ------------------------------------------------
49
49
  // Compiled once; every row's discriminator reads the same normalized signals so
50
50
  // confusable pairs split on the discriminator column, never trigger text.
51
- const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b/i;
51
+ const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b|(?<![\p{L}\p{N}_])(?:viết|viet)(?![\p{L}\p{N}_])/iu;
52
52
  // Vietnamese words never match `\b` (JS word chars are ASCII-only — 'sửa' ends
53
53
  // in a non-word char, 'đổi' starts with one), so the diacritic alternates use
54
54
  // explicit lookarounds instead. Same word list as the original literal.
@@ -396,6 +396,20 @@ function matchFirst(text, regexes) {
396
396
  return -1;
397
397
  }
398
398
 
399
+ // "thêm" is both the order "add" and the adverb "more/additional". The order
400
+ // leads its clause ("thêm nút Save", "giúp tôi thêm …"); the adverb trails a
401
+ // verb/noun ("học hỏi gì thêm", "tích hợp thêm ý tưởng") or is the word under
402
+ // discussion ("thêm cũng có nghĩa là more"). Only the order counts as create.
403
+ const THEM_ORDER_LEAD = new Set(['hãy', 'hay', 'giúp', 'giùm', 'cho', 'tôi', 'mình', 'em', 'anh', 'bạn', 'và', 'rồi', 'thì', 'cần', 'lại', 'luôn', 'lòng', 'please']);
404
+ function stripAdverbialThem(text) {
405
+ return text
406
+ .replace(/(^|[\s.,;:!?])thêm(?=\s+(?:cũng|có nghĩa|nghĩa là|là|nữa)(?![\p{L}\p{N}_]))/giu, '$1 ')
407
+ .replace(/(?<!\S)(\S{1,40})(\s+)thêm(?![\p{L}\p{N}_])/giu, (match, prev, space) => {
408
+ if (/[.,;:!?]$/.test(prev) || THEM_ORDER_LEAD.has(prev.toLowerCase())) return match;
409
+ return `${prev}${space} `;
410
+ });
411
+ }
412
+
399
413
  async function buildRouteSignals({
400
414
  signalText,
401
415
  rawPromptText = '',
@@ -410,10 +424,14 @@ async function buildRouteSignals({
410
424
  // because no consult pattern consumes its clause.
411
425
  const verbScanText = signalText
412
426
  .replace(/(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+[^\n?]*/g, ' ')
413
- .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s*[?.!]?\s*$/g, ' ')
414
- .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ');
427
+ .replace(/[^\n.,;?]{0,80}\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|không|khong|rồi|roi|nhỉ|nhi|ạ|a)\s{0,16}[?.!]?\s{0,16}$/g, ' ')
428
+ .replace(/\b(?:có|co)\s+(?:nên|nen|cần|can|phải|phai)\s+[^\n?]*/g, ' ')
429
+ // A mid-prompt question clause ("học hỏi gì thêm … vậy.", "apply có tốt hơn
430
+ // không, …") is an ask too — only true question particles close it here
431
+ // ('rồi' stays out: "fix X rồi, chạy test" means "then").
432
+ .replace(/[^\n.,;?]{0,80}(?:\b(?:không|khong|chưa|chua|được không|duoc khong|đúng không|dung khong|nhỉ)|(?<![A-Za-z0-9_])vậy)\s*[?.!,;]/g, ' ');
415
433
  const changeIdx = verbScanText.search(CHANGE_VERB_RE);
416
- const createIdx = verbScanText.search(CREATE_VERB_RE);
434
+ const createIdx = stripAdverbialThem(verbScanText).search(CREATE_VERB_RE);
417
435
  const explainIdx = signalText.search(EXPLAIN_ASK_RE);
418
436
  const defectIdx = signalText.search(DEFECT_TRIGGER_RE);
419
437
  const checkIdx = signalText.search(CHECK_VERB_RE);
@@ -421,7 +439,7 @@ async function buildRouteSignals({
421
439
  const consultLead = /(?:^|[.!;\n]\s*)(?:should|shall|do|does|did|can|could|would|will|is|are|am)\s+(?:i|we|you)\s+/
422
440
  .test(signalText)
423
441
  || /\b(?:co|có)\s+(?:nên|nen|cần|can|phải|phai)\s+/.test(signalText)
424
- || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s*[?.!]?\s*$/.test(signalText);
442
+ || /\b(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|nhỉ|nhi|rồi|roi)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
425
443
  const firstVerbIdx = [changeIdx, createIdx].filter((i) => i !== -1).sort((a, b) => a - b)[0] ?? -1;
426
444
  const explanationAsk = explainIdx !== -1 && (firstVerbIdx === -1 || explainIdx < firstVerbIdx);
427
445
  const changeRequested = !consultLead && firstVerbIdx !== -1 && (explainIdx === -1 || firstVerbIdx < explainIdx);
@@ -439,7 +457,7 @@ async function buildRouteSignals({
439
457
  || /\b(how|why|what|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(signalText)
440
458
  || /(?:có|co)\s+(?:phải|phai)\s+/.test(signalText)
441
459
  || /(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|thế nào|the nao|như thế nào|nhu the nao|tại sao|tai sao|là gì|la gi|bao giờ|bao gio|khi nào|khi nao|ở đâu|o dau|không biết|khong biet)/.test(signalText)
442
- || /(?:chưa|chua|đúng không|dung khong|không|khong)\s*[?.!]?\s*$/.test(signalText);
460
+ || /(?:chưa|chua|đúng không|dung khong|không|khong)\s{0,16}[?.!]?\s{0,16}$/.test(signalText);
443
461
  const questionAsk = questionShaped && !changeRequested;
444
462
  const referenceTarget = REFERENCE_TARGET_RE.test(signalText);
445
463
  const cloneIntent = CLONE_INTENT_RE.test(signalText);
@@ -622,6 +640,34 @@ export async function loadRegistry({ projectRoot = null, homeDir = null, builtin
622
640
  return records;
623
641
  }
624
642
 
643
+ // Delivery: the playbook body (frontmatter stripped, CRLF normalized) for
644
+ // injection into the routed turn. Bounded so a hand-edited user playbook can
645
+ // never flood the context; null on any read/parse failure (fail-open).
646
+ export const PLAYBOOK_BODY_MAX_CHARS = 2400;
647
+ export async function readPlaybookBody(filePath, { maxChars = PLAYBOOK_BODY_MAX_CHARS } = {}) {
648
+ if (typeof filePath !== 'string' || filePath === '') return null;
649
+ let raw;
650
+ try {
651
+ raw = await fs.readFile(filePath, 'utf8');
652
+ } catch {
653
+ return null;
654
+ }
655
+ const text = String(raw).replace(/\r\n/g, '\n');
656
+ let body = text;
657
+ if (text.startsWith('---\n')) {
658
+ const fenceIndex = text.indexOf('\n---', 3);
659
+ if (fenceIndex === -1) return null;
660
+ body = text.slice(fenceIndex + 4).replace(/^\n/, '');
661
+ }
662
+ // A body cannot close the <ukit-playbook> wrapper early.
663
+ body = body.trim().replace(/<\/ukit-playbook>/gi, '&lt;/ukit-playbook>');
664
+ if (body === '') return null;
665
+ if (body.length <= maxChars) return body;
666
+ // Cut on a code-point boundary (never split a surrogate pair).
667
+ const cut = Array.from(body.slice(0, maxChars + 1)).slice(0, -1).join('').slice(0, maxChars);
668
+ return `${cut.trimEnd()}\n[…truncated — full text: ${filePath}]`;
669
+ }
670
+
625
671
  function findRegistryRecord(records, playbookId) {
626
672
  const direct = records.find((r) => r.frontmatterValid && r.playbookId === playbookId);
627
673
  if (direct) return direct;
@@ -813,5 +859,11 @@ export async function resolvePlaybookRoute({
813
859
  fastPath: resolution.fastPath ?? null,
814
860
  reason: resolution.reason ?? null,
815
861
  playbookLoad: resolution.reason === 'playbook-missing' ? 'missing' : null,
862
+ // Delivery fields: the resolved file lets the hook inject the playbook body
863
+ // (agents never Read a relative `playbooks/<id>.md` that does not exist in
864
+ // the project); ambiguous candidates let the agent pick instead of losing
865
+ // the playbook entirely (pstack posture — the model chooses on ties).
866
+ file: resolution.file ?? null,
867
+ candidates: Array.isArray(resolution.candidates) ? resolution.candidates : null,
816
868
  };
817
869
  }
@@ -77,7 +77,7 @@ import {
77
77
  deriveRouteFields,
78
78
  } from './route-resolver.mjs';
79
79
  import { applyMeasuredTier, loadTierMap } from './tier-selection.mjs';
80
- import { resolvePlaybookRoute, loadRegistry, deriveRouteOrchestrationSignals } from './playbook-registry.mjs';
80
+ import { resolvePlaybookRoute, loadRegistry, deriveRouteOrchestrationSignals, readPlaybookBody as readRegistryPlaybookBody } from './playbook-registry.mjs';
81
81
  import { extractHistorySignalsAsync } from './session-history-extractor.mjs';
82
82
  import { carryProgress, buildDecompositionPlan, estimateContextWindow, MIN_AUTO_SPLIT_CONFIDENCE } from '../runtime/context-budget-policy.mjs';
83
83
  import {
@@ -1560,7 +1560,7 @@ async function main() {
1560
1560
  try { await requirePersistedRouteState(sharedStatePath, sharedState, { expectedRouteBytes }); }
1561
1561
  catch (error) { console.error(`route-task: state persist degraded — ${error?.message ?? error}`); }
1562
1562
  }
1563
- printRouteState(sharedState);
1563
+ printRouteState(await withPlaybookBody(sharedState));
1564
1564
  return;
1565
1565
  }
1566
1566
 
@@ -1666,7 +1666,7 @@ async function main() {
1666
1666
  console.error(`route-task: state persist degraded — ${error?.message ?? error}`);
1667
1667
  }
1668
1668
  }
1669
- printRouteState(sharedState);
1669
+ printRouteState(await withPlaybookBody(sharedState));
1670
1670
  return;
1671
1671
  }
1672
1672
 
@@ -1729,7 +1729,7 @@ async function main() {
1729
1729
  }
1730
1730
  }
1731
1731
 
1732
- printRouteState(sharedState);
1732
+ printRouteState(await withPlaybookBody(sharedState));
1733
1733
 
1734
1734
  // 3.3.0: Codex has no hook lifecycle — route-task is the one helper it runs
1735
1735
  // per task, so it doubles as the self-improve trigger there. Fire-and-forget:
@@ -2765,6 +2765,8 @@ async function finalizeTaskRoute({
2765
2765
  routeSummary.workGroup = playbookResolution.workGroup;
2766
2766
  routeSummary.playbookReason = playbookResolution.reason;
2767
2767
  routeSummary.playbookLoad = playbookResolution.playbookLoad;
2768
+ routeSummary.playbookFile = playbookResolution.file ?? null;
2769
+ routeSummary.playbookCandidates = Array.isArray(playbookResolution.candidates) ? playbookResolution.candidates : null;
2768
2770
  // BL-010 (ARCH Task Contract): `path` = direct|handoff; `fastPathKind` is
2769
2771
  // the ARCH `none|small-feature|bug-fix` enum — named Kind because
2770
2772
  // routeSummary.fastPath already carries the FR-004 eligibility object.
@@ -2969,6 +2971,21 @@ async function finalizeTaskRoute({
2969
2971
  };
2970
2972
  }
2971
2973
 
2974
+ // Playbook delivery: Codex/omp/print consumers read stdout, not files — an
2975
+ // absolute path alone was never followed, so the body prints with the route.
2976
+ // Read here (print-only copy) so persisted state never carries the body;
2977
+ // trivial routes get no playbook (instructions: trivial edits need none).
2978
+ async function withPlaybookBody(state) {
2979
+ try {
2980
+ const summary = state?.routeSummary;
2981
+ if (!summary?.playbookId || !summary.playbookFile || state?.routingContext?.taskType === 'trivial') return state;
2982
+ const playbookBody = await readRegistryPlaybookBody(summary.playbookFile);
2983
+ return playbookBody ? { ...state, routeSummary: { ...summary, playbookBody } } : state;
2984
+ } catch {
2985
+ return state;
2986
+ }
2987
+ }
2988
+
2972
2989
  function printRouteState(state) {
2973
2990
  const compactSummary = formatDisplayRouteSummary(state.routeSummary, state.routingContext);
2974
2991
  const nextDisplay = formatDisplayNextAction(state.routeSummary);
@@ -3051,13 +3068,27 @@ function printRouteState(state) {
3051
3068
  // TASK-007 (BL-009): playbook surface — the instruction-mediated load cue
3052
3069
  // Codex and print consumers read. playbookId only prints when a playbook
3053
3070
  // resolved; the degrade reason stays machine-side on the route record.
3054
- if (state.routeSummary?.playbookId) {
3055
- console.log(`playbook: ${state.routeSummary.playbookId} — read playbooks/${state.routeSummary.playbookId}.md and run its steps verbatim`);
3071
+ const trivialRoute = state.routingContext?.taskType === 'trivial';
3072
+ if (state.routeSummary?.playbookId && !trivialRoute) {
3073
+ console.log(`playbook: ${state.routeSummary.playbookId} — copy its numbered steps verbatim as your first todos; skipped steps keep skip:<reason>, non-applicable keep n/a:<reason>`);
3074
+ if (state.routeSummary.playbookBody) {
3075
+ console.log(`<ukit-playbook id="${state.routeSummary.playbookId}">\n${state.routeSummary.playbookBody}\n</ukit-playbook>`);
3076
+ } else if (state.routeSummary.playbookFile) {
3077
+ console.log(`playbookFile: ${state.routeSummary.playbookFile}`);
3078
+ }
3079
+ } else if (!trivialRoute && state.routeSummary?.playbookReason === 'ambiguous-route' && Array.isArray(state.routeSummary.playbookCandidates)) {
3080
+ const candidates = state.routeSummary.playbookCandidates.filter((id) => id && id !== 'handoff-cycle').slice(0, 4);
3081
+ if (candidates.length > 1) {
3082
+ console.log(`playbook candidates: ${candidates.join(', ')} — pick the one matching the primary intent and Read ${path.join(os.homedir(), '.ukit', 'playbooks')}/<id>.md`);
3083
+ }
3056
3084
  }
3057
- if (state.routeSummary?.workflowPolicyName) {
3085
+ // The injected playbook body supersedes the lane workflow policy — printing
3086
+ // both would duplicate the step list (token waste, conflicting steps).
3087
+ const playbookDelivered = Boolean(state.routeSummary?.playbookId && state.routeSummary?.playbookBody);
3088
+ if (!playbookDelivered && state.routeSummary?.workflowPolicyName) {
3058
3089
  console.log(`workflow: ${state.routeSummary.workflowPolicyName} — copy steps verbatim into your todo list; skipped steps keep skip:<reason>`);
3059
3090
  }
3060
- if (state.routeSummary?.workflowPolicy) {
3091
+ if (!playbookDelivered && state.routeSummary?.workflowPolicy) {
3061
3092
  console.log(state.routeSummary.workflowPolicy);
3062
3093
  }
3063
3094
  if (state.routeSummary?.principleIndex) {
@@ -4703,7 +4734,9 @@ function isInformationalPrompt({
4703
4734
  }
4704
4735
  // C85-019: consult-shape also overrides the vocabulary vetoes — the
4705
4736
  // mutation/debug/lỗi words are the question's SUBJECT, not the ask.
4706
- const implementWords = /(?<![A-Za-z0-9_])(implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|build|chạy|cài)(?![A-Za-z0-9_])/.test(raw);
4737
+ // chạy/tạo/cài are judged by the shared position rule (ambiguousVerbOrder), not by bare presence.
4738
+ const implementWords = /(?<![A-Za-z0-9_])(implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|xóa|đổi|thay thế|cập nhật|viết|build)(?![A-Za-z0-9_])/.test(softenEnglishNouns(raw))
4739
+ || ambiguousVerbOrder(raw);
4707
4740
  if (implementWords && !consultShape) return false;
4708
4741
  const investigationWords = /\b(why|debug|triage|root cause|investigate|tại sao)\b/.test(raw);
4709
4742
  if (investigationWords && !consultShape) return false;
@@ -4901,7 +4934,51 @@ export function classifyAdvisorRequest({ promptText = '', commandText = '' } = {
4901
4934
  // folding, so "Cái này là gì, tại sao…" is not read as an install order (3.4.81 telemetry audit).
4902
4935
  function maskTonedNonVerbs(text = '') {
4903
4936
  return String(text ?? '').normalize('NFC')
4904
- .replace(/(?<![\p{L}\p{N}_])(?:cái|chính|việt|cháy|chảy|đợi|đời|đối|đội|đôi|đói|sữa|thèm)(?![\p{L}\p{N}_])/giu, ' _ ');
4937
+ .replace(/(?<![\p{L}\p{N}_])(?:cái|cải|cãi|chính|việt|cháy|chảy|đợi|đời|đối|đội|đôi|đói|sữa|thèm)(?![\p{L}\p{N}_])/giu, ' _ ');
4938
+ }
4939
+ // Position rule for the closed set of verbs that tone-fold onto an order verb but are ordinary
4940
+ // aspect/nominal words in progress talk: ch\u1ea1y (run / is running), t\u1ea1o (create / the creation of),
4941
+ // c\u1ea3i/c\u00e0i (improve / install). Input is folded (accent-free, lowercase) text. A verb is an ORDER when it
4942
+ // has an object or an imperative particle; it is NOT an order after a nominaliser/preposition/copula/
4943
+ // aspect marker (PREV = cua, viec, su, khi, dang) or when only a stative/degree complement follows
4944
+ // (co ve + lau, mai, hoai, cham, nhanh, xong, roi, duoc, qua, rat, hoi, ne, then end of clause or a conjunction).
4945
+ // Imperative particles (di, luon, ngay, giup, gium, ho, nhe) within 3 tokens always keep it an order.
4946
+ // Non-orders become " _ "; orders are untouched. English: a mutation word right after a determiner/possessive is
4947
+ // a noun ("the build"), unless a light verb stands before the determiner ("do the build", "finish that update").
4948
+ // Destructive verbs (x\u00f3a, delete, drop, reset) are deliberately not in this set.
4949
+ // Three copies (taskRouting.js, route-task.mjs, skill-router.sh) \u2014 keep them identical.
4950
+ function softenEnglishNouns(text = '') {
4951
+ return String(text).replace(/(?<!\b(?:do|does|doing|perform|finish|complete|handle|start|get|try)\s+)\b(the|a|an|any|this|that|these|those|my|our|your|its|their|his|her)\s+(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|rename|change|write|build|make|install|run|deploy|execute|edit)\b/gi, '$1 _ ');
4952
+ }
4953
+ function softenAmbiguousVerbs(folded = '') {
4954
+ const PREV = new Set(['cua', 'viec', 'su', 'khi', 'dang']);
4955
+ const PARTICLE = new Set(['di', 'luon', 'ngay', 'giup', 'gium', 'ho', 'nhe']);
4956
+ const COMPLEMENT = new Set(['lau', 'mai', 'hoai', 'cham', 'nhanh', 'xong', 'roi', 'duoc', 'qua', 'rat', 'hoi', 'ne']);
4957
+ const CONJ = new Set(['ma', 'nhung', 'va', 'thi', 'hay', 'nen', 'khong', 'chua', 'but', 'and', 'so']);
4958
+ // Each occurrence is judged on its own (a clause can hold several: "tạo ra Ukit là cải tiến ...").
4959
+ // English: a mutation token right after a determiner/possessive is a noun ("the build", "my fix"), never an
4960
+ // order. Only that token is softened, so "run the build" / "fix the build" still order through the verb.
4961
+ // delete/remove are never softened.
4962
+ return softenEnglishNouns(folded).replace(/\b(chay|tao|cai)\b/g, (match, verb, offset, whole) => {
4963
+ const prev = whole.slice(0, offset).trimEnd().split(/\s+/).pop() || '';
4964
+ const tokens = (whole.slice(offset + match.length).split(/[.,;!?\n]/)[0] || '').split(/\s+/).filter(Boolean);
4965
+ if (tokens.slice(0, 3).some((token) => PARTICLE.has(token))) return match;
4966
+ if (PREV.has(prev)) return ' _ ';
4967
+ let index = 0;
4968
+ let consumed = 0;
4969
+ while (index < tokens.length) {
4970
+ if (tokens[index] === 'co' && tokens[index + 1] === 've') { index += 2; consumed += 1; continue; }
4971
+ if (COMPLEMENT.has(tokens[index])) { index += 1; consumed += 1; continue; }
4972
+ break;
4973
+ }
4974
+ if (consumed > 0 && (index >= tokens.length || CONJ.has(tokens[index]))) return ' _ ';
4975
+ return match;
4976
+ });
4977
+ }
4978
+ // The shared predicate: does any ambiguous verb in this text still stand as an order?
4979
+ function ambiguousVerbOrder(text = '') {
4980
+ const folded = maskTonedNonVerbs(text).toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/\u0111/g, 'd');
4981
+ return /\b(?:chay|tao|cai)\b/.test(softenAmbiguousVerbs(folded));
4905
4982
  }
4906
4983
  function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
4907
4984
  const folded = `${maskTonedNonVerbs(promptText)}\n${commandText ?? ''}`
@@ -4909,7 +4986,7 @@ function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
4909
4986
  .normalize('NFD')
4910
4987
  .replace(/[\u0300-\u036f]/g, '')
4911
4988
  .replace(/\u0111/g, 'd');
4912
- const trimmed = folded.trim();
4989
+ const trimmed = softenAmbiguousVerbs(folded.trim());
4913
4990
  if (!trimmed) return false;
4914
4991
  // C85-019c: clause strips must stop BEFORE a conjunction-joined imperative
4915
4992
  // — "giữ nguyên header và sửa lỗi login" keeps 'và sửa lỗi' as a surviving
@@ -5077,7 +5154,6 @@ function deriveExecutionMode({
5077
5154
  // an edit order, not a consultation). A leading interrogative overrides them:
5078
5155
  // "Lam sao ma do duoc khi toi cai…?" asks HOW something is done, it does not order
5079
5156
  // the action performed.
5080
- const consultationImplementWords = /(?<![A-Za-z0-9_])(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|chạy|cài)(?![A-Za-z0-9_])/.test(trimmedPromptText);
5081
5157
  // C85-019: question shape + no surviving imperative = consult. The
5082
5158
  // pre-C85-019 all-zero-scores clause consulted only when NOTHING in the
5083
5159
  // prompt resembled work — impossible for a question about code. Replacing
@@ -6302,6 +6378,11 @@ export function compactRouteSummary(routeSummary = null) {
6302
6378
  fastPathKind: routeSummary.fastPathKind ?? null,
6303
6379
  ...(routeSummary.playbookReason ? { playbookReason: routeSummary.playbookReason } : {}),
6304
6380
  ...(routeSummary.playbookLoad ? { playbookLoad: routeSummary.playbookLoad } : {}),
6381
+ // Playbook delivery: file/candidates survive compaction (the body is read
6382
+ // at print time and never persisted; conditional — absent keys keep
6383
+ // unrouted states byte-identical).
6384
+ ...(routeSummary.playbookFile ? { playbookFile: routeSummary.playbookFile } : {}),
6385
+ ...(Array.isArray(routeSummary.playbookCandidates) && routeSummary.playbookCandidates.length ? { playbookCandidates: routeSummary.playbookCandidates } : {}),
6305
6386
  // M04.1 (TASK-007): the resumable-run pointer survives compaction so
6306
6387
  // reinject-context resumes from the same taskId/boundary. Conditional
6307
6388
  // spread — stage-off output stays byte-identical (no key when absent).
@@ -6461,6 +6542,8 @@ function buildRouteAuditEntry({ route = null, state = null } = {}) {
6461
6542
  playbookId: routeSummary.playbookId ?? null,
6462
6543
  workGroup: routeSummary.workGroup ?? null,
6463
6544
  playbookLoad: routeSummary.playbookLoad ?? null,
6545
+ playbookReason: routeSummary.playbookReason ?? null,
6546
+ playbookCandidates: Array.isArray(routeSummary.playbookCandidates) ? routeSummary.playbookCandidates.slice(0, 8) : null,
6464
6547
  path: routeSummary.path ?? null,
6465
6548
  fastPathKind: routeSummary.fastPathKind ?? null,
6466
6549
  source: state?.source ?? 'task-route',
@@ -34,7 +34,7 @@ files before widening further. These node scripts work unchanged under omp.
34
34
 
35
35
  Skills live in `.claude/skills/`, read by omp through its `claude` discovery provider — no mirror under
36
36
  `.omp/`. On any non-trivial task — and again after the first tool calls reveal the real work — read the
37
- matching `SKILL.md` without being asked. Users never name skills.
37
+ matching `SKILL.md` without being asked. Users never name skills. Playbooks (no command): a routed `<ukit-playbook>`/`playbook:` → copy its numbered steps as first todos (`skip:`/`n/a: <reason>`, never drop), end with its **Reply**; none or candidates → pick by intent from `~/.ukit/playbooks/` (bug-fix, small-feature, feature-implementation, refactor, investigation, performance, migration, verification, release, session-pickup) and read it.
38
38
 
39
39
  ## 6. Delegate to bind a model tier
40
40
 
@@ -56,6 +56,11 @@
56
56
  ### Common skill triggers
57
57
  - review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
58
58
 
59
+ ## Playbooks (automatic — no command)
60
+ - Non-trivial work runs a playbook from `~/.ukit/playbooks/<id>.md`. When the router injects one (`<ukit-playbook>` block or `playbook:` route line), copy its numbered steps verbatim as your first todos — a skipped step stays as `skip: <reason>`, a non-applicable one as `n/a: <reason>` — and end with its **Reply** contract.
61
+ - No playbook injected, or the router lists candidates → pick yourself from the user's primary intent and Read that file: defect → `bug-fix` · new/changed behavior → `small-feature` (1-2 files) or `feature-implementation` · structure only → `refactor` · read-only question → `investigation` · measured slowness → `performance` · live hang/leak → `runtime-forensics` · data/schema move → `migration` · run a named check → `verification` · ship/publish → `release` · resume earlier work → `session-pickup`. Trivial edits and plain continuations ("tiếp tục", "push luôn") need none.
62
+ - `/ukit:handoff-*` commands already carry their own phases; follow them, not a second playbook (their executor briefs name one per task where it applies).
63
+
59
64
  ## Internal Helper Policy
60
65
  <!-- RULES: HELP-01 HELP-02 -->
61
66
  - Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, verification.
@@ -56,6 +56,11 @@
56
56
  ### Common skill triggers
57
57
  - review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
58
58
 
59
+ ## Playbooks (automatic — no command)
60
+ - Non-trivial work runs a playbook from `~/.ukit/playbooks/<id>.md`. When the router injects one (`<ukit-playbook>` block or `playbook:` route line), copy its numbered steps verbatim as your first todos — a skipped step stays as `skip: <reason>`, a non-applicable one as `n/a: <reason>` — and end with its **Reply** contract.
61
+ - No playbook injected, or the router lists candidates → pick yourself from the user's primary intent and Read that file: defect → `bug-fix` · new/changed behavior → `small-feature` (1-2 files) or `feature-implementation` · structure only → `refactor` · read-only question → `investigation` · measured slowness → `performance` · live hang/leak → `runtime-forensics` · data/schema move → `migration` · run a named check → `verification` · ship/publish → `release` · resume earlier work → `session-pickup`. Trivial edits and plain continuations ("tiếp tục", "push luôn") need none.
62
+ - `/ukit:handoff-*` commands already carry their own phases; follow them, not a second playbook (their executor briefs name one per task where it applies).
63
+
59
64
  ## Internal Helper Policy
60
65
  <!-- RULES: HELP-01 HELP-02 -->
61
66
  - Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, verification.
@@ -53,6 +53,11 @@
53
53
  ### Common skill triggers
54
54
  - review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
55
55
 
56
+ ## Playbooks (automatic — no command)
57
+ - Non-trivial work runs a playbook from `~/.ukit/playbooks/<id>.md`. When the router injects one (`<ukit-playbook>` block or `playbook:` route line), copy its numbered steps verbatim as your first todos — a skipped step stays as `skip: <reason>`, a non-applicable one as `n/a: <reason>` — and end with its **Reply** contract.
58
+ - No playbook injected, or the router lists candidates → pick yourself from the user's primary intent and Read that file: defect → `bug-fix` · new/changed behavior → `small-feature` (1-2 files) or `feature-implementation` · structure only → `refactor` · read-only question → `investigation` · measured slowness → `performance` · live hang/leak → `runtime-forensics` · data/schema move → `migration` · run a named check → `verification` · ship/publish → `release` · resume earlier work → `session-pickup`. Trivial edits and plain continuations ("tiếp tục", "push luôn") need none.
59
+ - `/ukit:handoff-*` commands already carry their own phases; follow them, not a second playbook (their executor briefs name one per task where it applies).
60
+
56
61
  ## Internal Helper Policy
57
62
  <!-- RULES: HELP-01 HELP-02 -->
58
63
  - Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, verification.
@@ -18,6 +18,7 @@ outputs:
18
18
  - { from: core, heading: Long-Run Continuity }
19
19
  - { from: core, heading: Index-First Loop }
20
20
  - { from: core, heading: Automatic Skill Activation (mandatory) }
21
+ - { from: core, heading: Playbooks (automatic — no command) }
21
22
  - { from: core, heading: Internal Helper Policy }
22
23
  - { from: core, heading: Skill Quality (maintainer-only) }
23
24
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -50,6 +51,7 @@ outputs:
50
51
  - { from: core, heading: Long-Run Continuity }
51
52
  - { from: core, heading: Index-First Loop }
52
53
  - { from: core, heading: Automatic Skill Activation (mandatory) }
54
+ - { from: core, heading: Playbooks (automatic — no command) }
53
55
  - { from: core, heading: Internal Helper Policy }
54
56
  - { from: core, heading: Skill Quality (maintainer-only) }
55
57
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -92,6 +94,7 @@ outputs:
92
94
  - { from: core, heading: Long-Run Continuity }
93
95
  - { from: core, heading: Index-First Loop }
94
96
  - { from: core, heading: Automatic Skill Activation (mandatory) }
97
+ - { from: core, heading: Playbooks (automatic — no command) }
95
98
  - { from: core, heading: Internal Helper Policy }
96
99
  - { from: core, heading: Skill Quality (maintainer-only) }
97
100
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -125,6 +128,7 @@ outputs:
125
128
  - { from: core, heading: Long-Run Continuity }
126
129
  - { from: core, heading: Index-First Loop }
127
130
  - { from: core, heading: Automatic Skill Activation (mandatory) }
131
+ - { from: core, heading: Playbooks (automatic — no command) }
128
132
  - { from: core, heading: Internal Helper Policy }
129
133
  - { from: core, heading: Skill Quality (maintainer-only) }
130
134
  - { from: core, heading: 'UKit v{{ukit.version}} Shared Runtime' }
@@ -31,7 +31,7 @@ files before widening further. These node scripts work unchanged under omp.
31
31
 
32
32
  Skills live in `.claude/skills/`, read by omp through its `claude` discovery provider — no mirror under
33
33
  `.omp/`. On any non-trivial task — and again after the first tool calls reveal the real work — read the
34
- matching `SKILL.md` without being asked. Users never name skills.
34
+ matching `SKILL.md` without being asked. Users never name skills. Playbooks (no command): a routed `<ukit-playbook>`/`playbook:` → copy its numbered steps as first todos (`skip:`/`n/a: <reason>`, never drop), end with its **Reply**; none or candidates → pick by intent from `~/.ukit/playbooks/` (bug-fix, small-feature, feature-implementation, refactor, investigation, performance, migration, verification, release, session-pickup) and read it.
35
35
 
36
36
  ## 6. Delegate to bind a model tier
37
37