@holmes-lab/holmes-kit 0.35.15 → 0.35.17

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 (33) hide show
  1. package/CHANGELOG.md +50 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/guardrail/write-target.d.ts +18 -0
  5. package/dist/holmes/guardrail/write-target.js +136 -35
  6. package/dist/holmes/hooks/pre-tool-use.js +15 -10
  7. package/dist/holmes/hooks/rtm-refresh-child.d.ts +12 -2
  8. package/dist/holmes/hooks/rtm-refresh-child.js +26 -4
  9. package/dist/holmes/mcp/handlers/graph-operations.d.ts +1 -0
  10. package/dist/holmes/mcp/handlers/graph-operations.js +4 -4
  11. package/dist/holmes/mcp/handlers/maintenance-analysis.js +39 -17
  12. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +25 -0
  13. package/dist/holmes/mcp/handlers/operator-inspection.js +60 -1
  14. package/dist/holmes/mcp/handlers/test-execution.d.ts +7 -0
  15. package/dist/holmes/mcp/handlers/test-execution.js +9 -2
  16. package/dist/holmes/mcp/handlers.d.ts +9 -0
  17. package/dist/holmes/mcp/maintenance-analyze.d.ts +21 -0
  18. package/dist/holmes/mcp/maintenance-analyze.js +1 -0
  19. package/dist/holmes/mcp/operator-recovery.js +5 -2
  20. package/dist/holmes/refresh/freshness-coordinator.d.ts +9 -0
  21. package/dist/holmes/refresh/freshness-coordinator.js +14 -4
  22. package/dist/holmes/review/missing-imports.d.ts +2 -0
  23. package/dist/holmes/review/missing-imports.js +2 -0
  24. package/dist/holmes/review/removed-names.d.ts +32 -0
  25. package/dist/holmes/review/removed-names.js +110 -0
  26. package/dist/holmes/rtm/anchor-ids.d.ts +15 -0
  27. package/dist/holmes/rtm/anchor-ids.js +45 -0
  28. package/dist/holmes/rtm/test-scope.d.ts +12 -0
  29. package/dist/holmes/rtm/test-scope.js +29 -4
  30. package/package.json +1 -1
  31. package/playbooks/publish/PLAYBOOK.md +29 -6
  32. package/dist/holmes/guardrail/write-verb-word.d.ts +0 -13
  33. package/dist/holmes/guardrail/write-verb-word.js +0 -55
@@ -1,6 +1,29 @@
1
1
  import { Spec } from '../../spec/spec-parser';
2
2
  import { SpecStore } from '../../spec/spec-store';
3
3
  import type { Approval } from '../../guardrail/risk-gate';
4
+ import type { ApprovalStatus } from '../../spec/approval-status';
5
+ /** The spec-approve request for one spec as the queue holds it now: its state and, when held, the operator's LATEST question. */
6
+ export interface ApprovalRequestState {
7
+ id: string;
8
+ state: 'pending' | 'held' | 'granted' | 'consumed' | 'denied' | 'revoked';
9
+ question?: string;
10
+ reason?: string;
11
+ ts?: string;
12
+ }
13
+ /**
14
+ * @implements A-SPEC-768
15
+ * Measured 2026-10-11 (SWE-bench Sphinx 11510, H0 arm): the operator held one request twice with two different
16
+ * questions; the worker polled `approval_status` eleven times and never saw the second, because the response reported
17
+ * the spec's seal only. The queue fold already keeps the latest `held` question (`pending[].question`, `holds[id]`);
18
+ * this reads it. Read-only; an unreadable queue is no request.
19
+ */
20
+ export declare function approvalRequestOf(root: string, specId: string): ApprovalRequestState | undefined;
21
+ /**
22
+ * @implements A-SPEC-768
23
+ * One sentence an agent can act on. Measured 2026-10-11 (HG arm): 58 `sealed: true` answers were read as "pending"
24
+ * because nothing in the response said what to do once the seal was there.
25
+ */
26
+ export declare function nextActionOf(described: Pick<ApprovalStatus, 'sealed' | 'blockers'>, request: ApprovalRequestState | undefined): string;
4
27
  export interface OperatorInspectionContext {
5
28
  listSpecs(): Promise<Spec[]>;
6
29
  readSpec: SpecStore['read'];
@@ -71,6 +94,8 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
71
94
  };
72
95
  unavailable?: "empty" | "unreadable";
73
96
  } | undefined;
97
+ nextAction: string;
98
+ request?: ApprovalRequestState | undefined;
74
99
  id: string;
75
100
  type?: string;
76
101
  status: string;
@@ -33,10 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.approvalRequestOf = approvalRequestOf;
37
+ exports.nextActionOf = nextActionOf;
36
38
  exports.createOperatorInspectionHandlers = createOperatorInspectionHandlers;
