@holmes-lab/holmes-kit 0.30.0 → 0.31.1

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 (139) hide show
  1. package/CHANGELOG.md +505 -0
  2. package/README.md +10 -1
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents.d.ts +41 -0
  9. package/dist/holmes/cli/agents.js +382 -2
  10. package/dist/holmes/cli/attest.d.ts +2 -0
  11. package/dist/holmes/cli/attest.js +66 -15
  12. package/dist/holmes/cli/ci-gate.js +16 -1
  13. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  14. package/dist/holmes/cli/claude-switches.js +967 -0
  15. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  16. package/dist/holmes/cli/codex-hooks.js +802 -0
  17. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  18. package/dist/holmes/cli/codex-oracle.js +1245 -0
  19. package/dist/holmes/cli/codex-toml.d.ts +35 -0
  20. package/dist/holmes/cli/codex-toml.js +321 -52
  21. package/dist/holmes/cli/doctor.d.ts +98 -8
  22. package/dist/holmes/cli/doctor.js +1328 -94
  23. package/dist/holmes/cli/index.js +26 -11
  24. package/dist/holmes/cli/init.d.ts +11 -0
  25. package/dist/holmes/cli/init.js +736 -44
  26. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  27. package/dist/holmes/cli/mcp-launcher.js +189 -6
  28. package/dist/holmes/cli/mcp-version.js +13 -2
  29. package/dist/holmes/cli/settings-merge.js +8 -2
  30. package/dist/holmes/cli/upgrade.d.ts +18 -0
  31. package/dist/holmes/cli/upgrade.js +129 -24
  32. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  33. package/dist/holmes/cli/workspace-scope.js +375 -0
  34. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  35. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  36. package/dist/holmes/cpg/cycle-detect.js +2 -1
  37. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  38. package/dist/holmes/cpg/required-calls.js +8 -1
  39. package/dist/holmes/governance/constitution-debt.js +3 -2
  40. package/dist/holmes/governance/constitution.js +15 -3
  41. package/dist/holmes/governance/provenance-chain.js +3 -2
  42. package/dist/holmes/governance/push-gate-runner.js +4 -3
  43. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  44. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  45. package/dist/holmes/guardrail/linear-match.js +256 -0
  46. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  47. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  48. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  49. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  50. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  51. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  52. package/dist/holmes/guardrail/shell-words.js +1720 -0
  53. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  54. package/dist/holmes/guardrail/write-target.js +2379 -87
  55. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  56. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  57. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  58. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  59. package/dist/holmes/hooks/rtm-refresh-child.js +3 -1
  60. package/dist/holmes/hooks/rtm-refresh.js +8 -4
  61. package/dist/holmes/hooks/session-start.d.ts +10 -0
  62. package/dist/holmes/hooks/session-start.js +31 -7
  63. package/dist/holmes/hooks/stop.d.ts +2 -1
  64. package/dist/holmes/hooks/stop.js +197 -91
  65. package/dist/holmes/mcp/approval-commit.d.ts +5 -6
  66. package/dist/holmes/mcp/approval-commit.js +18 -2
  67. package/dist/holmes/mcp/elicit-approval.js +4 -2
  68. package/dist/holmes/mcp/handlers/graph-operations.js +3 -2
  69. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  70. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  71. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  72. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  73. package/dist/holmes/mcp/handlers/requirement-triage.js +5 -3
  74. package/dist/holmes/mcp/handlers/review-evidence.js +8 -2
  75. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +11 -0
  76. package/dist/holmes/mcp/handlers/slice-orchestration.js +115 -16
  77. package/dist/holmes/mcp/handlers/spec-approval.d.ts +9 -0
  78. package/dist/holmes/mcp/handlers/spec-approval.js +110 -17
  79. package/dist/holmes/mcp/handlers/spec-authoring.js +17 -2
  80. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  81. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  82. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  83. package/dist/holmes/mcp/handlers.d.ts +81 -9
  84. package/dist/holmes/mcp/handlers.js +70 -23
  85. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  86. package/dist/holmes/mcp/harness-attestation.js +179 -0
  87. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -0
  88. package/dist/holmes/mcp/requirement-triage-evidence.js +160 -4
  89. package/dist/holmes/mcp/server.js +20 -1
  90. package/dist/holmes/mcp/tool-schemas.js +26 -9
  91. package/dist/holmes/mcp/validate-args.js +12 -0
  92. package/dist/holmes/project/bounded-io.d.ts +102 -0
  93. package/dist/holmes/project/bounded-io.js +212 -0
  94. package/dist/holmes/project/change-source.js +3 -1
  95. package/dist/holmes/project/ci-runs.js +3 -2
  96. package/dist/holmes/project/ignore.d.ts +31 -2
  97. package/dist/holmes/project/ignore.js +409 -50
  98. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  99. package/dist/holmes/project/regular-file-guard.js +149 -0
  100. package/dist/holmes/project/root.js +12 -3
  101. package/dist/holmes/reverse/anchor.js +4 -3
  102. package/dist/holmes/reverse/scan.js +6 -2
  103. package/dist/holmes/review/commit-text.js +3 -2
  104. package/dist/holmes/review/condition-hunk-replay.js +3 -2
  105. package/dist/holmes/review/failed-test-names.js +13 -10
  106. package/dist/holmes/review/findings.js +3 -1
  107. package/dist/holmes/review/kills-check.js +6 -1
  108. package/dist/holmes/review/point-in-time-replay.js +5 -4
  109. package/dist/holmes/review/replay-corpus.js +5 -4
  110. package/dist/holmes/review/run-replay.js +3 -2
  111. package/dist/holmes/review/temporal-prior.js +3 -2
  112. package/dist/holmes/review/test-evidence.js +3 -2
  113. package/dist/holmes/review/test-outcomes.js +3 -2
  114. package/dist/holmes/review/test-runner.d.ts +6 -0
  115. package/dist/holmes/review/test-runner.js +36 -15
  116. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  117. package/dist/holmes/rtm/anchor-ids.js +42 -2
  118. package/dist/holmes/rtm/file-anchors.js +4 -1
  119. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  120. package/dist/holmes/rtm/git-changes.js +3 -1
  121. package/dist/holmes/rtm/graph-store.js +3 -2
  122. package/dist/holmes/rtm/test-scope.js +9 -4
  123. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  124. package/dist/holmes/spec/compat-impact.js +682 -11
  125. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  126. package/dist/holmes/spec/entity-integration.js +3 -2
  127. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  128. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  129. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  130. package/dist/holmes/spec/renumber.js +25 -10
  131. package/dist/holmes/spec/spec-parser.js +9 -3
  132. package/dist/holmes/spec/yaml-scalar.js +2 -2
  133. package/dist/holmes/update/refresh.d.ts +5 -0
  134. package/dist/holmes/update/refresh.js +26 -1
  135. package/dist/holmes/update/update-notice.d.ts +6 -0
  136. package/dist/holmes/update/update-notice.js +18 -1
  137. package/dist/holmes/update/upgrade-plan.d.ts +28 -0
  138. package/dist/holmes/update/upgrade-plan.js +31 -2
  139. package/package.json +11 -4
