@holmes-lab/holmes-kit 0.37.1 → 0.37.2

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.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
  <!-- @implements A-SPEC-209 -->
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.37.2] - 2026-10-22
11
+
12
+ Three approval-UX fixes found by the SDLC comparison's feasibility gate (G0). In G0 round 1, headless Claude Code agents in Holmes workspaces filed 11 approval requests. One of them ended a run waiting for a person who was never coming, so the run changed no code. With these fixes, rounds 2 and 3 had no run blocked by an approval.
13
+
14
+ ### Fixed
15
+ - **Session autonomy is granted in the session's approval form (A-SPEC-718.7).**
16
+ - Before, from an agent's shell, `holmes-kit autonomy on` was refused with "the operator decides in the session's approval dialog", but it filed nothing for that dialog to decide. The only way through was the operator's own terminal.
17
+ - Now the refusal files an `autonomy-grant` request. Its subject names the duration, so a grant for 4h cannot enable 7d. The person approves it with `approval_ask`, and the same command then proceeds once and spends the grant.
18
+ - A person at their own terminal is unchanged.
19
+ - `holmes-kit doctor` now reports the autonomy posture `autonomy status` reports. Before, it said OFF beside a live session grant, because it read only the init default.
20
+ - **An autonomy refusal the agent can resolve by itself says how (A-SPEC-532.7).** When `upstream-without-aspec` or `files-to-touch-empty` holds a seal, the refusal now names the step: write the A-SPEC beneath it, drafts included, or fill in its Files to Touch, then seal again. No person is needed. Before, a Haiku agent sealed its REQ first, asked a person twice, and ended without changing code.
21
+ - **Two gate refusals name the route that needs no person (A-SPEC-773.4).**
22
+ - A read over `.ax` that the gate cannot judge now names the single-command reads it admits (`cat .ax/specs/*/<ID>.md | head`, `grep -n …`, `sed -n …`) and the Read tool.
23
+ - An `rm -rf` of an absolute temporary path now says that `holmes-kit scratch --new <label>` prints a directory the agent may create, fill and remove with no person.
24
+ - Every verdict is unchanged. The temporary-directory refusal itself stays (owner decision).
25
+
10
26
  ## [0.37.1] - 2026-10-21
11
27
 
