@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
@@ -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;
@@ -634,17 +661,20 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
634
661
  prompt: string;
635
662
  topK?: number;
636
663
  persist?: boolean;
664
+ detail?: string;
637
665
  }) => Promise<{
638
666
  promptDigest: string;
639
667
  semantic: {
640
668
  localState?: import("../semantic/model-cache").LocalModelState | undefined;
641
669
  recovery?: string | undefined;
642
670
  suppressed?: true | undefined;
671
+ availability: string;
672
+ missingLineages?: string[] | undefined;
643
673
  tier: "local" | "none" | "cloud";
644
674
  covered: number;
645
675
  total: number;
646
- state: "covered" | "unavailable" | "not-adopted" | "cold";
647
- availability: string;
676
+ unlineaged: number;
677
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
648
678
  };
649
679
  provenance: {
650
680
  reqId: string;
@@ -690,6 +720,80 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
690
720
  reasons: string[];
691
721
  uncertainty: string[];
692
722
  schema: "requirement-triage/1";
723
+ } | {
724
+ promptDigest: string;
725
+ semantic: {
726
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
727
+ recovery?: string | undefined;
728
+ suppressed?: true | undefined;
729
+ availability: string;
730
+ missingLineages?: string[] | undefined;
731
+ tier: "local" | "none" | "cloud";
732
+ covered: number;
733
+ total: number;
734
+ unlineaged: number;
735
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
736
+ };
737
+ provenance: {
738
+ reqId: string;
739
+ documents: {
740
+ id: string;
741
+ type: import("../review/requirement-triage").RequirementDocumentKind;
742
+ status: string;
743
+ dependsOn: readonly string[];
744
+ }[];
745
+ implementationAnchors: string[];
746
+ graphProvenance: {
747
+ [k: string]: {} | null;
748
+ };
749
+ executionEvidence: {
750
+ state: string;
751
+ recordedHead: string | null;
752
+ currentHead: string;
753
+ };
754
+ }[];
755
+ graph: {
756
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
757
+ sourceCommit: string | null;
758
+ graphAsOf: string | null;
759
+ resolutionLimits: string[];
760
+ };
761
+ graphBasis: {
762
+ head: string;
763
+ governedDocumentCount: number;
764
+ scannedSourceCount: number;
765
+ };
766
+ freshness: import("../refresh/freshness-coordinator").FreshnessReceipt | {
767
+ state: string;
768
+ };
769
+ refresh: {
770
+ status: "spawned" | "coalesced" | "failed";
771
+ generation?: string;
772
+ } | {
773
+ status: "unavailable" | "not-needed";
774
+ };
775
+ lexicalOnly?: true | undefined;
776
+ candidates: {
777
+ documents: {
778
+ id: string;
779
+ type: import("../review/requirement-triage").RequirementDocumentKind;
780
+ title: string;
781
+ status: string;
782
+ dependsOn: readonly string[];
783
+ }[];
784
+ reqId: string;
785
+ lexicalScore: number;
786
+ semanticScore?: number;
787
+ contentTerms: string[];
788
+ approved: boolean;
789
+ implementationAnchors: string[];
790
+ freshGreenTests: boolean;
791
+ reasons: string[];
792
+ }[];
793
+ verdict: import("../review/requirement-triage").RequirementVerdict;
794
+ reasons: string[];
795
+ uncertainty: string[];
796
+ schema: "requirement-triage/1";
693
797
  } | {
694
798
  evidenceDigest: string;
695
799
  persistedTo: string;
@@ -702,11 +806,13 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
702
806
  localState?: import("../semantic/model-cache").LocalModelState | undefined;
703
807
  recovery?: string | undefined;
704
808
  suppressed?: true | undefined;
809
+ availability: string;
810
+ missingLineages?: string[] | undefined;
705
811
  tier: "local" | "none" | "cloud";
706
812
  covered: number;
707
813
  total: number;
708
- state: "covered" | "unavailable" | "not-adopted" | "cold";
709
- availability: string;
814
+ unlineaged: number;
815
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
710
816
  };
711
817
  provenance: {
712
818
  reqId: string;
@@ -752,6 +858,86 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
752
858
  reasons: string[];
753
859
  uncertainty: string[];
754
860
  schema: "requirement-triage/1";
861
+ } | {
862
+ evidenceDigest: string;
863
+ persistedTo: string;
864
+ artifact: {
865
+ digest: string;
866
+ path: string;
867
+ };
868
+ promptDigest: string;
869
+ semantic: {
870
+ localState?: import("../semantic/model-cache").LocalModelState | undefined;
871
+ recovery?: string | undefined;
872
+ suppressed?: true | undefined;
873
+ availability: string;
874
+ missingLineages?: string[] | undefined;
875
+ tier: "local" | "none" | "cloud";
876
+ covered: number;
877
+ total: number;
878
+ unlineaged: number;
879
+ state: "covered" | "partial" | "unavailable" | "not-adopted" | "cold";
880
+ };
881
+ provenance: {
882
+ reqId: string;
883
+ documents: {
884
+ id: string;
885
+ type: import("../review/requirement-triage").RequirementDocumentKind;
886
+ status: string;
887
+ dependsOn: readonly string[];
888
+ }[];
889
+ implementationAnchors: string[];
890
+ graphProvenance: {
891
+ [k: string]: {} | null;
892
+ };
893
+ executionEvidence: {
894
+ state: string;
895
+ recordedHead: string | null;
896
+ currentHead: string;
897
+ };
898
+ }[];
899
+ graph: {
900
+ status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
901
+ sourceCommit: string | null;
902
+ graphAsOf: string | null;
903
+ resolutionLimits: string[];
904
+ };
905
+ graphBasis: {
906
+ head: string;
907
+ governedDocumentCount: number;
908
+ scannedSourceCount: number;
909
+ };
910
+ freshness: import("../refresh/freshness-coordinator").FreshnessReceipt | {
911
+ state: string;
912
+ };
913
+ refresh: {
914
+ status: "spawned" | "coalesced" | "failed";
915
+ generation?: string;
916
+ } | {
917
+ status: "unavailable" | "not-needed";
918
+ };
919
+ lexicalOnly?: true | undefined;
920
+ candidates: {
921
+ documents: {
922
+ id: string;
923
+ type: import("../review/requirement-triage").RequirementDocumentKind;
924
+ title: string;
925
+ status: string;
926
+ dependsOn: readonly string[];
927
+ }[];
928
+ reqId: string;
929
+ lexicalScore: number;
930
+ semanticScore?: number;
931
+ contentTerms: string[];
932
+ approved: boolean;
933
+ implementationAnchors: string[];
934
+ freshGreenTests: boolean;
935
+ reasons: string[];
936
+ }[];
937
+ verdict: import("../review/requirement-triage").RequirementVerdict;
938
+ reasons: string[];
939
+ uncertainty: string[];
940
+ schema: "requirement-triage/1";
755
941
  }>;
756
942
  ledger_reconcile: (a: {
757
943
  root?: string;
@@ -828,6 +1014,12 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
828
1014
  falseNegatives: number;
829
1015
  minSamples: number;
830
1016
  status: "measured" | "insufficient-data";
1017
+ scopeCauses: {
1018
+ full: number;
1019
+ narrow: number;
1020
+ unrecorded: number;
1021
+ causes: Record<string, number>;
1022
+ };
831
1023
  }>;
832
1024
  spec_create: (a: any) => Promise<{
833
1025
  ok: boolean;
@@ -1038,17 +1230,26 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1038
1230
  } | {
1039
1231
  ok: boolean;
1040
1232
  reason: string;
1233
+ blockers: string[];
1234
+ approvalIntent?: undefined;
1235
+ conflict?: undefined;
1236
+ } | {
1237
+ ok: boolean;
1238
+ reason: string;
1239
+ blockers?: undefined;
1041
1240
  approvalIntent?: undefined;
1042
1241
  conflict?: undefined;
1043
1242
  } | {
1044
1243
  ok: boolean;
1045
1244
  reason: string;
1046
1245
  approvalIntent: ApprovalIntent;
1246
+ blockers?: undefined;
1047
1247
  conflict?: undefined;
1048
1248
  } | {
1049
1249
  ok: boolean;
1050
1250
  reason: string;
1051
1251
  conflict: import("../spec/version-conflict").ConflictDetail;
1252
+ blockers?: undefined;
1052
1253
  approvalIntent?: undefined;
1053
1254
  } | {
1054
1255
  dismissUnknown?: string[] | undefined;
@@ -1069,18 +1270,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1069
1270
  digest: string;
1070
1271
  ok?: undefined;
1071
1272
  reason?: undefined;
1273
+ blockers?: undefined;
1072
1274
  approvalIntent?: undefined;
1073
1275
  conflict?: undefined;
1074
1276
  }>;
1075
- spec_list: (a: any) => Promise<{
1076
- specs: {
1077
- legacy?: boolean | undefined;
1078
- parent?: string | undefined;
1079
- id: string;
1080
- type: import("../spec/spec-types").SpecType;
1081
- status: "draft" | "review" | "approved" | "outdated";
1082
- }[];
1083
- }>;
1277
+ spec_list: (a: any) => Promise<Record<string, any>>;
1084
1278
  spec_next: (a?: {
1085
1279
  id?: string;
1086
1280
  }) => Promise<{
@@ -1186,15 +1380,15 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1186
1380
  counts: Record<string, Record<string, number>>;
1187
1381
  notApproved: {
1188
1382
  id: string;
1189
- type: string;
1190
- status: string;
1383
+ type: import("../spec/spec-types").SpecType;
1384
+ status: "draft" | "review" | "approved" | "outdated";
1191
1385
  }[];
1192
1386
  notApprovedTotal: number;
1193
1387
  };
1194
1388
  specs: {
1195
1389
  id: string;
1196
- type: string;
1197
- status: string;
1390
+ type: import("../spec/spec-types").SpecType;
1391
+ status: "draft" | "review" | "approved" | "outdated";
1198
1392
  }[];
1199
1393
  matched: number;
1200
1394
  ok?: undefined;
@@ -9,6 +9,7 @@ import { type TestEvidence } from '../review/test-evidence';
9
9
  import { type LanguageGap } from '../cpg/language-capability';
10
10
  export declare const MAINTENANCE_ANALYSIS_SCHEMA = "maintenance-analysis/1.13";
11
11
  export declare const MAINTENANCE_ANALYSIS_EXTRACTOR = "holmes-graph-fusion/1.13";
12
+ export declare const CONFIDENCE_NOTE: string;
12
13
  /**
13
14
  * The evidence kinds an ablation arm can actually produce. Completeness is measured by asking each
14
15
  * arm which of these it FILLED — the first cut hardcoded 1 / 2 / 2+n, so "enhanced beats current"
@@ -159,6 +160,14 @@ export interface MaintenanceAnalysisInput {
159
160
  scannedFiles: number;
160
161
  skippedFiles: readonly string[];
161
162
  unsupportedLanguages: readonly string[];
163
+ /**
164
+ * @implements A-SPEC-741 — paths of the files behind `unsupportedLanguages`, so a language counts
165
+ * against THIS request when one of its unreadable files shares a request term (the Ruby
166
+ * `legacy_session.rb` for "isolate the session"). Absent: only changed files and request paths count.
167
+ */
168
+ unsupportedFiles?: readonly string[];
169
+ /** @implements A-SPEC-741 — the handler capped `unsupportedFiles`; every language then counts. */
170
+ unsupportedFilesTruncated?: boolean;
162
171
  historyStatus?: 'available' | 'unavailable' | 'not-requested';
163
172
  };
164
173
  }
