@ngockhoale/ukit 3.5.2 → 3.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/CHANGELOG.md +38 -90
  2. package/README.md +1 -0
  3. package/manifests/documentation.yaml +12 -1
  4. package/manifests/platform.full.yaml +12 -0
  5. package/package.json +34 -1
  6. package/src/cli/commands/doctor.js +55 -2
  7. package/src/cli/commands/indexTools.js +10 -4
  8. package/src/cli/commands/memory.js +107 -8
  9. package/src/core/memory/episodes.js +106 -7
  10. package/src/core/memory/memoryCheck.js +241 -0
  11. package/src/core/memory/memoryCheckRun.js +27 -0
  12. package/src/core/memory/memoryHit.js +2 -0
  13. package/src/core/memory/mutateMemory.js +46 -1
  14. package/src/core/memory/observations.js +192 -0
  15. package/src/core/memory/projectIdentity.js +9 -2
  16. package/src/core/memory/recallEngine.js +204 -9
  17. package/src/core/memory/records.js +23 -0
  18. package/src/core/memory/registryPrune.js +230 -0
  19. package/src/core/memory/retrieval.js +12 -3
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +12 -2
  22. package/src/index/buildIndex.js +26 -0
  23. package/src/index/paths.js +3 -1
  24. package/src/index/queryIndex.js +372 -26
  25. package/src/index/resolveContext.js +1 -1
  26. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  27. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  28. package/template_project/.claude/hooks/session-episode.sh +9 -4
  29. package/template_project/.claude/settings.json +2 -2
  30. package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
  31. package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
  32. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  33. package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
  34. package/template_project/.claude/ukit/index/route-task.mjs +8 -2
  35. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  36. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
  37. package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
  38. package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
  39. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  40. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  41. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  42. package/template_project/ukit/storage/config.json +4 -2
  43. package/src/core/agentRuntime/completionGate.js +0 -179
  44. package/src/core/agentRuntime/context.js +0 -571
  45. package/src/core/agentRuntime/qualityComparison.js +0 -112
  46. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  47. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  48. package/src/core/codeintel/manifest.js +0 -176
  49. package/src/core/experiments/deliberation.js +0 -327
  50. package/src/core/experiments/dynamicWorkflow.js +0 -507
  51. package/src/core/handoffDocValidator.js +0 -154
  52. package/src/core/memory/deltaOverlays.js +0 -493
  53. package/src/core/memory/learningCandidates.js +0 -347
  54. package/src/core/observability/emit/sessionBoot.js +0 -407
  55. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  56. package/src/core/observability/evaluation/perturbation.js +0 -273
  57. package/src/core/observability/evaluation/replay.js +0 -149
  58. package/src/core/observability/evaluation/scorecard.js +0 -465
  59. package/src/core/observability/schema/compatibility.js +0 -180
  60. package/src/core/observability/support/renderer.js +0 -130
  61. package/src/core/reviewPanelAggregate.js +0 -204
  62. package/src/core/taskBudgetValidator.js +0 -251
  63. package/src/core/taskProgressGuard.js +0 -227
  64. package/src/decision/reviewVerdict.js +0 -339
  65. package/src/decision/runtimeFilter.js +0 -150
  66. package/src/decision/runtimeScheduler.js +0 -239
  67. package/src/diagnostics/classifyHang.js +0 -246
  68. package/src/diagnostics/ompStallSnapshot.js +0 -199
  69. package/src/index/contextPack.js +0 -285
  70. package/src/index/impactContext.js +0 -360
  71. package/src/index/reviewPolicy.js +0 -368
  72. package/src/index/sensitivePath.js +0 -21
  73. package/src/render/instructionRenderer.js +0 -290
  74. package/src/skill/auditSkill.js +0 -140
  75. package/template_project/instructions/overlays/repo.md +0 -9
