@holmes-lab/holmes-kit 0.37.1 → 0.38.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 (38) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +12 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +2 -1
  5. package/dist/holmes/cli/approve.js +24 -3
  6. package/dist/holmes/cli/autonomy.d.ts +72 -0
  7. package/dist/holmes/cli/autonomy.js +92 -8
  8. package/dist/holmes/cli/doctor.js +4 -13
  9. package/dist/holmes/cli/index.js +98 -10
  10. package/dist/holmes/cli/runtime-binding-approval.js +2 -3
  11. package/dist/holmes/governance/approval-queue.d.ts +7 -1
  12. package/dist/holmes/governance/approval-queue.js +10 -28
  13. package/dist/holmes/governance/autonomy.d.ts +10 -1
  14. package/dist/holmes/governance/autonomy.js +46 -2
  15. package/dist/holmes/governance/full-autonomy.d.ts +72 -0
  16. package/dist/holmes/governance/full-autonomy.js +308 -0
  17. package/dist/holmes/guardrail/operator-person.js +3 -2
  18. package/dist/holmes/guardrail/refusal-codes.js +13 -4
  19. package/dist/holmes/guardrail/risk-classifier.js +7 -3
  20. package/dist/holmes/guardrail/run-refusals.js +7 -6
  21. package/dist/holmes/guardrail/write-target.js +4 -1
  22. package/dist/holmes/hooks/pre-tool-use.d.ts +2 -0
  23. package/dist/holmes/hooks/pre-tool-use.js +55 -10
  24. package/dist/holmes/hooks/stop.js +3 -3
  25. package/dist/holmes/mcp/elicit-approval.js +5 -6
  26. package/dist/holmes/mcp/handlers/approval-ask.js +4 -3
  27. package/dist/holmes/mcp/handlers/review-verdict.js +3 -2
  28. package/dist/holmes/mcp/handlers/spec-approval.d.ts +2 -0
  29. package/dist/holmes/mcp/handlers/spec-approval.js +24 -6
  30. package/dist/holmes/mcp/handlers.d.ts +2 -0
  31. package/dist/holmes/mcp/handlers.js +2 -1
  32. package/dist/holmes/mcp/operator-recovery.d.ts +7 -2
  33. package/dist/holmes/mcp/operator-recovery.js +15 -58
  34. package/dist/holmes/mcp/tool-schemas.js +1 -1
  35. package/dist/holmes/review/run-replay.d.ts +31 -0
  36. package/dist/holmes/review/run-replay.js +25 -2
  37. package/package.json +1 -1
  38. package/playbooks/promote-slice/PLAYBOOK.md +2 -1
@@ -1,70 +1,27 @@
1
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
- })();
2
+ // @implements A-SPEC-754, A-SPEC-768, A-SPEC-770.12, A-SPEC-792.1
35
3
  Object.defineProperty(exports, "__esModule", { value: true });
36
4
  exports.operatorRecovery = operatorRecovery;