@@ -33,10 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.BADGE_REL = void 0;
36
+ exports.ATTEST_UNKNOWN = exports.BADGE_REL = void 0;
37
37
  exports.buildAttestReport = buildAttestReport;
38
38
  exports.runAttest = runAttest;
39
- // @implements A-SPEC-702
39
+ // @implements A-SPEC-702, A-SPEC-734
40
40
  /**
41
41
  * `holmes-kit attest` — the surface that calls `rtm/traced-files`.
42
42
  *
@@ -54,37 +54,62 @@ const root_1 = require("../project/root");
54
54
  const test_scope_1 = require("../rtm/test-scope");
55
55
  const file_anchors_1 = require("../rtm/file-anchors");
56
56
  const link_census_1 = require("../rtm/link-census");
57
+ const bounded_io_1 = require("../project/bounded-io");
57
58
  const traced_files_1 = require("../rtm/traced-files");
58
59
  exports.BADGE_REL = path.join('.ax', 'badges', 'traced.svg');
59
60
  const SPECS_REL = path.join('.ax', 'specs');
60
61
  const git = (root, args) => {
61
62
  try {
62
- return (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(process.env) }).toString('utf8');
63
+ return (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER, timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(process.env) }).toString('utf8');
63
64
  }
64
65
  catch {
65
66
  return undefined;
66
67
  }
67
68
  };
69
+ /** Round 15: the text of the qualifier when the working-tree status did not answer (it claimed a clean commit — measured). */
70
+ exports.ATTEST_UNKNOWN = '+unknown';
68
71
  /**
69
72
  * `+dirty` only when something that DECIDES the number is uncommitted: a scanned source file or a
70
73
  * spec. The badge and the README are outputs of this very command, and a session ledger is always
71
74
  * moving — counting them would make a committed badge say `+dirty` forever.
72
75
  */
