@holmes-lab/holmes-kit 0.35.25 → 0.36.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 (125) hide show
  1. package/CHANGELOG.md +298 -0
  2. package/README.md +3 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +31 -1
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +25 -1
  13. package/dist/holmes/cli/doctor.js +153 -7
  14. package/dist/holmes/cli/index.js +99 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  27. package/dist/holmes/cli/runtime-binding.js +96 -7
  28. package/dist/holmes/cli/test-platform.d.ts +16 -0
  29. package/dist/holmes/cli/test-platform.js +31 -1
  30. package/dist/holmes/config/config.d.ts +49 -0
  31. package/dist/holmes/config/config.js +146 -3
  32. package/dist/holmes/config/project-caps.d.ts +21 -0
  33. package/dist/holmes/config/project-caps.js +114 -0
  34. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  35. package/dist/holmes/governance/approval-queue.js +48 -6
  36. package/dist/holmes/governance/autonomy.d.ts +6 -0
  37. package/dist/holmes/governance/autonomy.js +21 -0
  38. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  39. package/dist/holmes/governance/push-gate-runner.js +49 -1
  40. package/dist/holmes/governance/replica-id.d.ts +9 -0
  41. package/dist/holmes/governance/replica-id.js +44 -7
  42. package/dist/holmes/governance/role-policy.d.ts +41 -1
  43. package/dist/holmes/governance/role-policy.js +137 -20
  44. package/dist/holmes/governance/run-mode.d.ts +14 -0
  45. package/dist/holmes/governance/run-mode.js +120 -0
  46. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  47. package/dist/holmes/governance/tool-actions.js +121 -0
  48. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  49. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  50. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  51. package/dist/holmes/guardrail/classification-mode.js +135 -0
  52. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  53. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  54. package/dist/holmes/guardrail/phase.d.ts +2 -1
  55. package/dist/holmes/guardrail/phase.js +22 -8
  56. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  57. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  58. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  59. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  60. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  61. package/dist/holmes/guardrail/risk-classifier.js +242 -26
  62. package/dist/holmes/guardrail/risk-types.d.ts +15 -0
  63. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  64. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  65. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  66. package/dist/holmes/guardrail/run-refusals.js +348 -0
  67. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  68. package/dist/holmes/guardrail/run-stages.js +188 -0
  69. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  70. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  71. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  72. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  73. package/dist/holmes/guardrail/shell-words.js +7 -7
  74. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  75. package/dist/holmes/guardrail/write-target.js +118 -16
  76. package/dist/holmes/hooks/pre-tool-use.d.ts +35 -1
  77. package/dist/holmes/hooks/pre-tool-use.js +702 -81
  78. package/dist/holmes/hooks/session-start.js +5 -3
  79. package/dist/holmes/hooks/stop.d.ts +32 -0
  80. package/dist/holmes/hooks/stop.js +129 -4
  81. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  82. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  83. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  84. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  85. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  86. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  87. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  88. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  89. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  90. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  91. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  92. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  93. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  94. package/dist/holmes/mcp/handlers.d.ts +2 -3
  95. package/dist/holmes/mcp/handlers.js +22 -2
  96. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  97. package/dist/holmes/mcp/harness-attestation.js +3 -1
  98. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  99. package/dist/holmes/mcp/operator-recovery.js +4 -3
  100. package/dist/holmes/mcp/server.js +9 -0
  101. package/dist/holmes/mcp/tool-schemas.js +6 -3
  102. package/dist/holmes/project/root.js +6 -1
  103. package/dist/holmes/project/run-records.d.ts +17 -0
  104. package/dist/holmes/project/run-records.js +126 -0
  105. package/dist/holmes/review/mrp.d.ts +35 -0
  106. package/dist/holmes/review/mrp.js +119 -0
  107. package/dist/holmes/review/verdicts.d.ts +117 -0
  108. package/dist/holmes/review/verdicts.js +345 -0
  109. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  110. package/dist/holmes/semantic/cloud-usage.js +106 -0
  111. package/dist/holmes/semantic/embedder.d.ts +15 -6
  112. package/dist/holmes/semantic/embedder.js +84 -3
  113. package/dist/holmes/semantic/local-model.d.ts +21 -2
  114. package/dist/holmes/semantic/local-model.js +14 -3
  115. package/dist/holmes/semantic/tier.d.ts +25 -0
  116. package/dist/holmes/semantic/tier.js +86 -1
  117. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  118. package/dist/holmes/semantic/vector-cache.js +4 -1
  119. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  120. package/dist/holmes/spec/approval-blockers.js +70 -2
  121. package/dist/holmes/spec/renumber.d.ts +1 -1
  122. package/dist/holmes/spec/renumber.js +5 -2
  123. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  124. package/dist/holmes/spec/transition-policy.js +17 -2
  125. package/package.json +1 -1