37
39
  // @implements A-SPEC-605, A-SPEC-605.1
38
40
  // @implements A-SPEC-642
39
41
  // @implements A-SPEC-631
42
+ // @implements A-SPEC-768
40
43
  const fs = __importStar(require("node:fs"));
41
44
  const path = __importStar(require("node:path"));
42
45
  const spec_store_1 = require("../../spec/spec-store");
@@ -46,6 +49,58 @@ const ledger_timeline_1 = require("../../governance/ledger-timeline");
46
49
  const provenance_ledger_1 = require("../../governance/provenance-ledger");
47
50
  const provenance_chain_1 = require("../../governance/provenance-chain");
48
51
  const approval_grants_1 = require("../../governance/approval-grants");
52
+ const approval_queue_1 = require("../../governance/approval-queue");
53
+ /**
54
+ * @implements A-SPEC-768
55
+ * Measured 2026-10-11 (SWE-bench Sphinx 11510, H0 arm): the operator held one request twice with two different
56
+ * questions; the worker polled `approval_status` eleven times and never saw the second, because the response reported
57
+ * the spec's seal only. The queue fold already keeps the latest `held` question (`pending[].question`, `holds[id]`);
58
+ * this reads it. Read-only; an unreadable queue is no request.
59
+ */
60
+ function approvalRequestOf(root, specId) {
61
+ try {
62
+ const id = (0, approval_queue_1.approvalRequestId)('spec-approve', specId);
63
+ const q = (0, approval_queue_1.readQueue)(root);
64
+ const pending = q.pending.find((p) => p.id === id);
65
+ const hold = q.holds[id];
66
+ if (pending?.hold || hold) {
67
+ const question = (pending?.hold ? pending.question : undefined) ?? hold?.question;
68
+ return { id, state: 'held', ...(question !== undefined ? { question } : {}), ...(hold?.ts ? { ts: hold.ts } : pending ? { ts: pending.lastTs } : {}) };
69
+ }
70
+ if (pending)
71
+ return { id, state: 'pending', ts: pending.lastTs };
72
+ const d = q.decisions[id];
73
+ if (!d)
74
+ return undefined;
75
+ if (d.event === 'granted')
76
+ return { id, state: d.consumedTs ? 'consumed' : 'granted', ts: d.consumedTs ?? d.ts };
77
+ return { id, state: d.event, ...(d.reason ? { reason: d.reason } : {}), ts: d.ts };
78
+ }
79
+ catch {
80
+ return undefined;
81
+ }
82
+ }
83
+ /**
84
+ * @implements A-SPEC-768
85
+ * One sentence an agent can act on. Measured 2026-10-11 (HG arm): 58 `sealed: true` answers were read as "pending"
86
+ * because nothing in the response said what to do once the seal was there.
87
+ */
88
+ function nextActionOf(described, request) {
89
+ if (described.sealed)
90
+ return 'sealed — stop polling this id; call spec_slice_approve or spec_approve for the next unsealed spec of the chain (spec_next names it).';
91
+ switch (request?.state) {
92
+ case 'held': return `held — the operator asks: ${request.question ?? '(no question recorded)'}. Resolve it in the spec or tests, then call spec_approve again.`;
93
+ case 'denied': return `denied — ${request.reason ?? 'no reason recorded'}. Do not re-request the same act; report it to the user.`;
94
+ case 'revoked': return `revoked — ${request.reason ?? 'no reason recorded'}. Do not re-request the same act; report it to the user.`;
95
+ case 'granted': return 'granted — call spec_approve now; the grant seals it.';
96
+ case 'consumed': return 'the grant was consumed but this spec is not sealed — call spec_approve again, and report its refusal to the user if it refuses.';
97
+ case 'pending': return "pending the operator's decision — wait, then call approval_status again; when sealed is true, retry spec_approve immediately.";
98
+ default: break;
99
+ }
100
+ if (described.blockers.length > 0)
101
+ return 'fix the blockers listed, then call spec_approve; no request is filed while they stand.';
102
+ return 'no approval request on file — call spec_approve to file one.';
103
+ }
49
104
  function createOperatorInspectionHandlers(context) {
50
105
  return {
51
106
  /**
@@ -261,7 +316,11 @@ function createOperatorInspectionHandlers(context) {
261
316
  advisoryIds = undefined;
262
317
  advisoryHistory = undefined;
263
318
  }
264
- return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, context.resolver(all)), ...(graphPreview ? { graphPreview } : {}),
319
+ // @implements A-SPEC-768 — the request's state and the next action ride beside the seal state.
320
+ const described = (0, approval_status_1.describeApproval)(cur.spec, context.resolver(all));
321
+ const request = typeof a.root === 'string' && a.root !== '' ? approvalRequestOf(a.root, a.id) : undefined;
322
+ const nextAction = nextActionOf(described, request);
323
+ return { ok: true, ...described, ...(request ? { request } : {}), nextAction, ...(graphPreview ? { graphPreview } : {}),
265
324
  ...(fttFulfilment ? { fttFulfilment } : {}), ...(killsAdvisory ? { killsAdvisory } : {}),
266
325
  ...(advisoryIds ? { advisoryIds } : {}), ...(advisoryHistory ? { advisoryHistory } : {}) };
267
326
  },
@@ -50,6 +50,13 @@ export declare function createTestExecutionHandlers(context: TestExecutionContex
50
50
  }[];
51
51
  };
52
52
  } | {
53
+ anchorDiagnostics?: {
54
+ hint: string;
55
+ file: string;
56
+ line: number;
57
+ separator: string;
58
+ dropped: string[];
59
+ }[] | undefined;
53
60
  calibrationClosed?: string[] | undefined;
54
61
  baselineRecorded?: string | undefined;
55
62
  scopeFallback?: "full" | undefined;
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createTestExecutionHandlers = createTestExecutionHandlers;
37
- // @implements A-SPEC-616, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-121.2, A-SPEC-121.3, A-SPEC-128, A-SPEC-130, A-SPEC-189, A-SPEC-233, A-SPEC-419, A-SPEC-433, A-SPEC-534.5, A-SPEC-534.8, A-SPEC-578.4, A-SPEC-614, A-SPEC-734
37
+ // @implements A-SPEC-616, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-121.2, A-SPEC-121.3, A-SPEC-128, A-SPEC-130, A-SPEC-189, A-SPEC-233, A-SPEC-419, A-SPEC-433, A-SPEC-534.5, A-SPEC-534.8, A-SPEC-578.4, A-SPEC-614, A-SPEC-734, A-SPEC-768.1
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");
@@ -55,6 +55,8 @@ const test_evidence_1 = require("../../review/test-evidence");
55
55
  const test_outcomes_1 = require("../../review/test-outcomes");
56
56
  const maintenance_evidence_1 = require("../maintenance-evidence");
57
57
  const bounded_io_1 = require("../../project/bounded-io");
58
+ // @implements A-SPEC-768.1 — the one sentence every anchor-separator diagnostic carries.
59
+ const ANCHOR_SEPARATOR_HINT = 'only a comma-separated list is an anchor list; ids after the separator are not attributed — write `@' + 'implements A, B` or one marker per line';
58
60
  // @implements A-SPEC-534.8
59
61
  // The governed source file a `kills` mutation targets: one that @implements the A-SPEC AND contains
60
62
  // the `where` literal. Bounded walk, skips vendored/test/hidden dirs. null when none qualifies.
@@ -168,6 +170,10 @@ function createTestExecutionHandlers(context) {
168
170
  const result = (0, test_runner_1.runTestScope)(testScope, root);
169
171
  const anchors = (0, test_scope_1.scanTestAnchors)(root);
170
172
  const executedByAspec = (0, test_evidence_1.computeExecutedByAspec)(result.executedByFile ?? {}, anchors);
173
+ // @implements A-SPEC-768.1 — an anchor list the grammar does not read is named beside the attribution it could
174
+ // not make (measured 2026-10-11: `A-SPEC-107; A-SPEC-122` counted A-SPEC-107 only, silently). Diagnosis only:
175
+ // `executedByAspec` is exactly what the grammar read.
176
+ const anchorDiagnostics = (0, test_scope_1.scanTestAnchorDiagnostics)(root).map((d) => ({ ...d, hint: ANCHOR_SEPARATOR_HINT }));
171
177
  let head = '';
172
178
  try {
173
179
  head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
@@ -218,7 +224,8 @@ function createTestExecutionHandlers(context) {
218
224
  // @implements A-SPEC-130 — the remediation rides in the answer: these are the files to anchor.
219
225
  unresolvedFiles: testScope.unresolvedFiles,
220
226
  changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}),
221
- ...(calibrationClosed ? { calibrationClosed } : {}) };
227
+ ...(calibrationClosed ? { calibrationClosed } : {}),
228
+ ...(anchorDiagnostics.length > 0 ? { anchorDiagnostics } : {}) };
222
229
  },
223
230
  };
224
231
  }
@@ -1205,6 +1205,8 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1205
1205
  };
1206
1206
  unavailable?: "empty" | "unreadable";
1207
1207
  } | undefined;
1208
+ nextAction: string;
1209
+ request?: import("./handlers/operator-inspection").ApprovalRequestState | undefined;
1208
1210
  id: string;
1209
1211
  type?: string;
1210
1212
  status: string;
@@ -1541,6 +1543,13 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1541
1543
  }[];
1542
1544
  };
1543
1545
  } | {
1546
+ anchorDiagnostics?: {
1547
+ hint: string;
1548
+ file: string;
1549
+ line: number;
1550
+ separator: string;
1551
+ dropped: string[];
1552
+ }[] | undefined;
1544
1553
  calibrationClosed?: string[] | undefined;
1545
1554
  baselineRecorded?: string | undefined;
1546
1555
  scopeFallback?: "full" | undefined;
@@ -127,6 +127,16 @@ export interface MaintenanceAnalysisInput {
127
127
  specifier: string;
128
128
  candidates: string[];
129
129
  }>;
130
+ /**
131
+ * @implements A-SPEC-759.2
132
+ * Unchanged files that still use a top-level name a changed file no longer defines
133
+ * (`review/removed-names.ts`), computed by the caller. Carried into `impacts.removedNameUsers`.
134
+ */
135
+ removedNameUsers?: Array<{
136
+ file: string;
137
+ imports: string;
138
+ name: string;
139
+ }>;
130
140
  /**
131
141
  * @implements A-SPEC-388
132
142
  * Per-file multipliers from how much each file's COMMIT PROSE talks like the request, normalised
@@ -366,6 +376,17 @@ export interface MaintenanceAnalysis {
366
376
  specifier: string;
367
377
  candidates: string[];
368
378
  }>;
379
+ /**
380
+ * @implements A-SPEC-759.2
381
+ * Files the change has BROKEN and not touched: `file` imports the changed file `imports` and
382
+ * still uses `name`, a top-level name that file no longer defines. Deterministic; present only
383
+ * when there is one.
384
+ */
385
+ removedNameUsers?: Array<{
386
+ file: string;
387
+ imports: string;
388
+ name: string;
389
+ }>;
369
390
  /**
370
391
  * @implements A-SPEC-290
371
392
  * Which impacted contracts were actually OBSERVED executing, and whether that observation can
@@ -1231,6 +1231,7 @@ function analyzeMaintenance(input) {
1231
1231
  rankedImpact,
1232
1232
  importedByFiles,
1233
1233
  ...((input.missingNewFiles?.length ?? 0) > 0 ? { missingNewFiles: input.missingNewFiles } : {}),
1234
+ ...((input.removedNameUsers?.length ?? 0) > 0 ? { removedNameUsers: input.removedNameUsers } : {}),
1234
1235
  unresolvedRelations: input.resolution ?? null,
1235
1236
  runtimeObserved: {
1236
1237
  status: runtimeStatus,
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.operatorRecovery = operatorRecovery;
37
- // @implements A-SPEC-754, A-SPEC-532.3
37
+ // @implements A-SPEC-754, A-SPEC-532.3, A-SPEC-768
38
38
  const path = __importStar(require("node:path"));
39
39
  const unsafeDisplay = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
40
40
  function literal(value, platform) {
@@ -58,9 +58,12 @@ function operatorRecovery(root, target, operation, options) {
58
58
  return `\n[승인 대기 ${id}] The request was recorded. Use the installed approval UI; a path exceeds the safe command display limit. No truncated command is provided.`;
59
59
  // @implements A-SPEC-532.3 — the resident surface is offered beside the one-off command (owner, 2026-10-04:
60
60
  // "why am I still pasting commands"): one key per arriving request.
61
+ // @implements A-SPEC-768 — the three lines above are the operator's; measured 2026-10-11 (HG arm) the agent read
62
+ // "keep the approval surface open" as its own instruction and polled a sealed spec 58 times. One line is the agent's.
61
63
  return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${literal(id, platform)}`
62
64
  + `\nOr keep the approval surface open and decide each arriving request with one key: ${command} --watch`
63
- + `\nAfter official approval, retry ${operation ? display(operation) : 'the original MCP operation'} for target ${display(target)} in the same workspace. Do not retry until approval is available.`;
65
+ + `\nAfter official approval, retry ${operation ? display(operation) : 'the original MCP operation'} for target ${display(target)} in the same workspace. Do not retry until approval is available.`
66
+ + '\nAgent: check approval_status for the target; sealed:true or request.state granted means retry now — polling a sealed spec is wasted; request.state held carries the operator\'s question.';
64
67
  },
65
68
  };
66
69
  }
@@ -1,4 +1,10 @@
1
1
  export type FreshnessLane = 'current' | 'refreshing' | 'retry-at' | 'failed' | 'suppressed' | 'not-adopted' | 'stale';
2
+ /** Why a lane failed, as the worker saw it: the stage that failed and the error's message, bounded to 300 characters. */
3
+ export interface RefreshFailure {
4
+ stage: 'graph' | 'source' | 'requirement' | 'child';
5
+ reason: string;
6
+ }
7
+ export declare const REFRESH_FAILURE_REASON_MAX = 300;
2
8
  export interface FreshnessReceipt {
3
9
  schema: 'fresh-evidence/1';
4
10
  workspaceId: string;
@@ -12,6 +18,8 @@ export interface FreshnessReceipt {
12
18
  graph: FreshnessLane;
13
19
  sourceSemantic: FreshnessLane;
14
20
  requirementSemantic: FreshnessLane;
21
+ /** @implements A-SPEC-768.4 — present only on a completion that failed; never carried into the next lease. */
22
+ failure?: RefreshFailure;
15
23
  }
16
24
  export interface RefreshRequest {
17
25
  workspaceId: string;
@@ -23,6 +31,7 @@ export interface RefreshCompletion {
23
31
  sourceSemantic: FreshnessLane;
24
32
  requirementSemantic: FreshnessLane;
25
33
  head: string | null;
34
+ failure?: RefreshFailure;
26
35
  }
27
36
  export declare const FRESHNESS_RECEIPT_FILE: string;
28
37
  export declare const FRESHNESS_LEASE_MS: number;
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = void 0;
36
+ exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
37
37
  exports.intakeUsable = intakeUsable;
38
38
  exports.lexicalOnly = lexicalOnly;
39
39
  exports.readFreshnessReceipt = readFreshnessReceipt;
@@ -41,7 +41,7 @@ exports.requestRefresh = requestRefresh;
41
41
  exports.ownsLease = ownsLease;
42
42
  exports.completeRefresh = completeRefresh;
43
43
  exports.workspaceIdFor = workspaceIdFor;
44
- // @implements A-SPEC-719
44
+ // @implements A-SPEC-719, A-SPEC-768.4
45
45
  /**
46
46
  * The durable source of truth for refresh work. A receipt names the workspace and
47
47
  * commit it describes, so an old detached worker cannot make a newer tree look
@@ -51,6 +51,7 @@ const crypto = __importStar(require("node:crypto"));
51
51
  const fs = __importStar(require("node:fs"));
52
52
  const path = __importStar(require("node:path"));
53
53
  const workspace_identity_1 = require("../project/workspace-identity");
54
+ exports.REFRESH_FAILURE_REASON_MAX = 300;
54
55
  exports.FRESHNESS_RECEIPT_FILE = path.join('.ax', 'state', 'fresh-evidence.json');
55
56
  // A crashed detached child becomes eligible quickly. This is intentionally much
56
57
  // shorter than the former 30-minute marker window, while still bounding spawn bursts.
@@ -93,7 +94,9 @@ function isReceipt(value) {
93
94
  && typeof r.requirementSemantic === 'string' && lanes.has(r.requirementSemantic)
94
95
  && (r.startedAt === undefined || typeof r.startedAt === 'string')
95
96
  && (r.completedAt === undefined || typeof r.completedAt === 'string')
96
- && (r.retryAt === undefined || typeof r.retryAt === 'string');
97
+ && (r.retryAt === undefined || typeof r.retryAt === 'string')
98
+ // @implements A-SPEC-768.4 — a receipt without the field is still a receipt (older builds wrote none).
99
+ && (r.failure === undefined || (!!r.failure && typeof r.failure === 'object' && typeof r.failure.stage === 'string' && typeof r.failure.reason === 'string'));
97
100
  }
98
101
  function storedReceipt(root) {
99
102
  try {
@@ -202,9 +205,16 @@ function completeRefresh(root, generation, completion, now) {
202
205
  : judged.includes('suppressed') ? 'suppressed'
203
206
  : judged.includes('not-adopted') ? 'not-adopted'
204
207
  : retry ? 'retry-at' : 'failed';
208
+ // @implements A-SPEC-768.4 — `failure` comes from THIS completion only, bounded; a lease never inherits the last one.
209
+ const { failure: _previousFailure, ...base } = previous;
210
+ const failure = completion.failure
211
+ ? { stage: completion.failure.stage, reason: String(completion.failure.reason).slice(0, exports.REFRESH_FAILURE_REASON_MAX) }
212
+ : undefined;
213
+ const { failure: _completionFailure, ...completed } = completion;
205
214
  const receipt = {
206
- ...previous, ...completion, state, completedAt: now.toISOString(),
215
+ ...base, ...completed, state, completedAt: now.toISOString(),
207
216
  ...(retry ? { retryAt: new Date(now.getTime() + exports.FRESHNESS_RETRY_MS).toISOString() } : {}),
217
+ ...(failure ? { failure } : {}),
208
218
  };
209
219
  writeReceipt(root, receipt);
210
220
  return receipt;
@@ -14,4 +14,6 @@ export interface MissingNewFilesInput {
14
14
  }
15
15
  export declare const MISSING_NEW_FILES_MAX = 20;
16
16
  export declare const MISSING_NEW_FILE_CANDIDATES = 4;
17
+ /** Exported for A-SPEC-759.2, which asks the inverse question: which import pointed at a file that is gone. */
18
+ export declare function candidatesOf(fromFile: string, specifier: string): string[] | null;
17
19
  export declare function missingNewFiles(input: MissingNewFilesInput): MissingNewFile[];
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.MISSING_NEW_FILE_CANDIDATES = exports.MISSING_NEW_FILES_MAX = void 0;
37
+ exports.candidatesOf = candidatesOf;
37
38
  exports.missingNewFiles = missingNewFiles;
38
39
  // @implements A-SPEC-759
39
40
  /**
@@ -64,6 +65,7 @@ const DECLARATIONS = ['.d.ts', '.d.mts', '.d.cts'];
64
65
  const DECLARATION_OF_EMITTED = [
65
66
  ['.js', '.d.ts'], ['.jsx', '.d.ts'], ['.mjs', '.d.mts'], ['.cjs', '.d.cts'],
66
67
  ];
68
+ /** Exported for A-SPEC-759.2, which asks the inverse question: which import pointed at a file that is gone. */
67
69
  function candidatesOf(fromFile, specifier) {
68
70
  const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
69
71
  if (base === '..' || base.startsWith('../') || base === '.' || base === '')
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The unchanged files a change has just broken.
3
+ *
4
+ * `missing-imports` names the file a change still has to create. The same necessity runs the other
5
+ * way: a change that removes or renames a top-level name leaves every file that imports the changed
6
+ * file and still uses that name in need of a change too. Measured before this was built (north-star
7
+ * goal document, H11), against every path each commit touched: 22 namings on a public TypeScript
8
+ * repository and 30 on a public Python repository, all correct, and 13 more on four smaller windows.
9
+ *
10
+ * The evidence is deliberately coarse — "imports the file" and "has the name as a word" — and the
11
+ * precise alternative lost: following resolved call edges from the removed symbol scored 0.46–1.00
12
+ * in the same measurement, because a member call is resolved by name. Hence top-level names only,
13
+ * and no call graph.
14
+ */
15
+ import { type ScannedFile } from '../cpg/cpg-scanner';
16
+ export interface RemovedNameUser {
17
+ file: string;
18
+ imports: string;
19
+ name: string;
20
+ }
21
+ export interface RemovedNameUsersInput {
22
+ scanned: readonly ScannedFile[];
23
+ changedFiles: readonly string[];
24
+ /** The file's text before the change; `null` when it did not exist; `undefined` when unknown. Both name nothing. */
25
+ priorText: (file: string) => string | null | undefined;
26
+ /** The file's text in the working tree; `null` when it is not there. */
27
+ currentText: (file: string) => string | null;
28
+ /** Top-level names a text defines. Defaults to the product parser; injected by tests. */
29
+ topLevelNames?: (code: string, file: string) => string[];
30
+ }
31
+ export declare const REMOVED_NAME_USERS_MAX = 20;
32
+ export declare function removedNameUsers(input: RemovedNameUsersInput): RemovedNameUser[];
@@ -0,0 +1,110 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.REMOVED_NAME_USERS_MAX = void 0;
4
+ exports.removedNameUsers = removedNameUsers;
5
+ // @implements A-SPEC-759.2
6
+ /**
7
+ * The unchanged files a change has just broken.
8
+ *
9
+ * `missing-imports` names the file a change still has to create. The same necessity runs the other
10
+ * way: a change that removes or renames a top-level name leaves every file that imports the changed
11
+ * file and still uses that name in need of a change too. Measured before this was built (north-star
12
+ * goal document, H11), against every path each commit touched: 22 namings on a public TypeScript
13
+ * repository and 30 on a public Python repository, all correct, and 13 more on four smaller windows.
14
+ *
15
+ * The evidence is deliberately coarse — "imports the file" and "has the name as a word" — and the
16
+ * precise alternative lost: following resolved call edges from the removed symbol scored 0.46–1.00
17
+ * in the same measurement, because a member call is resolved by name. Hence top-level names only,
18
+ * and no call graph.
19
+ */
20
+ const cpg_scanner_1 = require("../cpg/cpg-scanner");
21
+ const import_resolver_1 = require("../cpg/import-resolver");
22
+ const language_parser_1 = require("../cpg/language-parser");
23
+ const missing_imports_1 = require("./missing-imports");
24
+ exports.REMOVED_NAME_USERS_MAX = 20;
25
+ const MIN_NAME_LENGTH = 3;
26
+ const SCRIPT_FILE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
27
+ const READ_FILE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py)$/;
28
+ function parsedTopLevelNames(code, file) {
29
+ return new language_parser_1.TreeSitterTsParser().extractSymbols(code, (0, cpg_scanner_1.langForPath)(file))
30
+ .map((symbol) => symbol.qualifiedName).filter((name) => !name.includes('.'));
31
+ }
32
+ const escaped = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
33
+ const wordOf = (name) => new RegExp(`(?<![\\w$])${escaped(name)}(?![\\w$])`);
34
+ function removedNameUsers(input) {
35
+ if (input.changedFiles.length === 0)
36
+ return [];
37
+ const changed = new Set(input.changedFiles);
38
+ const byPath = new Map(input.scanned.map((file) => [file.sourcePath, file]));
39
+ const namesIn = input.topLevelNames ?? parsedTopLevelNames;
40
+ // What each changed file no longer defines.
41
+ const removedBy = new Map();
42
+ const deletedScripts = new Set();
43
+ for (const file of changed) {
44
+ if (!READ_FILE.test(file))
45
+ continue;
46
+ const prior = input.priorText(file);
47
+ if (typeof prior !== 'string')
48
+ continue;
49
+ let earlier;
50
+ try {
51
+ earlier = namesIn(prior, file);
52
+ }
53
+ catch {
54
+ continue;
55
+ }
56
+ const scannedNow = byPath.get(file);
57
+ const current = input.currentText(file);
58
+ const still = new Set((scannedNow?.symbols ?? []).map((symbol) => symbol.qualifiedName));
59
+ const removed = [...new Set(earlier)]
60
+ .filter((name) => !name.includes('.') && name.length >= MIN_NAME_LENGTH && !still.has(name))
61
+ // A name still written in the file — re-exported, or turned into an alias the scanner does not list — is not gone.
62
+ .filter((name) => current === null || !wordOf(name).test(current))
63
+ .sort();
64
+ if (removed.length === 0)
65
+ continue;
66
+ removedBy.set(file, removed);
67
+ if (current === null && scannedNow === undefined && SCRIPT_FILE.test(file))
68
+ deletedScripts.add(file);
69
+ }
70
+ if (removedBy.size === 0)
71
+ return [];
72
+ const { resolve } = (0, import_resolver_1.createImportResolver)(input.scanned);
73
+ const rows = [];
74
+ for (const user of input.scanned) {
75
+ if (changed.has(user.sourcePath))
76
+ continue;
77
+ const targets = new Set();
78
+ for (const edge of user.edges ?? []) {
79
+ if (edge.rel !== 'imports')
80
+ continue;
81
+ const target = resolve(user.sourcePath, edge.to);
82
+ if (target !== null) {
83
+ if (removedBy.has(target))
84
+ targets.add(target);
85
+ continue;
86
+ }
87
+ // The import resolves to nothing: it may have pointed at a file this change deleted.
88
+ if (deletedScripts.size === 0 || !(edge.to.startsWith('./') || edge.to.startsWith('../')))
89
+ continue;
90
+ for (const candidate of (0, missing_imports_1.candidatesOf)(user.sourcePath, edge.to) ?? [])
91
+ if (deletedScripts.has(candidate))
92
+ targets.add(candidate);
93
+ }
94
+ if (targets.size === 0)
95
+ continue;
96
+ let text;
97
+ for (const target of [...targets].sort()) {
98
+ if (text === undefined)
99
+ text = input.currentText(user.sourcePath);
100
+ if (text === null)
101
+ break;
102
+ const name = removedBy.get(target).find((candidate) => wordOf(candidate).test(text));
103
+ if (name !== undefined)
104
+ rows.push({ file: user.sourcePath, imports: target, name });
105
+ }
106
+ }
107
+ return rows
108
+ .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.imports < b.imports ? -1 : a.imports > b.imports ? 1 : 0))
109
+ .slice(0, exports.REMOVED_NAME_USERS_MAX);
110
+ }
@@ -34,3 +34,18 @@ export declare function anchorSpecSites(text: string): Array<{
34
34
  }>;
35
35
  /** Flattened wrong-kind ids (a governed id anchored where only A-SPEC belongs) — anywhere in a list. */
36
36
  export declare function wrongKindAnchorIds(text: string): string[];
37
+ /** A list the comma grammar does not read: the first non-comma joiner after a list, and every id the join drops. */
38
+ export interface AnchorListDiagnostic {
39
+ line: number;
40
+ separator: string;
41
+ dropped: string[];
42
+ }
43
+ /**
44
+ * @implements A-SPEC-768.1
45
+ * Measured 2026-10-11 (SWE-bench Sphinx 11510, HB arm): `# @implements A-SPEC-107; A-SPEC-122` attributed the file
46
+ * to A-SPEC-107 only and nothing said so — the C12 shape again, with a new separator. The grammar above stays the ONE
47
+ * grammar; this names what it does not read, per marker: the first `;`, `|`, `&`, `/` or `and` that follows the comma
48
+ * chain and is itself followed by a governed id, with every id of the chain after it. String literals are stripped the
49
+ * same way the anchor readers strip them, so a diagnostic never names text some code merely holds.
50
+ */
51
+ export declare function anchorListDiagnostics(text: string): AnchorListDiagnostic[];
@@ -1,5 +1,6 @@
1
1
  "use strict";
2
2
  // @implements A-SPEC-503.1
3
+ // @implements A-SPEC-768.1
3
4
  /**
4
5
  * The ONE comma-list grammar for anchor lines — C12, dogfooded: four parsers each captured only
5
6
  * the first id of a comma-listed anchor (`… <marker> A-SPEC-…110, …219`), so every id after the
@@ -15,6 +16,7 @@ exports.implementsIdLists = implementsIdLists;
15
16
  exports.anchorSpecIds = anchorSpecIds;
16
17
  exports.anchorSpecSites = anchorSpecSites;
17
18
  exports.wrongKindAnchorIds = wrongKindAnchorIds;
19
+ exports.anchorListDiagnostics = anchorListDiagnostics;
18
20
  // @implements A-SPEC-504.1
19
21
  // The ONE string-literal preprocessing every anchor-judging surface shares. Measured 2026-09-01:
20
22
  // the coverage scanner stripped literals while the claim gate judged raw text, so a legitimate
@@ -123,3 +125,46 @@ function anchorSpecSites(text) {
123
125
  function wrongKindAnchorIds(text) {
124
126
  return [...new Set(implementsIdLists(text).flat().filter((id) => !id.startsWith('A-SPEC-')))];
125
127
  }
128
+ const ID_RE = new RegExp(ID, 'g');
129
+ const DROPPED_TAIL_RE = new RegExp(String.raw `^[ \t]*(?:([;|&/])[ \t]*|(and)[ \t]+)(${ID})`);
130
+ const DROPPED_COMMA_RE = new RegExp(String.raw `^(?:[ \t]*,[ \t]*${ID})+`);
131
+ /**
132
+ * @implements A-SPEC-768.1
133
+ * Measured 2026-10-11 (SWE-bench Sphinx 11510, HB arm): `# @implements A-SPEC-107; A-SPEC-122` attributed the file
134
+ * to A-SPEC-107 only and nothing said so — the C12 shape again, with a new separator. The grammar above stays the ONE
135
+ * grammar; this names what it does not read, per marker: the first `;`, `|`, `&`, `/` or `and` that follows the comma
136
+ * chain and is itself followed by a governed id, with every id of the chain after it. String literals are stripped the
137
+ * same way the anchor readers strip them, so a diagnostic never names text some code merely holds.
138
+ */
139
+ function anchorListDiagnostics(text) {
140
+ const stripped = stripStringLiterals(text);
141
+ const out = [];
142
+ let line = 1;
143
+ let lineAt = 0;
144
+ for (const m of stripped.matchAll(LIST_RE)) {
145
+ const at = m.index ?? 0;
146
+ for (; lineAt < at; lineAt++)
147
+ if (stripped.charCodeAt(lineAt) === 10)
148
+ line++;
149
+ let pos = at + m[0].length;
150
+ let separator = null;
151
+ const dropped = [];
152
+ for (;;) {
153
+ const tail = DROPPED_TAIL_RE.exec(stripped.slice(pos));
154
+ if (!tail)
155
+ break;
156
+ separator ??= tail[1] ?? tail[2];
157
+ dropped.push(tail[3]);
158
+ pos += tail[0].length;
159
+ const chain = DROPPED_COMMA_RE.exec(stripped.slice(pos));
160
+ if (chain) {
161
+ for (const id of chain[0].matchAll(ID_RE))
162
+ dropped.push(id[0]);
163
+ pos += chain[0].length;
164
+ }
165
+ }
166
+ if (separator !== null)
167
+ out.push({ line, separator, dropped });
168
+ }
169
+ return out;
170
+ }
@@ -135,4 +135,16 @@ export declare function extractAnchors(source: string): string[];
135
135
  * paths → the impacted-spec ids they anchor. Pure-ish (fs read only); resilient to unreadable files.
136
136
  */
137
137
  export declare function scanTestAnchors(root: string): Record<string, string[]>;
138
+ /**
139
+ * @implements A-SPEC-768.1
140
+ * The anchor lists in test files that the comma grammar does not read (`A; B`, `A | B`, `A and B`): the same files
141
+ * `scanTestAnchors` attributes, the same string stripping, and only lines that are anchor lines (a comment with the
142
+ * marker) — so a diagnostic names exactly an attribution the scan above could not make.
143
+ */
144
+ export declare function scanTestAnchorDiagnostics(root: string): Array<{
145
+ file: string;
146
+ line: number;
147
+ separator: string;
148
+ dropped: string[];
149
+ }>;
138
150
  export declare function computeTestScope(impactedSpecsRaw: string[], testAnchors: Record<string, string[]>, specs: Spec[], coverageGaps?: string[], cfg?: TestScopeThresholds, extras?: TestScopeExtras): TestScope;