73
76
  function decidingPathsDirty(root, scanned) {
74
- const out = git(root, ['status', '--porcelain', '-z', '--untracked-files=all']);
75
- if (out === undefined)
76
- return false;
77
+ // @implements A-SPEC-734 (round 17) — limited to the project and read from its own root: git prints porcelain paths
78
+ // from the REPOSITORY root, so a monorepo package's dirty tree was called clean (measured).
79
+ const prefix = git(root, ['rev-parse', '--show-prefix']);
80
+ const base0 = (prefix ?? '').trim();
81
+ const limit = base0 !== '' && /^[\x20-\x7e]+$/.test(base0) ? ['--', `:(top,icase,literal)${base0}`] : [];
82
+ const out = git(root, ['status', '--porcelain', '-z', '--untracked-files=all', '--ignore-submodules=all', ...limit]);
83
+ // @implements A-SPEC-734 (round 15) — a status that did not answer is not a clean tree.
84
+ if (out === undefined || prefix === undefined)
85
+ return 'unknown';
86
+ const base = prefix.trim();
77
87
  const specs = SPECS_REL.split(path.sep).join('/') + '/';
78
- for (const entry of out.split('\0')) {
88
+ const entries = out.split('\0');
89
+ for (let i = 0; i < entries.length; i++) {
90
+ const entry = entries[i];
79
91
  if (entry.length < 4)
80
92
  continue;
81
- const p = entry.slice(3);
82
- if (p.startsWith(specs) || scanned.has(p))
93
+ // `-z` renames and copies: the next entry is the source path, in either column (a working-tree rename's source
94
+ // swallowed the next real entry — measured).
95
+ const xy = entry.slice(0, 2);
96
+ const source = /[RC]/.test(xy) ? entries[++i] : undefined;
97
+ // A-SPEC-734 (round 20): a deleted source and a rename's source decide too (` D src/b.ts` and a spec renamed out of
98
+ // the store read clean — measured); a deleted file is not in the current scan, so it is judged by its extension.
99
+ const decides = (q, gone) => q !== null
100
+ && (q.startsWith(specs) || scanned.has(q) || (gone && cpg_scanner_1.SCANNABLE_EXTENSIONS.some((e) => q.endsWith(e))));
101
+ if (source !== undefined && decides((0, bounded_io_1.underGitPrefix)(source, base), true))
102
+ return true;
103
+ const p = (0, bounded_io_1.underGitPrefix)(entry.slice(3), base);
104
+ if (p === null)
105
+ continue;
106
+ if (decides(p, xy.includes('D')))
83
107
  return true;
84
108
  }
85
109
  return false;
86
110
  }
87
111
  async function buildAttestReport(root, exclude) {
112
+ (0, cpg_scanner_1.forgetUnverifiedUnder)(root);
88
113
  const scanned = new cpg_scanner_1.CpgScanner().scan(root, root);
89
114
  const specs = await new spec_store_1.LocalMarkdownRepository(path.join(root, SPECS_REL)).list();
90
115
  const approved = specs.filter((s) => s.status === 'approved');
@@ -101,15 +126,26 @@ async function buildAttestReport(root, exclude) {
101
126
  weakMentions: {},
102
127
  });
103
128
  const commit = git(root, ['rev-parse', 'HEAD'])?.trim();
129
+ const dirty = commit ? decidingPathsDirty(root, new Set(files.map((f) => f.path))) : false;
130
+ const provenance = (0, traced_files_1.attestProvenance)({
131
+ commit,
132
+ dirty: dirty === true,
133
+ approved: approved.map((s) => ({ id: s.id, digest: String(s.frontmatter.approved_digest ?? '') })),
134
+ exclude,
135
+ });
136
+ // @implements A-SPEC-734 (round 17) — a repository git refuses to read has an unknown commit, not none (a refused
137
+ // repository said `unversioned`); a repository with no commit yet still answers `--git-dir`.
138
+ if (commit === undefined && git(root, ['rev-parse', '--git-dir']) === undefined && (0, bounded_io_1.gitEntryAbove)(root))
139
+ provenance.at = 'unknown';
140
+ // Round 17: a directory the scan skipped because git could not answer for it leaves the tree's content unknown.
141
+ if (dirty === 'unknown' || (0, cpg_scanner_1.unverifiedUnder)(root).length > 0) {
142
+ if (!provenance.at.endsWith(exports.ATTEST_UNKNOWN) && provenance.at !== 'unknown')
143
+ provenance.at += exports.ATTEST_UNKNOWN;
144
+ }
104
145
  return {
105
146
  files: (0, traced_files_1.tracedFiles)({ files, approvedIds: approved.map((s) => s.id), exclude }),
106
147
  specs: { total: census.total, linked: census.codeLinked },
107
- provenance: (0, traced_files_1.attestProvenance)({
108
- commit,
109
- dirty: commit ? decidingPathsDirty(root, new Set(files.map((f) => f.path))) : false,
110
- approved: approved.map((s) => ({ id: s.id, digest: String(s.frontmatter.approved_digest ?? '') })),
111
- exclude,
112
- }),
148
+ provenance,
113
149
  };
114
150
  }
