@holmes-lab/holmes-kit 0.35.25 → 0.36.1
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 +346 -0
- package/README.md +3 -2
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/approve-status.js +4 -1
- package/dist/holmes/cli/approve-watch.js +3 -1
- package/dist/holmes/cli/approve.d.ts +10 -0
- package/dist/holmes/cli/approve.js +31 -1
- package/dist/holmes/cli/claude-switches.d.ts +7 -1
- package/dist/holmes/cli/claude-switches.js +11 -7
- package/dist/holmes/cli/codex-toml.d.ts +3 -0
- package/dist/holmes/cli/codex-toml.js +2 -1
- package/dist/holmes/cli/doctor.d.ts +25 -1
- package/dist/holmes/cli/doctor.js +153 -7
- package/dist/holmes/cli/index.js +99 -4
- package/dist/holmes/cli/init.js +4 -3
- package/dist/holmes/cli/os-notify.d.ts +3 -1
- package/dist/holmes/cli/os-notify.js +10 -4
- package/dist/holmes/cli/review.d.ts +25 -0
- package/dist/holmes/cli/review.js +111 -0
- package/dist/holmes/cli/roles-readme.d.ts +11 -0
- package/dist/holmes/cli/roles-readme.js +38 -16
- package/dist/holmes/cli/roles.d.ts +12 -0
- package/dist/holmes/cli/roles.js +86 -0
- package/dist/holmes/cli/run.d.ts +65 -0
- package/dist/holmes/cli/run.js +308 -0
- package/dist/holmes/cli/runtime-binding.d.ts +30 -0
- package/dist/holmes/cli/runtime-binding.js +96 -7
- package/dist/holmes/cli/test-platform.d.ts +16 -0
- package/dist/holmes/cli/test-platform.js +31 -1
- package/dist/holmes/config/config.d.ts +49 -0
- package/dist/holmes/config/config.js +146 -3
- package/dist/holmes/config/project-caps.d.ts +21 -0
- package/dist/holmes/config/project-caps.js +114 -0
- package/dist/holmes/governance/approval-queue.d.ts +17 -3
- package/dist/holmes/governance/approval-queue.js +48 -6
- package/dist/holmes/governance/autonomy.d.ts +6 -0
- package/dist/holmes/governance/autonomy.js +21 -0
- package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
- package/dist/holmes/governance/push-gate-runner.js +49 -1
- package/dist/holmes/governance/replica-id.d.ts +9 -0
- package/dist/holmes/governance/replica-id.js +44 -7
- package/dist/holmes/governance/role-policy.d.ts +41 -1
- package/dist/holmes/governance/role-policy.js +137 -20
- package/dist/holmes/governance/run-mode.d.ts +14 -0
- package/dist/holmes/governance/run-mode.js +120 -0
- package/dist/holmes/governance/tool-actions.d.ts +30 -0
- package/dist/holmes/governance/tool-actions.js +121 -0
- package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
- package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
- package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
- package/dist/holmes/guardrail/classification-mode.js +135 -0
- package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
- package/dist/holmes/guardrail/dynamic-write.js +304 -0
- package/dist/holmes/guardrail/phase.d.ts +2 -1
- package/dist/holmes/guardrail/phase.js +22 -8
- package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
- package/dist/holmes/guardrail/powershell-shell.js +801 -0
- package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
- package/dist/holmes/guardrail/refusal-codes.js +141 -0
- package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
- package/dist/holmes/guardrail/risk-classifier.js +242 -26
- package/dist/holmes/guardrail/risk-types.d.ts +15 -0
- package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
- package/dist/holmes/guardrail/run-plan-scope.js +155 -0
- package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
- package/dist/holmes/guardrail/run-refusals.js +348 -0
- package/dist/holmes/guardrail/run-stages.d.ts +67 -0
- package/dist/holmes/guardrail/run-stages.js +188 -0
- package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
- package/dist/holmes/guardrail/scope-judgment.js +8 -10
- package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
- package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
- package/dist/holmes/guardrail/shell-words.js +7 -7
- package/dist/holmes/guardrail/write-target.d.ts +31 -2
- package/dist/holmes/guardrail/write-target.js +118 -16
- package/dist/holmes/hooks/adapters/antigravity.d.ts +1 -1
- package/dist/holmes/hooks/adapters/antigravity.js +6 -2
- package/dist/holmes/hooks/pre-tool-use.d.ts +55 -2
- package/dist/holmes/hooks/pre-tool-use.js +749 -89
- package/dist/holmes/hooks/session-start.js +5 -3
- package/dist/holmes/hooks/stop.d.ts +32 -0
- package/dist/holmes/hooks/stop.js +129 -4
- package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
- package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
- package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
- package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
- package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
- package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
- package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
- package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
- package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
- package/dist/holmes/mcp/handlers.d.ts +2 -3
- package/dist/holmes/mcp/handlers.js +22 -2
- package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
- package/dist/holmes/mcp/harness-attestation.js +3 -1
- package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
- package/dist/holmes/mcp/operator-recovery.js +4 -3
- package/dist/holmes/mcp/server.js +9 -0
- package/dist/holmes/mcp/tool-schemas.js +6 -3
- package/dist/holmes/project/root.js +6 -1
- package/dist/holmes/project/run-records.d.ts +17 -0
- package/dist/holmes/project/run-records.js +126 -0
- package/dist/holmes/review/mrp.d.ts +35 -0
- package/dist/holmes/review/mrp.js +119 -0
- package/dist/holmes/review/verdicts.d.ts +117 -0
- package/dist/holmes/review/verdicts.js +345 -0
- package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
- package/dist/holmes/semantic/cloud-usage.js +106 -0
- package/dist/holmes/semantic/embedder.d.ts +15 -6
- package/dist/holmes/semantic/embedder.js +84 -3
- package/dist/holmes/semantic/local-model.d.ts +21 -2
- package/dist/holmes/semantic/local-model.js +14 -3
- package/dist/holmes/semantic/tier.d.ts +25 -0
- package/dist/holmes/semantic/tier.js +86 -1
- package/dist/holmes/semantic/vector-cache.d.ts +1 -0
- package/dist/holmes/semantic/vector-cache.js +4 -1
- package/dist/holmes/spec/approval-blockers.d.ts +11 -1
- package/dist/holmes/spec/approval-blockers.js +70 -2
- package/dist/holmes/spec/renumber.d.ts +1 -1
- package/dist/holmes/spec/renumber.js +5 -2
- package/dist/holmes/spec/transition-policy.d.ts +5 -7
- package/dist/holmes/spec/transition-policy.js +17 -2
- package/package.json +1 -1
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.LOCAL_WARM_CHECKPOINT = void 0;
|
|
4
|
+
exports.chunkByTokens = chunkByTokens;
|
|
4
5
|
exports.makeTierEmbedder = makeTierEmbedder;
|
|
5
|
-
// @implements A-SPEC-591
|
|
6
|
+
// @implements A-SPEC-591, A-SPEC-719.14, A-SPEC-719.15, A-SPEC-476.5
|
|
6
7
|
// @implements A-SPEC-719.3
|
|
7
8
|
// @implements A-SPEC-478
|
|
8
9
|
/**
|
|
@@ -24,6 +25,7 @@ exports.makeTierEmbedder = makeTierEmbedder;
|
|
|
24
25
|
*/
|
|
25
26
|
const tier_1 = require("./tier");
|
|
26
27
|
const credentials_1 = require("./credentials");
|
|
28
|
+
const cloud_usage_1 = require("./cloud-usage");
|
|
27
29
|
const local_model_1 = require("./local-model");
|
|
28
30
|
const CLOUD_BATCH = 25;
|
|
29
31
|
/**
|
|
@@ -32,6 +34,52 @@ const CLOUD_BATCH = 25;
|
|
|
32
34
|
* documents for up to 1 h 53 min, and any worker ended before its last text landed nothing.
|
|
33
35
|
*/
|
|
34
36
|
exports.LOCAL_WARM_CHECKPOINT = 25;
|
|
37
|
+
/**
|
|
38
|
+
* @implements A-SPEC-719.14 — one macrotask turn. The local runtime's inference settles without the event loop ever
|
|
39
|
+
* reaching its timer phase, so a warm that only awaits it is one uninterrupted job: measured 2026-10-18 on Windows, a
|
|
40
|
+
* 20 s timer had not fired after 100 s of BGE-M3 warm, and six refresh children outlived their deadline and their
|
|
41
|
+
* supersede watch (A-SPEC-719.1, 719.2). With this turn after each inference the same timer fired at 20.1 s.
|
|
42
|
+
*/
|
|
43
|
+
const yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
|
|
44
|
+
/**
|
|
45
|
+
* The chunks a text is embedded as, each at most `budget` tokens where a separator allows it.
|
|
46
|
+
*
|
|
47
|
+
* @implements A-SPEC-719.15
|
|
48
|
+
* A blank line first, then a line break, then a space: adjacent segments are joined greedily while the joined text stays
|
|
49
|
+
* within the budget, and a segment that does not fit is split by the next separator. A segment with no separator left
|
|
50
|
+
* is kept whole — the tokenizer's cap (local-model.ts) bounds what the model is given. Pure.
|
|
51
|
+
*/
|
|
52
|
+
function chunkByTokens(text, budget, count) {
|
|
53
|
+
const split = (t, separators) => {
|
|
54
|
+
if (count(t) <= budget || separators.length === 0)
|
|
55
|
+
return [t];
|
|
56
|
+
const [sep, ...rest] = separators;
|
|
57
|
+
const parts = t.split(sep);
|
|
58
|
+
if (parts.length === 1)
|
|
59
|
+
return split(t, rest);
|
|
60
|
+
const out = [];
|
|
61
|
+
let current = '';
|
|
62
|
+
for (const part of parts) {
|
|
63
|
+
const joined = current === '' ? part : current + sep + part;
|
|
64
|
+
if (count(joined) <= budget) {
|
|
65
|
+
current = joined;
|
|
66
|
+
continue;
|
|
67
|
+
}
|
|
68
|
+
if (current !== '')
|
|
69
|
+
out.push(current);
|
|
70
|
+
if (count(part) <= budget)
|
|
71
|
+
current = part;
|
|
72
|
+
else {
|
|
73
|
+
out.push(...split(part, rest));
|
|
74
|
+
current = '';
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
if (current !== '')
|
|
78
|
+
out.push(current);
|
|
79
|
+
return out;
|
|
80
|
+
};
|
|
81
|
+
return split(text, ['\n\n', '\n', ' ']);
|
|
82
|
+
}
|
|
35
83
|
const CLOUD_BACKOFF_MS = 30_000;
|
|
36
84
|
function makeTierEmbedder(tier, cache, opts = {}) {
|
|
37
85
|
if (tier.tier === 'none' || tier.model === undefined)
|
|
@@ -40,6 +88,7 @@ function makeTierEmbedder(tier, cache, opts = {}) {
|
|
|
40
88
|
if (tier.tier === 'local') {
|
|
41
89
|
const tag = `${model}@${local_model_1.LOCAL_REVISION}-q8-${(0, tier_1.POOLING_OF)(model)}`;
|
|
42
90
|
let pipe = null;
|
|
91
|
+
const budget = opts.tokenBudget ?? local_model_1.LOCAL_EMBED_TOKEN_BUDGET;
|
|
43
92
|
const load = () => {
|
|
44
93
|
if (pipe === null) {
|
|
45
94
|
pipe = (opts.pipelineLoader ?? local_model_1.loadLocalPipeline)(model);
|
|
@@ -49,7 +98,27 @@ function makeTierEmbedder(tier, cache, opts = {}) {
|
|
|
49
98
|
const embed = async (text) => {
|
|
50
99
|
try {
|
|
51
100
|
const p = await load();
|
|
52
|
-
|
|
101
|
+
const options = { pooling: (0, tier_1.POOLING_OF)(model), normalize: true };
|
|
102
|
+
const tokenizer = p.tokenizer;
|
|
103
|
+
// A text within the budget — and any text, for a pipeline that exposes no tokenizer — is one call, as before.
|
|
104
|
+
if (typeof tokenizer !== 'function')
|
|
105
|
+
return Array.from((await p(text, options)).data);
|
|
106
|
+
const count = (t) => tokenizer(t, { truncation: false }).input_ids.size;
|
|
107
|
+
if (count(text) <= budget)
|
|
108
|
+
return Array.from((await p(text, options)).data);
|
|
109
|
+
// @implements A-SPEC-719.15 — longer: chunks within the budget, pooled by the tokens each one gave the model.
|
|
110
|
+
let pooled = null;
|
|
111
|
+
for (const chunk of chunkByTokens(text, budget, count)) {
|
|
112
|
+
const v = (await p(chunk, options)).data;
|
|
113
|
+
const weight = Math.min(count(chunk), budget);
|
|
114
|
+
if (pooled === null)
|
|
115
|
+
pooled = new Array(v.length).fill(0);
|
|
116
|
+
for (let i = 0; i < v.length; i++)
|
|
117
|
+
pooled[i] += v[i] * weight;
|
|
118
|
+
await yieldToEventLoop(); // A-SPEC-719.14 — a long text cannot starve the child's timers either
|
|
119
|
+
}
|
|
120
|
+
const norm = Math.hypot(...pooled);
|
|
121
|
+
return pooled.map((x) => x / norm);
|
|
53
122
|
}
|
|
54
123
|
catch {
|
|
55
124
|
pipe = null;
|
|
@@ -86,6 +155,7 @@ function makeTierEmbedder(tier, cache, opts = {}) {
|
|
|
86
155
|
if (computed % exports.LOCAL_WARM_CHECKPOINT === 0)
|
|
87
156
|
cache.flush(); // A-SPEC-719.3 — an ended worker keeps this much
|
|
88
157
|
}
|
|
158
|
+
await yieldToEventLoop(); // A-SPEC-719.14 — after every attempted inference, failed ones included
|
|
89
159
|
}
|
|
90
160
|
cache.flush();
|
|
91
161
|
return { computed, cached };
|
|
@@ -99,12 +169,23 @@ function makeTierEmbedder(tier, cache, opts = {}) {
|
|
|
99
169
|
return null;
|
|
100
170
|
const f = opts.fetchImpl ?? fetch;
|
|
101
171
|
const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
|
|
172
|
+
// @implements A-SPEC-476.5 — every HTTP request is counted (retries included); never the key, never a text.
|
|
173
|
+
const usage = opts.usage ?? ((n, outcome) => (0, cloud_usage_1.recordCloudRequest)(cache.root, n, outcome));
|
|
102
174
|
const callBatch = async (texts, taskType) => {
|
|
103
175
|
const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:batchEmbedContents?key=${key}`;
|
|
104
176
|
const body = JSON.stringify({ requests: texts.map((t) => ({ model: `models/${model}`, content: { parts: [{ text: t }] }, taskType })) });
|
|
105
177
|
for (let attempt = 0; attempt < 5; attempt++) {
|
|
178
|
+
let res;
|
|
179
|
+
try {
|
|
180
|
+
res = await f(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body });
|
|
181
|
+
}
|
|
182
|
+
catch {
|
|
183
|
+
usage(texts.length, 'network');
|
|
184
|
+
opts.log?.('cloud embed network error');
|
|
185
|
+
return null;
|
|
186
|
+
}
|
|
187
|
+
usage(texts.length, res.ok ? 'ok' : `http-${res.status}`);
|
|
106
188
|
try {
|
|
107
|
-
const res = await f(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body });
|
|
108
189
|
if (res.status === 429 || res.status >= 500) {
|
|
109
190
|
opts.log?.(`cloud embed backoff (HTTP ${res.status})`);
|
|
110
191
|
await sleep(CLOUD_BACKOFF_MS);
|
|
@@ -2,12 +2,31 @@ import { spawnSync } from 'node:child_process';
|
|
|
2
2
|
import { LOCAL_REVISION, modelCacheDir, modelCacheReady, readLocalModelReadiness } from './model-cache';
|
|
3
3
|
export { modelCacheDir, modelCacheReady, readLocalModelReadiness };
|
|
4
4
|
export { LOCAL_REVISION };
|
|
5
|
-
|
|
5
|
+
/** The runtime's tokenizer, as far as Holmes reads it: a token count, and the length it truncates at. */
|
|
6
|
+
export interface LocalTokenizer {
|
|
7
|
+
(text: string, options?: {
|
|
8
|
+
truncation?: boolean;
|
|
9
|
+
}): {
|
|
10
|
+
input_ids: {
|
|
11
|
+
size: number;
|
|
12
|
+
};
|
|
13
|
+
};
|
|
14
|
+
model_max_length?: number;
|
|
15
|
+
}
|
|
16
|
+
export type Pipeline = ((text: string, options: {
|
|
6
17
|
pooling: string;
|
|
7
18
|
normalize: boolean;
|
|
8
19
|
}) => Promise<{
|
|
9
20
|
data: Float32Array;
|
|
10
|
-
}
|
|
21
|
+
}>) & {
|
|
22
|
+
tokenizer?: LocalTokenizer;
|
|
23
|
+
};
|
|
24
|
+
/**
|
|
25
|
+
* @implements A-SPEC-719.15 — the most tokens one local inference is given. BGE-M3's memory grows steeply with input
|
|
26
|
+
* length — measured 2026-10-18 on Windows (16 GB): 2.83 GB at 1,024 tokens, 3.75 GB at 2,048, past 9.19 GB at 4,096 —
|
|
27
|
+
* and requirement texts reach 28,946 tokens. A longer text is embedded in chunks of at most this many (embedder.ts).
|
|
28
|
+
*/
|
|
29
|
+
export declare const LOCAL_EMBED_TOKEN_BUDGET = 2048;
|
|
11
30
|
interface Runtime {
|
|
12
31
|
pipeline(task: string, model: string, options: Record<string, unknown>): Promise<Pipeline>;
|
|
13
32
|
}
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.LOCAL_REVISION = exports.readLocalModelReadiness = exports.modelCacheReady = exports.modelCacheDir = void 0;
|
|
3
|
+
exports.LOCAL_EMBED_TOKEN_BUDGET = exports.LOCAL_REVISION = exports.readLocalModelReadiness = exports.modelCacheReady = exports.modelCacheDir = void 0;
|
|
4
4
|
exports.loadLocalPipeline = loadLocalPipeline;
|
|
5
5
|
exports.verifyLocalModel = verifyLocalModel;
|
|
6
6
|
exports.runModelSetup = runModelSetup;
|
|
7
|
-
// @implements A-SPEC-591, A-SPEC-712
|
|
7
|
+
// @implements A-SPEC-591, A-SPEC-712, A-SPEC-719.15
|
|
8
8
|
const node_child_process_1 = require("node:child_process");
|
|
9
9
|
const tier_1 = require("./tier");
|
|
10
10
|
const model_cache_1 = require("./model-cache");
|
|
@@ -12,6 +12,12 @@ Object.defineProperty(exports, "LOCAL_REVISION", { enumerable: true, get: functi
|
|
|
12
12
|
Object.defineProperty(exports, "modelCacheDir", { enumerable: true, get: function () { return model_cache_1.modelCacheDir; } });
|
|
13
13
|
Object.defineProperty(exports, "modelCacheReady", { enumerable: true, get: function () { return model_cache_1.modelCacheReady; } });
|
|
14
14
|
Object.defineProperty(exports, "readLocalModelReadiness", { enumerable: true, get: function () { return model_cache_1.readLocalModelReadiness; } });
|
|
15
|
+
/**
|
|
16
|
+
* @implements A-SPEC-719.15 — the most tokens one local inference is given. BGE-M3's memory grows steeply with input
|
|
17
|
+
* length — measured 2026-10-18 on Windows (16 GB): 2.83 GB at 1,024 tokens, 3.75 GB at 2,048, past 9.19 GB at 4,096 —
|
|
18
|
+
* and requirement texts reach 28,946 tokens. A longer text is embedded in chunks of at most this many (embedder.ts).
|
|
19
|
+
*/
|
|
20
|
+
exports.LOCAL_EMBED_TOKEN_BUDGET = 2048;
|
|
15
21
|
// TypeScript's CommonJS transform rewrites import() into require(), which cannot load this ESM
|
|
16
22
|
// dependency on supported Node 20 versions. Preserve native dynamic import without shell code.
|
|
17
23
|
const importRuntime = new Function('return import("@xenova/transformers")');
|
|
@@ -33,7 +39,12 @@ async function loadLocalPipeline(model = tier_1.LOCAL_MODEL, options = {}) {
|
|
|
33
39
|
revision: model === tier_1.LOCAL_MODEL ? model_cache_1.LOCAL_REVISION : 'main',
|
|
34
40
|
cache_dir: cacheDir,
|
|
35
41
|
local_files_only: !options.download,
|
|
36
|
-
})).
|
|
42
|
+
})).then((pipe) => {
|
|
43
|
+
// @implements A-SPEC-719.15 — the tokenizer truncates at the budget: the bound for a piece no separator can split.
|
|
44
|
+
if (pipe.tokenizer)
|
|
45
|
+
pipe.tokenizer.model_max_length = exports.LOCAL_EMBED_TOKEN_BUDGET;
|
|
46
|
+
return pipe;
|
|
47
|
+
}).catch(error => { cache.delete(key); throw error; });
|
|
37
48
|
cache.set(key, pending);
|
|
38
49
|
return pending;
|
|
39
50
|
}
|
|
@@ -31,7 +31,19 @@ export interface SemanticTier {
|
|
|
31
31
|
localRuntimePresent?: boolean;
|
|
32
32
|
/** Why local BGE-M3 was not activated, when readiness was observed. */
|
|
33
33
|
localState?: LocalModelReadiness['state'];
|
|
34
|
+
/**
|
|
35
|
+
* @implements A-SPEC-476.1 — present when the project's `semantic.maxTier` lowered the tier or could not be read:
|
|
36
|
+
* the cap that applied, the source of a key it withheld (never the value), and the read problem if any.
|
|
37
|
+
*/
|
|
38
|
+
cap?: {
|
|
39
|
+
maxTier: 'local' | 'none';
|
|
40
|
+
keyWithheld?: KeySource;
|
|
41
|
+
problem?: SemanticCapProblem;
|
|
42
|
+
};
|
|
34
43
|
}
|
|
44
|
+
/** @implements A-SPEC-476.1 — the project cap: `cloud` is no cap. */
|
|
45
|
+
export type SemanticCap = 'cloud' | 'local' | 'none';
|
|
46
|
+
export type SemanticCapProblem = 'unreadable' | 'malformed';
|
|
35
47
|
/**
|
|
36
48
|
* Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
|
|
37
49
|
* S-491 instrument accident — a 4.4x quality collapse (0.150 vs 0.667 recall) that read as a
|
|
@@ -46,3 +58,16 @@ export declare function resolveSemanticTier(opts?: {
|
|
|
46
58
|
localReadiness?: LocalModelReadiness;
|
|
47
59
|
credentials?: CredentialOpts;
|
|
48
60
|
}): SemanticTier;
|
|
61
|
+
/**
|
|
62
|
+
* @implements A-SPEC-476.1 — the project's cap, read on its own. `loadConfig` falls back to the default config on a broken
|
|
63
|
+
* file, and the default has no cap — cloud; a cap that cannot be read must fail toward none instead.
|
|
64
|
+
*/
|
|
65
|
+
export declare function readSemanticCap(root: string): {
|
|
66
|
+
maxTier: SemanticCap;
|
|
67
|
+
problem?: SemanticCapProblem;
|
|
68
|
+
};
|
|
69
|
+
/**
|
|
70
|
+
* @implements A-SPEC-476.1 — the tier every semantic path uses: the machine's tier, lowered by the project's cap. The cap
|
|
71
|
+
* only lowers — no value of it produces cloud without a key in the chain — and a key it withholds is named by source.
|
|
72
|
+
*/
|
|
73
|
+
export declare function resolveProjectSemanticTier(root: string, opts?: Parameters<typeof resolveSemanticTier>[0]): SemanticTier;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
-
// @implements A-SPEC-476, A-SPEC-712
|
|
2
|
+
// @implements A-SPEC-476, A-SPEC-712, A-SPEC-476.1
|
|
3
3
|
/**
|
|
4
4
|
* The semantic layer's tier structure — the owner's two-lever design made a contract:
|
|
5
5
|
* maximize what the harness can do WITHOUT egress (a local model), and let an explicit opt-in
|
|
@@ -12,15 +12,53 @@
|
|
|
12
12
|
* Consent model: setting GEMINI_API_KEY IS the opt-in. The tier resolver never probes the
|
|
13
13
|
* network; presence signals only, so doctor can call it offline.
|
|
14
14
|
*/
|
|
15
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
16
|
+
if (k2 === undefined) k2 = k;
|
|
17
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
18
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
19
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
20
|
+
}
|
|
21
|
+
Object.defineProperty(o, k2, desc);
|
|
22
|
+
}) : (function(o, m, k, k2) {
|
|
23
|
+
if (k2 === undefined) k2 = k;
|
|
24
|
+
o[k2] = m[k];
|
|
25
|
+
}));
|
|
26
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
27
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
28
|
+
}) : function(o, v) {
|
|
29
|
+
o["default"] = v;
|
|
30
|
+
});
|
|
31
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
32
|
+
var ownKeys = function(o) {
|
|
33
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
34
|
+
var ar = [];
|
|
35
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
36
|
+
return ar;
|
|
37
|
+
};
|
|
38
|
+
return ownKeys(o);
|
|
39
|
+
};
|
|
40
|
+
return function (mod) {
|
|
41
|
+
if (mod && mod.__esModule) return mod;
|
|
42
|
+
var result = {};
|
|
43
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
44
|
+
__setModuleDefault(result, mod);
|
|
45
|
+
return result;
|
|
46
|
+
};
|
|
47
|
+
})();
|
|
15
48
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
16
49
|
exports.CLOUD_MODEL = exports.LOCAL_MODEL = void 0;
|
|
17
50
|
exports.POOLING_OF = POOLING_OF;
|
|
18
51
|
exports.resolveSemanticTier = resolveSemanticTier;
|
|
52
|
+
exports.readSemanticCap = readSemanticCap;
|
|
53
|
+
exports.resolveProjectSemanticTier = resolveProjectSemanticTier;
|
|
54
|
+
const fs = __importStar(require("node:fs"));
|
|
55
|
+
const path = __importStar(require("node:path"));
|
|
19
56
|
const credentials_1 = require("./credentials");
|
|
20
57
|
const model_cache_1 = require("./model-cache");
|
|
21
58
|
Object.defineProperty(exports, "LOCAL_MODEL", { enumerable: true, get: function () { return model_cache_1.LOCAL_MODEL; } });
|
|
22
59
|
/** The opt-in cloud tier's model (S-491 four-arm winner). */
|
|
23
60
|
exports.CLOUD_MODEL = 'gemini-embedding-001';
|
|
61
|
+
const CAPS = ['cloud', 'local', 'none'];
|
|
24
62
|
/**
|
|
25
63
|
* Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
|
|
26
64
|
* S-491 instrument accident — a 4.4x quality collapse (0.150 vs 0.667 recall) that read as a
|
|
@@ -47,6 +85,9 @@ function resolveSemanticTier(opts = {}) {
|
|
|
47
85
|
if (found !== null) {
|
|
48
86
|
return { tier: 'cloud', model: exports.CLOUD_MODEL, egress: true, keySource: found.source };
|
|
49
87
|
}
|
|
88
|
+
return localOrNone(opts);
|
|
89
|
+
}
|
|
90
|
+
function localOrNone(opts) {
|
|
50
91
|
// @implements A-SPEC-594 — availability is a CONJUNCTION. Once @xenova/transformers became a
|
|
51
92
|
// required dependency, `localModulePresent()` answered true for every install and stopped
|
|
52
93
|
// discriminating; a resolvable runtime with no model produces no embedding at all. Wiring
|
|
@@ -59,3 +100,47 @@ function resolveSemanticTier(opts = {}) {
|
|
|
59
100
|
return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}),
|
|
60
101
|
...(hasModule && observed && !observed.ready ? { localState: observed.state } : {}) };
|
|
61
102
|
}
|
|
103
|
+
/**
|
|
104
|
+
* @implements A-SPEC-476.1 — the project's cap, read on its own. `loadConfig` falls back to the default config on a broken
|
|
105
|
+
* file, and the default has no cap — cloud; a cap that cannot be read must fail toward none instead.
|
|
106
|
+
*/
|
|
107
|
+
function readSemanticCap(root) {
|
|
108
|
+
const f = path.join(root, 'ax.config.json');
|
|
109
|
+
let text;
|
|
110
|
+
try {
|
|
111
|
+
text = fs.readFileSync(f, 'utf8');
|
|
112
|
+
}
|
|
113
|
+
catch (e) {
|
|
114
|
+
return e.code === 'ENOENT' ? { maxTier: 'cloud' } : { maxTier: 'none', problem: 'unreadable' };
|
|
115
|
+
}
|
|
116
|
+
let parsed;
|
|
117
|
+
try {
|
|
118
|
+
parsed = JSON.parse(text);
|
|
119
|
+
}
|
|
120
|
+
catch {
|
|
121
|
+
return { maxTier: 'none', problem: 'unreadable' };
|
|
122
|
+
}
|
|
123
|
+
if (parsed === null || typeof parsed !== 'object' || !('semantic' in parsed))
|
|
124
|
+
return { maxTier: 'cloud' };
|
|
125
|
+
const semantic = parsed.semantic;
|
|
126
|
+
if (semantic === null || typeof semantic !== 'object' || Array.isArray(semantic))
|
|
127
|
+
return { maxTier: 'none', problem: 'malformed' };
|
|
128
|
+
if (!('maxTier' in semantic))
|
|
129
|
+
return { maxTier: 'cloud' };
|
|
130
|
+
const declared = semantic.maxTier;
|
|
131
|
+
return CAPS.includes(declared) ? { maxTier: declared } : { maxTier: 'none', problem: 'malformed' };
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* @implements A-SPEC-476.1 — the tier every semantic path uses: the machine's tier, lowered by the project's cap. The cap
|
|
135
|
+
* only lowers — no value of it produces cloud without a key in the chain — and a key it withholds is named by source.
|
|
136
|
+
*/
|
|
137
|
+
function resolveProjectSemanticTier(root, opts = {}) {
|
|
138
|
+
const cap = readSemanticCap(root);
|
|
139
|
+
if (cap.maxTier === 'cloud')
|
|
140
|
+
return resolveSemanticTier(opts);
|
|
141
|
+
const found = (0, credentials_1.resolveSemanticKey)({ env: opts.env ?? process.env, ...opts.credentials });
|
|
142
|
+
const capInfo = { maxTier: cap.maxTier, ...(found !== null ? { keyWithheld: found.source } : {}), ...(cap.problem ? { problem: cap.problem } : {}) };
|
|
143
|
+
if (cap.maxTier === 'none')
|
|
144
|
+
return { tier: 'none', egress: false, cap: capInfo };
|
|
145
|
+
return { ...localOrNone(opts), cap: capInfo };
|
|
146
|
+
}
|
|
@@ -3,6 +3,7 @@ export declare const COMPACTION_THRESHOLD = 16;
|
|
|
3
3
|
/** Age after which a compaction lock or an abandoned `.tmp` is considered orphaned by a dead writer. */
|
|
4
4
|
export declare const STALE_MS: number;
|
|
5
5
|
export declare class VectorCache {
|
|
6
|
+
readonly root: string;
|
|
6
7
|
private readonly file;
|
|
7
8
|
private readonly dir;
|
|
8
9
|
private readonly lock;
|
|
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.VectorCache = exports.STALE_MS = exports.COMPACTION_THRESHOLD = void 0;
|
|
37
|
-
// @implements A-SPEC-476
|
|
37
|
+
// @implements A-SPEC-476, A-SPEC-476.5
|
|
38
38
|
// @implements A-SPEC-630
|
|
39
39
|
/**
|
|
40
40
|
* Content-addressed vector cache: never compute the same embedding twice, never serve a stale
|
|
@@ -126,12 +126,15 @@ function segmentName() {
|
|
|
126
126
|
return `${String(lastStamp).padStart(15, '0')}-${String(process.pid).padStart(8, '0')}-${(0, node_crypto_1.randomBytes)(4).toString('hex')}.json`;
|
|
127
127
|
}
|
|
128
128
|
class VectorCache {
|
|
129
|
+
root;
|
|
129
130
|
file;
|
|
130
131
|
dir;
|
|
131
132
|
lock;
|
|
132
133
|
store = null;
|
|
133
134
|
dirty = new Set();
|
|
135
|
+
// @implements A-SPEC-476.5 — the project the cache serves; the cloud embedder counts its requests against it.
|
|
134
136
|
constructor(root) {
|
|
137
|
+
this.root = root;
|
|
135
138
|
this.file = path.join(root, FILE);
|
|
136
139
|
this.dir = path.join(root, SEGMENT_DIR);
|
|
137
140
|
this.lock = path.join(this.dir, LOCK_DIR);
|
|
@@ -26,6 +26,7 @@ import { Spec } from './spec-parser';
|
|
|
26
26
|
* ("남아 있는 TODO 주석을 제거한다"), and every one carries real content beside it.
|
|
27
27
|
*/
|
|
28
28
|
export declare function placeholderSections(spec: Spec): string[];
|
|
29
|
+
export declare function scaffoldSections(spec: Spec): string[];
|
|
29
30
|
/**
|
|
30
31
|
* Codes that `validateSpec` reports but approval itself supplies, so they are not blockers.
|
|
31
32
|
* Exported because `spec_approve` filters by the same set — two hand-maintained lists were how the
|
|
@@ -44,6 +45,13 @@ export declare const placeholderMessage: (sections: string[]) => string;
|
|
|
44
45
|
/** The one wording for an unsealed parent. Shared so a second, degraded copy cannot appear. */
|
|
45
46
|
export declare const unsealedParentMessage: (pid: string) => string;
|
|
46
47
|
export declare function parentBlockers(spec: Spec, resolve: (id: string) => Spec | null): string[];
|
|
48
|
+
/**
|
|
49
|
+
* @implements A-SPEC-182.3 — the chain above the direct parents (which `parentBlockers` judges): one message per
|
|
50
|
+
* ancestor that is not approved. A-SPEC-102.2–102.6 were sealed under the approved H-SPEC-102 while REQ-102 was draft.
|
|
51
|
+
* Cycles end; depth is bounded. A missing direct parent is validateSpec's finding; a missing ancestor above it is one
|
|
52
|
+
* here (@implements A-SPEC-182.4 — skipping it sealed a chain whose top no spec carries).
|
|
53
|
+
*/
|
|
54
|
+
export declare function ancestorBlockers(spec: Spec, resolve: (id: string) => Spec | null): string[];
|
|
47
55
|
/**
|
|
48
56
|
* Every reason `spec` cannot be approved right now. Empty means nothing is in the way.
|
|
49
57
|
*
|
|
@@ -51,7 +59,9 @@ export declare function parentBlockers(spec: Spec, resolve: (id: string) => Spec
|
|
|
51
59
|
* placeholders. Pure — it reads the spec objects it is handed and touches no filesystem, because
|
|
52
60
|
* the gate calls it from a PreToolUse hook on every tool call.
|
|
53
61
|
*/
|
|
54
|
-
export declare function approvalBlockers(spec: Spec, resolve: (id: string) => Spec | null
|
|
62
|
+
export declare function approvalBlockers(spec: Spec, resolve: (id: string) => Spec | null, opts?: {
|
|
63
|
+
scaffold?: boolean;
|
|
64
|
+
}): string[];
|
|
55
65
|
/** The separator between one spec's blockers. Shared so nothing re-splits on a guessed delimiter. */
|
|
56
66
|
export declare const BLOCKER_SEP = "; ";
|
|
57
67
|
/**
|
|
@@ -2,11 +2,13 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.blockerClause = exports.BLOCKER_SEP = exports.unsealedParentMessage = exports.placeholderMessage = exports.SUPPLIED_BY_APPROVAL = void 0;
|
|
4
4
|
exports.placeholderSections = placeholderSections;
|
|
5
|
+
exports.scaffoldSections = scaffoldSections;
|
|
5
6
|
exports.parentBlockers = parentBlockers;
|
|
7
|
+
exports.ancestorBlockers = ancestorBlockers;
|
|
6
8
|
exports.approvalBlockers = approvalBlockers;
|
|
7
9
|
exports.blockerSummary = blockerSummary;
|
|
8
10
|
exports.unactionableCriteriaBlocker = unactionableCriteriaBlocker;
|
|
9
|
-
// @implements A-SPEC-182
|
|
11
|
+
// @implements A-SPEC-182, A-SPEC-182.3, A-SPEC-182.4
|
|
10
12
|
const acceptance_quality_1 = require("./acceptance-quality");
|
|
11
13
|
const validator_1 = require("./validator");
|
|
12
14
|
const breaking_change_1 = require("./breaking-change");
|
|
@@ -150,6 +152,31 @@ function placeholderSections(spec) {
|
|
|
150
152
|
}
|
|
151
153
|
return out;
|
|
152
154
|
}
|
|
155
|
+
/**
|
|
156
|
+
* @implements A-SPEC-182.1 — the bodies `spec_slice_init` writes. They are prose, not `TODO`, so `placeholderSections`
|
|
157
|
+
* never saw them: measured 2026-10-18, 421 approved specs here and 303 in a jarvis copy still carried one. A section
|
|
158
|
+
* counts only when its WHOLE body (whitespace normalised) is the scaffold; Open Questions, Assumptions, Non-Functional
|
|
159
|
+
* and Scope are left out because their scaffold ("None.") can be a real answer.
|
|
160
|
+
*/
|
|
161
|
+
const SCAFFOLD_BODIES = {
|
|
162
|
+
'Intent': /^Implement .+\.$/,
|
|
163
|
+
'Design Overview': /^High level design for .+\.$/,
|
|
164
|
+
'Acceptance Criteria': /^- Code written and tests passing\.$/,
|
|
165
|
+
'Component Design': /^1\. Target Component: - Modifies .+\.$/,
|
|
166
|
+
'Inputs / Outputs': /^- Inputs: Tool calls \/ developer modifications\. - Outputs: Working implementation\.$/,
|
|
167
|
+
'Behavior': /^- Implements desired behavior cleanly\.$/,
|
|
168
|
+
'Test Points': /^- Unit tests in test suite\.$/,
|
|
169
|
+
'Done When': /^- All tests pass 100%\.$/,
|
|
170
|
+
'Normal Cases': /^- Given valid inputs When operation is performed Then correct behavior is observed$/,
|
|
171
|
+
'Corner Cases': /^- Given edge cases When operation is performed Then system handles gracefully$/,
|
|
172
|
+
'Negative Cases': /^- Given invalid inputs When operation is performed Then appropriate error is returned$/,
|
|
173
|
+
'Boundary Cases': /^- Given boundary conditions When operation is performed Then boundary limits are respected$/,
|
|
174
|
+
};
|
|
175
|
+
function scaffoldSections(spec) {
|
|
176
|
+
return Object.entries(spec.sections ?? {})
|
|
177
|
+
.filter(([name, body]) => SCAFFOLD_BODIES[name]?.test(String(body ?? '').replace(/\s+/g, ' ').trim()))
|
|
178
|
+
.map(([name]) => name);
|
|
179
|
+
}
|
|
153
180
|
/**
|
|
154
181
|
* Codes that `validateSpec` reports but approval itself supplies, so they are not blockers.
|
|
155
182
|
* Exported because `spec_approve` filters by the same set — two hand-maintained lists were how the
|
|
@@ -185,6 +212,38 @@ function parentBlockers(spec, resolve) {
|
|
|
185
212
|
}
|
|
186
213
|
return out;
|
|
187
214
|
}
|
|
215
|
+
/**
|
|
216
|
+
* @implements A-SPEC-182.3 — the chain above the direct parents (which `parentBlockers` judges): one message per
|
|
217
|
+
* ancestor that is not approved. A-SPEC-102.2–102.6 were sealed under the approved H-SPEC-102 while REQ-102 was draft.
|
|
218
|
+
* Cycles end; depth is bounded. A missing direct parent is validateSpec's finding; a missing ancestor above it is one
|
|
219
|
+
* here (@implements A-SPEC-182.4 — skipping it sealed a chain whose top no spec carries).
|
|
220
|
+
*/
|
|
221
|
+
function ancestorBlockers(spec, resolve) {
|
|
222
|
+
const out = [];
|
|
223
|
+
const seen = new Set([spec.id]);
|
|
224
|
+
const walk = (id, via, namedBy, depth) => {
|
|
225
|
+
if (depth > 16 || seen.has(id))
|
|
226
|
+
return;
|
|
227
|
+
seen.add(id);
|
|
228
|
+
const s = resolve(id);
|
|
229
|
+
if (!s) {
|
|
230
|
+
out.push(`ancestor ${id} (named by ${namedBy}) cannot be found — the chain is justified only up to ${namedBy}; restore ${id} or re-parent ${namedBy}`);
|
|
231
|
+
return;
|
|
232
|
+
}
|
|
233
|
+
if (s.status !== 'approved') {
|
|
234
|
+
out.push(`ancestor ${s.id} is ${s.status} (via ${via}) — the chain is justified only up to it; seal ${s.id} first`);
|
|
235
|
+
}
|
|
236
|
+
for (const up of s.dependsOn ?? [])
|
|
237
|
+
walk(up, via, s.id, depth + 1);
|
|
238
|
+
};
|
|
239
|
+
for (const pid of spec.dependsOn ?? []) {
|
|
240
|
+
seen.add(pid);
|
|
241
|
+
const parent = resolve(pid);
|
|
242
|
+
for (const up of parent?.dependsOn ?? [])
|
|
243
|
+
walk(up, pid, pid, 1);
|
|
244
|
+
}
|
|
245
|
+
return out;
|
|
246
|
+
}
|
|
188
247
|
/**
|
|
189
248
|
* Every reason `spec` cannot be approved right now. Empty means nothing is in the way.
|
|
190
249
|
*
|
|
@@ -192,7 +251,7 @@ function parentBlockers(spec, resolve) {
|
|
|
192
251
|
* placeholders. Pure — it reads the spec objects it is handed and touches no filesystem, because
|
|
193
252
|
* the gate calls it from a PreToolUse hook on every tool call.
|
|
194
253
|
*/
|
|
195
|
-
function approvalBlockers(spec, resolve) {
|
|
254
|
+
function approvalBlockers(spec, resolve, opts) {
|
|
196
255
|
const out = parentBlockers(spec, resolve);
|
|
197
256
|
// Validate AS IT WILL BE — approved. Approving is what supplies the status and the seals, so the
|
|
198
257
|
// question is what would still block THIS document once approved.
|
|
@@ -216,6 +275,15 @@ function approvalBlockers(spec, resolve) {
|
|
|
216
275
|
if (stubs.length > 0) {
|
|
217
276
|
out.push((0, exports.placeholderMessage)(stubs));
|
|
218
277
|
}
|
|
278
|
+
// @implements A-SPEC-182.1 — the act refuses scaffold bodies; the gate pre-announces it (A-SPEC-182's parity). A sealed
|
|
279
|
+
// spec whose content is unchanged is exempt here as at the act: renumber and integration judge this list (A-SPEC-641),
|
|
280
|
+
// and the 421 legacy seals must still re-seal.
|
|
281
|
+
const seal = (0, spec_digest_1.sealOf)(spec).approvedDigest;
|
|
282
|
+
const unchangedSeal = typeof seal === 'string' && (0, spec_digest_1.specDigest)(spec) === seal;
|
|
283
|
+
// @implements A-SPEC-182.2 — only when the caller judges in a run or under classification.strict.
|
|
284
|
+
const scaffold = !opts?.scaffold || unchangedSeal ? [] : scaffoldSections(spec).filter((s) => !stubs.includes(s));
|
|
285
|
+
if (scaffold.length > 0)
|
|
286
|
+
out.push((0, exports.placeholderMessage)(scaffold));
|
|
219
287
|
return out;
|
|
220
288
|
}
|
|
221
289
|
/** The separator between one spec's blockers. Shared so nothing re-splits on a guessed delimiter. */
|
|
@@ -81,7 +81,7 @@ export interface RenumberPlan {
|
|
|
81
81
|
}[];
|
|
82
82
|
/** Child-first: T -> A -> H -> REQ. Only what a move actually unseals. */
|
|
83
83
|
unsealOrder: string[];
|
|
84
|
-
/** Parent-first: REQ -> H -> A -> T.
|
|
84
|
+
/** Parent-first: REQ -> H -> A -> T. What a move breaks, plus each moved seal the ledger knows only by its old id. */
|
|
85
85
|
approveOrder: string[];
|
|
86
86
|
/** Reported, never rewritten. */
|
|
87
87
|
proseCandidates: {
|
|
@@ -42,7 +42,7 @@ exports.planRenumber = planRenumber;
|
|
|
42
42
|
exports.applyRenumber = applyRenumber;
|
|
43
43
|
exports.readSourcesForRenumber = readSourcesForRenumber;
|
|
44
44
|
exports.readSpecsForRenumber = readSpecsForRenumber;
|
|
45
|
-
// @implements A-SPEC-629.1, A-SPEC-628, A-SPEC-255
|
|
45
|
+
// @implements A-SPEC-629.1, A-SPEC-628, A-SPEC-255, A-SPEC-255.1
|
|
46
46
|
// @implements A-SPEC-640
|
|
47
47
|
/**
|
|
48
48
|
* Renumbering a spec, as a contract instead of a memory exercise.
|
|
@@ -333,7 +333,10 @@ function planRenumber(input) {
|
|
|
333
333
|
const affected = specs.filter((s) => reseal.has(s.file) && (s.status ?? '') === 'approved');
|
|
334
334
|
const byKind = (a, b) => CHILD_FIRST.indexOf(a.type) - CHILD_FIRST.indexOf(b.type);
|
|
335
335
|
plan.unsealOrder = [...affected].sort(byKind).map((s) => s.id);
|
|
336
|
-
|
|
336
|
+
// @implements A-SPEC-255.1 — a surviving seal is not a recorded approval: the ledger holds the approving act under the
|
|
337
|
+
// OLD id, and ART-5 refused REQ-790 after REQ-774 → 790 (measured 2026-10-18). Re-approve it, never unseal it.
|
|
338
|
+
const surviving = family.filter((s) => !reseal.has(s.file) && (s.status ?? '') === 'approved');
|
|
339
|
+
plan.approveOrder = [...affected, ...surviving].sort(byKind).reverse().map((s) => renamed(s.id, oldBase, newBase));
|
|
337
340
|
const idInText = new RegExp(String.raw `(?:REQ|A-SPEC|H-SPEC|C-SPEC|T-SPEC)-${oldBase}(?:\.\d+)?\b`);
|
|
338
341
|
/** A line the tool will NOT rewrite but a human must look at. Anchors are excluded — those move. */
|
|
339
342
|
const scanProse = (file, text, skipFrontmatter) => {
|
|
@@ -12,21 +12,19 @@ export declare function prepareLifecycleSpec(spec: Spec, all: Spec[], operation:
|
|
|
12
12
|
reason?: undefined;
|
|
13
13
|
};
|
|
14
14
|
/** Act-time policy only: callers own authority, version checks, persistence and audit. */
|
|
15
|
-
export declare function prepareApprovedSpec(spec: Spec, specs: Spec[], resolver: (specs: Spec[]) => (id: string) => Spec | null, readFile: (relative: string) => string | null
|
|
15
|
+
export declare function prepareApprovedSpec(spec: Spec, specs: Spec[], resolver: (specs: Spec[]) => (id: string) => Spec | null, readFile: (relative: string) => string | null, opts?: {
|
|
16
|
+
scaffold?: 'refuse' | 'allow';
|
|
17
|
+
ancestors?: 'refuse' | 'allow';
|
|
18
|
+
}): {
|
|
16
19
|
ok: false;
|
|
17
20
|
reason: string;
|
|
18
21
|
findings?: undefined;
|
|
19
|
-
candidate?: undefined;
|
|
20
|
-
digest?: undefined;
|
|
21
|
-
parentDigests?: undefined;
|
|
22
22
|
} | {
|
|
23
23
|
ok: false;
|
|
24
24
|
reason: string;
|
|
25
25
|
findings: import("./validator").Finding[];
|
|
26
|
-
candidate?: undefined;
|
|
27
|
-
digest?: undefined;
|
|
28
|
-
parentDigests?: undefined;
|
|
29
26
|
} | {
|
|
27
|
+
ancestorWarnings?: string[] | undefined;
|
|
30
28
|
ok: true;
|
|
31
29
|
candidate: Spec;
|
|
32
30
|
digest: string;
|
|
@@ -30,7 +30,7 @@ function prepareLifecycleSpec(spec, all, operation, reason) {
|
|
|
30
30
|
return { ok: true, candidate, dependents };
|
|
31
31
|
}
|
|
32
32
|
/** Act-time policy only: callers own authority, version checks, persistence and audit. */
|
|
33
|
-
function prepareApprovedSpec(spec, specs, resolver, readFile) {
|
|
33
|
+
function prepareApprovedSpec(spec, specs, resolver, readFile, opts) {
|
|
34
34
|
// @implements A-SPEC-188 — duplicates make the id ambiguous, for the SPEC and for its
|
|
35
35
|
// PARENTS alike. Round-3 probed the parent half: with a stray duplicate of the parent
|
|
36
36
|
// walking first, the child's parent_digests sealed the stray's (forged) digest — the very
|
|
@@ -57,6 +57,11 @@ function prepareApprovedSpec(spec, specs, resolver, readFile) {
|
|
|
57
57
|
const parentIssues = (0, approval_blockers_1.parentBlockers)(spec, resolver(specs));
|
|
58
58
|
if (parentIssues.length > 0)
|
|
59
59
|
return { ok: false, reason: parentIssues[0] };
|
|
60
|
+
// @implements A-SPEC-182.3 — the chain above the parents: refused when the caller judges in a run or under strict;
|
|
61
|
+
// otherwise (and for renumber and integration, which pass no option) carried back as a warning, as in 0.35.25.
|
|
62
|
+
const ancestorIssues = (0, approval_blockers_1.ancestorBlockers)(spec, resolver(specs));
|
|
63
|
+
if (ancestorIssues.length > 0 && opts?.ancestors === 'refuse')
|
|
64
|
+
return { ok: false, reason: ancestorIssues[0] };
|
|
60
65
|
// Validate AS IT WILL BE — approved. Approval-gated checks (placeholder citations, 4-quadrant
|
|
61
66
|
// GWT) must fire NOW, not one turn after the seal exists.
|
|
62
67
|
const candidate = { ...spec, status: 'approved', frontmatter: { ...spec.frontmatter } };
|
|
@@ -101,6 +106,16 @@ function prepareApprovedSpec(spec, specs, resolver, readFile) {
|
|
|
101
106
|
if (stubs.length > 0) {
|
|
102
107
|
return { ok: false, reason: (0, approval_blockers_1.placeholderMessage)(stubs) };
|
|
103
108
|
}
|
|
109
|
+
// @implements A-SPEC-182.1 — a spec_slice_init scaffold body is a placeholder too. An already-sealed spec whose
|
|
110
|
+
// content is unchanged re-seals as before (renumber, integration): 421 approved specs here still carry one.
|
|
111
|
+
const storedSeal = spec.frontmatter?.approved_digest;
|
|
112
|
+
const unchangedSeal = typeof storedSeal === 'string' && (0, spec_digest_1.specDigest)(spec) === storedSeal;
|
|
113
|
+
// @implements A-SPEC-182.2 — refused only when the caller judges in a run or under strict; renumber and integration
|
|
114
|
+
// pass no option and keep their 0.35.25 verdicts.
|
|
115
|
+
const scaffold = opts?.scaffold !== 'refuse' || unchangedSeal ? [] : (0, approval_blockers_1.scaffoldSections)(candidate);
|
|
116
|
+
if (scaffold.length > 0) {
|
|
117
|
+
return { ok: false, reason: (0, approval_blockers_1.placeholderMessage)(scaffold) };
|
|
118
|
+
}
|
|
104
119
|
// @implements A-SPEC-505.1 — acceptance substance, judged at the ACT on the same candidate
|
|
105
120
|
// the seal would freeze, like the placeholder gate above (154/428 approved REQs here are
|
|
106
121
|
// non-stated legacy; a validateSpec predicate would brick them all). Judged HERE and not
|
|
@@ -131,5 +146,5 @@ function prepareApprovedSpec(spec, specs, resolver, readFile) {
|
|
|
131
146
|
const digest = (0, spec_digest_1.specDigest)(candidate);
|
|
132
147
|
candidate.frontmatter.approved_digest = digest;
|
|
133
148
|
candidate.frontmatter.parent_digests = parentDigests;
|
|
134
|
-
return { ok: true, candidate, digest, parentDigests };
|
|
149
|
+
return { ok: true, candidate, digest, parentDigests, ...(ancestorIssues.length > 0 ? { ancestorWarnings: ancestorIssues } : {}) };
|
|
135
150
|
}
|