@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 +22 -0
- package/package.json +1 -1
- package/src/core/compact/contextBudget.js +18 -5
- package/src/core/compact/threshold.js +6 -2
- package/src/index/playbookRegistry.js +58 -6
- package/src/index/taskRouting.js +4 -0
- package/src/render/buildVariables.js +2 -1
- package/template_project/.claude/commands/ukit/handoff-fullstack.md +4 -0
- package/template_project/.claude/commands/ukit/handoff-implement.md +4 -0
- package/template_project/.claude/hooks/context-hardcap-gate.sh +3 -3
- package/template_project/.claude/hooks/context-window-guard.sh +1 -1
- package/template_project/.claude/hooks/skill-router.sh +48 -1
- package/template_project/.claude/settings.json +1 -0
- package/template_project/.claude/ukit/index/playbook-registry.mjs +58 -6
- package/template_project/.claude/ukit/index/route-task.mjs +46 -8
- package/template_project/.claude/ukit/runtime/compact-threshold.mjs +8 -4
- package/template_project/.claude/ukit/runtime/context-capacity.mjs +10 -3
- package/template_project/.claude/ukit/runtime/output-compression.mjs +61 -5
- package/template_project/.omp/RULES.md +1 -1
- package/template_project/AGENTS.md +5 -0
- package/template_project/CLAUDE.md +5 -0
- package/template_project/docs/AI_HANDOFF/RULES.md +2 -2
- package/template_project/instructions/core.md +5 -0
- package/template_project/instructions/layout.yaml +4 -0
- package/template_project/instructions/overlays/omp-rules.md +1 -1
- package/template_project/ukit/storage/config.json +7 -5
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,11 +1,12 @@
|
|
|
1
1
|
import { readFileSync } from 'node:fs';
|
|
2
2
|
import { fileURLToPath } from 'node:url';
|
|
3
3
|
|
|
4
|
-
// The shipped compact.tokenThreshold /
|
|
5
|
-
//
|
|
6
|
-
// code-side defaults, CLAUDE_CODE_AUTO_COMPACT_WINDOW in
|
|
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
|
|
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
|
-
|
|
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(
|
|
471
|
-
:
|
|
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/
|
|
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
|
|
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
|
|
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
|
|
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, '</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
|
}
|
package/src/index/taskRouting.js
CHANGED
|
@@ -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
|
|
4
|
-
#
|
|
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=
|
|
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
|
|
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
|
|
@@ -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/
|
|
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
|
|
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
|
|
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
|
|
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, '</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
|
-
|
|
3055
|
-
|
|
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
|
-
|
|
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 (
|
|
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,
|
|
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(
|
|
499
|
-
:
|
|
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 =
|
|
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
|
-
|
|
137
|
-
const
|
|
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
|
-
|
|
1415
|
-
|
|
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
|
|
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` =
|
|
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":
|
|
16
|
-
"
|
|
17
|
-
"
|
|
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
|
-
"
|
|
685
|
-
"
|
|
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.",
|