@ngockhoale/ukit 3.5.8 → 3.5.10

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,28 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.5.10 - 2026-11-19
6
+
7
+ Sessions compacted after two or three prompts. Three causes, all fixed at the source; no new command. No host was run live; the checks are unit, parity and hook-process tests.
8
+
9
+ - **Claude Code now knows the real context window.** Gateway aliases such as `unic-opus` are unknown to Claude Code, which then assumes 200k and compacts around 167k. `compact.contextWindowTokens` (default 250000) renders `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` is `0.8 × hardCapTokens` = 188000. omp keeps `compaction.thresholdTokens` from the same budget.
10
+ - **One budget, consistent defaults.** `tokenThreshold` 115000, `hardCapTokens` 235000, both below the declared window. A hard cap above the window (old installs carried 500000) is clamped to the window at runtime, so teams that never edit their config get the new limits after `ukit update`.
11
+ - **Output compression really replaces the output.** The PostToolUse hook used to add its summary next to the full Bash output, so nothing was saved. On Claude Code it now returns `hookSpecificOutput.updatedToolOutput` with the summary, only when the full output was written to a tee log the summary points to. omp and Codex keep plain-text output.
12
+ - Stale tracked `.omp/RULES.md` re-rendered (worktree preflight tests).
13
+
14
+ ## 3.5.9 - 2026-11-18
15
+
16
+ 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.
17
+
18
+ - **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.
19
+ - **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.
20
+ - **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.
21
+ - **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.
22
+ - **Route audit rows record why no playbook was chosen** (`playbookReason`, `playbookCandidates`) so the hit rate can be re-measured.
23
+ - **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.
24
+
25
+ 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.
26
+
5
27
  ## 3.5.8 - 2026-11-16
6
28
 
7
29
  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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.8",
3
+ "version": "3.5.10",
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",
@@ -1,11 +1,12 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { fileURLToPath } from 'node:url';
3
3
 
4
- // The shipped compact.tokenThreshold / compact.hardCapTokens / compact.autoCompactWindowRatio
5
- // trio is the ONLY place the context budget is written down. Every other number — the
6
- // code-side defaults, CLAUDE_CODE_AUTO_COMPACT_WINDOW in .claude/settings.json, and
4
+ // The shipped compact.tokenThreshold / contextWindowTokens / hardCapTokens /
5
+ // autoCompactWindowRatio numbers are the ONLY place the context budget is written down. Every other number — the
6
+ // code-side defaults, CLAUDE_CODE_MAX_CONTEXT_TOKENS + CLAUDE_CODE_AUTO_COMPACT_WINDOW in
7
+ // .claude/settings.json, and
7
8
  // compaction.thresholdTokens in .omp/config.yml — is read or derived from here, so retuning
8
- // UKit for a different model context window is a three-number edit in
9
+ // UKit for a different model context window is a config-only edit in
9
10
  // template_project/ukit/storage/config.json and nothing else.
10
11
  const SHIPPED_CONFIG_URL = new URL('../../../template_project/ukit/storage/config.json', import.meta.url);
11
12
 
@@ -15,6 +16,7 @@ const EMERGENCY_BUDGET = {
15
16
  tokenThreshold: 50_000,
16
17
  hardCapTokens: 160_000,
17
18
  autoCompactWindowRatio: 0.7,
19
+ contextWindowTokens: 200_000,
18
20
  };
19
21
 
20
22
  // Auto-compact must land strictly below hardCapTokens so the client heals itself before
