@ngockhoale/ukit 3.5.14 → 3.5.17

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.
Files changed (30) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/package.json +2 -1
  3. package/scripts/release/candidate-state.mjs +2 -1
  4. package/scripts/release/heavy-first.mjs +12 -0
  5. package/scripts/release/release-steps.mjs +7 -4
  6. package/scripts/release/run-core-batch.mjs +50 -0
  7. package/src/diagnostics/routeOutcomes.js +5 -1
  8. package/src/diagnostics/skillAccuracy.js +5 -2
  9. package/template_project/.claude/hooks/delegation-gate.mjs +1 -1
  10. package/template_project/.claude/hooks/skill-router.sh +13 -0
  11. package/template_project/.claude/hooks/task-watchdog.sh +7 -7
  12. package/template_project/.claude/skills/backend-api/SKILL.md +1 -1
  13. package/template_project/.claude/skills/delivery/SKILL.md +1 -1
  14. package/template_project/.claude/skills/docs-manager/SKILL.md +1 -1
  15. package/template_project/.claude/skills/duraone/SKILL.md +2 -1
  16. package/template_project/.claude/skills/file-organizer/SKILL.md +1 -1
  17. package/template_project/.claude/skills/frontend/SKILL.md +1 -1
  18. package/template_project/.claude/skills/frontend-vue/SKILL.md +1 -1
  19. package/template_project/.claude/skills/pdf-processing/SKILL.md +1 -1
  20. package/template_project/.claude/skills/postgres/SKILL.md +1 -1
  21. package/template_project/.claude/skills/testing-quality/SKILL.md +2 -0
  22. package/template_project/.claude/skills/webapp-testing/SKILL.md +1 -1
  23. package/template_project/.claude/ukit/index/route-task.mjs +3 -1
  24. package/template_project/.claude/ukit/index/tier-lane.mjs +1 -1
  25. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +151 -16
  26. package/template_project/.omp/RULES.md +1 -1
  27. package/template_project/AGENTS.md +2 -0
  28. package/template_project/CLAUDE.md +2 -0
  29. package/template_project/instructions/core.md +2 -0
  30. package/template_project/instructions/overlays/omp-rules.md +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,32 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.5.17 - 2026-11-21
