@holmes-lab/holmes-kit 0.35.24 → 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 (136) hide show
  1. package/CHANGELOG.md +363 -0
  2. package/README.md +4 -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 +34 -4
  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 +31 -1
  13. package/dist/holmes/cli/doctor.js +204 -7
  14. package/dist/holmes/cli/index.js +115 -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-approval.js +3 -2
  27. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  28. package/dist/holmes/cli/runtime-binding.js +116 -11
  29. package/dist/holmes/cli/scratch.d.ts +12 -0
  30. package/dist/holmes/cli/scratch.js +20 -0
  31. package/dist/holmes/cli/test-platform.d.ts +16 -0
  32. package/dist/holmes/cli/test-platform.js +31 -1
  33. package/dist/holmes/config/config.d.ts +49 -0
  34. package/dist/holmes/config/config.js +146 -3
  35. package/dist/holmes/config/project-caps.d.ts +21 -0
  36. package/dist/holmes/config/project-caps.js +114 -0
  37. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  38. package/dist/holmes/governance/approval-queue.js +51 -8
  39. package/dist/holmes/governance/autonomy.d.ts +6 -0
  40. package/dist/holmes/governance/autonomy.js +21 -0
  41. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  42. package/dist/holmes/governance/push-gate-runner.js +49 -1
  43. package/dist/holmes/governance/replica-id.d.ts +9 -0
  44. package/dist/holmes/governance/replica-id.js +44 -7
  45. package/dist/holmes/governance/role-policy.d.ts +41 -1
  46. package/dist/holmes/governance/role-policy.js +137 -20
  47. package/dist/holmes/governance/run-mode.d.ts +14 -0
  48. package/dist/holmes/governance/run-mode.js +120 -0
  49. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  50. package/dist/holmes/governance/tool-actions.js +121 -0
  51. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  52. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  53. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  54. package/dist/holmes/guardrail/classification-mode.js +135 -0
  55. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  56. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  57. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  58. package/dist/holmes/guardrail/impact-gate.js +34 -11
  59. package/dist/holmes/guardrail/phase.d.ts +2 -1
  60. package/dist/holmes/guardrail/phase.js +22 -8
  61. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  62. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  63. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  64. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  65. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  66. package/dist/holmes/guardrail/risk-classifier.js +255 -27
  67. package/dist/holmes/guardrail/risk-types.d.ts +16 -0
  68. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  69. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  70. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  71. package/dist/holmes/guardrail/run-refusals.js +348 -0
  72. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  73. package/dist/holmes/guardrail/run-stages.js +188 -0
  74. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  75. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  76. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  77. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  78. package/dist/holmes/guardrail/shell-words.js +7 -7
  79. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  80. package/dist/holmes/guardrail/write-target.js +118 -16
  81. package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
  82. package/dist/holmes/hooks/pre-tool-use.js +740 -81
  83. package/dist/holmes/hooks/session-start.js +5 -3
  84. package/dist/holmes/hooks/stop.d.ts +35 -1
  85. package/dist/holmes/hooks/stop.js +142 -7
  86. package/dist/holmes/mcp/elicit-approval.js +4 -4
  87. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  89. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  90. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  91. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  92. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  93. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  94. package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
  95. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  96. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  97. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  98. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  99. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  100. package/dist/holmes/mcp/handlers.d.ts +2 -3
  101. package/dist/holmes/mcp/handlers.js +22 -2
  102. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  103. package/dist/holmes/mcp/harness-attestation.js +3 -1
  104. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  105. package/dist/holmes/mcp/operator-recovery.js +4 -3
  106. package/dist/holmes/mcp/server.js +9 -0
  107. package/dist/holmes/mcp/tool-schemas.js +6 -3
  108. package/dist/holmes/project/npx-bin.d.ts +26 -0
  109. package/dist/holmes/project/npx-bin.js +272 -2
  110. package/dist/holmes/project/root.js +6 -1
  111. package/dist/holmes/project/run-records.d.ts +17 -0
  112. package/dist/holmes/project/run-records.js +126 -0
  113. package/dist/holmes/project/scratch-root.d.ts +12 -0
  114. package/dist/holmes/project/scratch-root.js +132 -0
  115. package/dist/holmes/review/mrp.d.ts +35 -0
  116. package/dist/holmes/review/mrp.js +119 -0
  117. package/dist/holmes/review/verdicts.d.ts +117 -0
  118. package/dist/holmes/review/verdicts.js +345 -0
  119. package/dist/holmes/runtime/dispatch.js +6 -3
  120. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  121. package/dist/holmes/semantic/cloud-usage.js +106 -0
  122. package/dist/holmes/semantic/embedder.d.ts +15 -6
  123. package/dist/holmes/semantic/embedder.js +84 -3
  124. package/dist/holmes/semantic/local-model.d.ts +21 -2
  125. package/dist/holmes/semantic/local-model.js +14 -3
  126. package/dist/holmes/semantic/tier.d.ts +25 -0
  127. package/dist/holmes/semantic/tier.js +86 -1
  128. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  129. package/dist/holmes/semantic/vector-cache.js +4 -1
  130. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  131. package/dist/holmes/spec/approval-blockers.js +70 -2
  132. package/dist/holmes/spec/renumber.d.ts +1 -1
  133. package/dist/holmes/spec/renumber.js +5 -2
  134. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  135. package/dist/holmes/spec/transition-policy.js +17 -2
  136. package/package.json +1 -1