37
- // @implements A-SPEC-754, A-SPEC-532.3, A-SPEC-768, A-SPEC-770.12
38
- const path = __importStar(require("node:path"));
39
- const unsafeDisplay = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
40
- function literal(value, platform) {
41
- return platform === 'win32' ? `'${value.replace(/'/g, "''")}'` : `'${value.replace(/'/g, `'\\''`)}'`;
42
- }
43
- /** Formatting only: the caller must return pending text only after a successful enqueue. */
5
+ /**
6
+ * Formatting only: the caller must return pending text only after a successful enqueue.
7
+ *
8
+ * @implements A-SPEC-792.1 — the hint names no command to type. The operator lines it used to carry (`approve --grant`,
9
+ * `approve --watch`, A-SPEC-532.3) were relayed by agents and typed by the person in a terminal — the UX REQ-792 removes.
10
+ * `platform`, `executable` and `cli` once built that command; they are accepted and no longer used.
11
+ */
44
12
  function operatorRecovery(root, target, operation, options) {
13
+ void root;
45
14
  const label = options?.label ?? '';
46
- const platform = options?.platform ?? process.platform;
47
- const executable = options?.executable ?? process.execPath;
48
- // Both src/holmes/mcp (tests) and dist/holmes/mcp (installed) have the same depth.
49
- const cli = options?.cli ?? path.resolve(__dirname, '../../..', 'bin/holmes-kit.js');
50
- const commandSafe = [root, executable, cli].every(value => value.length > 0 && value.length <= 2048 && !unsafeDisplay.test(value));
51
- const command = commandSafe ? `${platform === 'win32' ? '& ' : ''}${literal(executable, platform)} ${literal(cli, platform)} approve --target ${literal(root, platform)}` : '';
52
- const display = (value) => JSON.stringify(value.slice(0, 300)).replace(/[\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
15
+ const display = (value) => JSON.stringify(value.slice(0, 300)).replace(/[\u007f-\u009f‪-‮⁦-⁩]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
53
16
  return {
54
- reviewCommand: command || 'the installed Holmes-Kit approval UI (path cannot be safely displayed; no command emitted)',
55
17
  pendingHint(id) {
56
18
  if (!/^req-[a-f0-9]{12}$/.test(id))
57
19
  return '';
58
- if (!command)
59
- return `\n[승인 대기 ${id}${label}] The request was recorded. Use the installed approval UI; a path exceeds the safe command display limit. No truncated command is provided.`;
60
- // @implements A-SPEC-532.3 — the resident surface is offered beside the one-off command (owner, 2026-10-04:
61
- // "why am I still pasting commands"): one key per arriving request.
62
- // @implements A-SPEC-768 — the three lines above are the operator's; measured 2026-10-11 (HG arm) the agent read
63
- // "keep the approval surface open" as its own instruction and polled a sealed spec 58 times. One line is the agent's.
64
- return `\n[승인 대기 ${id}${label}] 운영자: ${command} --grant ${literal(id, platform)}`
65
- + `\nOr keep the approval surface open and decide each arriving request with one key: ${command} --watch`
66
- + `\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.`
67
- // @implements A-SPEC-718.5 — the in-session route first: the person answers the form, nobody types a command.
20
+ // @implements A-SPEC-768 — one line is the agent's; measured 2026-10-11 (HG arm) an agent read an operator line as
21
+ // its own instruction and polled a sealed spec 58 times.
22
+ return `\n[승인 대기 ${id}${label}] The request was recorded.`
23
+ + `\nAfter approval, retry ${operation ? display(operation) : 'the original MCP operation'} for target ${display(target)} in the same workspace. Do not retry until approval is available.`
24
+ // @implements A-SPEC-718.5 — the in-session route: the person answers the form, nobody types a command.
68
25
  + `\nAgent: call approval_ask with id "${id}" — the person decides in this session's approval form; after granted, retry once.`
69
26
  + ' Otherwise 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.';
70
27
  },
@@ -225,7 +225,7 @@ exports.TOOL_SCHEMAS = {
225
225
  },
226
226
  // @implements A-SPEC-718.4
