@holmes-lab/holmes-kit 0.32.0 → 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.
@@ -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) {
@@ -469,7 +469,14 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
469
469
  }>;
470
470
  review_status: (a: {
471
471
  root: string;
472
+ detail?: unknown;
472
473
  }) => Promise<{
474
+ ok: boolean;
475
+ reason: string;
476
+ blocked?: undefined;
477
+ open?: undefined;
478
+ reviewNeeded?: undefined;
479
+ } | {
473
480
  blocked: boolean;
474
481
  open: {
475
482
  critical: number;
@@ -477,6 +484,25 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
477
484
  minor: number;
478
485
  };
479
486
  reviewNeeded: import("../review/review-targets").ReviewNeeded[];
487
+ ok?: undefined;
488
+ reason?: undefined;
489
+ } | {
490
+ reviewNeeded: Array<{
491
+ spec: string;
492
+ files: string[];
493
+ signals: number;
494
+ }>;
495
+ reviewNeededTotal: number;
496
+ reviewNeededOmitted?: number;
497
+ note?: string;
498
+ blocked: boolean;
499
+ open: {
500
+ critical: number;
501
+ important: number;
502
+ minor: number;
503
+ };
504
+ ok?: undefined;
505
+ reason?: undefined;
480
506
  }>;
481
507
  risk_check: (a: {
482
508
  root?: string;
@@ -494,7 +520,8 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
494
520
  reverse_scan: (a: {
495
521
  root: string;
496
522
  maxFlagged?: number;
497
- }) => Promise<{
523
+ detail?: unknown;
524
+ }) => Promise<Record<string, unknown> | {
498
525
  root: string;
499
526
  isGit: boolean;
500
527
  scanned: number;
@@ -1203,17 +1230,26 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1203
1230
  } | {
1204
1231
  ok: boolean;
1205
1232
  reason: string;
1233
+ blockers: string[];
1234
+ approvalIntent?: undefined;
1235
+ conflict?: undefined;
1236
+ } | {
1237
+ ok: boolean;
1238
+ reason: string;
1239
+ blockers?: undefined;
1206
1240
  approvalIntent?: undefined;
1207
1241
  conflict?: undefined;
1208
1242
  } | {
1209
1243
  ok: boolean;
1210
1244
  reason: string;
1211
1245
  approvalIntent: ApprovalIntent;
1246
+ blockers?: undefined;
1212
1247
  conflict?: undefined;
1213
1248
  } | {
1214
1249
  ok: boolean;
1215
1250
  reason: string;
1216
1251
  conflict: import("../spec/version-conflict").ConflictDetail;
1252
+ blockers?: undefined;
1217
1253
  approvalIntent?: undefined;
1218
1254
  } | {
1219
1255
  dismissUnknown?: string[] | undefined;
@@ -1234,18 +1270,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1234
1270
  digest: string;
1235
1271
  ok?: undefined;
1236
1272
  reason?: undefined;
1273
+ blockers?: undefined;
1237
1274
  approvalIntent?: undefined;
1238
1275
  conflict?: undefined;
1239
1276
  }>;
1240
- spec_list: (a: any) => Promise<{
1241
- specs: {
1242
- legacy?: boolean | undefined;
1243
- parent?: string | undefined;
1244
- id: string;
1245
- type: import("../spec/spec-types").SpecType;
1246
- status: "draft" | "review" | "approved" | "outdated";
1247
- }[];
1248
- }>;
1277
+ spec_list: (a: any) => Promise<Record<string, any>>;
1249
1278
  spec_next: (a?: {
1250
1279
  id?: string;
1251
1280
  }) => Promise<{
@@ -1351,15 +1380,15 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1351
1380
  counts: Record<string, Record<string, number>>;
1352
1381
  notApproved: {
1353
1382
  id: string;
1354
- type: string;
1355
- status: string;
1383
+ type: import("../spec/spec-types").SpecType;
1384
+ status: "draft" | "review" | "approved" | "outdated";
1356
1385
  }[];
1357
1386
  notApprovedTotal: number;
1358
1387
  };
1359
1388
  specs: {
1360
1389
  id: string;
1361
- type: string;
1362
- status: string;
1390
+ type: import("../spec/spec-types").SpecType;
1391
+ status: "draft" | "review" | "approved" | "outdated";
1363
1392
  }[];
1364
1393
  matched: number;
1365
1394
  ok?: undefined;
@@ -4,7 +4,7 @@ exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH
4
4
  exports.unquoteGitPath = unquoteGitPath;
5
5
  exports.analyzeMaintenance = analyzeMaintenance;
6
6
  exports.boundAnalysis = boundAnalysis;
7
- // @implements A-SPEC-745, A-SPEC-741, A-SPEC-740, A-SPEC-725, A-SPEC-310
7
+ // @implements A-SPEC-745, A-SPEC-741, A-SPEC-741.1, A-SPEC-740, A-SPEC-725, A-SPEC-310
8
8
  // @implements A-SPEC-295
9
9
  // @implements A-SPEC-294
10
10
  // @implements A-SPEC-293
@@ -25,6 +25,7 @@ const localize_1 = require("../rtm/localize");
25
25
  // lookups must key identically or the coverage reported is about nothing.
26
26
  const vector_coverage_1 = require("../semantic/vector-coverage");
27
27
  const admission_1 = require("../semantic/admission");
28
+ const unreadable_paths_1 = require("../semantic/unreadable-paths");
28
29
  const dense_retrieval_1 = require("../review/dense-retrieval");
29
30
  const test_scope_1 = require("../rtm/test-scope");
30
31
  const scope_1 = require("../review/scope");
@@ -58,6 +59,26 @@ const LANGUAGE_NAMES = {
58
59
  '.sh': ['shell', 'bash', 'sh'], '.rb': ['ruby', 'rails'], '.php': ['php'], '.kt': ['kotlin'], '.kts': ['kotlin'],
59
60
  '.swift': ['swift'], '.scala': ['scala'], '.ex': ['elixir'], '.exs': ['elixir'], '.lua': ['lua'],
60
61
  };
62
+ /** @implements A-SPEC-741.1 — the same names as a Korean or Japanese request writes them (substring match). */
63
+ const LANGUAGE_NAMES_CJK = {
64
+ '.sh': ['셸', '쉘', '배시', '스크립트', 'シェル', 'スクリプト'], '.rb': ['루비', '레일즈', 'ルビー'],
65
+ '.kt': ['코틀린', 'コトリン'], '.kts': ['코틀린', 'コトリン'], '.swift': ['스위프트', 'スウィフト'], '.scala': ['스칼라'],
66
+ '.ex': ['엘릭서'], '.exs': ['엘릭서'], '.lua': ['루아'],
67
+ };
68
+ /**
69
+ * @implements A-SPEC-741.1 — a leading conventional-commit type word is not about any file: `feat`
70
+ * met `create-new-feature.sh` through the 4-letter prefix rule in 28 of 60 replayed Korean requests.
71
+ * The scope that may follow it (`fix(holmes):`) stays — it names the area the author meant.
72
+ */
73
+ const COMMIT_TYPE_WORD = /^\s*(feat|fix|chore|docs|refactor|perf|style|revert|harden)(?=(\([^)]*\))?!?:)/i;
74
+ /**
75
+ * @implements A-SPEC-741.1 — an ASCII token that can be compared with a path: 3+ characters with a
76
+ * letter, not a spec-id fragment (`req`, `spec`, `adr`, `goal`) nor an id-shaped token (`f079`, `516`).
77
+ */
78
+ function isComparableWord(token) {
79
+ return token.length >= 3 && /[a-z]/.test(token) && !/^(req|spec|aspec|hspec|tspec|cspec|adr|goal)$/.test(token)
80
+ && !/^[a-z]{0,2}\d+$/.test(token);
81
+ }
61
82
  // @implements A-SPEC-740