@@ -0,0 +1,67 @@
1
+ import { StageMachine } from '../config/config';
2
+ type Decision = {
3
+ permissionDecision: string;
4
+ permissionDecisionReason?: string;
5
+ } & Record<string, unknown>;
6
+ /**
7
+ * @implements A-SPEC-781.1 — the stage means something to the gate: in a run, a file write whose action the current
8
+ * stage denies is refused. Outside a run, or for a run without a record, nothing changes.
9
+ */
10
+ export declare function applyStageGate(out: Decision, ctx: {
11
+ projectRoot: string;
12
+ env: NodeJS.ProcessEnv;
13
+ cwd?: string;
14
+ sessionId?: string;
15
+ tool: string;
16
+ toolInput: Record<string, unknown>;
17
+ }): Decision;
18
+ /**
19
+ * @implements A-SPEC-774.19 — in a run, every file tool target asks the role check with the run's stage, so a role that
20
+ * declares stages acts only in them. Without a run record, or without a role policy, nothing changes.
21
+ */
22
+ export declare function applyRoleStage(out: Decision, ctx: {
23
+ projectRoot: string;
24
+ env: NodeJS.ProcessEnv;
25
+ cwd?: string;
26
+ sessionId?: string;
27
+ tool: string;
28
+ toolInput: Record<string, unknown>;
29
+ }): Decision;
30
+ export declare function currentStage(main: string, runId: string, machine: StageMachine): string;
31
+ export declare function transitionRun(main: string, runId: string, to: string, opts: {
32
+ key: string;
33
+ why?: string;
34
+ by?: string;
35
+ now?: () => Date;
36
+ }): {
37
+ ok: true;
38
+ from: string;
39
+ to: string;
40
+ unchecked?: string[];
41
+ } | {
42
+ ok: false;
43
+ reason: string;
44
+ };
45
+ /** @implements A-SPEC-781.2 — what a transition condition sees, and what it answers. */
46
+ export interface TransitionContext {
47
+ main: string;
48
+ runId: string;
49
+ worktree: string;
50
+ from: string;
51
+ to: string;
52
+ }
53
+ export type TransitionVerdict = {
54
+ status: 'pass';
55
+ } | {
56
+ status: 'fail';
57
+ reason: string;
58
+ } | {
59
+ status: 'unchecked';
60
+ note: string;
61
+ };
62
+ /**
63
+ * @implements A-SPEC-781.2 — the transition checks by name. `design-section` is the G5.7 slot (a design section exists
64
+ * and agrees with the C-SPECs); until G5.7 fills it, it answers `unchecked`, recorded on the stage event.
65
+ */
66
+ export declare const TRANSITION_CHECKS: Record<string, (ctx: TransitionContext) => TransitionVerdict>;
67
+ export {};
@@ -0,0 +1,188 @@
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.TRANSITION_CHECKS = void 0;
37
+ exports.applyStageGate = applyStageGate;
38
+ exports.applyRoleStage = applyRoleStage;
39
+ exports.currentStage = currentStage;
40
+ exports.transitionRun = transitionRun;
41
+ // @implements A-SPEC-781, A-SPEC-781.1, A-SPEC-774.19, A-SPEC-781.2
42
+ /**
43
+ * @implements A-SPEC-781 — a run's SDLC stage is recorded state. Only the holder of the run's stop key (the
44
+ * orchestrator; the session inside the run never sees it) moves it, along the edges the project's machine declares,
45
+ * and into a stage that needs review only when an independent passing review covers the run's range.
46
+ */
47
+ const crypto = __importStar(require("node:crypto"));
48
+ const path = __importStar(require("node:path"));
49
+ const config_1 = require("../config/config");
50
+ const run_mode_1 = require("../governance/run-mode");
51
+ const identity_1 = require("../governance/identity");
52
+ const role_policy_1 = require("../governance/role-policy");
53
+ const run_records_1 = require("../project/run-records");
54
+ const classification_mode_1 = require("./classification-mode");
55
+ const phase_1 = require("./phase");
56
+ const run_plan_scope_1 = require("./run-plan-scope");
57
+ const verdicts_1 = require("../review/verdicts");
58
+ const run_refusals_1 = require("./run-refusals");
59
+ /**
60
+ * @implements A-SPEC-781.1 — the stage means something to the gate: in a run, a file write whose action the current
61
+ * stage denies is refused. Outside a run, or for a run without a record, nothing changes.
62
+ */
63
+ function applyStageGate(out, ctx) {
64
+ if (out.permissionDecision === 'deny')
65
+ return out;
66
+ const targets = (0, run_plan_scope_1.planTargets)(ctx.tool, ctx.toolInput);
67
+ if (targets.length === 0)
68
+ return out;
69
+ const mode = (0, run_mode_1.runMode)(ctx.env, ctx.projectRoot, ctx.cwd, ctx.sessionId);
70
+ if (!mode.run || !mode.id)
71
+ return out;
72
+ const main = (0, run_records_1.mainCheckoutOf)(ctx.projectRoot);
73
+ if (!(0, run_records_1.listRuns)(main).some((r) => r.run_id === mode.id))
74
+ return out;
75
+ const machine = (0, config_1.loadConfig)(main).stages;
76
+ const stage = currentStage(main, mode.id, machine);
77
+ const denied = new Set(machine.deny[stage] ?? []);
78
+ if (denied.size === 0)
79
+ return out;
80
+ const opts = (0, classification_mode_1.classifyOptionsFor)(ctx.projectRoot, true);
81
+ const base = path.resolve(ctx.cwd ?? ctx.projectRoot);
82
+ for (const t of targets) {
83
+ const rel = path.relative(ctx.projectRoot, path.isAbsolute(t) ? t : path.resolve(base, t)).replace(/\\/g, '/');
84
+ const action = (0, phase_1.classifyAction)(rel, undefined, opts);
85
+ if (action && denied.has(action)) {
86
+ return {
87
+ permissionDecision: 'deny',
88
+ permissionDecisionReason: `[Holmes-Kit] the run is in stage ${stage}, where ${action} is not allowed (${rel}) — the orchestrator moves the run with holmes-kit run transition`,
89
+ };
90
+ }
91
+ }
92
+ return out;
93
+ }
94
+ /**
95
+ * @implements A-SPEC-774.19 — in a run, every file tool target asks the role check with the run's stage, so a role that
96
+ * declares stages acts only in them. Without a run record, or without a role policy, nothing changes.
97
+ */
98
+ function applyRoleStage(out, ctx) {
99
+ if (out.permissionDecision === 'deny')
100
+ return out;
101
+ const targets = (0, run_plan_scope_1.planTargets)(ctx.tool, ctx.toolInput);
102
+ if (targets.length === 0)
103
+ return out;
104
+ const mode = (0, run_mode_1.runMode)(ctx.env, ctx.projectRoot, ctx.cwd, ctx.sessionId);
105
+ if (!mode.run || !mode.id)
106
+ return out;
107
+ const main = (0, run_records_1.mainCheckoutOf)(ctx.projectRoot);
108
+ if (!(0, run_records_1.listRuns)(main).some((r) => r.run_id === mode.id))
109
+ return out;
110
+ const policy = (0, role_policy_1.loadRolePolicy)(ctx.projectRoot);
111
+ if (policy === null)
112
+ return out;
113
+ const stage = currentStage(main, mode.id, (0, config_1.loadConfig)(main).stages);
114
+ const identity = new identity_1.EnvIdentityProvider(ctx.env).current();
115
+ const opts = (0, classification_mode_1.classifyOptionsFor)(ctx.projectRoot, true);
116
+ const base = path.resolve(ctx.cwd ?? ctx.projectRoot);
117
+ for (const t of targets) {
118
+ const rel = path.relative(ctx.projectRoot, path.isAbsolute(t) ? t : path.resolve(base, t)).replace(/\\/g, '/');
119
+ const issue = (0, role_policy_1.roleCheck)((0, phase_1.classifyAction)(rel, undefined, opts) ?? 'WRITE_OTHER', identity, policy, { run: true, stage });
120
+ if (issue)
121
+ return { permissionDecision: 'deny', permissionDecisionReason: issue };
122
+ }
123
+ return out;
124
+ }
125
+ function currentStage(main, runId, machine) {
126
+ const events = (0, run_refusals_1.readRunRefusals)((0, run_refusals_1.runRefusalsFile)(main, runId));
127
+ if (Array.isArray(events)) {
128
+ for (let i = events.length - 1; i >= 0; i--) {
129
+ const e = events[i];
130
+ if (e.event === 'stage' && typeof e.to === 'string')
131
+ return e.to;
132
+ }
133
+ }
134
+ return machine.order[0];
135
+ }
136
+ function transitionRun(main, runId, to, opts) {
137
+ const rec = (0, run_records_1.listRuns)(main).find((r) => r.run_id === runId);
138
+ if (!rec)
139
+ return { ok: false, reason: `no run ${runId}` };
140
+ const stored = typeof rec.stop_key_sha256 === 'string' && /^[0-9a-f]{64}$/.test(rec.stop_key_sha256) ? rec.stop_key_sha256 : null;
141
+ if (!stored || !crypto.timingSafeEqual(Buffer.from((0, run_records_1.keyHash)(opts.key)), Buffer.from(stored))) {
142
+ return { ok: false, reason: 'the stop key does not match this run — only its orchestrator moves its stage' };
143
+ }
144
+ const machine = (0, config_1.loadConfig)(main).stages;
145
+ if (!machine.order.includes(to))
146
+ return { ok: false, reason: `${to} is not a stage of this project's machine (${machine.order.join(', ')})` };
147
+ const from = currentStage(main, runId, machine);
148
+ if (!(machine.transitions[from] ?? []).includes(to)) {
149
+ return { ok: false, reason: `${from} → ${to} is not an allowed transition (from ${from}: ${(machine.transitions[from] ?? []).join(', ') || 'none'})` };
150
+ }
151
+ if (machine.reviewed.includes(to)) {
152
+ if (typeof rec.base !== 'string' || rec.base === '')
153
+ return { ok: false, reason: `${to} needs a review of the run's range, and the run recorded no base at start` };
154
+ const range = (0, verdicts_1.resolveRange)(rec.worktree, rec.base, 'HEAD');
155
+ if ('error' in range)
156
+ return { ok: false, reason: range.error };
157
+ const g = (0, verdicts_1.gateRange)(rec.worktree, range.base, range.head, {});
158
+ if (!g.ok)
159
+ return { ok: false, reason: `${to} needs an independent passing review of ${range.base}..${range.head}: ${g.reasons.join('; ')}` };
160
+ }
161
+ // @implements A-SPEC-781.2 — the edge's conditions: a name nobody checks refuses; a slot is recorded as unchecked.
162
+ const edge = `${from}->${to}`;
163
+ const unchecked = [];
164
+ for (const name of machine.conditions[edge] ?? []) {
165
+ const check = exports.TRANSITION_CHECKS[name];
166
+ if (!check)
167
+ return { ok: false, reason: `condition ${name} on ${edge} has no checker — a transition condition nobody can check is refused` };
168
+ const r = check({ main, runId, worktree: rec.worktree, from, to });
169
+ if (r.status === 'fail')
170
+ return { ok: false, reason: `${edge} needs ${name}: ${r.reason}` };
171
+ if (r.status === 'unchecked')
172
+ unchecked.push(name);
173
+ }
174
+ const ok = (0, run_refusals_1.appendRunEvent)(main, runId, {
175
+ ts: (opts.now ? opts.now() : new Date()).toISOString(), event: 'stage', from, to,
176
+ by: opts.by ?? 'orchestrator', ...(opts.why ? { why: opts.why } : {}), ...(unchecked.length > 0 ? { unchecked } : {}),
177
+ });
178
+ if (!ok)
179
+ return { ok: false, reason: 'the run event log could not be written' };
180
+ return { ok: true, from, to, ...(unchecked.length > 0 ? { unchecked } : {}) };
181
+ }
182
+ /**
183
+ * @implements A-SPEC-781.2 — the transition checks by name. `design-section` is the G5.7 slot (a design section exists
184
+ * and agrees with the C-SPECs); until G5.7 fills it, it answers `unchecked`, recorded on the stage event.
185
+ */
186
+ exports.TRANSITION_CHECKS = {
187
+ 'design-section': () => ({ status: 'unchecked', note: 'the design-section check arrives with G5.7' }),
188
+ };
@@ -1,4 +1,8 @@
1
- /** Repo test conventions — the single census every dispensation consumer shares. */
1
+ /**
2
+ * Repo test conventions — the single census every dispensation consumer shares.
3
+ * @implements A-SPEC-775 — the scanner's table, minus anything that executes. A private folder rule
4
+ * here dispensed `tests/run.sh` as a test while the gate and the graph each kept their own answer.
5
+ */
2
6
  export declare function isTestPath(relPath: string): boolean;