12
28
  Two fixes. On Windows, 0.37.0 refused grants from a person's own terminal; Windows has been checked with fixture tests here but not yet re-measured on a Windows machine. The traced-files badge now counts only what git tracks.
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **466/466** source files (100%) trace to an approved spec · **937/1013** approved A-SPECs (92.4%) are anchored from code.
13
- Measured at `fd66f7ce5fef` (specs `sha256:7a6c4957d5c0`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
12
+ **474/474** source files (100%) trace to an approved spec · **945/1021** approved A-SPECs (92.5%) are anchored from code.
13
+ Measured at `1d8fd9d2ab01` (specs `sha256:7cc2b555ea49`) — reproduce with `holmes-kit attest --exclude docs/goals/probes/`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 829a8208-mvhbw5jo
1
+ 40e7e026-mvibagi4
@@ -20,6 +20,50 @@ export interface AutonomyResult {
20
20
  exitCode: 0 | 1 | 2;
21
21
  message: string;
22
22
  }
23
+ export type AutonomyGrantVerdict = {
24
+ proceed: true;
25
+ approval?: Approval;
26
+ spend?: string;
27
+ } | {
28
+ proceed: false;
29
+ id: string;
30
+ message: string;
31
+ };
32
+ export interface AutonomyGrantDeps {
33
+ guard: () => string | null;
34
+ resolve: (askRoot: string, env: Approval | undefined, action: {
35
+ kind: string;
36
+ target: string;
37
+ subject: string;
38
+ }, now: string) => {
39
+ approval: Approval;
40
+ source: 'env' | 'grant';
41
+ } | undefined;
42
+ enqueue: (askRoot: string, req: {
43
+ kind: string;
44
+ target: string;
45
+ why: string;
46
+ subject: string;
47
+ title: string;
48
+ }) => void;
49
+ }
50
+ /**
51
+ * @implements A-SPEC-718.7 — may `autonomy on` proceed? In order: an approval that covers this exact grant (the env
52
+ * token, or the grant the person's answer in the session form minted — `approval_ask`); a person at their own terminal;
53
+ * otherwise a request the session form can decide. Measured 2026-10-21: the refusal promised "the session's approval
54
+ * dialog" but filed nothing, so the only way through was a terminal the owner had asked never to need. The duration is
55
+ * the request's subject, so a grant for 4h cannot enable 7d. The request lives in the asking session's project
56
+ * (`askRoot`), where its `approval_ask` can find it, and names the workspace it would change.
57
+ */
58
+ export declare function autonomyGrantGate(input: {
59
+ root: string;
60
+ askRoot: string;
61
+ mins: number;
62
+ now: string;
63
+ envApproval?: Approval;
64
+ }, deps: AutonomyGrantDeps): AutonomyGrantVerdict;
65
+ /** @implements A-SPEC-718.7 — the posture `autonomy status` reports, never coloured by the caller's own environment. */
66
+ export declare function autonomyPostureLine(root: string, now: string): string;
23
67
  /**
24
68
  * The `holmes-kit autonomy status|on|off|delegate|revoke-delegation` core. Pure over injected io (clock/TTY/approval/
25
69
  * env) so every branch is testable. Enabling (`on`) and delegating are protected exactly like `init --autonomy`: the
@@ -34,8 +34,10 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.parseForMinutes = parseForMinutes;
37
+ exports.autonomyGrantGate = autonomyGrantGate;
38
+ exports.autonomyPostureLine = autonomyPostureLine;
37
39
  exports.runAutonomy = runAutonomy;
38
- // @implements A-SPEC-553.1, A-SPEC-553.2, A-SPEC-771
40
+ // @implements A-SPEC-553.1, A-SPEC-553.2, A-SPEC-771, A-SPEC-718.7
39
41
  const fs = __importStar(require("node:fs"));
40
42
  const path = __importStar(require("node:path"));
41
43
  const risk_gate_1 = require("../guardrail/risk-gate");
@@ -44,6 +46,7 @@ const delegation_1 = require("../governance/delegation");
44
46
  const PROJECT_DEFAULT_ON = 'autonomous spec approval: ON (project default, .mcp.json) — governance-critical still ask you. '
45
47
  + 'Turn it off by removing HOLMES_AUTONOMOUS_APPROVAL from .mcp.json (or holmes-kit init --no-autonomy).';
46
48
  const ledger_store_1 = require("../governance/ledger-store");
49
+ const approval_queue_1 = require("../governance/approval-queue");
47
50
  const provenance_chain_1 = require("../governance/provenance-chain");
48
51
  /** `--for` accepts `2h` / `90m` / `7d` / a bare number of hours. Minutes, capped at 7 days (like grants);
49
52
  * null on a malformed value; default 2h when omitted. */
@@ -86,6 +89,33 @@ function revokeDelegationQuietly(root, io, rationale) {
86
89
  }
87
90
  catch { /* the document is gone either way */ }
88
91
  }