@@ -177,6 +186,16 @@ export interface MaintenanceAnalysis {
177
186
  * nobody has a hypothesis for why it inverts.
178
187
  */
179
188
  confidence: number;
189
+ /**
190
+ * @implements A-SPEC-740
191
+ * The standing of `confidence`, stated where the number is read — the tool description says it
192
+ * once, but a caller reading this object or a persisted artifact never sees that. A constant
193
+ * `false`: lifting the request-unrelated coverage gates turns 120/120 replay cases into 0.95 at
194
+ * 0.467/0.383 top-1 accuracy (Phase A, 2026-09-30). Only a passing calibration measurement,
195
+ * shipped as its own requirement, may turn it true.
196
+ */
197
+ confidenceCalibrated: false;
198
+ confidenceNote: string;
180
199
  /**
181
200
  * @implements A-SPEC-375
182
201
  * A-SPECs worth citing, when the request cited nothing. Empty when it already did.
@@ -1,10 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
3
+ exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.CONFIDENCE_NOTE = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
4
4
  exports.unquoteGitPath = unquoteGitPath;
5
5
  exports.analyzeMaintenance = analyzeMaintenance;
6
6
  exports.boundAnalysis = boundAnalysis;
7
- // @implements 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");
@@ -48,6 +49,39 @@ const defuse_symbols_1 = require("../rtm/defuse-symbols");
48
49
  // artifacts are only comparable when this string matches.
49
50
  exports.MAINTENANCE_ANALYSIS_SCHEMA = 'maintenance-analysis/1.13';
50
51
  exports.MAINTENANCE_ANALYSIS_EXTRACTOR = 'holmes-graph-fusion/1.13';
52
+ // @implements A-SPEC-741 — tokens for the unreadable-file relevance rule: split on non-alphanumerics
53
+ // and camelCase, lower-cased, length >= 2, NO stop list (a file named `test.sh` or `db.rb` is named).
54
+ function rawTokens(text) {
55
+ return text.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2);
56
+ }
57
+ /** @implements A-SPEC-741 — words a request uses when it is about a language the scanner cannot read. */
58
+ const LANGUAGE_NAMES = {
59
+ '.sh': ['shell', 'bash', 'sh'], '.rb': ['ruby', 'rails'], '.php': ['php'], '.kt': ['kotlin'], '.kts': ['kotlin'],
60
+ '.swift': ['swift'], '.scala': ['scala'], '.ex': ['elixir'], '.exs': ['elixir'], '.lua': ['lua'],
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
+ }
82
+ // @implements A-SPEC-740
83
+ exports.CONFIDENCE_NOTE = 'confidence is not calibrated: it counts which kinds of evidence were present, '
84
+ + 'does not predict accuracy, and must not be used to weight answers or to narrow a test scope.';
51
85
  /**
52
86
  * The evidence kinds an ablation arm can actually produce. Completeness is measured by asking each
53
87
  * arm which of these it FILLED — the first cut hardcoded 1 / 2 / 2+n, so "enhanced beats current"
@@ -589,6 +623,10 @@ function analyzeMaintenance(input) {
589
623
  }
590
624
  frontier = next;
591
625
  }
626
+ // Every frontier node is recorded as a stop, including those with no further callers (about half,
627
+ // measured 2026-09-30). A-SPEC-741 first recorded only the ones with unexplored callers; the replay
628
+ // then narrowed 12/120 scopes and 10 of them missed a test the commit changed — the conservative
629
+ // record was masking narrowing from anchors that do not cover the tests, so it stays.
592
630
  for (const id of frontier)
593
631
  stoppedAt.push({ id, reason: 'depth' });
594
632
  const transitive = sortedUnique([...transitiveIds].map(codeQualifiedName).filter((qn) => !direct.includes(qn)));
@@ -740,6 +778,108 @@ function analyzeMaintenance(input) {
740
778
  // coexisted with tier `unit`, empty coverage gaps, and no `unknowns` line at all.
741
779
  const truncationReasons = sortedUnique(stoppedAt.map((stop) => stop.reason));
742
780
  const truncationMarkers = sortedUnique(stoppedAt.map((stop) => `impact-truncated:${stop.reason}:${stop.id}`));
781
+ // @implements A-SPEC-741 — an unsupported language is a gap about THIS change only when the change
782
+ // names it: a changed file with that extension, or a path in the request that ends with it. A CI
783
+ // `.sh` script elsewhere in the tree pinned 455/455 analyses here to `ambiguous` + `full` from
784
+ // 2026-09-03 on. An entry that is not an extension (`not-enumerated(non-git)`) means the analysis
785
+ // could not look at all, so it always counts.
786
+ // A third way in: an unreadable file whose path shares a request term may be the very target the
787
+ // analysis cannot see — `src/legacy_session.rb` for "isolate the session".
788
+ // Review round 1 (2026-09-30): where the rule cannot judge it leans to "relevant" — a false
789
+ // "unrelated" is false confidence. Raw tokens (length >= 2, no stop list: `ci`, `db`, `test` are
790
+ // names), a prefix match from 4 characters (`session`/`sessions`), trailing punctuation stripped
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).
793
+ const requestLower = input.request.toLowerCase();
794
+ // Review round 2: a Set, capped — a 500 KB request cost 2.9 s against 5,000 paths when the tokens were
795
+ // an array compared inside the per-file loop.
796
+ // Round 3: de-duplicate FIRST, then cap — a pasted log of repeated lines pushed the file's name past
797
+ // a cap taken over raw tokens.
798
+ // Round 4: tokens over 64 characters (a pasted hex blob, a minified line) are not words.
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));
802
+ const requestStems = new Set([...requestTokens].filter((t) => t.length >= 5).map((t) => t.slice(0, 5)));
803
+ // Every prefix (>= 4 chars) of every request token, so "a path token is a prefix of a request word"
804
+ // (`auth` / `authentication`) is one lookup instead of a scan.
805
+ // Built on first use only — most analyses never reach the path condition (round 4).
806
+ let requestPrefixes = null;
807
+ const prefixes = () => {
808
+ if (requestPrefixes === null) {
809
+ requestPrefixes = new Set();
810
+ for (const t of requestTokens)
811
+ for (let n = 4; n <= t.length; n++)
812
+ requestPrefixes.add(t.slice(0, n));
813
+ }
814
+ return requestPrefixes;
815
+ };
816
+ const tokenMeetsRequest = (token) => {
817
+ if (requestTokens.has(token))
818
+ return true;
819
+ if (token.length >= 4 && prefixes().has(token))
820
+ return true; // path token ⊑ request word
821
+ for (let n = 4; n < token.length; n++)
822
+ if (requestTokens.has(token.slice(0, n)))
823
+ return true; // request word ⊑ path token
824
+ return token.length >= 5 && requestStems.has(token.slice(0, 5));
825
+ };
826
+ // A LETTER outside ASCII (Hangul, Kana, …) — not an em dash or a curly quote, which every commit subject here uses.
827
+ const requestIsNonAscii = /(?![\x00-\x7f])\p{L}/u.test(input.request);
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
+ };
858
+ const relevantUnsupported = input.coverage.unsupportedLanguages.filter((language) => {
859
+ if (!language.startsWith('.'))
860
+ return true;
861
+ const ext = language.toLowerCase();
862
+ if ((input.changedFiles ?? []).some((file) => file.toLowerCase().endsWith(ext)))
863
+ return true;
864
+ // A path token ending with the extension: `scripts/ci-local.sh`, not a bare word `sh`.
865
+ if (requestLower.split(/[^\w./-]+/).map((token) => token.replace(/[.,;:!?]+$/, ''))
866
+ .some((token) => token.length > ext.length && token.endsWith(ext)))
867
+ return true;
868
+ // Review round 2: a request that names the language itself (`.sh`, `shell`, `kotlin`) is about it.
869
+ if (requestTokens.has(ext.slice(1)) || (LANGUAGE_NAMES[ext] ?? []).some((name) => requestTokens.has(name)))
870
+ return true;
871
+ if ((LANGUAGE_NAMES_CJK[ext] ?? []).some((name) => input.request.includes(name)))
872
+ return true;
873
+ const files = (input.coverage.unsupportedFiles ?? []).filter((file) => file.toLowerCase().endsWith(ext));
874
+ if (pathsCapped)
875
+ return true;
876
+ // Every token of the path — folders too (`app/session/store.rb`) — exact, or sharing a 5-letter stem.
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);
880
+ });
881
+ // The TEST SCOPE keeps every language (A-SPEC-741 revision): relevance decides the classification
882
+ // only. Dropping the unrelated ones from the scope let anchor-based narrowing miss tests on replay.
743
883
  const unresolvedCoverage = [
744
884
  ...input.coverage.skippedFiles,
745
885
  ...input.coverage.unsupportedLanguages.map((language) => `unsupported:${language}`),
@@ -759,16 +899,25 @@ function analyzeMaintenance(input) {
759
899
  .sort((a, b) => b.date.localeCompare(a.date) || a.commit.localeCompare(b.commit));
760
900
  const skippedFiles = sortedUnique(input.coverage.skippedFiles);
761
901
  const unsupportedLanguages = sortedUnique(input.coverage.unsupportedLanguages);
762
- const coverageGaps = skippedFiles.length > 0 || unsupportedLanguages.length > 0
763
- || input.coverage.scannedFiles === 0 || truncationMarkers.length > 0;
902
+ // @implements A-SPEC-741 — the classification gate holds only gaps about the change. A truncated
903
+ // walk bounds how far the TEST SCOPE can be trusted (it stays in `unresolvedCoverage`, which forces
904
+ // `full`); it says nothing about whether the request maps to an existing requirement.
905
+ const coverageGaps = skippedFiles.length > 0 || relevantUnsupported.length > 0
906
+ || input.coverage.scannedFiles === 0;
764
907
  const stale = input.basis.loadedBuild !== input.basis.diskBuild;
765
908
  const unknowns = [];
766
909
  if (input.coverage.scannedFiles === 0)
767
910
  unknowns.push('No source files were represented in the analyzed graph.');
768
911
  if (skippedFiles.length > 0)
769
912
  unknowns.push(`Skipped files are outside the evidence basis: ${skippedFiles.join(', ')}`);
770
- if (unsupportedLanguages.length > 0)
771
- unknowns.push(`Unsupported languages are outside the evidence basis: ${unsupportedLanguages.join(', ')}`);
913
+ if (unsupportedLanguages.length > 0) {
914
+ const outside = unsupportedLanguages.filter((language) => !relevantUnsupported.includes(language));
915
+ unknowns.push(`Unsupported languages are outside the evidence basis: ${unsupportedLanguages.join(', ')}`
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('')
919
+ + (pathsCapped ? ' (the list of unreadable files was capped, so every language counts as about this change)' : ''));
920
+ }
772
921
  if (truncationMarkers.length > 0) {
773
922
  unknowns.push(`Impact closure was truncated (${truncationReasons.join(', ')}) at ${stoppedAt.length} node(s): callers beyond the bound were never explored, so the transitive impact is a lower bound, not a complete set. Stopped at ${stoppedAt.map((stop) => stop.id).join(', ')}.`);
774
923
  }
@@ -936,17 +1085,32 @@ function analyzeMaintenance(input) {
936
1085
  + `scan (libraries and builtins) and ${edgeAmbiguous} are ambiguous. Impact traversal uses only `
937
1086
  + `the resolved ones.`);
938
1087
  }
1088
+ // @implements A-SPEC-745 — the same set as `specIds`, emitted in relevance order: the response
1089
+ // bound keeps ten, and id order made those ten A-SPEC-100 and its neighbours for every request.
1090
+ // Cited first, then by the rank of the first candidate file that anchors the spec, then by id.
1091
+ const specRank = new Map();
1092
+ for (const id of (0, localize_1.citationsIn)(input.request, new Set(specIds)).cited)
1093
+ specRank.set(id, -1);
1094
+ const anchorsOf = new Map(scanned.map((file) => [file.sourcePath, file.implementsSpecs]));
1095
+ candidates.forEach((candidate, index) => {
1096
+ for (const id of anchorsOf.get(candidate.file) ?? [])
1097
+ if (!specRank.has(id))
1098
+ specRank.set(id, index);
1099
+ });
1100
+ const relevanceOrderedSpecs = [...specIds].sort((a, b) => (specRank.get(a) ?? Infinity) - (specRank.get(b) ?? Infinity) || a.localeCompare(b));
939
1101
  const evidence = {
940
1102
  schemaVersion: exports.MAINTENANCE_ANALYSIS_SCHEMA,
941
1103
  extractorVersion: exports.MAINTENANCE_ANALYSIS_EXTRACTOR,
942
1104
  classification,
943
1105
  confidence,
1106
+ confidenceCalibrated: false,
1107
+ confidenceNote: exports.CONFIDENCE_NOTE,
944
1108
  citationCandidates,
945
1109
  callEdges,
946
1110
  candidates,
947
1111
  ...(semanticAlternates !== undefined ? { semanticAlternates } : {}),
948
1112
  rerankPool,
949
- candidateSpecs: specIds,
1113
+ candidateSpecs: relevanceOrderedSpecs,
950
1114
  impacts: {
951
1115
  files: localizedFiles,
952
1116
  tiers: { primary: primaryTier, secondary: secondaryTier },
@@ -27,6 +27,11 @@ export interface EvidenceArtifact {
27
27
  extractorVersion: string;
28
28
  classification: string;
29
29
  confidence: number;
30
+ /**
31
+ * @implements A-SPEC-740 — optional on purpose: an artifact recorded before the marker existed is
32
+ * just as uncalibrated, and the schema string stays 1.4 so calibration still reads it.
33
+ */
34
+ confidenceCalibrated?: false;
30
35
  graphBasis: MaintenanceAnalysis['graphBasis'];
31
36
  predicted: {
32
37
  files: string[];
@@ -58,6 +63,9 @@ export interface EvidenceArtifact {
58
63
  /** The caller walk stopped at a bound: the transitive set is a lower bound, not a complete one. */
59
64
  impactTruncated: boolean;
60
65
  testScopeTier: string;
66
+ /** @implements A-SPEC-744 — why the scope was what it was; optional so older artifacts still read. */
67
+ testScopeReason?: string;
68
+ testScopeCauses?: string[];
61
69
  /** Files reachable only through a call edge — affected, but never analysed as edit candidates. */
62
70
  impactedFiles: string[];
63
71
  /**
@@ -170,7 +178,24 @@ export interface Calibration {
170
178
  falseNegatives: number;
171
179
  minSamples: number;
172
180
  status: 'measured' | 'insufficient-data';
181
+ /**
182
+ * @implements A-SPEC-744 — how often each cause made a persisted scope `full`. `unrecorded` counts
183
+ * artifacts written before the causes were kept: they are not evidence for any cause.
184
+ */
185
+ scopeCauses: {
186
+ full: number;
187
+ narrow: number;
188
+ unrecorded: number;
189
+ causes: Record<string, number>;
190
+ };
173
191
  }
192
+ /**
193
+ * @implements A-SPEC-744
194
+ * The named reasons a test scope is `full`, read from its structured fields — never parsed out of the
195
+ * sentence. 455 persisted analyses were all `full` and none said why; the investigation that followed
196
+ * needed a 120-commit replay to answer a question the analysis had already known.
197
+ */
198
+ export declare function scopeCauses(scope: MaintenanceAnalysis['testScope']): string[];
174
199
  /**
175
200
  * Reliability bins plus a Brier score. `minSamples` is the honesty knob: below it a bin reports
176
201
  * `insufficient-data` and a null accuracy, because one sample in a bin yields a 0 or a 1 that looks