@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.
@@ -1,13 +1,55 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.canonicalRequirementDocument = void 0;
4
+ exports.requestIdentifiers = requestIdentifiers;
4
5
  exports.triageRequirements = triageRequirements;
5
6
  exports.requirementSemanticCoverage = requirementSemanticCoverage;
6
- // @implements A-SPEC-713.1, A-SPEC-742, A-SPEC-713
7
+ // @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-742, A-SPEC-713
7
8
  /** Pure, conservative lifecycle triage over governed requirement documents. */
8
9
  const semantic_retrieval_1 = require("./semantic-retrieval");
9
10
  const localize_1 = require("../rtm/localize");
10
11
  const vector_coverage_1 = require("../semantic/vector-coverage");
12
+ const CODE_FILE = /\.(ts|tsx|js|mjs|cjs|py|go|rs|java|cs|rb|sh|json|ya?ml|toml|md)$/i;
13
+ /**
14
+ * @implements A-SPEC-713.2 — the code identifiers a request names: snake_case, camelCase/PascalCase,
15
+ * paths and code or config file names. Spec ids are pointers (removed first), URLs and kebab-case prose
16
+ * are not identifiers. Lower-cased, de-duplicated, at most 50.
17
+ */
18
+ function requestIdentifiers(prompt) {
19
+ const out = [];
20
+ for (const raw of (0, localize_1.withoutCitations)(prompt).split(/\s+/)) {
21
+ const token = raw.replace(/^[`'"([{<]+/, '').replace(/[`'")\]}>.,;:!?]+$/, '');
22
+ if (token === '' || /^[a-z][a-z0-9+.-]*:\/\//i.test(token) || /^www\./i.test(token))
23
+ continue;
24
+ const snake = /^[A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+$/.test(token);
25
+ const camel = token.length >= 4 && /^[A-Za-z][A-Za-z0-9]*$/.test(token) && /[a-z][A-Z]/.test(token);
26
+ // A path needs a code extension or two separators: `and/or` and `client/server` are prose.
27
+ const pathLike = token.includes('/') && /[A-Za-z]/.test(token) && (CODE_FILE.test(token) || (token.match(/\//g) ?? []).length >= 2);
28
+ const file = !token.includes('/') && /[A-Za-z]/.test(token.replace(CODE_FILE, '')) && CODE_FILE.test(token);
29
+ if (!snake && !camel && !pathLike && !file)
30
+ continue;
31
+ const id = token.toLowerCase();
32
+ if (!out.includes(id))
33
+ out.push(id);
34
+ if (out.length === 50)
35
+ break;
36
+ }
37
+ return out;
38
+ }
39
+ /**
40
+ * @implements A-SPEC-713.2 — what a lineage says it covers: titles and section bodies, without a section
41
+ * headed "Out of Scope" and without what follows an `Out of Scope:` line inside a section.
42
+ */
43
+ function inScopeText(docs) {
44
+ return docs.map((d) => [d.title, ...Object.entries(d.sections ?? {})
45
+ .filter(([heading]) => !/out of scope/i.test(heading))
46
+ .map(([, body]) => body.split(/^\s*Out of Scope\s*:/im)[0])].join('\n')).join('\n').toLowerCase();
47
+ }
48
+ function identifierCovered(id, text) {
49
+ if (text.includes(id))
50
+ return true;
51
+ return id.includes('/') && text.includes(id.slice(id.lastIndexOf('/') + 1));
52
+ }
11
53
  /** Re-exported for triage callers; the cache contract belongs to vector coverage. */
12
54
  exports.canonicalRequirementDocument = vector_coverage_1.canonicalRequirementDocument;
13
55
  function rankLimit(value) {
@@ -215,13 +257,19 @@ function triageCore(input) {
215
257
  // Round 3: a citation never counts toward agreement — "(unrelated to REQ-1)" plus one channel on
216
258
  // REQ-1 decided REQ-1. Both channels (or, lexical-only, the lexical one) must name a lineage, and it
217
259
  // must be the first-ranked one.
218
- const agreed = withVector.length > 0
219
- ? (lexicalTop !== null && semanticTop !== null && lexicalTop.reqId === semanticTop.reqId ? lexicalTop.reqId : null)
220
- : (lexicalTop?.reqId ?? null);
221
- if (agreed === null)
222
- agreementReason = withVector.length > 0 || !citedLineages.has(top.reqId) ? 'channels-disagree' : 'citation-unbacked';
223
- else if (agreed !== top.reqId)
224
- agreementReason = 'citation-unbacked';
260
+ // @implements A-SPEC-713.3 — a single channel never confirms (owner decision 2026-10-01). With no vector on
261
+ // any candidate, the lexical top alone answered existing-change for 47 of 60 requirements that were new at
262
+ // the time, and intake then refused them. The lexical order stays visible; the verdict does not decide.
263
+ if (withVector.length === 0) {
264
+ agreementReason = 'single-channel';
265
+ }
266
+ else {
267
+ const agreed = lexicalTop !== null && semanticTop !== null && lexicalTop.reqId === semanticTop.reqId ? lexicalTop.reqId : null;
268
+ if (agreed === null)
269
+ agreementReason = 'channels-disagree';
270
+ else if (agreed !== top.reqId)
271
+ agreementReason = 'citation-unbacked';
272
+ }
225
273
  }
226
274
  if (tied.length > 1 || agreementReason !== null || top.contentTerms.length === 0 || top.reasons.includes('contradictory-evidence')) {
227
275
  const uncertainty = [
@@ -232,6 +280,20 @@ function triageCore(input) {
232
280
  ];
233
281
  return { verdict: 'ambiguous', candidates, reasons: uncertainty, uncertainty };
234
282
  }
283
+ // @implements A-SPEC-713.2 — a confident verdict says the request is this lineage's business; a code
284
+ // identifier the lineage never mentions in scope means the rule cannot judge that. Measured: a request
285
+ // about spec_list/review_status was `fulfilled` by the phase_status lineage whose REQ puts other tools
286
+ // out of scope, and intake then refused the new requirement.
287
+ const identifiers = requestIdentifiers(input.prompt);
288
+ if (identifiers.length > 0) {
289
+ const text = inScopeText(top.documents);
290
+ const missing = identifiers.filter((id) => !identifierCovered(id, text)).sort();
291
+ if (missing.length > 0) {
292
+ const named = [...missing.slice(0, 5), ...(missing.length > 5 ? [`+${missing.length - 5}`] : [])];
293
+ const reason = `identifiers-outside-lineage:${named.join(',')}`;
294
+ return { verdict: 'ambiguous', candidates, reasons: [reason], uncertainty: [reason] };
295
+ }
296
+ }
235
297
  if (top.approved && top.implementationAnchors.length > 0 && top.freshGreenTests) {
236
298
  return { verdict: 'fulfilled', candidates, reasons: ['approved-lineage', 'implementation-anchors', 'fresh-green-execution'], uncertainty: [] };
237
299
  }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Cosine at or above which an unreadable file's path words are "about" a non-ASCII request, keyed by
3
+ * the semantic runtime label. Measured 2026-09-30 (docs/goals/EVIDENCE-nonlatin-relevance-2026-09-30.md):
4
+ * on gemini-embedding-001 mixed requests naming the file scored 0.701–0.765 and no unmatched jarvis
5
+ * request exceeded 0.640. On local bge-m3 the populations overlapped (pin 0.486 against 0.489), so it
6
+ * has no entry — a label without a threshold keeps the language relevant.
7
+ */
8
+ export declare const UNREADABLE_PATH_THRESHOLDS: Readonly<Record<string, number>>;
9
+ /** `scripts/holmes_session_key.sh` -> `scripts holmes session key`: the words of the path, no extension. */
10
+ export declare function unreadablePathText(file: string): string;
11
+ /**
12
+ * Tracked and untracked-not-ignored files whose extension the scanner cannot read. Throws when git
13
+ * fails: the analysis handler turns that into its `not-enumerated(non-git)` gap.
14
+ */
15
+ export declare function listUnreadableFiles(root: string): {
16
+ languages: string[];
17
+ files: string[];
18
+ truncated: boolean;
19
+ };
20
+ /**
21
+ * Warm the path vectors the analysis compares a non-ASCII request with. Best effort: a tree git cannot
22
+ * list, or an embedder that fails, leaves vectors missing — and a missing vector keeps the language
23
+ * relevant, which is the behavior before this existed.
24
+ */
25
+ export declare function warmUnreadablePaths(rt: {
26
+ warm(texts: string[]): Promise<{
27
+ computed: number;
28
+ cached: number;
29
+ }>;
30
+ }, root: string): Promise<void>;
@@ -0,0 +1,104 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.UNREADABLE_PATH_THRESHOLDS = void 0;
37
+ exports.unreadablePathText = unreadablePathText;
38
+ exports.listUnreadableFiles = listUnreadableFiles;
39
+ exports.warmUnreadablePaths = warmUnreadablePaths;
40
+ // @implements A-SPEC-741.1
41
+ // The files the scanner cannot read, and the ONE definition of their path-vector key. The warm
42
+ // (writer) and maintenance analysis (reader) both key through `unreadablePathText`: a writer key that
43
+ // drifts from the reader's misses for ever while both sides look correct (A-SPEC-683).
44
+ const path = __importStar(require("node:path"));
45
+ const node_child_process_1 = require("node:child_process");
46
+ const cpg_scanner_1 = require("../cpg/cpg-scanner");
47
+ const root_1 = require("../project/root");
48
+ const bounded_io_1 = require("../project/bounded-io");
49
+ /** Code extensions the scanner does not read (the handler's list since A-SPEC-741). */
50
+ const KNOWN_CODE_EXTENSIONS = ['.rb', '.php', '.kt', '.kts', '.swift', '.scala', '.sh', '.ex', '.exs', '.lua', '.r'];
51
+ const MAX_UNREADABLE_FILES = 5000;
52
+ /**
53
+ * Cosine at or above which an unreadable file's path words are "about" a non-ASCII request, keyed by
54
+ * the semantic runtime label. Measured 2026-09-30 (docs/goals/EVIDENCE-nonlatin-relevance-2026-09-30.md):
55
+ * on gemini-embedding-001 mixed requests naming the file scored 0.701–0.765 and no unmatched jarvis
56
+ * request exceeded 0.640. On local bge-m3 the populations overlapped (pin 0.486 against 0.489), so it
57
+ * has no entry — a label without a threshold keeps the language relevant.
58
+ */
59
+ exports.UNREADABLE_PATH_THRESHOLDS = {
60
+ 'cloud:gemini-embedding-001': 0.65,
61
+ };
62
+ /** `scripts/holmes_session_key.sh` -> `scripts holmes session key`: the words of the path, no extension. */
63
+ function unreadablePathText(file) {
64
+ const ext = path.posix.extname(file);
65
+ const stem = ext === '' ? file : file.slice(0, -ext.length);
66
+ return stem.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/).filter(Boolean).join(' ').toLowerCase();
67
+ }
68
+ /**
69
+ * Tracked and untracked-not-ignored files whose extension the scanner cannot read. Throws when git
70
+ * fails: the analysis handler turns that into its `not-enumerated(non-git)` gap.
71
+ */
72
+ function listUnreadableFiles(root) {
73
+ const supported = new Set(cpg_scanner_1.SCANNABLE_EXTENSIONS);
74
+ const unreadable = new Set(KNOWN_CODE_EXTENSIONS.filter((ext) => !supported.has(ext)));
75
+ // A-SPEC-734 (round 15): with the fsmonitor hook off; round 16: the shared bound.
76
+ const listed = (0, node_child_process_1.execFileSync)('git', ['-c', 'core.fsmonitor=false', '-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: bounded_io_1.GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'pipe'] }).split('\0');
77
+ const languages = new Set();
78
+ const files = [];
79
+ let truncated = false;
80
+ for (const file of listed) {
81
+ const ext = path.extname(file).toLowerCase();
82
+ if (!unreadable.has(ext))
83
+ continue;
84
+ languages.add(ext);
85
+ if (files.length < MAX_UNREADABLE_FILES)
86
+ files.push(file);
87
+ else
88
+ truncated = true;
89
+ }
90
+ return { languages: [...languages].sort(), files, truncated };
91
+ }
92
+ /**
93
+ * Warm the path vectors the analysis compares a non-ASCII request with. Best effort: a tree git cannot
94
+ * list, or an embedder that fails, leaves vectors missing — and a missing vector keeps the language
95
+ * relevant, which is the behavior before this existed.
96
+ */
97
+ async function warmUnreadablePaths(rt, root) {
98
+ try {
99
+ const texts = [...new Set(listUnreadableFiles(root).files.map(unreadablePathText))].filter((t) => t !== '');
100
+ if (texts.length > 0)
101
+ await rt.warm(texts);
102
+ }
103
+ catch { /* best effort — see above */ }
104
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.32.0",
4
+ "version": "0.33.0",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",
@@ -10,7 +10,7 @@ description: >-
10
10
  # author-slice
11
11
 
12
12
  거부가 요구하는 문서가 **아직 없을 때** 이 플레이북이다. 문서는 있는데 `status`가 막고 있다면
13
- `promote-slice`다 — `spec_list`로 먼저 갈라라. `approved H-SPEC이 없습니다` / `approved A-SPEC이
13
+ `promote-slice`다 — `spec_list({ ids: ["<id>"] })`로 먼저 갈라라. `approved H-SPEC이 없습니다` / `approved A-SPEC이
14
14
  없습니다`는 "없음"과 "draft로 있음" 두 상황에서 같은 문구로 나오므로 문구가 아니라 스토어 상태가
15
15
  판별 기준이고, `선행 REQ가 없습니다`만은 존재 검사라서 언제나 이쪽이다.
16
16
 
@@ -42,7 +42,7 @@ description: >-
42
42
  말하지 않는다 — 두 개의 서로 다른 실패가 같은 `missing`을 낸다. 「T-SPEC 거부는 상태를 구별해 말한다」를 함께 읽는다.
43
43
  2. **대상을 특정한다.** `구현 대상 A-SPEC(미지정)` 이 나왔다면 스펙이 아니라 호출이 문제다 —
44
44
  `targetAspecId`를 넘기지 않은 것이고, 승인할 것은 없다.
45
- 3. **그 스펙이 존재하는가.** `spec_list`로 확인한다. 없으면 이것은 승격이 아니라 저작이다 →
45
+ 3. **그 스펙이 존재하는가.** `spec_list({ ids: ["<id>"] })`로 확인한다(없으면 `unknownIds`에 이름이 나온다). 없으면 이것은 승격이 아니라 저작이다 →
46
46
  `author-slice`. 있으면 계속한다.
47
47
  4. **검증을 확인한다 — 부르는 게 아니라 받는 것이다.** `spec_validate`는 기본 프로파일에서
48
48
  **광고되지 않는다**. `phase_check` · `risk_check` · `rtm_check`와 함께 훅이 push로 강제하는