@@ -1,368 +0,0 @@
1
- // reviewPolicy.js — deterministic review decision policy evaluator (BL-015 /
2
- // SPEC FR-003 / ARCH §Review Decision Policy).
3
- //
4
- // The evaluator answers "is one more verification round needed?" at checkpoints
5
- // — playbook step boundaries and the pre-Stop gate (stop-coordinator.mjs) —
6
- // from checkable signals only. It is the TRIGGER for the existing review lane
7
- // (`review-verdict.mjs` + `review-panel-aggregate.mjs`, GAP M05 reuse), never a
8
- // new reviewer and never a second gate: consumers record the verdict as an
9
- // advisory while the completion gate stays the single Stop authority.
10
- //
11
- // Contract:
12
- // evaluateReviewPolicy({signals, doneCriteria, evidenceClasses, fixLoopCount,
13
- // round, cap, escalationDepth?, crossCheck?, projectRoot?,
14
- // appendDecisionReceipt?})
15
- // → {action, namedCheck?, signalsHit[], rationale, reviewRounds,
16
- // verified[], notVerified[], missingEvidence[]}
17
- //
18
- // action ∈ REVIEW_POLICY_ACTIONS — exactly five:
19
- // 'finish' stop; done predicates evidenced, no suspicion.
20
- // 'run-targeted-check' name the command/surface + predicate to satisfy.
21
- // 'independent-review' name what the reviewer must verify; the caller
22
- // bundles {original request, diff, context files,
23
- // run evidence} for the review-verdict lane — never
24
- // the agent's summary alone (SPEC FR-004d).
25
- // 'escalate' name the deeper lane/question (unic-decision
26
- // laneDeepening/verificationDepth family) or the
27
- // human authorization boundary. Terminal hand-off:
28
- // it is NOT another round, so the cap never traps it.
29
- // 'inconclusive' honest stop: report verified-vs-not, name the
30
- // missing evidence. Round cap + timeout land here —
31
- // never an infinite block.
32
- //
33
- // Safety boundary (ARCH §Safety boundary): no self-declared confidence exists
34
- // in the input contract — keys like `confidence`/`statedConfidence` are ignored
35
- // by design, so identical signal sets decide identically whether or not the
36
- // agent narrates certainty.
37
- //
38
- // Calibration (ARCH §Calibration plan): when a caller supplies `projectRoot` +
39
- // an `appendDecisionReceipt` implementation (execution-ledger.mjs signature,
40
- // consumed unchanged), every evaluation emits one `kind:'review-policy'`
41
- // receipt carrying action + namedCheck + signalsHit + round so decision↔outcome
42
- // joins can measure unnecessary-review and escaped-defect rates.
43
- //
44
- // Parity: tests/consistency/reviewPolicyParity.test.js locks this module and
45
- // the installed mirror to identical exports and identical verdicts.
46
-
47
- import { resolveCrossCheckDepth } from './crossCheckMatrix.js';
48
-
49
- // Exactly five actions — the closed enum consumers may switch on.
50
- export const REVIEW_POLICY_ACTIONS = Object.freeze([
51
- 'finish',
52
- 'run-targeted-check',
53
- 'independent-review',
54
- 'escalate',
55
- 'inconclusive',
56
- ]);
57
-
58
- // Action severity for multi-signal precedence and the escalationDepth bias.
59
- // A higher-severity fired signal wins the action; the namedCheck travels with
60
- // the winning signal.
61
- const ACTION_SEVERITY = Object.freeze({
62
- finish: 0,
63
- 'run-targeted-check': 1,
64
- 'independent-review': 2,
65
- escalate: 3,
66
- inconclusive: 0,
67
- });
68
-
69
- // Suspicion signal → action the policy fires. 'targeted' resolves to
70
- // 'run-targeted-check', 'review' to 'independent-review'.
71
- const SIGNAL_ACTION = Object.freeze({
72
- targeted: 'run-targeted-check',
73
- review: 'independent-review',
74
- escalate: 'escalate',
75
- });
76
-
77
- // The 8-signal suspicion catalogue (ARCH §Suspicion-signal catalogue), kept as
78
- // data so calibration + docs share one list. `check` names the exact check the
79
- // action demands — command/surface + predicate, or what the reviewer verifies.
80
- export const SUSPICION_SIGNAL_CATALOGUE = Object.freeze([
81
- {
82
- id: 'unchecked-request-details',
83
- fires: 'targeted',
84
- check: 'cross-check every request detail against the diff — each stated requirement must have a corresponding hunk or an explicit, evidenced skip',
85
- },
86
- {
87
- id: 'wider-than-goal',
88
- fires: 'review',
89
- check: 'independent reviewer verifies each out-of-scope hunk is either required for the stated goal or reverted',
90
- },
91
- {
92
- id: 'unwired-component',
93
- fires: 'targeted',
94
- check: 'verify the component is reachable in the usage flow — import/callsite present + render/import observation, not just a file on disk',
95
- },
96
- {
97
- id: 'claimed-verification',
98
- fires: 'targeted',
99
- check: 're-run the claimed verification and require verbatim captured output — a claimed pass with no output is not evidence',
100
- },
101
- {
102
- id: 'impl-detail-tests-only',
103
- fires: 'targeted',
104
- check: 'run one concrete behavioral input→output case per public entry point — tests asserting internals cannot catch user-visible failure',
105
- },
106
- {
107
- id: 'tool-error-storm',
108
- fires: 'review',
109
- check: 'independent reviewer checks whether the unexplained tool errors mask a real (often environment-dependent) defect',
110
- },
111
- {
112
- id: 'fix-loop-same-fingerprint',
113
- fires: 'escalate',
114
- check: 'fire the unic-decision laneDeepening/verificationDepth question → deeper debug lane (runtime-forensics for a live symptom, systematic-debugging depth otherwise); never another same-lane retry',
115
- },
116
- {
117
- id: 'unconfirmed-assumptions',
118
- fires: 'review',
119
- check: 'independent reviewer verifies the unconfirmed assumptions the run carried to done — each must be confirmed or named as a stated limit',
120
- },
121
- ]);
122
-
123
- // Catalogue ids callers may assert through `signals` (object-map or array).
124
- // Derived signals (`claimed-verification`, `fix-loop-same-fingerprint`) share
125
- // the same catalogue — the caller never has to restate what the inputs already
126
- // prove.
127
- const SIGNAL_ID_SET = new Set(SUSPICION_SIGNAL_CATALOGUE.map((s) => s.id));
128
-
129
- // Round-cap default: one initial check + one re-check round is the ARCH
130
- // "one round default-sufficient for small tasks" bound. Every check-driven
131
- // loop must land `inconclusive` at the cap, never retry forever.
132
- export const DEFAULT_REVIEW_ROUND_CAP = 2;
133
-
134
- // Same-fingerprint fix-loop threshold — aligned with the route layer's
135
- // debugLoopThreshold default (runtimeConfig.js:379). fixLoopCount ≥ threshold
136
- // derives suspicion signal #7 and routes to `escalate`.
137
- export const DEFAULT_FIX_LOOP_THRESHOLD = 2;
138
-
139
- // escalationDepth (forward-declared slot for TASK-C85-016's depth matrix):
140
- // {depth, reasons[]?} or a bare depth string. The depth matrix may only RAISE
141
- // the action floor — it never suppresses a fired suspicion signal.
142
- const DEPTH_MIN_ACTION = Object.freeze({
143
- none: 'finish',
144
- runnable: 'run-targeted-check',
145
- 'review-round': 'independent-review',
146
- escalate: 'escalate',
147
- });
148
-
149
- function isPlainObject(value) {
150
- return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
151
- }
152
-
153
- function clampInt(value, fallback, min = 0, max = 99) {
154
- const n = Number(value);
155
- return Number.isFinite(n) ? Math.max(min, Math.min(max, Math.trunc(n))) : fallback;
156
- }
157
-
158
- // doneCriteria entry → {name, status}. Statuses:
159
- // 'verified' — a real-run/surface receipt attests the predicate.
160
- // 'claimed' — asserted with no captured output (suspicion signal #4).
161
- // 'missing' — no evidence at all.
162
- // Bare strings and `{satisfied:true}` shorthands normalize so callers can pass
163
- // the completion contract's bare class tokens when they have nothing richer.
164
- function normalizeDoneCriterion(entry) {
165
- if (typeof entry === 'string' && entry.trim()) {
166
- return { name: entry.trim(), status: 'missing' };
167
- }
168
- if (!isPlainObject(entry)) return null;
169
- const name = typeof entry.name === 'string' && entry.name.trim()
170
- ? entry.name.trim()
171
- : (typeof entry.id === 'string' && entry.id.trim() ? entry.id.trim() : null);
172
- if (!name) return null;
173
- let status = typeof entry.status === 'string' ? entry.status.trim().toLowerCase() : null;
174
- if (status !== 'verified' && status !== 'claimed') {
175
- status = entry.satisfied === true || entry.verified === true ? 'verified' : 'missing';
176
- }
177
- return { name, status };
178
- }
179
-
180
- // signals may arrive as an object map ({'unwired-component': true, ...}) or an
181
- // array of catalogue ids. Only catalogue keys with a truthy flag count — a
182
- // caller cannot inject self-declared confidence or invent signals, and a
183
- // `confidence: 'sure'` key is silently ignored by design.
184
- function assertedSignalIds(signals) {
185
- const ids = new Set();
186
- if (Array.isArray(signals)) {
187
- for (const id of signals) {
188
- if (typeof id === 'string' && SIGNAL_ID_SET.has(id)) ids.add(id);
189
- }
190
- } else if (isPlainObject(signals)) {
191
- for (const [id, flag] of Object.entries(signals)) {
192
- if (flag && SIGNAL_ID_SET.has(id)) ids.add(id);
193
- }
194
- }
195
- return ids;
196
- }
197
-
198
- function escalationDepthAction(escalationDepth) {
199
- const depth = typeof escalationDepth === 'string'
200
- ? escalationDepth
201
- : escalationDepth?.depth;
202
- return typeof depth === 'string' && Object.hasOwn(DEPTH_MIN_ACTION, depth)
203
- ? DEPTH_MIN_ACTION[depth]
204
- : 'finish';
205
- }
206
-
207
- // Resolve the route record's crossCheck sub-record (BL-016): a pinned `depth`
208
- // field counts as an already-resolved value; otherwise the full sub-record
209
- // (risk/implementerReliability/evidenceQuality/rigor/…) feeds the matrix.
210
- // Returns null when no usable depth exists — never throws.
211
- function resolveCrossCheckInput(crossCheck) {
212
- if (crossCheck == null) return null;
213
- if (typeof crossCheck === 'string') {
214
- return Object.hasOwn(DEPTH_MIN_ACTION, crossCheck) ? crossCheck : null;
215
- }
216
- if (!isPlainObject(crossCheck)) return null;
217
- if (typeof crossCheck.depth === 'string' && Object.hasOwn(DEPTH_MIN_ACTION, crossCheck.depth)) {
218
- return crossCheck.depth;
219
- }
220
- try {
221
- return resolveCrossCheckDepth(crossCheck);
222
- } catch {
223
- return null; // a malformed sub-record never blocks the evaluation
224
- }
225
- }
226
-
227
- // ─── evaluator ──────────────────────────────────────────────────────────────
228
-
229
- export function evaluateReviewPolicy({
230
- signals = {},
231
- doneCriteria = [],
232
- evidenceClasses = [],
233
- fixLoopCount = 0,
234
- round = 0,
235
- cap = DEFAULT_REVIEW_ROUND_CAP,
236
- escalationDepth = null,
237
- // TASK-C85-016 (BL-016): the route record's crossCheck sub-record resolves
238
- // its depth through the matrix when the caller didn't pass an explicit
239
- // escalationDepth. A pinned `depth` field on the sub-record wins as an
240
- // already-resolved value; explicit escalationDepth wins over both.
241
- crossCheck = null,
242
- fixLoopThreshold = DEFAULT_FIX_LOOP_THRESHOLD,
243
- projectRoot = null,
244
- appendDecisionReceipt = null,
245
- } = {}) {
246
- const criteria = (Array.isArray(doneCriteria) ? doneCriteria : [])
247
- .map(normalizeDoneCriterion)
248
- .filter(Boolean);
249
- const verified = criteria.filter((c) => c.status === 'verified').map((c) => c.name);
250
- const notVerified = criteria.filter((c) => c.status !== 'verified').map((c) => c.name);
251
- const claimed = criteria.filter((c) => c.status === 'claimed').map((c) => c.name);
252
- const requiredEvidence = (Array.isArray(evidenceClasses) ? evidenceClasses : [])
253
- .filter((e) => typeof e === 'string' && e.trim());
254
- const cappedRound = clampInt(round, 0);
255
- const cappedCap = clampInt(cap, DEFAULT_REVIEW_ROUND_CAP, 1);
256
-
257
- // ── signal detection ────────────────────────────────────────────────────
258
- // Caller-asserted signals + the two the inputs derive on their own: a
259
- // 'claimed' criterion IS signal #4 (verification claimed, no output) and
260
- // fixLoopCount ≥ threshold IS signal #7 (same-fingerprint fix loop).
261
- const hitIds = assertedSignalIds(signals);
262
- if (claimed.length > 0) hitIds.add('claimed-verification');
263
- if (clampInt(fixLoopCount, 0) >= Math.max(1, clampInt(fixLoopThreshold, DEFAULT_FIX_LOOP_THRESHOLD))) {
264
- hitIds.add('fix-loop-same-fingerprint');
265
- }
266
-
267
- const hits = SUSPICION_SIGNAL_CATALOGUE.filter((s) => hitIds.has(s.id));
268
-
269
- // ── base action ─────────────────────────────────────────────────────────
270
- let action = 'finish';
271
- let namedCheck = null;
272
- let rationale;
273
-
274
- if (hits.length > 0) {
275
- const winning = hits.reduce((best, signal) => (
276
- ACTION_SEVERITY[SIGNAL_ACTION[signal.fires]] > ACTION_SEVERITY[SIGNAL_ACTION[best.fires]]
277
- ? signal
278
- : best
279
- ));
280
- action = SIGNAL_ACTION[winning.fires];
281
- namedCheck = winning.check;
282
- rationale = `suspicion signal${hits.length > 1 ? 's' : ''} fired: ${hits.map((s) => s.id).join(', ')} — strongest is ${winning.id} (${action})`;
283
- } else if (notVerified.length > 0) {
284
- // Unevidenced work with no named suspicion still cannot finish: demand one
285
- // cheap targeted check per the cheapest defect to catch.
286
- action = 'run-targeted-check';
287
- namedCheck = `obtain the named evidence for: ${notVerified.join(', ')} — receipt or verbatim output, not a claim`;
288
- rationale = `unverified done-criteria with no fired signal: ${notVerified.join(', ')}`;
289
- } else if (criteria.length === 0 && requiredEvidence.length > 0) {
290
- // No criteria but required evidence classes → confirm the classes landed.
291
- action = 'run-targeted-check';
292
- namedCheck = `confirm receipt classes present: ${requiredEvidence.join(', ')}`;
293
- rationale = 'no done-criteria; required evidence classes unaccounted';
294
- } else if (criteria.length === 0) {
295
- // Nothing checkable exists at all — the honest report, not a free pass.
296
- action = 'inconclusive';
297
- rationale = 'no done-criteria and no evidence classes to verify — nothing checkable was provided';
298
- } else {
299
- // Every criterion verified — a verified criterion IS the evidence;
300
- // declared evidence classes add no extra round on their own.
301
- rationale = 'all done-criteria verified, no suspicion signals — review round suppressed';
302
- }
303
-
304
- // ── cross-check depth floor (escalationDepth) ───────────────────────────
305
- // TASK-C85-016 wires the depth matrix here: a depth may raise the action
306
- // floor (e.g. 'review-round' forces ≥ independent-review) but never lowers
307
- // it — a fired suspicion signal always outranks a shallow depth.
308
- const effectiveDepth = escalationDepth ?? resolveCrossCheckInput(crossCheck);
309
- const depthFloor = escalationDepthAction(effectiveDepth);
310
- if (ACTION_SEVERITY[depthFloor] > ACTION_SEVERITY[action]) {
311
- const depth = typeof effectiveDepth === 'object' ? (effectiveDepth?.depth ?? effectiveDepth) : effectiveDepth;
312
- action = depthFloor;
313
- namedCheck = namedCheck
314
- ?? (action === 'independent-review'
315
- ? 'cross-check depth matrix requires one independent review round — reviewer verifies the request is satisfied, wired into flow, and free of convention breaks'
316
- : (action === 'escalate'
317
- ? SUSPICION_SIGNAL_CATALOGUE.find((s) => s.id === 'fix-loop-same-fingerprint').check
318
- : 'run the artifact-class runnable checks required by the depth matrix'));
319
- rationale += `; escalationDepth=${depth} raised the action floor to ${action}`;
320
- }
321
-
322
- // ── round cap → inconclusive (never infinite blocking) ──────────────────
323
- // 'escalate' bypasses the cap deliberately: it is a terminal hand-off to a
324
- // deeper lane, not another loop iteration.
325
- if (action !== 'finish' && action !== 'escalate' && cappedRound >= cappedCap) {
326
- const previous = action;
327
- action = 'inconclusive';
328
- namedCheck = null;
329
- rationale = `review round cap reached (round=${cappedRound} ≥ cap=${cappedCap}) — ${previous} could not be confirmed; reporting verified-vs-not honestly instead of looping`;
330
- }
331
-
332
- const missingEvidence = [...new Set([...notVerified, ...requiredEvidence])];
333
-
334
- const decision = {
335
- action,
336
- namedCheck,
337
- signalsHit: hits.map((s) => s.id),
338
- rationale,
339
- reviewRounds: cappedRound + (action === 'finish' || action === 'inconclusive' ? 0 : 1),
340
- verified,
341
- notVerified,
342
- missingEvidence,
343
- };
344
-
345
- // ── calibration receipt (consumed signature — never edited) ─────────────
346
- // decisionKeys carry the receipt fields the ledger schema doesn't model:
347
- // signalsHit, round, and outcome (unknown at decision time → pending).
348
- if (typeof appendDecisionReceipt === 'function' && projectRoot) {
349
- try {
350
- const appended = appendDecisionReceipt(projectRoot, {
351
- kind: 'review-policy',
352
- boundary: 'review',
353
- stage: 'deterministic',
354
- outcomeClass: decision.action,
355
- checkpoint: decision.namedCheck,
356
- decisionKeys: [
357
- `signalsHit=${decision.signalsHit.join(',') || 'none'}`,
358
- `round=${cappedRound}`,
359
- 'outcome=pending',
360
- ],
361
- agreement: 'n/a',
362
- });
363
- if (appended?.catch) appended.catch(() => {});
364
- } catch { /* calibration telemetry never fails the evaluation */ }
365
- }
366
-
367
- return decision;
368
- }
@@ -1,21 +0,0 @@
1
- // Pure (I/O-free) sensitive-path predicate shared by the context pack builder
2
- // (src/index/contextPack.js) and the delegation candidate mapper
3
- // (src/core/agentRuntime/context.js). One definition so the two cannot drift.
4
- export function isSensitivePath(value) {
5
- const normalized = String(value ?? '').replace(/\\/g, '/');
6
- const segments = normalized.split('/');
7
- const base = segments[segments.length - 1] ?? '';
8
- if (base.toLowerCase().startsWith('.env')) {
9
- return true;
10
- }
11
- if (/\.(?:pem|key|p12|pfx|jks|keystore)$/i.test(base)) {
12
- return true;
13
- }
14
- if (/^(?:credentials?|\.npmrc|\.netrc|\.pypirc)(?:\.[^/]*)?$/i.test(base)) {
15
- return true;
16
- }
17
- if (/^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.[^/]*)?$/i.test(base)) {
18
- return true;
19
- }
20
- return segments.includes('.ssh') || segments.includes('.aws') || segments.includes('.gnupg');
21
- }
@@ -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
- }