62
83
  exports.CONFIDENCE_NOTE = 'confidence is not calibrated: it counts which kinds of evidence were present, '
63
84
  + 'does not predict accuracy, and must not be used to weight answers or to narrow a test scope.';
@@ -767,15 +788,17 @@ function analyzeMaintenance(input) {
767
788
  // Review round 1 (2026-09-30): where the rule cannot judge it leans to "relevant" — a false
768
789
  // "unrelated" is false confidence. Raw tokens (length >= 2, no stop list: `ci`, `db`, `test` are
769
790
  // names), a prefix match from 4 characters (`session`/`sessions`), trailing punctuation stripped
770
- // from request paths (`ci.sh.`), any non-ASCII letter in the request (a Korean or Japanese request
771
- // cannot be compared with ASCII paths), and a capped path list all count as "about the change".
791
+ // from request paths (`ci.sh.`), and a capped path list all count as "about the change". A non-ASCII
792
+ // request used to count too; A-SPEC-741.1 judges its non-ASCII part by meaning instead (below).
772
793
  const requestLower = input.request.toLowerCase();
773
794
  // Review round 2: a Set, capped — a 500 KB request cost 2.9 s against 5,000 paths when the tokens were
774
795
  // an array compared inside the per-file loop.
775
796
  // Round 3: de-duplicate FIRST, then cap — a pasted log of repeated lines pushed the file's name past
776
797
  // a cap taken over raw tokens.
777
798
  // Round 4: tokens over 64 characters (a pasted hex blob, a minified line) are not words.
778
- const requestTokens = new Set([...new Set(rawTokens(input.request).filter((t) => t.length <= 64))].slice(0, 4096));
799
+ // A-SPEC-741.1: a leading commit type word (`feat:`, `fix(scope):`) is not compared; the scope is.
800
+ const comparableRequest = input.request.replace(COMMIT_TYPE_WORD, '');
801
+ const requestTokens = new Set([...new Set(rawTokens(comparableRequest).filter((t) => t.length <= 64))].slice(0, 4096));
779
802
  const requestStems = new Set([...requestTokens].filter((t) => t.length >= 5).map((t) => t.slice(0, 5)));
780
803
  // Every prefix (>= 4 chars) of every request token, so "a path token is a prefix of a request word"
781
804
  // (`auth` / `authentication`) is one lookup instead of a scan.
@@ -803,6 +826,35 @@ function analyzeMaintenance(input) {
803
826
  // A LETTER outside ASCII (Hangul, Kana, …) — not an em dash or a curly quote, which every commit subject here uses.
804
827
  const requestIsNonAscii = /(?![\x00-\x7f])\p{L}/u.test(input.request);
805
828
  const pathsCapped = input.coverage.unsupportedFilesTruncated === true;
829
+ // @implements A-SPEC-741.1 — a non-ASCII request is no longer relevant to every unreadable language.
830
+ // Its ASCII words are compared like any request's; what they cannot reach, the Korean or Japanese
831
+ // part may still name (`세션 격리 isolate` for `app/session_store.rb`), so that part is judged by
832
+ // meaning against the warmed path vectors. It is "outside the change" only when every file of the
833
+ // language has a vector and all sit below the model's measured threshold — anything the rule cannot
834
+ // judge (no comparable word, no tier, no threshold, a missing vector) stays relevant.
835
+ const hasComparableWord = [...requestTokens].some(isComparableWord);
836
+ const judgedByMeaning = [];
837
+ const outsideByMeaning = (ext, files) => {
838
+ const sem = input.semantic;
839
+ if (!hasComparableWord || !sem || sem.queryVector === null)
840
+ return false;
841
+ const threshold = unreadable_paths_1.UNREADABLE_PATH_THRESHOLDS[sem.label];
842
+ if (threshold === undefined)
843
+ return false;
844
+ let max = -1;
845
+ for (const file of files) {
846
+ const vector = sem.cachedDocVector((0, unreadable_paths_1.unreadablePathText)(file));
847
+ if (vector === null)
848
+ return false;
849
+ const c = (0, dense_retrieval_1.cosine)(sem.queryVector, vector);
850
+ if (c >= threshold)
851
+ return false;
852
+ if (c > max)
853
+ max = c;
854
+ }
855
+ judgedByMeaning.push({ ext, label: sem.label, max, threshold });
856
+ return true;
857
+ };
806
858
  const relevantUnsupported = input.coverage.unsupportedLanguages.filter((language) => {
807
859
  if (!language.startsWith('.'))
808
860
  return true;
@@ -816,11 +868,15 @@ function analyzeMaintenance(input) {
816
868
  // Review round 2: a request that names the language itself (`.sh`, `shell`, `kotlin`) is about it.
817
869
  if (requestTokens.has(ext.slice(1)) || (LANGUAGE_NAMES[ext] ?? []).some((name) => requestTokens.has(name)))
818
870
  return true;
871
+ if ((LANGUAGE_NAMES_CJK[ext] ?? []).some((name) => input.request.includes(name)))
872
+ return true;
819
873
  const files = (input.coverage.unsupportedFiles ?? []).filter((file) => file.toLowerCase().endsWith(ext));
820
- if (pathsCapped || (requestIsNonAscii && files.length > 0))
874
+ if (pathsCapped)
821
875
  return true;
822
876
  // Every token of the path — folders too (`app/session/store.rb`) — exact, or sharing a 5-letter stem.
823
- return files.some((file) => rawTokens(file.slice(0, -ext.length)).some(tokenMeetsRequest));
877
+ if (files.some((file) => rawTokens(file.slice(0, -ext.length)).some(tokenMeetsRequest)))
878
+ return true;
879
+ return requestIsNonAscii && files.length > 0 && !outsideByMeaning(ext, files);
824
880
  });
825
881
  // The TEST SCOPE keeps every language (A-SPEC-741 revision): relevance decides the classification
826
882
  // only. Dropping the unrelated ones from the scope let anchor-based narrowing miss tests on replay.
@@ -858,6 +914,8 @@ function analyzeMaintenance(input) {
858
914
  const outside = unsupportedLanguages.filter((language) => !relevantUnsupported.includes(language));
859
915
  unknowns.push(`Unsupported languages are outside the evidence basis: ${unsupportedLanguages.join(', ')}`
860
916
  + (outside.length > 0 ? ` (${outside.join(', ')} judged outside this change for the classification: no changed file, request path or path-sharing file names it; the test scope still counts it)` : '')
917
+ // @implements A-SPEC-741.1 — say which languages a non-ASCII request was judged against by meaning.
918
+ + judgedByMeaning.map((j) => ` (${j.ext} judged outside this change by meaning (${j.label}: max ${j.max.toFixed(2)} < ${j.threshold.toFixed(2)}))`).join('')
861
919
  + (pathsCapped ? ' (the list of unreadable files was capped, so every language counts as about this change)' : ''));
862
920
  }
863
921
  if (truncationMarkers.length > 0) {
@@ -255,10 +255,20 @@ exports.TOOL_SCHEMAS = {
255
255
  },
256
256
  },
257
257
  spec_list: {
258
- description: `List all specs (id, type, status; plus parent when depends_on names one, and legacy: true when the status is outside the canonical ${spec_types_1.SPEC_STATUSES.join('|')} union — absence of legacy speaks only to the STATUS being canonical, not to governance), optionally filtered to a single kind.`,
258
+ // @implements A-SPEC-746 — the whole corpus in one answer was 202,608 characters here.
259
+ description: `List specs (id, type, status; plus parent when depends_on names one, and legacy: true when the status is outside the canonical ${spec_types_1.SPEC_STATUSES.join('|')} union — absence of legacy speaks only to the STATUS being canonical, not to governance). `
260
+ + 'Answers with `summary` { total, counts[type][status] }, `pending` (first 100 specs that are not approved — what needs action) with `pendingTotal`, '
261
+ + 'and one page of `specs` in id order (default 100, `limit` 1..500) with `total` and `nextCursor` while rows remain — pass it back as `cursor`. '
262
+ + 'To ask whether a spec exists, pass `ids`: only those rows come back, and missing ids are named in `unknownIds`.',
259
263
  inputSchema: {
260
264
  type: 'object',
261
- properties: { type: str('Optional spec kind to filter by (e.g. A-SPEC).') },
265
+ properties: {
266
+ type: str('Optional spec kind to filter by (e.g. A-SPEC).'),
267
+ ids: strArray('Only these spec ids; ids that do not exist are listed in `unknownIds`.'),
268
+ status: str('Only this status, e.g. draft | approved | outdated.'),
269
+ limit: num('Rows per page: an integer 1..500 (default 100).'),
270
+ cursor: str('The `nextCursor` of the previous page; rows after it are returned.'),
271
+ },
262
272
  },
263
273
  },
264
274
  spec_next: {
@@ -553,21 +563,32 @@ exports.TOOL_SCHEMAS = {
553
563
  },
554
564
  },
555
565
  review_status: {
556
- description: 'Summarize open findings by severity and whether the review is blocked ({ blocked, open }).',
566
+ // @implements A-SPEC-746
567
+ description: 'Summarize open findings by severity and whether the review is blocked ({ blocked, open }), and the specs whose approved content moved and await review: '
568
+ + 'by default one row per spec { spec, files, signals } newest first with `reviewNeededTotal` (signals); if they would not fit, the rest are counted in `reviewNeededOmitted`. '
569
+ + '`detail: "full"` returns every raw signal with its from/to digests.',
557
570
  inputSchema: {
558
571
  type: 'object',
559
- properties: { root: ROOT },
572
+ properties: {
573
+ root: ROOT,
574
+ detail: { type: 'string', enum: ['summary', 'full'], description: 'summary (default): merged per spec, no digests. full: every raw review-needed signal.' },
575
+ },
560
576
  required: ['root'],
561
577
  },
562
578
  },
563
579
  // @implements A-SPEC-126
564
580
  reverse_scan: {
565
- description: 'Brownfield inventory: scan a legacy target read-only and return candidate A-SPEC clusters, cohesion evidence, and an honest coverage report (unresolved wiring, uncalibrated languages). Writes nothing.',
581
+ description: 'Brownfield inventory: scan a legacy target read-only and return candidate A-SPEC clusters, cohesion evidence, and an honest coverage report (unresolved wiring, uncalibrated languages). Writes nothing. '
582
+ // @implements A-SPEC-746
583
+ + 'By default a compressed view: unanchored clusters first with paths relative to their dir, clusters already fully anchored folded to { dir, fileCount, anchored }, '
584
+ + 'test matches counted (matchedTotal, matchedVia) and unmatched tests grouped by directory; anything reduced further is counted in clustersReduced with a note. '
585
+ + '`detail: "full"` returns every row.',
566
586
  inputSchema: {
567
587
  type: 'object',
568
588
  properties: {
569
589
  root: str('Absolute path to the target repository root. Unlike the other tools this need not be a git repository — a non-git tree is scanned whole and reported as isGit:false.'),
570
590
  maxFlagged: num('Cap on the listed dynamic-wiring files (default 50). Counts stay complete.'),
591
+ detail: { type: 'string', enum: ['summary', 'full'], description: 'summary (default): the compressed view. full: every cluster file and test-match row.' },
571
592
  },
572
593
  required: ['root'],
573
594
  },
@@ -67,6 +67,12 @@ export interface ReverseScanReport {
67
67
  * call, and the surface measures ~5KB per cluster on the calibration target. The handler strips it.
68
68
  */
69
69
  surfaceByCluster: Record<string, SurfaceSymbol[]>;
70
+ /**
71
+ * @implements A-SPEC-746 — candidate files that already carry an `@implements` anchor, so the tool
72
+ * handler can fold clusters that are no longer adoption candidates. Stripped from every response,
73
+ * like `surfaceByCluster`.
74
+ */
75
+ anchoredFiles: string[];
70
76
  coverage: {
71
77
  /** Candidate files placed in a production cluster by directory evidence. */
72
78
  structurallyResolved: number;
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.candidates = candidates;
37
37
  exports.reverseScan = reverseScan;
38
- // @implements A-SPEC-126, A-SPEC-734
38
+ // @implements A-SPEC-126, A-SPEC-734, A-SPEC-746
39
39
  const fs = __importStar(require("node:fs"));
40
40
  const path = __importStar(require("node:path"));
41
41
  const node_child_process_1 = require("node:child_process");
@@ -175,7 +175,8 @@ function reverseScan(root, opts = {}) {
175
175
  flagged.push({ file: f.sourcePath, indicators: hits });
176
176
  }
177
177
  flagged.sort((a, b) => cmp(a.file, b.file));
178
- const anchored = files.filter((f) => f.implementsSpecs.length > 0).length;
178
+ const anchoredFiles = files.filter((f) => f.implementsSpecs.length > 0).map((f) => f.sourcePath).sort(cmp);
179
+ const anchored = anchoredFiles.length;
179
180
  const countFiles = (cs) => cs.reduce((n, c) => n + c.files.length, 0);
180
181
  return {
181
182
  root,
@@ -188,6 +189,7 @@ function reverseScan(root, opts = {}) {
188
189
  clusters: production,
189
190
  testClusters,
190
191
  surfaceByCluster,
192
+ anchoredFiles,
191
193
  coverage: {
192
194
  structurallyResolved: countFiles(production),
193
195
  inTestClusters: countFiles(testClusters),
@@ -55,6 +55,12 @@ export interface RequirementTriageResult {
55
55
  reasons: string[];
56
56
  uncertainty: string[];
57
57
  }
58
+ /**
59
+ * @implements A-SPEC-713.2 — the code identifiers a request names: snake_case, camelCase/PascalCase,
60
+ * paths and code or config file names. Spec ids are pointers (removed first), URLs and kebab-case prose
61
+ * are not identifiers. Lower-cased, de-duplicated, at most 50.
62
+ */
63
+ export declare function requestIdentifiers(prompt: string): string[];
58
64
  /** Re-exported for triage callers; the cache contract belongs to vector coverage. */
59
65
  export declare const canonicalRequirementDocument: typeof canonicalRequirementDocumentText;
60
66
  /**