227
227
  approval_ask: {
228
- description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as `holmes-kit approve --grant/--deny/--ask` would record it (actor `elicitation:<client>`), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
228
+ description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as the operator's grant, deny or question is recorded (actor `elicitation:<client>`), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
229
229
  inputSchema: {
230
230
  type: 'object',
231
231
  properties: {
@@ -287,6 +287,15 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
287
287
  score: number;
288
288
  semCos?: number;
289
289
  }>;
290
+ /** @implements A-SPEC-791.1 — present only when the product-semantic pass produced alternates (cloud tier). */
291
+ semanticAlternates?: Array<{
292
+ file: string;
293
+ cos: number;
294
+ }>;
295
+ /** @implements A-SPEC-791.2 — present only when dumpRerankPool was asked. */
296
+ rerankPool?: Array<{
297
+ file: string;
298
+ }>;
290
299
  truthFiles: string[];
291
300
  /** @implements A-SPEC-755.1 — the function axis as scored: truth from the parent-side changed
292
301
  * lines, prediction from the scored (1-pass) candidates. Empty truth = outside that denominator. */
@@ -303,10 +312,14 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
303
312
  * to `ReplayResult`, so a pin cannot move because a measurement was asked for.
304
313
  */
305
314
  pairedDump?: (row: PairedRow) => void;
315
+ /** @implements A-SPEC-791.2 — put the product's rerank pool (files) on each caseDump row. */
316
+ dumpRerankPool?: boolean;
306
317
  /** @implements A-SPEC-487 — 2-pass semantic injection for the dump only, never the pins. */
307
318
  productSemantic?: {
308
319
  embedBatch: (texts: string[], kind: 'query' | 'doc') => Promise<number[][]>;
309
320
  label: string;
321
+ /** @implements A-SPEC-791.1 — 'all' embeds every scanned file (a warmed product); default 'surfaced'. */
322
+ scope?: 'surfaced' | 'all';
310
323
  };
311
324
  /**
312
325
  * @implements A-SPEC-489 — body EXCERPTS for the content-access judgment protocol: the top
@@ -322,6 +335,24 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
322
335
  mode?: 'head' | 'aligned';
323
336
  };
324
337
  }): Promise<ReplayResult>;
338
+ /**
339
+ * @implements A-SPEC-791.1 — which document texts the dump's product-semantic pass embeds. `surfaced` (the default)
340
+ * keeps the original contract: only files the 1-pass emitted. `all` embeds every scanned file, as a warmed product
341
+ * holds them — the cloud-only alternates (A-SPEC-494) scan every file and could never fire on the surfaced set.
342
+ */
343
+ /**
344
+ * @implements A-SPEC-791.2 — the product's lexical rerank pool, as files in pool order, on a dump row only when asked;
345
+ * absent otherwise so every earlier dump keeps its bytes. It is the same-budget opponent the cloud alternates are scored
346
+ * against.
347
+ */
348
+ export declare function rerankPoolField(enabled: boolean | undefined, pool: ReadonlyArray<{
349
+ file: string;
350
+ }>): {
351
+ rerankPool?: Array<{
352
+ file: string;
353
+ }>;
354
+ };
355
+ export declare function semanticDocTargets(scope: 'surfaced' | 'all' | undefined, docTextOf: ReadonlyMap<string, string>, surfaced: readonly string[]): string[];
325
356
  /**
326
357
  * @implements A-SPEC-475
327
358
  * One case of the semantic arm, pure given an embedder: documents follow the S-491 convention
@@ -35,8 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.uncitedDiffs = uncitedDiffs;
37
37
  exports.runReplay = runReplay;
38
+ exports.rerankPoolField = rerankPoolField;
39
+ exports.semanticDocTargets = semanticDocTargets;
38
40
  exports.semanticCaseRanking = semanticCaseRanking;
39
- // @implements A-SPEC-346, A-SPEC-734, A-SPEC-758, A-SPEC-469.1, A-SPEC-469.2
41
+ // @implements A-SPEC-346, A-SPEC-734, A-SPEC-758, A-SPEC-469.1, A-SPEC-469.2, A-SPEC-791.2
40
42
  // @implements A-SPEC-347
41
43
  // @implements A-SPEC-348
42
44
  // @implements A-SPEC-349
@@ -420,7 +422,7 @@ async function runReplay(corpus, limit, opts = {}) {
420
422
  const dumpDocText = (0, vector_coverage_1.docTextIndex)(scanned);
421
423
  const targets = [...new Set([...result.candidates.map((x) => x.file),
422
424
  ...(result.impacts?.rankedImpact ?? []).map((r) => r.file)])];
423
- const texts = targets.map((f) => dumpDocText.get(f)).filter((t) => t !== undefined);
425
+ const texts = semanticDocTargets(opts.productSemantic.scope, dumpDocText, targets); // A-SPEC-791.1
424
426
  const [qv] = await opts.productSemantic.embedBatch([c.subject], 'query');
425
427
  const dvs = texts.length > 0 ? await opts.productSemantic.embedBatch(texts, 'doc') : [];
426
428
  const vecOf = new Map(texts.map((t, i) => [t, dvs[i] ?? null]));
@@ -495,6 +497,9 @@ async function runReplay(corpus, limit, opts = {}) {
495
497
  truthSymbols, rankedSymbols,
496
498
  ...(bodies !== undefined ? { bodies } : {}),
497
499
  ...(judgementBundle !== undefined ? { judgementBundle } : {}),
500
+ // A-SPEC-791.1: part of the product response on the cloud tier; absent elsewhere, so earlier dumps keep their bytes.
501
+ ...(dumpResult.semanticAlternates !== undefined ? { semanticAlternates: dumpResult.semanticAlternates } : {}),
502
+ ...rerankPoolField(opts.dumpRerankPool, dumpResult.rerankPool), // A-SPEC-791.2
498
503
  });
499
504
  }
500
505
  // Same case, same truth, same `topN` the product used — an arm scored against a different
@@ -963,6 +968,24 @@ function reachableFrom(graph, scanned, seed) {
963
968
  return [...seen].filter((id) => id.startsWith('CODE:') && id.includes('@'))
964
969
  .map((id) => id.slice(id.lastIndexOf('@') + 1));
965
970
  }
971
+ /**
972
+ * @implements A-SPEC-791.1 — which document texts the dump's product-semantic pass embeds. `surfaced` (the default)
973
+ * keeps the original contract: only files the 1-pass emitted. `all` embeds every scanned file, as a warmed product
974
+ * holds them — the cloud-only alternates (A-SPEC-494) scan every file and could never fire on the surfaced set.
975
+ */
976
+ /**
977
+ * @implements A-SPEC-791.2 — the product's lexical rerank pool, as files in pool order, on a dump row only when asked;
978
+ * absent otherwise so every earlier dump keeps its bytes. It is the same-budget opponent the cloud alternates are scored
979
+ * against.
980
+ */
981
+ function rerankPoolField(enabled, pool) {
982
+ return enabled === true ? { rerankPool: pool.map((x) => ({ file: x.file })) } : {};
983
+ }
984
+ function semanticDocTargets(scope, docTextOf, surfaced) {
985
+ if (scope === 'all')
986
+ return [...docTextOf.values()];
987
+ return surfaced.map((f) => docTextOf.get(f)).filter((t) => t !== undefined);
988
+ }
966
989
  /**
967
990
  * @implements A-SPEC-475
968
991
  * One case of the semantic arm, pure given an embedder: documents follow the S-491 convention
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.37.1",
4
+ "version": "0.38.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",
@@ -15,7 +15,8 @@ description: >-
15
15
  검증에 걸리고, 봉인 후 본문을 고치면 `post-approval-edit`으로, 부모가 움직이면 `stale-parent`로
16
16
  걸린다(REQ-132). `spec_approve`는 사람의 승인을 요구한다(fail-closed) — 요청 인자로는 대체되지 않는다.
17
17
  사람은 세션의 승인 창에서 답한다. 거부가 `[승인 대기 req-…]`를 지목했다면 `approval_ask`에 그 id를 넘겨
18
- 창을 띄운다(0.37.0). 창이 없는 세션에서는 운영자가 자기 터미널에서 `holmes-kit approve --grant <id>`로 결정한다.
18
+ 창을 띄운다(0.37.0). 창이 없는 세션에서는 같은 작업공간의 Claude Code 세션 승인 창에서 결정한다 —
19
+ 명령을 입력하라고 사람에게 넘기지 않는다(0.38.0, REQ-792).
19
20
 
20
21
  이 플레이북은 그 승인을 **언제·무엇에·어떤 근거로** 하는지를 다룬다. 문서를 새로 쓰는 일이라면
21
22
  이것이 아니라 `author-slice`다 — 판별은 3단계에 있다.