@holmes-lab/holmes-kit 0.31.2 → 0.33.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.
Files changed (37) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/README.md +3 -1
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/autonomy.js +15 -1
  5. package/dist/holmes/guardrail/impact-gate.js +50 -1
  6. package/dist/holmes/mcp/handlers/adoption.d.ts +17 -3
  7. package/dist/holmes/mcp/handlers/adoption.js +70 -2
  8. package/dist/holmes/mcp/handlers/graph-operations.js +6 -1
  9. package/dist/holmes/mcp/handlers/maintenance-analysis.js +17 -11
  10. package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +6 -0
  11. package/dist/holmes/mcp/handlers/phase-queries.d.ts +30 -2
  12. package/dist/holmes/mcp/handlers/phase-queries.js +5 -1
  13. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +163 -4
  14. package/dist/holmes/mcp/handlers/requirement-triage.js +26 -18
  15. package/dist/holmes/mcp/handlers/review-evidence.d.ts +44 -1
  16. package/dist/holmes/mcp/handlers/review-evidence.js +48 -2
  17. package/dist/holmes/mcp/handlers/spec-approval.d.ts +10 -0
  18. package/dist/holmes/mcp/handlers/spec-approval.js +16 -1
  19. package/dist/holmes/mcp/handlers/spec-queries.d.ts +1 -9
  20. package/dist/holmes/mcp/handlers/spec-queries.js +40 -15
  21. package/dist/holmes/mcp/handlers.d.ts +212 -18
  22. package/dist/holmes/mcp/maintenance-analyze.d.ts +19 -0
  23. package/dist/holmes/mcp/maintenance-analyze.js +171 -7
  24. package/dist/holmes/mcp/maintenance-evidence.d.ts +25 -0
  25. package/dist/holmes/mcp/maintenance-evidence.js +52 -1
  26. package/dist/holmes/mcp/tool-schemas.js +29 -6
  27. package/dist/holmes/reverse/scan.d.ts +6 -0
  28. package/dist/holmes/reverse/scan.js +4 -2
  29. package/dist/holmes/review/requirement-triage.d.ts +25 -1
  30. package/dist/holmes/review/requirement-triage.js +175 -12
  31. package/dist/holmes/rtm/localize.d.ts +7 -0
  32. package/dist/holmes/rtm/localize.js +10 -0
  33. package/dist/holmes/semantic/unreadable-paths.d.ts +30 -0
  34. package/dist/holmes/semantic/unreadable-paths.js +104 -0
  35. package/package.json +1 -1
  36. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  37. package/playbooks/promote-slice/PLAYBOOK.md +1 -1
@@ -19,17 +19,20 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
19
19
  prompt: string;
20
20
  topK?: number;
21
21
  persist?: boolean;
