@holmes-lab/holmes-kit 0.40.0 → 0.40.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.
- package/CHANGELOG.md +234 -0
- package/README.md +70 -4
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/index.js +25 -19
- package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
- package/dist/holmes/cli/interactive-prompt.js +98 -16
- package/dist/holmes/config/config.d.ts +17 -0
- package/dist/holmes/config/config.js +13 -1
- package/dist/holmes/governance/autonomy.d.ts +7 -0
- package/dist/holmes/governance/autonomy.js +36 -5
- package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
- package/dist/holmes/governance/push-gate-runner.js +40 -3
- package/dist/holmes/governance/push-gate.d.ts +13 -2
- package/dist/holmes/governance/push-gate.js +106 -14
- package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
- package/dist/holmes/guardrail/advisory-line.js +718 -0
- package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
- package/dist/holmes/guardrail/impact-gate.js +32 -5
- package/dist/holmes/hooks/pre-tool-use.d.ts +11 -0
- package/dist/holmes/hooks/pre-tool-use.js +44 -5
- package/dist/holmes/hooks/session-start.js +17 -1
- package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
- package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
- package/dist/holmes/mcp/handlers/test-execution.js +199 -21
- package/dist/holmes/mcp/handlers.d.ts +468 -3
- package/dist/holmes/mcp/handlers.js +5 -1
- package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
- package/dist/holmes/mcp/maintenance-analyze.js +4 -2
- package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
- package/dist/holmes/mcp/maintenance-evidence.js +4 -1
- package/dist/holmes/mcp/tool-schemas.js +13 -7
- package/dist/holmes/project/baseline.d.ts +15 -2
- package/dist/holmes/project/baseline.js +11 -6
- package/dist/holmes/project/bounded-io.d.ts +1 -0
- package/dist/holmes/project/bounded-io.js +4 -2
- package/dist/holmes/project/change-source.d.ts +4 -0
- package/dist/holmes/project/change-source.js +13 -5
- package/dist/holmes/project/root.js +3 -1
- package/dist/holmes/review/evidence-mode.d.ts +21 -0
- package/dist/holmes/review/evidence-mode.js +33 -0
- package/dist/holmes/review/head-worktree.d.ts +55 -0
- package/dist/holmes/review/head-worktree.js +329 -0
- package/dist/holmes/review/mrp.js +13 -3
- package/dist/holmes/review/run-provenance.d.ts +45 -0
- package/dist/holmes/review/run-provenance.js +314 -0
- package/dist/holmes/review/test-evidence.d.ts +174 -0
- package/dist/holmes/review/test-evidence.js +330 -2
- package/dist/holmes/review/test-reports.d.ts +94 -0
- package/dist/holmes/review/test-reports.js +382 -0
- package/dist/holmes/review/test-runner.d.ts +176 -65
- package/dist/holmes/review/test-runner.js +531 -316
- package/dist/holmes/review/test-units.d.ts +159 -0
- package/dist/holmes/review/test-units.js +814 -0
- package/package.json +1 -1
- package/playbooks/publish/PLAYBOOK.md +2 -1
|
@@ -57,6 +57,12 @@ export interface EditEvidenceVerdict {
|
|
|
57
57
|
* material. Same locations, read from the type table rather than spelled twice.
|
|
58
58
|
*/
|
|
59
59
|
export declare function isLowRiskTarget(target: string): boolean;
|
|
60
|
+
/** @implements A-SPEC-333.1 — every code the gate can emit, read off the remediation table. */
|
|
61
|
+
export declare function editEvidenceCodes(): Array<EditEvidenceReason['code']>;
|
|
62
|
+
/** @implements A-SPEC-333.2 — one code's remediation sentence, for an explanation said once per epoch. */
|
|
63
|
+
export declare function remediationFor(code: EditEvidenceReason['code']): string;
|
|
64
|
+
/** @implements A-SPEC-333.1 — lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal. */
|
|
65
|
+
export declare function primaryReason(reasons: EditEvidenceReason[]): EditEvidenceReason | undefined;
|
|
60
66
|
export declare function evaluateEditEvidence(inputArgs: EditEvidenceInput): EditEvidenceVerdict;
|
|
61
67
|
/**
|
|
62
68
|
* @implements A-SPEC-278
|
|
@@ -34,10 +34,13 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.isLowRiskTarget = isLowRiskTarget;
|
|
37
|
+
exports.editEvidenceCodes = editEvidenceCodes;
|
|
38
|
+
exports.remediationFor = remediationFor;
|
|
39
|
+
exports.primaryReason = primaryReason;
|
|
37
40
|
exports.evaluateEditEvidence = evaluateEditEvidence;
|
|
38
41
|
exports.preEditEvidenceDecision = preEditEvidenceDecision;
|
|
39
42
|
exports.loadEditEvidence = loadEditEvidence;
|
|
40
|
-
// @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6
|
|
43
|
+
// @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6, A-SPEC-333.1, A-SPEC-333.9, A-SPEC-333.10
|
|
41
44
|
// @implements A-SPEC-278
|
|
42
45
|
// @implements A-SPEC-277
|
|
43
46
|
// @implements A-SPEC-276
|
|
@@ -46,6 +49,7 @@ const fs = __importStar(require("node:fs"));
|
|
|
46
49
|
const crypto = __importStar(require("node:crypto"));
|
|
47
50
|
const path = __importStar(require("node:path"));
|
|
48
51
|
const spec_types_1 = require("../spec/spec-types");
|
|
52
|
+
const test_scope_1 = require("../rtm/test-scope");
|
|
49
53
|
const CODE_EXTENSIONS = new Set([
|
|
50
54
|
'.ts', '.mts', '.cts', '.tsx', '.jsx', '.js', '.mjs', '.cjs', '.py', '.cs', '.java', '.go',
|
|
51
55
|
'.rs', '.cpp', '.cc', '.cxx', '.hpp', '.hh', '.h', '.rb', '.php', '.kt', '.kts', '.swift',
|
|
@@ -68,6 +72,20 @@ function isLowRiskTarget(target) {
|
|
|
68
72
|
return false;
|
|
69
73
|
return true;
|
|
70
74
|
}
|
|
75
|
+
/** @implements A-SPEC-333.1 — every code the gate can emit, read off the remediation table. */
|
|
76
|
+
function editEvidenceCodes() {
|
|
77
|
+
return Object.keys(REMEDIATION);
|
|
78
|
+
}
|
|
79
|
+
/** @implements A-SPEC-333.2 — one code's remediation sentence, for an explanation said once per epoch. */
|
|
80
|
+
function remediationFor(code) {
|
|
81
|
+
return REMEDIATION[code];
|
|
82
|
+
}
|
|
83
|
+
/** @implements A-SPEC-333.1 — lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal. */
|
|
84
|
+
function primaryReason(reasons) {
|
|
85
|
+
return reasons.find((r) => r.code === 'basis-drift')
|
|
86
|
+
?? reasons.find((r) => r.code === 'target-drift')
|
|
87
|
+
?? reasons[0];
|
|
88
|
+
}
|
|
71
89
|
const REMEDIATION = {
|
|
72
90
|
// @implements A-SPEC-278.4 — an Edit or Write call carries no digest, so "retry with the digest" could not be followed.
|
|
73
91
|
'no-analysis': 'Run maintenance_analyze({ root, request, persist: true }) for this change; the gate finds an analysis persisted at this HEAD by itself (impact_gate_check also accepts its digest).',
|
|
@@ -174,6 +192,18 @@ function evaluateEditEvidence(inputArgs) {
|
|
|
174
192
|
});
|
|
175
193
|
escalate('widen');
|
|
176
194
|
}
|
|
195
|
+
else if ((0, test_scope_1.architectureGoverningFiles)([target]).length > 0
|
|
196
|
+
&& artifact.changedFilesSource === 'git-diff-default'
|
|
197
|
+
&& !(artifact.uncertainty.architectureTouched ?? []).includes(target)) {
|
|
198
|
+
// @implements A-SPEC-333.9 — a basis built from the working tree's diff assessed the documents it held; an edit of
|
|
199
|
+
// a decision or C-SPEC document it did not hold is outside what was assessed
|
|
200
|
+
// @implements A-SPEC-333.10 — read from the structured field the artifact persists, never from the explaining sentence
|
|
201
|
+
reasons.push({
|
|
202
|
+
code: 'architecture-unchecked',
|
|
203
|
+
detail: `The analysis's architecture basis came from the working tree's diff and did not hold ${target}, so its constraints were not checked.`,
|
|
204
|
+
});
|
|
205
|
+
escalate('widen');
|
|
206
|
+
}
|
|
177
207
|
// (6b) @implements A-SPEC-279 — the remaining two constraint axes. The condition is "was it
|
|
178
208
|
// EXAMINED", not "does a constraint exist": 61 of this repository's 192 A-SPECs declare a non-none
|
|
179
209
|
// breaking change, so widening on mere presence would fire on about a third of all edits and teach
|
|
@@ -204,10 +234,7 @@ function evaluateEditEvidence(inputArgs) {
|
|
|
204
234
|
escalate('widen');
|
|
205
235
|
}
|
|
206
236
|
traceGapReason();
|
|
207
|
-
|
|
208
|
-
const primary = reasons.find((r) => r.code === 'basis-drift')
|
|
209
|
-
?? reasons.find((r) => r.code === 'target-drift')
|
|
210
|
-
?? reasons[0];
|
|
237
|
+
const primary = primaryReason(reasons);
|
|
211
238
|
return {
|
|
212
239
|
decision,
|
|
213
240
|
reasons,
|
|
@@ -4,6 +4,7 @@ import { Approval } from '../guardrail/risk-gate';
|
|
|
4
4
|
import { GrantSettlement, type GrantSettlementPending, type GrantSettlementResult } from '../governance/approval-grants';
|
|
5
5
|
import { RiskAction, RiskAssessment, RmSignal, StagedStoreSignal } from '../guardrail/risk-types';
|
|
6
6
|
import { type PreEditEvidenceMode } from '../guardrail/impact-gate';
|
|
7
|
+
import { type AdvisoryContext } from '../guardrail/advisory-line';
|
|
7
8
|
export declare function resolveRmSignals(command: string, cwd: string, projectRoot?: string, specsDir?: string, scratchTmpdir?: string): Record<string, RmSignal> | undefined;
|
|
8
9
|
/**
|
|
9
10
|
* @implements A-SPEC-226.3 — what `git status` says about the spec store, for a command that holds a staging verb. One
|
|
@@ -179,6 +180,8 @@ export interface HookInput {
|
|
|
179
180
|
cwd?: string;
|
|
180
181
|
/** @implements A-SPEC-774.9 — the harness session id, so a run record can bind the session itself. */
|
|
181
182
|
session_id?: string;
|
|
183
|
+
/** @implements A-SPEC-333.1 — the subagent the harness names, so a parent's first sighting is not a subagent's. */
|
|
184
|
+
agent_id?: string;
|
|
182
185
|
/**
|
|
183
186
|
* @implements A-SPEC-163
|
|
184
187
|
* The raw payload carried a path field that was NOT a string, or `tool_input` was not an object.
|
|
@@ -254,6 +257,11 @@ export declare function preEditEvidenceGate(o: {
|
|
|
254
257
|
mode: PreEditEvidenceMode;
|
|
255
258
|
declaredDigest: string | null;
|
|
256
259
|
currentHead: string;
|
|
260
|
+
/**
|
|
261
|
+
* @implements A-SPEC-333.1, A-SPEC-333.2 — who is reading, and where the records of what was said wait for the final decision.
|
|
262
|
+
* Without it (no session, a counterfactual re-ask) every warning is said in full and nothing is read or recorded.
|
|
263
|
+
*/
|
|
264
|
+
advisory?: AdvisoryContext;
|
|
257
265
|
}): {
|
|
258
266
|
permissionDecision: 'allow' | 'deny';
|
|
259
267
|
permissionDecisionReason?: string;
|
|
@@ -349,6 +357,7 @@ declare function judgeHook(input: {
|
|
|
349
357
|
};
|
|
350
358
|
cwd?: string;
|
|
351
359
|
session_id?: string;
|
|
360
|
+
agent_id?: string;
|
|
352
361
|
}, specsDir: string, opts: {
|
|
353
362
|
assess?: (a: RiskAction) => RiskAssessment;
|
|
354
363
|
/**
|
|
@@ -387,6 +396,8 @@ declare function judgeHook(input: {
|
|
|
387
396
|
autonomySpecStaging?: boolean;
|
|
388
397
|
/** @implements A-SPEC-245.4 — where this judgement holds the grants it resolved; the caller settles it once. */
|
|
389
398
|
settlement?: GrantSettlement;
|
|
399
|
+
/** @implements A-SPEC-333.2 — the decision being made, never a counterfactual re-ask: what its warnings may record. */
|
|
400
|
+
advisory?: AdvisoryContext;
|
|
390
401
|
filed?: {
|
|
391
402
|
request?: string;
|
|
392
403
|
};
|
|
@@ -62,7 +62,7 @@ exports.settleOnMainThread = settleOnMainThread;
|
|
|
62
62
|
exports.auditApprovalFor = auditApprovalFor;
|
|
63
63
|
exports.evaluateHook = evaluateHook;
|
|
64
64
|
exports.readSpecsSync = readSpecsSync;
|
|
65
|
-
// @implements A-SPEC-794.57, A-SPEC-794.55, A-SPEC-794.54, A-SPEC-794.53, A-SPEC-794.52, A-SPEC-794.49, A-SPEC-222.12, A-SPEC-222.13, A-SPEC-476.7, A-SPEC-226.3, A-SPEC-774.28, A-SPEC-747.4, A-SPEC-747.7, A-SPEC-774.23, A-SPEC-753.3, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-134.2,A-SPEC-278,A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7, A-SPEC-768.2, A-SPEC-772.1, A-SPEC-747.3, A-SPEC-774.26, A-SPEC-163.8, A-SPEC-790, A-SPEC-790.2, A-SPEC-790.7, A-SPEC-790.8, A-SPEC-792.5, A-SPEC-245.9, A-SPEC-245.15, A-SPEC-245.17
|
|
65
|
+
// @implements A-SPEC-333.9, A-SPEC-794.57, A-SPEC-794.55, A-SPEC-794.54, A-SPEC-794.53, A-SPEC-794.52, A-SPEC-794.49, A-SPEC-222.12, A-SPEC-222.13, A-SPEC-476.7, A-SPEC-226.3, A-SPEC-774.28, A-SPEC-747.4, A-SPEC-747.7, A-SPEC-774.23, A-SPEC-753.3, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-134.2,A-SPEC-278,A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7, A-SPEC-768.2, A-SPEC-772.1, A-SPEC-747.3, A-SPEC-774.26, A-SPEC-163.8, A-SPEC-790, A-SPEC-790.2, A-SPEC-790.7, A-SPEC-790.8, A-SPEC-792.5, A-SPEC-245.9, A-SPEC-245.15, A-SPEC-245.17
|
|
66
66
|
const powershell_shell_1 = require("../guardrail/powershell-shell");
|
|
67
67
|
const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
|
|
68
68
|
// @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
|
|
@@ -122,6 +122,8 @@ const linear_match_1 = require("../guardrail/linear-match");
|
|
|
122
122
|
const approval_grants_1 = require("../governance/approval-grants");
|
|
123
123
|
const approval_blockers_1 = require("../spec/approval-blockers");
|
|
124
124
|
const impact_gate_1 = require("../guardrail/impact-gate");
|
|
125
|
+
const advisory_line_1 = require("../guardrail/advisory-line");
|
|
126
|
+
const heartbeat_1 = require("./heartbeat");
|
|
125
127
|
const bounded_io_1 = require("../project/bounded-io");
|
|
126
128
|
const flags_1 = require("../cli/flags"); // @implements A-SPEC-245.18 — the CLI's own flag reading, one source
|
|
127
129
|
// Resolve per-rm-target git facts (H1 git-aware guardrail): is each recursive-rm target a
|
|
@@ -2049,7 +2051,8 @@ function normalizeHookInput(raw, host = process.platform) {
|
|
|
2049
2051
|
}
|
|
2050
2052
|
}
|
|
2051
2053
|
const sessionId = str(r.session_id);
|
|
2052
|
-
|
|
2054
|
+
const agentId = str(r.agent_id);
|
|
2055
|
+
return { tool_name: psShell !== undefined ? 'Bash' : str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(sessionId ? { session_id: sessionId } : {}), ...(agentId ? { agent_id: agentId } : {}), ...(malformed ? { malformed: true } : {}),
|
|
2053
2056
|
...(ps !== null && 'unjudgeable' in ps ? { powershellUnjudgeable: ps.unjudgeable } : {}),
|
|
2054
2057
|
...(codexPs !== null ? { codexPowerShell: codexPs } : {}),
|
|
2055
2058
|
...(patchUnreadable ? { patchUnreadable: true } : {}), ...(shellMarked && !otherUnreadable ? { patchUnreadableCause: 'shell-marker' } : {}),
|
|
@@ -2089,8 +2092,20 @@ function preEditEvidenceGate(o) {
|
|
|
2089
2092
|
return null;
|
|
2090
2093
|
if (o.covered)
|
|
2091
2094
|
return null;
|
|
2092
|
-
const
|
|
2093
|
-
|
|
2095
|
+
const evidence = (0, impact_gate_1.loadEditEvidence)(o.projectRoot, o.relPath, o.declaredDigest, o.currentHead);
|
|
2096
|
+
const verdict = (0, impact_gate_1.evaluateEditEvidence)(evidence);
|
|
2097
|
+
const decision = (0, impact_gate_1.preEditEvidenceDecision)(verdict, o.mode);
|
|
2098
|
+
// @implements A-SPEC-333.4 — a clean allow clears the file from the commit reminder (recorded with the final allow)
|
|
2099
|
+
if (decision === null && verdict.decision === 'allow' && o.advisory)
|
|
2100
|
+
(0, advisory_line_1.adviseClean)(o.projectRoot, o.advisory, o.relPath);
|
|
2101
|
+
// @implements A-SPEC-333.2 — only a warn allow is shaped; a deny is said in full and touches no store
|
|
2102
|
+
if (decision?.permissionDecision !== 'allow' || !o.advisory)
|
|
2103
|
+
return decision;
|
|
2104
|
+
const detail = (0, advisory_line_1.advisoryDetail)({ artifactDigest: evidence.artifactDigest, traceGaps: evidence.traceGaps, head: o.currentHead, codes: verdict.reasons.map((r) => r.code) });
|
|
2105
|
+
const said = (0, advisory_line_1.adviseWarn)(o.projectRoot, o.advisory, verdict, o.relPath, detail, decision.permissionDecisionReason ?? '');
|
|
2106
|
+
if (said === undefined)
|
|
2107
|
+
return decision;
|
|
2108
|
+
return said === null ? { permissionDecision: 'allow' } : { ...decision, permissionDecisionReason: said };
|
|
2094
2109
|
}
|
|
2095
2110
|
function decideOnGateError(opts) {
|
|
2096
2111
|
if (opts.bypass) {
|
|
@@ -4406,6 +4421,7 @@ function judgeHook(input, specsDir, opts) {
|
|
|
4406
4421
|
// vouching for itself.
|
|
4407
4422
|
declaredDigest: process.env.HOLMES_EVIDENCE?.trim() || null,
|
|
4408
4423
|
currentHead: evidenceHead,
|
|
4424
|
+
...(opts.advisory ? { advisory: opts.advisory } : {}),
|
|
4409
4425
|
});
|
|
4410
4426
|
if (evidenceDecision) {
|
|
4411
4427
|
if (evidenceDecision.permissionDecision === 'allow')
|
|
@@ -4538,10 +4554,21 @@ if (require.main === module) {
|
|
|
4538
4554
|
})();
|
|
4539
4555
|
// @implements A-SPEC-245.4 — held through every pass below, settled once after the last one
|
|
4540
4556
|
const settlement = new approval_grants_1.GrantSettlement();
|
|
4557
|
+
// @implements A-SPEC-333.2, A-SPEC-333.4 — the session reading these warnings; records wait for the final decision
|
|
4558
|
+
// below. Compression only where the compaction signal is observed (Claude Code); elsewhere only the ledger row.
|
|
4559
|
+
const rawFields = (rawHookInput !== null && typeof rawHookInput === 'object' ? rawHookInput : {});
|
|
4560
|
+
const advisoryHarness = (0, heartbeat_1.hookHarnessOf)(rawHookInput, process.env);
|
|
4561
|
+
const advisory = input.session_id
|
|
4562
|
+
? { session: input.session_id, ...(input.agent_id ? { agent: input.agent_id } : {}), pending: [],
|
|
4563
|
+
compress: advisoryHarness === 'claude', harness: advisoryHarness ?? '', // A-SPEC-333.9 — the ledger names it
|
|
4564
|
+
...(typeof rawFields.transcript_path === 'string' ? { transcriptPath: rawFields.transcript_path } : {}),
|
|
4565
|
+
...(typeof rawFields.tool_use_id === 'string' ? { toolUseId: rawFields.tool_use_id } : {}) }
|
|
4566
|
+
: undefined;
|
|
4541
4567
|
const judged = evaluateHook(input, specsDirWired, {
|
|
4542
4568
|
projectRoot: hookProjectRoot,
|
|
4543
4569
|
approval: readApprovalFromEnv(),
|
|
4544
4570
|
settlement,
|
|
4571
|
+
...(advisory ? { advisory } : {}),
|
|
4545
4572
|
// Round 17: rm targets resolve from the directory the shell runs in (inside the project).
|
|
4546
4573
|
resolveRmSignals: (command) => resolveRmSignals(command, (0, write_target_2.shellBaseFor)(hookProjectRoot, input.tool_input.workdir, input.cwd), hookProjectRoot, specsDirWired),
|
|
4547
4574
|
resolveStagedStore: (command) => resolveStagedStore(command, hookProjectRoot, specsDirWired),
|
|
@@ -4562,9 +4589,13 @@ if (require.main === module) {
|
|
|
4562
4589
|
tool: input.tool_name, toolInput: input.tool_input })
|
|
4563
4590
|
: staged;
|
|
4564
4591
|
// @implements A-SPEC-778 — in a run, refusals are logged and a repeated code stops the run; elsewhere unchanged.
|
|
4565
|
-
const
|
|
4592
|
+
const settled = settleVerdict((hookRoot.anchored
|
|
4566
4593
|
? (0, run_refusals_1.applyRunRefusalStop)(roled, { projectRoot: hookProjectRoot, env: process.env, cwd: input.cwd, sessionId: input.session_id, tool: input.tool_name })
|
|
4567
4594
|
: judged), settlement);
|
|
4595
|
+
// @implements A-SPEC-333.4 — an allowed `git commit` in a Claude session names the files still warned (information only)
|
|
4596
|
+
const reminder = advisory?.compress && settled.permissionDecision === 'allow' && input.tool_name === 'Bash'
|
|
4597
|
+
&& (0, advisory_line_1.isGitCommit)(input.tool_input?.command ?? '') ? (0, advisory_line_1.commitReminder)(hookProjectRoot, advisory) : null;
|
|
4598
|
+
const out = reminder ? { ...settled, permissionDecisionReason: [settled.permissionDecisionReason, reminder].filter(Boolean).join('\n') } : settled;
|
|
4568
4599
|
io.out(JSON.stringify({ hookSpecificOutput: hookOutputFor(input.tool_name, out) }));
|
|
4569
4600
|
// N3 provenance: record the audit-critical decision classes on the tamper-evident chain —
|
|
4570
4601
|
// every DENY, and every ALLOW that was unlocked by an out-of-band approval. Fail-open: a
|
|
@@ -4589,6 +4620,8 @@ if (require.main === module) {
|
|
|
4589
4620
|
// recorded as approved under a token that had expired in 2000. Under a session key that made
|
|
4590
4621
|
// the whole log 'approved-action' and hid the real openings. Ask the counterfactual instead:
|
|
4591
4622
|
// would this same call have been denied with no approval in hand?
|
|
4623
|
+
// A-SPEC-333.2, A-SPEC-333.4 — invariant: this re-ask never carries `advisory`. It reads no warning store and adds
|
|
4624
|
+
// nothing to `advisory.pending`, so only what the decision above said can be recorded below.
|
|
4592
4625
|
const withoutApproval = out.permissionDecision === 'allow' && valid
|
|
4593
4626
|
? evaluateHook(input, specsDirWired, {
|
|
4594
4627
|
projectRoot: hookProjectRoot,
|
|
@@ -4635,6 +4668,12 @@ if (require.main === module) {
|
|
|
4635
4668
|
}
|
|
4636
4669
|
}
|
|
4637
4670
|
catch { /* provenance must never break the gate */ }
|
|
4671
|
+
// @implements A-SPEC-333.2, A-SPEC-333.4 — the last act before the return: recorded only now, and only what this
|
|
4672
|
+
// allow actually carried (a deny records nothing)
|
|
4673
|
+
try {
|
|
4674
|
+
(0, advisory_line_1.commitAdvisory)(hookProjectRoot, advisory, out);
|
|
4675
|
+
}
|
|
4676
|
+
catch { /* an unrecorded warning is said again */ }
|
|
4638
4677
|
if (out.permissionDecision === 'deny') {
|
|
4639
4678
|
// Belt-and-suspenders: Claude Code's exit-code-2 contract feeds STDERR back to the
|
|
4640
4679
|
// model as the block reason, while permissionDecisionReason in the stdout JSON is
|
|
@@ -37,7 +37,7 @@ exports.detectInstallMode = detectInstallMode;
|
|
|
37
37
|
exports.buildSessionStartOutput = buildSessionStartOutput;
|
|
38
38
|
exports.staleWiredServerLine = staleWiredServerLine;
|
|
39
39
|
exports.driftNudge = driftNudge;
|
|
40
|
-
// @implements A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1, A-SPEC-251.5
|
|
40
|
+
// @implements A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1, A-SPEC-251.5, A-SPEC-333.2, A-SPEC-333.4, A-SPEC-333.5
|
|
41
41
|
// The SessionStart banner hook. It emits the intro (+ optional update notice) as additionalContext,
|
|
42
42
|
// which Claude Code delivers to BOTH the human transcript and the agent context — the "human and
|
|
43
43
|
// agent" delivery REQ-531 asks for. The update refresh is a DETACHED, fire-and-forget child so the
|
|
@@ -184,6 +184,22 @@ if (require.main === module) {
|
|
|
184
184
|
let buf = '';
|
|
185
185
|
process.stdin.on('data', (c) => (buf += c));
|
|
186
186
|
process.stdin.on('end', () => {
|
|
187
|
+
// @implements A-SPEC-333.2, A-SPEC-333.4 — the first act: every SessionStart (startup, resume, clear, compact) opens a
|
|
188
|
+
// new warning epoch for the session, so what may be gone from the reader's context is said again. Nothing before it
|
|
189
|
+
// can fail and leave an old epoch standing. Fail-quiet: no epoch means every warning is said in full.
|
|
190
|
+
try {
|
|
191
|
+
const raw = JSON.parse(buf || '{}');
|
|
192
|
+
if (typeof raw.session_id === 'string' && raw.session_id !== '') {
|
|
193
|
+
const { openEpoch } = require('../guardrail/advisory-line');
|
|
194
|
+
const { resolveProjectRoot } = require('../project/root');
|
|
195
|
+
// A-SPEC-333.5 — the source tells the epoch whether the next compact boundary is its own
|
|
196
|
+
openEpoch(resolveProjectRoot(process.cwd()).root, raw.session_id, {
|
|
197
|
+
...(typeof raw.transcript_path === 'string' ? { transcriptPath: raw.transcript_path } : {}),
|
|
198
|
+
...(typeof raw.source === 'string' ? { source: raw.source } : {})
|
|
199
|
+
});
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
catch { /* the banner is never a gate */ }
|
|
187
203
|
try {
|
|
188
204
|
const out = buildSessionStartOutput({
|
|
189
205
|
version: pkgVersion(),
|
|
@@ -4,6 +4,19 @@ import { DecisionRecord, DecisionCitation } from '../../rtm/rtm-builder';
|
|
|
4
4
|
import { ContentSource } from '../../context/bundler';
|
|
5
5
|
import { MaintenanceGroundTruth, MaintenanceAnalysis } from '../maintenance-analyze';
|
|
6
6
|
import { Basis } from '../basis';
|
|
7
|
+
/**
|
|
8
|
+
* @implements A-SPEC-293.1 — the working tree's changes against HEAD, tracked and untracked, bounded; undefined when there
|
|
9
|
+
* are none or git cannot say (the caller then keeps the axis disclosed as not assessed).
|
|
10
|
+
* @implements A-SPEC-333.8 — both lists are relative to the analysed root (`--relative`, as `ls-files` already is), so a
|
|
11
|
+
* change elsewhere in the repository is not this analysis's; both children run inert under one deadline; governing
|
|
12
|
+
* documents are taken first, and a cut list says so.
|
|
13
|
+
* @implements A-SPEC-333.9 — a timeout here is the analysis's own deadline, not the root's slowness: it is not recorded,
|
|
14
|
+
* so it blocks no later git call for this root.
|
|
15
|
+
*/
|
|
16
|
+
export declare function workingTreeChanges(root: string, deadlineMs?: number): {
|
|
17
|
+
files: string[];
|
|
18
|
+
truncated: boolean;
|
|
19
|
+
} | undefined;
|
|
7
20
|
export interface MaintenanceAnalysisContext {
|
|
8
21
|
listSpecs(): Promise<Spec[]>;
|
|
9
22
|
foreignRootReason(root?: string): string | null;
|
|
@@ -33,8 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.workingTreeChanges = workingTreeChanges;
|
|
36
37
|
exports.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
|
|
37
|
-
// @implements A-SPEC-476.1, A-SPEC-745, A-SPEC-469.1,A-SPEC-469.2, A-SPEC-741, A-SPEC-741.1, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734, A-SPEC-278.3
|
|
38
|
+
// @implements A-SPEC-476.1, A-SPEC-745, A-SPEC-469.1,A-SPEC-469.2, A-SPEC-741, A-SPEC-741.1, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734, A-SPEC-278.3, A-SPEC-293.1, A-SPEC-333.8, A-SPEC-333.9
|
|
38
39
|
const fs = __importStar(require("node:fs"));
|
|
39
40
|
const path = __importStar(require("node:path"));
|
|
40
41
|
const node_child_process_1 = require("node:child_process");
|
|
@@ -60,6 +61,47 @@ const maintenance_analyze_1 = require("../maintenance-analyze");
|
|
|
60
61
|
const maintenance_evidence_1 = require("../maintenance-evidence");
|
|
61
62
|
const defuse_bound_1 = require("../defuse-bound");
|
|
62
63
|
const bounded_io_1 = require("../../project/bounded-io");
|
|
64
|
+
/** At most this many paths from the working tree's own diff (A-SPEC-293.1). */
|
|
65
|
+
const ARCHITECTURE_BASIS_MAX = 2000;
|
|
66
|
+
/** The two git children together finish within this (A-SPEC-333.8). */
|
|
67
|
+
const ARCHITECTURE_BASIS_DEADLINE_MS = 5000;
|
|
68
|
+
/**
|
|
69
|
+
* @implements A-SPEC-293.1 — the working tree's changes against HEAD, tracked and untracked, bounded; undefined when there
|
|
70
|
+
* are none or git cannot say (the caller then keeps the axis disclosed as not assessed).
|
|
71
|
+
* @implements A-SPEC-333.8 — both lists are relative to the analysed root (`--relative`, as `ls-files` already is), so a
|
|
72
|
+
* change elsewhere in the repository is not this analysis's; both children run inert under one deadline; governing
|
|
73
|
+
* documents are taken first, and a cut list says so.
|
|
74
|
+
* @implements A-SPEC-333.9 — a timeout here is the analysis's own deadline, not the root's slowness: it is not recorded,
|
|
75
|
+
* so it blocks no later git call for this root.
|
|
76
|
+
*/
|
|
77
|
+
function workingTreeChanges(root, deadlineMs = ARCHITECTURE_BASIS_DEADLINE_MS) {
|
|
78
|
+
const started = Date.now();
|
|
79
|
+
const run = (args) => {
|
|
80
|
+
const left = deadlineMs - (Date.now() - started);
|
|
81
|
+
if (left <= 0)
|
|
82
|
+
return undefined;
|
|
83
|
+
const r = (0, bounded_io_1.gitOnce)(root, args, 'worktree', { timeout: left, env: (0, bounded_io_1.inertGitConfig)((0, root_1.cleanSubprocessEnv)()), record: false });
|
|
84
|
+
return r.status === 0 && !r.error ? r.stdout : undefined;
|
|
85
|
+
};
|
|
86
|
+
const tracked = run(['diff', '--name-only', '-z', '--relative', 'HEAD']);
|
|
87
|
+
const untracked = tracked === undefined ? undefined : run(['ls-files', '--others', '--exclude-standard', '-z']);
|
|
88
|
+
if (tracked === undefined || untracked === undefined)
|
|
89
|
+
return undefined;
|
|
90
|
+
const all = new Set();
|
|
91
|
+
for (const f of `${tracked}\0${untracked}`.split('\0')) {
|
|
92
|
+
// the governance store's runtime state (evidence, ledgers, caches) is not a change: an analysis persisted a moment
|
|
93
|
+
// ago must not change the next one. Its documents (.ax/decisions, .ax/specs) are kept: they are the axis.
|
|
94
|
+
if (f === '' || (f.startsWith('.ax/') && !f.startsWith('.ax/decisions/') && !f.startsWith('.ax/specs/')))
|
|
95
|
+
continue;
|
|
96
|
+
all.add(f);
|
|
97
|
+
}
|
|
98
|
+
if (all.size === 0)
|
|
99
|
+
return undefined;
|
|
100
|
+
const governing = (0, test_scope_1.architectureGoverningFiles)([...all]);
|
|
101
|
+
const rest = [...all].filter((f) => !governing.includes(f));
|
|
102
|
+
const files = [...governing, ...rest].slice(0, ARCHITECTURE_BASIS_MAX);
|
|
103
|
+
return { files, truncated: all.size > files.length };
|
|
104
|
+
}
|
|
63
105
|
/** @implements A-SPEC-759 — at most this many changed files have their HEAD text read for the missing-new-file finding. */
|
|
64
106
|
const MISSING_NEW_FILES_PRIOR_READS = 50;
|
|
65
107
|
function createMaintenanceAnalysisHandlers(context) {
|
|
@@ -82,6 +124,11 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
82
124
|
head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER, timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
|
|
83
125
|
}
|
|
84
126
|
catch { /* non-git */ }
|
|
127
|
+
// @implements A-SPEC-293.1 — no list from the caller: the working tree's own diff assesses the architecture axis
|
|
128
|
+
// (and nothing else). A clean or non-git tree passes nothing, so the axis stays disclosed as not assessed.
|
|
129
|
+
const basis = a.changedFiles === undefined && head !== '' ? workingTreeChanges(root) : undefined;
|
|
130
|
+
const architectureBasis = basis?.files;
|
|
131
|
+
const changedFilesSource = a.changedFiles !== undefined ? 'caller' : architectureBasis ? 'git-diff-default' : 'none';
|
|
85
132
|
const unsupportedLanguages = new Set();
|
|
86
133
|
// @implements A-SPEC-741 — the paths too, so the analysis can tell an unreadable file that may
|
|
87
134
|
// be this request's target from one that is unrelated. Bounded: a vendored tree must not grow it.
|
|
@@ -124,6 +171,7 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
124
171
|
specFingerprint: `count:${specs.length}/fp:${detail.specs ?? 'unknown'}`,
|
|
125
172
|
},
|
|
126
173
|
changedFiles: a.changedFiles,
|
|
174
|
+
...(architectureBasis ? { architectureBasis } : {}),
|
|
127
175
|
// @implements A-SPEC-290 — the stored run record. Freshness is judged inside the analysis
|
|
128
176
|
// against its own basis, so a record from another commit is reported as stale rather than
|
|
129
177
|
// quietly used.
|
|
@@ -346,6 +394,14 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
346
394
|
const blind = context.specStoreBlindReason(root, specs.length);
|
|
347
395
|
if (blind !== null)
|
|
348
396
|
result.unknowns = [blind, ...result.unknowns];
|
|
397
|
+
result.changedFilesSource = changedFilesSource;
|
|
398
|
+
// @implements A-SPEC-333.8 — what the default basis is, and is not, said where the answer is read
|
|
399
|
+
if (basis) {
|
|
400
|
+
result.unknowns = [...result.unknowns,
|
|
401
|
+
"The architecture axis was assessed from the working tree's diff against HEAD under this root; it holds no file the request has yet to change, so pass changedFiles to assess those."];
|
|
402
|
+
if (basis.truncated)
|
|
403
|
+
result.unknowns.push(`The architecture basis was cut at ${ARCHITECTURE_BASIS_MAX} working-tree files (decision and C-SPEC documents first); files past the cut were not assessed.`);
|
|
404
|
+
}
|
|
349
405
|
if (a.persist) {
|
|
350
406
|
// @implements A-SPEC-277 — record WHAT WAS ANALYSED, not just which paths. HEAD cannot see
|
|
351
407
|
// an uncommitted edit to the analysed file; a content digest can.
|
|
@@ -360,7 +416,8 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
360
416
|
// product actually predicted.
|
|
361
417
|
result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests,
|
|
362
418
|
// @implements A-SPEC-278.3 — the request and the caller's changed files travel with the prediction.
|
|
363
|
-
|
|
419
|
+
// A-SPEC-293.1 — the default diff is never recorded as the caller's list (the gate reads that as "named")
|
|
420
|
+
{ request: a.request, changedFiles: a.changedFiles, changedFilesSource }));
|
|
364
421
|
}
|
|
365
422
|
// @implements A-SPEC-578.5 — the response, and only the response, is bounded. Measured
|
|
366
423
|
// 2026-09-09: the full shape is 187,174 characters (~47k tokens) and the harness refuses
|