@holmes-lab/holmes-kit 0.35.1 → 0.35.3

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 (35) hide show
  1. package/CHANGELOG.md +72 -0
  2. package/README.md +6 -3
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve.js +9 -2
  5. package/dist/holmes/cli/doctor.js +21 -2
  6. package/dist/holmes/cli/init.d.ts +2 -0
  7. package/dist/holmes/cli/init.js +37 -1
  8. package/dist/holmes/cli/runtime-binding.d.ts +16 -0
  9. package/dist/holmes/cli/runtime-binding.js +62 -2
  10. package/dist/holmes/governance/approval-grants.d.ts +7 -0
  11. package/dist/holmes/governance/approval-grants.js +8 -2
  12. package/dist/holmes/governance/approval-queue.d.ts +5 -0
  13. package/dist/holmes/governance/approval-queue.js +14 -3
  14. package/dist/holmes/governance/autonomy.d.ts +10 -1
  15. package/dist/holmes/governance/autonomy.js +66 -14
  16. package/dist/holmes/guardrail/risk-classifier.js +32 -3
  17. package/dist/holmes/guardrail/write-verb-word.d.ts +13 -0
  18. package/dist/holmes/guardrail/write-verb-word.js +55 -0
  19. package/dist/holmes/hooks/pre-tool-use.d.ts +2 -0
  20. package/dist/holmes/hooks/pre-tool-use.js +32 -9
  21. package/dist/holmes/mcp/approval-policy.d.ts +4 -1
  22. package/dist/holmes/mcp/approval-policy.js +5 -4
  23. package/dist/holmes/mcp/elicit-approval.d.ts +0 -2
  24. package/dist/holmes/mcp/elicit-approval.js +3 -4
  25. package/dist/holmes/mcp/handlers/review-evidence.d.ts +1 -2
  26. package/dist/holmes/mcp/handlers/review-evidence.js +4 -12
  27. package/dist/holmes/mcp/handlers/spec-approval.d.ts +2 -2
  28. package/dist/holmes/mcp/handlers/spec-approval.js +18 -11
  29. package/dist/holmes/mcp/handlers.d.ts +1 -9
  30. package/dist/holmes/mcp/handlers.js +7 -7
  31. package/dist/holmes/mcp/harness-attestation.d.ts +10 -1
  32. package/dist/holmes/mcp/harness-attestation.js +70 -3
  33. package/dist/holmes/mcp/operator-recovery.js +4 -1
  34. package/dist/holmes/mcp/server.js +6 -3
  35. package/package.json +1 -1
@@ -37,6 +37,9 @@ exports.SESSION_AUTONOMY_MARKER = exports.AUTONOMY_ENV = void 0;
37
37
  exports.isHighRiskPath = isHighRiskPath;
38
38
  exports.descendantAspecs = descendantAspecs;
39
39
  exports.specApprovalAutonomy = specApprovalAutonomy;
40
+ exports.declaredGateDirection = declaredGateDirection;
41
+ exports.autonomyRuleMeaning = autonomyRuleMeaning;
42
+ exports.specApprovalAutonomyReason = specApprovalAutonomyReason;
40
43
  exports.requiresAutonomousApprovalPrompt = requiresAutonomousApprovalPrompt;
41
44
  exports.sessionAutonomyActive = sessionAutonomyActive;
42
45
  exports.projectDefaultAutonomy = projectDefaultAutonomy;
@@ -45,7 +48,7 @@ exports.autonomyBanner = autonomyBanner;
45
48
  exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
46
49
  exports.versionBumpKind = versionBumpKind;
47
50
  exports.releaseAutonomy = releaseAutonomy;
48
- // @implements A-SPEC-532.1, A-SPEC-718
51
+ // @implements A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4
49
52
  // Whether a spec approval may be sealed AUTONOMOUSLY by the agent, or must still ask a human through
50
53
  // the MCP elicitation TUI. The governance chain (REQ→H→A→T→CPG + RTM + taint + phase gate) already
51
54
  // forces quality structurally, so a low/mid-risk spec self-approving under an explicitly-enabled
