@holmes-lab/holmes-kit 0.32.0 → 0.34.0
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 +88 -0
- package/README.md +3 -1
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/autonomy.js +15 -1
- package/dist/holmes/guardrail/impact-gate.js +50 -1
- package/dist/holmes/guardrail/risk-classifier.js +218 -6
- package/dist/holmes/hooks/pre-tool-use.d.ts +12 -0
- package/dist/holmes/hooks/pre-tool-use.js +55 -2
- package/dist/holmes/mcp/handlers/adoption.d.ts +17 -3
- package/dist/holmes/mcp/handlers/adoption.js +70 -2
- package/dist/holmes/mcp/handlers/graph-operations.js +6 -1
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +9 -16
- package/dist/holmes/mcp/handlers/phase-queries.d.ts +30 -2
- package/dist/holmes/mcp/handlers/phase-queries.js +5 -1
- package/dist/holmes/mcp/handlers/review-evidence.d.ts +44 -1
- package/dist/holmes/mcp/handlers/review-evidence.js +48 -2
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +10 -0
- package/dist/holmes/mcp/handlers/spec-approval.js +16 -1
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +1 -9
- package/dist/holmes/mcp/handlers/spec-queries.js +40 -15
- package/dist/holmes/mcp/handlers.d.ts +43 -14
- package/dist/holmes/mcp/maintenance-analyze.js +64 -6
- package/dist/holmes/mcp/supervisor.d.ts +8 -0
- package/dist/holmes/mcp/supervisor.js +32 -2
- package/dist/holmes/mcp/tool-schemas.js +26 -5
- package/dist/holmes/reverse/scan.d.ts +6 -0
- package/dist/holmes/reverse/scan.js +4 -2
- package/dist/holmes/review/requirement-triage.d.ts +6 -0
- package/dist/holmes/review/requirement-triage.js +78 -9
- package/dist/holmes/review/test-outcomes.d.ts +53 -1
- package/dist/holmes/review/test-outcomes.js +156 -8
- package/dist/holmes/semantic/unreadable-paths.d.ts +30 -0
- package/dist/holmes/semantic/unreadable-paths.js +104 -0
- package/package.json +1 -1
- package/playbooks/author-slice/PLAYBOOK.md +1 -1
- package/playbooks/promote-slice/PLAYBOOK.md +1 -1
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { Spec } from '../../spec/spec-parser';
|
|
2
2
|
import { SpecStore } from '../../spec/spec-store';
|
|
3
|
+
import { type ReverseScanReport } from '../../reverse/scan';
|
|
4
|
+
import type { Cluster } from '../../reverse/cluster';
|
|
3
5
|
import { DraftResult } from '../../reverse/draft';
|
|
4
6
|
import { AnchorMapping } from '../../reverse/anchor';
|
|
5
7
|
export interface AdoptionContext {
|
|
@@ -8,6 +10,16 @@ export interface AdoptionContext {
|
|
|
8
10
|
assertReadableRoot(tool: string, root: string): void;
|
|
9
11
|
occupiedTarget(specs: Spec[]): string | undefined;
|
|
10
12
|
}
|
|
13
|
+
type ScanView = Omit<ReverseScanReport, 'surfaceByCluster' | 'anchoredFiles'>;
|
|
14
|
+
/**
|
|
15
|
+
* @implements A-SPEC-746 — the adoption inventory as an agent reads it. Compression, not a cut:
|
|
16
|
+
* test matches are counted (each cluster already lists its tests), paths are relative to their
|
|
17
|
+
* cluster, unmatched tests are grouped by directory with only the non-template reasons kept, and a
|
|
18
|
+
* cluster whose every file is already anchored — not an adoption candidate — folds to its size.
|
|
19
|
+
* Unanchored clusters come first. Only if the view is still over `budget` are the last clusters
|
|
20
|
+
* reduced to their size, counted, with a note naming `detail: "full"`.
|
|
21
|
+
*/
|
|
22
|
+
export declare function conciseReverseScan(report: ScanView, anchored: ReadonlySet<string>, budget?: number): Record<string, unknown>;
|
|
11
23
|
export declare function createAdoptionHandlers(context: AdoptionContext): {
|
|
12
24
|
/**
|
|
13
25
|
* Read-only inventory of a brownfield target: candidate clusters, coverage, and what the scan
|
|
@@ -17,7 +29,8 @@ export declare function createAdoptionHandlers(context: AdoptionContext): {
|
|
|
17
29
|
reverse_scan(a: {
|
|
18
30
|
root: string;
|
|
19
31
|
maxFlagged?: number;
|
|
20
|
-
|
|
32
|
+
detail?: unknown;
|
|
33
|
+
}): Promise<Record<string, unknown> | {
|
|
21
34
|
root: string;
|
|
22
35
|
isGit: boolean;
|
|
23
36
|
scanned: number;
|
|
@@ -25,8 +38,8 @@ export declare function createAdoptionHandlers(context: AdoptionContext): {
|
|
|
25
38
|
candidates: number;
|
|
26
39
|
anchored: number;
|
|
27
40
|
unanchored: number;
|
|
28
|
-
clusters:
|
|
29
|
-
testClusters:
|
|
41
|
+
clusters: Cluster[];
|
|
42
|
+
testClusters: Cluster[];
|
|
30
43
|
coverage: {
|
|
31
44
|
structurallyResolved: number;
|
|
32
45
|
inTestClusters: number;
|
|
@@ -116,3 +129,4 @@ export declare function createAdoptionHandlers(context: AdoptionContext): {
|
|
|
116
129
|
refused: import("../../reverse/anchor").RefusedAnchor[];
|
|
117
130
|
}>;
|
|
118
131
|
};
|
|
132
|
+
export {};
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.conciseReverseScan = conciseReverseScan;
|
|
3
4
|
exports.createAdoptionHandlers = createAdoptionHandlers;
|
|
4
5
|
const spec_store_1 = require("../../spec/spec-store");
|
|
5
6
|
const validator_1 = require("../../spec/validator");
|
|
@@ -8,6 +9,66 @@ const approval_blockers_1 = require("../../spec/approval-blockers");
|
|
|
8
9
|
const scan_1 = require("../../reverse/scan");
|
|
9
10
|
const draft_1 = require("../../reverse/draft");
|
|
10
11
|
const anchor_1 = require("../../reverse/anchor");
|
|
12
|
+
const cmpText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
13
|
+
const relativeTo = (dir, file) => dir === '.' || dir === '' || !file.startsWith(`${dir}/`) ? file : file.slice(dir.length + 1);
|
|
14
|
+
const TEMPLATE_UNMATCHED = /^no candidate file named /;
|
|
15
|
+
/**
|
|
16
|
+
* @implements A-SPEC-746 — the adoption inventory as an agent reads it. Compression, not a cut:
|
|
17
|
+
* test matches are counted (each cluster already lists its tests), paths are relative to their
|
|
18
|
+
* cluster, unmatched tests are grouped by directory with only the non-template reasons kept, and a
|
|
19
|
+
* cluster whose every file is already anchored — not an adoption candidate — folds to its size.
|
|
20
|
+
* Unanchored clusters come first. Only if the view is still over `budget` are the last clusters
|
|
21
|
+
* reduced to their size, counted, with a note naming `detail: "full"`.
|
|
22
|
+
*/
|
|
23
|
+
function conciseReverseScan(report, anchored, budget = 28000) {
|
|
24
|
+
const fold = (c) => {
|
|
25
|
+
const anchoredCount = c.files.filter((f) => anchored.has(f)).length;
|
|
26
|
+
if (c.files.length > 0 && anchoredCount === c.files.length)
|
|
27
|
+
return { dir: c.dir, fileCount: c.files.length, anchored: true };
|
|
28
|
+
return { ...c, files: c.files.map((f) => relativeTo(c.dir, f)), testFiles: (c.testFiles ?? []).map((f) => relativeTo(c.dir, f)), anchoredCount };
|
|
29
|
+
};
|
|
30
|
+
const order = (cs) => cs.map(fold)
|
|
31
|
+
.sort((a, b) => Number('anchored' in a) - Number('anchored' in b) || cmpText(a.dir, b.dir));
|
|
32
|
+
const matchedVia = {};
|
|
33
|
+
for (const m of report.tests.matched)
|
|
34
|
+
matchedVia[m.via] = (matchedVia[m.via] ?? 0) + 1;
|
|
35
|
+
const unmatchedByDir = {};
|
|
36
|
+
for (const u of report.tests.unmatched) {
|
|
37
|
+
const cut = u.file.lastIndexOf('/');
|
|
38
|
+
const dir = cut < 0 ? '.' : u.file.slice(0, cut);
|
|
39
|
+
(unmatchedByDir[dir] ??= []).push(cut < 0 ? u.file : u.file.slice(cut + 1));
|
|
40
|
+
}
|
|
41
|
+
const unmatchedReasons = report.tests.unmatched.filter((u) => !TEMPLATE_UNMATCHED.test(u.reason));
|
|
42
|
+
const view = {
|
|
43
|
+
...report,
|
|
44
|
+
clusters: order(report.clusters),
|
|
45
|
+
testClusters: order(report.testClusters),
|
|
46
|
+
tests: {
|
|
47
|
+
matchedTotal: report.tests.matched.length, matchedVia,
|
|
48
|
+
unmatchedTotal: report.tests.unmatched.length, unmatchedByDir,
|
|
49
|
+
...(unmatchedReasons.length > 0 ? { unmatchedReasons } : {}),
|
|
50
|
+
},
|
|
51
|
+
};
|
|
52
|
+
let size = JSON.stringify(view).length;
|
|
53
|
+
let reduced = 0;
|
|
54
|
+
for (const key of ['testClusters', 'clusters']) {
|
|
55
|
+
const list = view[key];
|
|
56
|
+
for (let i = list.length - 1; i >= 0 && size > budget; i--) {
|
|
57
|
+
const c = list[i];
|
|
58
|
+
if (!('files' in c))
|
|
59
|
+
continue;
|
|
60
|
+
const small = { dir: c.dir, fileCount: c.files.length, anchoredCount: c.anchoredCount };
|
|
61
|
+
size -= JSON.stringify(c).length - JSON.stringify(small).length;
|
|
62
|
+
list[i] = small;
|
|
63
|
+
reduced++;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
if (reduced > 0) {
|
|
67
|
+
view.clustersReduced = reduced;
|
|
68
|
+
view.note = `${reduced} cluster(s) are listed by size only to keep this answer small — call reverse_scan with detail: "full" for every file, or reverse_draft with cluster for one.`;
|
|
69
|
+
}
|
|
70
|
+
return view;
|
|
71
|
+
}
|
|
11
72
|
function createAdoptionHandlers(context) {
|
|
12
73
|
return {
|
|
13
74
|
// @implements A-SPEC-126
|
|
@@ -20,6 +81,10 @@ function createAdoptionHandlers(context) {
|
|
|
20
81
|
* repository is a supported case here, reported as `isGit: false`.
|
|
21
82
|
*/
|
|
22
83
|
async reverse_scan(a) {
|
|
84
|
+
// @implements A-SPEC-746 — an unknown view is refused before anything is read.
|
|
85
|
+
if (a.detail !== undefined && a.detail !== 'summary' && a.detail !== 'full') {
|
|
86
|
+
return { ok: false, reason: 'detail must be "summary" (the default, compressed view) or "full" (the complete answer).' };
|
|
87
|
+
}
|
|
23
88
|
// @implements A-SPEC-189 §10 (round 11) — `reverse_scan`/`reverse_draft` never call
|
|
24
89
|
// `projectRootOf`, so §7's refusal marker never reached them and their own POINTED sentence
|
|
25
90
|
// ("<root> is not a directory") arrived at the wire as a raw -32603 fault. A refusal about the
|
|
@@ -28,8 +93,11 @@ function createAdoptionHandlers(context) {
|
|
|
28
93
|
// `surfaceByCluster` is drafting evidence, not reading material. On the calibration target it
|
|
29
94
|
// is 11,460 characters across 15 clusters, and this response enters context on every scan —
|
|
30
95
|
// paying that to READ what only DRAFTING consumes. `reverse_draft` reads it in-process instead.
|
|
31
|
-
|
|
32
|
-
|
|
96
|
+
// @implements A-SPEC-746 — `anchoredFiles` is the handler's input for folding, never the reader's.
|
|
97
|
+
const { surfaceByCluster: _drafting, anchoredFiles, ...response } = (0, scan_1.reverseScan)(a.root, { maxFlagged: a.maxFlagged });
|
|
98
|
+
if (a.detail === 'full')
|
|
99
|
+
return response;
|
|
100
|
+
return conciseReverseScan(response, new Set(anchoredFiles));
|
|
33
101
|
},
|
|
34
102
|
/**
|
|
35
103
|
* Draft H-SPEC/A-SPEC/T-SPEC documents for the recovered clusters under an EXISTING parent REQ.
|
|
@@ -39,7 +39,7 @@ exports.warmRequirementSemanticCache = warmRequirementSemanticCache;
|
|
|
39
39
|
exports.headOf = headOf;
|
|
40
40
|
exports.refreshSemanticVectors = refreshSemanticVectors;
|
|
41
41
|
exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
|
|
42
|
-
// @implements A-SPEC-719, A-SPEC-734
|
|
42
|
+
// @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1
|
|
43
43
|
// @implements A-SPEC-614, A-SPEC-613, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-139, A-SPEC-189, A-SPEC-280, A-SPEC-282, A-SPEC-283, A-SPEC-419, A-SPEC-433, A-SPEC-469, A-SPEC-478, A-SPEC-568.1, A-SPEC-568.2, A-SPEC-569.1, A-SPEC-569.2, A-SPEC-569.3, A-SPEC-589
|
|
44
44
|
// @implements A-SPEC-632
|
|
45
45
|
const fs = __importStar(require("node:fs"));
|
|
@@ -54,6 +54,7 @@ const trace_gaps_1 = require("../../rtm/trace-gaps");
|
|
|
54
54
|
const tier_1 = require("../../semantic/tier");
|
|
55
55
|
const vector_cache_1 = require("../../semantic/vector-cache");
|
|
56
56
|
const embedder_1 = require("../../semantic/embedder");
|
|
57
|
+
const unreadable_paths_1 = require("../../semantic/unreadable-paths");
|
|
57
58
|
const bounded_io_1 = require("../../project/bounded-io");
|
|
58
59
|
const vector_coverage_1 = require("../../semantic/vector-coverage");
|
|
59
60
|
// @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
|
|
@@ -104,6 +105,10 @@ async function warmSemanticCache(root, scanned) {
|
|
|
104
105
|
const w = await rt.warm(docTexts);
|
|
105
106
|
if (docTexts.length > 0 && w.computed + w.cached === 0)
|
|
106
107
|
return { status: 'unavailable', tier: rt.label };
|
|
108
|
+
// @implements A-SPEC-741.1 — the unreadable files' path vectors a non-ASCII request is judged by.
|
|
109
|
+
// Best effort and NOT counted: the outcome is a persisted discharge shape (A-SPEC-632) that describes
|
|
110
|
+
// the source warm, and a missing path vector only keeps a language relevant.
|
|
111
|
+
await (0, unreadable_paths_1.warmUnreadablePaths)(rt, root);
|
|
107
112
|
// @implements A-SPEC-683 — `stored` is measured by refreshSemanticVectors, NOT returned here.
|
|
108
113
|
// This outcome flows into entity_integrate's discharge record, a PERSISTED artifact whose shape
|
|
109
114
|
// A-SPEC-632 pins by toEqual and validates by RECORD_KEYS; widening it is a persisted-artifact
|
|
@@ -34,12 +34,13 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
|
|
37
|
-
// @implements A-SPEC-745, A-SPEC-741, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734
|
|
37
|
+
// @implements A-SPEC-745, A-SPEC-741, A-SPEC-741.1, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734
|
|
38
38
|
const fs = __importStar(require("node:fs"));
|
|
39
39
|
const path = __importStar(require("node:path"));
|
|
40
40
|
const node_child_process_1 = require("node:child_process");
|
|
41
41
|
const spec_types_1 = require("../../spec/spec-types");
|
|
42
42
|
const cpg_scanner_1 = require("../../cpg/cpg-scanner");
|
|
43
|
+
const unreadable_paths_1 = require("../../semantic/unreadable-paths");
|
|
43
44
|
const rtm_graph_1 = require("../../rtm/rtm-graph");
|
|
44
45
|
const rtm_builder_1 = require("../../rtm/rtm-builder");
|
|
45
46
|
const test_scope_1 = require("../../rtm/test-scope");
|
|
@@ -75,29 +76,21 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
75
76
|
head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER, timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
|
|
76
77
|
}
|
|
77
78
|
catch { /* non-git */ }
|
|
78
|
-
const supportedExtensions = new Set(cpg_scanner_1.SCANNABLE_EXTENSIONS);
|
|
79
|
-
const knownCodeExtensions = new Set(['.rb', '.php', '.kt', '.kts', '.swift', '.scala', '.sh', '.ex', '.exs', '.lua', '.r']);
|
|
80
79
|
const unsupportedLanguages = new Set();
|
|
81
80
|
// @implements A-SPEC-741 — the paths too, so the analysis can tell an unreadable file that may
|
|
82
81
|
// be this request's target from one that is unrelated. Bounded: a vendored tree must not grow it.
|
|
83
|
-
|
|
82
|
+
// @implements A-SPEC-741.1 — enumerated by the same function the path-vector warm uses.
|
|
83
|
+
let unsupportedFiles = [];
|
|
84
84
|
let unsupportedFilesTruncated = false;
|
|
85
85
|
try {
|
|
86
86
|
// A-SPEC-734 (round 12): a root whose git timed out is not asked again (the shared memory).
|
|
87
87
|
if ((0, bounded_io_1.gitRootBlocked)(root))
|
|
88
88
|
throw new Error('git blocked on this root');
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
unsupportedLanguages.add(ext);
|
|
95
|
-
if (unsupportedFiles.length < 5000)
|
|
96
|
-
unsupportedFiles.push(file);
|
|
97
|
-
else
|
|
98
|
-
unsupportedFilesTruncated = true;
|
|
99
|
-
}
|
|
100
|
-
}
|
|
89
|
+
const listed = (0, unreadable_paths_1.listUnreadableFiles)(root);
|
|
90
|
+
for (const language of listed.languages)
|
|
91
|
+
unsupportedLanguages.add(language);
|
|
92
|
+
unsupportedFiles = listed.files;
|
|
93
|
+
unsupportedFilesTruncated = listed.truncated;
|
|
101
94
|
}
|
|
102
95
|
catch (e) {
|
|
103
96
|
(0, bounded_io_1.noteGitFailure)(root, e);
|
|
@@ -10,6 +10,26 @@ type PhaseRow = {
|
|
|
10
10
|
type: string;
|
|
11
11
|
status: string;
|
|
12
12
|
};
|
|
13
|
+
export declare function limitProblem(limit: unknown): string | undefined;
|
|
14
|
+
export declare function phasePage<R extends PhaseRow>(all: R[], a: {
|
|
15
|
+
ids?: string[];
|
|
16
|
+
type?: string;
|
|
17
|
+
status?: string;
|
|
18
|
+
limit?: number;
|
|
19
|
+
cursor?: string;
|
|
20
|
+
}): {
|
|
21
|
+
unknownIds?: string[] | undefined;
|
|
22
|
+
unknownIdsTotal?: number | undefined;
|
|
23
|
+
nextCursor?: string | undefined;
|
|
24
|
+
summary: {
|
|
25
|
+
total: number;
|
|
26
|
+
counts: Record<string, Record<string, number>>;
|
|
27
|
+
notApproved: R[];
|
|
28
|
+
notApprovedTotal: number;
|
|
29
|
+
};
|
|
30
|
+
specs: R[];
|
|
31
|
+
matched: number;
|
|
32
|
+
};
|
|
13
33
|
export declare function createPhaseQueryHandlers(context: PhaseQueryContext): {
|
|
14
34
|
phase_status(a: {
|
|
15
35
|
root?: string;
|
|
@@ -29,10 +49,18 @@ export declare function createPhaseQueryHandlers(context: PhaseQueryContext): {
|
|
|
29
49
|
summary: {
|
|
30
50
|
total: number;
|
|
31
51
|
counts: Record<string, Record<string, number>>;
|
|
32
|
-
notApproved:
|
|
52
|
+
notApproved: {
|
|
53
|
+
id: string;
|
|
54
|
+
type: import("../../spec/spec-types").SpecType;
|
|
55
|
+
status: "draft" | "review" | "approved" | "outdated";
|
|
56
|
+
}[];
|
|
33
57
|
notApprovedTotal: number;
|
|
34
58
|
};
|
|
35
|
-
specs:
|
|
59
|
+
specs: {
|
|
60
|
+
id: string;
|
|
61
|
+
type: import("../../spec/spec-types").SpecType;
|
|
62
|
+
status: "draft" | "review" | "approved" | "outdated";
|
|
63
|
+
}[];
|
|
36
64
|
matched: number;
|
|
37
65
|
ok?: undefined;
|
|
38
66
|
reason?: undefined;
|
|
@@ -33,8 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.limitProblem = limitProblem;
|
|
37
|
+
exports.phasePage = phasePage;
|
|
36
38
|
exports.createPhaseQueryHandlers = createPhaseQueryHandlers;
|
|
37
|
-
// @implements A-SPEC-606, A-SPEC-100.2, A-SPEC-735
|
|
39
|
+
// @implements A-SPEC-606, A-SPEC-100.2, A-SPEC-735, A-SPEC-746
|
|
38
40
|
const fs = __importStar(require("node:fs"));
|
|
39
41
|
const path = __importStar(require("node:path"));
|
|
40
42
|
const phase_1 = require("../../guardrail/phase");
|
|
@@ -51,6 +53,7 @@ const byId = (a, b) => a.id.localeCompare(b.id, 'en', { numeric: true })
|
|
|
51
53
|
|| codepoint(a.id, b.id) || codepoint(a.type, b.type) || codepoint(a.status, b.status);
|
|
52
54
|
const CURSOR_SEP = '\u0001';
|
|
53
55
|
const UNKNOWN_SHOWN = 50;
|
|
56
|
+
// @implements A-SPEC-746 — exported so spec_list pages by the same proved rules.
|
|
54
57
|
function limitProblem(limit) {
|
|
55
58
|
if (limit === undefined || limit === null)
|
|
56
59
|
return undefined;
|
|
@@ -58,6 +61,7 @@ function limitProblem(limit) {
|
|
|
58
61
|
return undefined;
|
|
59
62
|
return `limit은 1..${PAGE_MAX} 범위의 정수여야 합니다 (받은 값: ${JSON.stringify(limit)}).`;
|
|
60
63
|
}
|
|
64
|
+
// @implements A-SPEC-746 — generic over the row, so spec_list's extra fields (parent, legacy) travel.
|
|
61
65
|
function phasePage(all, a) {
|
|
62
66
|
const rows = [...all].sort(byId);
|
|
63
67
|
// @implements A-SPEC-735 (round 2) — Maps, never assignment into a plain object: `type: __proto__`
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Finding } from '../../review/findings';
|
|
2
|
+
import { ReviewNeeded } from '../../review/review-targets';
|
|
2
3
|
import { Approval } from '../../guardrail/risk-gate';
|
|
3
4
|
import { ElicitOutcome } from '../elicit-approval';
|
|
4
5
|
import { Basis } from '../basis';
|
|
@@ -27,6 +28,22 @@ export interface ReviewEvidenceContext {
|
|
|
27
28
|
why: string;
|
|
28
29
|
}): string;
|
|
29
30
|
}
|
|
31
|
+
/**
|
|
32
|
+
* @implements A-SPEC-746 — the review-needed backlog as an agent reads it: one row per spec (signals
|
|
33
|
+
* merged, files unioned), newest first, without the from/to digests — 64-hex identifiers were most of
|
|
34
|
+
* a 96,407-character answer here, and 123 specs fit in 10,887 once they go. Only over the budget does
|
|
35
|
+
* it keep the newest rows that fit, counting the rest and naming `detail: "full"`.
|
|
36
|
+
*/
|
|
37
|
+
export declare function summarizeReviewNeeded(signals: readonly ReviewNeeded[], budget?: number): {
|
|
38
|
+
reviewNeeded: Array<{
|
|
39
|
+
spec: string;
|
|
40
|
+
files: string[];
|
|
41
|
+
signals: number;
|
|
42
|
+
}>;
|
|
43
|
+
reviewNeededTotal: number;
|
|
44
|
+
reviewNeededOmitted?: number;
|
|
45
|
+
note?: string;
|
|
46
|
+
};
|
|
30
47
|
export declare function createReviewEvidenceHandlers(context: ReviewEvidenceContext): {
|
|
31
48
|
review_record(a: {
|
|
32
49
|
root: string;
|
|
@@ -36,13 +53,39 @@ export declare function createReviewEvidenceHandlers(context: ReviewEvidenceCont
|
|
|
36
53
|
}>;
|
|
37
54
|
review_status(a: {
|
|
38
55
|
root: string;
|
|
56
|
+
detail?: unknown;
|
|
39
57
|
}): Promise<{
|
|
58
|
+
ok: boolean;
|
|
59
|
+
reason: string;
|
|
60
|
+
blocked?: undefined;
|
|
61
|
+
open?: undefined;
|
|
62
|
+
reviewNeeded?: undefined;
|
|
63
|
+
} | {
|
|
64
|
+
blocked: boolean;
|
|
65
|
+
open: {
|
|
66
|
+
critical: number;
|
|
67
|
+
important: number;
|
|
68
|
+
minor: number;
|
|
69
|
+
};
|
|
70
|
+
reviewNeeded: ReviewNeeded[];
|
|
71
|
+
ok?: undefined;
|
|
72
|
+
reason?: undefined;
|
|
73
|
+
} | {
|
|
74
|
+
reviewNeeded: Array<{
|
|
75
|
+
spec: string;
|
|
76
|
+
files: string[];
|
|
77
|
+
signals: number;
|
|
78
|
+
}>;
|
|
79
|
+
reviewNeededTotal: number;
|
|
80
|
+
reviewNeededOmitted?: number;
|
|
81
|
+
note?: string;
|
|
40
82
|
blocked: boolean;
|
|
41
83
|
open: {
|
|
42
84
|
critical: number;
|
|
43
85
|
important: number;
|
|
44
86
|
minor: number;
|
|
45
87
|
};
|
|
46
|
-
|
|
88
|
+
ok?: undefined;
|
|
89
|
+
reason?: undefined;
|
|
47
90
|
}>;
|
|
48
91
|
};
|
|
@@ -33,8 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.summarizeReviewNeeded = summarizeReviewNeeded;
|
|
36
37
|
exports.createReviewEvidenceHandlers = createReviewEvidenceHandlers;
|
|
37
|
-
// @implements A-SPEC-718, A-SPEC-617, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-133, A-SPEC-135, A-SPEC-141, A-SPEC-157, A-SPEC-160, A-SPEC-189, A-SPEC-191, A-SPEC-244, A-SPEC-245, A-SPEC-263.1, A-SPEC-497.1, A-SPEC-732
|
|
38
|
+
// @implements A-SPEC-718, A-SPEC-746, A-SPEC-617, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-133, A-SPEC-135, A-SPEC-141, A-SPEC-157, A-SPEC-160, A-SPEC-189, A-SPEC-191, A-SPEC-244, A-SPEC-245, A-SPEC-263.1, A-SPEC-497.1, A-SPEC-732
|
|
38
39
|
const path = __importStar(require("node:path"));
|
|
39
40
|
const findings_1 = require("../../review/findings");
|
|
40
41
|
const review_targets_1 = require("../../review/review-targets");
|
|
@@ -45,6 +46,44 @@ const ledger_lock_1 = require("../../governance/ledger-lock");
|
|
|
45
46
|
const approval_grants_1 = require("../../governance/approval-grants");
|
|
46
47
|
const provenance_chain_1 = require("../../governance/provenance-chain");
|
|
47
48
|
const autonomy_1 = require("../../governance/autonomy");
|
|
49
|
+
/**
|
|
50
|
+
* @implements A-SPEC-746 — the review-needed backlog as an agent reads it: one row per spec (signals
|
|
51
|
+
* merged, files unioned), newest first, without the from/to digests — 64-hex identifiers were most of
|
|
52
|
+
* a 96,407-character answer here, and 123 specs fit in 10,887 once they go. Only over the budget does
|
|
53
|
+
* it keep the newest rows that fit, counting the rest and naming `detail: "full"`.
|
|
54
|
+
*/
|
|
55
|
+
function summarizeReviewNeeded(signals, budget = 24000) {
|
|
56
|
+
const bySpec = new Map();
|
|
57
|
+
signals.forEach((s, i) => {
|
|
58
|
+
const entry = bySpec.get(s.spec) ?? { files: new Set(), signals: 0, last: i };
|
|
59
|
+
for (const f of s.files)
|
|
60
|
+
entry.files.add(f);
|
|
61
|
+
entry.signals++;
|
|
62
|
+
entry.last = i;
|
|
63
|
+
bySpec.set(s.spec, entry);
|
|
64
|
+
});
|
|
65
|
+
const rows = [...bySpec].sort((a, b) => b[1].last - a[1].last)
|
|
66
|
+
.map(([spec, e]) => ({ spec, files: [...e.files].sort(), signals: e.signals }));
|
|
67
|
+
let size = 2;
|
|
68
|
+
const kept = [];
|
|
69
|
+
for (const row of rows) {
|
|
70
|
+
const n = JSON.stringify(row).length + 1;
|
|
71
|
+
if (size + n > budget)
|
|
72
|
+
break;
|
|
73
|
+
size += n;
|
|
74
|
+
kept.push(row);
|
|
75
|
+
}
|
|
76
|
+
const omitted = rows.length - kept.length;
|
|
77
|
+
return {
|
|
78
|
+
reviewNeeded: kept,
|
|
79
|
+
reviewNeededTotal: signals.length,
|
|
80
|
+
...(omitted > 0 ? {
|
|
81
|
+
reviewNeededOmitted: omitted,
|
|
82
|
+
note: `${omitted} older spec(s) awaiting review are not listed — call review_status with detail: "full" for every signal.`,
|
|
83
|
+
} : {}),
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
const DETAIL_REASON = 'detail must be "summary" (the default, compressed view) or "full" (the complete answer).';
|
|
48
87
|
function createReviewEvidenceHandlers(context) {
|
|
49
88
|
return {
|
|
50
89
|
async review_record(a) {
|
|
@@ -332,6 +371,9 @@ function createReviewEvidenceHandlers(context) {
|
|
|
332
371
|
return { recorded: a.findings.length };
|
|
333
372
|
},
|
|
334
373
|
async review_status(a) {
|
|
374
|
+
// @implements A-SPEC-746 — an unknown view is refused before anything is read.
|
|
375
|
+
if (a.detail !== undefined && a.detail !== 'summary' && a.detail !== 'full')
|
|
376
|
+
return { ok: false, reason: DETAIL_REASON };
|
|
335
377
|
// @implements A-SPEC-191 §15 — the merge gate must not answer about a project it did not read.
|
|
336
378
|
const foreign = context.foreignRootReason(a.root);
|
|
337
379
|
if (foreign !== null)
|
|
@@ -374,7 +416,11 @@ function createReviewEvidenceHandlers(context) {
|
|
|
374
416
|
// P4 routing backlog depending on how its root was spelled (a subdirectory passes the
|
|
375
417
|
// project-level foreign check). One question, one tree.
|
|
376
418
|
const reviewNeeded = (0, review_targets_1.readReviewNeeded)(path.join(path.dirname(context.boundFindingsLedger(a.root)), 'provenance.jsonl'));
|
|
377
|
-
|
|
419
|
+
const blocked = counts.critical > 0 || counts.important > 0;
|
|
420
|
+
// @implements A-SPEC-746 — `detail: "full"` is the raw signal list, as before.
|
|
421
|
+
if (a.detail === 'full')
|
|
422
|
+
return { blocked, open: counts, reviewNeeded };
|
|
423
|
+
return { blocked, open: counts, ...summarizeReviewNeeded(reviewNeeded) };
|
|
378
424
|
},
|
|
379
425
|
};
|
|
380
426
|
}
|
|
@@ -70,17 +70,26 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
|
|
|
70
70
|
} | {
|
|
71
71
|
ok: boolean;
|
|
72
72
|
reason: string;
|
|
73
|
+
blockers: string[];
|
|
74
|
+
approvalIntent?: undefined;
|
|
75
|
+
conflict?: undefined;
|
|
76
|
+
} | {
|
|
77
|
+
ok: boolean;
|
|
78
|
+
reason: string;
|
|
79
|
+
blockers?: undefined;
|
|
73
80
|
approvalIntent?: undefined;
|
|
74
81
|
conflict?: undefined;
|
|
75
82
|
} | {
|
|
76
83
|
ok: boolean;
|
|
77
84
|
reason: string;
|
|
78
85
|
approvalIntent: ApprovalIntent;
|
|
86
|
+
blockers?: undefined;
|
|
79
87
|
conflict?: undefined;
|
|
80
88
|
} | {
|
|
81
89
|
ok: boolean;
|
|
82
90
|
reason: string;
|
|
83
91
|
conflict: import("../../spec/version-conflict").ConflictDetail;
|
|
92
|
+
blockers?: undefined;
|
|
84
93
|
approvalIntent?: undefined;
|
|
85
94
|
} | {
|
|
86
95
|
dismissUnknown?: string[] | undefined;
|
|
@@ -101,6 +110,7 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
|
|
|
101
110
|
digest: string;
|
|
102
111
|
ok?: undefined;
|
|
103
112
|
reason?: undefined;
|
|
113
|
+
blockers?: undefined;
|
|
104
114
|
approvalIntent?: undefined;
|
|
105
115
|
conflict?: undefined;
|
|
106
116
|
}>;
|
|
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.createSpecApprovalHandlers = createSpecApprovalHandlers;
|
|
37
37
|
exports.readProjectFile = readProjectFile;
|
|
38
|
-
// @implements A-SPEC-718, A-SPEC-551.1, A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245, A-SPEC-729
|
|
38
|
+
// @implements A-SPEC-718, A-SPEC-551.1, A-SPEC-551.2, A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245, A-SPEC-729
|
|
39
39
|
// @implements A-SPEC-631, A-SPEC-733
|
|
40
40
|
const fs = __importStar(require("node:fs"));
|
|
41
41
|
const compat_impact_1 = require("../../spec/compat-impact");
|
|
@@ -54,6 +54,7 @@ const provenance_chain_1 = require("../../governance/provenance-chain");
|
|
|
54
54
|
const review_targets_1 = require("../../review/review-targets");
|
|
55
55
|
const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
|
|
56
56
|
const approval_policy_1 = require("../approval-policy");
|
|
57
|
+
const approval_blockers_1 = require("../../spec/approval-blockers");
|
|
57
58
|
function createSpecApprovalHandlers(context) {
|
|
58
59
|
const { store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval } = context;
|
|
59
60
|
return {
|
|
@@ -112,6 +113,20 @@ function createSpecApprovalHandlers(context) {
|
|
|
112
113
|
// @implements A-SPEC-649 — the digest of what the operator will read rides the request.
|
|
113
114
|
subject = target ? (0, spec_digest_1.specDigest)(target.spec) : undefined;
|
|
114
115
|
if (target) {
|
|
116
|
+
// @implements A-SPEC-551.2 — a spec no approval could seal as written is answered with WHY, before
|
|
117
|
+
// any channel is chosen: no elicitation, no queue entry. Measured 2026-09-30: an invalid
|
|
118
|
+
// breaking_change grade graded `hitl`, went to the owner's queue, and the refusal named the approval
|
|
119
|
+
// channel instead of the blocker — the agent asked the owner for an approval that could not help.
|
|
120
|
+
// Same predicate `approval_status.blockers` reports. A covered act (above) keeps its own order.
|
|
121
|
+
const blockers = (0, approval_blockers_1.approvalBlockers)(target.spec, resolver(await store.list()));
|
|
122
|
+
if (blockers.length > 0) {
|
|
123
|
+
return {
|
|
124
|
+
ok: false,
|
|
125
|
+
reason: `spec_approve: ${a.id} cannot be sealed as written — fix these first (approval_status shows the same list); `
|
|
126
|
+
+ `no approval request was filed: ${blockers.join('; ')}`,
|
|
127
|
+
blockers,
|
|
128
|
+
};
|
|
129
|
+
}
|
|
115
130
|
const targetSubject = (0, spec_digest_1.specDigest)(target.spec);
|
|
116
131
|
// A host-gated commit is a continuation of this exact original action. It is checked
|
|
117
132
|
// before presentation and is memory-only, so a bare retry never carries authority.
|
|
@@ -18,15 +18,7 @@ export declare function createSpecQueryHandlers(context: SpecQueryContext): {
|
|
|
18
18
|
message: any;
|
|
19
19
|
}[];
|
|
20
20
|
}>;
|
|
21
|
-
spec_list(a: any): Promise<
|
|
22
|
-
specs: {
|
|
23
|
-
legacy?: boolean | undefined;
|
|
24
|
-
parent?: string | undefined;
|
|
25
|
-
id: string;
|
|
26
|
-
type: import("../../spec/spec-types").SpecType;
|
|
27
|
-
status: "draft" | "review" | "approved" | "outdated";
|
|
28
|
-
}[];
|
|
29
|
-
}>;
|
|
21
|
+
spec_list(a: any): Promise<Record<string, any>>;
|
|
30
22
|
spec_next(a?: {
|
|
31
23
|
id?: string;
|
|
32
24
|
}): Promise<{
|
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.createSpecQueryHandlers = createSpecQueryHandlers;
|
|
4
|
+
const phase_queries_1 = require("./phase-queries");
|
|
5
|
+
const SPEC_LIST_PAGE = 100;
|
|
6
|
+
const SPEC_LIST_PENDING = 100;
|
|
4
7
|
const validator_1 = require("../../spec/validator");
|
|
5
8
|
const legacy_format_1 = require("../../spec/legacy-format");
|
|
6
9
|
const spec_types_1 = require("../../spec/spec-types");
|
|
@@ -109,8 +112,13 @@ function createSpecQueryHandlers(context) {
|
|
|
109
112
|
return { ok: false, findings: [{ level: 'error', code: 'not-found', message: a.id }] };
|
|
110
113
|
return (0, validator_1.validateSpec)(spec, context.resolver(specs));
|
|
111
114
|
},
|
|
115
|
+
// A-SPEC-746: the declared answer stays one open record so the refusal branch ({ ok: false, reason })
|
|
116
|
+
// does not turn every existing reader's `result.specs` into a compile error.
|
|
112
117
|
async spec_list(a) {
|
|
113
118
|
context.assertStoreReachable('spec_list', a.root); // @implements A-SPEC-419
|
|
119
|
+
const badLimit = (0, phase_queries_1.limitProblem)(a?.limit); // @implements A-SPEC-746 — refused before the corpus is read
|
|
120
|
+
if (badLimit)
|
|
121
|
+
return { ok: false, reason: badLimit };
|
|
114
122
|
const specs = await context.listSpecs();
|
|
115
123
|
// @implements A-SPEC-186
|
|
116
124
|
// The parent travels with the id because a bare one cannot be read. Measured: a reader took
|
|
@@ -138,22 +146,39 @@ function createSpecQueryHandlers(context) {
|
|
|
138
146
|
// canonical row (the same omission convention as `parent` above). The set derives from the
|
|
139
147
|
// SPEC_STATUSES runtime list — a hand-copy here was a second truth the compiler cannot police.
|
|
140
148
|
const CANONICAL_STATUSES = new Set(spec_types_1.SPEC_STATUSES);
|
|
149
|
+
// @implements A-SPEC-746 — a compressed view by default: counts, what needs action (the specs not
|
|
150
|
+
// approved), then a page with a cursor. The whole corpus was 202,608 characters here, past the
|
|
151
|
+
// client's tool-result limit, for a question the playbooks ask about ONE spec.
|
|
152
|
+
const rows = specs
|
|
153
|
+
.filter((s) => (!a?.type || s.type === a.type) && (typeof a?.status !== 'string' || s.status === a.status))
|
|
154
|
+
.map((s) => {
|
|
155
|
+
const parent = parentOf(s);
|
|
156
|
+
// @implements A-SPEC-192 §5R (round 9) — the mark asks 'is this row a GOVERNED spec?',
|
|
157
|
+
// and status alone could not answer it: an old-format document that never declared a
|
|
158
|
+
// `type` came through with a lone `approved` and dressed exactly like a canonical row —
|
|
159
|
+
// the misreading this REQ exists to prevent. Format and status are both grounds.
|
|
160
|
+
const legacyFormat = (0, legacy_format_1.formatStateOf)({ id: s.id, type: s.type }).kind !== 'current';
|
|
161
|
+
return {
|
|
162
|
+
id: s.id, type: s.type, status: s.status,
|
|
163
|
+
...(parent ? { parent } : {}),
|
|
164
|
+
...(CANONICAL_STATUSES.has(s.status) && !legacyFormat ? {} : { legacy: true }),
|
|
165
|
+
};
|
|
166
|
+
});
|
|
167
|
+
const wanted = Array.isArray(a?.ids) ? new Set(a.ids.filter((x) => typeof x === 'string')) : undefined;
|
|
168
|
+
const selected = wanted ? rows.filter((r) => wanted.has(r.id)) : rows;
|
|
169
|
+
const page = (0, phase_queries_1.phasePage)(selected, { ids: a?.ids, limit: typeof a?.limit === 'number' ? a.limit : SPEC_LIST_PAGE, cursor: a?.cursor });
|
|
170
|
+
const pending = (0, phase_queries_1.phasePage)(selected.filter((r) => r.status !== 'approved'), { limit: SPEC_LIST_PENDING });
|
|
141
171
|
return {
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
id: s.id, type: s.type, status: s.status,
|
|
153
|
-
...(parent ? { parent } : {}),
|
|
154
|
-
...(CANONICAL_STATUSES.has(s.status) && !legacyFormat ? {} : { legacy: true }),
|
|
155
|
-
};
|
|
156
|
-
}),
|
|
172
|
+
summary: { total: page.summary.total, counts: page.summary.counts },
|
|
173
|
+
pending: pending.specs,
|
|
174
|
+
pendingTotal: pending.matched,
|
|
175
|
+
specs: page.specs,
|
|
176
|
+
total: page.matched,
|
|
177
|
+
...(page.nextCursor !== undefined ? {
|
|
178
|
+
nextCursor: page.nextCursor,
|
|
179
|
+
note: 'More rows follow this page (total counts every matching row) — pass nextCursor as cursor to continue, or ask for specific specs with ids.',
|
|
180
|
+
} : {}),
|
|
181
|
+
...(page.unknownIds !== undefined ? { unknownIds: page.unknownIds, unknownIdsTotal: page.unknownIdsTotal } : {}),
|
|
157
182
|
};
|
|
158
183
|
},
|
|
159
184
|
async spec_next(a) {
|