22
+ detail?: string;
22
23
  }): Promise<{
23
24
  promptDigest: string;
24
25
  semantic: {
25
26
  localState?: import("../../semantic/model-cache").LocalModelState | undefined;
26
27
  recovery?: string | undefined;
27
28
  suppressed?: true | undefined;
29
+ availability: string;
30
+ missingLineages?: string[] | undefined;
28
31
  tier: "local" | "none" | "cloud";
29
32
  covered: number;
30
33
  total: number;
31
- state: "covered" | "unavailable" | "not-adopted" | "cold";
32
- availability: string;
34
+ unlineaged: number;
35
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
33
36
  };
34
37
  provenance: {
35
38
  reqId: string;
@@ -75,6 +78,80 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
75
78
  reasons: string[];
76
79
  uncertainty: string[];
77
80
  schema: "requirement-triage/1";
81
+ } | {
82
+ promptDigest: string;
83
+ semantic: {
84
+ localState?: import("../../semantic/model-cache").LocalModelState | undefined;
85
+ recovery?: string | undefined;
86
+ suppressed?: true | undefined;
87
+ availability: string;
88
+ missingLineages?: string[] | undefined;
89
+ tier: "local" | "none" | "cloud";
90
+ covered: number;
91
+ total: number;
92
+ unlineaged: number;
93
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
94
+ };
95
+ provenance: {
96
+ reqId: string;
97
+ documents: {
98
+ id: string;
99
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
100
+ status: string;
101
+ dependsOn: readonly string[];
102
+ }[];
103
+ implementationAnchors: string[];
104
+ graphProvenance: {
105
+ [k: string]: {} | null;
106
+ };
107
+ executionEvidence: {
108
+ state: string;
109
+ recordedHead: string | null;
110
+ currentHead: string;
111
+ };
112
+ }[];
113
+ graph: {
114
+ status: GraphStatus;
115
+ sourceCommit: string | null;
116
+ graphAsOf: string | null;
117
+ resolutionLimits: string[];
118
+ };
119
+ graphBasis: {
120
+ head: string;
121
+ governedDocumentCount: number;
122
+ scannedSourceCount: number;
123
+ };
124
+ freshness: import("../../refresh/freshness-coordinator").FreshnessReceipt | {
125
+ state: string;
126
+ };
127
+ refresh: {
128
+ status: "spawned" | "coalesced" | "failed";
129
+ generation?: string;
130
+ } | {
131
+ status: "unavailable" | "not-needed";
132
+ };
133
+ lexicalOnly?: true | undefined;
134
+ candidates: {
135
+ documents: {
136
+ id: string;
137
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
138
+ title: string;
139
+ status: string;
140
+ dependsOn: readonly string[];
141
+ }[];
142
+ reqId: string;
143
+ lexicalScore: number;
144
+ semanticScore?: number;
145
+ contentTerms: string[];
146
+ approved: boolean;
147
+ implementationAnchors: string[];
148
+ freshGreenTests: boolean;
149
+ reasons: string[];
150
+ }[];
151
+ verdict: import("../../review/requirement-triage").RequirementVerdict;
152
+ reasons: string[];
153
+ uncertainty: string[];
154
+ schema: "requirement-triage/1";
78
155
  } | {
79
156
  evidenceDigest: string;
80
157
  persistedTo: string;
@@ -87,11 +164,13 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
87
164
  localState?: import("../../semantic/model-cache").LocalModelState | undefined;
88
165
  recovery?: string | undefined;
89
166
  suppressed?: true | undefined;
167
+ availability: string;
168
+ missingLineages?: string[] | undefined;
90
169
  tier: "local" | "none" | "cloud";
91
170
  covered: number;
92
171
  total: number;
93
- state: "covered" | "unavailable" | "not-adopted" | "cold";
94
- availability: string;
172
+ unlineaged: number;
173
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
95
174
  };
96
175
  provenance: {
97
176
  reqId: string;
@@ -137,6 +216,86 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
137
216
  reasons: string[];
138
217
  uncertainty: string[];
139
218
  schema: "requirement-triage/1";
219
+ } | {
220
+ evidenceDigest: string;
221
+ persistedTo: string;
222
+ artifact: {
223
+ digest: string;
224
+ path: string;
225
+ };
226
+ promptDigest: string;
227
+ semantic: {
228
+ localState?: import("../../semantic/model-cache").LocalModelState | undefined;
229
+ recovery?: string | undefined;
230
+ suppressed?: true | undefined;
231
+ availability: string;
232
+ missingLineages?: string[] | undefined;
233
+ tier: "local" | "none" | "cloud";
234
+ covered: number;
235
+ total: number;
236
+ unlineaged: number;
237
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
238
+ };
239
+ provenance: {
240
+ reqId: string;
241
+ documents: {
242
+ id: string;
243
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
244
+ status: string;
245
+ dependsOn: readonly string[];
246
+ }[];
247
+ implementationAnchors: string[];
248
+ graphProvenance: {
249
+ [k: string]: {} | null;
250
+ };
251
+ executionEvidence: {
252
+ state: string;
253
+ recordedHead: string | null;
254
+ currentHead: string;
255
+ };
256
+ }[];
257
+ graph: {
258
+ status: GraphStatus;
259
+ sourceCommit: string | null;
260
+ graphAsOf: string | null;
261
+ resolutionLimits: string[];
262
+ };
263
+ graphBasis: {
264
+ head: string;
265
+ governedDocumentCount: number;
266
+ scannedSourceCount: number;
267
+ };
268
+ freshness: import("../../refresh/freshness-coordinator").FreshnessReceipt | {
269
+ state: string;
270
+ };
271
+ refresh: {
272
+ status: "spawned" | "coalesced" | "failed";
273
+ generation?: string;
274
+ } | {
275
+ status: "unavailable" | "not-needed";
276
+ };
277
+ lexicalOnly?: true | undefined;
278
+ candidates: {
279
+ documents: {
280
+ id: string;
281
+ type: import("../../review/requirement-triage").RequirementDocumentKind;
282
+ title: string;
283
+ status: string;
284
+ dependsOn: readonly string[];
285
+ }[];
286
+ reqId: string;
287
+ lexicalScore: number;
288
+ semanticScore?: number;
289
+ contentTerms: string[];
290
+ approved: boolean;
291
+ implementationAnchors: string[];
292
+ freshGreenTests: boolean;
293
+ reasons: string[];
294
+ }[];
295
+ verdict: import("../../review/requirement-triage").RequirementVerdict;
296
+ reasons: string[];
297
+ uncertainty: string[];
298
+ schema: "requirement-triage/1";
140
299
  }>;
141
300
  };
