@holmes-lab/holmes-kit 0.40.0 → 0.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +79 -5
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-context.js +4 -3
  5. package/dist/holmes/cli/approve.js +22 -12
  6. package/dist/holmes/cli/autonomy.d.ts +21 -0
  7. package/dist/holmes/cli/autonomy.js +35 -5
  8. package/dist/holmes/cli/doctor.js +58 -6
  9. package/dist/holmes/cli/index.js +394 -267
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  12. package/dist/holmes/cli/interactive-prompt.js +98 -16
  13. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  14. package/dist/holmes/cli/ledger-witness.js +212 -0
  15. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  16. package/dist/holmes/cli/playbook-skills.js +26 -349
  17. package/dist/holmes/config/config.d.ts +21 -0
  18. package/dist/holmes/config/config.js +22 -3
  19. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  20. package/dist/holmes/governance/approval-queue.js +279 -9
  21. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  22. package/dist/holmes/governance/autonomous-shell.js +157 -4
  23. package/dist/holmes/governance/autonomy.d.ts +216 -0
  24. package/dist/holmes/governance/autonomy.js +1162 -10
  25. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  26. package/dist/holmes/governance/install-manifest.js +144 -14
  27. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  28. package/dist/holmes/governance/ledger-witness.js +296 -0
  29. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  30. package/dist/holmes/governance/provenance-chain.js +23 -4
  31. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  32. package/dist/holmes/governance/push-gate-runner.js +40 -3
  33. package/dist/holmes/governance/push-gate.d.ts +13 -2
  34. package/dist/holmes/governance/push-gate.js +106 -14
  35. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  36. package/dist/holmes/governance/recorded-pairs.js +25 -1
  37. package/dist/holmes/governance/session-context.d.ts +7 -0
  38. package/dist/holmes/governance/session-context.js +34 -6
  39. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  40. package/dist/holmes/guardrail/advisory-line.js +718 -0
  41. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  42. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  43. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  44. package/dist/holmes/guardrail/command-traits.js +379 -0
  45. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  46. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  47. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  48. package/dist/holmes/guardrail/impact-gate.js +32 -5
  49. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  50. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  51. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  52. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  53. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  54. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  55. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  56. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  57. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  58. package/dist/holmes/guardrail/write-target.js +7 -1
  59. package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
  60. package/dist/holmes/hooks/pre-tool-use.js +1466 -14
  61. package/dist/holmes/hooks/session-start.js +27 -1
  62. package/dist/holmes/hooks/stop.d.ts +7 -0
  63. package/dist/holmes/hooks/stop.js +39 -2
  64. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  65. package/dist/holmes/mcp/elicit-approval.js +5 -2
  66. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  67. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  68. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  69. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  70. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  71. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  72. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  73. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  74. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  75. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  76. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  77. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  78. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  79. package/dist/holmes/mcp/handlers/test-execution.js +201 -21
  80. package/dist/holmes/mcp/handlers.d.ts +473 -8
  81. package/dist/holmes/mcp/handlers.js +6 -1
  82. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  83. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  84. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  85. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  86. package/dist/holmes/mcp/tool-schemas.js +16 -10
  87. package/dist/holmes/project/baseline.d.ts +15 -2
  88. package/dist/holmes/project/baseline.js +11 -6
  89. package/dist/holmes/project/bounded-io.d.ts +1 -0
  90. package/dist/holmes/project/bounded-io.js +4 -2
  91. package/dist/holmes/project/change-source.d.ts +4 -0
  92. package/dist/holmes/project/change-source.js +13 -5
  93. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  94. package/dist/holmes/project/playbook-reference.js +259 -0
  95. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  96. package/dist/holmes/project/playbook-skill-states.js +396 -0
  97. package/dist/holmes/project/root.d.ts +9 -1
  98. package/dist/holmes/project/root.js +26 -3
  99. package/dist/holmes/project/running-package.d.ts +15 -0
  100. package/dist/holmes/project/running-package.js +87 -0
  101. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  102. package/dist/holmes/review/evidence-mode.js +33 -0
  103. package/dist/holmes/review/head-worktree.d.ts +55 -0
  104. package/dist/holmes/review/head-worktree.js +329 -0
  105. package/dist/holmes/review/mrp.js +13 -3
  106. package/dist/holmes/review/run-provenance.d.ts +45 -0
  107. package/dist/holmes/review/run-provenance.js +314 -0
  108. package/dist/holmes/review/test-evidence.d.ts +174 -0
  109. package/dist/holmes/review/test-evidence.js +330 -2
  110. package/dist/holmes/review/test-reports.d.ts +94 -0
  111. package/dist/holmes/review/test-reports.js +382 -0
  112. package/dist/holmes/review/test-runner.d.ts +178 -65
  113. package/dist/holmes/review/test-runner.js +551 -319
  114. package/dist/holmes/review/test-units.d.ts +159 -0
  115. package/dist/holmes/review/test-units.js +814 -0
  116. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  117. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  118. package/package.json +5 -2
  119. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -2,6 +2,22 @@ import { EntityByteChange, entityLockOwner } from './entity-transaction';
