@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.
- package/CHANGELOG.md +363 -0
- package/README.md +4 -2
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/approve-status.js +4 -1
- package/dist/holmes/cli/approve-watch.js +3 -1
- package/dist/holmes/cli/approve.d.ts +10 -0
- package/dist/holmes/cli/approve.js +34 -4
- package/dist/holmes/cli/claude-switches.d.ts +7 -1
- package/dist/holmes/cli/claude-switches.js +11 -7
- package/dist/holmes/cli/codex-toml.d.ts +3 -0
- package/dist/holmes/cli/codex-toml.js +2 -1
- package/dist/holmes/cli/doctor.d.ts +31 -1
- package/dist/holmes/cli/doctor.js +204 -7
- package/dist/holmes/cli/index.js +115 -4
- package/dist/holmes/cli/init.js +4 -3
- package/dist/holmes/cli/os-notify.d.ts +3 -1
- package/dist/holmes/cli/os-notify.js +10 -4
- package/dist/holmes/cli/review.d.ts +25 -0
- package/dist/holmes/cli/review.js +111 -0
- package/dist/holmes/cli/roles-readme.d.ts +11 -0
- package/dist/holmes/cli/roles-readme.js +38 -16
- package/dist/holmes/cli/roles.d.ts +12 -0
- package/dist/holmes/cli/roles.js +86 -0
- package/dist/holmes/cli/run.d.ts +65 -0
- package/dist/holmes/cli/run.js +308 -0
- package/dist/holmes/cli/runtime-binding-approval.js +3 -2
- package/dist/holmes/cli/runtime-binding.d.ts +30 -0
- package/dist/holmes/cli/runtime-binding.js +116 -11
- package/dist/holmes/cli/scratch.d.ts +12 -0
- package/dist/holmes/cli/scratch.js +20 -0
- package/dist/holmes/cli/test-platform.d.ts +16 -0
- package/dist/holmes/cli/test-platform.js +31 -1
- package/dist/holmes/config/config.d.ts +49 -0
- package/dist/holmes/config/config.js +146 -3
- package/dist/holmes/config/project-caps.d.ts +21 -0
- package/dist/holmes/config/project-caps.js +114 -0
- package/dist/holmes/governance/approval-queue.d.ts +17 -3
- package/dist/holmes/governance/approval-queue.js +51 -8
- package/dist/holmes/governance/autonomy.d.ts +6 -0
- package/dist/holmes/governance/autonomy.js +21 -0
- package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
- package/dist/holmes/governance/push-gate-runner.js +49 -1
- package/dist/holmes/governance/replica-id.d.ts +9 -0
- package/dist/holmes/governance/replica-id.js +44 -7
- package/dist/holmes/governance/role-policy.d.ts +41 -1
- package/dist/holmes/governance/role-policy.js +137 -20
- package/dist/holmes/governance/run-mode.d.ts +14 -0
- package/dist/holmes/governance/run-mode.js +120 -0
- package/dist/holmes/governance/tool-actions.d.ts +30 -0
- package/dist/holmes/governance/tool-actions.js +121 -0
- package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
- package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
- package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
- package/dist/holmes/guardrail/classification-mode.js +135 -0
- package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
- package/dist/holmes/guardrail/dynamic-write.js +304 -0
- package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
- package/dist/holmes/guardrail/impact-gate.js +34 -11
- package/dist/holmes/guardrail/phase.d.ts +2 -1
- package/dist/holmes/guardrail/phase.js +22 -8
- package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
- package/dist/holmes/guardrail/powershell-shell.js +801 -0
- package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
- package/dist/holmes/guardrail/refusal-codes.js +140 -0
- package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
- package/dist/holmes/guardrail/risk-classifier.js +255 -27
- package/dist/holmes/guardrail/risk-types.d.ts +16 -0
- package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
- package/dist/holmes/guardrail/run-plan-scope.js +155 -0
- package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
- package/dist/holmes/guardrail/run-refusals.js +348 -0
- package/dist/holmes/guardrail/run-stages.d.ts +67 -0
- package/dist/holmes/guardrail/run-stages.js +188 -0
- package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
- package/dist/holmes/guardrail/scope-judgment.js +8 -10
- package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
- package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
- package/dist/holmes/guardrail/shell-words.js +7 -7
- package/dist/holmes/guardrail/write-target.d.ts +31 -2
- package/dist/holmes/guardrail/write-target.js +118 -16
- package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
- package/dist/holmes/hooks/pre-tool-use.js +740 -81
- package/dist/holmes/hooks/session-start.js +5 -3
- package/dist/holmes/hooks/stop.d.ts +35 -1
- package/dist/holmes/hooks/stop.js +142 -7
- package/dist/holmes/mcp/elicit-approval.js +4 -4
- package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
- package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
- package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
- package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
- package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
- package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
- package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
- package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
- package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
- package/dist/holmes/mcp/handlers.d.ts +2 -3
- package/dist/holmes/mcp/handlers.js +22 -2
- package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
- package/dist/holmes/mcp/harness-attestation.js +3 -1
- package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
- package/dist/holmes/mcp/operator-recovery.js +4 -3
- package/dist/holmes/mcp/server.js +9 -0
- package/dist/holmes/mcp/tool-schemas.js +6 -3
- package/dist/holmes/project/npx-bin.d.ts +26 -0
- package/dist/holmes/project/npx-bin.js +272 -2
- package/dist/holmes/project/root.js +6 -1
- package/dist/holmes/project/run-records.d.ts +17 -0
- package/dist/holmes/project/run-records.js +126 -0
- package/dist/holmes/project/scratch-root.d.ts +12 -0
- package/dist/holmes/project/scratch-root.js +132 -0
- package/dist/holmes/review/mrp.d.ts +35 -0
- package/dist/holmes/review/mrp.js +119 -0
- package/dist/holmes/review/verdicts.d.ts +117 -0
- package/dist/holmes/review/verdicts.js +345 -0
- package/dist/holmes/runtime/dispatch.js +6 -3
- package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
- package/dist/holmes/semantic/cloud-usage.js +106 -0
- package/dist/holmes/semantic/embedder.d.ts +15 -6
- package/dist/holmes/semantic/embedder.js +84 -3
- package/dist/holmes/semantic/local-model.d.ts +21 -2
- package/dist/holmes/semantic/local-model.js +14 -3
- package/dist/holmes/semantic/tier.d.ts +25 -0
- package/dist/holmes/semantic/tier.js +86 -1
- package/dist/holmes/semantic/vector-cache.d.ts +1 -0
- package/dist/holmes/semantic/vector-cache.js +4 -1
- package/dist/holmes/spec/approval-blockers.d.ts +11 -1
- package/dist/holmes/spec/approval-blockers.js +70 -2
- package/dist/holmes/spec/renumber.d.ts +1 -1
- package/dist/holmes/spec/renumber.js +5 -2
- package/dist/holmes/spec/transition-policy.d.ts +5 -7
- package/dist/holmes/spec/transition-policy.js +17 -2
- package/package.json +1 -1
|
@@ -40,6 +40,7 @@ exports.readCodexConfigBytes = readCodexConfigBytes;
|
|
|
40
40
|
exports.codexConfigLoadProblem = codexConfigLoadProblem;
|
|
41
41
|
exports.codexConfigWriteProblem = codexConfigWriteProblem;
|
|
42
42
|
exports.defaultCodexConfigPath = defaultCodexConfigPath;
|
|
43
|
+
exports.tomlStr = tomlStr;
|
|
43
44
|
exports.codexMcpBlock = codexMcpBlock;
|
|
44
45
|
exports.mergeCodexToml = mergeCodexToml;
|
|
45
46
|
exports.removeCodexToml = removeCodexToml;
|
|
@@ -49,7 +50,7 @@ exports.mentionsHolmes = mentionsHolmes;
|
|
|
49
50
|
exports.unownedHolmesShape = unownedHolmesShape;
|
|
50
51
|
exports.readCodexFixedSpecs = readCodexFixedSpecs;
|
|
51
52
|
exports.invalidTomlEscape = invalidTomlEscape;
|
|
52
|
-
// @implements A-SPEC-733, A-SPEC-731, A-SPEC-721
|
|
53
|
+
// @implements A-SPEC-733, A-SPEC-731, A-SPEC-721, A-SPEC-769.22
|
|
53
54
|
// @implements A-SPEC-266
|
|
54
55
|
// Codex reads default MCP servers from `$CODEX_HOME/config.toml` (normally
|
|
55
56
|
// `~/.codex/config.toml`), not from a repository-local `.codex/config.toml`. This module owns only
|
|
@@ -210,6 +210,17 @@ export declare function wiringSpawnCheck(command: string, args: string[], timeou
|
|
|
210
210
|
* over as it was, the server's supervisor (`HOLMES_MCP_AUTORELOAD=1`) started the `node` the workspace had put on PATH.
|
|
211
211
|
*/
|
|
212
212
|
export declare function mcpProbeEnv(env: NodeJS.ProcessEnv, target: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
|
|
213
|
+
/**
|
|
214
|
+
* @implements A-SPEC-182.3 — approved specs whose ancestor chain (direct parents included) holds a spec that is not
|
|
215
|
+
* approved: a WARN with the count and the ancestors that hold most of them, or null on a clean store. Measured here on
|
|
216
|
+
* 2026-10-18: 28 (REQ-102 13, REQ-125 11, H-SPEC-100 4).
|
|
217
|
+
*/
|
|
218
|
+
export declare function sealedUnderUnsealedAncestorCheck(target: string): Check | null;
|
|
219
|
+
/**
|
|
220
|
+
* @implements A-SPEC-781.2 — how the run stage machine in `ax.config.json` was read: a WARN naming the fallback or the
|
|
221
|
+
* deny entries filled in, or null when it was read as written (no line, so a clean project's doctor is unchanged).
|
|
222
|
+
*/
|
|
223
|
+
export declare function stageMachineCheck(target: string): Check | null;
|
|
213
224
|
/**
|
|
214
225
|
* Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
|
|
215
226
|
* AND has git. Absence or a hook without our signature is a WARN carrying the install command —
|
|
@@ -255,6 +266,12 @@ export type CodexGateReading = {
|
|
|
255
266
|
* beside a Codex-only report read as Codex's activation.
|
|
256
267
|
*/
|
|
257
268
|
export declare function activationText(observed: string[], agent?: string): string;
|
|
269
|
+
/**
|
|
270
|
+
* @implements A-SPEC-770.3 — the nearest ancestor node_modules copy of holmes-kit, which the bare npx command run from the
|
|
271
|
+
* target (or below) resolves before any global install. Field incident 2026-10-17: ~/node_modules held 0.19.3 and a
|
|
272
|
+
* 0.35.23 refusal's own grant hint answered "no pending request matches". No copy: no row.
|
|
273
|
+
*/
|
|
274
|
+
export declare function npxResolutionCheck(target: string, runningVersion: string): Check | null;
|
|
258
275
|
export declare function hookObservationChecks(targetIn: string, now?: number, agent?: Agent): Check[];
|
|
259
276
|
/**
|
|
260
277
|
* Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate: Codex sessions end without the constitution
|
|
@@ -300,6 +317,15 @@ export declare function formatChecks(checks: Check[]): string;
|
|
|
300
317
|
* target is told that the shared file lacks a Holmes entry.
|
|
301
318
|
*/
|
|
302
319
|
export declare function codexWiredTarget(target: string): boolean;
|
|
320
|
+
/** The Holmes wirings of the three harnesses, read the way the handshake reads them (nothing is started). */
|
|
321
|
+
export declare function holmesWirings(target: string, codexConfigPath: string): Array<{
|
|
322
|
+
label: string;
|
|
323
|
+
file: string;
|
|
324
|
+
entry: {
|
|
325
|
+
command: string;
|
|
326
|
+
args: string[];
|
|
327
|
+
} | null;
|
|
328
|
+
}>;
|
|
303
329
|
/**
|
|
304
330
|
* @implements A-SPEC-251.2 (0.31.0) — each harness whose Holmes wiring runs npx gets a WARN: npx runs npm in every
|
|
305
331
|
* session workspace, and that workspace's .npmrc (node-options, registry) and node_modules replaced the server
|
|
@@ -367,8 +393,12 @@ export declare function wiringHandshakeChecks(target: string, codexConfigPath?:
|
|
|
367
393
|
* user decides the trade with numbers rather than adjectives.
|
|
368
394
|
*/
|
|
369
395
|
export declare function semanticCoverageCheck(root: string, tier: SemanticTier): Check | null;
|
|
396
|
+
/**
|
|
397
|
+
* @implements A-SPEC-476.1 — the tier row names the project's cap: a key it withheld (by source, never the value) and the
|
|
398
|
+
* cap that applied; a cap that could not be read is FAIL, because the tier is none until it is fixed.
|
|
399
|
+
*/
|
|
370
400
|
export declare function semanticTierVerdict(t: SemanticTier): {
|
|
371
|
-
level: 'PASS' | 'WARN';
|
|
401
|
+
level: 'PASS' | 'WARN' | 'FAIL';
|
|
372
402
|
detail: string;
|
|
373
403
|
fix?: string;
|
|
374
404
|
};
|
|
@@ -51,15 +51,19 @@ exports.resetWiringSpawns = resetWiringSpawns;
|
|
|
51
51
|
exports.wiringSpawnShared = wiringSpawnShared;
|
|
52
52
|
exports.wiringSpawnCheck = wiringSpawnCheck;
|
|
53
53
|
exports.mcpProbeEnv = mcpProbeEnv;
|
|
54
|
+
exports.sealedUnderUnsealedAncestorCheck = sealedUnderUnsealedAncestorCheck;
|
|
55
|
+
exports.stageMachineCheck = stageMachineCheck;
|
|
54
56
|
exports.pushGateCheck = pushGateCheck;
|
|
55
57
|
exports.stopHookTimeoutCheck = stopHookTimeoutCheck;
|
|
56
58
|
exports.activationText = activationText;
|
|
59
|
+
exports.npxResolutionCheck = npxResolutionCheck;
|
|
57
60
|
exports.hookObservationChecks = hookObservationChecks;
|
|
58
61
|
exports.codexStopGateCheck = codexStopGateCheck;
|
|
59
62
|
exports.ciMatrixCheck = ciMatrixCheck;
|
|
60
63
|
exports.checksJson = checksJson;
|
|
61
64
|
exports.formatChecks = formatChecks;
|
|
62
65
|
exports.codexWiredTarget = codexWiredTarget;
|
|
66
|
+
exports.holmesWirings = holmesWirings;
|
|
63
67
|
exports.wiringLauncherChecks = wiringLauncherChecks;
|
|
64
68
|
exports.wiringVersionChecks = wiringVersionChecks;
|
|
65
69
|
exports.harnessClause = harnessClause;
|
|
@@ -71,7 +75,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
|
|
|
71
75
|
exports.semanticCoverageCheck = semanticCoverageCheck;
|
|
72
76
|
exports.semanticTierVerdict = semanticTierVerdict;
|
|
73
77
|
exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
|
|
74
|
-
// @implements A-SPEC-751.4, A-SPEC-
|
|
78
|
+
// @implements A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
|
|
75
79
|
// @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18, A-SPEC-769.19, A-SPEC-769.20, A-SPEC-769.21
|
|
76
80
|
const doctor_guidance_1 = require("./doctor-guidance");
|
|
77
81
|
// @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
|
|
@@ -87,11 +91,13 @@ const npx_bin_1 = require("../project/npx-bin");
|
|
|
87
91
|
const install_scripts_policy_1 = require("../project/install-scripts-policy");
|
|
88
92
|
const native_deps_1 = require("./native-deps");
|
|
89
93
|
const tier_1 = require("../semantic/tier");
|
|
94
|
+
const cloud_usage_1 = require("../semantic/cloud-usage");
|
|
90
95
|
const probe_process_1 = require("./probe-process");
|
|
91
96
|
const npx_cache_check_1 = require("./npx-cache-check");
|
|
92
97
|
const ci_runs_1 = require("../project/ci-runs");
|
|
93
98
|
const vector_coverage_1 = require("../semantic/vector-coverage");
|
|
94
99
|
const path = __importStar(require("node:path"));
|
|
100
|
+
const config_1 = require("../config/config");
|
|
95
101
|
const role_policy_1 = require("../governance/role-policy");
|
|
96
102
|
const blind_spots_1 = require("../guardrail/blind-spots");
|
|
97
103
|
const node_child_process_1 = require("node:child_process");
|
|
@@ -908,6 +914,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
908
914
|
checks.push(...wiringVersionChecks(target, opts?.codexConfigPath, cli));
|
|
909
915
|
}
|
|
910
916
|
}
|
|
917
|
+
// @implements A-SPEC-770.3 — the copy the bare npx command would run from the target, when it is not this install.
|
|
918
|
+
{
|
|
919
|
+
const cli = (0, mcp_launcher_1.readPackageVersion)(packageRoot);
|
|
920
|
+
const row = cli ? npxResolutionCheck(target ?? process.cwd(), cli) : null;
|
|
921
|
+
if (row)
|
|
922
|
+
checks.push(row);
|
|
923
|
+
}
|
|
911
924
|
// 7. Target wiring — do the configured commands point at THIS installed package and exist?
|
|
912
925
|
if (target) {
|
|
913
926
|
// @implements A-SPEC-190 §13 (round 11) — `init --settings project` wires `.claude/settings.json`,
|
|
@@ -1169,9 +1182,40 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
1169
1182
|
// operators that doctor's failures are noise, which costs more than this check is worth.
|
|
1170
1183
|
if (target) {
|
|
1171
1184
|
const rs = (0, role_policy_1.rolePolicyStatus)(target);
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1185
|
+
// @implements A-SPEC-774.8 — a broad default is refused in a run; interactively it is a warning with the migration.
|
|
1186
|
+
// @implements A-SPEC-774.15 — an unreadable policy refuses every action; a role defined twice is refused in a run.
|
|
1187
|
+
if (rs.loadIssue)
|
|
1188
|
+
add('role policy', 'WARN', `${rs.loadIssue}. Every role-checked action is refused until it can be read.`);
|
|
1189
|
+
else if (rs.duplicates?.length)
|
|
1190
|
+
add('role policy', 'WARN', `role(s) defined in more than one file under .ax/roles: ${rs.duplicates.join(', ')}. The later definition holds interactively; an orchestrated run refuses them. Define each role once.`);
|
|
1191
|
+
else if (rs.defaultIssue)
|
|
1192
|
+
add('role policy', 'WARN', `${rs.defaultIssue}. In an orchestrated run this policy is refused; interactive sessions are unaffected.`);
|
|
1193
|
+
// @implements A-SPEC-774.22 — a stages declaration that cannot be read: ignored interactively, refused in a run.
|
|
1194
|
+
else if (rs.malformedStages?.length)
|
|
1195
|
+
add('role policy', 'WARN', `role(s) whose stages cannot be read: ${rs.malformedStages.join(', ')} — interactive sessions ignore them; an orchestrated run refuses them in every stage. Write stages as a list of stage names.`);
|
|
1196
|
+
else
|
|
1197
|
+
add('role policy', 'PASS', rs.state === 'absent' ? 'not configured (optional)'
|
|
1198
|
+
: rs.state === 'inactive' ? 'guidance present, no policy — roles are off (see .ax/roles/README.md)'
|
|
1199
|
+
: `active — ${rs.roles.length} role(s): ${rs.roles.join(', ')}; default=${rs.default ?? '(none — unspecified is refused)'}`);
|
|
1200
|
+
// @implements A-SPEC-781.2 — a stage machine not read as written is named, never replaced silently.
|
|
1201
|
+
const sm = stageMachineCheck(target);
|
|
1202
|
+
if (sm)
|
|
1203
|
+
checks.push(sm);
|
|
1204
|
+
}
|
|
1205
|
+
// @implements A-SPEC-532.6 — the owner's ceiling on automatic approval; a value the loader could not read is `off`.
|
|
1206
|
+
if (target) {
|
|
1207
|
+
let raw;
|
|
1208
|
+
try {
|
|
1209
|
+
raw = JSON.parse(fs.readFileSync(path.join(target, 'ax.config.json'), 'utf8')).autonomy?.ceiling;
|
|
1210
|
+
}
|
|
1211
|
+
catch {
|
|
1212
|
+
raw = undefined;
|
|
1213
|
+
}
|
|
1214
|
+
const ceiling = (0, config_1.loadConfig)(target).autonomy.ceiling;
|
|
1215
|
+
if (raw !== undefined && raw !== ceiling)
|
|
1216
|
+
add('autonomy ceiling', 'WARN', `ax.config.json autonomy.ceiling ${JSON.stringify(raw)} is not one of off, tests, no-gate, default — read as "off": no seal is automatic until it is corrected`);
|
|
1217
|
+
else
|
|
1218
|
+
add('autonomy ceiling', 'PASS', ceiling === 'default' ? 'default — the grader decides which seals are automatic' : `"${ceiling}" — automatic seals above it are the operator's`);
|
|
1175
1219
|
}
|
|
1176
1220
|
// @implements A-SPEC-165
|
|
1177
1221
|
// The boundary, told to the user rather than left in a document nobody opens. PASS, not FAIL: a
|
|
@@ -1206,6 +1250,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
1206
1250
|
: `${orphaned.length} approved spec(s) with a non-approved parent: ${orphaned.map((s) => s.id).slice(0, 5).join(', ')}`);
|
|
1207
1251
|
}
|
|
1208
1252
|
catch { /* an unreadable corpus is doctor's other checks' business, not this one's */ }
|
|
1253
|
+
// @implements A-SPEC-182.3 — the whole chain, not only the direct parents: named, never silent.
|
|
1254
|
+
try {
|
|
1255
|
+
const anc = sealedUnderUnsealedAncestorCheck(target);
|
|
1256
|
+
if (anc)
|
|
1257
|
+
checks.push(anc);
|
|
1258
|
+
}
|
|
1259
|
+
catch { /* as above */ }
|
|
1209
1260
|
// @implements A-SPEC-254.1
|
|
1210
1261
|
// Distributed id preemption (the 2026-08-23 REQ-220 incident): two offline workspaces issue the
|
|
1211
1262
|
// same number, silent at create and at push. Judgment lives in the ONE pure detector; identity is
|
|
@@ -1701,13 +1752,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
1701
1752
|
issues.push(`${file}: hooks are disabled`);
|
|
1702
1753
|
for (const g of ours.PreToolUse ?? [])
|
|
1703
1754
|
for (const hook of g.hooks ?? []) {
|
|
1704
|
-
if (hook.command
|
|
1755
|
+
if ((0, runtime_binding_1.sameAgyCommand)(hook.command, routed.command('antigravity', 'pre-tool-use'))) { // A-SPEC-751.9
|
|
1705
1756
|
pres++;
|
|
1706
1757
|
if (g.matcher !== '*')
|
|
1707
1758
|
issues.push(`${file}: PreToolUse matcher must be *`);
|
|
1708
1759
|
}
|
|
1709
1760
|
}
|
|
1710
|
-
stops += (ours.Stop ?? []).filter((h2) => h2.command
|
|
1761
|
+
stops += (ours.Stop ?? []).filter((h2) => (0, runtime_binding_1.sameAgyCommand)(h2.command, routed.command('antigravity', 'stop'))).length; // A-SPEC-751.9
|
|
1711
1762
|
}
|
|
1712
1763
|
if (pres !== 1 || (stops !== 1 && !(emptyStop && stops === 0)))
|
|
1713
1764
|
issues.push('expected exactly one registered PreToolUse and Stop across Antigravity sources');
|
|
@@ -2335,9 +2386,11 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
2335
2386
|
add('global prefix', verdict.level, verdict.detail, verdict.fix);
|
|
2336
2387
|
}
|
|
2337
2388
|
{
|
|
2338
|
-
const t = (0, tier_1.
|
|
2389
|
+
const t = (0, tier_1.resolveProjectSemanticTier)(target ?? process.cwd()); // @implements A-SPEC-476.1
|
|
2339
2390
|
const v = semanticTierVerdict(t);
|
|
2340
2391
|
add('semantic tier', v.level, v.detail, v.fix);
|
|
2392
|
+
// @implements A-SPEC-476.5 — what this project actually sent to the cloud embedder, by day (every tier, so a cap shows 0).
|
|
2393
|
+
add('cloud embedding usage', 'PASS', (0, cloud_usage_1.cloudUsageLine)((0, cloud_usage_1.cloudUsageSummary)(target ?? process.cwd())));
|
|
2341
2394
|
// @implements A-SPEC-682 — the tier line says what is CONFIGURED. Measured 2026-09-19 on this
|
|
2342
2395
|
// repository, the configured tier was cloud while 0 of 602 scanned files had a cached document
|
|
2343
2396
|
// vector under it, so every lookup returned nothing and both semantic surfaces were inert —
|
|
@@ -2683,6 +2736,85 @@ function mcpHandshakeCheck(packageRoot, target, timeoutMs = 15000) {
|
|
|
2683
2736
|
send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'holmes-doctor', version: '1' } } });
|
|
2684
2737
|
});
|
|
2685
2738
|
}
|
|
2739
|
+
/**
|
|
2740
|
+
* @implements A-SPEC-182.3 — approved specs whose ancestor chain (direct parents included) holds a spec that is not
|
|
2741
|
+
* approved: a WARN with the count and the ancestors that hold most of them, or null on a clean store. Measured here on
|
|
2742
|
+
* 2026-10-18: 28 (REQ-102 13, REQ-125 11, H-SPEC-100 4).
|
|
2743
|
+
*/
|
|
2744
|
+
function sealedUnderUnsealedAncestorCheck(target) {
|
|
2745
|
+
const { parseSpec } = require('../spec/spec-parser');
|
|
2746
|
+
const byId = new Map();
|
|
2747
|
+
const walk = (dir, depth) => {
|
|
2748
|
+
if (depth > 6)
|
|
2749
|
+
return;
|
|
2750
|
+
let entries;
|
|
2751
|
+
try {
|
|
2752
|
+
entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
2753
|
+
}
|
|
2754
|
+
catch {
|
|
2755
|
+
return;
|
|
2756
|
+
}
|
|
2757
|
+
for (const e of entries) {
|
|
2758
|
+
const p = path.join(dir, e.name);
|
|
2759
|
+
if (e.isDirectory())
|
|
2760
|
+
walk(p, depth + 1);
|
|
2761
|
+
else if (e.isFile() && e.name.endsWith('.md')) {
|
|
2762
|
+
try {
|
|
2763
|
+
const s = parseSpec(fs.readFileSync(p, 'utf8'));
|
|
2764
|
+
if (s.id)
|
|
2765
|
+
byId.set(s.id, s);
|
|
2766
|
+
}
|
|
2767
|
+
catch { /* unreadable: other checks */ }
|
|
2768
|
+
}
|
|
2769
|
+
}
|
|
2770
|
+
};
|
|
2771
|
+
walk(path.join(target, '.ax', 'specs'), 0);
|
|
2772
|
+
const holders = new Map();
|
|
2773
|
+
let count = 0;
|
|
2774
|
+
for (const s of byId.values()) {
|
|
2775
|
+
if (s.status !== 'approved')
|
|
2776
|
+
continue;
|
|
2777
|
+
const bad = new Set();
|
|
2778
|
+
const seen = new Set([s.id]);
|
|
2779
|
+
const up = (id, depth) => {
|
|
2780
|
+
if (depth > 16 || seen.has(id))
|
|
2781
|
+
return;
|
|
2782
|
+
seen.add(id);
|
|
2783
|
+
const a = byId.get(id);
|
|
2784
|
+
// @implements A-SPEC-182.4 — an ancestor no spec carries holds the chain up as an unapproved one does.
|
|
2785
|
+
if (!a) {
|
|
2786
|
+
bad.add(`${id} (missing)`);
|
|
2787
|
+
return;
|
|
2788
|
+
}
|
|
2789
|
+
if (a.status !== 'approved')
|
|
2790
|
+
bad.add(`${a.id} (${a.status})`);
|
|
2791
|
+
for (const d of a.dependsOn ?? [])
|
|
2792
|
+
up(d, depth + 1);
|
|
2793
|
+
};
|
|
2794
|
+
for (const d of s.dependsOn ?? [])
|
|
2795
|
+
up(d, 1);
|
|
2796
|
+
if (bad.size > 0) {
|
|
2797
|
+
count++;
|
|
2798
|
+
for (const b of bad)
|
|
2799
|
+
holders.set(b, (holders.get(b) ?? 0) + 1);
|
|
2800
|
+
}
|
|
2801
|
+
}
|
|
2802
|
+
if (count === 0)
|
|
2803
|
+
return null;
|
|
2804
|
+
const top = [...holders.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([k, v]) => `${k}: ${v}`).join(', ');
|
|
2805
|
+
return { name: 'sealed under unsealed ancestor', level: 'WARN',
|
|
2806
|
+
detail: `${count} approved spec(s) sit under an ancestor that is not approved — ${top}. A run or classification.strict refuses such a seal; seal the ancestor to restore the chain.` };
|
|
2807
|
+
}
|
|
2808
|
+
/**
|
|
2809
|
+
* @implements A-SPEC-781.2 — how the run stage machine in `ax.config.json` was read: a WARN naming the fallback or the
|
|
2810
|
+
* deny entries filled in, or null when it was read as written (no line, so a clean project's doctor is unchanged).
|
|
2811
|
+
*/
|
|
2812
|
+
function stageMachineCheck(target) {
|
|
2813
|
+
const notes = (0, config_1.loadConfig)(target).stages.notes;
|
|
2814
|
+
if (notes.length === 0)
|
|
2815
|
+
return null;
|
|
2816
|
+
return { name: 'stage machine', level: 'WARN', detail: `${notes.join('; ')}. Orchestrated runs use the machine as read; interactive sessions are unaffected.` };
|
|
2817
|
+
}
|
|
2686
2818
|
// @implements A-SPEC-509.1
|
|
2687
2819
|
/**
|
|
2688
2820
|
* Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
|
|
@@ -2984,6 +3116,49 @@ function activationText(observed, agent) {
|
|
|
2984
3116
|
return `live activation observed (${agent})`;
|
|
2985
3117
|
return `live activation unverified for ${agent}${observed.length ? ` (observed: ${observed.join(', ')})` : ''}`;
|
|
2986
3118
|
}
|
|
3119
|
+
/**
|
|
3120
|
+
* @implements A-SPEC-770.3 — the nearest ancestor node_modules copy of holmes-kit, which the bare npx command run from the
|
|
3121
|
+
* target (or below) resolves before any global install. Field incident 2026-10-17: ~/node_modules held 0.19.3 and a
|
|
3122
|
+
* 0.35.23 refusal's own grant hint answered "no pending request matches". No copy: no row.
|
|
3123
|
+
*/
|
|
3124
|
+
function npxResolutionCheck(target, runningVersion) {
|
|
3125
|
+
// @implements A-SPEC-770.6 — what npx resolves: the first node_modules/.bin/holmes-kit link from the target up (round
|
|
3126
|
+
// 1: a pnpm link and an unscoped package were run by npx and missed here). The command is spelled via npxBin().
|
|
3127
|
+
const { shadowCopy, runningCli, powershellLiteral, posixLiteral, binEntryNames } = require('../project/npx-bin');
|
|
3128
|
+
const shadowed = `${(0, npx_bin_1.npxBin)()} holmes-kit`;
|
|
3129
|
+
const shadow = shadowCopy(target);
|
|
3130
|
+
if (shadow === null) {
|
|
3131
|
+
// @implements A-SPEC-770.7 — PASS only when npx would take a file entry here and it is this install; a dangling link
|
|
3132
|
+
// or a directory is skipped by npx, so it gives no row (round 2: a dangling link read as PASS).
|
|
3133
|
+
for (let dir = path.resolve(target);; dir = path.dirname(dir)) {
|
|
3134
|
+
// @implements A-SPEC-770.9 — the platform's entry names, as shadowCopy reads them (round 4: .cmd PASS on POSIX).
|
|
3135
|
+
if (binEntryNames().some((n) => { try {
|
|
3136
|
+
return fs.statSync(path.join(dir, 'node_modules', '.bin', n)).isFile();
|
|
3137
|
+
}
|
|
3138
|
+
catch {
|
|
3139
|
+
return false;
|
|
3140
|
+
} })) {
|
|
3141
|
+
return { name: 'npx resolution', level: 'PASS', detail: `${shadowed} from ${target} runs this install (${runningCli()})` };
|
|
3142
|
+
}
|
|
3143
|
+
if (path.dirname(dir) === dir)
|
|
3144
|
+
return null;
|
|
3145
|
+
}
|
|
3146
|
+
}
|
|
3147
|
+
// @implements A-SPEC-770.7 — the fix names the package directory itself, quoted for this platform, and never a
|
|
3148
|
+
// node_modules directory (round 2: a shim made it `rm -r <project>/node_modules`).
|
|
3149
|
+
const q = process.platform === 'win32' ? powershellLiteral : posixLiteral;
|
|
3150
|
+
const removable = shadow.packageDir !== null && path.basename(shadow.packageDir) !== 'node_modules';
|
|
3151
|
+
// @implements A-SPEC-770.10 — npx runs the project's OWN bin here (a holmes-kit checkout or fork): nothing to remove.
|
|
3152
|
+
if (path.basename(shadow.link) === 'package.json' && shadow.packageDir === null) {
|
|
3153
|
+
return { name: 'npx resolution', level: 'WARN',
|
|
3154
|
+
detail: `npx run here starts this project's own bin.holmes-kit (${shadow.version || 'unknown version'}), not this install (${runningVersion}) — expected in a holmes-kit checkout; approval hints name this install's own path` };
|
|
3155
|
+
}
|
|
3156
|
+
return { name: 'npx resolution', level: 'WARN',
|
|
3157
|
+
detail: `${shadowed} from ${target} or below runs ${shadow.link}${shadow.packageDir ? ` (${shadow.packageDir})` : ''} ${shadow.version || '(unknown version)'}, not this install (${runningVersion}); approval hints there name this install's own path so they reach it`,
|
|
3158
|
+
fix: removable
|
|
3159
|
+
? `Remove that copy (rm -r ${q(shadow.packageDir)} and the link ${q(shadow.link)}) or update it to ${runningVersion}.`
|
|
3160
|
+
: `Update or remove the holmes-kit install that provides ${q(shadow.link)}.` };
|
|
3161
|
+
}
|
|
2987
3162
|
/** @implements A-SPEC-772.11 — the workspace a target belongs to (a subdirectory reads its project's records). */
|
|
2988
3163
|
function governedRootOf(target) {
|
|
2989
3164
|
try {
|
|
@@ -3145,6 +3320,7 @@ function codexWiredTarget(target) {
|
|
|
3145
3320
|
|| fs.existsSync(path.join(target, '.codex', 'mcp_config.json'));
|
|
3146
3321
|
}
|
|
3147
3322
|
/** The Holmes wirings of the three harnesses, read the way the handshake reads them (nothing is started). */
|
|
3323
|
+
// @implements A-SPEC-774.18 — exported: run start reads the same wirings to pin the MCP version of a run.
|
|
3148
3324
|
function holmesWirings(target, codexConfigPath) {
|
|
3149
3325
|
const wirings = [
|
|
3150
3326
|
{
|
|
@@ -3782,7 +3958,28 @@ function semanticCoverageCheck(root, tier) {
|
|
|
3782
3958
|
return unjudgeable();
|
|
3783
3959
|
}
|
|
3784
3960
|
}
|
|
3961
|
+
/**
|
|
3962
|
+
* @implements A-SPEC-476.1 — the tier row names the project's cap: a key it withheld (by source, never the value) and the
|
|
3963
|
+
* cap that applied; a cap that could not be read is FAIL, because the tier is none until it is fixed.
|
|
3964
|
+
*/
|
|
3785
3965
|
function semanticTierVerdict(t) {
|
|
3966
|
+
if (t.cap?.problem) {
|
|
3967
|
+
return {
|
|
3968
|
+
level: 'FAIL',
|
|
3969
|
+
detail: `semantic.maxTier in ax.config.json could not be read (${t.cap.problem}) — the semantic tier is none until it is fixed.`,
|
|
3970
|
+
fix: 'Set semantic.maxTier to "cloud", "local" or "none" in ax.config.json, or remove the key for no cap.',
|
|
3971
|
+
};
|
|
3972
|
+
}
|
|
3973
|
+
const v = uncappedTierVerdict(t);
|
|
3974
|
+
if (!t.cap)
|
|
3975
|
+
return v;
|
|
3976
|
+
const key = t.cap.keyWithheld === undefined ? 'no key' : `key present (${KEY_SOURCE_LABEL[t.cap.keyWithheld]})`;
|
|
3977
|
+
return { ...v, detail: `${v.detail} [${key}, project cap ${t.cap.maxTier} (ax.config.json semantic.maxTier)]` };
|
|
3978
|
+
}
|
|
3979
|
+
const KEY_SOURCE_LABEL = {
|
|
3980
|
+
'env': 'HOLMES_SEMANTIC_API_KEY', 'env-compat': 'GEMINI_API_KEY', 'keychain': 'macOS keychain', 'file': '~/.holmes/credentials.json',
|
|
3981
|
+
};
|
|
3982
|
+
function uncappedTierVerdict(t) {
|
|
3786
3983
|
if (t.tier === 'cloud') {
|
|
3787
3984
|
// @implements A-SPEC-477 — the SOURCE of the consent is shown (env/keychain/file); the value
|
|
3788
3985
|
// never is. Consent must be able to see what it consented to, and where it lives.
|
package/dist/holmes/cli/index.js
CHANGED
|
@@ -37,7 +37,7 @@ exports.isBrokenPipe = void 0;
|
|
|
37
37
|
exports.packageRoot = packageRoot;
|
|
38
38
|
exports.main = main;
|
|
39
39
|
exports.installPipeGuard = installPipeGuard;
|
|
40
|
-
// @implements A-SPEC-704, A-SPEC-709, A-SPEC-734,
|
|
40
|
+
// @implements A-SPEC-704, A-SPEC-773, A-SPEC-770.11,A-SPEC-709, A-SPEC-734,A-SPEC-751, A-SPEC-752, A-SPEC-772.4, A-SPEC-779, A-SPEC-102.2, A-SPEC-774.20, A-SPEC-102.7, A-SPEC-779.2
|
|
41
41
|
// @implements A-SPEC-549.2
|
|
42
42
|
// @implements A-SPEC-591, A-SPEC-626
|
|
43
43
|
const cli_execution_1 = require("./cli-execution");
|
|
@@ -85,10 +85,16 @@ const KNOWN_FLAGS = {
|
|
|
85
85
|
doctor: ['help', 'target', 'json', 'agent', 'registry'],
|
|
86
86
|
// @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
|
|
87
87
|
attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
|
|
88
|
+
// @implements A-SPEC-773 — the Holmes scratch root an agent may clean up on its own.
|
|
89
|
+
scratch: ['help', 'new'],
|
|
90
|
+
// @implements A-SPEC-774.10 — the role policy rewritten into the new vocabulary with equal verdicts.
|
|
91
|
+
roles: ['help', 'target', 'dry-run'],
|
|
92
|
+
run: ['help', 'target', 'worktree', 'engine', 'engine-arg', 'id', 'key', 'scope', 'to', 'why', 'accept-unknown-versions'], // @implements A-SPEC-774.17, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20
|
|
93
|
+
review: ['help', 'target', 'base', 'head', 'verdict', 'finding', 'engine', 'model', 'session', 'strict', 'solid'], // @implements A-SPEC-102.2, A-SPEC-102.7
|
|
88
94
|
skills: ['help', 'target'],
|
|
89
95
|
ci: ['help', 'target', 'specs-dir', 'json'],
|
|
90
96
|
serve: ['help', 'target', 'port'],
|
|
91
|
-
approve: ['help', 'target', 'list', 'status', 'refusals', 'grant', 'deny', 'ask', 'revoke', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'], // A-SPEC-649: --revoke · A-SPEC-650: --status
|
|
97
|
+
approve: ['help', 'target', 'list', 'status', 'refusals', 'grant', 'deny', 'ask', 'revoke', 'withdraw', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'], // A-SPEC-649: --revoke · A-SPEC-650: --status · A-SPEC-779.2: --withdraw
|
|
92
98
|
ledger: ['help', 'target', 'ref', 'dry-run'],
|
|
93
99
|
// @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
|
|
94
100
|
'semantic-key': ['help'],
|
|
@@ -116,6 +122,7 @@ const APPROVE_USAGE = `holmes-kit approve — decide pending approval requests (
|
|
|
116
122
|
--deny <id> --reason <text> deny — the reason rides the agent's next refusal
|
|
117
123
|
--ask <id> --question <text> leave a question and hold — the agent relays it to the user
|
|
118
124
|
--revoke <id> --reason <text> withdraw a live grant — the request must be decided again
|
|
125
|
+
--withdraw <ref> --reason <text> the run that filed a request closes it (recorded as withdrawn, not denied)
|
|
119
126
|
--target <dir> project root (default: current directory)
|
|
120
127
|
`;
|
|
121
128
|
class UnknownFlagError extends Error {
|
|
@@ -128,9 +135,12 @@ class UnknownFlagError extends Error {
|
|
|
128
135
|
*/
|
|
129
136
|
// A-SPEC-251.1 (round 26): `yes` — `upgrade --yes` was refused as "--yes requires a value", so the non-interactive
|
|
130
137
|
// upgrade its own guidance names could not run (measured).
|
|
138
|
+
// A-SPEC-774.24: --accept-unknown-versions names its fields, so it is a value flag, not one of these.
|
|
131
139
|
const BOOLEAN_FLAGS = new Set(['badge', 'readme', 'help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy', 'yes']); // A-SPEC-650: --status
|
|
140
|
+
/** @implements A-SPEC-770.11 — value flags whose value may be omitted; the handler supplies the default. */
|
|
141
|
+
const OPTIONAL_VALUE_FLAGS = new Set(['refusals']);
|
|
132
142
|
/** @implements A-SPEC-771.1 — value flags that may be given more than once. */
|
|
133
|
-
const REPEATABLE_FLAGS = new Set(['limit']);
|
|
143
|
+
const REPEATABLE_FLAGS = new Set(['limit', 'engine-arg', 'finding', 'scope']); // @implements A-SPEC-774.17 — one engine argument per flag; A-SPEC-102.2 — one finding id per flag
|
|
134
144
|
function parseFlags(argv, known) {
|
|
135
145
|
const flags = {};
|
|
136
146
|
const positionals = [];
|
|
@@ -247,9 +257,32 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
|
|
|
247
257
|
--deny <ref> --reason <text> record a denial the agent will see
|
|
248
258
|
--ask <ref> --question <text> hold with a question the agent relays
|
|
249
259
|
--revoke <id> --reason <text> withdraw a live grant (full id or unique prefix)
|
|
260
|
+
--withdraw <ref> --reason <text> the filing run closes its own request (recorded withdrawn)
|
|
250
261
|
<ref> list index (1,2,…), full id, or a unique id prefix
|
|
251
262
|
--target <dir> project root (default: cwd)
|
|
252
263
|
|
|
264
|
+
holmes-kit run start|status|stop open, list and end an orchestrated run (JSON on stdout)
|
|
265
|
+
start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]… [--scope <A-SPEC-id>]…
|
|
266
|
+
[--accept-unknown-versions <field,...>]
|
|
267
|
+
checks the worktree would be governed (specs, MCP, gate hook, no
|
|
268
|
+
gate-off argument, every version and build readable), writes the run
|
|
269
|
+
record, prints the headless command, HOLMES_RUN_ID and a one-time stop
|
|
270
|
+
key; exit 3 if refused. --accept-unknown-versions hook,mcp starts
|
|
271
|
+
despite those unreadable fields only, and records them; fields a
|
|
272
|
+
harness cannot read by design (agy: hook, hook_build) are exempt
|
|
273
|
+
stop --id <run_id> --key <stop_key> end the run (only the holder of the key can)
|
|
274
|
+
transition --id <run_id> --to <stage> --key <stop_key> [--why <text>]
|
|
275
|
+
move the run along its stage machine (ax.config.json stages);
|
|
276
|
+
test and done need an independent passing review; exit 3 if refused
|
|
277
|
+
|
|
278
|
+
holmes-kit review record|status|gate review verdicts bound to a base and head (JSON on stdout)
|
|
279
|
+
record --base <rev> --head <rev> --verdict pass|fail [--finding <id>]… [--engine e] [--model m]
|
|
280
|
+
refuses a self-review (the run that wrote the head) and a role
|
|
281
|
+
without RECORD_REVIEW; the ledger lives in the main checkout
|
|
282
|
+
gate --base <rev> --head <rev> [--strict] exit 1 unless an independent pass covers the range
|
|
283
|
+
and no open critical (with --strict, important) finding remains
|
|
284
|
+
mrp --base <rev> --head <rev> the merge-ready package: spec chain, test evidence, verdict, missing
|
|
285
|
+
|
|
253
286
|
holmes-kit autonomy status|on|off|delegate|revoke-delegation grant/end autonomous spec approval
|
|
254
287
|
delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]
|
|
255
288
|
run delegation for THIS workspace: hitl specs whose only reason is a
|
|
@@ -273,6 +306,9 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
|
|
|
273
306
|
--target <dir> also verify that target's wiring points at this install
|
|
274
307
|
--json machine-readable output
|
|
275
308
|
|
|
309
|
+
holmes-kit scratch [--new <label>]
|
|
310
|
+
print the Holmes scratch root, or make a fresh directory under it; the gate lets
|
|
311
|
+
an agent rm -rf such a directory by its absolute path in every harness
|
|
276
312
|
holmes-kit attest [flags] say how many source files trace to an APPROVED spec (a statement, not a gate)
|
|
277
313
|
--target <dir> the project to measure (default: current directory)
|
|
278
314
|
--exclude <a,b> path prefixes that are not this project's source (vendored trees); echoed in the output
|
|
@@ -322,6 +358,10 @@ async function main(argv) {
|
|
|
322
358
|
for (const [key, v] of Object.entries(flags)) {
|
|
323
359
|
// `--target` (true) AND `--target=` ('') both point at nothing — an empty inline value
|
|
324
360
|
// resolved to CWD and wired it silently (round-5 HIGH).
|
|
361
|
+
// @implements A-SPEC-770.11 — an optional-value flag defaults where it is read (`--refusals` → 20 rows): the
|
|
362
|
+
// `approve --refusals --target <root>` every refusal prints exited 2 here (measured 2026-10-17).
|
|
363
|
+
if (OPTIONAL_VALUE_FLAGS.has(key) && v === true)
|
|
364
|
+
continue;
|
|
325
365
|
if (!BOOLEAN_FLAGS.has(key) && (v === true || (typeof v === 'string' && v.trim() === ''))) {
|
|
326
366
|
process.stderr.write(`--${key} requires a value\n\n${USAGE}`);
|
|
327
367
|
return 2;
|
|
@@ -331,7 +371,10 @@ async function main(argv) {
|
|
|
331
371
|
// silently wrote into CWD while the named target stayed stale (round-3 HIGH).
|
|
332
372
|
const expected = cmd === 'runtime-binding' ? ['setup', 'status', 'remove'] : cmd === 'guidance' ? ['check', 'refresh'] : cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
|
|
333
373
|
: cmd === 'semantic-key' ? ['set', 'unset', 'status']
|
|
334
|
-
: cmd === 'autonomy' ? ['status', 'on', 'off', 'delegate', 'revoke-delegation']
|
|
374
|
+
: cmd === 'autonomy' ? ['status', 'on', 'off', 'delegate', 'revoke-delegation'] // @implements A-SPEC-771.1
|
|
375
|
+
: cmd === 'roles' ? ['migrate'] // @implements A-SPEC-774.10
|
|
376
|
+
: cmd === 'run' ? ['start', 'status', 'stop', 'transition'] // @implements A-SPEC-774.17, A-SPEC-781
|
|
377
|
+
: cmd === 'review' ? ['record', 'status', 'gate', 'mrp'] : []; // @implements A-SPEC-102.2, A-SPEC-102.6
|
|
335
378
|
const unexpected = positionals.filter((p) => !expected.includes(p));
|
|
336
379
|
if (unexpected.length > 0) {
|
|
337
380
|
const hint = fs.existsSync(unexpected[0]) ? ` — did you mean --target ${unexpected[0]}?` : '';
|
|
@@ -466,6 +509,48 @@ async function main(argv) {
|
|
|
466
509
|
}
|
|
467
510
|
// @implements A-SPEC-702 — reads one scan and the spec store; writes only the badge and the README's
|
|
468
511
|
// marker region, and only when asked. The numbers never change the exit code.
|
|
512
|
+
// @implements A-SPEC-773
|
|
513
|
+
// @implements A-SPEC-774.10
|
|
514
|
+
// @implements A-SPEC-774.17 — open, list and end an orchestrated run (the record A-SPEC-774.9's run mode reads).
|
|
515
|
+
if (cmd === 'run') {
|
|
516
|
+
const { runRun, parseAcceptedVersions } = require('./run');
|
|
517
|
+
const str = (k) => (typeof flags[k] === 'string' ? flags[k] : undefined);
|
|
518
|
+
// @implements A-SPEC-774.24 — the accepted unreadable fields, by name; an empty or unknown name is refused.
|
|
519
|
+
const acceptText = str('accept-unknown-versions');
|
|
520
|
+
const acceptParsed = acceptText === undefined ? null : parseAcceptedVersions(acceptText);
|
|
521
|
+
if (acceptParsed !== null && 'refusal' in acceptParsed) {
|
|
522
|
+
process.stderr.write(`✗ ${acceptParsed.refusal}\n`);
|
|
523
|
+
return 2;
|
|
524
|
+
}
|
|
525
|
+
return runRun(positionals[0], {
|
|
526
|
+
target: str('target') ? path.resolve(str('target')) : undefined, worktree: str('worktree'), engine: str('engine'),
|
|
527
|
+
engineArgs: str('engine-arg')?.split('\n'), id: str('id'), key: str('key'), scope: str('scope')?.split('\n'), to: str('to'), why: str('why'),
|
|
528
|
+
// @implements A-SPEC-774.20 — start despite unreadable versions; run start records which.
|
|
529
|
+
...(acceptParsed !== null ? { acceptUnknownVersions: acceptParsed.fields } : {}),
|
|
530
|
+
}, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
|
|
531
|
+
}
|
|
532
|
+
// @implements A-SPEC-102.2 — review verdicts for callers that are not MCP clients.
|
|
533
|
+
if (cmd === 'review') {
|
|
534
|
+
const { runReview, REVIEW_USAGE } = require('./review');
|
|
535
|
+
if (flags.help) {
|
|
536
|
+
process.stdout.write(REVIEW_USAGE);
|
|
537
|
+
return 0;
|
|
538
|
+
}
|
|
539
|
+
const str = (k) => (typeof flags[k] === 'string' ? flags[k] : undefined);
|
|
540
|
+
return runReview(positionals[0], {
|
|
541
|
+
target: str('target'), base: str('base'), head: str('head'), verdict: str('verdict'), findings: str('finding')?.split('\n'),
|
|
542
|
+
solid: str('solid')?.split('\n'), // @implements A-SPEC-102.7
|
|
543
|
+
engine: str('engine'), model: str('model'), session: str('session'), strict: flags.strict === true,
|
|
544
|
+
}, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
|
|
545
|
+
}
|
|
546
|
+
if (cmd === 'roles') {
|
|
547
|
+
const { runRoles } = require('./roles');
|
|
548
|
+
return runRoles(positionals[0], { target: typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd(), dryRun: flags['dry-run'] === true }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
|
|
549
|
+
}
|
|
550
|
+
if (cmd === 'scratch') {
|
|
551
|
+
const { runScratch } = require('./scratch');
|
|
552
|
+
return runScratch({ label: typeof flags.new === 'string' ? flags.new : undefined }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
|
|
553
|
+
}
|
|
469
554
|
if (cmd === 'attest') {
|
|
470
555
|
const { runAttest } = require('./attest');
|
|
471
556
|
const target = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
|
|
@@ -961,6 +1046,15 @@ async function main(argv) {
|
|
|
961
1046
|
process.stdout.write(`\u2717 ${ref.refusal}\n`);
|
|
962
1047
|
return 1;
|
|
963
1048
|
}
|
|
1049
|
+
// @implements A-SPEC-779 \u2014 never from inside a run; a run's awaited request only from a terminal.
|
|
1050
|
+
const { grantGuard } = require('../guardrail/run-refusals');
|
|
1051
|
+
const guarded = grantGuard(root, ref.id, { env: process.env, interactive: process.stdin.isTTY === true && process.stdout.isTTY === true });
|
|
1052
|
+
if (guarded !== null) {
|
|
1053
|
+
// @implements A-SPEC-779.1 \u2014 the refusal carries its envelope, so an orchestrator reads its class.
|
|
1054
|
+
const { withRefusalLine } = require('../guardrail/refusal-codes');
|
|
1055
|
+
process.stdout.write(`${withRefusalLine(`\u2717 ${guarded}`)}\n`);
|
|
1056
|
+
return 1;
|
|
1057
|
+
}
|
|
964
1058
|
const r = grantRequest(root, ref.id, opts);
|
|
965
1059
|
process.stdout.write(r.ok ? `✓ approved — ${ref.subject('✓ approved — ')}\n${ref.detail(`valid until ${r.expires}`)}\n` : `✗ ${r.reason}\n`);
|
|
966
1060
|
return r.ok ? 0 : 1;
|
|
@@ -980,6 +1074,23 @@ async function main(argv) {
|
|
|
980
1074
|
process.stdout.write(r.ok ? `✓ denied — ${ref.subject('✓ denied — ')}\n${ref.detail('the denial was recorded')}\n` : `✗ ${r.reason}\n`);
|
|
981
1075
|
return r.ok ? 0 : 1;
|
|
982
1076
|
}
|
|
1077
|
+
// @implements A-SPEC-779.2 — the requester's own close: only the run that filed it, recorded as `withdrawn`.
|
|
1078
|
+
if (typeof flags.withdraw === 'string') {
|
|
1079
|
+
const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
|
|
1080
|
+
if (reason === '') {
|
|
1081
|
+
process.stderr.write('✗ --withdraw requires --reason — it is what the operator reads in place of a decision\n');
|
|
1082
|
+
return 1;
|
|
1083
|
+
}
|
|
1084
|
+
const { withdrawRequest } = require('./approve');
|
|
1085
|
+
const ref = resolveRef(flags.withdraw);
|
|
1086
|
+
if ('refusal' in ref) {
|
|
1087
|
+
process.stdout.write(`✗ ${ref.refusal}\n`);
|
|
1088
|
+
return 1;
|
|
1089
|
+
}
|
|
1090
|
+
const r = withdrawRequest(root, ref.id, reason, { env: process.env, cwd: process.cwd() });
|
|
1091
|
+
process.stdout.write(r.ok ? `↩ withdrawn — ${ref.subject('↩ withdrawn — ')}\n${ref.detail('withdrawn by its run')}\n` : `✗ ${r.reason}\n`);
|
|
1092
|
+
return r.ok ? 0 : 1;
|
|
1093
|
+
}
|
|
983
1094
|
// @implements A-SPEC-649 — the operator withdraws a live grant. A granted id is no longer
|
|
984
1095
|
// pending, so it resolves against the DECIDED ids (full id or a unique prefix), never a list index.
|
|
985
1096
|
if (typeof flags.revoke === 'string') {
|
package/dist/holmes/cli/init.js
CHANGED
|
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
36
36
|
exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
|
|
37
37
|
exports.buildHookPlan = buildHookPlan;
|
|
38
38
|
exports.runInit = runInit;
|
|
39
|
-
// @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6
|
|
39
|
+
// @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-476.1
|
|
40
40
|
// @implements A-SPEC-709
|
|
41
41
|
// @implements A-SPEC-769.11
|
|
42
42
|
// @implements A-SPEC-340
|
|
@@ -1356,9 +1356,10 @@ function runInitUnguarded(opts) {
|
|
|
1356
1356
|
// runs doctor never met it. One-time by the nature of the act, so no marker is needed here.
|
|
1357
1357
|
// Fail-open: an invitation is not worth failing a wiring over.
|
|
1358
1358
|
try {
|
|
1359
|
-
const {
|
|
1359
|
+
const { resolveProjectSemanticTier } = require('../semantic/tier');
|
|
1360
1360
|
const { tierAdviceLines } = require('../semantic/tier-advice');
|
|
1361
|
-
|
|
1361
|
+
// @implements A-SPEC-476.1 — the target project's capped tier.
|
|
1362
|
+
for (const line of tierAdviceLines(resolveProjectSemanticTier(opts.target)))
|
|
1362
1363
|
messages.push(line);
|
|
1363
1364
|
}
|
|
1364
1365
|
catch { /* the wiring is the point; the invitation is not */
|
|
@@ -16,4 +16,6 @@ export interface NotifyDeps {
|
|
|
16
16
|
detached?: boolean;
|
|
17
17
|
}) => Pick<ChildProcess, 'unref' | 'on'>;
|
|
18
18
|
}
|
|
19
|
-
|
|
19
|
+
/** @implements A-SPEC-770.12 — the notification text: kind, target and, when the request carries one, its title. */
|
|
20
|
+
export declare function notificationBody(item: Pick<PendingRequest, 'kind' | 'target' | 'title'>): string;
|
|
21
|
+
export declare function notifyQueueArrival(item: Pick<PendingRequest, 'kind' | 'target' | 'title'>, deps?: NotifyDeps): void;
|