142
301
  export {};
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
37
- // @implements A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734
37
+ // @implements A-SPEC-743, A-SPEC-742, A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734
38
38
  // @implements A-SPEC-713
39
39
  /** Read-only MCP projection of the pure requirement lifecycle triage model. */
40
40
  const node_child_process_1 = require("node:child_process");
@@ -163,31 +163,32 @@ function createRequirementTriageHandlers(context) {
163
163
  const runtime = suppressed ? null : (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
164
164
  const query = runtime ? await runtime.embedQuery(a.prompt) : null;
165
165
  const semanticCandidates = [];
166
- let covered = 0;
167
- if (runtime && query)
168
- for (const doc of documents) {
169
- const reqId = lineageOf(doc.id, byId);
170
- if (!reqId)
171
- continue;
172
- const vector = runtime.cachedDocVector((0, requirement_triage_1.canonicalRequirementDocument)(doc, reqId));
173
- if (vector) {
174
- covered++;
175
- semanticCandidates.push({ id: doc.id, score: cosine(query, vector) });
176
- }
177
- }
166
+ // @implements A-SPEC-742 — counted over documents that can carry a vector (a REQ lineage);
167
+ // the unlineaged are reported, not counted against the layer.
168
+ const coverage = (0, requirement_triage_1.requirementSemanticCoverage)(documents, (doc, reqId) => {
169
+ if (!runtime || !query)
170
+ return false;
171
+ const vector = runtime.cachedDocVector((0, requirement_triage_1.canonicalRequirementDocument)(doc, reqId));
172
+ if (vector)
173
+ semanticCandidates.push({ id: doc.id, score: cosine(query, vector) });
174
+ return vector !== null && vector !== undefined;
175
+ });
176
+ const covered = coverage.covered;
178
177
  const semanticState = suppressed ? 'not-adopted'
179
178
  : runtime === null || query === null
180
179
  ? (tier.tier === 'none' && !tier.localRuntimePresent ? 'not-adopted' : 'unavailable')
181
- : covered === documents.length ? 'covered' : 'cold';
180
+ : coverage.state;
182
181
  const readiness = tier.tier === 'none' && tier.localRuntimePresent ? (0, model_cache_1.readLocalModelReadiness)() : null;
183
182
  const availability = semanticState === 'covered' ? 'available'
184
- : semanticState === 'cold' || tier.tier === 'none' && tier.localRuntimePresent ? 'degraded'
183
+ : semanticState === 'cold' || semanticState === 'partial' || tier.tier === 'none' && tier.localRuntimePresent ? 'degraded'
185
184
  : 'unavailable';
186
- const semantic = { tier: tier.tier, covered, total: documents.length, state: semanticState,
185
+ const semantic = { tier: tier.tier, covered, total: coverage.eligible, unlineaged: coverage.unlineaged, state: semanticState,
186
+ ...(semanticState === 'partial' ? { missingLineages: coverage.missingLineages } : {}),
187
187
  availability, ...(suppressed ? { suppressed: true } : {}),
188
188
  ...(readiness ? { localState: readiness.state, recovery: readiness.recovery } : {}) };
189
189
  // lexicalOnly describes THIS run: no semantic score contributed to its ranking.
190
- const lexical = semanticCandidates.length === 0;
190
+ // A-SPEC-742 review round 1: a vector whose cosine was filtered out (<= 0) ranked nothing.
191
+ const lexical = !semanticCandidates.some((c) => Number.isFinite(c.score) && c.score > 0);
191
192
  const ranked = (0, requirement_triage_1.triageRequirements)({ prompt: a.prompt, documents, evidence: lineageEvidence,
192
193
  semanticCandidates, semantic, graph: { state: graph.status }, topK: a.topK });
193
194
  const result = freshnessCurrent ? ranked : {
@@ -206,7 +207,14 @@ function createRequirementTriageHandlers(context) {
206
207
  graphProvenance: Object.fromEntries(candidate.documents.map((document) => [document.id, graph.provenanceBySpec[document.id] ?? null])),
207
208
  executionEvidence: { state: executionState, recordedHead: evidence?.head ?? null, currentHead },
208
209
  }));
209
- const answer = { schema: 'requirement-triage/1', ...result, ...(lexical ? { lexicalOnly: true } : {}), promptDigest, semantic, provenance,
210
+ // @implements A-SPEC-743 — documents as summaries unless the caller asks for their text: the
211
+ // bodies were 72% of a 201 KB median answer, past the harness tool-result limit. Every decision
212
+ // field (verdict, reasons, uncertainty, candidate order and scores) is the same either way.
213
+ const shown = a.detail === 'full' ? result : { ...result, candidates: result.candidates.map((candidate) => ({
214
+ ...candidate,
215
+ documents: candidate.documents.map((d) => ({ id: d.id, type: d.type, title: d.title, status: d.status, dependsOn: d.dependsOn ?? [] })),
216
+ })) };
217
+ const answer = { schema: 'requirement-triage/1', ...shown, ...(lexical ? { lexicalOnly: true } : {}), promptDigest, semantic, provenance,
210
218
  graph: { status: graph.status, sourceCommit: graph.sourceCommit, graphAsOf: graph.graphAsOf, resolutionLimits: graph.resolutionLimits },
211
219
  graphBasis: { head: currentHead, governedDocumentCount: documents.length, scannedSourceCount: scanned.length },
212
220
  freshness: freshness === null ? { state: 'absent' } : freshness,
@@ -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
- reviewNeeded: import("../../review/review-targets").ReviewNeeded[];
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
- return { blocked: counts.critical > 0 || counts.important > 0, open: counts, reviewNeeded };
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
- specs: specs
143
- .filter((s) => !a?.type || s.type === a.type)
144
- .map((s) => {
145
- const parent = parentOf(s);
146
- // @implements A-SPEC-192 §5R (round 9) — the mark asks 'is this row a GOVERNED spec?',
147
- // and status alone could not answer it: an old-format document that never declared a
148
- // `type` came through with a lone `approved` and dressed exactly like a canonical row —
149
- // the misreading this REQ exists to prevent. Format and status are both grounds.
150
- const legacyFormat = (0, legacy_format_1.formatStateOf)({ id: s.id, type: s.type }).kind !== 'current';
151
- return {
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) {