6
+
7
+ - **Full test suites run in memory-safe batches.** A new always-on rule (TEST-01) tells the agent to run the whole suite, or any run beyond a few targeted files, with `node .claude/ukit/index/test-batches.mjs run`: sequential fresh-process batches, every file runs, and only a `PASS` verdict counts as green. Targeted 1-3 file runs still use the bare runner. Applies to Claude Code, Codex and omp.
8
+ - **Batch runs count as verification evidence.** `test-batches.mjs run` (default mode included) is recognised as a test run by the Stop gate; `plan`, `audit` and `detect-leaks` are not.
9
+ - **The release verifier runs its core suite in four bounded batches.** The single core phase had outgrown its fixed 600 s budget. It is now split into "Core test suite (batch 1/4)" through "(batch 4/4)". The file list comes from `vitest list` at run time and is dealt deterministically, with heavy files spread across batches. A batch fails if the batches together do not cover every file. No timeout was relaxed, and 3.5.16, which was never published, ships inside this release.
10
+ - **Delegation guidance mentions the batch runner.** The orchestrator brief and the delegation-gate message now point to `test-batches.mjs run` for full-suite verification.
11
+
12
+ ## 3.5.16 - 2026-11-21
13
+
14
+ Field-telemetry fix round 4.
15
+
16
+ - **Projects without a test command can finish (#7, #13).** The Stop gate only accepted a test-runner verdict, so a project with no declared tests (9Router: no package.json; checks were `node --check`) could never satisfy "verification-evidence" and got "check-only does not satisfy this lane" in a loop. When the project declares no test surface — no non-default `test`/`test:*` script, no pytest/go/cargo/gradle/maven/phpunit/mix/Gemfile marker, no `test:` Makefile target, no `tests/`, `test/`, `__tests__/` or `spec/` directory — a current passing check-only verdict now counts. Any declared test surface keeps the strict requirement.
17
+ - **Telemetry logs stop growing without bound (#8).** `decisions.tsv` (13 MB in one project) and `cache/route-audit.segments.jsonl` (12.5 MB) now rotate at 4 MiB to a single `.1` generation, and the diagnostics read both. Per-session `cache/route-state/*.json` files (1,513 in one project) are swept by the existing bounded ledger sweep: older than 30 days, or past 400 files when idle for more than 24 h. A live session's state is never evicted.
18
+ - **Skill descriptions say when to use them (#15).** Ten skills (backend-api, delivery, docs-manager, duraone, file-organizer, frontend, frontend-vue, pdf-processing, postgres, webapp-testing) had descriptions that named a topic but not a trigger; each now carries a "Use when…" clause.
19
+
20
+ ## 3.5.15 - 2026-11-21
21
+
22
+ Field-telemetry fix round 3.
23
+
24
+ - **Semantic contract mismatch no longer blocks Stop (#6).** The gate re-derived a task's contract from its first prompt and blocked when it differed from the stored one (≈390 field blocks: BAGuide 281, UKit 101, AI-Gateway 9). The router legitimately grows the stored contract during a task (carried evidence, publication and verification flags, mode churn), so a mismatch is not proof of a contradiction. Stop now evaluates the stored contract (no accumulated obligation is dropped), records the diagnostic, and shows a one-line note once per task.
25
+ - **task-watchdog accepts large payloads (#9).** It staged stdin with a 64 KiB cap while every other hook uses 2 MiB, so long Stop messages and big tool outputs were reported as "truncated or stalled during stdin staging". The cap now matches; real truncation still fails open.
26
+ - **Route state is recovered at Stop (#14).** When the session sidecar is missing and the shared route file is unstamped or stamped by another session but carries this session's task id, the gate adopts it instead of reporting "route state … was lost".
27
+ - **Playbook notes stop crying wolf (#17).** The trace was rebuilt from a 24-receipt window, so in long runs the early Read/Edit/test receipts fell out and `analog-search`/`verify` flipped back to "missing" (228 + 56 field notes). Completed steps now persist across the window, and the note is shown once per task.
28
+ - **Release fingerprint ignores hook-written memory notes.** `docs/memory/topics/*.md` are regenerated by edit hooks and are not package content; they changed the candidate fingerprint mid-gate and made the publish guard refuse. They are now excluded like other runtime outputs.
29
+ - Root `.omp/config.yml` comment synced with the template (worktree preflight parity).
30
+
5
31
  ## 3.5.14 - 2026-11-20
6
32
 
7
33
  Field-telemetry fix round 1. Source: Claude Code transcripts and `.ukit/storage/` of every consumer project (BAGuide, CKit, 4vn, XoonCube, UnicDB, …). New offline tools measure each class before and after a fix: `scripts/audit/field-telemetry.mjs` clusters hook messages and latency, and `scripts/audit/field-replay.mjs` re-runs historical hook inputs through the current hooks.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.14",
3
+ "version": "3.5.17",
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",
@@ -114,6 +114,7 @@
114
114
  "test:python:setup": "node tests/python/setup-test-venv.mjs",
115
115
  "test:artifact": "vitest run tests/integration/packageArtifact.test.js tests/integration/artifactReferenceIntegrity.test.js",
116
116
  "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
117
+ "test:release-core-batch": "node ./scripts/release/run-core-batch.mjs",
117
118
  "release:verify": "node ./scripts/release/verify-release.mjs",
118
119
  "prepublishOnly": "node ./scripts/release/publish-guard.mjs",
119
120
  "test": "vitest run",
@@ -4,8 +4,9 @@ import { createHash } from 'node:crypto';
4
4
  import path from 'node:path';
5
5
 
6
6
  // Runtime receipts are outputs of verification, not release candidate inputs.
7
+ // docs/memory/topics/ = hook-derived notes (memory-topics.mjs), not in package.json "files"; hooks rewrite them mid-gate.
7
8
  // Canonical template_project runtime sources are deliberately NOT excluded.
8
- const mutable = /^(?:\.ukit\/storage\/|\.claude\/ukit\/runtime\/\.ukit\/storage\/|\.cache\/|node_modules\/)/;
9
+ const mutable = /^(?:\.ukit\/storage\/|\.claude\/ukit\/runtime\/\.ukit\/storage\/|\.cache\/|docs\/memory\/topics\/|node_modules\/)/;
9
10
 
10
11
  export function candidateFingerprint(root) {
11
12
  // `git ls-files --others` lists an untracked nested repository (a running test's temp project
@@ -0,0 +1,12 @@
1
+ // Measured slowest suites. Shared by vitest.config.js (run order) and run-core-batch.mjs (spread
2
+ // across release batches so no single batch inherits all the heavy files).
3
+ export const HEAVY_FIRST = [
4
+ 'tests/integration/installPipeline.test.js',
5
+ 'tests/hooks/guidanceSupplementBinding.test.js',
6
+ 'tests/hooks/historicalSemanticMetamorphic.test.js',
7
+ 'tests/hooks/nativePublicationRouting.test.js',
8
+ 'tests/hooks/handoffProvenance.test.js',
9
+ 'tests/hooks/skillRouterHook.test.js',
10
+ 'tests/hooks/releaseCompletionEvidence.test.js',
11
+ 'tests/hooks/completionClosure.test.js',
12
+ ];
@@ -7,6 +7,8 @@ import os from 'node:os';
7
7
  // Ships with verify-release.mjs so installed --post-publish checks can load.
8
8
  export const npmCacheDir = path.join(os.tmpdir(), 'ukit-npm-cache');
9
9
 
10
+ export const CORE_BATCHES = 4;
11
+
10
12
  export const releaseSteps = [
11
13
  {
12
14
  label: 'Rendered instructions up to date (fix: yarn docs:render)',
@@ -45,12 +47,13 @@ export const releaseSteps = [
45
47
  args: ['test:handoff'],
46
48
  env: process.env,
47
49
  },
48
- {
49
- label: 'Core test suite',
50
+ ...Array.from({ length: CORE_BATCHES }, (_, i) => ({
51
+ // Same file set as `yarn test:release-core`, split so no single step nears the per-step deadline.
52
+ label: `Core test suite (batch ${i + 1}/${CORE_BATCHES})`,
50
53
  command: 'yarn',
51
- args: ['test:release-core', '--bail', '5'], // stop after 5 failures instead of finishing a doomed 4 min run
54
+ args: ['test:release-core-batch', String(i + 1), String(CORE_BATCHES)],
52
55
  env: process.env,
53
- },
56
+ })),
54
57
  {
55
58
  label: 'Local package dry-run',
56
59
  command: 'npm',
@@ -0,0 +1,50 @@
1
+ import { spawn, execFileSync } from 'node:child_process';
2
+ import { statSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ import { HEAVY_FIRST } from './heavy-first.mjs';
5
+
6
+ // Runs batch <index> of <count> of the release core suite (everything `yarn test:release-core`
7
+ // would run). The file list is computed at run time from vitest itself, so new tests are never
8
+ // skipped; partitioning is deterministic and every invocation proves the batches cover the list.
9
+ export const CORE_EXCLUDE = 'tests/integration/packageArtifact.test.js'; // run by the Artifact smoke step
10
+
11
+ export function listCoreFiles(cwd = process.cwd()) {
12
+ const env = { ...process.env };
13
+ delete env.UKIT_VERIFY_PROGRESS_FILE; // listing must not emit phase progress
14
+ const out = execFileSync('yarn', ['--silent', 'vitest', 'list', '--filesOnly', '--exclude', CORE_EXCLUDE], {
15
+ cwd, env, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, timeout: 120_000, stdio: ['ignore', 'pipe', 'ignore'],
16
+ });
17
+ return out.split('\n').map((l) => l.trim().replace(/\\/g, '/')).filter((l) => /\.test\.[cm]?js$/.test(l));
18
+ }
19
+
20
+ export function partition(files, count, cwd = process.cwd()) {
21
+ const size = (f) => { try { return statSync(path.join(cwd, f)).size; } catch { return 0; } };
22
+ const heavy = (f) => { const i = HEAVY_FIRST.indexOf(f); return i === -1 ? HEAVY_FIRST.length : i; };
23
+ const ordered = [...new Set(files)].sort((a, b) => heavy(a) - heavy(b) || size(b) - size(a) || (a < b ? -1 : 1));
24
+ const batches = Array.from({ length: count }, () => []);
25
+ ordered.forEach((f, i) => batches[i % count].push(f)); // round-robin spreads heavy files
26
+ const union = batches.flat();
27
+ if (union.length !== new Set(files).size || !files.every((f) => union.includes(f))) {
28
+ throw new Error('core batch partition does not cover the full test file list');
29
+ }
30
+ return batches;
31
+ }
32
+
33
+ if (import.meta.url === `file://${process.argv[1]}`) {
34
+ const index = Number(process.argv[2]);
35
+ const count = Number(process.argv[3]);
36
+ if (!Number.isInteger(index) || !Number.isInteger(count) || count < 1 || index < 1 || index > count) {
37
+ console.error('usage: run-core-batch.mjs <batch 1..N> <N>');
38
+ process.exit(2);
39
+ }
40
+ const files = listCoreFiles();
41
+ if (files.length === 0) { console.error('[core-batch] no test files listed'); process.exit(1); }
42
+ const batch = partition(files, count)[index - 1];
43
+ console.log(`[core-batch] ${index}/${count}: ${batch.length} of ${files.length} files`);
44
+ const child = spawn('yarn', ['vitest', 'run', ...batch, '--bail', '5'], { stdio: 'inherit' });
45
+ // Backstop watchdog (same budget as the verifier's per-step deadline; the verifier kills the whole tree first).
46
+ const watchdog = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, Number(process.env.UKIT_VERIFY_STEP_TIMEOUT_MS) || 10 * 60 * 1000);
47
+ watchdog.unref();
48
+ child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
49
+ child.on('error', () => process.exit(1));
50
+ }
@@ -123,7 +123,11 @@ export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } =
123
123
  const cacheDir = path.join(projectRoot, '.ukit', 'storage', 'cache');
124
124
  // BL-004: rows evicted past the 40-entry ring cap spill to the segments
125
125
  // sidecar — they must still reach the join or coverage silently decays.
126
- const segmentEntries = await readJsonLines(path.join(cacheDir, SEGMENTS_REL));
126
+ // Field #8: the sidecar rotates to `.1` past its size cap — older generation first.
127
+ const segmentEntries = [
128
+ ...await readJsonLines(path.join(cacheDir, `${SEGMENTS_REL}.1`)),
129
+ ...await readJsonLines(path.join(cacheDir, SEGMENTS_REL)),
130
+ ];
127
131
  const auditDoc = await readJson(path.join(cacheDir, 'route-audit.json'));
128
132
  const auditEntries = Array.isArray(auditDoc?.entries) ? auditDoc.entries : [];
129
133
 
@@ -161,8 +161,11 @@ export async function collectSkillAccuracy(projectRoot, { limitLedgers = 500 } =
161
161
  : [];
162
162
  // BL-004: rows evicted past the ring cap live in the segments sidecar —
163
163
  // they still carry skillIds and must reach the join.
164
- const segmentEntries = (await readJsonLines(path.join(projectRoot, SEGMENTS_REL)))
165
- .filter(isObject);
164
+ // Field #8: the sidecar rotates to `.1` past its size cap — older generation first.
165
+ const segmentEntries = [
166
+ ...await readJsonLines(path.join(projectRoot, `${SEGMENTS_REL}.1`)),
167
+ ...await readJsonLines(path.join(projectRoot, SEGMENTS_REL)),
168
+ ].filter(isObject);
166
169
  result.auditRowsScanned = auditEntries.length + segmentEntries.length;
167
170
  // Dedupe on requestKey (newest wins, per collectRouteOutcomes): last write
168
171
  // wins, so scan oldest→newest — segments append oldest→newest (forward),
@@ -270,7 +270,7 @@ function mainMessage(attempt, limit, taskId, mutation, projectRoot) {
270
270
  if (attempt >= limit) {
271
271
  return `UKit delegation gate — BLOCKED: this task's feature-implementation Playbook requires the coding to be delegated to the Tier 2 worker, but the orchestrator tried ${attempt} times to write ${describeTarget(mutation, projectRoot)} itself. This run is now recorded as BLOCKED (delegation-required-not-performed). Do not retry the write; report the blocker to the user.`;
272
272
  }
273
- return `UKit delegation gate (attempt ${attempt} of ${limit}): this task's feature-implementation Playbook requires Tier 2 coding delegation, and you are the Tier 3 orchestrator — writing ${describeTarget(mutation, projectRoot)} yourself is refused. Dispatch a native worker now with the Agent tool (subagent_type "feature-implementer", the Tier 2 coding model) and start its prompt with "[ukit-task ${taskId}]", naming the files and behaviour to implement; the worker must edit with Edit/Write. When it returns, verify the integrated result yourself with the bare test runner (for example \`npm test\`) — no pipe, tail, grep or compound command — so the runner's own exit status is the evidence. Repeating this write will end the run as BLOCKED.`;
273
+ return `UKit delegation gate (attempt ${attempt} of ${limit}): this task's feature-implementation Playbook requires Tier 2 coding delegation, and you are the Tier 3 orchestrator — writing ${describeTarget(mutation, projectRoot)} yourself is refused. Dispatch a native worker now with the Agent tool (subagent_type "feature-implementer", the Tier 2 coding model) and start its prompt with "[ukit-task ${taskId}]", naming the files and behaviour to implement; the worker must edit with Edit/Write. When it returns, verify the integrated result yourself with the bare test runner (for example \`npm test\`) — no pipe, tail, grep or compound command — so the runner's own exit status is the evidence; a full-suite run uses \`node .claude/ukit/index/test-batches.mjs run\` (its exit status is the evidence). Repeating this write will end the run as BLOCKED.`;
274
274
  }
275
275
 
276
276
  function workerMessage(mutation, projectRoot) {
@@ -4478,9 +4478,19 @@ function applyTaskSemantics(contract, semantic) {
4478
4478
  return { entries: merged.slice(0, 40), evicted: merged.slice(40) };
4479
4479
  }
4480
4480
 
4481
+ // Field #8: size-capped rotation (one `.1` generation), parity with
4482
+ // rotateAppendLogSync in runtime/execution-ledger.mjs.
4483
+ const SEGMENTS_MAX_BYTES = 4 * 1024 * 1024;
4484
+ async function rotateSegments() {
4485
+ try {
4486
+ if ((await fsp.stat(segmentsPath)).size >= SEGMENTS_MAX_BYTES) await fsp.rename(segmentsPath, `${segmentsPath}.1`);
4487
+ } catch {}
4488
+ }
4489
+
4481
4490
  async function spillEvictedEntries(evicted) {
4482
4491
  if (!evicted?.length) return;
4483
4492
  try {
4493
+ await rotateSegments();
4484
4494
  await fsp.appendFile(
4485
4495
  segmentsPath,
4486
4496
  evicted.map((item) => JSON.stringify(item)).join('\n') + '\n',
@@ -4504,6 +4514,9 @@ function applyTaskSemantics(contract, semantic) {
4504
4514
  function spillEvictedEntriesSync(evicted) {
4505
4515
  if (!evicted?.length) return;
4506
4516
  try {
4517
+ try {
4518
+ if (fsSync.statSync(segmentsPath).size >= SEGMENTS_MAX_BYTES) fsSync.renameSync(segmentsPath, `${segmentsPath}.1`);
4519
+ } catch {}
4507
4520
  fsSync.appendFileSync(
4508
4521
  segmentsPath,
4509
4522
  evicted.map((item) => JSON.stringify(item)).join('\n') + '\n',
@@ -35,12 +35,12 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
35
35
  # runtime (pre-install tree) simply leaves telemetry off.
36
36
  source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
37
37
  trap ukit_cleanup_hook_input EXIT
38
- # Bounded stdin (H01): the 64 KiB cap is preserved, but the payload now travels
38
+ # Bounded stdin (H01): the cap is 2 MiB like the other Stop hooks, but the payload now travels
39
39
  # as a staged file path — never through the exec environment, so an oversized
40
40
  # input can no longer stop node from starting (E2BIG) or stall the wrapper in
41
41
  # `cat`. A truncated payload simply fails JSON.parse inside node → {} → silent
42
42
  # degrade exit 0 (documented posture).
43
- ukit_stage_hook_input 65536 truncate
43
+ ukit_stage_hook_input 2097152 truncate
44
44
  __ukit_main_stage_rc=$?
45
45
  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
46
46
  # Infra failure during staging (mktemp/truncate): payload was never
@@ -48,7 +48,7 @@ source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
48
48
  ukit_emit_input_degraded advisory "task-watchdog"
49
49
  fi
50
50
  # BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
51
- # Exception: a payload cut ONLY by the 64 KiB size cap (not a stall) for PostToolUse. That path reads
51
+ # Exception: a payload cut ONLY by the 2 MiB size cap (not a stall) for PostToolUse. That path reads
52
52
  # nothing but hook_event_name from the payload (tasks/state/config all come from disk), so a size-truncated
53
53
  # payload is not incomplete for this hook. The event name is recovered only when provably complete
54
54
  # (ukit_salvage_tool_field); anything else - stall, unrecoverable name, non-PostToolUse (Stop forwards the
@@ -62,16 +62,16 @@ if ukit_input_degraded; then
62
62
  [ -n "$UKIT_WD_SALVAGED_EVENT" ] || ukit_emit_input_degraded advisory "task-watchdog"
63
63
  fi
64
64
  else
65
- # 64 KiB cap and the advisory degrade path alive.
65
+ # 2 MiB cap and the advisory degrade path alive.
66
66
  # Runtime helper missing (pre-install tree): the SAME bounded staging,
67
67
  # inline - `cat >/dev/null` used to block forever on a producer that never
68
68
  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
69
69
  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
70
70
  if [ -e /dev/fd/0 ]; then
71
71
  exec 8<&0
72
- head -c 65537 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
72
+ head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
73
73
  else
74
- head -c 65537 > "$UKIT_INPUT_FILE" 2>/dev/null &
74
+ head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
75
75
  fi
76
76
  __ukit_reader=$!
77
77
  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
@@ -88,7 +88,7 @@ else
88
88
  wait "$__ukit_waiter" 2>/dev/null
89
89
  exec 8<&-
90
90
  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
91
- if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 65536 ]; then
91
+ if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
92
92
  # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
93
93
  # must be announced, never silently acted on — same shape as the helper
94
94
  # path's ukit_emit_input_degraded.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: backend-api
3
- description: Backend API standards for endpoints, contracts, auth, and service logic.
3
+ description: Backend API standards for endpoints, contracts, auth, and service logic. Use when adding or changing an HTTP/RPC endpoint, request/response contract, auth check, or service-layer logic.
4
4
  enabledByDefault: false
5
5
  ---
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: delivery
3
- description: Project delivery workflow and quality gates for UKit templates.
3
+ description: Project delivery workflow and quality gates for UKit templates. Use when preparing a change to ship — version bump, changelog, release checklist, or final quality gate before handoff.
4
4
  ---
5
5
 
6
6
  # Delivery Skill
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: docs-manager
3
- description: Standardized documentation workflow for template-based projects.
3
+ description: Standardized documentation workflow for template-based projects. Use when creating, restructuring, or syncing project docs (README, docs/*.md, CHANGELOG) with the code.
4
4
  ---
5
5
 
6
6
  # Documentation Manager Skill
@@ -8,7 +8,8 @@ description: >
8
8
  load dropdown data, xử lý datetime, validate form, thiết kế luồng tính năng, hay bất kỳ task code
9
9
  nào liên quan đến FE_DuraOne, BE_DuraOne, hoặc dự án cùng stack (Nuxt 3 + Sanic + PostgreSQL).
10
10
  Skill này là nguồn sự thật duy nhất — không đoán mò, không dùng raw input, không dùng new Date().
11
- Đọc reference phù hợp TRƯỚC KHI code bất kỳ thứ gì.
11
+ Đọc reference phù hợp TRƯỚC KHI code bất kỳ thứ gì. Use when working on any DuraOne-stack
12
+ project (FE_DuraOne, BE_DuraOne, Nuxt 3 + Sanic + PostgreSQL).
12
13
  ---
13
14
 
14
15
  # DuraOne Skill — Phong Cách Code Cá Nhân
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: file-organizer
3
- description: Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort.
3
+ description: Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Use when asked to tidy, deduplicate, or restructure files or folders.
4
4
  ---
5
5
 
6
6
  # File Organizer
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: frontend
3
- description: Generic frontend implementation standards for UI and UX work.
3
+ description: Generic frontend implementation standards for UI and UX work. Use when building or changing UI components, pages, styling, forms, or client-side state in a non-Vue stack.
4
4
  enabledByDefault: false
5
5
  ---
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: frontend-vue
3
- description: Vue 2 / Nuxt frontend skill pack for UKit projects. Options API, Bootstrap 5 + Ant Design Vue, predefined components (Control*, Grid*, Popup*), composables (request, session, translation, utils). Always reuse existing components before creating new ones.
3
+ description: Vue 2 / Nuxt frontend skill pack for UKit projects. Options API, Bootstrap 5 + Ant Design Vue, predefined components (Control*, Grid*, Popup*), composables (request, session, translation, utils). Use when creating or editing a Vue/Nuxt page, component, form, or grid; always reuse existing components before creating new ones.
4
4
  triggers:
5
5
  - vue
6
6
  - nuxt
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: pdf-processing
3
- description: Production-ready PDF processing toolkit with forms, tables, OCR, validation, and batch operations. Supports extracting text/tables, creating/modifying PDFs, and handling complex forms.
3
+ description: Production-ready PDF processing toolkit with forms, tables, OCR, validation, and batch operations. Use when extracting text/tables from a PDF, filling or reading PDF forms, OCR-ing scans, or creating/modifying PDFs.
4
4
  enabledByDefault: false
5
5
  ---
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: postgres
3
- description: PostgreSQL conventions and patterns for UKit SQL work.
3
+ description: PostgreSQL conventions and patterns for UKit SQL work. Use when writing or reviewing PostgreSQL queries, views, functions, procedures, migrations, or indexes.
4
4
  enabledByDefault: false
5
5
  ---
6
6
 
@@ -9,6 +9,8 @@ description: Quality-driven testing methodology combining Test-Driven Developmen
9
9
 
10
10
  High-quality code starts with high-quality tests. This skill enforces Test-Driven Development (TDD) and prevents common testing mistakes.
11
11
 
12
+ **Full suite rule:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run`; only a `PASS` verdict counts. Targeted 1-3 file runs use the bare runner.
13
+
12
14
  **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
13
15
 
14
16
  **The Iron Law:**
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: webapp-testing
3
- description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
3
+ description: Toolkit for interacting with and testing local web applications using Playwright. Use when verifying frontend behaviour in a real browser, debugging UI, capturing screenshots, or reading browser console logs.
4
4
  license: Complete terms in LICENSE.txt
5
5
  ---
6
6
 
@@ -23,7 +23,7 @@ import { buildTierLane, classifyModelTier, resolveMainTier } from './tier-lane.m
23
23
  export { buildTierLane, classifyModelTier, resolveMainTier };
24
24
  import { detectUnicGateway } from './unic-gateway.mjs';
25
25
  import { withAsyncLock } from '../runtime/async-lock.mjs';
26
- import { appendDecisionReceipt, recordLedgerEvent } from '../runtime/execution-ledger.mjs';
26
+ import { appendDecisionReceipt, recordLedgerEvent, rotateAppendLogSync } from '../runtime/execution-ledger.mjs';
27
27
  import {
28
28
  RESUMABLE_RUN_SCHEMA_VERSION,
29
29
  readResumableRun,
@@ -6731,6 +6731,7 @@ function routeAuditSegmentsPath(filePath) {
6731
6731
  async function spillRouteAuditEntries(filePath, evicted) {
6732
6732
  if (!evicted?.length) return;
6733
6733
  try {
6734
+ rotateAppendLogSync(routeAuditSegmentsPath(filePath));
6734
6735
  await fs.appendFile(
6735
6736
  routeAuditSegmentsPath(filePath),
6736
6737
  evicted.map((item) => JSON.stringify(item)).join('\n') + '\n',
@@ -6744,6 +6745,7 @@ async function spillRouteAuditEntries(filePath, evicted) {
6744
6745
  function spillRouteAuditEntriesSync(filePath, evicted) {
6745
6746
  if (!evicted?.length) return;
6746
6747
  try {
6748
+ rotateAppendLogSync(routeAuditSegmentsPath(filePath));
6747
6749
  fsSync.appendFileSync(
6748
6750
  routeAuditSegmentsPath(filePath),
6749
6751
  evicted.map((item) => JSON.stringify(item)).join('\n') + '\n',
@@ -52,7 +52,7 @@ export function buildTierLane({ modelTier = null, escalatedTier = null, mainTier
52
52
  };
53
53
  }
54
54
  const policy = delegationPolicy ?? 'allow-qualified-sidecar';
55
- const brief = 'Give the worker scope, dependencies, acceptance criteria and the verification to run; verify its diff yourself after it returns, then run the project\'s bare test runner yourself (e.g. `npm test`, no pipe/tail/grep/compound command) and read its exit status — that status is the verification evidence.';
55
+ const brief = 'Give the worker scope, dependencies, acceptance criteria and the verification to run; verify its diff yourself after it returns, then run the project\'s bare test runner yourself (e.g. `npm test`, no pipe/tail/grep/compound command) and read its exit status — that status is the verification evidence. A full-suite run uses `node .claude/ukit/index/test-batches.mjs run` (its exit status is the evidence).';
56
56
  // A high-risk target on a Tier 2 coding lane is still Tier 2 work: the inline-by-policy exemption
57
57
  // (hand-off costs more than the work) does not apply, otherwise the Tier 3 orchestrator would be the
58
58
  // one editing the dangerous file. Risk raises verification rigor, not the executor.
@@ -330,6 +330,22 @@ export async function readRouteState(projectRoot, payload = {}) {
330
330
  return readSessionRouteState(projectRoot, sessionId);
331
331
  }
332
332
 
333
+ // Field #14 recovery: the session sidecar is missing, but the shared single-slot route file may still
334
+ // hold THIS session's task (unstamped by an older router, or re-stamped by a concurrent session that
335
+ // routed afterwards). The session ledger records the taskInstanceId it was opened under; a shared
336
+ // route carrying that exact id is the same task, so adopt it (in memory only) rather than declaring
337
+ // the route lost. Task ids are unique per route, so a different task is never adopted.
338
+ export async function recoverRouteStateFromLedger(projectRoot, payload = {}, ledger = {}) {
339
+ try {
340
+ const taskId = ledger?.taskInstanceId;
341
+ const sessionId = explicitSessionId(payload);
342
+ if (!taskId || !sessionId) return null;
343
+ const shared = await readJson(path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json'), null);
344
+ if (!shared || shared.routePublicationIncomplete || shared.taskInstanceId !== taskId) return null;
345
+ return { ...shared, sessionId };
346
+ } catch { return null; }
347
+ }
348
+
333
349
  export function ownerStopActive(state, payload = {}) {
334
350
  const control = state?.ownerControl;
335
351
  if (!control || control.kind !== 'stop') return false;
@@ -909,6 +925,10 @@ function simpleCommandVerifierKind(tokens) {
909
925
  if (/^(?:-e|-p|--eval|--print)$/.test(arg)) return null; // inline code: later words are its argv
910
926
  if (/^(?:-r|--require|--import|--loader|--experimental-loader|-C|--conditions)$/.test(arg)) { i += 1; continue; }
911
927
  if (/^-/.test(arg)) continue;
928
+ if (/(?:^|\/)test-batches\.mjs$/.test(arg)) {
929
+ const mode = rest.slice(i + 1).find((a) => !/^-/.test(a));
930
+ return !mode || mode === 'run' ? 'test' : null;
931
+ }
912
932
  return runnerWordKind(arg);
913
933
  }
914
934
  }
@@ -1493,6 +1513,38 @@ function promptNamesBookkeepingFile(state, file) {
1493
1513
  return promptNamesBookkeeping(state);
1494
1514
  }
1495
1515
 
1516
+ // Field #7/#13 (greenfield/brownfield onboarding): a project that declares NO test command
1517
+ // cannot ever produce a test-verified verdict, so demanding one blocks Stop forever (9Router:
1518
+ // no package.json, verified with `node --check`). Detection is cheap and conservative —
1519
+ // any recognizable test surface keeps the strict test-verified requirement.
1520
+ const NPM_DEFAULT_TEST = /no test specified/i;
1521
+ const testSurfaceMemo = new Map();
1522
+ export function projectDeclaresTestCommand(cwd) {
1523
+ const root = path.resolve(cwd || process.cwd());
1524
+ if (testSurfaceMemo.has(root)) return testSurfaceMemo.get(root);
1525
+ const exists = (rel) => { try { return fsSync.existsSync(path.join(root, rel)); } catch { return false; } };
1526
+ const read = (rel) => { try { return fsSync.readFileSync(path.join(root, rel), 'utf8'); } catch { return ''; } };
1527
+ let found = false;
1528
+ const pkgRaw = read('package.json');
1529
+ if (pkgRaw) {
1530
+ try {
1531
+ const scripts = JSON.parse(pkgRaw)?.scripts || {};
1532
+ found = Object.entries(scripts).some(([name, body]) => /^test(?::|$)/.test(name) && !NPM_DEFAULT_TEST.test(String(body)));
1533
+ } catch { found = true; } // unreadable manifest: stay strict
1534
+ }
1535
+ if (!found) {
1536
+ found = ['pytest.ini', 'tox.ini', 'conftest.py', 'go.mod', 'Cargo.toml', 'phpunit.xml', 'phpunit.xml.dist', 'build.gradle', 'build.gradle.kts', 'pom.xml', 'mix.exs', 'Gemfile']
1537
+ .some(exists)
1538
+ || /\[tool\.pytest|\[tool:pytest/.test(read('pyproject.toml') + read('setup.cfg'))
1539
+ || /^test\s*:/m.test(read('Makefile'))
1540
+ || ['tests', 'test', '__tests__', 'spec'].some((dir) => {
1541
+ try { return fsSync.statSync(path.join(root, dir)).isDirectory(); } catch { return false; }
1542
+ });
1543
+ }
1544
+ testSurfaceMemo.set(root, found);
1545
+ return found;
1546
+ }
1547
+
1496
1548
  function contentFingerprint(cwd) { return memoGit(`content\0${cwd}`, () => contentFingerprintRaw(cwd)); }
1497
1549
  function contentFingerprintRaw(cwd) {
1498
1550
  if (!cwd) return null;
@@ -2671,7 +2723,7 @@ function isPlaybookRead(file, playbookId) {
2671
2723
  * playbookId yields the not-applicable trace (no requirements) — the greeting /
2672
2724
  * informational shape.
2673
2725
  */
2674
- export function buildPlaybookTrace(ledger = {}, playbookId = null) {
2726
+ export function buildPlaybookTrace(ledger = {}, playbookId = null, priorTrace = null) {
2675
2727
  const id = playbookId || null;
2676
2728
  if (!id) {
2677
2729
  return {
@@ -2746,9 +2798,29 @@ export function buildPlaybookTrace(ledger = {}, playbookId = null) {
2746
2798
  stepsSkipped.push({ id: step.id, justification: PROPORTIONATE_JUSTIFICATION });
2747
2799
  }
2748
2800
  }
2801
+ // Monotone: the receipt window is capped (MAX_RECEIPTS), so a step proven earlier in the task may have
2802
+ // had its receipt evicted. A prior trace of the SAME playbook keeps its done steps/outputs (field #17:
2803
+ // false "missing: analog-search, verify" after long runs).
2804
+ let priorVerified = false;
2805
+ if (priorTrace && priorTrace.playbookId === id) {
2806
+ const have = new Set(stepsDone.map((step) => step.id));
2807
+ for (const done of Array.isArray(priorTrace.stepsDone) ? priorTrace.stepsDone : []) {
2808
+ if (done?.id && steps.some((step) => step.id === done.id) && !have.has(done.id)) {
2809
+ stepsDone.push(done);
2810
+ const at = stepsSkipped.findIndex((skip) => skip.id === done.id);
2811
+ if (at !== -1) stepsSkipped.splice(at, 1);
2812
+ }
2813
+ }
2814
+ stepsDone.sort((x, y) => steps.findIndex((st) => st.id === x.id) - steps.findIndex((st) => st.id === y.id));
2815
+ for (const out of Array.isArray(priorTrace.outputs) ? priorTrace.outputs : []) {
2816
+ if (typeof out === 'string' && !outputs.includes(out) && outputs.length < MAX_PLAYBOOK_OUTPUTS) outputs.push(out);
2817
+ }
2818
+ priorVerified = priorTrace.verification === 'passed';
2819
+ if (priorTrace.loaded === true) loaded = true;
2820
+ }
2749
2821
  const verification = steps.length === 0
2750
2822
  ? 'n/a'
2751
- : stepEvidence.has('post-verify') ? 'passed'
2823
+ : stepEvidence.has('post-verify') || priorVerified ? 'passed'
2752
2824
  : anyVerificationFailed ? 'failed'
2753
2825
  : 'pending';
2754
2826
  return {
@@ -3259,7 +3331,7 @@ function applyReceiptCore(ledger, receipt, { vibecode = false, projectRoot } = {
3259
3331
  // receipt (live and journaled replay alike) so the persisted record never
3260
3332
  // shows an evictable window. Only playbook-routed ledgers grow the field.
3261
3333
  if (next.playbookId) {
3262
- next.playbookTrace = buildPlaybookTrace(next, next.playbookId);
3334
+ next.playbookTrace = buildPlaybookTrace(next, next.playbookId, ledger?.playbookTrace);
3263
3335
  }
3264
3336
  next.updatedAt = Date.now();
3265
3337
  return { ledger: next, value: null };
@@ -3738,6 +3810,12 @@ export async function recordLedgerEvent(event, {
3738
3810
  // contended acquisition never pays sweep latency. Advisory — never throws.
3739
3811
  // BUG-C23-10: a persistent failure is still surfaced as a bounded degrade.
3740
3812
  try { await maybeSweepExecLedgerDir(path.dirname(target)); } catch (error) { noteSweepFailure(error); }
3813
+ // Field #8: per-session route-state sidecars (cache/route-state/<session>.json) were never
3814
+ // pruned (1,513 files in one consumer). Same bounded sampled sweep: 30-day age cap, count
3815
+ // cap only for files idle > 24 h, so a live session's route state is never evicted.
3816
+ try {
3817
+ await maybeSweepExecLedgerDir(path.join(path.dirname(path.dirname(target)), 'route-state'), { maxFiles: 400 });
3818
+ } catch (error) { noteSweepFailure(error); }
3741
3819
  return outcome.value;
3742
3820
  }
3743
3821
 
@@ -4340,8 +4418,11 @@ function evidenceSatisfied(evidence, ledger = {}, state = {}, { cwd } = {}) {
4340
4418
  // verdict record the boolean path below is unchanged (backward compatible).
4341
4419
  const verdicts = [ledger.verdict, ...(ledger.verdictHistory || [])].filter(Boolean);
4342
4420
  if (verdicts.length > 0) {
4421
+ // #7/#13: with no declared test command a current check-only verdict is the strongest
4422
+ // evidence the project can produce; a project with a test surface stays strict.
4423
+ const noTestSurface = () => !projectDeclaresTestCommand(verdicts.find((v) => v.workspaceRoot)?.workspaceRoot || cwd);
4343
4424
  return verdicts.some(
4344
- (verdict) => VERDICT_SATISFYING_KINDS.has(verdict.kind)
4425
+ (verdict) => (VERDICT_SATISFYING_KINDS.has(verdict.kind) || (verdict.kind === 'check-only' && noTestSurface()))
4345
4426
  && verdictCurrent(verdict, { cwd }).current === true,
4346
4427
  );
4347
4428
  }
@@ -5478,7 +5559,7 @@ function playbookStopAdvisory({ state = {}, ledger = {}, cwd } = {}, result = {}
5478
5559
  if (!playbookId || playbookId === BUGFIX_PLAYBOOK_ID) return null;
5479
5560
  const effectiveLedger = effectiveRequestLedger(state, ledger, cwd);
5480
5561
  if (effectiveLedger.writeAttempted !== true) return null;
5481
- const trace = buildPlaybookTrace(effectiveLedger, playbookId);
5562
+ const trace = buildPlaybookTrace(effectiveLedger, playbookId, effectiveLedger.playbookTrace);
5482
5563
  const stepNote = playbookTraceMissingSteps(trace).length === 0 ? null
5483
5564
  : `UKit playbook note: ${formatPlaybookTrace(trace)} (advisory).`;
5484
5565
  // Round 5: a delegated feature run adds its acceptance verdict — advisory text only.
@@ -5743,6 +5824,31 @@ export async function reconcileStaleContract(projectRoot, state) {
5743
5824
  } catch { return state; }
5744
5825
  }
5745
5826
 
5827
+ // One advisory line per task for a semantic-contract invariant violation (marker under the seal cache dir).
5828
+ async function takeInvariantAdvisory(projectRoot, payload, state, diagnostic) {
5829
+ const id = state?.taskInstanceId || 'unknown';
5830
+ const file = path.join(path.dirname(sealPath(projectRoot, payload)), `invariant-advisory-${sessionIdentity(payload)}.json`);
5831
+ const seen = await readJson(file, {}) || {};
5832
+ try { process.stderr.write(`[ukit-completion] semantic contract invariant diagnostic (self-healed, stored contract kept): ${JSON.stringify(diagnostic)}\n`); } catch { /* advisory */ }
5833
+ if (seen[id]) return null;
5834
+ seen[id] = Date.now();
5835
+ await fs.mkdir(path.dirname(file), { recursive: true });
5836
+ await writeJsonAtomic(file, Object.fromEntries(Object.entries(seen).sort((x, y) => y[1] - x[1]).slice(0, SEAL_MAX)));
5837
+ return 'UKit note: internal semantic-contract check disagreed; continuing with the task\'s stored contract (no obligations dropped).';
5838
+ }
5839
+
5840
+ // The playbook note is advisory telemetry: show it at most once per task (marker beside the seal cache).
5841
+ async function takePlaybookNoteOnce(projectRoot, payload, state) {
5842
+ const id = state?.taskInstanceId || state?.requestKey || 'unknown';
5843
+ const file = path.join(path.dirname(sealPath(projectRoot, payload)), `playbook-note-${sessionIdentity(payload)}.json`);
5844
+ const seen = await readJson(file, {}) || {};
5845
+ if (seen[id]) return false;
5846
+ seen[id] = Date.now();
5847
+ await fs.mkdir(path.dirname(file), { recursive: true });
5848
+ await writeJsonAtomic(file, Object.fromEntries(Object.entries(seen).sort((x, y) => y[1] - x[1]).slice(0, SEAL_MAX)));
5849
+ return true;
5850
+ }
5851
+
5746
5852
  async function runEvaluateStop() {
5747
5853
  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
5748
5854
  gitMemo = new Map();
@@ -5757,7 +5863,7 @@ async function runEvaluateStop() {
5757
5863
  // malformed payload starts blocking again.
5758
5864
  await resetGateCrashCounter(projectRoot);
5759
5865
 
5760
- const state = await readRouteState(projectRoot, payload);
5866
+ let state = await readRouteState(projectRoot, payload);
5761
5867
  const ledger = await readExecutionLedger(projectRoot, payload) || {};
5762
5868
  if (state?.routePublicationIncomplete) {
5763
5869
  process.stdout.write(`${JSON.stringify({ decision: 'block', reason: 'UKit route publication incomplete: shared state and session route do not match; completion is unproven.' })}\n`);
@@ -5770,6 +5876,9 @@ async function runEvaluateStop() {
5770
5876
  // ending silently there is indistinguishable from a mid-run stall. Surface the loss so the
5771
5877
  // user sees WHY the run released. Sessions that were never routed (no ledger activity at
5772
5878
  // all) stay silent: there is nothing to report (silent-success carve-out).
5879
+ if (!state) {
5880
+ state = await recoverRouteStateFromLedger(projectRoot, payload, ledger);
5881
+ }
5773
5882
  if (!state) {
5774
5883
  const hasActivity = ledger.sourceSucceeded || ledger.writeAttempted
5775
5884
  || ledger.verificationAttempted || (ledger.receipts || []).length > 0;
@@ -5785,11 +5894,20 @@ async function runEvaluateStop() {
5785
5894
  // never heals a contract classified by an older classifier. Reconcile it from the task's own
5786
5895
  // prompt at the gate boundary (in memory; the stored route state is left untouched).
5787
5896
  const reconciled = await reconcileStaleContract(projectRoot, state);
5897
+ // Invariant violation = internal nondeterminism (the router legitimately mutates the stored contract over a task),
5898
+ // never a reason to trap the user: evaluate with the STORED contract (reconcile keeps it untouched, so accumulated
5899
+ // obligations such as release-publication stay enforced), keep the diagnostic, and advise once per task.
5900
+ let advisory = null;
5788
5901
  if (reconciled.semanticDiagnostic?.status === 'invariant-violation') {
5789
- process.stdout.write(`${JSON.stringify({ decision: 'block', reason: `UKit semantic contract invariant violation: unchanged authoritative task/prompt/engine produced contradictory contracts. No new operation or publication obligation has been accepted. ${JSON.stringify(reconciled.semanticDiagnostic)}` })}\n`);
5790
- return;
5902
+ try { advisory = await takeInvariantAdvisory(projectRoot, payload, state, reconciled.semanticDiagnostic); } catch { advisory = null; }
5791
5903
  }
5904
+ const emit = (obj) => process.stdout.write(`${JSON.stringify(advisory && !obj.systemMessage ? { ...obj, systemMessage: advisory } : obj)}\n`);
5792
5905
  let result = evaluateCompletion({ state: reconciled, ledger, cwd: projectRoot, phase });
5906
+ if (result.playbookAdvisory) {
5907
+ let first = true;
5908
+ try { first = await takePlaybookNoteOnce(projectRoot, payload, state); } catch { first = true; }
5909
+ if (!first) { const { playbookAdvisory, ...rest } = result; result = rest; }
5910
+ }
5793
5911
  if (result.continue && result.missingEvidence?.includes('release-publication')) {
5794
5912
  const progress = await noteStopProgress(projectRoot, payload);
5795
5913
  if (progress?.value?.reentrant === true) {
@@ -5884,7 +6002,7 @@ async function runEvaluateStop() {
5884
6002
  // blocker.
5885
6003
  if (result.gateRelease === 'handback-delivered') {
5886
6004
  // The one handback for this state was already shown: no message, but never a silent success either.
5887
- process.stdout.write(`${JSON.stringify({ outcome: 'blocked', complete: false, gateRelease: 'handback-delivered' })}\n`);
6005
+ emit({ outcome: 'blocked', complete: false, gateRelease: 'handback-delivered' });
5888
6006
  return;
5889
6007
  }
5890
6008
  if (!result.continue && (result.outcome === 'handback' || result.capped === true)) {
@@ -5907,7 +6025,7 @@ async function runEvaluateStop() {
5907
6025
  reason: result.reason,
5908
6026
  });
5909
6027
  } catch { /* advisory */ }
5910
- process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
6028
+ emit({ decision: 'block', reason: result.reason });
5911
6029
  return;
5912
6030
  }
5913
6031
  if (result.capped || result.notify) {
@@ -5917,24 +6035,24 @@ async function runEvaluateStop() {
5917
6035
  // single line (evaluator stdout is parsed first-line-wins by the stop coordinator).
5918
6036
  const message = result.playbookAdvisory ? `${result.reason} ${result.playbookAdvisory}` : result.reason;
5919
6037
  process.stderr.write(`[ukit-completion] ${result.reason}\n`);
5920
- process.stdout.write(`${JSON.stringify({ systemMessage: message,
6038
+ emit({ systemMessage: advisory ? `${message} ${advisory}` : message,
5921
6039
  ...(result.outcome === 'blocked' || result.outcome === 'handback' ? { outcome: 'blocked', complete: false } : {}),
5922
- })}\n`);
6040
+ });
5923
6041
  return;
5924
6042
  }
5925
6043
  if (result.complete) {
5926
6044
  // A satisfied route stays a silent success — unless the routed playbook has
5927
6045
  // steps missing, where the trace advisory IS the one-line release message.
5928
6046
  if (result.playbookAdvisory) {
5929
- process.stdout.write(`${JSON.stringify({ systemMessage: result.playbookAdvisory })}\n`);
5930
- }
6047
+ emit({ systemMessage: advisory ? `${result.playbookAdvisory} ${advisory}` : result.playbookAdvisory });
6048
+ } else if (advisory) emit({});
5931
6049
  return; // silent success: route present, all evidence satisfied
5932
6050
  }
5933
- if (result.gateRelease === 'no-routable-contract') return; // Advisory release, never VERIFIED.
6051
+ if (result.gateRelease === 'no-routable-contract') { if (advisory) emit({}); return; } // Advisory release, never VERIFIED.
5934
6052
  // Defensive final else: no evaluation result may ever end a routed stop silently.
5935
6053
  const fallback = `UKit completion gate: the stop was evaluated without a decision (missing evidence: ${(result.missingEvidence || []).join(', ') || 'none'}). If work is unfinished, re-send the task in a new message.`;
5936
6054
  process.stderr.write(`[ukit-completion] ${fallback}\n`);
5937
- process.stdout.write(`${JSON.stringify({ systemMessage: fallback })}\n`);
6055
+ emit({ systemMessage: fallback });
5938
6056
  }
5939
6057
 
5940
6058
  async function main() {
@@ -5987,6 +6105,22 @@ async function main() {
5987
6105
 
5988
6106
  const DECISION_LOG_HEADER = 'ts\tphase\tdecision\twhy\tevidence\tresult';
5989
6107
 
6108
+ // Field #8: append-only telemetry logs grew without bound (decisions.tsv 13 MB / 76k rows,
6109
+ // route-audit.segments.jsonl 12.5 MB in one consumer) on slow external volumes. Before an
6110
+ // append, a log past `maxBytes` is renamed to `<file>.1` (one generation, replacing the older
6111
+ // one), so disk use stays ≤ ~2× the cap. Rename is atomic; a lost race at worst drops one old
6112
+ // generation of diagnostics, never the row being written. Readers merge `.1` + current.
6113
+ export const APPEND_LOG_MAX_BYTES = 4 * 1024 * 1024;
6114
+ export function rotateAppendLogSync(target, maxBytes = APPEND_LOG_MAX_BYTES) {
6115
+ try {
6116
+ if (fsSync.statSync(target).size < maxBytes) return false;
6117
+ fsSync.renameSync(target, `${target}.1`);
6118
+ return true;
6119
+ } catch {
6120
+ return false;
6121
+ }
6122
+ }
6123
+
5990
6124
  function decisionLogPath(projectRoot) {
5991
6125
  return path.join(projectRoot, '.ukit', 'storage', 'decisions.tsv');
5992
6126
  }
@@ -6020,6 +6154,7 @@ export async function appendDecision(projectRoot, {
6020
6154
  ].map(sanitizeDecisionCell).join('\t');
6021
6155
  try {
6022
6156
  await fs.mkdir(path.dirname(target), { recursive: true });
6157
+ rotateAppendLogSync(target);
6023
6158
  let needsHeader = true;
6024
6159
  try {
6025
6160
  needsHeader = (await fs.stat(target)).size === 0;
@@ -28,7 +28,7 @@ edit/write evidence in the current turn, plus verification when the change is ri
28
28
 
29
29
  Check `.cache/index/` freshness first. Then run
30
30
  `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"` and open only the top 1-3 suspect
31
- files before widening further. These node scripts work unchanged under omp.
31
+ files before widening further. These node scripts work unchanged under omp. Full suite (or beyond a few targeted files): `node .claude/ukit/index/test-batches.mjs run`; only `PASS` is green.
32
32
 
33
33
  ## 5. Auto-activate skills
34
34
 
@@ -91,6 +91,8 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
91
91
  - **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
92
92
  <!-- RULES: BUDGET-02 BUDGET-03 -->
93
93
  - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
94
+ <!-- RULE: TEST-01 -->
95
+ - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never add parallel workers or launch a second copy. Targeted 1-3 file runs use the bare runner directly.
94
96
  - **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
95
97
 
96
98
  ## Living Status Workflow
@@ -91,6 +91,8 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
91
91
  - **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
92
92
  <!-- RULES: BUDGET-02 BUDGET-03 -->
93
93
  - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
94
+ <!-- RULE: TEST-01 -->
95
+ - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never add parallel workers or launch a second copy. Targeted 1-3 file runs use the bare runner directly.
94
96
  - **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
95
97
 
96
98
  ## Living Status Workflow
@@ -88,6 +88,8 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
88
88
  - **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
89
89
  <!-- RULES: BUDGET-02 BUDGET-03 -->
90
90
  - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
91
+ <!-- RULE: TEST-01 -->
92
+ - **Full/large test suites run in batches:** run the whole suite (or any run beyond a few targeted files) with `node .claude/ukit/index/test-batches.mjs run` — sequential fresh-process batches, every file runs, only a `PASS` verdict (exit 0) counts as green; never add parallel workers or launch a second copy. Targeted 1-3 file runs use the bare runner directly.
91
93
  - **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
92
94
 
93
95
  ## Living Status Workflow
@@ -25,7 +25,7 @@ edit/write evidence in the current turn, plus verification when the change is ri
25
25
 
26
26
  Check `.cache/index/` freshness first. Then run
27
27
  `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"` and open only the top 1-3 suspect
28
- files before widening further. These node scripts work unchanged under omp.
28
+ files before widening further. These node scripts work unchanged under omp. Full suite (or beyond a few targeted files): `node .claude/ukit/index/test-batches.mjs run`; only `PASS` is green.
29
29
 
30
30
  ## 5. Auto-activate skills
31
31