@ngockhoale/ukit 3.5.2 → 3.5.3
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 +17 -90
- package/README.md +1 -0
- package/package.json +8 -1
- package/src/cli/commands/doctor.js +14 -2
- package/src/cli/commands/memory.js +30 -2
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +9 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +86 -4
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/runtimeConfig.js +1 -1
- package/src/index/queryIndex.js +151 -20
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +149 -19
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +4 -1
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +86 -4
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +232 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- package/src/render/instructionRenderer.js +0 -290
- package/src/skill/auditSkill.js +0 -140
- package/template_project/instructions/overlays/repo.md +0 -9
|
@@ -1,199 +0,0 @@
|
|
|
1
|
-
// Development-only incident capture: bounded metadata, no session control or payload persistence.
|
|
2
|
-
import fs from 'node:fs/promises';
|
|
3
|
-
import { constants } from 'node:fs';
|
|
4
|
-
import { spawn } from 'node:child_process';
|
|
5
|
-
|
|
6
|
-
const ID_PATTERN = /^[\w.:/-]{1,120}$/;
|
|
7
|
-
const id = (value) => typeof value === 'string' && ID_PATTERN.test(value) ? value : null;
|
|
8
|
-
const time = (value) => Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
export async function runBoundedProcess(command, args = [], { timeoutMs = 650, maxBuffer = 65536 } = {}) {
|
|
12
|
-
return new Promise((resolve) => {
|
|
13
|
-
let settled = false;
|
|
14
|
-
let timedOut = false;
|
|
15
|
-
let oversized = false;
|
|
16
|
-
let stdoutBytes = 0;
|
|
17
|
-
let stderrBytes = 0;
|
|
18
|
-
const stdout = [];
|
|
19
|
-
const stderr = [];
|
|
20
|
-
let timer;
|
|
21
|
-
const finish = (result) => { if (!settled) { settled = true; clearTimeout(timer); resolve(result); } };
|
|
22
|
-
let child;
|
|
23
|
-
try { child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); }
|
|
24
|
-
catch (error) { resolve({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }); return; }
|
|
25
|
-
timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, Math.max(1, timeoutMs));
|
|
26
|
-
const collect = (chunks, field) => (chunk) => {
|
|
27
|
-
const next = field === 'stdout' ? stdoutBytes + chunk.length : stderrBytes + chunk.length;
|
|
28
|
-
if (next + (field === 'stdout' ? stderrBytes : stdoutBytes) > maxBuffer) { oversized = true; child.kill('SIGKILL'); return; }
|
|
29
|
-
chunks.push(chunk);
|
|
30
|
-
if (field === 'stdout') stdoutBytes = next; else stderrBytes = next;
|
|
31
|
-
};
|
|
32
|
-
child.stdout.on('data', collect(stdout, 'stdout'));
|
|
33
|
-
child.stderr.on('data', collect(stderr, 'stderr'));
|
|
34
|
-
child.on('error', (error) => finish({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }));
|
|
35
|
-
child.on('close', (code) => finish({ ok: !timedOut && !oversized && code === 0,
|
|
36
|
-
errorCode: timedOut ? 'ETIMEDOUT' : oversized ? 'MAXBUFFER' : code === 0 ? null : 'EXIT_NONZERO',
|
|
37
|
-
exitCode: code, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }));
|
|
38
|
-
});
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
export async function readBoundedTail(file, { maxBytes = 262144 } = {}) {
|
|
42
|
-
const cap = Math.max(1, Math.min(1048576, maxBytes));
|
|
43
|
-
const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NONBLOCK || 0) | (constants.O_NOFOLLOW || 0));
|
|
44
|
-
try {
|
|
45
|
-
const stat = await handle.stat();
|
|
46
|
-
if (!stat.isFile()) throw new Error('capture requires a regular file');
|
|
47
|
-
const size = Math.min(cap, stat.size);
|
|
48
|
-
const buffer = Buffer.alloc(size);
|
|
49
|
-
const { bytesRead } = await handle.read(buffer, 0, size, Math.max(0, stat.size - size));
|
|
50
|
-
let text = buffer.subarray(0, bytesRead).toString('utf8');
|
|
51
|
-
const truncated = stat.size > size;
|
|
52
|
-
if (truncated) text = text.includes('\n') ? text.slice(text.indexOf('\n') + 1) : '';
|
|
53
|
-
return { text, bytesRead, truncated, size: stat.size, modifiedAt: stat.mtimeMs };
|
|
54
|
-
} finally { await handle.close(); }
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
const operationKinds = ['model', 'tool', 'hook', 'subagent'];
|
|
58
|
-
const activeStates = new Set(['started', 'running', 'pending', 'waiting']);
|
|
59
|
-
const terminalStates = new Set(['completed', 'finished', 'failed', 'stopped', 'cancelled']);
|
|
60
|
-
export function processInventoryCommand(platform) {
|
|
61
|
-
return platform === 'win32' ? ['tasklist', ['/FO', 'CSV', '/NH']]
|
|
62
|
-
: ['ps', ['-A', '-o', 'pid=,ppid=,stat=,etime=,comm=']];
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
export function parseProcessInventory(platform, text) {
|
|
66
|
-
if (platform === 'win32') return text.split(/\r?\n/).flatMap((line) => {
|
|
67
|
-
const fields = line.match(/"(?:[^"]|"")*"|[^,]+/g) || [];
|
|
68
|
-
const name = fields[0]?.replace(/^"|"$/g, '').replace(/""/g, '"');
|
|
69
|
-
const pid = Number(fields[1]?.replaceAll('"', ''));
|
|
70
|
-
return Number.isSafeInteger(pid) && pid > 0 ? [{ pid, name: (name || '').split(/[\\/]/).at(-1) }] : [];
|
|
71
|
-
});
|
|
72
|
-
return text.split('\n').flatMap((line) => {
|
|
73
|
-
const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(.+)$/);
|
|
74
|
-
return match ? [{ pid: Number(match[1]), name: match[5].trim().split(/[\\/]/).at(-1) }] : [];
|
|
75
|
-
});
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
export function parseOwnerPids(command, text) {
|
|
79
|
-
const values = command === 'fuser' ? (text.match(/:\s*([^\r\n]+)/g) || []).flatMap((line) => line.slice(line.indexOf(':') + 1).trim().split(/\s+/).map((token) => token.match(/^(\d+)[A-Za-z]*$/)?.[1]).filter(Boolean))
|
|
80
|
-
: (text.match(/\b\d+\b/g) || []);
|
|
81
|
-
return [...new Set(values.map(Number).filter((pid) => Number.isSafeInteger(pid) && pid > 0))];
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
export function classifySessionActivity({ association = 'NOT_OBSERVABLE', summary = null, now = Date.now(), idleMs = 120000 } = {}) {
|
|
85
|
-
if (summary?.operatorBlock === 'OBSERVED_BLOCK') return 'OPERATOR_BLOCK';
|
|
86
|
-
if (summary?.sessionState === 'STOPPED') return 'STOPPED';
|
|
87
|
-
if (association !== 'ACTIVE_OWNER' || !summary) return 'NOT_OBSERVABLE';
|
|
88
|
-
const progressAge = Number.isFinite(summary.lastProgressAt) ? Math.max(0, now - summary.lastProgressAt) : null;
|
|
89
|
-
const outputAge = Number.isFinite(summary.lastOutputAt) ? Math.max(0, now - summary.lastOutputAt) : null;
|
|
90
|
-
const pending = summary.pendingOperations || {};
|
|
91
|
-
if (progressAge === null) return 'NOT_OBSERVABLE';
|
|
92
|
-
if (progressAge >= idleMs) return 'SUSPECTED_STALL';
|
|
93
|
-
if (Object.values(pending).some((items) => Array.isArray(items) && items.length > 0)
|
|
94
|
-
&& Object.entries(pending).some(([kind, items]) => items.length > 0 && summary.operationObservability?.[kind] === 'OBSERVED')) return 'WAITING';
|
|
95
|
-
if (outputAge !== null && outputAge >= idleMs) return 'NO_OUTPUT';
|
|
96
|
-
return 'ACTIVE_PROGRESS';
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
export function summarizeSessionTail(text) {
|
|
101
|
-
const result = { sessionId: null, modelAlias: 'NOT_OBSERVABLE', resolvedRoute: 'NOT_OBSERVABLE', currentTurn: 'NOT_OBSERVABLE', lastCompletedTurn: 'NOT_OBSERVABLE',
|
|
102
|
-
pendingModelRequest: 'NOT_OBSERVABLE', lastChunk: 'NOT_OBSERVABLE', terminalEvent: 'NOT_OBSERVABLE', pendingTools: [], unmatchedToolCallCandidates: [], pendingSubagent: 'NOT_OBSERVABLE',
|
|
103
|
-
pendingOperations: { model: [], tool: [], hook: [], subagent: [] }, operationObservability: { model: 'NOT_OBSERVABLE', tool: 'NOT_OBSERVABLE', hook: 'NOT_OBSERVABLE', subagent: 'NOT_OBSERVABLE' },
|
|
104
|
-
operatorBlock: 'NOT_OBSERVABLE', turnState: 'NOT_OBSERVABLE', sessionState: 'NOT_OBSERVABLE', compaction: 'NOT_OBSERVABLE', stopContinuation: 'NOT_OBSERVABLE',
|
|
105
|
-
lastProgressAt: 'NOT_OBSERVABLE', lastOutputAt: 'NOT_OBSERVABLE', outputState: 'NOT_OBSERVABLE' };
|
|
106
|
-
const operations = Object.fromEntries(operationKinds.map((kind) => [kind, new Map()]));
|
|
107
|
-
const tools = new Map();
|
|
108
|
-
const observedOperations = new Set();
|
|
109
|
-
const operatorBlocks = new Map();
|
|
110
|
-
for (const line of text.split('\n')) {
|
|
111
|
-
let row;
|
|
112
|
-
try { row = JSON.parse(line); } catch { continue; }
|
|
113
|
-
const ts = time(row.timestamp);
|
|
114
|
-
if (ts) result.lastProgressAt = Date.parse(ts);
|
|
115
|
-
if (row.type === 'session' && id(row.id)) { result.sessionId = id(row.id); result.sessionIdentityObserved = true; }
|
|
116
|
-
if (row.type === 'compaction') result.compaction = { timestamp: ts, id: id(row.id), tokensBefore: Number.isFinite(row.tokensBefore) ? row.tokensBefore : null };
|
|
117
|
-
if (row.type === 'session_end' || row.type === 'session_stopped') result.sessionState = 'STOPPED';
|
|
118
|
-
|
|
119
|
-
if (row.type === 'operation' && operationKinds.includes(row.operation) && id(row.id)) {
|
|
120
|
-
observedOperations.add(row.operation);
|
|
121
|
-
const state = typeof row.state === 'string' ? row.state.toLowerCase() : '';
|
|
122
|
-
if (activeStates.has(state)) operations[row.operation].set(row.id, { id: row.id, ...(id(row.name) ? { name: id(row.name) } : {}) });
|
|
123
|
-
if (terminalStates.has(state)) operations[row.operation].delete(row.id);
|
|
124
|
-
}
|
|
125
|
-
const eventState = String(row.state || '').toLowerCase();
|
|
126
|
-
if (row.type === 'operator_block' || row.operation === 'operator') {
|
|
127
|
-
const key = id(row.id) || `block-${operatorBlocks.size}`;
|
|
128
|
-
if (['pending', 'blocked', 'waiting'].includes(eventState)) operatorBlocks.set(key, { id: id(row.id), state: 'BLOCKED' });
|
|
129
|
-
if (terminalStates.has(eventState) || ['unblocked', 'cleared'].includes(eventState)) operatorBlocks.delete(key);
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
const message = row.message;
|
|
133
|
-
if (!message) continue;
|
|
134
|
-
if (message.role === 'toolResult' && id(message.toolCallId)) tools.delete(message.toolCallId);
|
|
135
|
-
if (message.role !== 'assistant') continue;
|
|
136
|
-
result.modelAlias = { provider: id(message.provider), model: id(message.model) };
|
|
137
|
-
if (message.stopReason) {
|
|
138
|
-
const stopReason = ['stop', 'toolUse', 'error', 'aborted', 'length'].includes(message.stopReason) ? message.stopReason : 'other';
|
|
139
|
-
result.lastCompletedTurn = { id: id(row.id), timestamp: ts, stopReason };
|
|
140
|
-
result.terminalEvent = stopReason;
|
|
141
|
-
result.turnState = message.stopReason === 'aborted' ? 'TURN_ABORTED' : message.stopReason === 'error' ? 'TURN_ERROR' : 'TURN_COMPLETED';
|
|
142
|
-
}
|
|
143
|
-
if (Array.isArray(message.content)) {
|
|
144
|
-
for (const part of message.content) {
|
|
145
|
-
if (part.type === 'toolCall' && id(part.id)) tools.set(part.id, { id: id(part.id), name: id(part.name) });
|
|
146
|
-
if (part.type === 'text' && ts) {
|
|
147
|
-
result.lastOutputAt = Date.parse(ts);
|
|
148
|
-
result.outputState = 'OBSERVED_OUTPUT';
|
|
149
|
-
}
|
|
150
|
-
}
|
|
151
|
-
}
|
|
152
|
-
}
|
|
153
|
-
result.unmatchedToolCallCandidates = [...tools.values()].slice(-32);
|
|
154
|
-
result.pendingOperations = Object.fromEntries(operationKinds.map((kind) => [kind, [...operations[kind].values()].slice(-32)]));
|
|
155
|
-
result.pendingTools = result.pendingOperations.tool;
|
|
156
|
-
result.operationObservability = Object.fromEntries(operationKinds.map((kind) => [kind, observedOperations.has(kind) || (kind === 'tool' && tools.size > 0) ? 'OBSERVED' : 'NOT_OBSERVABLE']));
|
|
157
|
-
result.pendingModelRequest = result.operationObservability.model === 'OBSERVED' ? (result.pendingOperations.model.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
|
|
158
|
-
result.pendingSubagent = result.operationObservability.subagent === 'OBSERVED' ? (result.pendingOperations.subagent.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
|
|
159
|
-
result.operatorBlock = operatorBlocks.size ? 'OBSERVED_BLOCK' : 'NOT_OBSERVABLE';
|
|
160
|
-
return result;
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
export function associateSessionEvidence({ sessions = [], ownerLocks = {}, processInventory = { state: 'NOT_OBSERVABLE', processes: [] }, logs = [] } = {}) {
|
|
164
|
-
const sessionCounts = new Map();
|
|
165
|
-
for (const session of sessions) if (id(session.sessionId)) sessionCounts.set(session.sessionId, (sessionCounts.get(session.sessionId) || 0) + 1);
|
|
166
|
-
return sessions.map((session) => {
|
|
167
|
-
const sessionId = id(session.sessionId);
|
|
168
|
-
const lock = sessionId ? ownerLocks[sessionId] : null;
|
|
169
|
-
const lockState = lock?.state || 'NOT_OBSERVABLE';
|
|
170
|
-
const pids = lockState === 'OBSERVED' && Array.isArray(lock.pids) ? [...new Set(lock.pids.filter((pid) => Number.isSafeInteger(pid) && pid > 0))] : [];
|
|
171
|
-
const uniqueOwnerPid = pids.length === 1 ? pids[0] : null;
|
|
172
|
-
const duplicateSession = sessionId !== null && sessionCounts.get(sessionId) > 1;
|
|
173
|
-
const process = uniqueOwnerPid !== null && processInventory.state === 'OBSERVED'
|
|
174
|
-
? processInventory.processes.find((entry) => entry.pid === uniqueOwnerPid && /^omp(?:\.exe)?$/i.test(entry.name)) || null : null;
|
|
175
|
-
const processAssociation = duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : pids.length > 1 ? 'AMBIGUOUS_OWNER_LOCK'
|
|
176
|
-
: uniqueOwnerPid === null ? (lockState === 'NOT_OBSERVABLE' ? 'NOT_OBSERVABLE' : 'UNHELD')
|
|
177
|
-
: processInventory.state !== 'OBSERVED' ? 'NOT_OBSERVABLE' : process ? 'VERIFIED' : 'PID_NOT_FOUND';
|
|
178
|
-
const ownerPid = duplicateSession ? null : uniqueOwnerPid;
|
|
179
|
-
const identityVerified = session?.sessionIdentityObserved === true || session?.sourceCoverage?.sessionIdentityObserved === true;
|
|
180
|
-
const ompLog = ownerPid === null ? null : logs.find((entry) => entry.pid === ownerPid) || null;
|
|
181
|
-
const logAssociation = ownerPid === null ? 'NOT_OBSERVABLE' : ompLog ? 'VERIFIED' : 'NOT_OBSERVABLE';
|
|
182
|
-
return { sessionId, transcript: typeof session.transcriptPath === 'string' ? session.transcriptPath.split(/[\\/]/).at(-1) : null,
|
|
183
|
-
sessionAssociation: identityVerified && processAssociation === 'VERIFIED' && logAssociation === 'VERIFIED' ? 'ACTIVE_OWNER' : 'NOT_OBSERVABLE',
|
|
184
|
-
ownerLockState: duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : lockState, ownerPid, processAssociation, logAssociation, identityVerified,
|
|
185
|
-
process: process ? { pid: process.pid, name: id(process.name) } : null, ompLog };
|
|
186
|
-
});
|
|
187
|
-
}
|
|
188
|
-
|
|
189
|
-
export function buildStallSnapshot({ now = Date.now(), lastProgressAt = null, lastOutputAt = null, idleMs = 120000, executionState = 'NOT_OBSERVABLE', ...evidence } = {}) {
|
|
190
|
-
const age = (ts) => Number.isFinite(ts) ? Math.max(0, now - ts) : null;
|
|
191
|
-
const progressAgeMs = age(lastProgressAt);
|
|
192
|
-
const outputAgeMs = age(lastOutputAt);
|
|
193
|
-
const activity = evidence.activity || (executionState === 'NO_EXECUTION' ? 'NO_EXECUTION'
|
|
194
|
-
: executionState !== 'EXECUTING' ? 'NOT_OBSERVABLE'
|
|
195
|
-
: progressAgeMs === null ? 'NOT_OBSERVABLE' : progressAgeMs >= idleMs ? 'NO_OBSERVED_PROGRESS'
|
|
196
|
-
: outputAgeMs !== null && outputAgeMs >= idleMs ? 'NO_OUTPUT' : 'RECENT_PROGRESS');
|
|
197
|
-
return { schemaVersion: 1, capturedAt: new Date(now).toISOString(), verdict: 'INSUFFICIENT_EVIDENCE', activity,
|
|
198
|
-
executionState, progressAgeMs, outputAgeMs, ...evidence };
|
|
199
|
-
}
|
|
@@ -1,290 +0,0 @@
|
|
|
1
|
-
import fs from 'node:fs';
|
|
2
|
-
import path from 'node:path';
|
|
3
|
-
import YAML from 'yaml';
|
|
4
|
-
|
|
5
|
-
import { renderTemplateString } from './renderTemplate.js';
|
|
6
|
-
|
|
7
|
-
/**
|
|
8
|
-
* Deterministic core/overlay renderer for the five instruction-contract
|
|
9
|
-
* outputs (SPEC §8.1, FR-004..FR-007). Pure functions; disk access only in
|
|
10
|
-
* renderInstructionsFromDisk / checkRenderedInstructions.
|
|
11
|
-
*
|
|
12
|
-
* Emission rules (byte-exact):
|
|
13
|
-
* h1 + '\n' + banner + '\n\n' + blocks.join('') [+ trailer] [+ '\n']
|
|
14
|
-
* where each `## ` block is `## <heading>` + the raw body slice — the body
|
|
15
|
-
* keeps its leading AND trailing whitespace, so concatenation reproduces
|
|
16
|
-
* the source bytes exactly; the reserved
|
|
17
|
-
* `__preamble__` block is the source's leading non-## text verbatim.
|
|
18
|
-
*/
|
|
19
|
-
|
|
20
|
-
export const PREAMBLE_KEY = '__preamble__';
|
|
21
|
-
|
|
22
|
-
const FENCE_OPEN_RE = /^ {0,3}(`{3,}|~{3,})/;
|
|
23
|
-
const FENCE_CLOSE_RES = {
|
|
24
|
-
'`': /^ {0,3}(`{3,})\s*$/,
|
|
25
|
-
'~': /^ {0,3}(~{3,})\s*$/,
|
|
26
|
-
};
|
|
27
|
-
const LEFTOVER_TOKEN_RE = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/;
|
|
28
|
-
|
|
29
|
-
/**
|
|
30
|
-
* Split markdown into a Map<heading, body> at `## ` boundaries.
|
|
31
|
-
* The reserved key PREAMBLE_KEY holds the leading non-## block verbatim.
|
|
32
|
-
* Bodies are raw slices (leading+trailing whitespace byte-meaningful).
|
|
33
|
-
*
|
|
34
|
-
* FR-017 (SPEC §5): heading detection is fence-aware — a `## ` line inside a
|
|
35
|
-
* fenced code block is content, not a boundary. Fences follow CommonMark: the
|
|
36
|
-
* opener is ``` or ~~~ indented ≤3 spaces; the closer uses the same character
|
|
37
|
-
* at the same or greater length with nothing after it. Duplicate `## `
|
|
38
|
-
* headings warn and keep the FIRST boundary (the duplicate line and its text
|
|
39
|
-
* stay inside the first section's verbatim body — no content is dropped).
|
|
40
|
-
*/
|
|
41
|
-
export function parseSections(markdown) {
|
|
42
|
-
// Collect `## ` heading boundaries by line scan, tracking fence state.
|
|
43
|
-
// Byte offsets are maintained manually so bodies stay raw slices.
|
|
44
|
-
const boundaries = []; // {index, matchLength, heading}
|
|
45
|
-
let fence = null; // {char, length} of the open fence
|
|
46
|
-
let offset = 0;
|
|
47
|
-
for (const line of markdown.split('\n')) {
|
|
48
|
-
if (fence) {
|
|
49
|
-
const close = line.match(FENCE_CLOSE_RES[fence.char]);
|
|
50
|
-
if (close && close[1].length >= fence.length) fence = null;
|
|
51
|
-
} else {
|
|
52
|
-
const open = line.match(FENCE_OPEN_RE);
|
|
53
|
-
if (open) {
|
|
54
|
-
fence = { char: open[1][0], length: open[1].length };
|
|
55
|
-
} else if (line.startsWith('## ') && line.length > 3) {
|
|
56
|
-
boundaries.push({ index: offset, matchLength: line.length, heading: line.slice(3).trimEnd() });
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
offset += line.length + 1;
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
const sections = new Map();
|
|
63
|
-
const first = boundaries[0];
|
|
64
|
-
|
|
65
|
-
const preamble = first ? markdown.slice(0, first.index) : markdown;
|
|
66
|
-
if (preamble.trim().length > 0) {
|
|
67
|
-
// Raw slice kept verbatim: its trailing newline(s) are the separator
|
|
68
|
-
// before the first ## section (e.g. the RULES.md preamble block).
|
|
69
|
-
sections.set(PREAMBLE_KEY, preamble);
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
// Seed with the reserved key so a literal `## __preamble__` heading after a
|
|
73
|
-
// preamble degrades to keep-first instead of overwriting it.
|
|
74
|
-
const seen = new Set(sections.has(PREAMBLE_KEY) ? [PREAMBLE_KEY] : []);
|
|
75
|
-
const heads = [];
|
|
76
|
-
for (const b of boundaries) {
|
|
77
|
-
if (seen.has(b.heading)) {
|
|
78
|
-
console.warn(
|
|
79
|
-
`instructionRenderer: duplicate ## heading '${b.heading}' — keeping first occurrence`,
|
|
80
|
-
);
|
|
81
|
-
continue;
|
|
82
|
-
}
|
|
83
|
-
seen.add(b.heading);
|
|
84
|
-
heads.push(b);
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
for (let i = 0; i < heads.length; i++) {
|
|
88
|
-
const h = heads[i];
|
|
89
|
-
const bodyStart = h.index + h.matchLength;
|
|
90
|
-
const bodyEnd = i + 1 < heads.length ? heads[i + 1].index : markdown.length;
|
|
91
|
-
// Raw slice up to (not including) the next `## ` heading — leading AND
|
|
92
|
-
// trailing whitespace are byte-meaningful (marker line vs blank line
|
|
93
|
-
// under the heading; multi-blank separators between sections). A skipped
|
|
94
|
-
// duplicate boundary leaves its line inside this slice.
|
|
95
|
-
sections.set(h.heading, markdown.slice(bodyStart, bodyEnd));
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
return sections;
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
/**
|
|
102
|
-
* Render one layout output. `outputSpec` = layout.outputs[i];
|
|
103
|
-
* `sources` = { <sourceName>: Map<heading, body> }; `vars` = flat/nested
|
|
104
|
-
* variables applied when `outputSpec.resolve_vars` is true.
|
|
105
|
-
* Reserved specifiers: heading '__preamble__' emits the source's leading
|
|
106
|
-
* non-## block verbatim (no `## ` prefix); heading '*' expands to every
|
|
107
|
-
* `## ` section of that source in file order.
|
|
108
|
-
*/
|
|
109
|
-
export function renderOutput(outputSpec, sources, vars = {}) {
|
|
110
|
-
if (!Array.isArray(outputSpec.sections) || outputSpec.sections.length === 0) {
|
|
111
|
-
throw new Error(`output ${outputSpec.target}: sections must be a non-empty list`);
|
|
112
|
-
}
|
|
113
|
-
|
|
114
|
-
const blocks = [];
|
|
115
|
-
for (const ref of outputSpec.sections) {
|
|
116
|
-
const source = sources.get(ref.from);
|
|
117
|
-
if (!source) {
|
|
118
|
-
throw new Error(`output ${outputSpec.target}: unknown source '${ref.from}'`);
|
|
119
|
-
}
|
|
120
|
-
if (ref.heading === '*') {
|
|
121
|
-
for (const [heading, body] of source) {
|
|
122
|
-
if (heading === PREAMBLE_KEY) continue;
|
|
123
|
-
blocks.push(`## ${heading}${body}`);
|
|
124
|
-
}
|
|
125
|
-
continue;
|
|
126
|
-
}
|
|
127
|
-
if (ref.heading === PREAMBLE_KEY) {
|
|
128
|
-
if (!source.has(PREAMBLE_KEY)) {
|
|
129
|
-
throw new Error(
|
|
130
|
-
`output ${outputSpec.target}: source '${ref.from}' has no __preamble__ block`,
|
|
131
|
-
);
|
|
132
|
-
}
|
|
133
|
-
blocks.push(source.get(PREAMBLE_KEY));
|
|
134
|
-
continue;
|
|
135
|
-
}
|
|
136
|
-
if (!source.has(ref.heading)) {
|
|
137
|
-
throw new Error(
|
|
138
|
-
`output ${outputSpec.target}: heading '${ref.heading}' missing from source '${ref.from}'`,
|
|
139
|
-
);
|
|
140
|
-
}
|
|
141
|
-
blocks.push(`## ${ref.heading}${source.get(ref.heading)}`);
|
|
142
|
-
}
|
|
143
|
-
|
|
144
|
-
let out = `${outputSpec.h1}\n${outputSpec.banner}\n\n${blocks.join('')}`;
|
|
145
|
-
if (outputSpec.trailer !== undefined && outputSpec.trailer !== null && outputSpec.trailer !== '') {
|
|
146
|
-
if (!out.endsWith('\n')) out += '\n';
|
|
147
|
-
out += `${outputSpec.trailer}`;
|
|
148
|
-
}
|
|
149
|
-
if (!out.endsWith('\n')) out += '\n';
|
|
150
|
-
|
|
151
|
-
if (outputSpec.resolve_vars) {
|
|
152
|
-
out = renderTemplateString(out, vars);
|
|
153
|
-
const leftover = out.match(LEFTOVER_TOKEN_RE);
|
|
154
|
-
if (leftover) {
|
|
155
|
-
// FR-017(d): warn + emit the token verbatim instead of bricking
|
|
156
|
-
// install/render on an imperfect user overlay.
|
|
157
|
-
console.warn(
|
|
158
|
-
`instructionRenderer: output '${outputSpec.target}' has unresolved template variable '{{${leftover[1]}}}' — emitted verbatim`,
|
|
159
|
-
);
|
|
160
|
-
}
|
|
161
|
-
}
|
|
162
|
-
return out;
|
|
163
|
-
}
|
|
164
|
-
|
|
165
|
-
/**
|
|
166
|
-
* Render every output in `layout` from `sourceTexts` ({name: markdown}).
|
|
167
|
-
* Source names are looked up as `sources.get(ref.from)`; overlay sources are
|
|
168
|
-
* named `overlay:<file-stem>` by convention in renderInstructionsFromDisk.
|
|
169
|
-
* `varsByResolve` supplies variables to outputs with resolve_vars: true.
|
|
170
|
-
* FR-006 strictness: a `## ` section referenced by zero outputs throws for
|
|
171
|
-
* shipped sources, preserving the layout contract. FR-017(c): the same
|
|
172
|
-
* condition in a USER overlay (`overlay:*` source name) downgrades to
|
|
173
|
-
* console.warn + keep — an imperfect repo.md must not brick install/render.
|
|
174
|
-
*/
|
|
175
|
-
export function renderAll(layout, sourceTexts, varsByResolve = {}) {
|
|
176
|
-
if (!layout || !Array.isArray(layout.outputs) || layout.outputs.length === 0) {
|
|
177
|
-
throw new Error('layout.outputs must be a non-empty list');
|
|
178
|
-
}
|
|
179
|
-
|
|
180
|
-
const sources = new Map(
|
|
181
|
-
Object.entries(sourceTexts).map(([name, text]) => [name, parseSections(text)]),
|
|
182
|
-
);
|
|
183
|
-
|
|
184
|
-
// Referenced-heading accounting for the unreferenced-section check.
|
|
185
|
-
const referenced = new Map(); // sourceName -> Set<heading>
|
|
186
|
-
const mark = (from, heading) => {
|
|
187
|
-
if (!referenced.has(from)) referenced.set(from, new Set());
|
|
188
|
-
referenced.get(from).add(heading);
|
|
189
|
-
};
|
|
190
|
-
for (const spec of layout.outputs) {
|
|
191
|
-
for (const ref of spec.sections || []) {
|
|
192
|
-
if (ref.heading === '*') {
|
|
193
|
-
const source = sources.get(ref.from);
|
|
194
|
-
if (!source) throw new Error(`unknown source '${ref.from}' referenced by '*'`);
|
|
195
|
-
for (const heading of source.keys()) {
|
|
196
|
-
if (heading !== PREAMBLE_KEY) mark(ref.from, heading);
|
|
197
|
-
}
|
|
198
|
-
} else if (ref.heading !== PREAMBLE_KEY) {
|
|
199
|
-
mark(ref.from, ref.heading);
|
|
200
|
-
}
|
|
201
|
-
}
|
|
202
|
-
}
|
|
203
|
-
for (const [name, source] of sources) {
|
|
204
|
-
const isOverlay = name.startsWith('overlay:');
|
|
205
|
-
for (const heading of source.keys()) {
|
|
206
|
-
if (heading === PREAMBLE_KEY) continue;
|
|
207
|
-
if (!referenced.get(name) || !referenced.get(name).has(heading)) {
|
|
208
|
-
if (isOverlay) {
|
|
209
|
-
console.warn(
|
|
210
|
-
`instructionRenderer: overlay source '${name}' has ## section '${heading}' referenced by zero outputs — kept`,
|
|
211
|
-
);
|
|
212
|
-
continue;
|
|
213
|
-
}
|
|
214
|
-
throw new Error(`source '${name}': ## section '${heading}' referenced by zero outputs`);
|
|
215
|
-
}
|
|
216
|
-
}
|
|
217
|
-
}
|
|
218
|
-
|
|
219
|
-
const rendered = new Map();
|
|
220
|
-
for (const spec of layout.outputs) {
|
|
221
|
-
const vars = spec.resolve_vars ? varsByResolve : {};
|
|
222
|
-
rendered.set(spec.target, renderOutput(spec, sources, vars));
|
|
223
|
-
}
|
|
224
|
-
return rendered;
|
|
225
|
-
}
|
|
226
|
-
|
|
227
|
-
const SOURCE_FILES = {
|
|
228
|
-
core: 'template_project/instructions/core.md',
|
|
229
|
-
'overlay:claude': 'template_project/instructions/overlays/claude.md',
|
|
230
|
-
'overlay:agents': 'template_project/instructions/overlays/agents.md',
|
|
231
|
-
'overlay:omp-rules': 'template_project/instructions/overlays/omp-rules.md',
|
|
232
|
-
'overlay:repo': 'template_project/instructions/overlays/repo.md',
|
|
233
|
-
};
|
|
234
|
-
|
|
235
|
-
/**
|
|
236
|
-
* Read layout + sources + repo-vars + package.json version from disk, render
|
|
237
|
-
* all outputs, and (write=true) write each target. Returns Map<target, content>.
|
|
238
|
-
* FR-015: every input read/parse failure is rethrown as a typed
|
|
239
|
-
* `Failed to read render input <rel>: <code|message>` naming the rel path.
|
|
240
|
-
* FR-016: target parent dirs are created before each write.
|
|
241
|
-
*/
|
|
242
|
-
export async function renderInstructionsFromDisk({ repoRoot, write = true } = {}) {
|
|
243
|
-
const abs = (p) => path.join(repoRoot, p);
|
|
244
|
-
const readInput = (rel, parse) => {
|
|
245
|
-
try {
|
|
246
|
-
return parse(fs.readFileSync(abs(rel), 'utf8'));
|
|
247
|
-
} catch (err) {
|
|
248
|
-
const reason = err && err.code ? err.code : err && err.message ? err.message : String(err);
|
|
249
|
-
throw new Error(`Failed to read render input ${rel}: ${reason}`);
|
|
250
|
-
}
|
|
251
|
-
};
|
|
252
|
-
const layout = readInput('template_project/instructions/layout.yaml', (text) =>
|
|
253
|
-
YAML.parse(text),
|
|
254
|
-
);
|
|
255
|
-
const repoVars =
|
|
256
|
-
readInput('template_project/instructions/repo-vars.yaml', (text) => YAML.parse(text)) || {};
|
|
257
|
-
const pkg = readInput('package.json', (text) => JSON.parse(text));
|
|
258
|
-
|
|
259
|
-
const sourceTexts = {};
|
|
260
|
-
for (const [name, rel] of Object.entries(SOURCE_FILES)) {
|
|
261
|
-
sourceTexts[name] = readInput(rel, (text) => text);
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
const vars = { ...repoVars, ukit: { ...(repoVars.ukit || {}), version: pkg.version } };
|
|
265
|
-
const rendered = renderAll(layout, sourceTexts, vars);
|
|
266
|
-
|
|
267
|
-
if (write) {
|
|
268
|
-
for (const [target, content] of rendered) {
|
|
269
|
-
fs.mkdirSync(path.dirname(abs(target)), { recursive: true });
|
|
270
|
-
fs.writeFileSync(abs(target), content);
|
|
271
|
-
}
|
|
272
|
-
}
|
|
273
|
-
return rendered;
|
|
274
|
-
}
|
|
275
|
-
|
|
276
|
-
/**
|
|
277
|
-
* → string[] of drifted target paths (empty = clean). Drift means rendered
|
|
278
|
-
* bytes differ from disk bytes, or the target is missing.
|
|
279
|
-
*/
|
|
280
|
-
export async function checkRenderedInstructions({ repoRoot } = {}) {
|
|
281
|
-
const rendered = await renderInstructionsFromDisk({ repoRoot, write: false });
|
|
282
|
-
const drift = [];
|
|
283
|
-
for (const [target, content] of rendered) {
|
|
284
|
-
const file = path.join(repoRoot, target);
|
|
285
|
-
if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) {
|
|
286
|
-
drift.push(target);
|
|
287
|
-
}
|
|
288
|
-
}
|
|
289
|
-
return drift;
|
|
290
|
-
}
|
package/src/skill/auditSkill.js
DELETED
|
@@ -1,140 +0,0 @@
|
|
|
1
|
-
import fs from 'node:fs/promises';
|
|
2
|
-
import path from 'node:path';
|
|
3
|
-
import { writeFileAtomic } from '../core/fileOps.js';
|
|
4
|
-
|
|
5
|
-
const TEMPLATE_FILES = [
|
|
6
|
-
'pressure-scenario-template.md',
|
|
7
|
-
'rationalization-table-template.md',
|
|
8
|
-
'trigger-accuracy-template.md',
|
|
9
|
-
];
|
|
10
|
-
|
|
11
|
-
// C91-022 (W3-skill): skillName becomes a path segment — reject traversal and
|
|
12
|
-
// separators before path.join so `../../x` can never escape docs/skill-audits.
|
|
13
|
-
function isValidSkillName(skillName) {
|
|
14
|
-
return typeof skillName === 'string'
|
|
15
|
-
&& skillName.trim().length > 0
|
|
16
|
-
&& skillName !== '.'
|
|
17
|
-
&& !skillName.includes('..')
|
|
18
|
-
&& !skillName.includes('/')
|
|
19
|
-
&& !skillName.includes('\\');
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
export function getAuditDir(rootDir, skillName) {
|
|
23
|
-
if (!isValidSkillName(skillName)) {
|
|
24
|
-
throw new Error(`invalid skill name: ${JSON.stringify(skillName)} — expected a plain directory name without path separators or ".."`);
|
|
25
|
-
}
|
|
26
|
-
return path.join(rootDir, 'docs', 'skill-audits', skillName);
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
function getHistoryPath(rootDir, skillName) {
|
|
30
|
-
return path.join(getAuditDir(rootDir, skillName), 'history.json');
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
export async function initSkillAudit({ rootDir = process.cwd(), skillName } = {}) {
|
|
34
|
-
if (!skillName) {
|
|
35
|
-
throw new Error('skillName is required. Usage: yarn skill:audit init <skill-name>');
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
const auditDir = getAuditDir(rootDir, skillName);
|
|
39
|
-
await fs.mkdir(auditDir, { recursive: true });
|
|
40
|
-
|
|
41
|
-
const templateSourceDir = path.join(rootDir, 'template_project/.claude/skills/skill-quality');
|
|
42
|
-
const copied = [];
|
|
43
|
-
const skipped = [];
|
|
44
|
-
|
|
45
|
-
for (const fileName of TEMPLATE_FILES) {
|
|
46
|
-
const destPath = path.join(auditDir, fileName);
|
|
47
|
-
const alreadyExists = await fs.access(destPath).then(() => true).catch(() => false);
|
|
48
|
-
if (alreadyExists) {
|
|
49
|
-
skipped.push(fileName);
|
|
50
|
-
continue;
|
|
51
|
-
}
|
|
52
|
-
const sourcePath = path.join(templateSourceDir, fileName);
|
|
53
|
-
await fs.copyFile(sourcePath, destPath);
|
|
54
|
-
copied.push(fileName);
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
return { auditDir, copied, skipped };
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
export async function recordAuditEntry({ rootDir = process.cwd(), skillName, entry } = {}) {
|
|
61
|
-
if (!skillName) {
|
|
62
|
-
throw new Error('skillName is required. Usage: yarn skill:audit record <skill-name>');
|
|
63
|
-
}
|
|
64
|
-
if (!entry || !entry.phase) {
|
|
65
|
-
throw new Error('entry with a "phase" field (RED|GREEN|REFACTOR) is required');
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
const auditDir = getAuditDir(rootDir, skillName);
|
|
69
|
-
await fs.mkdir(auditDir, { recursive: true });
|
|
70
|
-
|
|
71
|
-
const historyPath = getHistoryPath(rootDir, skillName);
|
|
72
|
-
const history = await readHistory(historyPath);
|
|
73
|
-
|
|
74
|
-
const record = {
|
|
75
|
-
date: entry.date ?? new Date().toISOString().slice(0, 10),
|
|
76
|
-
phase: entry.phase,
|
|
77
|
-
complianceRate: entry.complianceRate ?? null,
|
|
78
|
-
rationalizationsFound: entry.rationalizationsFound ?? [],
|
|
79
|
-
};
|
|
80
|
-
|
|
81
|
-
history.push(record);
|
|
82
|
-
await writeFileAtomic(historyPath, `${JSON.stringify(history, null, 2)}\n`);
|
|
83
|
-
|
|
84
|
-
return record;
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
export async function statusSkillAudit({ rootDir = process.cwd(), skillName } = {}) {
|
|
88
|
-
if (!skillName) {
|
|
89
|
-
throw new Error('skillName is required. Usage: yarn skill:audit status <skill-name>');
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
const historyPath = getHistoryPath(rootDir, skillName);
|
|
93
|
-
const history = await readHistory(historyPath);
|
|
94
|
-
const latest = history.length > 0 ? history[history.length - 1] : null;
|
|
95
|
-
|
|
96
|
-
const openRationalizations = history
|
|
97
|
-
.flatMap((record) => record.rationalizationsFound ?? [])
|
|
98
|
-
// `typeof null === 'object'` — a null entry in a hand-edited history file
|
|
99
|
-
// crashed status on `item.closed`. Optional chaining keeps nulls open.
|
|
100
|
-
.filter((item) => item?.closed !== true);
|
|
101
|
-
|
|
102
|
-
return { latest, openRationalizations, entryCount: history.length };
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
async function readHistory(historyPath) {
|
|
106
|
-
// C92-H-04: "absent" and "unreadable" are NOT the same. Only ENOENT yields a
|
|
107
|
-
// fresh array — any other failure to read or parse an existing history must
|
|
108
|
-
// fail loudly, or recordAuditEntry would overwrite the whole audit trail
|
|
109
|
-
// with a single row and report it as success.
|
|
110
|
-
let raw;
|
|
111
|
-
try {
|
|
112
|
-
raw = await fs.readFile(historyPath, 'utf8');
|
|
113
|
-
} catch (error) {
|
|
114
|
-
if (error?.code === 'ENOENT') {
|
|
115
|
-
return [];
|
|
116
|
-
}
|
|
117
|
-
const wrapped = new Error(
|
|
118
|
-
`cannot read skill-audit history at ${historyPath}: ${error?.message ?? error}. ` +
|
|
119
|
-
'Fix the file permissions or remove it to start a fresh audit trail.',
|
|
120
|
-
{ cause: error },
|
|
121
|
-
);
|
|
122
|
-
wrapped.code = 'ERR_SKILL_AUDIT_HISTORY_UNREADABLE';
|
|
123
|
-
throw wrapped;
|
|
124
|
-
}
|
|
125
|
-
try {
|
|
126
|
-
const parsed = JSON.parse(raw);
|
|
127
|
-
if (!Array.isArray(parsed)) {
|
|
128
|
-
throw new Error(`expected a JSON array at the top level, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
|
|
129
|
-
}
|
|
130
|
-
return parsed;
|
|
131
|
-
} catch (error) {
|
|
132
|
-
const wrapped = new Error(
|
|
133
|
-
`malformed skill-audit history at ${historyPath}: ${error?.message ?? error}. ` +
|
|
134
|
-
'The file was left untouched — repair or remove it before recording a new entry.',
|
|
135
|
-
{ cause: error },
|
|
136
|
-
);
|
|
137
|
-
wrapped.code = 'ERR_SKILL_AUDIT_HISTORY_MALFORMED';
|
|
138
|
-
throw wrapped;
|
|
139
|
-
}
|
|
140
|
-
}
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
## Release Policy (mandatory — never replace)
|
|
2
|
-
|
|
3
|
-
> User-mandated 2026-09-13. This file uses `mergeStrategy: skip` — ukit install/update never overwrite it. This section is permanent.
|
|
4
|
-
|
|
5
|
-
- **Latest code must always be on npm.** Every version bump ships with `npm publish` in the same cycle, before the work counts as done. A release that only commits to git is not a release (this gap left 2.3.18–2.3.19 unpublished).
|
|
6
|
-
- **npm and git always hold the same latest version.** After publish, `npm view @ngockhoale/ukit version` must equal the `package.json` version; if they ever diverge, publishing wins and happens first.
|
|
7
|
-
- **Never ask the user for npm publish permission** — approval is permanently granted for this package. Use `npm publish --dry-run` for pre-verification, then run the real publish in the same cycle.
|
|
8
|
-
- Users update with `ukit update`, which pulls from npm — an unpublished fix reaches no one. Git is code history/tracking only; npm is the distribution channel.
|
|
9
|
-
- **Repo-only rule:** this policy applies to the UKit development repo itself and must NEVER be added to `template_project/CLAUDE.md` / `template_project/AGENTS.md` (it must not ship to installed projects). Mirrored at the top of root CLAUDE.md + AGENTS.md; those copies can be wiped by a `ukit update` run inside this repo — if missing, restore them from this section.
|