92
+ /**
93
+ * @implements A-SPEC-718.7 — may `autonomy on` proceed? In order: an approval that covers this exact grant (the env
94
+ * token, or the grant the person's answer in the session form minted — `approval_ask`); a person at their own terminal;
95
+ * otherwise a request the session form can decide. Measured 2026-10-21: the refusal promised "the session's approval
96
+ * dialog" but filed nothing, so the only way through was a terminal the owner had asked never to need. The duration is
97
+ * the request's subject, so a grant for 4h cannot enable 7d. The request lives in the asking session's project
98
+ * (`askRoot`), where its `approval_ask` can find it, and names the workspace it would change.
99
+ */
100
+ function autonomyGrantGate(input, deps) {
101
+ const action = { kind: 'autonomy-grant', target: input.root, subject: `for=${input.mins}m` };
102
+ const covering = deps.resolve(input.askRoot, input.envApproval, action, input.now);
103
+ if (covering !== undefined) {
104
+ const nonce = covering.approval.nonce;
105
+ return { proceed: true, approval: covering.approval, ...(covering.source === 'grant' && typeof nonce === 'string' ? { spend: nonce } : {}) };
106
+ }
107
+ const why = deps.guard();
108
+ if (why === null)
109
+ return { proceed: true };
110
+ const title = `session autonomy for ${input.mins} minutes`;
111
+ deps.enqueue(input.askRoot, { ...action, why: `enable autonomous spec approval in ${input.root} for ${input.mins} minutes`, title });
112
+ const id = (0, approval_queue_1.approvalRequestId)(action.kind, action.target);
113
+ return { proceed: false, id, message: `${why}${(0, approval_queue_1.pendingRequestLine)(id, action.kind, input.askRoot, title, input.root)}` };
114
+ }
115
+ /** @implements A-SPEC-718.7 — the posture `autonomy status` reports, never coloured by the caller's own environment. */
116
+ function autonomyPostureLine(root, now) {
117
+ return runAutonomy(root, 'status', undefined, { now, isTTY: false, env: {} }).message;
118
+ }
89
119
  /**
90
120
  * The `holmes-kit autonomy status|on|off|delegate|revoke-delegation` core. Pure over injected io (clock/TTY/approval/
91
121
  * env) so every branch is testable. Enabling (`on`) and delegating are protected exactly like `init --autonomy`: the
@@ -1531,19 +1531,10 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1531
1531
  // @implements A-SPEC-552.1 — surface the project's autonomy posture so a human always knows
1532
1532
  // whether the agent may self-approve. Read from the SAME place the MCP server does (.mcp.json
1533
1533
  // server env), never from doctor's own process, for the reason stated above.
1534
- let autonomyOn = false;
1535
- try {
1536
- const raw = fs.readFileSync(path.join(target, '.mcp.json'), 'utf8');
1537
- const env = JSON.parse(raw)
1538
- .mcpServers?.[init_1.SERVER_NAME]?.env;
1539
- autonomyOn = !!env && !!env['HOLMES_AUTONOMOUS_APPROVAL'];
1540
- }
1541
- catch {
1542
- autonomyOn = false;
1543
- }
1544
- add('autonomous spec approval', 'PASS', autonomyOn
1545
- ? 'ON — the agent may self-approve low-risk specs; governance-critical still ask you (holmes-kit autonomy off to disable)'
1546
- : 'OFF — every spec approval is human (enable at init, or holmes-kit autonomy on for one session)');
1534
+ // @implements A-SPEC-718.7 — the posture `autonomy status` reports (project default, session grant with its expiry, run
1535
+ // delegation, or OFF). Reading only the init default, this row said OFF beside a live session grant (2026-10-21).
1536
+ const { autonomyPostureLine } = require('./autonomy');
1537
+ add('autonomous spec approval', 'PASS', autonomyPostureLine(target, new Date().toISOString()).replace(/^autonomous spec approval: /, ''));
1547
1538
  // @implements A-SPEC-251.2 — the version this project's MCP server will ACTUALLY launch, vs this
1548
1539
  // CLI. The stale-global trap (measured 2026-08-23: .mcp.json pinned a 0.1.9 global while the user
1549
1540
  // believed they had upgraded) was invisible because nothing compared them. Offline: the launch
@@ -464,7 +464,7 @@ async function main(argv) {
464
464
  // foreground human act (raw-TTY proof, or an out-of-band HOLMES_APPROVAL for the non-interactive
465
465
  // path); the marker lives in the agent-write-protected .ax/state/, so a session cannot self-grant.
466
466
  if (cmd === 'autonomy') {
467
- const { runAutonomy } = await Promise.resolve().then(() => __importStar(require('./autonomy')));
467
+ const { runAutonomy, parseForMinutes, autonomyGrantGate } = await Promise.resolve().then(() => __importStar(require('./autonomy')));
468
468
  const root = path.resolve(typeof flags.target === 'string' ? flags.target : process.cwd());
469
469
  const forStr = typeof flags.for === 'string' ? flags.for : undefined;
470
470
  // @implements A-SPEC-771.1 — the delegation's own inputs ride through to the core; `--limit` may repeat.
@@ -476,13 +476,42 @@ async function main(argv) {
476
476
  // @implements A-SPEC-779.4 — the terminal path proves a person only when no agent harness started this process;
477
477
  // a covering out-of-band approval is its own proof and keeps its path.
478
478
  const sub = positionals[0];
479
- if (sub === 'on' || sub === 'delegate') {
479
+ const { operatorActGuard } = require('../guardrail/operator-person');
480
+ const { withRefusalLine } = require('../guardrail/refusal-codes');
481
+ let effective = approval;
482
+ let spend;
483
+ const minutes = sub === 'on' ? parseForMinutes(forStr) : null;
484
+ if (sub === 'on' && minutes !== null) {
485
+ // @implements A-SPEC-718.7 — the person grants it in the session form: a refused `on` files an autonomy-grant
486
+ // request in the asking session's project (where approval_ask finds it), and the retry spends the grant.
487
+ const { resolveApproval } = require('../governance/approval-grants');
488
+ const { enqueueApprovalRequest } = require('../governance/approval-queue');
489
+ const { resolveProjectRoot } = require('../project/root');
490
+ let askRoot = root;
491
+ try {
492
+ const p = resolveProjectRoot(process.cwd());
493
+ if (p.marker === '.ax')
494
+ askRoot = p.root;
495
+ }
496
+ catch { /* the target's own project */ }
497
+ const v = autonomyGrantGate({ root, askRoot, mins: minutes, now, envApproval: approval }, {
498
+ guard: () => operatorActGuard('enabling session autonomy'),
499
+ resolve: (r, env, action, n) => resolveApproval(r, env, action, n),
500
+ enqueue: (r, req) => { enqueueApprovalRequest(r, req); },
501
+ });
502
+ if (!v.proceed) {
503
+ process.stderr.write(`${withRefusalLine(v.message)}\n`);
504
+ return 2;
505
+ }
506
+ effective = v.approval;
507
+ if (v.spend !== undefined)
508
+ spend = { root: askRoot, nonce: v.spend };
509
+ }
510
+ else if (sub === 'delegate') {
480
511
  const { approvalCovers } = require('../guardrail/risk-gate');
481
512
  if (!approvalCovers(approval, { kind: 'autonomy-grant', target: root }, now)) {
482
- const { operatorActGuard } = require('../guardrail/operator-person');
483
- const why = operatorActGuard(sub === 'on' ? 'enabling session autonomy' : 'issuing a run delegation');
513
+ const why = operatorActGuard('issuing a run delegation');
484
514
  if (why !== null) {
485
- const { withRefusalLine } = require('../guardrail/refusal-codes');
486
515
  process.stderr.write(`${withRefusalLine(why)}\n`);
487
516
  return 2;
488
517
  }
@@ -491,8 +520,12 @@ async function main(argv) {
491
520
  const r = runAutonomy(root, sub, forStr, {
492
521
  now,
493
522
  isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY,
494
- approval,
523
+ approval: effective,
495
524
  }, extra);
525
+ if (r.ok && spend !== undefined) {
526
+ const { consumeGrantFile } = require('../governance/approval-grants');
527
+ consumeGrantFile(spend.root, spend.nonce);
528
+ }
496
529
  process[r.ok ? 'stdout' : 'stderr'].write(`${r.message}\n`);
497
530
  return r.exitCode;
498
531
  });
@@ -27,6 +27,13 @@ export declare function specApprovalAutonomy(spec: Spec, resolveParent: (id: str
27
27
  export declare function declaredGateDirection(spec: Spec): 'tightens' | 'wording' | null;
28
28
  /** @implements A-SPEC-532.3 — one plain clause per rule name, for the refusal a person reads. */
29
29
  export declare function autonomyRuleMeaning(rule: string): string;
30
+ /**
31
+ * @implements A-SPEC-532.7 — the step that resolves a rule without a person, or '' when only a person can. Measured in
32
+ * G0 round 1 (2026-10-21): a Haiku agent sealed REQ-001 first, got `upstream-without-aspec`, asked a person twice
33
+ * through approval_ask in a headless run, and ended without changing code. `descendantAspecs` counts drafts, so writing
34
+ * the A-SPEC beneath makes the same seal gradable — the refusal never said so.
35
+ */
36
+ export declare function autonomyNextStep(rule: string, specId: string): string;
30
37
  /**
31
38
  * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
32
39
  * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
@@ -39,6 +39,7 @@ exports.descendantAspecs = descendantAspecs;
39
39
  exports.specApprovalAutonomy = specApprovalAutonomy;
40
40
  exports.declaredGateDirection = declaredGateDirection;
41
41
  exports.autonomyRuleMeaning = autonomyRuleMeaning;
42
+ exports.autonomyNextStep = autonomyNextStep;
42
43
  exports.specApprovalAutonomyReason = specApprovalAutonomyReason;
43
44
  exports.ceilingRefusal = ceilingRefusal;
44
45
  exports.requiresAutonomousApprovalPrompt = requiresAutonomousApprovalPrompt;
@@ -49,7 +50,7 @@ exports.autonomyBanner = autonomyBanner;
49
50
  exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
50
51
  exports.versionBumpKind = versionBumpKind;
51
52
  exports.releaseAutonomy = releaseAutonomy;
52
- // @implements A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4
53
+ // @implements A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4, A-SPEC-532.7
53
54
  // Whether a spec approval may be sealed AUTONOMOUSLY by the agent, or must still ask a human through
54
55
  // the MCP elicitation TUI. The governance chain (REQ→H→A→T→CPG + RTM + taint + phase gate) already
55
56
  // forces quality structurally, so a low/mid-risk spec self-approving under an explicitly-enabled
@@ -201,6 +202,23 @@ function autonomyRuleMeaning(rule) {
201
202
  default: return 'the spec kind is not one the grader knows';
202
203
  }
203
204
  }
205
+ /**
206
+ * @implements A-SPEC-532.7 — the step that resolves a rule without a person, or '' when only a person can. Measured in
207
+ * G0 round 1 (2026-10-21): a Haiku agent sealed REQ-001 first, got `upstream-without-aspec`, asked a person twice
208
+ * through approval_ask in a headless run, and ended without changing code. `descendantAspecs` counts drafts, so writing
209
+ * the A-SPEC beneath makes the same seal gradable — the refusal never said so.
210
+ */
211
+ function autonomyNextStep(rule, specId) {
212
+ if (rule === 'upstream-without-aspec') {
213
+ return `\n[next, no person needed: scaffold the H-SPEC and A-SPEC beneath ${specId} (drafts are fine) and write the A-SPEC's `
214
+ + `Files to Touch, then call spec_approve on ${specId} again — with an A-SPEC beneath it this seal is graded on that `
215
+ + 'scope, automatically when nothing else holds it; spec_slice_approve seals the chain in order]';
216
+ }
217
+ if (rule === 'files-to-touch-empty') {
218
+ return `\n[next, no person needed: write the paths this change touches under ## Files to Touch in ${specId}, then call spec_approve again]`;
219
+ }
220
+ return '';
221
+ }
204
222
  /**
205
223
  * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
206
224
  * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
@@ -47,7 +47,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
47
47
  exports.classifySecret = classifySecret;
48
48
  exports.classifyBlastRadius = classifyBlastRadius;
49
49
  exports.assessRisk = assessRisk;
50
- // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3
50
+ // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4
51
51
  const fs = __importStar(require("node:fs"));
52
52
  const path = __importStar(require("node:path"));
53
53
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -260,7 +260,9 @@ function rmDangerReason(cmd, signals) {
260
260
  // @implements A-SPEC-773.2 — an absolute target is where an agent's temporary work usually is: name the place
261
261
  // whose directories it may remove (round 1, quality: nothing told an agent the scratch root exists).
262
262
  const hint = targets.some((t) => t.replace(/^["']/, '').startsWith('/'))
263
- ? '; agent temporary work belongs under `holmes-kit scratch --new <label>` (POSIX), whose directories an agent may remove' : '';
263
+ // @implements A-SPEC-773.4 — say what the command gives back and that it needs no person (G0 round 1: 4 of 6 runs
264
+ // filed an approval request for an rm of their own /tmp directory instead).
265
+ ? '; no person needed for temporary work: `holmes-kit scratch --new <label>` prints a directory that you may create, fill and rm -rf — use it instead of /tmp (POSIX)' : '';
264
266
  return `recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction${hint}`;
265
267
  }
266
268
  if (targets.length > 0 && safeties.every((s) => s === 'safe'))
@@ -1860,7 +1862,9 @@ function classifyReversibilityAsWritten(action) {
1860
1862
  return {
1861
1863
  axis,
1862
1864
  level: 'hard-hitl',
1863
- reasons: ['shell command over a protected .ax governance path is not recognisably read-only'],
1865
+ // @implements A-SPEC-773.4 — name the reads the gate already admits (G0 round 1: 5 of 6 runs filed an approval
1866
+ // request for a read loop it could not judge, while one read command with a glob passes).
1867
+ reasons: ['shell command over a protected .ax governance path is not recognisably read-only; to read, use one read command with literal paths or a glob — `cat .ax/specs/*/<ID>.md | head`, `grep -n <word> .ax/specs/…`, `sed -n 1,80p <file>` — or the Read tool; loops, xargs and sh -c are not judged as reads'],
1864
1868
  };
1865
1869
  }
1866
1870
  // @implements A-SPEC-226.3 — the same act without the spelling.
@@ -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-182.3, A-SPEC-718.3, A-SPEC-770.6, A-SPEC-718.1,A-SPEC-718.2, 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
38
+ // @implements A-SPEC-182.3, A-SPEC-718.3, A-SPEC-770.6, A-SPEC-718.1,A-SPEC-718.2, 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, A-SPEC-532.7
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");
@@ -210,7 +210,7 @@ function createSpecApprovalHandlers(context) {
210
210
  else if (autonomyOn && risk === 'hitl') {
211
211
  const rule = noIntake ? 'requirement-without-intake' : (0, autonomy_1.specApprovalAutonomyReason)(target.spec, resolver([target.spec]), below);
212
212
  if (rule !== null) {
213
- autonomyNote = `\n[autonomy: this seal is the operator's — ${rule} (${(0, autonomy_1.autonomyRuleMeaning)(rule)})]`;
213
+ autonomyNote = `\n[autonomy: this seal is the operator's — ${rule} (${(0, autonomy_1.autonomyRuleMeaning)(rule)})]${(0, autonomy_1.autonomyNextStep)(rule, a.id)}`; // A-SPEC-532.7
214
214
  // @implements A-SPEC-771 — the operator's run delegation may cover this very rule: then the seal proceeds
215
215
  // as a DELEGATED grant (actor `delegated:<client>`, the run and the rule in the ledger) and no person is
216
216
  // asked; otherwise the refusal names which limit of the delegation applied. The grader's verdict above
@@ -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.37.2",
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",