3
7
  /**
4
8
  * One FtT token against one repo-relative path. `**` crosses separators, `*` does not; a literal
@@ -29,17 +29,15 @@ exports.judgeScope = judgeScope;
29
29
  * a warning — silent RTM loss is the failure mode C12 taught us to fear.
30
30
  */
31
31
  const linear_match_1 = require("./linear-match");
32
- /** Repo test conventions — the single census every dispensation consumer shares. */
32
+ const test_files_1 = require("../cpg/test-files");
33
+ const executable_artifact_1 = require("./executable-artifact");
34
+ /**
35
+ * Repo test conventions — the single census every dispensation consumer shares.
36
+ * @implements A-SPEC-775 — the scanner's table, minus anything that executes. A private folder rule
37
+ * here dispensed `tests/run.sh` as a test while the gate and the graph each kept their own answer.
38
+ */
33
39
  function isTestPath(relPath) {
34
- const base = relPath.split('/').at(-1) ?? '';
35
- if (/\.(test|spec)\.[^.]+$/.test(base))
36
- return true; // x.test.ts / x.spec.tsx
37
- if (/^test_[^/]*\.py$/.test(base))
38
- return true; // pytest collection default
39
- if (/_test\.(py|go)$/.test(base))
40
- return true; // pytest alt / go test
41
- const segs = relPath.split('/').slice(0, -1);
42
- return segs.some((s) => s === 'tests' || s === '__tests__' || s === 'test');
40
+ return (0, test_files_1.isTestFile)(relPath) && !(0, executable_artifact_1.isExecutableArtifact)(relPath);
43
41
  }
