@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.
Files changed (56) hide show
  1. package/CHANGELOG.md +234 -0
  2. package/README.md +70 -4
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/index.js +25 -19
  5. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  6. package/dist/holmes/cli/interactive-prompt.js +98 -16
  7. package/dist/holmes/config/config.d.ts +17 -0
  8. package/dist/holmes/config/config.js +13 -1
  9. package/dist/holmes/governance/autonomy.d.ts +7 -0
  10. package/dist/holmes/governance/autonomy.js +36 -5
  11. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  12. package/dist/holmes/governance/push-gate-runner.js +40 -3
  13. package/dist/holmes/governance/push-gate.d.ts +13 -2
  14. package/dist/holmes/governance/push-gate.js +106 -14
  15. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  16. package/dist/holmes/guardrail/advisory-line.js +718 -0
  17. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  18. package/dist/holmes/guardrail/impact-gate.js +32 -5
  19. package/dist/holmes/hooks/pre-tool-use.d.ts +11 -0
  20. package/dist/holmes/hooks/pre-tool-use.js +44 -5
  21. package/dist/holmes/hooks/session-start.js +17 -1
  22. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  23. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  24. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  25. package/dist/holmes/mcp/handlers/test-execution.js +199 -21
  26. package/dist/holmes/mcp/handlers.d.ts +468 -3
  27. package/dist/holmes/mcp/handlers.js +5 -1
  28. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  29. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  30. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  31. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  32. package/dist/holmes/mcp/tool-schemas.js +13 -7
  33. package/dist/holmes/project/baseline.d.ts +15 -2
  34. package/dist/holmes/project/baseline.js +11 -6
  35. package/dist/holmes/project/bounded-io.d.ts +1 -0
  36. package/dist/holmes/project/bounded-io.js +4 -2
  37. package/dist/holmes/project/change-source.d.ts +4 -0
  38. package/dist/holmes/project/change-source.js +13 -5
  39. package/dist/holmes/project/root.js +3 -1
  40. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  41. package/dist/holmes/review/evidence-mode.js +33 -0
  42. package/dist/holmes/review/head-worktree.d.ts +55 -0
  43. package/dist/holmes/review/head-worktree.js +329 -0
  44. package/dist/holmes/review/mrp.js +13 -3
  45. package/dist/holmes/review/run-provenance.d.ts +45 -0
  46. package/dist/holmes/review/run-provenance.js +314 -0
  47. package/dist/holmes/review/test-evidence.d.ts +174 -0
  48. package/dist/holmes/review/test-evidence.js +330 -2
  49. package/dist/holmes/review/test-reports.d.ts +94 -0
  50. package/dist/holmes/review/test-reports.js +382 -0
  51. package/dist/holmes/review/test-runner.d.ts +176 -65
  52. package/dist/holmes/review/test-runner.js +531 -316
  53. package/dist/holmes/review/test-units.d.ts +159 -0
  54. package/dist/holmes/review/test-units.js +814 -0
  55. package/package.json +1 -1
  56. 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
- // Lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal.
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
- return { tool_name: psShell !== undefined ? 'Bash' : str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(sessionId ? { session_id: sessionId } : {}), ...(malformed ? { malformed: true } : {}),
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 verdict = (0, impact_gate_1.evaluateEditEvidence)((0, impact_gate_1.loadEditEvidence)(o.projectRoot, o.relPath, o.declaredDigest, o.currentHead));
2093
- return (0, impact_gate_1.preEditEvidenceDecision)(verdict, o.mode);
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 out = settleVerdict((hookRoot.anchored
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
- { request: a.request, changedFiles: a.changedFiles }));
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