@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.
- package/CHANGELOG.md +38 -90
- package/README.md +1 -0
- package/manifests/documentation.yaml +12 -1
- package/manifests/platform.full.yaml +12 -0
- package/package.json +34 -1
- package/src/cli/commands/doctor.js +55 -2
- package/src/cli/commands/indexTools.js +10 -4
- package/src/cli/commands/memory.js +107 -8
- package/src/core/memory/episodes.js +106 -7
- package/src/core/memory/memoryCheck.js +241 -0
- package/src/core/memory/memoryCheckRun.js +27 -0
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +46 -1
- package/src/core/memory/observations.js +192 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +204 -9
- package/src/core/memory/records.js +23 -0
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/memory/writeGate.js +137 -0
- package/src/core/runtimeConfig.js +12 -2
- package/src/index/buildIndex.js +26 -0
- package/src/index/paths.js +3 -1
- package/src/index/queryIndex.js +372 -26
- package/src/index/resolveContext.js +1 -1
- package/template_project/.claude/hooks/edit-hint.mjs +64 -17
- package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
- package/template_project/.claude/hooks/session-episode.sh +9 -4
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
- package/template_project/.claude/ukit/index/query-index.mjs +14 -3
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +8 -2
- package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/ukit/storage/config.json +4 -2
- package/src/core/agentRuntime/completionGate.js +0 -179
- package/src/core/agentRuntime/context.js +0 -571
- package/src/core/agentRuntime/qualityComparison.js +0 -112
- package/src/core/agentRuntime/resourcePolicy.js +0 -78
- package/src/core/agentRuntime/runtimeSupport.js +0 -255
- package/src/core/codeintel/manifest.js +0 -176
- package/src/core/experiments/deliberation.js +0 -327
- package/src/core/experiments/dynamicWorkflow.js +0 -507
- package/src/core/handoffDocValidator.js +0 -154
- package/src/core/memory/deltaOverlays.js +0 -493
- package/src/core/memory/learningCandidates.js +0 -347
- package/src/core/observability/emit/sessionBoot.js +0 -407
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/core/observability/evaluation/replay.js +0 -149
- package/src/core/observability/evaluation/scorecard.js +0 -465
- package/src/core/observability/schema/compatibility.js +0 -180
- package/src/core/observability/support/renderer.js +0 -130
- package/src/core/reviewPanelAggregate.js +0 -204
- package/src/core/taskBudgetValidator.js +0 -251
- package/src/core/taskProgressGuard.js +0 -227
- package/src/decision/reviewVerdict.js +0 -339
- package/src/decision/runtimeFilter.js +0 -150
- package/src/decision/runtimeScheduler.js +0 -239
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- package/src/index/contextPack.js +0 -285
- package/src/index/impactContext.js +0 -360
- package/src/index/reviewPolicy.js +0 -368
- package/src/index/sensitivePath.js +0 -21
- package/src/render/instructionRenderer.js +0 -290
- package/src/skill/auditSkill.js +0 -140
- 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
|
-
}
|