@@ -155,40 +158,89 @@ function descendantAspecs(spec, all) {
155
158
  * or no A-SPEC at all (unknown scope) → human. The two-argument call keeps the old answer.
156
159
  */
157
160
  function specApprovalAutonomy(spec, resolveParent, descendants) {
161
+ // @implements A-SPEC-532.3 — one walk: the verdict is "no rule fired", so it cannot disagree with the rule's name.
162
+ return specApprovalAutonomyReason(spec, resolveParent, descendants) === null ? 'auto' : 'hitl';
163
+ }
164
+ /**
165
+ * @implements A-SPEC-532.4 — the declared direction of a gate change: `gate-behavior: tightens — …` (nothing refused
166
+ * before passes after) or `gate-behavior: wording — …` (no input changes side). Owner decision 2026-10-05: these are
167
+ * sealed autonomously; any other gate change asks the owner. The word is the first of the reason, read
168
+ * case-sensitively, and must be followed by white space or a dash.
169
+ */
170
+ function gateDirection(spec) {
171
+ const raw = spec.frontmatter?.breaking_change;
172
+ if (typeof raw !== 'string')
173
+ return null;
174
+ const m = /^\s*gate-behavior\s*:\s*(tightens|wording)(?=[\s—–-])/.exec(raw);
175
+ return m ? m[1] : null;
176
+ }
177
+ function declaredGateDirection(spec) {
178
+ return spec.type === 'A-SPEC' ? gateDirection(spec) : null;
179
+ }
180
+ /** @implements A-SPEC-532.3 — one plain clause per rule name, for the refusal a person reads. */
181
+ function autonomyRuleMeaning(rule) {
182
+ if (rule.startsWith('files-to-touch-gate-file'))
183
+ return 'Files to Touch names a gate or governance file and the spec declares no tightening-only or wording-only gate change';
184
+ if (rule === 'breaking-change-gate-behavior')
185
+ return 'the gate change does not declare its direction as tightens or wording';
186
+ if (rule.startsWith('breaking-change-'))
187
+ return rule === 'breaking-change-undeclared' ? 'breaking_change is not declared' : 'the breaking_change grade is not one the grader knows';
188
+ switch (rule) {
189
+ case 'upstream-without-aspec': return 'no A-SPEC exists beneath it yet, so its scope is unknown';
190
+ case 'upstream-has-human-aspec': return 'an A-SPEC beneath it is the operator\'s to seal';
191
+ case 'architecture-document': return 'a C-SPEC or ADR is a decision';
192
+ case 'files-to-touch-empty': return 'Files to Touch names no path, so its scope is unbounded';
193
+ case 'files-to-touch-root-only': return 'Files to Touch names only root-level files';
194
+ case 'requirement-without-intake': return 'the requirement was never admitted through requirement_triage';
195
+ default: return 'the spec kind is not one the grader knows';
196
+ }
197
+ }
198
+ /**
199
+ * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
200
+ * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
201
+ * could tell which rule had fired.
202
+ */
203
+ function specApprovalAutonomyReason(spec, resolveParent, descendants) {
158
204
  switch (spec.type) {
159
205
  case 'T-SPEC':
160
- return 'auto'; // tests are low risk
206
+ return null; // tests are low risk
161
207
  case 'REQ':
162
208
  case 'H-SPEC': {
163
209
  const below = (descendants ?? []).filter((s) => s.type === 'A-SPEC');
164
210
  if (below.length === 0)
165
- return 'hitl'; // unknown scope stays human
166
- return below.every((a) => specApprovalAutonomy(a, resolveParent) === 'auto') ? 'auto' : 'hitl';
211
+ return 'upstream-without-aspec'; // unknown scope stays human
212
+ return below.every((a) => specApprovalAutonomyReason(a, resolveParent) === null) ? null : 'upstream-has-human-aspec';
167
213
  }
168
214
  case 'C-SPEC':
169
215
  case 'ADR': // @implements A-SPEC-571.1 — a decision is the human's to seal
170
- return 'hitl'; // architecture / structural constraint — the owner's exception
216
+ return 'architecture-document'; // architecture / structural constraint — the owner's exception
171
217
  case 'A-SPEC': {
172
218
  const grade = breakingGrade(spec);
173
- if (grade === null || !AUTO_GRADES.has(grade))
174
- return 'hitl'; // undeclared or gate-behavior
219
+ if (grade === null)
220
+ return 'breaking-change-undeclared';
221
+ // @implements A-SPEC-532.4 — a gate change that declares tightening or wording passes the grade rule and the
222
+ // gate-file rule; an undirected one, and a gate file under any other grade, do not.
223
+ const directed = grade === 'gate-behavior' && gateDirection(spec) !== null;
224
+ if (!directed && !AUTO_GRADES.has(grade))
225
+ return `breaking-change-${grade}`; // gate-behavior, or unrecognised
175
226
  const paths = (0, scope_judgment_1.fttPathTokens)(spec.sections['Files to Touch'] ?? '');
176
227
  // @implements A-SPEC-556.1 — no path tokens (prose-only / empty FtT) is an UNCONSTRAINED scope:
177
228
  // the enforcer imposes nothing, so the spec can write ANYWHERE incl. the gate. Never self-approve.
178
229
  if (paths.length === 0)
179
- return 'hitl';
180
- if (paths.some(isHighRiskPath))
181
- return 'hitl'; // gate/governance/taint file
230
+ return 'files-to-touch-empty';
231
+ const gateFile = paths.find(isHighRiskPath);
232
+ if (gateFile !== undefined && !directed)
233
+ return `files-to-touch-gate-file: ${gateFile}`; // gate/governance/taint file
182
234
  // @implements A-SPEC-654 — a ROOT-level file is project-wide configuration (the test runner, the
183
235
  // manifest, the ignore policy): admitting it at the gate was the point of that slice, but grading
184
236
  // it auto would be a widening nobody asked for. A spec earns self-approval only when it also names
185
237
  // a directory-scoped surface — the same doubt `paths.length === 0` already encodes.
186
238
  if (!paths.some((p) => p.includes('/')))
187
- return 'hitl';
188
- return 'auto';
239
+ return 'files-to-touch-root-only';
240
+ return null;
189
241
  }
190
242
  default:
191
- return 'hitl'; // unknown kind: fail-safe to human
243
+ return 'unknown-kind'; // unknown kind: fail-safe to human
192
244
  }
193
245
  }
194
246
  /**
@@ -197,7 +249,7 @@ function specApprovalAutonomy(spec, resolveParent, descendants) {
197
249
  * `specApprovalAutonomy(...) === 'hitl'`: an upstream REQ/H-SPEC with no implemented A-SPEC is
198
250
  * not identified as high-risk yet, so autonomous mode queues it without interrupting the agent.
199
251
  * Architecture, an explicitly high-risk A-SPEC, and an upstream document leading to either remain
200
- * visible to a human; their direct-form timeout is handled separately as an autonomous timeout.
252
+ * visible to a human; a prompt that is not answered is held (A-SPEC-718.1).
201
253
  */
202
254
  function requiresAutonomousApprovalPrompt(spec, descendants) {
203
255
  switch (spec.type) {
@@ -44,7 +44,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
44
44
  exports.classifySecret = classifySecret;
45
45
  exports.classifyBlastRadius = classifyBlastRadius;
46
46
  exports.assessRisk = assessRisk;
47
- // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747, A-SPEC-753
47
+ // @implements A-SPEC-125.1, 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
48
48
  const fs = __importStar(require("node:fs"));
49
49
  const path = __importStar(require("node:path"));
50
50
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -391,6 +391,22 @@ const REMOVAL_VERB_RE = /\b(rm|rmdir|unlink|git\s+rm|git\s+mv|mv|cp)\b/i;
391
391
  // 240 000 of them). A later `>` inside an already-scanned token can only see a suffix of it.
392
392
  const CLOBBER_AX_RE = (0, linear_match_1.redirectTokenTester)(new RegExp(String.raw `\.ax/(${PROTECTED_AX_ALT})\b`, 'i'));
393
393
  const CMD_PROTECTED_AX_RE = new RegExp(String.raw `(^|[\s'"=(/])\.ax/(${PROTECTED_AX_ALT})(/|\b)`, 'i');
394
+ // No boundary after the child either: under a separator the text does not show, `mvq.ax/specsq/tmp/z` is `mv .ax/specs /tmp/z`.
395
+ const PROTECTED_AX_ANYWHERE_RE = new RegExp(String.raw `\.ax/(?:${PROTECTED_AX_ALT})`, 'i');
396
+ /**
397
+ * @implements A-SPEC-226.1 — does the text name a protected .ax path. The pattern above asks for white space, a quote,
398
+ * `=`, `(` or `/` before `.ax/`, so a path glued to an expansion was not one: `rm${IFS}-rf${IFS}.ax/specs/…` and
399
+ * `rm$IFS-rf$IFS.ax/specs` were allowed while `rm -rf .ax/specs/…` was refused (shipped through 0.35.1; measured
400
+ * 2026-10-05). Only tightens: everything the old pattern matched still matches. One linear pattern test.
401
+ */
402
+ function namesProtectedAx(text) {
403
+ // @implements A-SPEC-226.2 — the spelling counts wherever it appears. A-SPEC-226.1 kept "a spelling that continues a
404
+ // longer file name" out, and its re-review (2026-10-05) passed removals through exactly that door: `rm -f $-.ax/specs/…`
405
+ // (dash), `rm -f $X:t.ax/specs/…` (zsh), `P=q.ax/specs; mv ${P#q} /tmp/gone`, `echo mvq.ax/specsq/tmp/z | tr q ' ' | sh`,
406
+ // `sed -n w.ax/ledger/p.jsonl /dev/null`. The text cannot tell a longer file name from a prefix the shell removes, so
407
+ // it no longer tries; 226.1's three rules are subsumed. Cost, stated: `backup.ax/specs` is judged as the store.
408
+ return CMD_PROTECTED_AX_RE.test(text) || PROTECTED_AX_ANYWHERE_RE.test(text);
409
+ }
394
410
  /**
395
411
  * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so
396
412
  * `./.ax//ledger/x` matches the same rules as `.ax/ledger/x` (adversarial probe: those forms slipped
@@ -641,6 +657,11 @@ function normalizeCommandPaths(cmd, followCd = true) {
641
657
  }
642
658
  // File-mutating shell verbs beyond redirect/removal: these WRITE a target path, so a protected path
643
659
  // as their argument is the same governance breach as `>` or `rm` (probe: tee/cp/install slipped).
660
+ // A-SPEC-747.1 rules 1–5 (count a verb only as a shell word) are NOT implemented: the independent review of the first
661
+ // build (2026-10-04) showed the exemption for a verb inside a longer file name passes real writes whenever the shell
662
+ // splits a word the text does not (`cp${IFS}a${IFS}.ax/specs/x.md`, a custom IFS, text re-parsed by `sh -c`). The
663
+ // `\b…\b` test stays; `docs/install-guide.md` beside an .ax path is still refused, on purpose, until a rule exists
664
+ // that the shell cannot split around.
644
665
  const WRITE_VERB_AX_RE = (0, linear_match_1.headThenTail)(/\b(?:tee|cp|install|dd|ln|mv|rsync)\b/i, SEG, new RegExp(String.raw `\.ax/(?:${PROTECTED_AX_ALT})\b`, 'i'));
645
666
  // An interpreter one-liner naming a protected path: `node -e "...appendFileSync('.ax/ledger/...')"`,
646
667
  // `python3 -c "open('.ax/ledger/...','a')"`. Read-only one-liners are not distinguishable from writes
@@ -671,6 +692,8 @@ const READ_ONLY_SHELL = new Set([
671
692
  const READ_ONLY_GIT = new Set([
672
693
  'show', 'log', 'status', 'diff', 'ls-tree', 'ls-files', 'blame', 'cat-file', 'rev-parse',
673
694
  'merge-base', 'describe',
695
+ // @implements A-SPEC-747.1 — `git check-ignore -v .ax/state/…` was refused (measured); it only reads.
696
+ 'check-ignore',
674
697
  ]);
675
698
  /** Is `t` a spelling of the long option `--<full>` that getopt_long accepts (an unambiguous prefix of `min`+ letters)? */
676
699
  function longOption(t, full, min) {
@@ -1419,6 +1442,8 @@ function awkIsRead(clause, args) {
1419
1442
  const FOR_HEAD_RE = /^for\s+[A-Za-z_][A-Za-z0-9_]*\s+in\b/;
1420
1443
  const SUBSTITUTION_RE = /\$\(|`|<\(|>\(/;
1421
1444
  const OUTPUT_REDIRECT_RE = />(?!\s*(?:\/dev\/null\b|&\d))/;
1445
+ /** An output redirect whose target word holds an expansion (`> ${P#q}`, `>> "$f"`, `` > `x` ``). Linear: one word after `>`. */
1446
+ const COMPUTED_REDIRECT_RE = />[>|&]?[ \t]*[^\s;|&<>$`]*[$`]/;
1422
1447
  function clausesAreReads(clauses, isRead) {
1423
1448
  let inLoop = false;
1424
1449
  for (const raw of clauses) {
@@ -1515,7 +1540,7 @@ function stripCommitMessages(cmd) {
1515
1540
  * @implements A-SPEC-226
1516
1541
  */
1517
1542
  function shellWritesProtectedAx(ncmd) {
1518
- if (!CMD_PROTECTED_AX_RE.test(ncmd))
1543
+ if (!namesProtectedAx(ncmd))
1519
1544
  return false;
1520
1545
  // @implements A-SPEC-227 — the ledger exemption is cancelled here, not inside the restore check,
1521
1546
  // because it is a property of the TARGET rather than of the command shape.
@@ -1532,6 +1557,10 @@ function shellWritesProtectedAx(ncmd) {
1532
1557
  sawCd = true;
1533
1558
  else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
1534
1559
  return false;
1560
+ // @implements A-SPEC-226.2 — an output redirect whose target is computed is not a read here: the re-review passed
1561
+ // `P=q.ax/ledger/p.jsonl; echo x > ${P#q}` (the protected spelling in the text, the write through an expansion).
1562
+ if (COMPUTED_REDIRECT_RE.test(c))
1563
+ return false;
1535
1564
  return clauseIsRead(c, isRead);
1536
1565
  });
1537
1566
  }
@@ -1594,7 +1623,7 @@ function classifyReversibilityAsWritten(action) {
1594
1623
  const ncmd = [...new Set([flat, asWritten, bySegment, ...outputTargets])].join('\n');
1595
1624
  // @implements A-SPEC-737 — one reason served all four channels, so an interpreter READ was refused as
1596
1625
  // a "removal command" and the author could not tell what to change. Each channel names itself.
1597
- const axChannel = REMOVAL_VERB_RE.test(ncmd) && CMD_PROTECTED_AX_RE.test(ncmd)
1626
+ const axChannel = REMOVAL_VERB_RE.test(ncmd) && namesProtectedAx(ncmd)
1598
1627
  ? 'removal, move or copy command targets a protected .ax governance path'
1599
1628
  : CLOBBER_AX_RE.test(ncmd) ? 'output redirection writes into a protected .ax governance path'
1600
1629
  : WRITE_VERB_AX_RE.test(ncmd) ? 'file-writing command (tee/cp/install/dd/ln/mv/rsync) targets a protected .ax governance path'
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Whether `text` names one of `verbs` as a shell word, rather than as letters inside another word.
3
+ *
4
+ * Measured 2026-10-04: `\bverb\b` matched `install` in `docs/install-guide.md` and `ln` in `grep -ln`, so read-only
5
+ * commands were refused as file writes. A verb occurrence still counts in every spelling a shell runs it under
6
+ * (`cp`, `/usr/bin/install`, `'cp'`, `cp.exe`, `--to-command=tee`, `rsync-ssl`); only two shapes do not:
7
+ * a. the word is a single-dash option cluster of letters and digits (`-ln`, `-rm1`);
8
+ * b. inside the word the verb is followed by `/`, or the word ends in a file extension other than `.exe`.
9
+ * Callers keep their own matching for what the verb targets — this answers only "is there such a verb at all", so a
10
+ * caller's verdict is removed only when the whole text holds no counting occurrence. One pass: a word's shape is read
11
+ * once however many occurrences it holds.
12
+ */
13
+ export declare function namesWriteVerb(text: string, verbs: RegExp): boolean;
@@ -0,0 +1,55 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.namesWriteVerb = namesWriteVerb;
4
+ // @implements A-SPEC-747.1
5
+ /** A shell word ends at white space or at one of `;|&()<>`. */
6
+ function isBreak(code) {
7
+ return code === 32 || code === 9 || code === 10 || code === 13 || code === 11 || code === 12
8
+ || code === 59 || code === 124 || code === 38 || code === 40 || code === 41 || code === 60 || code === 62;
9
+ }
10
+ /**
11
+ * Whether `text` names one of `verbs` as a shell word, rather than as letters inside another word.
12
+ *
13
+ * Measured 2026-10-04: `\bverb\b` matched `install` in `docs/install-guide.md` and `ln` in `grep -ln`, so read-only
14
+ * commands were refused as file writes. A verb occurrence still counts in every spelling a shell runs it under
15
+ * (`cp`, `/usr/bin/install`, `'cp'`, `cp.exe`, `--to-command=tee`, `rsync-ssl`); only two shapes do not:
16
+ * a. the word is a single-dash option cluster of letters and digits (`-ln`, `-rm1`);
17
+ * b. inside the word the verb is followed by `/`, or the word ends in a file extension other than `.exe`.
18
+ * Callers keep their own matching for what the verb targets — this answers only "is there such a verb at all", so a
19
+ * caller's verdict is removed only when the whole text holds no counting occurrence. One pass: a word's shape is read
20
+ * once however many occurrences it holds.
21
+ */
22
+ function namesWriteVerb(text, verbs) {
23
+ const re = new RegExp(verbs.source, verbs.flags.includes('g') ? verbs.flags : `${verbs.flags}g`);
24
+ let wordStart = -1;
25
+ let wordEnd = -1;
26
+ let cluster = false;
27
+ let extension = false;
28
+ for (let m = re.exec(text); m !== null; m = re.exec(text)) {
29
+ if (m[0].length === 0) {
30
+ re.lastIndex++;
31
+ continue;
32
+ }
33
+ const at = m.index;
34
+ if (at < wordStart || at >= wordEnd) {
35
+ let s = at;
36
+ while (s > 0 && !isBreak(text.charCodeAt(s - 1)))
37
+ s--;
38
+ let e = at;
39
+ while (e < text.length && !isBreak(text.charCodeAt(e)))
40
+ e++;
41
+ wordStart = s;
42
+ wordEnd = e;
43
+ const raw = text.slice(s, e);
44
+ cluster = /^-[A-Za-z0-9]+$/.test(raw);
45
+ const ext = /\.([A-Za-z0-9]{1,8})$/.exec(raw.replace(/["'\\]/g, ''));
46
+ extension = ext !== null && ext[1].toLowerCase() !== 'exe';
47
+ }
48
+ if (cluster || extension)
49
+ continue;
50
+ if (text.charCodeAt(at + m[0].length) === 47)
51
+ continue; // the verb is a directory name inside a path
52
+ return true;
53
+ }
54
+ return false;
55
+ }
@@ -93,6 +93,8 @@ export interface HookInput {
93
93
  malformed?: boolean;
94
94
  /** @implements A-SPEC-163.2 — the payload carries a patch whose targets cannot be read one way; denied whichever tool sent it. */
95
95
  patchUnreadable?: boolean;
96
+ /** @implements A-SPEC-163.7 — set only when the one cause is a marked shell command (A-SPEC-163.6 rule 3). */
97
+ patchUnreadableCause?: 'shell-marker';
96
98
  }
97
99
  /**
98
100
  * @implements A-SPEC-753.2 — what a denial leaves in the provenance ledger: the reason up to the operator command.
@@ -48,7 +48,7 @@ exports.gateErrorDecision = gateErrorDecision;
48
48
  exports.wiredSpecsDir = wiredSpecsDir;
49
49
  exports.evaluateHook = evaluateHook;
50
50
  exports.readSpecsSync = readSpecsSync;
51
- // @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753
51
+ // @implements A-SPEC-134.2, A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7
52
52
  const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
53
53
  // @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
54
54
  // evaluateHook in this file to prove it.
@@ -952,6 +952,9 @@ const PATCH_STRINGS_MAX = 256;
952
952
  /** A file an update hunk is applied to; a larger one is not judged by its result. */
953
953
  const PATCH_UPDATE_BYTES_MAX = 8 * 1024 * 1024;
954
954
  const PATCH_UNREADABLE_REASON = '[Holmes-Kit] cannot read the edit target path, so it cannot be judged (file_path missing or not a string)';
955
+ // @implements A-SPEC-163.7 — the refusal of A-SPEC-163.6 rule 3 in its own words (each refusal names its channel, A-SPEC-737).
956
+ const SHELL_MARKED_REASON = '[Holmes-Kit] this shell command mentions the patch tool or a patch marker and is not one plain read, so it is not judged — '
957
+ + 'search with the harness\'s own search tool, or run one plain grep, egrep, fgrep, rg, cat, head, tail, wc or ls with literal words (no pipe, redirect or substitution)';
955
958
  /**
956
959
  * @implements A-SPEC-753.2 — what a denial leaves in the provenance ledger: the reason up to the operator command.
957
960
  * The installer refusal (A-SPEC-753.1) carries the raw command after ` Operator: ` for the operator to run; the ledger
@@ -1026,6 +1029,9 @@ function normalizeHookInput(raw) {
1026
1029
  // A patch that cannot be read one way (no target, an empty path, too many, an indented header) is unreadable.
1027
1030
  const toolName = (str(r.tool_name) ?? '').toLowerCase();
1028
1031
  let patchUnreadable = false;
1032
+ // @implements A-SPEC-163.7 — why: a shell command refused for a patch marker is told so (it has no file path to miss).
1033
+ let shellMarked = false;
1034
+ let otherUnreadable = false;
1029
1035
  if (!write_target_1.READ_ONLY_TOOLS.includes(toolName)) {
1030
1036
  const strings = [];
1031
1037
  const collect = (v, depth) => {
@@ -1033,8 +1039,10 @@ function normalizeHookInput(raw) {
1033
1039
  if (!v.includes('*** '))
1034
1040
  return;
1035
1041
  // @implements A-SPEC-163.3 (rule 6) — more than the gate reads is unreadable, never unread.
1036
- if (strings.length >= PATCH_STRINGS_MAX)
1042
+ if (strings.length >= PATCH_STRINGS_MAX) {
1037
1043
  patchUnreadable = true;
1044
+ otherUnreadable = true;
1045
+ }
1038
1046
  else
1039
1047
  strings.push(v);
1040
1048
  return;
@@ -1055,21 +1063,25 @@ function normalizeHookInput(raw) {
1055
1063
  const patches = strings.filter((text) => !(isShell && text === cmd) && (isPatchTool ? (0, write_target_1.hasPatchEnvelope)(text) : (0, write_target_1.isWholePatch)(text)));
1056
1064
  if (isShell && cmd !== undefined) {
1057
1065
  const shellPatch = shellPatchOf(cmd);
1058
- if (shellPatch === 'unreadable')
1066
+ if (shellPatch === 'unreadable') {
1059
1067
  patchUnreadable = true;
1068
+ shellMarked = true;
1069
+ }
1060
1070
  else if (shellPatch !== null)
1061
1071
  patches.push(shellPatch.text);
1062
1072
  }
1063
1073
  if (patches.length > 0) {
1064
1074
  const targets = patches.flatMap((text) => (0, write_target_1.patchTargetsOf)(text));
1065
- if (targets.length === 0 || targets.length > write_target_1.PATCH_TARGETS_MAX || patches.some((text) => !(0, write_target_1.canonicalPatch)(text)))
1075
+ if (targets.length === 0 || targets.length > write_target_1.PATCH_TARGETS_MAX || patches.some((text) => !(0, write_target_1.canonicalPatch)(text))) {
1066
1076
  patchUnreadable = true;
1077
+ otherUnreadable = true;
1078
+ }
1067
1079
  else
1068
1080
  out.patch_targets = targets;
1069
1081
  }
1070
1082
  }
1071
1083
  return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(malformed ? { malformed: true } : {}),
1072
- ...(patchUnreadable ? { patchUnreadable: true } : {}) };
1084
+ ...(patchUnreadable ? { patchUnreadable: true } : {}), ...(shellMarked && !otherUnreadable ? { patchUnreadableCause: 'shell-marker' } : {}) };
1073
1085
  }
1074
1086
  /**
1075
1087
  * Which way to fail when the gate itself throws.
@@ -1220,8 +1232,10 @@ function evaluateHook(input, specsDir, opts) {
1220
1232
  // disk); a move's source is judged as a delete; a relative target is `<base>/<path>` as written, not folded first;
1221
1233
  // a patch that cannot be read or applied is denied. When no target is denied, a payload with a path field or a
1222
1234
  // shell command is then judged as before.
1223
- if (input.patchUnreadable)
1224
- return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1235
+ if (input.patchUnreadable) {
1236
+ return { permissionDecision: 'deny', permissionDecisionReason: input.patchUnreadableCause === 'shell-marker'
1237
+ ? SHELL_MARKED_REASON : PATCH_UNREADABLE_REASON };
1238
+ }
1225
1239
  const patchTargets = input.tool_input.patch_targets;
1226
1240
  if (patchTargets !== undefined && !input.malformed) {
1227
1241
  const isShell = (input.tool_name ?? '').toLowerCase() === 'bash';
@@ -2566,11 +2580,20 @@ function evaluateHook(input, specsDir, opts) {
2566
2580
  if (debt && debt.length > 0 && !cureOnly
2567
2581
  && (0, approval_grants_1.resolveApproval)(projectRoot, weApproval, { kind: 'code-write', target: relPath }, nowTs) === undefined) {
2568
2582
  const why = `code write under constitution debt (${debt.join(', ')})`;
2583
+ let hint = (0, approval_queue_1.queueHint)(projectRoot, { kind: 'code-write', target: relPath, why });
2584
+ // @implements A-SPEC-134.2 — a decision-kind request that is already pending is not written again, so the
2585
+ // hint is empty for it. The refusal still names that request; "could not persist" is for a queue that
2586
+ // really could not be written.
2587
+ if (!hint) {
2588
+ const id = (0, approval_queue_1.approvalRequestId)('code-write', relPath);
2589
+ if ((0, approval_queue_1.readQueue)(projectRoot).pending.some((request) => request.id === id)) {
2590
+ hint = (0, approval_queue_1.pendingRequestLine)(id);
2591
+ }
2592
+ }
2569
2593
  return {
2570
2594
  permissionDecision: 'deny',
2571
2595
  permissionDecisionReason: `[Holmes-Kit] constitution-debt outstanding (${debt.join(', ')}) — resolve the constitution (a clean turn clears it) before writing new code, or supply a covering approval`
2572
- + ((0, approval_queue_1.queueHint)(projectRoot, { kind: 'code-write', target: relPath, why })
2573
- || ' — could not persist the approval request; ask the operator to check the project approval queue storage'),
2596
+ + (hint || ' — could not persist the approval request; ask the operator to check the project approval queue storage'),
2574
2597
  };
2575
2598
  }
2576
2599
  }
@@ -7,7 +7,10 @@ export type ApprovalPolicyDecision = {
7
7
  kind: 'hold';
8
8
  reason: string;
9
9
  };
10
- /** The sole response transition table; timeout is never a synonym for cancel or deny. */
10
+ /**
11
+ * The sole response transition table; timeout is never a synonym for cancel or deny.
12
+ * A-SPEC-718.1: it is not a synonym for approve either — an unanswered prompt is held in every mode.
13
+ */
11
14
  export declare function resolveApprovalPresentation(result: ApprovalPresentationResult, options: {
12
15
  autonomous: boolean;
13
16
  harness: string;
@@ -1,14 +1,15 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.resolveApprovalPresentation = resolveApprovalPresentation;
4
- /** The sole response transition table; timeout is never a synonym for cancel or deny. */
4
+ /**
5
+ * The sole response transition table; timeout is never a synonym for cancel or deny.
6
+ * A-SPEC-718.1: it is not a synonym for approve either — an unanswered prompt is held in every mode.
7
+ */
5
8
  function resolveApprovalPresentation(result, options) {
6
9
  const harness = options.harness.trim() || 'unknown';
7
10
  switch (result.kind) {
8
11
  case 'approve': return { kind: 'approved', actor: `elicitation:${harness}`, ...(result.reason ? { reason: result.reason } : {}) };
9
- case 'timeout': return options.autonomous
10
- ? { kind: 'approved', actor: `autonomous-timeout:${harness}`, reason: 'in-session approval timeout' }
11
- : { kind: 'hold', reason: 'approval prompt timed out' };
12
+ case 'timeout': return { kind: 'hold', reason: 'approval prompt timed out' };
12
13
  case 'deny': return { kind: 'hold', reason: result.reason ? `denied: ${result.reason}` : 'denied' };
13
14
  case 'question': return { kind: 'hold', reason: `question: ${result.reason}` };
14
15
  case 'cancel': return { kind: 'hold', reason: 'cancelled' };
@@ -34,8 +34,6 @@ export interface ElicitApprovalRequest {
34
34
  target: string;
35
35
  /** Human-facing one-liner: what is being approved (id, title, sealed-or-not). */
36
36
  summary: string;
37
- /** Server-derived outcome wording; only explicit autonomy may select automatic approval. */
38
- timeoutBehavior?: 'queue' | 'autonomous-approve';
39
37
  }
40
38
  /** The human's decision. `null` from interpretElicitResult means "no answer in this shape". */
41
39
  export interface ElicitDecision {
@@ -9,7 +9,7 @@ exports.buildDecisionForm = buildDecisionForm;
9
9
  exports.buildReasonForm = buildReasonForm;
10
10
  exports.runElicitFlow = runElicitFlow;
11
11
  exports.interpretElicitResult = interpretElicitResult;
12
- // @implements A-SPEC-718, A-SPEC-263.1, A-SPEC-732
12
+ // @implements A-SPEC-718.2, A-SPEC-718, A-SPEC-263.1, A-SPEC-732
13
13
  const npx_bin_1 = require("../project/npx-bin");
14
14
  /**
15
15
  * The decision comes INTO the session (REQ-263): an approval-shaped refusal (spec_approve without a
@@ -108,9 +108,8 @@ const flat = (s, max) => s.replace(/[\u0000-\u001f\u007f\u0085\u2028\u2029\u200b
108
108
  */
109
109
  function buildDecisionForm(req, attempt, timeoutMs) {
110
110
  const redisplay = attempt > 1 ? `⚠ 재표시 ${attempt}/${exports.MAX_PRESENTATIONS} — 이전 다이얼로그는 만료되어 무효입니다\n` : '';
111
- const timeoutNotice = req.timeoutBehavior === 'autonomous-approve'
112
- ? `⏱ ${timeoutMs / 1000}초 내 미결정 시 이 요청만 자동 승인됩니다(autonomous mode).`
113
- : `⏱ ${timeoutMs / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve).`;
111
+ // @implements A-SPEC-718.2 — one outcome for silence, in every mode: the request returns to the queue.
112
+ const timeoutNotice = `⏱ ${timeoutMs / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve).`;
114
113
  return {
115
114
  // @implements A-SPEC-497.1 — the forewarning is the LAST line and template-owned: it survives a
116
115
  // cap-filling summary (appended after the caps) and tells the human, before the clock runs out,
@@ -11,9 +11,8 @@ export interface ReviewEvidenceContext {
11
11
  projectRootOf(root: string): string;
12
12
  basisFor(root: string | undefined, withDisk?: boolean): Basis;
13
13
  hasElicitor(): boolean;
14
- tryElicit(kind: string, target: string, summary: string, timeoutBehavior?: 'queue' | 'autonomous-approve'): Promise<ElicitOutcome>;
14
+ tryElicit(kind: string, target: string, summary: string): Promise<ElicitOutcome>;
15
15
  elicitApproval(reason?: string): Approval;
16
- autonomousApproval(derivedFrom?: string[], source?: 'immediate' | 'timeout'): Approval;
17
16
  resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
18
17
  kind: string;
19
18
  target: string;
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.summarizeReviewNeeded = summarizeReviewNeeded;
37
37
  exports.createReviewEvidenceHandlers = createReviewEvidenceHandlers;
38
- // @implements A-SPEC-718, A-SPEC-746, A-SPEC-617, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-133, A-SPEC-135, A-SPEC-141, A-SPEC-157, A-SPEC-160, A-SPEC-189, A-SPEC-191, A-SPEC-244, A-SPEC-245, A-SPEC-263.1, A-SPEC-497.1, A-SPEC-732
38
+ // @implements A-SPEC-718.1, A-SPEC-718.2, A-SPEC-718, A-SPEC-746, A-SPEC-617, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-133, A-SPEC-135, A-SPEC-141, A-SPEC-157, A-SPEC-160, A-SPEC-189, A-SPEC-191, A-SPEC-244, A-SPEC-245, A-SPEC-263.1, A-SPEC-497.1, A-SPEC-732
39
39
  const path = __importStar(require("node:path"));
40
40
  const findings_1 = require("../../review/findings");
41
41
  const review_targets_1 = require("../../review/review-targets");
@@ -45,7 +45,6 @@ const ledger_store_1 = require("../../governance/ledger-store");
45
45
  const ledger_lock_1 = require("../../governance/ledger-lock");
46
46
  const approval_grants_1 = require("../../governance/approval-grants");
47
47
  const provenance_chain_1 = require("../../governance/provenance-chain");
48
- const autonomy_1 = require("../../governance/autonomy");
49
48
  /**
50
49
  * @implements A-SPEC-746 — the review-needed backlog as an agent reads it: one row per spec (signals
51
50
  * merged, files unioned), newest first, without the from/to digests — 64-hex identifiers were most of
@@ -132,6 +131,7 @@ function createReviewEvidenceHandlers(context) {
132
131
  // not covered by env/grant, ask now and carry the grant into the lock as data. TOCTOU folds
133
132
  // fail-closed — state moved so the lift is no longer needed → the grant is simply unused;
134
133
  // state moved so a lift IS needed that the snapshot missed → no grant → the standard refusal.
134
+ // @implements A-SPEC-718.1 — only a person's answer is a grant here; this handler holds no autonomous channel.
135
135
  const elicitGrants = new Map();
136
136
  // A DENY at pre-scan is carried as data too (round-1): throwing here judged a stale snapshot —
137
137
  // a finding concurrently resolved by someone else no longer needs a lift inside the lock, and
@@ -144,13 +144,6 @@ function createReviewEvidenceHandlers(context) {
144
144
  const elicitExpiries = new Map();
145
145
  if (context.hasElicitor()) {
146
146
  try {
147
- // @implements A-SPEC-732 (round 2) — autonomy is read at the project root, never a raw root.
148
- const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, (() => { try {
149
- return context.projectRootOf(a.root);
150
- }
151
- catch {
152
- return undefined;
153
- } })(), new Date().toISOString());
154
147
  const snapshot = new Map();
155
148
  for (const f of new findings_1.FindingsLedger(findingsFile).list())
156
149
  snapshot.set(f.id, f);
@@ -168,13 +161,12 @@ function createReviewEvidenceHandlers(context) {
168
161
  }
169
162
  if (context.resolveHandlerApproval(a.root, env0, { kind: 'review-resolve', target: f.id }, new Date().toISOString()) !== undefined)
170
163
  continue; // an open door never summons a human
171
- const out = await context.tryElicit('review-resolve', f.id, `열린 치명 발견 ${f.id} 의 해소 기록`, autonomyOn ? 'autonomous-approve' : 'queue');
164
+ const out = await context.tryElicit('review-resolve', f.id, `열린 치명 발견 ${f.id} 의 해소 기록`);
172
165
  if (out.kind === 'answered' && out.decision.granted)
173
166
  elicitGrants.set(f.id, { approval: context.elicitApproval(out.decision.reason), source: 'elicitation' });
174
167
  else if (out.kind === 'answered')
175
168
  elicitDenials.set(f.id, out.decision.reason ?? '(사유 없음)');
176
- else if (out.kind === 'expired' && autonomyOn)
177
- elicitGrants.set(f.id, { approval: context.autonomousApproval(undefined, 'timeout'), source: 'autonomous' });
169
+ // @implements A-SPEC-718.1 — an expired dialog grants nothing in any mode.
178
170
  else if (out.kind === 'expired')
179
171
  elicitExpiries.set(f.id, out.waitedMs);
180
172
  }
@@ -10,9 +10,9 @@ export interface SpecApprovalContext {
10
10
  resolver(specs: Spec[]): (id: string) => Spec | null;
11
11
  projectRootOf(root: string): string;
12
12
  cachedScan(root: string, repoRoot?: string): ScannedFile[];
13
- tryElicit(kind: string, target: string, summary: string, timeoutBehavior?: 'queue' | 'autonomous-approve'): Promise<ElicitOutcome>;
13
+ tryElicit(kind: string, target: string, summary: string): Promise<ElicitOutcome>;
14
14
  elicitApproval(reason?: string): Approval;
15
- autonomousApproval(derivedFrom?: string[], source?: 'immediate' | 'timeout'): Approval;
15
+ autonomousApproval(derivedFrom?: string[]): Approval;
16
16
  approvalAdapter(): ApprovalAdapter;
17
17
  approvalHarness(): string;
18
18
  prepareHostApproval(input: {