@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.
- package/CHANGELOG.md +15 -0
- package/package.json +2 -1
- package/scripts/release/heavy-first.mjs +12 -0
- package/scripts/release/release-steps.mjs +7 -4
- package/scripts/release/run-core-batch.mjs +50 -0
- package/src/diagnostics/routeOutcomes.js +5 -1
- package/src/diagnostics/skillAccuracy.js +5 -2
- package/template_project/.claude/hooks/delegation-gate.mjs +1 -1
- package/template_project/.claude/hooks/skill-router.sh +13 -0
- package/template_project/.claude/skills/backend-api/SKILL.md +1 -1
- package/template_project/.claude/skills/delivery/SKILL.md +1 -1
- package/template_project/.claude/skills/docs-manager/SKILL.md +1 -1
- package/template_project/.claude/skills/duraone/SKILL.md +2 -1
- package/template_project/.claude/skills/file-organizer/SKILL.md +1 -1
- package/template_project/.claude/skills/frontend/SKILL.md +1 -1
- package/template_project/.claude/skills/frontend-vue/SKILL.md +1 -1
- package/template_project/.claude/skills/pdf-processing/SKILL.md +1 -1
- package/template_project/.claude/skills/postgres/SKILL.md +1 -1
- package/template_project/.claude/skills/testing-quality/SKILL.md +2 -0
- package/template_project/.claude/skills/webapp-testing/SKILL.md +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +3 -1
- package/template_project/.claude/ukit/index/tier-lane.mjs +1 -1
- package/template_project/.claude/ukit/runtime/execution-ledger.mjs +63 -1
- package/template_project/.omp/RULES.md +1 -1
- package/template_project/AGENTS.md +2 -0
- package/template_project/CLAUDE.md +2 -0
- package/template_project/instructions/core.md +2 -0
- 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.
|
|
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
|
-
|
|
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',
|
|
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
|
-
|
|
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
|
-
|
|
165
|
-
|
|
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.
|
|
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).
|
|
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.
|
|
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.
|
|
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
|
|