@@ -44,10 +46,21 @@ export function deriveCompactBudget(compact = {}) {
44
46
  const tokenThreshold = Number.isFinite(source.tokenThreshold)
45
47
  ? source.tokenThreshold
46
48
  : EMERGENCY_BUDGET.tokenThreshold;
47
- const hardCapTokens = positiveInteger(source.hardCapTokens, EMERGENCY_BUDGET.hardCapTokens);
49
+ // compact.contextWindowTokens is the model window UKit tells the client to assume
50
+ // (CLAUDE_CODE_MAX_CONTEXT_TOKENS). It is a deliberate operator CEILING, not a probe of
51
+ // what the provider accepts: a gateway alias such as unic-opus is unknown to Claude Code,
52
+ // and without this it silently falls back to 200k (or 1M), ignoring UKit's budget.
53
+ const contextWindowTokens = positiveInteger(source.contextWindowTokens, EMERGENCY_BUDGET.contextWindowTokens);
54
+ // The hard cap must sit inside the window it guards; a cap above the window could never
55
+ // fire before the provider rejects the request.
56
+ const hardCapTokens = Math.min(
57
+ positiveInteger(source.hardCapTokens, EMERGENCY_BUDGET.hardCapTokens),
58
+ contextWindowTokens,
59
+ );
48
60
  return {
49
61
  tokenThreshold,
50
62
  hardCapTokens,
63
+ contextWindowTokens,
51
64
  autoCompactWindow: deriveAutoCompactWindow(hardCapTokens, source.autoCompactWindowRatio),
52
65
  };
53
66
  }
@@ -462,13 +462,17 @@ export async function buildCompactThresholds(config = {}) {
462
462
  config?.compact?.hardCapTokens,
463
463
  loadShippedCompactBudget().hardCapTokens,
464
464
  );
465
+ // Upgrade safety: an install that predates compact.contextWindowTokens still carries the
466
+ // old 500k hard cap; the cap must never sit above the declared window it guards.
467
+ const declaredWindow = positiveInteger(config?.compact?.contextWindowTokens, 0);
468
+ const effectiveShippedHardCap = declaredWindow > 0 ? Math.min(shippedHardCap, declaredWindow) : shippedHardCap;
465
469
  const explicitSoftThreshold = finiteNumber(config?.compact?.tokenThreshold, 0);
466
470
  // Negotiated capacity (H22): the guard publishes what it derived from the live route and
467
471
  // this shared path consumes it; without a record the shipped tuning applies unchanged.
468
472
  const negotiated = await readNegotiatedCapacity(config);
469
473
  const hardCapTokens = negotiated
470
- ? Math.max(1, Math.min(shippedHardCap, negotiated.capTokens))
471
- : shippedHardCap;
474
+ ? Math.max(1, Math.min(effectiveShippedHardCap, negotiated.capTokens))
475
+ : effectiveShippedHardCap;
472
476
  // An explicit operator tokenThreshold is honoured but still clamped under the
473
477
  // negotiated cap: an advisory soft/hard pair sitting at or above hardCapTokens can
474
478
  // never fire, because context-hardcap-gate.sh already refuses tools at the cap
@@ -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.
@@ -20,7 +20,7 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
20
20
  // Derived, never hand-written: .claude/settings.json is read by Claude Code itself and so
21
21
  // cannot consult .ukit/storage/config.json at runtime. Baking the window in here keeps
22
22
  // compact.hardCapTokens the single number that retunes both.
23
- const { autoCompactWindow } = loadShippedCompactBudget();
23
+ const { autoCompactWindow, contextWindowTokens } = loadShippedCompactBudget();
24
24
 
25
25
  // FR-004 — fail closed: `allow` only on an explicit user opt-in
26
26
  // (`orchestration.allowUnsafeEval === true`). Missing, unreadable, or
@@ -31,6 +31,7 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
31
31
  return {
32
32
  compact: {
33
33
  autoCompactWindow: String(autoCompactWindow),
34
+ maxContextTokens: String(contextWindowTokens),
34
35
  },
35
36
  project: {
36
37
  name: projectContext.project.name,
@@ -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)
@@ -1,9 +1,9 @@
1
1
  #!/bin/bash
2
2
  # PreToolUse hook: hard-enforce an absolute context token cap (compact.hardCapTokens,
3
- # default 500000, sized for a 1M window — must stay below the model's real context
4
- # window, so lower it on a 200k/256k model), separate from the
3
+ # default 235000 inside the shipped 250k compact.contextWindowTokens; Claude Code itself
4
+ # auto-compacts earlier, at round(hardCap * autoCompactWindowRatio)), separate from the
5
5
  # soft/hard advisory pressure phases in
6
- # compact-threshold.mjs (default soft=150000/hard=240000, which only print a suggestion).
6
+ # compact-threshold.mjs (default soft=115000/hard=184000, which only print a suggestion).
7
7
  #
8
8
  # Those advisory phases are just injected text — nothing stops the agent from ignoring
9
9
  # them and letting a session run to hundreds of thousands of tokens with no compaction.
@@ -132,7 +132,7 @@ if (!runtimeConfig || typeof runtimeConfig !== 'object') runtimeConfig = {};
132
132
  function operatorHardCap() {
133
133
  const value = runtimeConfig?.compact?.hardCapTokens;
134
134
  if (typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0) return value;
135
- return 500_000;
135
+ return 235_000;
136
136
  }
137
137
 
138
138
  // H04: bounded async tail scan instead of a whole-transcript sync stat/read/split. The
@@ -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
  }