2
2
  import { EntityGitDocuments, EntityGitMergedSources } from './entity-integration';
3
3
  import { entitySourcePublicationOwner } from './entity-renumber-transaction';
4
4
  import { EntityRenumberEntry } from './entity-renumber';
5
+ import type { SpecTransition } from '../governance/approval-queue';
6
+ type TransitionStep = {
7
+ phase: string;
8
+ specId?: string;
9
+ change?: {
10
+ locator?: string;
11
+ after?: string | null;
12
+ };
13
+ };
14
+ /**
15
+ * @implements A-SPEC-794.92 (M-1) — an un-seal step whose document is later published as `outdated` is a retirement,
16
+ * not an un-seal: it needs spec-retire authority and records spec-retired, as spec_retire does outside an integration.
17
+ */
18
+ export declare function retiredSpecIds(plan: {
19
+ steps: ReadonlyArray<TransitionStep>;
20
+ }): Set<string>;
5
21
  export interface EntityIntegrationTransitions {
6
22
  unseal: Array<{
7
23
  entityId: string;
@@ -108,7 +124,7 @@ export interface EntityIntegrationPlan {
108
124
  export declare function validateEntityIntegrationPlan(value: unknown): EntityIntegrationPlan;
109
125
  export declare function entityIntegrationTarget(plan: EntityIntegrationPlan): string;
110
126
  /** Internal execution core; the public adapter supplies current authority and durable audit. */
111
- export declare function applyEntityIntegration(root: string, inspected: unknown, authorize: (specId?: string) => void, audit: (plan: EntityIntegrationPlan, verifyOnly?: boolean, renumbered?: NonNullable<EntityIntegrationCandidate['renumbered']>) => void, beforePublish?: (plan: EntityIntegrationPlan, index: number) => void): Promise<{
127
+ export declare function applyEntityIntegration(root: string, inspected: unknown, authorize: (specId?: string, transition?: SpecTransition) => void, audit: (plan: EntityIntegrationPlan, verifyOnly?: boolean, renumbered?: NonNullable<EntityIntegrationCandidate['renumbered']>) => void, beforePublish?: (plan: EntityIntegrationPlan, index: number) => void): Promise<{
112
128
  ok: true;
113
129
  state: 'completed';
114
130
  operationId: string;
@@ -130,7 +146,7 @@ export declare function abandonEntityIntegration(root: string, inspected: unknow
130
146
  untouched: string[];
131
147
  preserved: string[];
132
148
  }>;
133
- export declare function recoverEntityIntegration(root: string, inspected: EntityIntegrationRecoveryInspection, authorize: (specId?: string) => void, audit: (plan: EntityIntegrationPlan, verifyOnly?: boolean) => void, beforePublish?: (plan: EntityIntegrationPlan, index: number) => void): Promise<{
149
+ export declare function recoverEntityIntegration(root: string, inspected: EntityIntegrationRecoveryInspection, authorize: (specId?: string, transition?: SpecTransition) => void, audit: (plan: EntityIntegrationPlan, verifyOnly?: boolean) => void, beforePublish?: (plan: EntityIntegrationPlan, index: number) => void): Promise<{
134
150
  ok: true;
135
151
  state: 'completed';
136
152
  operationId: string;
@@ -177,3 +193,4 @@ export declare function planEntityIntegrationCandidate(root: string, revisions:
177
193
  left: string;
178
194
  right: string;
179
195
  }, storeLocator: string): Promise<EntityIntegrationCandidate>;
196
+ export {};
@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.retiredSpecIds = retiredSpecIds;
36
37
  exports.prepareEntityIntegrationTransitions = prepareEntityIntegrationTransitions;
37
38
  exports.validateEntityIntegrationPlan = validateEntityIntegrationPlan;
38
39
  exports.entityIntegrationTarget = entityIntegrationTarget;
@@ -47,7 +48,7 @@ exports.prepareEntityIntegrationPlan = prepareEntityIntegrationPlan;
47
48
  exports.reviewEntityIntegration = reviewEntityIntegration;
48
49
  exports.compileEntityIntegrationSteps = compileEntityIntegrationSteps;
49
50
  exports.planEntityIntegrationCandidate = planEntityIntegrationCandidate;
50
- // @implements A-SPEC-629
51
+ // @implements A-SPEC-629, A-SPEC-794.90, A-SPEC-794.92, A-SPEC-794.95
51
52
  // @implements A-SPEC-645
52
53
  // @implements A-SPEC-641
53
54
  // @implements A-SPEC-640
@@ -72,6 +73,64 @@ const spec_digest_1 = require("./spec-digest");
72
73
  const transition_policy_1 = require("./transition-policy");
73
74
  const node_crypto_1 = require("node:crypto");
74
75
  const workspace_identity_1 = require("../project/workspace-identity");
76
+ /**
77
+ * @implements A-SPEC-794.92 (M-1) — an un-seal step whose document is later published as `outdated` is a retirement,
78
+ * not an un-seal: it needs spec-retire authority and records spec-retired, as spec_retire does outside an integration.
79
+ */
80
+ function retiredSpecIds(plan) {
81
+ const out = new Set();
82
+ // A-SPEC-794.95 (A-M3) — judged by the spec, not the locator: a later document step is the spec's when it names the
83
+ // spec, sits at the un-sealed locator, or parses to the spec's id. Published as outdated → retired; the un-sealed
84
+ // document deleted and no document of the spec published again → retired (a deletion withdraws the seal as well)
85
+ const parsed = (after) => {
86
+ try {
87
+ const s = (0, spec_parser_1.parseSpec)(Buffer.from(after, 'base64').toString('utf8'));
88
+ return { id: s.id, status: s.status };
89
+ }
90
+ catch {
91
+ return null;
92
+ }
93
+ };
94
+ plan.steps.forEach((step, i) => {
95
+ if (step.phase !== 'unseal' || !step.specId || !step.change?.locator)
96
+ return;
97
+ const id = step.specId, locator = step.change.locator;
98
+ let deleted = false, published = null;
99
+ for (const s of plan.steps.slice(i + 1)) {
100
+ if (s.phase !== 'document' || !s.change)
101
+ continue;
102
+ const after = s.change.after;
103
+ if (typeof after !== 'string') {
104
+ if (s.change.locator === locator || s.specId === id)
105
+ deleted = true;
106
+ continue;
107
+ }
108
+ const p = parsed(after);
109
+ if (s.specId === id || s.change.locator === locator || p?.id === id)
110
+ published = p?.status ?? 'unreadable';
111
+ }
112
+ if (published === 'outdated' || (published === null && deleted))
113
+ out.add(id);
114
+ });
115
+ return out;
116
+ }
117
+ /** @implements A-SPEC-794.90 — each spec step's (id, transition): an un-seal step un-seals, an approval step seals. */
118
+ function stepTransitions(plan) {
119
+ const seen = new Set();
120
+ const out = [];
121
+ const retired = retiredSpecIds(plan);
122
+ for (const step of plan.steps) {
123
+ if (!step.specId)
124
+ continue;
125
+ const t = step.phase === 'unseal' ? (retired.has(step.specId) ? 'retire' : 'unseal') : 'seal';
126
+ const key = `${step.specId}\u0000${t}`;
127
+ if (!seen.has(key)) {
128
+ seen.add(key);
129
+ out.push([step.specId, t]);
130
+ }
131
+ }
132
+ return out.sort((a, b) => (a[0] + a[1]).localeCompare(b[0] + b[1]));
133
+ }
75
134
  /** Produces document transitions only; authority and durable application belong to the executor. */
76
135
  function prepareEntityIntegrationTransitions(current, desired, readFile) {
77
136
  const graph = (entries) => {
@@ -256,9 +315,10 @@ async function applyEntityIntegration(root, inspected, authorize, audit, beforeP
256
315
  if (integrationRead(root, '.ax/state/entity-completed/' + plan.operationId + '/journal.json'))
257
316
  throw new entity_transaction_1.EntityStoreError('recovery-required', 'This operation already has a completion receipt; verify it through recovery.');
258
317
  const program = JSON.stringify(plan), journal = JSON.stringify({ schema: 'holmes-entity-integration-journal/1', plan, storeOwner, sourceOwner });
259
- const progress = integrationProgress(root, plan), targets = [...new Set(plan.steps.flatMap(step => step.specId ? [step.specId] : []))].sort();
260
- const authority = () => { authorize(); for (const id of targets)
261
- authorize(id); };
318
+ const progress = integrationProgress(root, plan);
319
+ // A-SPEC-794.90 — each step's own kind before publication: an un-seal step asks spec-unseal here, not only in the audit
320
+ const authority = () => { authorize(); for (const [id, transition] of stepTransitions(plan))
321
+ authorize(id, transition); };
262
322
  let persisted = false;
263
323
  const verify = () => {
264
324
  if (JSON.stringify(plan) !== program)
@@ -359,9 +419,10 @@ async function recoverEntityIntegration(root, inspected, authorize, audit, befor
359
419
  const plan = observed.plan, program = JSON.stringify(plan), directory = '.ax/state/entity-transactions/' + plan.operationId, journalFile = directory + '/journal.json';
360
420
  const journalBytes = integrationRead(root, journalFile);
361
421
  const journal = JSON.parse(journalBytes.toString('utf8'));
362
- const targets = observed.completionVersion ? [] : [...new Set(plan.steps.flatMap(step => step.specId ? [step.specId] : []))].sort();
363
- const authority = () => { authorize(); for (const id of targets)
364
- authorize(id); };
422
+ // A-SPEC-794.90 — each step's own kind, as in apply
423
+ const steps = observed.completionVersion ? [] : stepTransitions(plan);
424
+ const authority = () => { authorize(); for (const [id, transition] of steps)
425
+ authorize(id, transition); };
365
426
  const identity = () => {
366
427
  const current = (0, workspace_identity_1.workspaceIdentity)(root);
367
428
  if (current.state !== 'registered' || current.workspaceId !== plan.workspaceId)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209, A-SPEC-794.58",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.40.0",
4
+ "version": "0.41.0",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",
@@ -61,8 +61,11 @@
61
61
  "**/src/**/*.test.ts"
62
62
  ],
63
63
  "testTimeout": 30000,
64
+ "globalSetup": "<rootDir>/src/holmes/test-support/repo-artifacts-global.ts",
65
+ "globalTeardown": "<rootDir>/src/holmes/test-support/repo-artifacts-global.ts",
64
66
  "setupFilesAfterEnv": [
65
- "<rootDir>/src/holmes/test-support/jest-timeouts-setup.ts"
67
+ "<rootDir>/src/holmes/test-support/jest-timeouts-setup.ts",
68
+ "<rootDir>/src/holmes/test-support/own-repo-judge-setup.ts"
66
69
  ],
67
70
  "maxWorkers": "50%",
68
71
  "roots": [
@@ -23,7 +23,8 @@ npm publish 는 **비가역·외부노출**이라 **게시는 오너가 정합
23
23
  거부하고, 시험 영수증은 같은 HEAD만 받는다. 개발 트리에 추적되지 않은 파일이 있으면 릴리스 커밋의 깨끗한
24
24
  worktree에서 진행한다.
25
25
  1. `npm run typecheck` (타입 오류 0건)
26
- 2. 전체 스위트 green — `mcp__holmes-kit__test_run`(HEAD~1..HEAD) 또는 `npx jest`. 부하가 높으면 대시보드
26
+ 2. 전체 스위트 green — `mcp__holmes-kit__test_run({root, full: true})`. 범위 실행(`HEAD~1..HEAD`)과 `npx jest`는
27
+ push 증빙을 남기지 않는다(A-SPEC-128.2, 128.4). 부하가 높으면 대시보드
27
28
  canary(A-SPEC-435)가 타임아웃할 수 있으니 부하를 낮춘 뒤 재실행한다(코드가 아니라 부하 문제).
28
29
  3. `npm run build` (`dist/` 최신 + `.build-id`).
29
30