@@ -33,10 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.LEGACY_UNCHECKED = void 0;
36
37
  exports.loadRolePolicy = loadRolePolicy;
38
+ exports.parseRolePolicyText = parseRolePolicyText;
39
+ exports.migrateRolePolicyText = migrateRolePolicyText;
37
40
  exports.rolePolicyStatus = rolePolicyStatus;
41
+ exports.defaultBreadthIssue = defaultBreadthIssue;
38
42
  exports.roleCheck = roleCheck;
39
- // @implements A-SPEC-152
43
+ // @implements A-SPEC-152, A-SPEC-774.19, A-SPEC-774.22
40
44
  const fs = __importStar(require("node:fs"));
41
45
  const path = __importStar(require("node:path"));
42
46
  const yaml = __importStar(require("js-yaml"));
@@ -46,30 +50,33 @@ function loadRolePolicy(root) {
46
50
  const dir = path.join(root, ROLES_DIR);
47
51
  let files;
48
52
  try {
49
- files = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml')).sort();
53
+ // @implements A-SPEC-774.15 — a `.json` policy is read (the YAML parser reads JSON), never silently ignored.
54
+ files = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml') || f.endsWith('.json')).sort();
50
55
  }
51
- catch {
52
- return null; // no directory: not opted in
56
+ catch (e) {
57
+ // @implements A-SPEC-774.15 — only a missing directory means "not opted in". Any other error (a file in its place,
58
+ // no permission) used to switch roles off; it now grants nothing, the direction REQ-144 set.
59
+ if (e.code === 'ENOENT')
60
+ return null;
61
+ return { roles: {}, loadIssue: `the role policy directory .ax/roles could not be read (${e.code ?? 'error'})` };
53
62
  }
54
63
  if (files.length === 0)
55
64
  return null; // empty directory: not opted in either
56
- const roles = {};
57
- let dflt;
65
+ const acc = { roles: {} };
66
+ const seen = new Set();
67
+ const dup = new Set();
58
68
  for (const f of files) {
59
69
  try {
60
70
  const doc = yaml.load(fs.readFileSync(path.join(dir, f), 'utf8'));
61
- // FIRST declaration wins, by filename order. If the last one won, dropping in a new file would
62
- // silently reverse a decision another file already made — and nothing would report the change.
63
- if (dflt === undefined && typeof doc?.default === 'string' && doc.default.trim() !== '') {
64
- dflt = doc.default.trim();
65
- }
66
- const declared = doc && typeof doc === 'object' ? doc.roles : undefined;
67
- if (!declared || typeof declared !== 'object')
68
- continue;
69
- for (const [name, def] of Object.entries(declared)) {
70
- const allow = def?.allow;
71
- roles[name] = { allow: Array.isArray(allow) ? allow.filter((a) => typeof a === 'string') : [] };
71
+ // @implements A-SPEC-774.15 — a role declared again in another file is recorded; the later still loads, as before.
72
+ if (doc && typeof doc === 'object' && doc.roles && typeof doc.roles === 'object') {
73
+ for (const name of Object.keys(doc.roles)) {
74
+ if (seen.has(name))
75
+ dup.add(name);
76
+ seen.add(name);
77
+ }
72
78
  }
79
+ mergePolicyDoc(acc, doc);
73
80
  }
74
81
  catch {
75
82
  // A corrupt file contributes NO roles — deliberately not `null`. Returning "no policy" would
@@ -78,7 +85,67 @@ function loadRolePolicy(root) {
78
85
  continue;
79
86
  }
80
87
  }
81
- return dflt === undefined ? { roles } : { roles, default: dflt };
88
+ if (dup.size > 0)
89
+ acc.duplicates = [...dup].sort();
90
+ return acc;
91
+ }
92
+ /** One policy document folded into the accumulated policy (shared by the loader and `parseRolePolicyText`). */
93
+ function mergePolicyDoc(acc, raw) {
94
+ const doc = raw;
95
+ // FIRST declaration wins, by filename order. If the last one won, dropping in a new file would
96
+ // silently reverse a decision another file already made — and nothing would report the change.
97
+ if (acc.default === undefined && typeof doc?.default === 'string' && doc.default.trim() !== '') {
98
+ acc.default = doc.default.trim();
99
+ }
100
+ // @implements A-SPEC-774.10 — any file declaring the new vocabulary opts the whole policy into strict reading.
101
+ if (doc && typeof doc === 'object' && doc.vocabulary === 2)
102
+ acc.vocabulary = 2;
103
+ const declared = doc && typeof doc === 'object' ? doc.roles : undefined;
104
+ if (!declared || typeof declared !== 'object')
105
+ return;
106
+ for (const [name, def] of Object.entries(declared)) {
107
+ const allow = def?.allow;
108
+ // @implements A-SPEC-774.19 — `stages` is kept only as a list of strings; anything else declares no stages.
109
+ const stages = def?.stages;
110
+ const readable = Array.isArray(stages) && stages.every((s) => typeof s === 'string');
111
+ acc.roles[name] = {
112
+ allow: Array.isArray(allow) ? allow.filter((a) => typeof a === 'string') : [],
113
+ ...(readable ? { stages: stages } : {}),
114
+ // @implements A-SPEC-774.22 — present but unreadable is kept as a flag, not dropped: a run refuses it.
115
+ ...(!readable && stages !== undefined ? { stagesMalformed: true } : {}),
116
+ };
117
+ }
118
+ }
119
+ /** A policy from one document's text, as the loader would read it. */
120
+ function parseRolePolicyText(text) {
121
+ const acc = { roles: {} };
122
+ mergePolicyDoc(acc, yaml.load(text));
123
+ return acc;
124
+ }
125
+ /**
126
+ * @implements A-SPEC-774.10 — the actions REQ-774 added that 0.35.25 never role-checked. A policy written for
127
+ * 0.35.25 names none of them; outside a run it keeps allowing them, so no person has to migrate by hand. `AUTHOR_*`,
128
+ * `WRITE_CODE` and `WRITE_TEST` are not here: they kept their meaning, and their checks are the Fixed set (C1, C2).
129
+ */
130
+ exports.LEGACY_UNCHECKED = new Set(['WRITE_OTHER', 'APPROVE_SPEC', 'RECORD_REVIEW', 'RECORD_EVIDENCE', 'MAINTAIN_GOVERNANCE']);
131
+ /**
132
+ * @implements A-SPEC-774.10 §4 — the same policy written in the new vocabulary: `vocabulary: 2`, and every role
133
+ * granted the actions the legacy reading allowed implicitly, so verdicts outside a run are unchanged.
134
+ */
135
+ function migrateRolePolicyText(text) {
136
+ const doc = (yaml.load(text) ?? {});
137
+ if (doc.vocabulary === 2)
138
+ return text;
139
+ const roles = doc.roles && typeof doc.roles === 'object' ? doc.roles : {};
140
+ const migratedRoles = {};
141
+ for (const [name, def] of Object.entries(roles)) {
142
+ const allow = Array.isArray(def?.allow) ? def.allow.filter((a) => typeof a === 'string') : [];
143
+ migratedRoles[name] = { ...(def ?? {}), allow: [...allow, ...[...exports.LEGACY_UNCHECKED].filter((a) => !allow.includes(a))] };
144
+ }
145
+ const { vocabulary: _v, roles: _r, ...rest } = doc;
146
+ void _v;
147
+ void _r;
148
+ return yaml.dump({ vocabulary: 2, ...rest, roles: migratedRoles });
82
149
  }
83
150
  /**
84
151
  * Describes the project's role configuration WITHOUT judging it. Not having roles on is not a
@@ -91,7 +158,12 @@ function rolePolicyStatus(root) {
91
158
  const policy = loadRolePolicy(root);
92
159
  if (policy === null)
93
160
  return { state: 'inactive', roles: [] };
94
- return { state: 'active', roles: Object.keys(policy.roles).sort(), default: policy.default };
161
+ const defaultIssue = defaultBreadthIssue(policy);
162
+ // @implements A-SPEC-774.22 — the roles whose stages cannot be read, for doctor.
163
+ const malformedStages = Object.entries(policy.roles).filter(([, d]) => d.stagesMalformed).map(([n]) => n).sort();
164
+ return { state: 'active', roles: Object.keys(policy.roles).sort(), default: policy.default, ...(defaultIssue ? { defaultIssue } : {}),
165
+ ...(policy.loadIssue ? { loadIssue: policy.loadIssue } : {}), ...(policy.duplicates ? { duplicates: policy.duplicates } : {}),
166
+ ...(malformedStages.length > 0 ? { malformedStages } : {}) };
95
167
  }
96
168
  /**
97
169
  * Whether this identity may perform this action. Returns the refusal reason, or `null` to allow.
@@ -99,9 +171,40 @@ function rolePolicyStatus(root) {
99
171
  * Fail-closed once a policy exists: an absent role, an unregistered role, and a role without the
100
172
  * action are all refusals. Before a policy exists there is no opinion at all.
101
173
  */
102
- function roleCheck(action, identity, policy) {
174
+ /**
175
+ * @implements A-SPEC-774.8 — a session reaches the default by LOSING its role (unset, or a harness that does not pass it
176
+ * to the MCP server). A default broader than what every role allows turns that loss into an escalation. Null when the
177
+ * default is a subset of the intersection of every role's allow list (an empty intersection makes `allow: []` valid).
178
+ */
179
+ function defaultBreadthIssue(policy) {
180
+ if (policy.default === undefined)
181
+ return null;
182
+ const dflt = policy.roles[policy.default];
183
+ if (!dflt)
184
+ return null; // an undefined default is refused by roleCheck already
185
+ const all = Object.values(policy.roles).map((r) => new Set(r.allow));
186
+ const extra = dflt.allow.filter((a) => !all.every((s) => s.has(a)));
187
+ if (extra.length === 0)
188
+ return null;
189
+ return `the default role "${policy.default}" allows ${extra.join(', ')}, which not every role allows — a session that loses `
190
+ + 'its role would gain them. Make the default a role that allows only what every role allows, for example '
191
+ + '`readonly: { allow: [] }` with `default: readonly` (A-SPEC-774.8)';
192
+ }
193
+ function roleCheck(action, identity, policy, opts) {
103
194
  if (policy === null)
104
195
  return null;
196
+ // @implements A-SPEC-774.15 — a policy that could not be read grants nothing, in every mode.
197
+ if (policy.loadIssue)
198
+ return `[Holmes-Kit] ${policy.loadIssue} — ${action} cannot be allowed until the policy can be read`;
199
+ // @implements A-SPEC-774.8 — in a run a broad default invalidates the policy: it grants nothing.
200
+ if (opts?.run) {
201
+ const breadth = defaultBreadthIssue(policy);
202
+ if (breadth)
203
+ return `[Holmes-Kit] this role policy is refused in a run: ${breadth}`;
204
+ }
205
+ // @implements A-SPEC-774.10 — a legacy policy, outside a run, keeps allowing what 0.35.25 never checked.
206
+ if (!opts?.run && policy.vocabulary !== 2 && exports.LEGACY_UNCHECKED.has(action))
207
+ return null;
105
208
  const known = Object.keys(policy.roles);
106
209
  // The default is resolved HERE, not in the identity provider. Identity is observed fact — what the
107
210
  // operator actually claimed — while a default is the policy's interpretation of silence. Folding
@@ -124,11 +227,25 @@ function roleCheck(action, identity, policy) {
124
227
  }
125
228
  // Exact match on purpose: a silent case-fold would make `Developer` and `developer` the same
126
229
  // principal by accident, which is not a decision a policy file ever expressed.
230
+ // @implements A-SPEC-774.15 — in a run, a role defined in more than one file grants nothing: which definition holds
231
+ // is a decision no file expressed. Interactively the later definition still decides (0.35.25).
232
+ if (opts?.run && policy.duplicates?.includes(effective)) {
233
+ return `[Holmes-Kit] role "${effective}" is defined in more than one file under .ax/roles — ${action} cannot be allowed in a run until it is defined once`;
234
+ }
127
235
  const def = policy.roles[effective];
128
236
  if (!def) {
129
237
  return `[Holmes-Kit] 역할 "${effective}"이(가) 역할 정책에 없습니다 — ${action}을(를) 허용할 수 없습니다.`
130
238
  + ` 등록된 역할: ${known.join(', ') || '(없음)'}`;
131
239
  }
240
+ // @implements A-SPEC-774.22 — in a run, a stages declaration that cannot be read limits the role to no stage at all.
241
+ if (opts?.run && def.stagesMalformed) {
242
+ return `[Holmes-Kit] role ${effective} may not act in stage ${opts.stage ?? 'any'} of a run: its stages declaration cannot be read`
243
+ + ' (a list of stage names is expected)';
244
+ }
245
+ // @implements A-SPEC-774.19 — action, role and stage together: a role that declares stages acts only in them.
246
+ if (opts?.stage !== undefined && def.stages !== undefined && !def.stages.includes(opts.stage)) {
247
+ return `[Holmes-Kit] role ${effective} may not act in stage ${opts.stage} (its stages: ${def.stages.join(', ') || 'none'})`;
248
+ }
132
249
  if (!def.allow.includes(action)) {
133
250
  return `[Holmes-Kit] 역할 "${effective}"은(는) ${action}을(를) 수행할 수 없습니다.`
134
251
  + ` 허용된 동작: ${def.allow.join(', ') || '(없음)'}`;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Whether this SESSION is an orchestrated run. Owner principle (2026-10-18): new controls bind runs; a person working
3
+ * interactively keeps what 0.35.25 allowed. Until the G2.4 run token exists, a run is known by either of two marks the
4
+ * session cannot remove:
5
+ * - `HOLMES_RUN_ID` in the environment the orchestrator launched the harness with (an authority name, A-SPEC-774.2);
6
+ * - a run record under `.ax/state/runs/` (a protected path) binding the session's cwd or its harness session id.
7
+ * Judged by the session, never by the target a command names: `cd <other repo> && …` stays in the run.
8
+ * A runs directory that cannot be read, or a record of the wrong shape, answers "run" — the stricter side.
9
+ */
10
+ export declare function runMode(env: NodeJS.ProcessEnv, projectRoot: string, cwd?: string, sessionId?: string): {
11
+ run: boolean;
12
+ why: string;
13
+ id?: string;
14
+ };
@@ -0,0 +1,120 @@
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.runMode = runMode;
37
+ // @implements A-SPEC-774.9
38
+ const fs = __importStar(require("node:fs"));
39
+ const path = __importStar(require("node:path"));
40
+ /**
41
+ * Whether this SESSION is an orchestrated run. Owner principle (2026-10-18): new controls bind runs; a person working
42
+ * interactively keeps what 0.35.25 allowed. Until the G2.4 run token exists, a run is known by either of two marks the
43
+ * session cannot remove:
44
+ * - `HOLMES_RUN_ID` in the environment the orchestrator launched the harness with (an authority name, A-SPEC-774.2);
45
+ * - a run record under `.ax/state/runs/` (a protected path) binding the session's cwd or its harness session id.
46
+ * Judged by the session, never by the target a command names: `cd <other repo> && …` stays in the run.
47
+ * A runs directory that cannot be read, or a record of the wrong shape, answers "run" — the stricter side.
48
+ */
49
+ // @implements A-SPEC-778 — `id` names the run that binds the session (the marker's value or the record's run_id), so
50
+ // the run's refusal log can be found; a run known only by an unreadable store has no id.
51
+ function runMode(env, projectRoot, cwd, sessionId) {
52
+ const marker = env.HOLMES_RUN_ID;
53
+ if (typeof marker === 'string' && marker.trim() !== '')
54
+ return { run: true, why: 'HOLMES_RUN_ID is set', id: marker.trim() };
55
+ // @implements A-SPEC-774.11 §1 — a `git worktree add` worktree checks out its own spec store, so it IS the project
56
+ // root, while the run record lives in the main checkout's gitignored state (supervisor probe7749). Both are read.
57
+ const roots = [projectRoot];
58
+ const pointer = path.join(projectRoot, '.git');
59
+ try {
60
+ if (fs.existsSync(pointer) && fs.lstatSync(pointer).isFile()) {
61
+ const m = /^gitdir:\s*(.+?)\s*$/m.exec(fs.readFileSync(pointer, 'utf8'));
62
+ if (!m)
63
+ return { run: true, why: 'worktree pointer unreadable — treated as a run' };
64
+ const gitdir = path.resolve(projectRoot, m[1]);
65
+ const commondir = path.join(gitdir, 'commondir');
66
+ if (fs.existsSync(commondir)) {
67
+ const common = path.resolve(gitdir, fs.readFileSync(commondir, 'utf8').trim());
68
+ if (path.basename(common) === '.git')
69
+ roots.push(path.dirname(common));
70
+ }
71
+ }
72
+ }
73
+ catch {
74
+ return { run: true, why: 'worktree pointer unreadable — treated as a run' };
75
+ }
76
+ const real = (p) => { try {
77
+ return fs.realpathSync(p);
78
+ }
79
+ catch {
80
+ return path.resolve(p);
81
+ } };
82
+ const here = cwd ? real(cwd) : undefined;
83
+ for (const root of roots) {
84
+ const found = recordsIn(path.join(root, '.ax', 'state', 'runs'), here, sessionId, real);
85
+ if (found)
86
+ return found;
87
+ }
88
+ return { run: false, why: 'no run marker or record binds this session' };
89
+ }
90
+ function recordsIn(dir, here, sessionId, real) {
91
+ let names;
92
+ try {
93
+ names = fs.readdirSync(dir);
94
+ }
95
+ catch (e) {
96
+ if (e.code === 'ENOENT')
97
+ return null;
98
+ return { run: true, why: `run records unreadable (${e.code ?? 'error'}) — treated as a run` };
99
+ }
100
+ for (const n of names.filter((f) => f.endsWith('.json'))) {
101
+ let rec;
102
+ try {
103
+ rec = JSON.parse(fs.readFileSync(path.join(dir, n), 'utf8'));
104
+ }
105
+ catch {
106
+ return { run: true, why: `run record ${n} unreadable — treated as a run` };
107
+ }
108
+ const r = rec;
109
+ if (!r || typeof r !== 'object' || typeof r.run_id !== 'string' || typeof r.worktree !== 'string'
110
+ || (r.sessions !== undefined && !(Array.isArray(r.sessions) && r.sessions.every((s) => typeof s === 'string')))) {
111
+ return { run: true, why: `run record ${n} malformed — treated as a run` };
112
+ }
113
+ const wt = real(r.worktree);
114
+ if (here && (here === wt || here.startsWith(wt + path.sep)))
115
+ return { run: true, why: `cwd is run ${r.run_id}'s worktree`, id: r.run_id };
116
+ if (sessionId && Array.isArray(r.sessions) && r.sessions.includes(sessionId))
117
+ return { run: true, why: `session bound to run ${r.run_id}`, id: r.run_id };
118
+ }
119
+ return null;
120
+ }
@@ -0,0 +1,30 @@
1
+ import { Identity } from './identity';
2
+ /**
3
+ * What each holmes-kit MCP tool DOES, in the role policy's vocabulary.
4
+ *
5
+ * Measured 2026-10-17 (C2): a reviewer allowed only WRITE_TEST called `spec_create` and `spec_remediate` and both ran
6
+ * — a tool call carries no path field, so the hook let it through at once, and the server never asked the role.
7
+ * The server is the one point Claude Code, Codex and Antigravity share, so the question is asked there.
8
+ *
9
+ * The entries come from what each handler WRITES (census of 2026-10-17), not from the tool's name: a name says what
10
+ * a tool is for, and `approval_status` — a status query by name — appends reaction rows. Where a write waits on an
11
+ * argument (`persist`, `dryRun:false`, `operation`), the action is named only when that argument asks for it, so a
12
+ * read-only call stays free for a role that may not record. Telemetry rows a query appends about itself
13
+ * (`approval_status`, `rtm_dashboard` advisory outcomes) and derived caches (`.ax/cpg_cache`, `rtm.sqlite`) are not
14
+ * governed state and are not acts.
15
+ */
16
+ export type ToolActions = (args: Record<string, unknown>) => string[];
17
+ /**
18
+ * @implements A-SPEC-774.6 — every action a role policy can name, shared by the four decision points (the hook's
19
+ * Write/Edit check, the spec-store branch, the unclassified write and this table). A census test holds them to it.
20
+ */
21
+ export declare const ROLE_ACTIONS: readonly ["AUTHOR_REQ", "AUTHOR_HSPEC", "AUTHOR_ASPEC", "AUTHOR_CSPEC", "AUTHOR_TSPEC", "WRITE_CODE", "WRITE_TEST", "WRITE_OTHER", "APPROVE_SPEC", "RECORD_REVIEW", "RECORD_EVIDENCE", "MAINTAIN_GOVERNANCE"];
22
+ export declare const TOOL_ACTIONS: Record<string, ToolActions>;
23
+ /** The actions a call performs: `[]` for a read, `null` for a tool the table does not know. */
24
+ export declare function actionsForTool(name: string, args: unknown): string[] | null;
25
+ /**
26
+ * The role refusal for this call, or null. The policy is the one of the project the call acts on (`args.root`, else
27
+ * `root`), resolved the way the handlers resolve it. With no policy there is no opinion (A-SPEC-152); with one, a tool
28
+ * the table does not know is refused, so a new tool cannot ship ungated.
29
+ */
30
+ export declare function toolRoleRefusal(name: string, args: unknown, root: string, identity: Identity): string | null;
@@ -0,0 +1,121 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.TOOL_ACTIONS = exports.ROLE_ACTIONS = void 0;
4
+ exports.actionsForTool = actionsForTool;
5
+ exports.toolRoleRefusal = toolRoleRefusal;
6
+ // @implements A-SPEC-774
7
+ const root_1 = require("../project/root");
8
+ const role_policy_1 = require("./role-policy");
9
+ const run_mode_1 = require("./run-mode");
10
+ /**
11
+ * @implements A-SPEC-774.6 — every action a role policy can name, shared by the four decision points (the hook's
12
+ * Write/Edit check, the spec-store branch, the unclassified write and this table). A census test holds them to it.
13
+ */
14
+ exports.ROLE_ACTIONS = [
15
+ 'AUTHOR_REQ', 'AUTHOR_HSPEC', 'AUTHOR_ASPEC', 'AUTHOR_CSPEC', 'AUTHOR_TSPEC',
16
+ 'WRITE_CODE', 'WRITE_TEST', 'WRITE_OTHER',
17
+ 'APPROVE_SPEC', 'RECORD_REVIEW', 'RECORD_EVIDENCE', 'MAINTAIN_GOVERNANCE',
18
+ ];
19
+ const NONE = () => [];
20
+ const always = (...actions) => () => actions;
21
+ const when = (pred, ...actions) => (a) => (pred(a) ? actions : []);
22
+ const applied = (a) => a.dryRun === false;
23
+ const persisted = (a) => a.persist === true;
24
+ /** The handlers write only on these explicit operations; any other value, or none, is a read there. */
25
+ const opIn = (...writeOps) => (a) => typeof a.operation === 'string' && writeOps.includes(a.operation);
26
+ const AUTHOR_BY_TYPE = {
27
+ REQ: 'AUTHOR_REQ', 'H-SPEC': 'AUTHOR_HSPEC', 'A-SPEC': 'AUTHOR_ASPEC', 'C-SPEC': 'AUTHOR_CSPEC', 'T-SPEC': 'AUTHOR_TSPEC',
28
+ };
29
+ /** An unknown kind is authored as a REQ — the broadest authoring act, so a new kind can never be the weaker gate. */
30
+ const authorOf = (type) => (typeof type === 'string' && AUTHOR_BY_TYPE[type]) || 'AUTHOR_REQ';
31
+ /** A legacy upgrade or a citation edit names one spec by id; its prefix is its kind. */
32
+ const authorOfId = (id) => {
33
+ const m = typeof id === 'string' ? /^(REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC)-/.exec(id) : null;
34
+ return authorOf(m?.[1]);
35
+ };
36
+ exports.TOOL_ACTIONS = {
37
+ // reads (a scan cache or derived graph is not governed state)
38
+ workspace_preflight: NONE, basis_detail: NONE, spec_validate: NONE, spec_list: NONE, spec_next: NONE,
39
+ ledger_timeline: NONE, rtm_check: NONE, phase_status: NONE, phase_check: NONE, cpg_scan: NONE, taint_scan: NONE,
40
+ issue_localize: NONE, maintenance_calibration: NONE, impact_gate_check: NONE, rtm_impact: NONE, rtm_reindex: NONE,
41
+ context_bundle: NONE, review_scope: NONE, review_prepare: NONE, review_status: NONE, reverse_scan: NONE,
42
+ approval_status: NONE, rtm_dashboard: NONE,
43
+ // approval_commit changes only the server's in-memory continuation; the act it completes is spec_approve's
44
+ approval_commit: always('APPROVE_SPEC'),
45
+ // evidence
46
+ test_run: always('RECORD_EVIDENCE'),
47
+ maintenance_analyze: when(persisted, 'RECORD_EVIDENCE'),
48
+ requirement_triage: when(persisted, 'RECORD_EVIDENCE'),
49
+ maintenance_outcome: always('RECORD_EVIDENCE'),
50
+ risk_check: always('RECORD_EVIDENCE'),
51
+ // authoring
52
+ spec_create: (a) => [authorOf(a.type)],
53
+ spec_slice_init: always('AUTHOR_REQ', 'AUTHOR_HSPEC', 'AUTHOR_ASPEC', 'AUTHOR_TSPEC'),
54
+ spec_upgrade: (a) => [authorOfId(a.id)],
55
+ citation_pin: (a) => (applied(a) ? [authorOfId(a.id)] : []),
56
+ reverse_draft: when(applied, 'AUTHOR_HSPEC', 'AUTHOR_ASPEC', 'AUTHOR_TSPEC'),
57
+ // seals, unseals and grants
58
+ spec_approve: always('APPROVE_SPEC'),
59
+ spec_slice_approve: always('APPROVE_SPEC'),
60
+ spec_unseal: always('APPROVE_SPEC'),
61
+ spec_retire: always('APPROVE_SPEC'),
62
+ // code
63
+ reverse_anchor: when(applied, 'WRITE_CODE'),
64
+ spec_remediate: always('WRITE_CODE', 'APPROVE_SPEC'),
65
+ // review
66
+ review_record: always('RECORD_REVIEW'),
67
+ // bulk rewrites of specs, ledgers, identity or harness wiring
68
+ spec_renumber: when(applied, 'MAINTAIN_GOVERNANCE'),
69
+ spec_reconcile: when(opIn('apply'), 'MAINTAIN_GOVERNANCE'),
70
+ ledger_reconcile: always('MAINTAIN_GOVERNANCE'),
71
+ entity_integrate: when(opIn('apply', 'recover', 'abandon', 'discharge'), 'MAINTAIN_GOVERNANCE'),
72
+ entity_renumber: when(opIn('apply', 'recover', 'abandon'), 'MAINTAIN_GOVERNANCE'),
73
+ entity_store: when(opIn('adopt', 'recover'), 'MAINTAIN_GOVERNANCE'),
74
+ runtime_binding: when(opIn('apply'), 'MAINTAIN_GOVERNANCE'),
75
+ workspace_identity: when(opIn('initialize', 'register'), 'MAINTAIN_GOVERNANCE'),
76
+ };
77
+ /** The actions a call performs: `[]` for a read, `null` for a tool the table does not know. */
78
+ function actionsForTool(name, args) {
79
+ if (!Object.prototype.hasOwnProperty.call(exports.TOOL_ACTIONS, name))
80
+ return null;
81
+ const a = args && typeof args === 'object' ? args : {};
82
+ return exports.TOOL_ACTIONS[name](a);
83
+ }
84
+ /**
85
+ * The role refusal for this call, or null. The policy is the one of the project the call acts on (`args.root`, else
86
+ * `root`), resolved the way the handlers resolve it. With no policy there is no opinion (A-SPEC-152); with one, a tool
87
+ * the table does not know is refused, so a new tool cannot ship ungated.
88
+ */
89
+ function toolRoleRefusal(name, args, root, identity) {
90
+ const a = args && typeof args === 'object' ? args : {};
91
+ const resolve = (r) => { try {
92
+ return (0, root_1.resolveProjectRoot)(r).root;
93
+ }
94
+ catch {
95
+ return r;
96
+ } };
97
+ // @implements A-SPEC-774.6 — the caller chooses `args.root`; a root with no policy must not erase the bound
98
+ // project's (not every handler refuses a foreign root). Both policies are asked; either may refuse.
99
+ const roots = [resolve(root)];
100
+ if (typeof a.root === 'string' && a.root.trim() !== '') {
101
+ const asked = resolve(a.root);
102
+ if (asked !== roots[0])
103
+ roots.push(asked);
104
+ }
105
+ const policies = roots.map(role_policy_1.loadRolePolicy).filter((p) => p !== null);
106
+ if (policies.length === 0)
107
+ return null;
108
+ const actions = actionsForTool(name, a);
109
+ if (actions === null) {
110
+ return `[Holmes-Kit] ${name} is not in the role table (governance/tool-actions.ts) — under a role policy an unclassified tool is refused rather than run unchecked (A-SPEC-774).`;
111
+ }
112
+ for (const policy of policies) {
113
+ for (const action of actions) {
114
+ // @implements A-SPEC-774.10 — a legacy policy outside a run keeps what 0.35.25 never checked.
115
+ const refusal = (0, role_policy_1.roleCheck)(action, identity, policy, { run: (0, run_mode_1.runMode)(process.env, roots[0]).run });
116
+ if (refusal)
117
+ return refusal;
118
+ }
119
+ }
120
+ return null;
121
+ }
@@ -0,0 +1,15 @@
1
+ export declare function gateOffMarker(text: string): string | null;
2
+ /**
3
+ * @implements A-SPEC-774.26 — the words the option check reads. When the agent word is unquoted, each quoted span is one
4
+ * value or prompt (a `-d=` inside `-p "…"` is text) and is kept as a single word marked quoted. When the agent word is
5
+ * itself inside a quoted span (`tmux new -d 'claude --settings x'`), that span's words are the agent's options.
6
+ * Without spans (callers before 774.26) every word is an option word, as before.
7
+ */
8
+ export declare function launchView(words: readonly string[], spans?: readonly number[]): {
9
+ words: string[];
10
+ quoted: boolean[];
11
+ };
12
+ /** @implements A-SPEC-774.26 — the option words alone (no quoted prompt text), for the marker check. */
13
+ export declare function launchOptionWords(words: readonly string[], spans?: readonly number[]): string[];
14
+ /** The refusal for an interactive launch, or null. `words` is one launching segment (A-SPEC-774.5), quoting removed. */
15
+ export declare function interactiveLaunchIssue(rawWords: readonly string[], spans?: readonly number[]): string | null;