115
151
  async function runAttest(o, io) {
@@ -118,6 +154,21 @@ async function runAttest(o, io) {
118
154
  return 2;
119
155
  }
120
156
  const report = await buildAttestReport(o.root, o.exclude);
157
+ if (report.provenance.at.endsWith(exports.ATTEST_UNKNOWN))
158
+ io.stderr('attest: the working-tree status did not answer, so whether the tree matches the commit is unknown (+unknown)\n');
159
+ // @implements A-SPEC-734 (round 17) — directories whose nesting git could not answer were not counted; named.
160
+ const skipped = (0, cpg_scanner_1.unverifiedUnder)(o.root);
161
+ if (skipped.length > 0) {
162
+ let real = o.root;
163
+ try {
164
+ real = fs.realpathSync.native(o.root);
165
+ }
166
+ catch { /* as given */ }
167
+ const shown = skipped.slice(0, 5).map((d) => path.relative(real, d).split(path.sep).join('/'));
168
+ io.stderr(`attest: ${skipped.length} director${skipped.length === 1 ? 'y' : 'ies'} holding .git could not be verified with git and ${skipped.length === 1 ? 'was' : 'were'} not counted (${shown.join(', ')}${skipped.length > 5 ? ', …' : ''}) — the tree's content is unknown (+unknown)\n`);
169
+ }
170
+ if (report.provenance.at === 'unknown')
171
+ io.stderr('attest: git refused to read this repository, so the commit is unknown\n');
121
172
  io.stdout(o.json ? (0, traced_files_1.renderAttestJson)(report) : (0, traced_files_1.renderAttestText)(report));
122
173
  let code = 0;
123
174
  const note = (s) => { if (!o.json)
@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.runCiGate = runCiGate;
37
37
  // @implements A-SPEC-213
38
+ // @implements A-SPEC-734
38
39
  const fs = __importStar(require("node:fs"));
39
40
  const path = __importStar(require("node:path"));
40
41
  const cpg_scanner_1 = require("../cpg/cpg-scanner");
@@ -67,8 +68,22 @@ function runCiGate(targetDir, options) {
67
68
  }
68
69
  const ignore = (0, ignore_1.loadIgnore)(root);
69
70
  const scanner = new cpg_scanner_1.CpgScanner();
71
+ (0, cpg_scanner_1.forgetUnverifiedUnder)(root);
70
72
  const scannedFiles = scanner.scan(root, root);
73
+ // @implements A-SPEC-734 (round 17) — directories holding `.git` whose nesting git could not answer are skipped by
74
+ // the scan, so their code was not judged: the gate fails and names them (round 15 read 100% — measured; round 16
75
+ // walked them and judged a registered worktree's files as this project's — measured).
76
+ const skipped = (0, cpg_scanner_1.unverifiedUnder)(root);
77
+ let realRoot = root;
78
+ try {
79
+ realRoot = fs.realpathSync.native(root);
80
+ }
81
+ catch { /* as given */ }
82
+ const shown = skipped.slice(0, 5).map((d) => path.relative(realRoot, d).split(path.sep).join('/'));
83
+ const unverified = skipped.length === 0 ? '' : ` (${skipped.length} director${skipped.length === 1 ? 'y' : 'ies'} holding .git could not be verified with git and ${skipped.length === 1 ? 'was' : 'were'} not judged: ${shown.join(', ')}${skipped.length > 5 ? ', …' : ''})`;
71
84
  const violations = [];
85
+ for (const d of shown)
86
+ violations.push({ file: d, reason: 'Not judged — a directory holding .git whose nesting git could not answer (fix git access to the repository and run again)' });
72
87
  for (const sf of scannedFiles) {
73
88
  const rel = path.relative(root, sf.path).split(path.sep).join('/');
74
89
  if (ignore.isIgnored(rel))
@@ -94,7 +109,7 @@ function runCiGate(targetDir, options) {
94
109
  return {
95
110
  ok: false,
96
111
  violations,
97
- summary: `[Holmes-Kit CI Gate Refusal] Governance Violations Detected — ${violations.length} un-anchored file(s) or invalid spec anchors found in PR commit range.`,
112
+ summary: `[Holmes-Kit CI Gate Refusal] Governance Violations Detected — ${violations.length - shown.length} un-anchored file(s) or invalid spec anchors found in PR commit range.${unverified}`,
98
113
  };
99
114
  }
100
115
  return {
@@ -0,0 +1,95 @@
1
+ import type { Check } from './doctor-check';
2
+ export interface ClaudeSwitchEnv {
3
+ home: string;
4
+ /** `$CLAUDE_CONFIG_DIR`: where Claude reads the user's settings instead of `~/.claude`. */
5
+ claudeConfigDir?: string;
6
+ /** Directories holding `managed-settings.json` and `managed-settings.d/*.json`. */
7
+ managedDirs: string[];
8
+ /** Round 42: `$CLAUDE_CODE_CUSTOM_OAUTH_URL` is set — Claude's global config is then `.claude-custom-oauth.json`. */
9
+ customOauth?: boolean;
10
+ /** Round 43: `$CLAUDE_CONFIG_DIR` exactly as set (empty and whitespace included) — Claude computes the global config from it. */
11
+ rawConfigDir?: string;
12
+ }
13
+ /** The managed-settings folders Claude Code reads on each platform. */
14
+ export declare function managedSettingsDirs(platform?: NodeJS.Platform): string[];
15
+ export declare function claudeSwitchEnv(): ClaudeSwitchEnv;
16
+ /** Claude's user settings file: `$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`. */
17
+ export declare function claudeUserSettingsPath(env: ClaudeSwitchEnv): string | null;
18
+ /**
19
+ * @implements A-SPEC-251.2 (round 35) — the largest settings file Claude Code 2.1.281 reads (`size > maxBytes` is
20
+ * ERR_FILE_TOO_LARGE, and the file applies nothing): a 3 MiB file holding Holmes's hooks read PASS and "enforced" (measured).
21
+ */
22
+ export declare const CLAUDE_SETTINGS_MAX_BYTES: number;
23
+ /** The first `max` bytes of a regular file as text (a `.git` file, `commondir`, `gitdir`), or null. Never blocks on a FIFO. */
24
+ export declare function readFileHead(file: string, max?: number): string | null;
25
+ /**
26
+ * @implements A-SPEC-251.2 (round 35) — a path resolved one component at a time as the kernel resolves a command (`..` from
27
+ * the real path so far), never looking up a network or device path (`/net/<host>`, `//host`, `\\host`): Claude's and
28
+ * Antigravity's wirings reached `realpath` on an automounter path (code reading, lookups intercepted — measured).
29
+ */
30
+ export declare function localPhysicalRealpath(p: string, budget?: {
31
+ left: number;
32
+ }): {
33
+ path: string | null;
34
+ refused: boolean;
35
+ exhausted?: true;
36
+ };
37
+ export declare function isClaudeEvent(name: string): boolean;
38
+ /**
39
+ * @implements A-SPEC-251.2 (round 35) — where Claude 2.1.281 also reads local settings (`lU`, `pOo`, `Bme`): the canonical git
40
+ * root — the nearest `.git` directory's checkout, or a `.git` file's main checkout (its `commondir` named `.git`) — when it is
41
+ * neither the target nor the home directory and, on POSIX, it, its `.git` and its `.claude` (if any) belong to this user. A
42
+ * root's `disableAllHooks` read PASS from a monorepo package and a linked worktree (measured). Network paths are not followed.
43
+ */
44
+ export declare function canonicalLocalSettingsPath(target: string, home: string): string | null;
45
+ /**
46
+ * Why Claude Code applies NOTHING from this settings file, or null.
47
+ *
48
+ * @implements A-SPEC-251.2 (round 34) — Claude 2.1.281's loader (`Pf`, `Tf`, `zt`, `gc`) transcribed: a PreToolUse/
49
+ * PermissionRequest hook it cannot load, or one declared outside `hooks`, makes it apply nothing in the file ("nothing it
50
+ * sits in is applied"). Round 33 read a few shapes and PASSed 24 others (`timeout: 0`, `matcher: null`, a top-level
51
+ * `"PreToolUse"` — measured); it also refused files Claude loads (a `"matcher"` key beside the events). What Claude only warns
52
+ * about and drops (an unknown event, another event's bad group) does not drop the file. The rest of Claude's settings schema
53
+ * (which can also drop a file) is not read.
54
+ */
55
+ export declare function claudeDropsFile(raw: unknown): string | null;
56
+ /**
57
+ * @implements A-SPEC-251.2 (round 42) — a script path that does not depend on the directory the harness runs its hook in:
58
+ * POSIX `/…`, Windows `X:\…` or UNC. Claude runs a command hook in the session's current directory, so a relative gate script
59
+ * failed with "Cannot find module" (exit 1, non-blocking) after one `cd src` while doctor read PASS (measured).
60
+ */
61
+ export declare function isAbsoluteScript(p: string): boolean;
62
+ /**
63
+ * @implements A-SPEC-251.2 (round 43) — a string from a file, safe to print: control characters are escaped (an `env` key holding
64
+ * ESC and BEL retitled the terminal and cleared the screen through doctor and init — measured).
65
+ */
66
+ export declare function printable(s: string): string;
67
+ export interface ClaudeSwitches {
68
+ /** Files (with the setting) that switch every hook off here — the Holmes gate included. */
69
+ hooksOff: string[];
70
+ /** Files (with the setting) that reject or deny Holmes's MCP tools. */
71
+ toolsOff: string[];
72
+ /** Files that exist but could not be read as settings. */
73
+ unreadable: string[];
74
+ /** Files Claude applies nothing from (an unloadable guard entry) that do not hold Holmes's hooks. */
75
+ notApplied: string[];
76
+ /** Why the gate is not confirmed to block (round 39: a gate entry of another shape than init's, or a shell prefix). */
77
+ unconfirmed: string[];
78
+ /** Round 40: switches that turn off every non-managed hook while a managed gate still runs (WARN, not FAIL). */
79
+ spared: string[];
80
+ /** Round 40: the scripts the canonical gate entries run (for a caller that knows which install is this one). */
81
+ gateScripts: string[];
82
+ /** Round 40: files wiring Holmes's other hooks with no Holmes PreToolUse gate anywhere Claude applies. */
83
+ noGate: string[];
84
+ }
85
+ /**
86
+ * @implements A-SPEC-251.2 (round 50) — `planned`: settings files by path with the content init is about to write, judged in
87
+ * place of what is on disk (a first init said "enforced" over an entry doctor and the next init called not confirmed).
88
+ */
89
+ export declare function claudeSwitches(target: string, env?: ClaudeSwitchEnv, planned?: ReadonlyMap<string, string>): ClaudeSwitches;
90
+ /**
91
+ * `script` is which install a canonical gate entry's script belongs to: this one, another existing one, or none (a missing
92
+ * file). Given by doctor, which knows this install; absent, the scripts are not judged.
93
+ */
94
+ export type GateScriptOwner = (script: string) => 'this' | 'other' | 'missing' | 'unknown';
95
+ export declare function claudeHookSwitchesCheck(target: string, env?: ClaudeSwitchEnv, owner?: GateScriptOwner): Check;