44
42
  /**
45
43
  * One FtT token against one repo-relative path. `**` crosses separators, `*` does not; a literal
@@ -0,0 +1,3 @@
1
+ export declare function recordScopeRefusals(root: string, file: string, specs: readonly string[], now?: number): void;
2
+ /** The specs this file was refused admission to within the last 2 hours, oldest first. */
3
+ export declare function recentScopeRefusals(root: string, file: string, now?: number): string[];
@@ -0,0 +1,85 @@
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.recordScopeRefusals = recordScopeRefusals;
37
+ exports.recentScopeRefusals = recentScopeRefusals;
38
+ // @implements A-SPEC-166.2
39
+ // The gate's short memory of the scope refusals it gave, per file. It exists for one question: after the gate refused
40
+ // admitting a file to spec X, does the next edit add an anchor site naming another spec instead (anchor
41
+ // self-selection)? Bounded (50 entries, 2 hours) and never decisive when broken: a record that cannot be read or
42
+ // written changes no verdict.
43
+ const fs = __importStar(require("node:fs"));
44
+ const path = __importStar(require("node:path"));
45
+ const MAX_ENTRIES = 50;
46
+ const MAX_AGE_MS = 2 * 3600_000;
47
+ const recordPath = (root) => path.join(root, '.ax', 'state', 'scope-refusals.json');
48
+ function readEntries(root) {
49
+ try {
50
+ const doc = JSON.parse(fs.readFileSync(recordPath(root), 'utf8'));
51
+ if (!Array.isArray(doc.entries))
52
+ return [];
53
+ return doc.entries.filter((e) => !!e && typeof e === 'object'
54
+ && typeof e.file === 'string' && typeof e.spec === 'string' && typeof e.ts === 'string');
55
+ }
56
+ catch {
57
+ return [];
58
+ }
59
+ }
60
+ function recordScopeRefusals(root, file, specs, now = Date.now()) {
61
+ if (specs.length === 0)
62
+ return;
63
+ const ts = new Date(now).toISOString();
64
+ const entries = [...readEntries(root).filter((e) => !(e.file === file && specs.includes(e.spec))),
65
+ ...specs.map((spec) => ({ file, spec, ts }))].slice(-MAX_ENTRIES);
66
+ const target = recordPath(root);
67
+ const tmp = `${target}.${process.pid}.tmp`;
68
+ try {
69
+ fs.mkdirSync(path.dirname(target), { recursive: true });
70
+ fs.writeFileSync(tmp, JSON.stringify({ entries }));
71
+ fs.renameSync(tmp, target);
72
+ }
73
+ catch {
74
+ try {
75
+ fs.rmSync(tmp, { force: true });
76
+ }
77
+ catch { /* nothing to clean */ }
78
+ }
79
+ }
80
+ /** The specs this file was refused admission to within the last 2 hours, oldest first. */
81
+ function recentScopeRefusals(root, file, now = Date.now()) {
82
+ return [...new Set(readEntries(root)
83
+ .filter((e) => e.file === file && now - Date.parse(e.ts) <= MAX_AGE_MS && Date.parse(e.ts) <= now + 60_000)
84
+ .map((e) => e.spec))];
85
+ }
@@ -38,7 +38,7 @@ exports.findRunsUnfiltered = findRunsUnfiltered;
38
38
  exports.harnessWiringActOf = harnessWiringActOf;
