@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.
- package/CHANGELOG.md +26 -0
- package/package.json +2 -1
- package/scripts/release/candidate-state.mjs +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/hooks/task-watchdog.sh +7 -7
- 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 +151 -16
- 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,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.
|
|
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
|
-
|
|
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',
|
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
#
|
|
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
|
|
72
|
+
head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
|
|
73
73
|
else
|
|
74
|
-
head -c
|
|
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
|
|
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.
|
|
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.
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
6038
|
+
emit({ systemMessage: advisory ? `${message} ${advisory}` : message,
|
|
5921
6039
|
...(result.outcome === 'blocked' || result.outcome === 'handback' ? { outcome: 'blocked', complete: false } : {}),
|
|
5922
|
-
})
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|