@@ -4154,6 +4191,8 @@ function applyTaskSemantics(contract, semantic) {
4154
4191
  fastPathKind: routeSummary.fastPathKind ?? null,
4155
4192
  ...(routeSummary.playbookReason ? { playbookReason: routeSummary.playbookReason } : {}),
4156
4193
  ...(routeSummary.playbookLoad ? { playbookLoad: routeSummary.playbookLoad } : {}),
4194
+ ...(routeSummary.playbookFile ? { playbookFile: routeSummary.playbookFile } : {}),
4195
+ ...(Array.isArray(routeSummary.playbookCandidates) && routeSummary.playbookCandidates.length ? { playbookCandidates: routeSummary.playbookCandidates } : {}),
4157
4196
  completionState: routeSummary.completionState || null,
4158
4197
  continuationState: routeSummary.continuationState || null,
4159
4198
  delegateHint: routeSummary.delegateHint || null,
@@ -4258,6 +4297,11 @@ function applyTaskSemantics(contract, semantic) {
4258
4297
  playbookId: routeSummary.playbookId ?? null,
4259
4298
  workGroup: routeSummary.workGroup ?? null,
4260
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,
4261
4305
  // BL-010: direct/handoff path + fast-path enum on the audit row so the
4262
4306
  // eval join can assert `direct, fastPath=small-feature` (E-01).
4263
4307
  path: routeSummary.path ?? null,
@@ -6310,6 +6354,9 @@ function applyTaskSemantics(contract, semantic) {
6310
6354
  process.stdout.write(`[ukit-skill-router] Delegate: ${routeSummary.delegateHint}\n`);
6311
6355
  }
6312
6356
  writeTierLaneLines(routeSummary, taskInstanceId);
6357
+ if (!payload.tool_name && promptText && routingContext.taskType !== 'trivial') {
6358
+ await writePlaybookLines(routeSummary);
6359
+ }
6313
6360
  if (
6314
6361
  routeSummary.helperHint
6315
6362
  && !routeSummary.nextActionCommand
@@ -11,6 +11,7 @@
11
11
  "defaultView": "chat",
12
12
  "autoCompactEnabled": true,
13
13
  "env": {
14
+ "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "{{compact.maxContextTokens}}",
14
15
  "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "{{compact.autoCompactWindow}}"
15
16
  },
16
17
  "permissions": {
@@ -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) {
@@ -6347,6 +6378,11 @@ export function compactRouteSummary(routeSummary = null) {
6347
6378
  fastPathKind: routeSummary.fastPathKind ?? null,
6348
6379
  ...(routeSummary.playbookReason ? { playbookReason: routeSummary.playbookReason } : {}),
6349
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 } : {}),
6350
6386
  // M04.1 (TASK-007): the resumable-run pointer survives compaction so
6351
6387
  // reinject-context resumes from the same taskId/boundary. Conditional
6352
6388
  // spread — stage-off output stays byte-identical (no key when absent).
@@ -6506,6 +6542,8 @@ function buildRouteAuditEntry({ route = null, state = null } = {}) {
6506
6542
  playbookId: routeSummary.playbookId ?? null,
6507
6543
  workGroup: routeSummary.workGroup ?? null,
6508
6544
  playbookLoad: routeSummary.playbookLoad ?? null,
6545
+ playbookReason: routeSummary.playbookReason ?? null,
6546
+ playbookCandidates: Array.isArray(routeSummary.playbookCandidates) ? routeSummary.playbookCandidates.slice(0, 8) : null,
6509
6547
  path: routeSummary.path ?? null,
6510
6548
  fastPathKind: routeSummary.fastPathKind ?? null,
6511
6549
  source: state?.source ?? 'task-route',
@@ -452,7 +452,7 @@ function computeEstimatedTotalTokens({
452
452
  // real serving model. This record is how negotiated capacity reaches the shared
453
453
  // threshold/gate path; without it a verified 200k route would still compact at 240k.
454
454
  export const CAPACITY_RECORD_SEGMENTS = ['.ukit', 'storage', 'cache', 'context-capacity.json'];
455
- // Shipped tuning as a ratio of the absolute cap (150_000 soft of a 500_000 cap), so a
455
+ // Shipped tuning as a ratio of the absolute cap (fallback when no explicit tokenThreshold is set), so a
456
456
  // smaller verified window moves the advisory phases down with the cap they precede.
457
457
  export const SOFT_TO_CAP_RATIO = 0.3;
458
458
 
@@ -489,14 +489,18 @@ export async function resolveCompactCapacity(config = {}, { record } = {}) {
489
489
 
490
490
  export async function buildCompactThresholds(config = {}) {
491
491
  const explicitSoftThreshold = finiteNumber(config?.compact?.tokenThreshold, 0);
492
- const shippedHardCap = positiveInteger(config?.compact?.hardCapTokens, 500_000);
492
+ const shippedHardCap = positiveInteger(config?.compact?.hardCapTokens, 235_000);
493
+ // Upgrade safety: an install that predates compact.contextWindowTokens still carries the
494
+ // old 500k hard cap; the cap must never sit above the declared window it guards.
495
+ const declaredWindow = positiveInteger(config?.compact?.contextWindowTokens, 0);
496
+ const effectiveShippedHardCap = declaredWindow > 0 ? Math.min(shippedHardCap, declaredWindow) : shippedHardCap;
493
497
  // Only tighten once a record exists: an install with no evidence yet (and every caller
494
498
  // that passes no project root) keeps the shipped tuning unchanged.
495
499
  const record = await readContextCapacityRecord(config?.projectRoot);
496
500
  const negotiated = record ? await resolveCompactCapacity(config, { record }) : null;
497
501
  const hardCapTokens = negotiated
498
- ? Math.max(1, Math.min(shippedHardCap, negotiated.capTokens))
499
- : shippedHardCap;
502
+ ? Math.max(1, Math.min(effectiveShippedHardCap, negotiated.capTokens))
503
+ : effectiveShippedHardCap;
500
504
  // An explicit operator tokenThreshold is honoured but still clamped under the
501
505
  // negotiated cap: an advisory soft/hard pair sitting at or above hardCapTokens can
502
506
  // never fire, because context-hardcap-gate.sh already refuses tools at the cap
@@ -30,7 +30,7 @@ export const CAPACITY_ENV_VAR = 'UKIT_CONTEXT_WINDOW_TOKENS';
30
30
  export const DEFAULT_CAPACITY_TOKENS = 100_000;
31
31
  // The shipped operator ceiling (compact.hardCapTokens) — only ever an UPPER bound; negotiated
32
32
  // capacity can tighten it but never raise it.
33
- export const SHIPPED_HARD_CAP_TOKENS = 500_000;
33
+ export const SHIPPED_HARD_CAP_TOKENS = 235_000;
34
34
  // A verified window is only ever usable as an estimate: the response itself plus the
35
35
  // char/token estimator's own undercount must fit too, so only half the window becomes
36
36
  // the advisory cap (500k cap from a 1M window — the original tuning, made explicit).
@@ -133,8 +133,15 @@ export function resolveContextCapacity({ env = {}, config = {}, modelMetadata =
133
133
  export function resolveContextCapTokens({ env, config, modelMetadata } = {}) {
134
134
  const capacity = resolveContextCapacity({ env, config, modelMetadata });
135
135
  const operatorHardCap = parseConfigTokenCount(config?.compact?.hardCapTokens);
136
- const ceiling = operatorHardCap ?? SHIPPED_HARD_CAP_TOKENS;
137
- const derived = capacity.source === 'default'
136
+ // Upgrade safety: an old operator hard cap (500k) never outranks a declared smaller window.
137
+ const declaredWindow = parseConfigTokenCount(config?.compact?.contextWindowTokens);
138
+ const baseCeiling = operatorHardCap ?? SHIPPED_HARD_CAP_TOKENS;
139
+ const ceiling = declaredWindow !== null ? Math.min(baseCeiling, declaredWindow) : baseCeiling;
140
+ // compact.contextWindowTokens is an operator declaration made together with hardCapTokens
141
+ // (the shipped pair is 250k window / 235k cap), so it is NOT halved: halving it would
142
+ // silently drop the gate to 125k and block tools long before Claude Code auto-compacts.
143
+ // Only env / model-table evidence keeps the conservative half-window estimate.
144
+ const derived = capacity.source === 'default' || (capacity.source === 'config' && operatorHardCap !== null)
138
145
  ? (operatorHardCap ?? capacity.tokens)
139
146
  : Math.round(capacity.tokens * CAPACITY_TO_CAP_RATIO);
140
147
  return {
@@ -31,6 +31,51 @@ function emitSystemMessage(text) {
31
31
  } catch { /* stdout already gone */ }
32
32
  }
33
33
 
34
+ // 3.5.10 context-budget fix: on Claude Code, plain PostToolUse stdout is only ADDED
35
+ // context — the full raw Bash output still reached the model and `savedTokens` was
36
+ // fictional. `hookSpecificOutput.updatedToolOutput` replaces the tool output before it
37
+ // is sent to the model; its value must match the Bash tool_response shape
38
+ // ({stdout, stderr, interrupted, isImage}). omp keeps plain text (its bridge already
39
+ // swaps Bash content for hook stdout); Codex has no PostToolUse replacement, so plain
40
+ // text there too. Replacement is only allowed when the full output stays recoverable:
41
+ // a failing command whose tee persist failed (no rawPath) falls back to add-context.
42
+ function resolveHookHarness(payload) {
43
+ const fromPayload = typeof payload?.ukit_harness === 'string' ? payload.ukit_harness.trim() : '';
44
+ if (fromPayload) return fromPayload;
45
+ const fromEnv = typeof process.env.UKIT_HARNESS === 'string' ? process.env.UKIT_HARNESS.trim() : '';
46
+ return fromEnv || 'claude-code';
47
+ }
48
+
49
+ export function buildCompressedHookOutput(payload, summary, { rawPath = '' } = {}) {
50
+ const text = String(summary ?? '');
51
+ const harness = resolveHookHarness(payload);
52
+ if (harness !== 'claude-code' && harness !== 'claude') return text;
53
+ // Quality first: only replace when the summary itself carries the recovery line for
54
+ // a persisted tee log. A failed tee persist (rawPath '') or a summary that could not
55
+ // fit the hint keeps the add-context behaviour so the raw output still reaches the
56
+ // model — failing commands included.
57
+ const recoverable = typeof rawPath === 'string' && rawPath !== ''
58
+ && text.includes(`Tee log: ${rawPath}`);
59
+ if (!recoverable) return text;
60
+ const original = payload?.tool_response && typeof payload.tool_response === 'object'
61
+ && !Array.isArray(payload.tool_response)
62
+ ? payload.tool_response
63
+ : {};
64
+ const updatedToolOutput = {
65
+ ...original,
66
+ stdout: text,
67
+ stderr: '',
68
+ interrupted: typeof original.interrupted === 'boolean' ? original.interrupted : false,
69
+ isImage: false,
70
+ };
71
+ return JSON.stringify({
72
+ hookSpecificOutput: {
73
+ hookEventName: 'PostToolUse',
74
+ updatedToolOutput,
75
+ },
76
+ });
77
+ }
78
+
34
79
  // BUG-C23-10: bare `.catch(() => {})` swallowed every sweep failure — a
35
80
  // persistent EACCES/ENOSPC on .ukit meant silent non-convergence of the tee/
36
81
  // backlog bound (live dir observed at 2,417 files). Announce the first failure
@@ -1194,6 +1239,8 @@ function extractExitCode(payload) {
1194
1239
  payload?.tool_output?.exit_code,
1195
1240
  payload?.tool_result?.exitCode,
1196
1241
  payload?.tool_result?.exit_code,
1242
+ payload?.tool_response?.exitCode,
1243
+ payload?.tool_response?.exit_code,
1197
1244
  payload?.exitCode,
1198
1245
  payload?.exit_code,
1199
1246
  ];
@@ -1411,8 +1458,11 @@ async function main() {
1411
1458
  return;
1412
1459
  }
1413
1460
 
1414
- const stdout = extractText(payload?.tool_output ?? payload?.tool_result ?? payload, ['stdout', 'output', 'result']);
1415
- const stderr = extractText(payload?.tool_output ?? payload?.tool_result ?? payload, ['stderr', 'error']);
1461
+ // Claude Code carries Bash output under `tool_response`; omp/legacy payloads under
1462
+ // tool_output/tool_result.
1463
+ const toolOutputSource = payload?.tool_output ?? payload?.tool_response ?? payload?.tool_result ?? payload;
1464
+ const stdout = extractText(toolOutputSource, ['stdout', 'output', 'result']);
1465
+ const stderr = extractText(toolOutputSource, ['stderr', 'error']);
1416
1466
  const exitCode = extractExitCode(payload);
1417
1467
  if (!stdout.trim() && !stderr.trim()) {
1418
1468
  process.exit(0);
@@ -1479,7 +1529,9 @@ async function main() {
1479
1529
  exitCode,
1480
1530
  }, sessionConfig);
1481
1531
  }
1482
- process.stdout.write(String(cached.content));
1532
+ process.stdout.write(buildCompressedHookOutput(payload, String(cached.content), {
1533
+ rawPath: cached.metadata?.rawPath ?? '',
1534
+ }));
1483
1535
  return;
1484
1536
  }
1485
1537
  }
@@ -1511,7 +1563,9 @@ async function main() {
1511
1563
  recoveryReason: historyMatch.recoveryReason,
1512
1564
  truncated: historyMatch.truncated,
1513
1565
  });
1514
- process.stdout.write(String(historyMatch.summary));
1566
+ process.stdout.write(buildCompressedHookOutput(payload, String(historyMatch.summary), {
1567
+ rawPath: historyMatch.rawPath,
1568
+ }));
1515
1569
  return;
1516
1570
  }
1517
1571
 
@@ -1607,7 +1661,9 @@ async function main() {
1607
1661
  });
1608
1662
  }
1609
1663
 
1610
- process.stdout.write(result.summary);
1664
+ process.stdout.write(buildCompressedHookOutput(payload, result.summary, {
1665
+ rawPath: rawOutputMetadata.rawPath,
1666
+ }));
1611
1667
  }
1612
1668
 
1613
1669
  // BUG-C23-13: only run main() on direct CLI invocation — an unguarded bottom
@@ -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.
@@ -82,8 +82,8 @@ Next: <bước kế tiếp chính xác>
82
82
  - Subagent ghi **full log vào task file trên đĩa**, chỉ trả về orchestrator ≤10 dòng (executor) / ≤6 dòng (reviewer). Paste log ngược lại orchestrator là nguyên nhân số 1 làm run chết vì hết context.
83
83
  - Hết mỗi wave: commit, ghi cursor, **collapse** wave đó còn 1 dòng/task trong bộ nhớ làm việc, rồi chạy tiếp.
84
84
  - Yêu cầu `/compact` **chỉ** được đặt ở cuối command, giữa 2 cycle. Giữa cycle thì tuyệt đối không — state đã nằm hết ở git + `INDEX.md` + `RUN.md` nên compact ở ranh giới cycle không mất gì.
85
- - Vượt `compact.hardCapTokens` (mặc định 500k = 50% của context window 1M) mà `RUN.md` còn run dở **hoặc ordinary routed task có session execution ledger còn thiếu completion evidence**: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit/verification đang dở và ghi state resume; không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
86
- - Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` = 70% của `hardCapTokens` (mặc định 350000 < 500k), render lúc install, nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor cho handoff run hoặc tiêu thụ resume intent cho ordinary task → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
85
+ - Vượt `compact.hardCapTokens` (mặc định 235k, trong `compact.contextWindowTokens` 250k) mà `RUN.md` còn run dở **hoặc ordinary routed task có session execution ledger còn thiếu completion evidence**: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit/verification đang dở và ghi state resume; không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
86
+ - Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` = `autoCompactWindowRatio` × `hardCapTokens` (mặc định 0.8 × 235k = 188000) và `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS` = `contextWindowTokens` (250000), render lúc install, nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor cho handoff run hoặc tiêu thụ resume intent cho ordinary task → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
87
87
  - Sửa một trong hai số đó thì phải giữ `autoCompactWindow < hardCapTokens`. Đảo thứ tự là deadlock: gate chặn tool trước → transcript ngừng lớn → ngưỡng auto-compact không bao giờ tới. `tests/core/autoCompactWindow.test.js` khóa bất biến này.
88
88
 
89
89
  ### Git
@@ -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
 
@@ -12,9 +12,10 @@
12
12
  },
13
13
  "compact": {
14
14
  "enabled": true,
15
- "tokenThreshold": 150000,
16
- "hardCapTokens": 500000,
17
- "autoCompactWindowRatio": 0.7,
15
+ "tokenThreshold": 115000,
16
+ "contextWindowTokens": 250000,
17
+ "hardCapTokens": 235000,
18
+ "autoCompactWindowRatio": 0.8,
18
19
  "hardCapBlock": true,
19
20
  "hardCapGraceCalls": 10,
20
21
  "contextRotDetection": true,
@@ -681,8 +682,9 @@
681
682
  "compact": {
682
683
  "enabled": "B\u1eadt/t\u1eaft to\u00e0n b\u1ed9 helper compact c\u1ee7a UKit.",
683
684
  "tokenThreshold": "Ng\u01b0\u1ee1ng token chung cho runtime compact d\u00f9ng chung.",
684
- "hardCapTokens": "Ng\u01b0\u1ee1ng c\u1ee9ng tuy\u1ec7t \u0111\u1ed1i (m\u1eb7c \u0111\u1ecbnh 500000 token \u01b0\u1edbc l\u01b0\u1ee3ng = 50% c\u1ee7a context window 1M). Ch\u1ea1m/v\u01b0\u1ee3t ng\u01b0\u1ee1ng n\u00e0y th\u00ec context coi nh\u01b0 qu\u00e1 d\u00e0i \u2014 kh\u00f4ng ph\u1ea3i g\u1ee3i \u00fd n\u1eefa, l\u00e0 b\u1eaft bu\u1ed9c. PH\u1ea2I th\u1ea5p h\u01a1n context window th\u1eadt c\u1ee7a model, n\u1ebfu kh\u00f4ng API s\u1ebd b\u00e1o l\u1ed7i v\u01b0\u1ee3t context tr\u01b0\u1edbc khi gate k\u1ecbp ch\u1eb7n \u2014 model 200k th\u00ec h\u1ea1 xu\u1ed1ng 100000, model 256k th\u00ec 128000. C\u1ea3 env.CLAUDE_CODE_AUTO_COMPACT_WINDOW (.claude/settings.json) l\u1eabn compaction.thresholdTokens (.omp/config.yml) \u0111\u1ec1u \u0111\u01b0\u1ee3c SUY RA t\u1eeb s\u1ed1 n\u00e0y khi ch\u1ea1y ukit install, n\u00ean ch\u1ec9 c\u1ea7n s\u1eeda \u1edf \u0111\u00e2y r\u1ed3i c\u00e0i l\u1ea1i l\u00e0 auto-compact c\u1ee7a c\u1ea3 Claude Code v\u00e0 omp \u0111\u1ed5i theo.",
685
- "autoCompactWindowRatio": "Auto-compact ch\u1ea1y \u1edf bao nhi\u00eau ph\u1ea7n c\u1ee7a hardCapTokens (m\u1eb7c \u0111\u1ecbnh 0.7 \u2192 350000). Ph\u1ea3i < 1 \u0111\u1ec3 client t\u1ef1 compact TR\u01af\u1edaC khi context-hardcap-gate ch\u1eb7n tool; s\u1ed1 c\u00e0ng nh\u1ecf th\u00ec compact c\u00e0ng s\u1edbm v\u00e0 c\u00e0ng nhi\u1ec1u \u0111\u1ec7m an to\u00e0n.",
685
+ "contextWindowTokens": "Context window t\u1ed1i \u0111a UKit cho client d\u00f9ng (m\u1eb7c \u0111\u1ecbnh 250000, k\u1ec3 c\u1ea3 khi provider h\u1ed7 tr\u1ee3 1M). Render th\u00e0nh env.CLAUDE_CODE_MAX_CONTEXT_TOKENS \u2014 model alias gateway nh\u01b0 unic-opus kh\u00f4ng c\u00f3 trong b\u1ea3ng c\u1ee7a Claude Code n\u00ean n\u1ebfu thi\u1ebfu s\u1ed1 n\u00e0y client t\u1ef1 \u0111o\u00e1n 200k/1M v\u00e0 b\u1ecf qua budget UKit. Kh\u00f4ng khuy\u1ebfn kh\u00edch t\u0103ng.",
686
+ "hardCapTokens": "Ng\u01b0\u1ee1ng c\u1ee9ng tuy\u1ec7t \u0111\u1ed1i (m\u1eb7c \u0111\u1ecbnh 235000 token \u01b0\u1edbc l\u01b0\u1ee3ng, n\u1eb1m trong contextWindowTokens 250000). Ch\u1ea1m/v\u01b0\u1ee3t ng\u01b0\u1ee1ng n\u00e0y th\u00ec context-hardcap-gate ch\u1eb7n Edit/Write/Bash \u2014 kh\u00f4ng ph\u1ea3i g\u1ee3i \u00fd n\u1eefa, l\u00e0 b\u1eaft bu\u1ed9c. Ph\u1ea3i \u2264 contextWindowTokens. env.CLAUDE_CODE_AUTO_COMPACT_WINDOW (.claude/settings.json) v\u00e0 compaction.thresholdTokens (.omp/config.yml) \u0111\u1ec1u \u0111\u01b0\u1ee3c SUY RA t\u1eeb s\u1ed1 n\u00e0y khi ch\u1ea1y ukit install.",
687
+ "autoCompactWindowRatio": "Auto-compact ch\u1ea1y \u1edf bao nhi\u00eau ph\u1ea7n c\u1ee7a hardCapTokens (m\u1eb7c \u0111\u1ecbnh 0.8 \u2192 188000). Ph\u1ea3i < 1 \u0111\u1ec3 client t\u1ef1 compact TR\u01af\u1edaC khi context-hardcap-gate ch\u1eb7n tool; s\u1ed1 c\u00e0ng nh\u1ecf th\u00ec compact c\u00e0ng s\u1edbm.",
686
688
  "hardCapBlock": "N\u1ebfu true, hook context-hardcap-gate ch\u1eb7n c\u1ee9ng Edit/Write/Bash (exit 2) khi v\u01b0\u1ee3t hardCapTokens, cho t\u1edbi khi c\u00f3 compact th\u1eadt (PreCompact) reset l\u1ea1i b\u1ed9 \u0111\u1ebfm.",
687
689
  "hardCapGraceCalls": "S\u1ed1 tool call \u0111\u01b0\u1ee3c ph\u00e9p ch\u1ea1y ti\u1ebfp sau khi v\u01b0\u1ee3t hardCapTokens khi handoff run trong docs/AI_HANDOFF/RUN.md ho\u1eb7c ordinary routed task c\u00f3 session execution ledger c\u00f2n dang d\u1edf (m\u1eb7c \u0111\u1ecbnh 10). \u0110\u00e2y ch\u1ec9 l\u00e0 landing window: ho\u00e0n t\u1ea5t edit/verification \u0111ang d\u1edf v\u00e0 ghi state resume, kh\u00f4ng m\u1edf task m\u1edbi. H\u1ebft grace l\u00e0 ch\u1eb7n c\u1ee9ng nh\u01b0 c\u0169. Budget t\u00ednh theo m\u1ed7i \u0111\u1ee3t v\u01b0\u1ee3t cap, ch\u1ec9 reset khi \u01b0\u1edbc l\u01b0\u1ee3ng token th\u1eadt s\u1ef1 gi\u1ea3m (c\u00f3 compact th\u1eadt) \u2014 kh\u00f4ng reset theo wave.",
688
690
  "contextRotDetection": "Ph\u00e1t hi\u1ec7n context qu\u00e1 d\u00e0i/d\u1ec5 m\u1ee5c \u0111\u1ec3 gi\u1eef l\u1ea1i state quan tr\u1ecdng tr\u01b0\u1edbc khi AI nh\u1edb sai.",