39
39
  exports.harnessWiringActOfCommand = harnessWiringActOfCommand;
40
40
  exports.globToRe = globToRe;
41
- // @implements A-SPEC-728, A-SPEC-733, A-SPEC-753
41
+ // @implements A-SPEC-728, A-SPEC-733, A-SPEC-753, A-SPEC-476.7
42
42
  // Shell WORDS, not spellings. The wiring-protection rule was first written as regexes over verb
43
43
  // spellings and the adversarial round walked through it twenty ways (`\rm`, `env rm`, `rm .mcp"".json`,
44
44
  // `rm .claude/settings.{json,local.json}`, `mv`, `git rm`, `find -delete`, …): a gate over a spelling
@@ -237,17 +237,17 @@ const pathShapedLiteral = (literal) => {
237
237
  const t = literal.trim();
238
238
  if (t === '')
239
239
  return false;
240
- return !/\s/.test(t) || /^(?:[/~]|\.{1,2}[/\\]|[A-Za-z]:[\\/])/.test(t) || write_target_1.WIRING_FILE_NAMES.some((n) => t.toLowerCase().startsWith(n));
240
+ return !/\s/.test(t) || /^(?:[/~]|\.{1,2}[/\\]|[A-Za-z]:[\\/])/.test(t) || (0, write_target_1.wiringFileNames)().some((n) => t.toLowerCase().startsWith(n));
241
241
  };
