@ngockhoale/ukit 3.5.15 → 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 (28) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/package.json +2 -1
  3. package/scripts/release/heavy-first.mjs +12 -0
  4. package/scripts/release/release-steps.mjs +7 -4
  5. package/scripts/release/run-core-batch.mjs +50 -0
  6. package/src/diagnostics/routeOutcomes.js +5 -1
  7. package/src/diagnostics/skillAccuracy.js +5 -2
  8. package/template_project/.claude/hooks/delegation-gate.mjs +1 -1
  9. package/template_project/.claude/hooks/skill-router.sh +13 -0
  10. package/template_project/.claude/skills/backend-api/SKILL.md +1 -1
  11. package/template_project/.claude/skills/delivery/SKILL.md +1 -1
  12. package/template_project/.claude/skills/docs-manager/SKILL.md +1 -1
  13. package/template_project/.claude/skills/duraone/SKILL.md +2 -1
  14. package/template_project/.claude/skills/file-organizer/SKILL.md +1 -1
  15. package/template_project/.claude/skills/frontend/SKILL.md +1 -1
  16. package/template_project/.claude/skills/frontend-vue/SKILL.md +1 -1
  17. package/template_project/.claude/skills/pdf-processing/SKILL.md +1 -1
  18. package/template_project/.claude/skills/postgres/SKILL.md +1 -1
  19. package/template_project/.claude/skills/testing-quality/SKILL.md +2 -0
  20. package/template_project/.claude/skills/webapp-testing/SKILL.md +1 -1
  21. package/template_project/.claude/ukit/index/route-task.mjs +3 -1
  22. package/template_project/.claude/ukit/index/tier-lane.mjs +1 -1
  23. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +63 -1
  24. package/template_project/.omp/RULES.md +1 -1
  25. package/template_project/AGENTS.md +2 -0
  26. package/template_project/CLAUDE.md +2 -0
  27. package/template_project/instructions/core.md +2 -0
  28. package/template_project/instructions/overlays/omp-rules.md +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,21 @@
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
+
5
20
  ## 3.5.15 - 2026-11-21
6
21
 
7
22
  Field-telemetry fix round 3.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.15",
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",
@@ -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',
@@ -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.
@@ -925,6 +925,10 @@ function simpleCommandVerifierKind(tokens) {
925
925
  if (/^(?:-e|-p|--eval|--print)$/.test(arg)) return null; // inline code: later words are its argv
926
926
  if (/^(?:-r|--require|--import|--loader|--experimental-loader|-C|--conditions)$/.test(arg)) { i += 1; continue; }
927
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
+ }
928
932
  return runnerWordKind(arg);
929
933
  }
930
934
  }
@@ -1509,6 +1513,38 @@ function promptNamesBookkeepingFile(state, file) {
1509
1513
  return promptNamesBookkeeping(state);
1510
1514
  }
1511
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
+
1512
1548
  function contentFingerprint(cwd) { return memoGit(`content\0${cwd}`, () => contentFingerprintRaw(cwd)); }
1513
1549
  function contentFingerprintRaw(cwd) {
1514
1550
  if (!cwd) return null;
@@ -3774,6 +3810,12 @@ export async function recordLedgerEvent(event, {
3774
3810
  // contended acquisition never pays sweep latency. Advisory — never throws.
3775
3811
  // BUG-C23-10: a persistent failure is still surfaced as a bounded degrade.
3776
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); }
3777
3819
  return outcome.value;
3778
3820
  }
3779
3821
 
@@ -4376,8 +4418,11 @@ function evidenceSatisfied(evidence, ledger = {}, state = {}, { cwd } = {}) {
4376
4418
  // verdict record the boolean path below is unchanged (backward compatible).
4377
4419
  const verdicts = [ledger.verdict, ...(ledger.verdictHistory || [])].filter(Boolean);
4378
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);
4379
4424
  return verdicts.some(
4380
- (verdict) => VERDICT_SATISFYING_KINDS.has(verdict.kind)
4425
+ (verdict) => (VERDICT_SATISFYING_KINDS.has(verdict.kind) || (verdict.kind === 'check-only' && noTestSurface()))
4381
4426
  && verdictCurrent(verdict, { cwd }).current === true,
4382
4427
  );
4383
4428
  }
@@ -6060,6 +6105,22 @@ async function main() {
6060
6105
 
6061
6106
  const DECISION_LOG_HEADER = 'ts\tphase\tdecision\twhy\tevidence\tresult';
6062
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
+
6063
6124
  function decisionLogPath(projectRoot) {
6064
6125
  return path.join(projectRoot, '.ukit', 'storage', 'decisions.tsv');
6065
6126
  }
@@ -6093,6 +6154,7 @@ export async function appendDecision(projectRoot, {
6093
6154
  ].map(sanitizeDecisionCell).join('\t');
6094
6155
  try {
6095
6156
  await fs.mkdir(path.dirname(target), { recursive: true });
6157
+ rotateAppendLogSync(target);
6096
6158
  let needsHeader = true;
6097
6159
  try {
6098
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