242
242
  const mentionsWiringUncached = (text) => {
243
243
  const t = text.toLowerCase();
244
- if (write_target_1.WIRING_FILE_NAMES.some((n) => t.includes(n)) || /(^|[^\w.-])\.(?:claude|agents|codex|ax)(?![\w-])/.test(t))
244
+ if ((0, write_target_1.wiringFileNames)().some((n) => t.includes(n)) || /(^|[^\w.-])\.(?:claude|agents|codex|ax)(?![\w-])/.test(t))
245
245
  return true;
246
246
  for (const tok of t.split(/[\s;|&<>()'"`=]+/)) {
247
247
  if (!/[*?[]/.test(tok) || tok.length > 256)
248
248
  continue;
249
249
  const re = (0, write_target_1.globPatternRe)(tok.split('/').pop() ?? tok, true);
250
- if ([...write_target_1.WIRING_FILE_NAMES, ...write_target_1.WIRING_DIR_NAMES].some((n) => re.test(n)))
250
+ if ([...(0, write_target_1.wiringFileNames)(), ...write_target_1.WIRING_DIR_NAMES].some((n) => re.test(n)))
251
251
  return true;
252
252
  }
253
253
  return false;
@@ -376,7 +376,7 @@ function harnessWiringActOf(root, base, segmentText, fullText, env = process.env
376
376
  const byName = (w, dirs) => {
377
377
  const n = (0, linear_match_1.trimTrailing)(w.text, '/\\').split(/[/\\]/).pop()?.toLowerCase() ?? '';
378
378
  const shown = w.text.length > 120 ? `…${w.text.slice(-80)}` : w.text;
379
- return write_target_1.WIRING_FILE_NAMES.includes(n) || (dirs && write_target_1.WIRING_DIR_NAMES.includes(n))
379
+ return (0, write_target_1.wiringFileNames)().includes(n) || (dirs && write_target_1.WIRING_DIR_NAMES.includes(n))
380
380
  ? `${shown} (${!w.known ? 'a path spelled with an unknowable part' : w.text.length > MAX_PATH ? 'a path too long to resolve' : 'where the command runs is unknowable'})` : null;
381
381
  };
382
382
  // A word made unknowable by `$(…)` or a variable is still refused when its last component is a
@@ -882,7 +882,7 @@ function harnessWiringActOf(root, base, segmentText, fullText, env = process.env
882
882
  const namedLikeWiring = (m) => {
883
883
  if (!byNameToo)
884
884
  return null;
885
- const hit = m.text.split(/[/\\]/).find((c) => { const n = c.toLowerCase(); return n !== '' && n !== '.' && (write_target_1.WIRING_FILE_NAMES.includes(n) || write_target_1.WIRING_DIR_NAMES.includes(n)); });
885
+ const hit = m.text.split(/[/\\]/).find((c) => { const n = c.toLowerCase(); return n !== '' && n !== '.' && ((0, write_target_1.wiringFileNames)().includes(n) || write_target_1.WIRING_DIR_NAMES.includes(n)); });
886
886
  if (hit === undefined)
887
887
  return null;
888
888
  const shown = m.text.length > 120 ? `…${m.text.slice(-80)}` : m.text;
@@ -1135,7 +1135,7 @@ function harnessWiringActOf(root, base, segmentText, fullText, env = process.env
1135
1135
  if (filters.length > 0) {
1136
1136
  const hit = filters.some((f) => {
1137
1137
  const re = (0, write_target_1.globPatternRe)(path.basename(f), true);
1138
- return write_target_1.WIRING_FILE_NAMES.some((n) => re.test(n)) || write_target_1.WIRING_DIR_NAMES.some((d) => re.test(d));
1138
+ return (0, write_target_1.wiringFileNames)().some((n) => re.test(n)) || write_target_1.WIRING_DIR_NAMES.some((d) => re.test(d));
1139
1139
  });
1140
1140
  return hit ? `a wiring file matched by find ${filters.join(' ')}` : null;
1141
1141
  }
@@ -83,6 +83,10 @@ export declare function isWholePatch(text: string): boolean;
83
83
  * line, so the patch cannot be read one way (A-SPEC-163.2 rule 2).
84
84
  */
85
85
  export declare function patchAmbiguous(text: string): boolean;
86
+ /** The grammar's one option: the host whose path grammar applies the patch (default: this process's host). */
87
+ export interface PatchGrammarOpts {
88
+ host?: path.PlatformPath;
89
+ }
86
90
  /**
87
91
  * Whether a text is the one patch form the gate judges.
88
92
  *
@@ -93,7 +97,7 @@ export declare function patchAmbiguous(text: string): boolean;
93
97
  * header behind anything — makes the text not canonical, and the caller refuses it. A line-by-line prefix walk: no
94
98
  * pattern over the whole text, nothing to back-track on.
95
99
  */
96
- export declare function canonicalPatch(text: string): boolean;
100
+ export declare function canonicalPatch(text: string, opts?: PatchGrammarOpts): boolean;
97
101
  /**
98
102
  * @implements A-SPEC-769.7 — WHY a text is not canonical, for the refusal that names it. `null` when `canonicalPatch`
99
103
  * is true; `'no-op'` when every grammar rule holds and the only fault is an update block with no `+`/`-` line (the
@@ -103,7 +107,7 @@ export declare function canonicalPatch(text: string): boolean;
103
107
  * block that closes with zero content lines is counted instead of refused, and an add block that adds nothing stays a
104
108
  * grammar fault (an add must add). This function changes no gate decision — only the reason text a caller prints.
105
109
  */
106
- export declare function canonicalPatchReason(text: string): null | 'no-op' | 'grammar';
110
+ export declare function canonicalPatchReason(text: string, opts?: PatchGrammarOpts): null | 'no-op' | 'grammar';
107
111
  /** Every header is a target, in order; nothing is merged or dropped by path (A-SPEC-163.2 rule 2). */
108
112
  export declare function patchTargetsOf(text: string): PatchTarget[];
109
113
  /**
@@ -153,6 +157,15 @@ export declare function applyPatchUpdateDetailed(original: string, hunk: string)
153
157
  * A relative `raw` carries no grammar of its own, so the root decides.
154
158
  */
155
159
  export declare function pathFlavorFor(root: string, raw: string): path.PlatformPath;
160
+ /**
161
+ * The path grammar of the host this process runs on — the one place this module asks.
162
+ *
163
+ * @implements A-SPEC-163.8
164
+ * Read off `path.sep` at call time: not `process.platform`, and not module identity (see `resolveTarget`). Every caller
165
+ * takes it as a default it lets a test override, so a POSIX run asserts the win32 answers and a Windows run the POSIX
166
+ * ones. `pathFlavorFor` answers a different question — which grammar a STRING is written in.
167
+ */
168
+ export declare function hostFlavor(): path.PlatformPath;
156
169
  /**
157
170
  * The filesystem operations `resolveTarget` consults, injectable so the CROSS-flavor scenario is
158
171
  * testable from either host (A-SPEC-465): production always passes the real `fs`.
@@ -214,6 +227,8 @@ export declare function specTargetOf(root: string, specsDir: string, raw: string
214
227
  * resolution is `resolveTarget`'s — it follows links, including dangling ones, because a write
215
228
  * through a dangling link creates exactly the file it names.
216
229
  */
230
+ /** @implements A-SPEC-476.3 — whether a write lands on `<root>/ax.config.json`, by identity (links followed, case folded). */
231
+ export declare function isProjectConfigTarget(root: string, raw: string): boolean;
217
232
  export declare function protectedFileKindOf(root: string, raw: string): string | null;
218
233
  /**
219
234
  * @implements A-SPEC-728
@@ -228,7 +243,10 @@ export declare const GOVERNANCE_STORE_LABEL = ".ax (the spec store and ledger)";
228
243
  /** Every directory name that is judged as a whole: the session wiring directories and `.ax`. */
229
244
  export declare const WIRING_DIR_NAMES: string[];
230
245
  /** Every file name a wiring target can carry — `xargs`/`find` judge by name when paths are unknowable. */
246
+ export declare const PROJECT_CAPS_LABEL = "ax.config.json";
231
247
  export declare const WIRING_FILE_NAMES: string[];
248
+ export declare function wiringFileNames(): readonly string[];
249
+ export declare function withoutProjectCaps<T>(fn: () => T): T;
232
250
  export declare function withIdentCache<T>(fn: () => T): T;
233
251
  /**
234
252
  * @implements A-SPEC-728
@@ -426,3 +444,14 @@ export declare function shellSegments(command: string, startBase: string, depth?
426
444
  ax?: boolean;
427
445
  }): ShellSegment[];
428
446
  export declare function resolvesInside(raw: string, roots: readonly string[], impl?: PathImpl): boolean;
447
+ /**
448
+ * @implements A-SPEC-776 — the paths a foreign MCP call names, read from whatever field its author chose.
449
+ * `null` for a call that is not a foreign (non-holmes-kit) MCP tool, or whose tool name is a recognisable read. A
450
+ * `file://` URI becomes its path; any other `scheme://` value is unresolvable, and the caller refuses it.
451
+ * Measured 2026-10-18: write_file{path}, write{filePath}, save{uri}, create{target} and move{destination} all wrote a
452
+ * code file the gate never saw, because it read only `file_path` and `notebook_path`.
453
+ */
454
+ export declare function foreignMcpPaths(toolName: string | undefined, input: unknown): {
455
+ paths: string[];
456
+ unresolvable: string[];
457
+ } | null;