@holmes-lab/holmes-kit 0.35.25 → 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.
Files changed (125) hide show
  1. package/CHANGELOG.md +298 -0
  2. package/README.md +3 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +31 -1
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +25 -1
  13. package/dist/holmes/cli/doctor.js +153 -7
  14. package/dist/holmes/cli/index.js +99 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  27. package/dist/holmes/cli/runtime-binding.js +96 -7
  28. package/dist/holmes/cli/test-platform.d.ts +16 -0
  29. package/dist/holmes/cli/test-platform.js +31 -1
  30. package/dist/holmes/config/config.d.ts +49 -0
  31. package/dist/holmes/config/config.js +146 -3
  32. package/dist/holmes/config/project-caps.d.ts +21 -0
  33. package/dist/holmes/config/project-caps.js +114 -0
  34. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  35. package/dist/holmes/governance/approval-queue.js +48 -6
  36. package/dist/holmes/governance/autonomy.d.ts +6 -0
  37. package/dist/holmes/governance/autonomy.js +21 -0
  38. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  39. package/dist/holmes/governance/push-gate-runner.js +49 -1
  40. package/dist/holmes/governance/replica-id.d.ts +9 -0
  41. package/dist/holmes/governance/replica-id.js +44 -7
  42. package/dist/holmes/governance/role-policy.d.ts +41 -1
  43. package/dist/holmes/governance/role-policy.js +137 -20
  44. package/dist/holmes/governance/run-mode.d.ts +14 -0
  45. package/dist/holmes/governance/run-mode.js +120 -0
  46. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  47. package/dist/holmes/governance/tool-actions.js +121 -0
  48. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  49. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  50. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  51. package/dist/holmes/guardrail/classification-mode.js +135 -0
  52. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  53. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  54. package/dist/holmes/guardrail/phase.d.ts +2 -1
  55. package/dist/holmes/guardrail/phase.js +22 -8
  56. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  57. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  58. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  59. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  60. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  61. package/dist/holmes/guardrail/risk-classifier.js +242 -26
  62. package/dist/holmes/guardrail/risk-types.d.ts +15 -0
  63. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  64. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  65. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  66. package/dist/holmes/guardrail/run-refusals.js +348 -0
  67. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  68. package/dist/holmes/guardrail/run-stages.js +188 -0
  69. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  70. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  71. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  72. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  73. package/dist/holmes/guardrail/shell-words.js +7 -7
  74. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  75. package/dist/holmes/guardrail/write-target.js +118 -16
  76. package/dist/holmes/hooks/pre-tool-use.d.ts +35 -1
  77. package/dist/holmes/hooks/pre-tool-use.js +702 -81
  78. package/dist/holmes/hooks/session-start.js +5 -3
  79. package/dist/holmes/hooks/stop.d.ts +32 -0
  80. package/dist/holmes/hooks/stop.js +129 -4
  81. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  82. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  83. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  84. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  85. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  86. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  87. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  88. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  89. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  90. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  91. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  92. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  93. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  94. package/dist/holmes/mcp/handlers.d.ts +2 -3
  95. package/dist/holmes/mcp/handlers.js +22 -2
  96. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  97. package/dist/holmes/mcp/harness-attestation.js +3 -1
  98. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  99. package/dist/holmes/mcp/operator-recovery.js +4 -3
  100. package/dist/holmes/mcp/server.js +9 -0
  101. package/dist/holmes/mcp/tool-schemas.js +6 -3
  102. package/dist/holmes/project/root.js +6 -1
  103. package/dist/holmes/project/run-records.d.ts +17 -0
  104. package/dist/holmes/project/run-records.js +126 -0
  105. package/dist/holmes/review/mrp.d.ts +35 -0
  106. package/dist/holmes/review/mrp.js +119 -0
  107. package/dist/holmes/review/verdicts.d.ts +117 -0
  108. package/dist/holmes/review/verdicts.js +345 -0
  109. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  110. package/dist/holmes/semantic/cloud-usage.js +106 -0
  111. package/dist/holmes/semantic/embedder.d.ts +15 -6
  112. package/dist/holmes/semantic/embedder.js +84 -3
  113. package/dist/holmes/semantic/local-model.d.ts +21 -2
  114. package/dist/holmes/semantic/local-model.js +14 -3
  115. package/dist/holmes/semantic/tier.d.ts +25 -0
  116. package/dist/holmes/semantic/tier.js +86 -1
  117. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  118. package/dist/holmes/semantic/vector-cache.js +4 -1
  119. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  120. package/dist/holmes/spec/approval-blockers.js +70 -2
  121. package/dist/holmes/spec/renumber.d.ts +1 -1
  122. package/dist/holmes/spec/renumber.js +5 -2
  123. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  124. package/dist/holmes/spec/transition-policy.js +17 -2
  125. package/package.json +1 -1
@@ -1,6 +1,17 @@
1
1
  /** Identifies the file as ours, so `--remove` never reclaims something a user wrote. */
2
2
  export declare const ROLES_README_MARKER = "<!-- holmes-kit:roles-guide -->";
3
3
  export declare const rolesReadmePath: (root: string) => string;
4
+ /**
5
+ * The guidance MUST be markdown, not a `.yaml` template.
6
+ *
7
+ * `loadRolePolicy` reads only `.yaml`/`.yml`/`.json` (A-SPEC-774.15), so a directory holding just this file yields no policy
8
+ * and the gate's decision does not move by one bit. Shipping an active `policy.yaml` instead would
9
+ * put every newly initialised project behind a fail-closed role gate on its first run — the same
10
+ * bricking REQ-146 measured when it tried to make a spec field required, and REQ-152 avoided by
11
+ * making roles opt-in. A `.yaml.example` name would also work today, but only because of how the
12
+ * loader currently filters; markdown cannot be mistaken for a policy under any future rule.
13
+ */
14
+ export declare const ROLES_README_CONTENT = "<!-- holmes-kit:roles-guide -->\n# \uC5ED\uD560 \uC815\uCC45 (\uC120\uD0DD \uAE30\uB2A5 \u2014 \uC9C0\uAE08\uC740 \uAEBC\uC838 \uC788\uC2B5\uB2C8\uB2E4)\n\n\uC774 \uB514\uB809\uD130\uB9AC\uC5D0 `.yaml`, `.yml` \uB610\uB294 `.json` \uD30C\uC77C\uC774 **\uD558\uB098\uB77C\uB3C4** \uC0DD\uAE30\uBA74 \uC5ED\uD560 \uAC8C\uC774\uD2B8\uAC00 \uCF1C\uC9D1\uB2C8\uB2E4.\n\uC774 README\uB9CC \uC788\uB294 \uB3D9\uC548\uC5D0\uB294 \uC544\uBB34\uAC83\uB3C4 \uBC14\uB00C\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.\n\n## \uCF1C\uB294 \uBC95\n\n`.ax/roles/policy.yaml`\uC744 \uB9CC\uB4ED\uB2C8\uB2E4:\n\n```yaml\nvocabulary: 2\nroles:\n pm: { allow: [AUTHOR_REQ, AUTHOR_HSPEC] }\n architect: { allow: [AUTHOR_ASPEC, AUTHOR_CSPEC, AUTHOR_TSPEC] }\n developer: { allow: [WRITE_CODE, WRITE_TEST, WRITE_OTHER, RECORD_EVIDENCE] }\n tester: { allow: [WRITE_TEST, RECORD_EVIDENCE] }\n reviewer: { allow: [RECORD_REVIEW] }\n maintainer: { allow: [AUTHOR_REQ, AUTHOR_HSPEC, AUTHOR_ASPEC, AUTHOR_CSPEC, AUTHOR_TSPEC, WRITE_CODE, WRITE_TEST, WRITE_OTHER, APPROVE_SPEC, RECORD_REVIEW, RECORD_EVIDENCE, MAINTAIN_GOVERNANCE] }\n readonly: { allow: [] }\n\n# \uC5ED\uD560\uC744 \uC9C0\uC815\uD558\uC9C0 \uC54A\uACE0 \uC2E4\uD589\uD588\uC744 \uB54C \uC5B4\uB290 \uC5ED\uD560\uB85C \uCDE8\uAE09\uD560\uC9C0.\n# \uC0DD\uB7B5\uD558\uBA74 \uC5ED\uD560 \uBBF8\uC9C0\uC815\uC740 \uAC70\uBD80\uB429\uB2C8\uB2E4(fail-closed).\ndefault: readonly\n```\n\n\uC5ED\uD560 \uC774\uB984\uC740 \uD504\uB85C\uC81D\uD2B8\uAC00 \uC815\uD569\uB2C8\uB2E4 \u2014 \uC704\uB294 \uC608\uC2DC\uC77C \uBFD0\uC785\uB2C8\uB2E4. `allow`\uC5D0 \uC4F0\uB294 \uB3D9\uC791\uBA85\uC740 \uAC8C\uC774\uD2B8\uAC00 \uC2E4\uC81C\uB85C \uD310\uC815\uD558\uB294\n\uC774\uB984\uC774\uBA70, \uC774 \uBAA9\uB85D \uBC16\uC758 \uC774\uB984\uC740 \uC544\uBB34\uAC83\uB3C4 \uD5C8\uC6A9\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4:\n\n| \uB3D9\uC791 | \uB73B |\n|---|---|\n| `AUTHOR_REQ` \u00B7 `AUTHOR_HSPEC` \u00B7 `AUTHOR_ASPEC` \u00B7 `AUTHOR_CSPEC` \u00B7 `AUTHOR_TSPEC` | \uADF8 \uC885\uB958\uC758 \uC2A4\uD399 \uBB38\uC11C\uB97C \uC4F0\uAE30 |\n| `WRITE_CODE` | \uC18C\uC2A4\u00B7\uC2E4\uD589 \uD30C\uC77C \uC4F0\uAE30 |\n| `WRITE_TEST` | \uD14C\uC2A4\uD2B8 \uD30C\uC77C \uC4F0\uAE30 |\n| `WRITE_OTHER` | \uBD84\uB958\uB418\uC9C0 \uC54A\uC740 \uD30C\uC77C(\uC124\uC815\u00B7\uBB38\uC11C \uB4F1) \uC4F0\uAE30 |\n| `APPROVE_SPEC` | \uC2A4\uD399 \uBD09\uC778(\uC2B9\uC778) \uC694\uCCAD |\n| `RECORD_REVIEW` | \uB9AC\uBDF0 \uAE30\uB85D |\n| `RECORD_EVIDENCE` | \uD14C\uC2A4\uD2B8\u00B7\uBD84\uC11D \uC99D\uAC70 \uAE30\uB85D |\n| `MAINTAIN_GOVERNANCE` | \uC6D0\uC7A5\u00B7\uC800\uC7A5\uC18C \uC720\uC9C0 \uC791\uC5C5 |\n\n`vocabulary: 2`\uB294 \uC704 \uC774\uB984\uC73C\uB85C \uC5C4\uACA9\uD558\uAC8C \uC77D\uC73C\uB77C\uB294 \uD45C\uC2DC\uC785\uB2C8\uB2E4. \uC774 \uC904\uC774 \uC5C6\uB294 \uC608\uC804 \uC815\uCC45\uC740 \uB300\uD654\uD615 \uC138\uC158\uC5D0\uC11C\n0.35.25\uAC00 \uAC80\uC0AC\uD558\uC9C0 \uC54A\uB358 \uB3D9\uC791\uC744 \uACC4\uC18D \uD5C8\uC6A9\uD569\uB2C8\uB2E4(`holmes-kit roles migrate`\uB85C \uBA85\uC2DC\uC801\uC73C\uB85C \uC62E\uAE38 \uC218 \uC788\uC2B5\uB2C8\uB2E4).\n\n## \uC5ED\uD560\uC744 \uC9C0\uC815\uD558\uB294 \uBC95\n\n\uC5D0\uC774\uC804\uD2B8\uB97C \uAE30\uB3D9\uD560 \uB54C **\uD658\uACBD\uBCC0\uC218**\uB85C \uC90D\uB2C8\uB2E4:\n\n```bash\nHOLMES_ROLE=reviewer claude\n```\n\n\uC138\uC158\uC740 \uC790\uAE30 \uD658\uACBD\uC744 \uBC14\uAFC0 \uC218 \uC5C6\uC73C\uBBC0\uB85C **\uC5D0\uC774\uC804\uD2B8\uAC00 \uC2A4\uC2A4\uB85C \uC5ED\uD560\uC744 \uC8FC\uC7A5\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.** \uC2B9\uC778\n(`HOLMES_APPROVAL`)\uACFC \uAC19\uC740 \uB300\uC5ED\uC678 \uC6D0\uCE59\uC785\uB2C8\uB2E4.\n\n## `default`\uB97C \uC65C \uCF54\uB4DC\uAC00 \uC815\uD558\uC9C0 \uC54A\uB294\uAC00\n\n\"\uC5ED\uD560 \uBBF8\uC9C0\uC815\uC774\uBA74 \uB9CC\uB2A5\"\uC744 \uCF54\uB4DC\uC5D0 \uB123\uC73C\uBA74 `HOLMES_ROLE`\uC744 \uBE44\uC6B0\uB294 \uAC83\uB9CC\uC73C\uB85C \uBAA8\uB4E0 \uC81C\uD55C\uC774 \uC6B0\uD68C\uB429\uB2C8\uB2E4.\nReviewer\uC5D0\uAC8C \uCF54\uB4DC \uC791\uC131\uC744 \uB9C9\uB294 \uADDC\uC728\uC774 \"\uC124\uC815 \uC548 \uD558\uBA74 \uADF8\uB9CC\"\uC774 \uB418\uC8E0. \uADF8\uB798\uC11C \uAE30\uBCF8\uAC12\uC740 **\uD504\uB85C\uC81D\uD2B8\uAC00 \uC774 \uD30C\uC77C\uC5D0\n\uC801\uC744 \uB54C\uB9CC** \uC874\uC7AC\uD558\uACE0, \uC774 \uB514\uB809\uD130\uB9AC\uB294 \uBCF4\uD638 \uACBD\uB85C\uB77C \uC5D0\uC774\uC804\uD2B8\uAC00 \uACE0\uCE60 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.\n\n\uAE30\uBCF8 \uC5ED\uD560\uC740 **\uBAA8\uB4E0 \uC5ED\uD560\uC774 \uACF5\uD1B5\uC73C\uB85C \uD5C8\uC6A9\uD558\uB294 \uAC83\uB9CC** \uD5C8\uC6A9\uD574\uC57C \uD569\uB2C8\uB2E4(\uC704 \uC608\uC2DC\uB294 \uBE48 \uC5ED\uD560 `readonly`).\n\uC5ED\uD560\uC744 \uC783\uC740 \uC138\uC158\uC774 \uAE30\uBCF8 \uC5ED\uD560\uB85C \uB5A8\uC5B4\uC9C8 \uB54C \uAD8C\uD55C\uC774 \uB298\uC5B4\uB098\uBA74 \uC548 \uB418\uAE30 \uB54C\uBB38\uC785\uB2C8\uB2E4. \uC774\uB97C \uC5B4\uAE30\uB294 \uC815\uCC45\uC740 \uC624\uCF00\uC2A4\uD2B8\uB808\uC774\uD130\n\uC2E4\uD589(run)\uC5D0\uC11C \uAC70\uBD80\uB418\uACE0, \uB300\uD654\uD615\uC5D0\uC11C\uB294 `holmes-kit doctor`\uAC00 \uACBD\uACE0\uD569\uB2C8\uB2E4.\n\n## \uC8FC\uC758\n\n- \uC774 \uB514\uB809\uD130\uB9AC\uB294 **git\uC5D0 \uCEE4\uBC0B**\uB429\uB2C8\uB2E4 \u2014 \uAC70\uBC84\uB10C\uC2A4 \uC124\uC815\uC740 \uD300\uC774 \uACF5\uC720\uD574\uC57C \uD569\uB2C8\uB2E4.\n- `default`\uAC00 \uC815\uC758\uB418\uC9C0 \uC54A\uC740 \uC5ED\uD560\uC744 \uAC00\uB9AC\uD0A4\uBA74 **\uAC70\uBD80**\uB429\uB2C8\uB2E4. \uC624\uD0C0\uAC00 \uC870\uC6A9\uD788 \uD1B5\uACFC\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.\n- \uD55C \uC5ED\uD560\uC740 **\uD55C \uD30C\uC77C\uC5D0\uC11C\uB9CC** \uC815\uC758\uD558\uC138\uC694. \uB450 \uD30C\uC77C\uC5D0 \uAC19\uC740 \uC5ED\uD560\uC774 \uC788\uC73C\uBA74 run\uC5D0\uC11C \uAC70\uBD80\uB418\uACE0 doctor\uAC00 \uACBD\uACE0\uD569\uB2C8\uB2E4.\n- \uD604\uC7AC \uC5ED\uD560\uC740 \uAC8C\uC774\uD2B8 \uAD8C\uD55C\uB9CC \uC815\uD569\uB2C8\uB2E4. \uC5ED\uD560\uBCC4 LLM \uBAA8\uB378 \uBC30\uC815\u00B7\uC5D0\uC774\uC804\uD2B8 \uAE30\uB3D9\uC740 \uC544\uC9C1 \uC5C6\uC2B5\uB2C8\uB2E4.\n";
4
15
  /** Installs the guidance. A file the user has edited is left alone. */
5
16
  export declare function installRolesReadme(root: string): void;
6
17
  /**
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.rolesReadmePath = exports.ROLES_README_MARKER = void 0;
36
+ exports.ROLES_README_CONTENT = exports.rolesReadmePath = exports.ROLES_README_MARKER = void 0;
37
37
  exports.installRolesReadme = installRolesReadme;
38
38
  exports.removeRolesReadme = removeRolesReadme;
39
39
  // @implements A-SPEC-153
@@ -46,40 +46,57 @@ exports.rolesReadmePath = rolesReadmePath;
46
46
  /**
47
47
  * The guidance MUST be markdown, not a `.yaml` template.
48
48
  *
49
- * `loadRolePolicy` reads only `.yaml`/`.yml`, so a directory holding just this file yields no policy
49
+ * `loadRolePolicy` reads only `.yaml`/`.yml`/`.json` (A-SPEC-774.15), so a directory holding just this file yields no policy
50
50
  * and the gate's decision does not move by one bit. Shipping an active `policy.yaml` instead would
51
51
  * put every newly initialised project behind a fail-closed role gate on its first run — the same
52
52
  * bricking REQ-146 measured when it tried to make a spec field required, and REQ-152 avoided by
53
53
  * making roles opt-in. A `.yaml.example` name would also work today, but only because of how the
54
54
  * loader currently filters; markdown cannot be mistaken for a policy under any future rule.
55
55
  */
56
- const CONTENT = `${exports.ROLES_README_MARKER}
56
+ // @implements A-SPEC-774.16 — the example is a working policy in the gate's own vocabulary, with a default that grants
57
+ // nothing (A-SPEC-774.8); exported so the test reads exactly what ships.
58
+ exports.ROLES_README_CONTENT = `${exports.ROLES_README_MARKER}
57
59
  # 역할 정책 (선택 기능 — 지금은 꺼져 있습니다)
58
60
 
59
- 이 디렉터리에 \`.yaml\` 파일이 **하나라도** 생기면 역할 게이트가 켜집니다. 이 README만 있는 동안에는
60
- 아무것도 바뀌지 않습니다.
61
+ 이 디렉터리에 \`.yaml\`, \`.yml\` 또는 \`.json\` 파일이 **하나라도** 생기면 역할 게이트가 켜집니다.
62
+ 이 README만 있는 동안에는 아무것도 바뀌지 않습니다.
61
63
 
62
64
  ## 켜는 법
63
65
 
64
66
  \`.ax/roles/policy.yaml\`을 만듭니다:
65
67
 
66
68
  \`\`\`yaml
69
+ vocabulary: 2
67
70
  roles:
68
- pm: { allow: [WRITE_SPEC] }
69
- architect: { allow: [WRITE_SPEC] }
70
- developer: { allow: [WRITE_CODE, WRITE_TEST] }
71
- tester: { allow: [WRITE_TEST] }
72
- reviewer: { allow: [] }
73
- maintainer: { allow: [WRITE_CODE, WRITE_TEST, WRITE_SPEC] }
71
+ pm: { allow: [AUTHOR_REQ, AUTHOR_HSPEC] }
72
+ architect: { allow: [AUTHOR_ASPEC, AUTHOR_CSPEC, AUTHOR_TSPEC] }
73
+ developer: { allow: [WRITE_CODE, WRITE_TEST, WRITE_OTHER, RECORD_EVIDENCE] }
74
+ tester: { allow: [WRITE_TEST, RECORD_EVIDENCE] }
75
+ reviewer: { allow: [RECORD_REVIEW] }
76
+ maintainer: { allow: [AUTHOR_REQ, AUTHOR_HSPEC, AUTHOR_ASPEC, AUTHOR_CSPEC, AUTHOR_TSPEC, WRITE_CODE, WRITE_TEST, WRITE_OTHER, APPROVE_SPEC, RECORD_REVIEW, RECORD_EVIDENCE, MAINTAIN_GOVERNANCE] }
77
+ readonly: { allow: [] }
74
78
 
75
79
  # 역할을 지정하지 않고 실행했을 때 어느 역할로 취급할지.
76
80
  # 생략하면 역할 미지정은 거부됩니다(fail-closed).
77
- default: maintainer
81
+ default: readonly
78
82
  \`\`\`
79
83
 
80
- 역할 이름은 프로젝트가 정합니다 — 위는 예시일 뿐입니다.
81
- \`allow\`에 쓰는 동작명은 게이트가 실제로 판정하는 이름입니다: \`WRITE_CODE\`, \`WRITE_TEST\`,
82
- \`WRITE_SPEC\`, \`APPROVE\`.
84
+ 역할 이름은 프로젝트가 정합니다 — 위는 예시일 뿐입니다. \`allow\`에 쓰는 동작명은 게이트가 실제로 판정하는
85
+ 이름이며, 이 목록 밖의 이름은 아무것도 허용하지 않습니다:
86
+
87
+ | 동작 | 뜻 |
88
+ |---|---|
89
+ | \`AUTHOR_REQ\` · \`AUTHOR_HSPEC\` · \`AUTHOR_ASPEC\` · \`AUTHOR_CSPEC\` · \`AUTHOR_TSPEC\` | 그 종류의 스펙 문서를 쓰기 |
90
+ | \`WRITE_CODE\` | 소스·실행 파일 쓰기 |
91
+ | \`WRITE_TEST\` | 테스트 파일 쓰기 |
92
+ | \`WRITE_OTHER\` | 분류되지 않은 파일(설정·문서 등) 쓰기 |
93
+ | \`APPROVE_SPEC\` | 스펙 봉인(승인) 요청 |
94
+ | \`RECORD_REVIEW\` | 리뷰 기록 |
95
+ | \`RECORD_EVIDENCE\` | 테스트·분석 증거 기록 |
96
+ | \`MAINTAIN_GOVERNANCE\` | 원장·저장소 유지 작업 |
97
+
98
+ \`vocabulary: 2\`는 위 이름으로 엄격하게 읽으라는 표시입니다. 이 줄이 없는 예전 정책은 대화형 세션에서
99
+ 0.35.25가 검사하지 않던 동작을 계속 허용합니다(\`holmes-kit roles migrate\`로 명시적으로 옮길 수 있습니다).
83
100
 
84
101
  ## 역할을 지정하는 법
85
102
 
@@ -98,10 +115,15 @@ HOLMES_ROLE=reviewer claude
98
115
  Reviewer에게 코드 작성을 막는 규율이 "설정 안 하면 그만"이 되죠. 그래서 기본값은 **프로젝트가 이 파일에
99
116
  적을 때만** 존재하고, 이 디렉터리는 보호 경로라 에이전트가 고칠 수 없습니다.
100
117
 
118
+ 기본 역할은 **모든 역할이 공통으로 허용하는 것만** 허용해야 합니다(위 예시는 빈 역할 \`readonly\`).
119
+ 역할을 잃은 세션이 기본 역할로 떨어질 때 권한이 늘어나면 안 되기 때문입니다. 이를 어기는 정책은 오케스트레이터
120
+ 실행(run)에서 거부되고, 대화형에서는 \`holmes-kit doctor\`가 경고합니다.
121
+
101
122
  ## 주의
102
123
 
103
124
  - 이 디렉터리는 **git에 커밋**됩니다 — 거버넌스 설정은 팀이 공유해야 합니다.
104
125
  - \`default\`가 정의되지 않은 역할을 가리키면 **거부**됩니다. 오타가 조용히 통과하지 않습니다.
126
+ - 한 역할은 **한 파일에서만** 정의하세요. 두 파일에 같은 역할이 있으면 run에서 거부되고 doctor가 경고합니다.
105
127
  - 현재 역할은 게이트 권한만 정합니다. 역할별 LLM 모델 배정·에이전트 기동은 아직 없습니다.
106
128
  `;
107
129
  /** Installs the guidance. A file the user has edited is left alone. */
@@ -110,7 +132,7 @@ function installRolesReadme(root) {
110
132
  if (fs.existsSync(file))
111
133
  return;
112
134
  fs.mkdirSync(path.dirname(file), { recursive: true });
113
- fs.writeFileSync(file, CONTENT);
135
+ fs.writeFileSync(file, exports.ROLES_README_CONTENT);
114
136
  }
115
137
  /**
116
138
  * Reclaims the guidance on `init --remove`. Returns whether it was ours to remove.
@@ -0,0 +1,12 @@
1
+ /**
2
+ * `holmes-kit roles migrate [--dry-run]` — rewrite each role policy file into the REQ-774 vocabulary with the same
3
+ * verdicts outside a run (A-SPEC-774.10 §4). Optional: a legacy policy already reads compatibly without it. The policy
4
+ * is a protected path, so this is an operator act run from a terminal, not by a session.
5
+ */
6
+ export declare function runRoles(sub: string | undefined, opts: {
7
+ target: string;
8
+ dryRun: boolean;
9
+ }, io: {
10
+ stdout: (t: string) => void;
11
+ stderr: (t: string) => void;
12
+ }): number;
@@ -0,0 +1,86 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.runRoles = runRoles;
37
+ // @implements A-SPEC-774.10
38
+ const fs = __importStar(require("node:fs"));
39
+ const path = __importStar(require("node:path"));
40
+ const role_policy_1 = require("../governance/role-policy");
41
+ /**
42
+ * `holmes-kit roles migrate [--dry-run]` — rewrite each role policy file into the REQ-774 vocabulary with the same
43
+ * verdicts outside a run (A-SPEC-774.10 §4). Optional: a legacy policy already reads compatibly without it. The policy
44
+ * is a protected path, so this is an operator act run from a terminal, not by a session.
45
+ */
46
+ function runRoles(sub, opts, io) {
47
+ if (sub !== 'migrate') {
48
+ io.stderr('usage: holmes-kit roles migrate [--dry-run] [--target <dir>]\n');
49
+ return 2;
50
+ }
51
+ const dir = path.join(opts.target, '.ax', 'roles');
52
+ let files;
53
+ try {
54
+ files = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml')).sort();
55
+ }
56
+ catch {
57
+ io.stdout('no role policy (.ax/roles) — nothing to migrate\n');
58
+ return 0;
59
+ }
60
+ let changed = 0;
61
+ for (const f of files) {
62
+ const file = path.join(dir, f);
63
+ const before = fs.readFileSync(file, 'utf8');
64
+ let after;
65
+ try {
66
+ after = (0, role_policy_1.migrateRolePolicyText)(before);
67
+ }
68
+ catch (e) {
69
+ io.stderr(`${f}: not readable as YAML (${e.message}) — left unchanged\n`);
70
+ continue;
71
+ }
72
+ if (after === before) {
73
+ io.stdout(`${f}: already vocabulary 2\n`);
74
+ continue;
75
+ }
76
+ changed++;
77
+ if (opts.dryRun)
78
+ io.stdout(`${f} would become:\n${after}\n`);
79
+ else {
80
+ fs.writeFileSync(file, after);
81
+ io.stdout(`${f}: migrated to vocabulary 2\n`);
82
+ }
83
+ }
84
+ io.stdout(opts.dryRun ? `${changed} file(s) would change\n` : `${changed} file(s) migrated\n`);
85
+ return 0;
86
+ }
@@ -0,0 +1,65 @@
1
+ type Engine = 'claude' | 'codex' | 'agy';
2
+ type Check = {
3
+ name: string;
4
+ status: 'pass' | 'fail' | 'unknown' | 'accepted';
5
+ detail: string;
6
+ };
7
+ /** @implements A-SPEC-102.5 — `scope`: the plan's A-SPEC ids; a scoped run writes only inside their Files to Touch. */
8
+ /** @implements A-SPEC-781 — `to` and `why`: a stage transition and its reason. */
9
+ export interface RunOptions {
10
+ target?: string;
11
+ worktree?: string;
12
+ engine?: string;
13
+ engineArgs?: string[];
14
+ id?: string;
15
+ key?: string;
16
+ scope?: string[];
17
+ to?: string;
18
+ why?: string;
19
+ /** @implements A-SPEC-774.20, A-SPEC-774.24 — the unreadable version fields to start despite, by name; recorded. */
20
+ acceptUnknownVersions?: string[];
21
+ }
22
+ export interface RunDeps {
23
+ home?: string;
24
+ codexHome?: string;
25
+ now?: () => Date;
26
+ random?: (bytes: number) => string;
27
+ /** @implements A-SPEC-774.18 — injected in tests; otherwise this package's version, build id and the user's Codex config. */
28
+ cliVersion?: string;
29
+ cliBuild?: string | null;
30
+ codexConfigPath?: string;
31
+ }
32
+ /** @implements A-SPEC-780 — `hook_build`: the dist build id of the package the hook command runs from. */
33
+ export interface RunVersions {
34
+ cli: string;
35
+ cli_build: string | null;
36
+ mcp: string | null;
37
+ hook: string | null;
38
+ hook_build: string | null;
39
+ }
40
+ /** @implements A-SPEC-774.18 — the versions that would govern this run. Unknown is null, never a guess. */
41
+ export declare function runVersions(worktree: string, engine: Engine, deps: RunDeps): RunVersions;
42
+ /** @implements A-SPEC-774.24 — the version fields, in the order a refusal names them. */
43
+ export declare const VERSION_FIELDS: readonly ["cli", "cli_build", "mcp", "hook", "hook_build"];
44
+ export type VersionField = typeof VERSION_FIELDS[number];
45
+ /**
46
+ * @implements A-SPEC-774.24 — the capability table: the version fields run start cannot read for a harness by design.
47
+ * They are exempt without a flag and recorded as exempt; every other unreadable field must be named to be accepted.
48
+ * agy: run start reads no agy hook wiring, so its hook version and build are never known here.
49
+ */
50
+ export declare const HARNESS_UNREADABLE_VERSIONS: Record<Engine, readonly VersionField[]>;
51
+ /** @implements A-SPEC-774.20 — the version fields run start could not read, in a fixed order. */
52
+ export declare function unreadableVersions(v: RunVersions): VersionField[];
53
+ /** @implements A-SPEC-774.24 — `--accept-unknown-versions` names its fields; none, or a name that is no field, is refused. */
54
+ export declare function parseAcceptedVersions(text: string): {
55
+ fields: VersionField[];
56
+ } | {
57
+ refusal: string;
58
+ };
59
+ export declare function versionsCheck(v: RunVersions, engine: Engine, accepted: readonly string[]): Check;
60
+ type Io = {
61
+ stdout: (t: string) => void;
62
+ stderr: (t: string) => void;
63
+ };
64
+ export declare function runRun(sub: string | undefined, opts: RunOptions, io: Io, deps?: RunDeps): number;
65
+ export {};
@@ -0,0 +1,308 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.HARNESS_UNREADABLE_VERSIONS = exports.VERSION_FIELDS = void 0;
37
+ exports.runVersions = runVersions;
38
+ exports.unreadableVersions = unreadableVersions;
39
+ exports.parseAcceptedVersions = parseAcceptedVersions;
40
+ exports.versionsCheck = versionsCheck;
41
+ exports.runRun = runRun;
42
+ // @implements A-SPEC-774.17, A-SPEC-779, A-SPEC-780, A-SPEC-102.3, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20, A-SPEC-781.2
43
+ const node_child_process_1 = require("node:child_process");
44
+ const crypto = __importStar(require("node:crypto"));
45
+ const config_1 = require("../config/config");
46
+ const run_refusals_1 = require("../guardrail/run-refusals");
47
+ const run_stages_1 = require("../guardrail/run-stages");
48
+ const fs = __importStar(require("node:fs"));
49
+ const os = __importStar(require("node:os"));
50
+ const path = __importStar(require("node:path"));
51
+ const agent_launch_policy_1 = require("../guardrail/agent-launch-policy");
52
+ const run_records_1 = require("../project/run-records");
53
+ /** @implements A-SPEC-774.18 — the version of the holmes-kit package that holds `file`, walking up to its package.json. */
54
+ function holmesPackageVersionAbove(file) {
55
+ return (0, run_refusals_1.holmesPackageAbove)(file)?.version ?? null;
56
+ }
57
+ /** @implements A-SPEC-774.18 — the holmes-kit version a hook command runs: its first word that names a holmes `.js` path. */
58
+ function hookCommandPackage(command) {
59
+ const words = command.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
60
+ for (const w of words) {
61
+ const word = w.replace(/^["']|["']$/g, '');
62
+ if (/holmes/i.test(word) && /\.js$/.test(word) && path.isAbsolute(word))
63
+ return (0, run_refusals_1.holmesPackageAbove)(word);
64
+ }
65
+ return null;
66
+ }
67
+ /** @implements A-SPEC-102.3 — the worktree's HEAD commit, or null when git cannot say. */
68
+ function worktreeHead(worktree) {
69
+ const { GIT_MAX_BUFFER, GIT_TIMEOUT_MS } = require('../project/bounded-io');
70
+ try {
71
+ const out = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd: worktree, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim();
72
+ return /^[0-9a-f]{40,64}$/.test(out) ? out : null;
73
+ }
74
+ catch {
75
+ return null;
76
+ }
77
+ }
78
+ function hookCommandsIn(text) {
79
+ if (text === null)
80
+ return [];
81
+ const out = [];
82
+ const walk = (v) => {
83
+ if (Array.isArray(v)) {
84
+ v.forEach(walk);
85
+ return;
86
+ }
87
+ if (v && typeof v === 'object') {
88
+ const o = v;
89
+ if (typeof o.command === 'string' && /holmes/i.test(o.command))
90
+ out.push(o.command);
91
+ Object.values(o).forEach(walk);
92
+ }
93
+ };
94
+ try {
95
+ walk(JSON.parse(text));
96
+ }
97
+ catch { /* not JSON: no commands */ }
98
+ return out;
99
+ }
100
+ /** @implements A-SPEC-774.18 — the versions that would govern this run. Unknown is null, never a guess. */
101
+ function runVersions(worktree, engine, deps) {
102
+ const packageRoot = path.resolve(__dirname, '..', '..', '..');
103
+ const { readPackageVersion } = require('./mcp-launcher');
104
+ const { distBuildId } = require('../project/dist-freshness');
105
+ const { holmesWirings } = require('./doctor');
106
+ const { mcpLaunchVersion } = require('./mcp-version');
107
+ const { defaultCodexConfigPath } = require('./codex-toml');
108
+ const home = deps.home ?? os.homedir();
109
+ const label = engine === 'agy' ? 'antigravity' : engine;
110
+ let mcp = null;
111
+ try {
112
+ const wiring = holmesWirings(worktree, deps.codexConfigPath ?? defaultCodexConfigPath()).find((w) => w.label === label);
113
+ if (wiring?.entry) {
114
+ const args = wiring.entry.command === 'node' && wiring.entry.args.length > 0 && !path.isAbsolute(wiring.entry.args[0])
115
+ ? [path.resolve(worktree, wiring.entry.args[0]), ...wiring.entry.args.slice(1)] : wiring.entry.args;
116
+ mcp = mcpLaunchVersion({ command: path.basename(wiring.entry.command), args }, (dir) => holmesPackageVersionAbove(path.join(dir, 'package.json')) ?? undefined);
117
+ }
118
+ }
119
+ catch {
120
+ mcp = null;
121
+ }
122
+ const hookFiles = engine === 'claude'
123
+ ? [path.join(worktree, '.claude', 'settings.json'), path.join(home, '.claude', 'settings.json')]
124
+ : engine === 'codex' ? [path.join(deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex'), 'hooks.json')] : [];
125
+ const hookPkg = hookFiles.flatMap((f) => hookCommandsIn(readText(f))).map(hookCommandPackage).find((v) => v !== null) ?? null;
126
+ return {
127
+ cli: deps.cliVersion ?? readPackageVersion(packageRoot) ?? 'unknown',
128
+ cli_build: deps.cliBuild !== undefined ? deps.cliBuild : distBuildId(packageRoot),
129
+ mcp, hook: hookPkg?.version ?? null,
130
+ // @implements A-SPEC-780 — the hook's own build, which the hook compares itself with during the run.
131
+ hook_build: hookPkg ? distBuildId(hookPkg.root) : null,
132
+ };
133
+ }
134
+ /** @implements A-SPEC-774.24 — the version fields, in the order a refusal names them. */
135
+ exports.VERSION_FIELDS = ['cli', 'cli_build', 'mcp', 'hook', 'hook_build'];
136
+ /**
137
+ * @implements A-SPEC-774.24 — the capability table: the version fields run start cannot read for a harness by design.
138
+ * They are exempt without a flag and recorded as exempt; every other unreadable field must be named to be accepted.
139
+ * agy: run start reads no agy hook wiring, so its hook version and build are never known here.
140
+ */
141
+ exports.HARNESS_UNREADABLE_VERSIONS = { claude: [], codex: [], agy: ['hook', 'hook_build'] };
142
+ /** @implements A-SPEC-774.20 — the version fields run start could not read, in a fixed order. */
143
+ function unreadableVersions(v) {
144
+ return [
145
+ ...(v.cli === 'unknown' ? ['cli'] : []),
146
+ ...['cli_build', 'mcp', 'hook', 'hook_build'].filter((k) => v[k] === null),
147
+ ];
148
+ }
149
+ /** @implements A-SPEC-774.24 — `--accept-unknown-versions` names its fields; none, or a name that is no field, is refused. */
150
+ function parseAcceptedVersions(text) {
151
+ const names = text.split(',').map((s) => s.trim()).filter((s) => s !== '');
152
+ if (names.length === 0)
153
+ return { refusal: `--accept-unknown-versions must name the fields it accepts (${exports.VERSION_FIELDS.join(', ')})` };
154
+ const bad = names.filter((n) => !exports.VERSION_FIELDS.includes(n));
155
+ if (bad.length > 0)
156
+ return { refusal: `--accept-unknown-versions: ${bad.join(', ')} is not a version field (${exports.VERSION_FIELDS.join(', ')})` };
157
+ return { fields: [...new Set(names)] };
158
+ }
159
+ /** @implements A-SPEC-774.24 — each unreadable field is exempt by the table, accepted by name, or failing. */
160
+ function sortUnreadable(v, engine, accepted) {
161
+ const unread = unreadableVersions(v);
162
+ const exempt = unread.filter((k) => exports.HARNESS_UNREADABLE_VERSIONS[engine].includes(k));
163
+ const rest = unread.filter((k) => !exempt.includes(k));
164
+ return { exempt, accepted: rest.filter((k) => accepted.includes(k)), failing: rest.filter((k) => !accepted.includes(k)) };
165
+ }
166
+ function versionsCheck(v, engine, accepted) {
167
+ const drift = ['mcp', 'hook'].filter((k) => v[k] !== null && v[k] !== v.cli).map((k) => `${k} ${v[k]}`);
168
+ if (drift.length > 0)
169
+ return { name: 'versions', status: 'fail', detail: `${drift.join(', ')} differ from this CLI ${v.cli} — one build must govern a run; rewire or reinstall` };
170
+ // @implements A-SPEC-774.20 — in run mode an unreadable version blocks and is named; accepting it is on record.
171
+ const s = sortUnreadable(v, engine, accepted);
172
+ const exemptNote = s.exempt.length > 0 ? `; ${s.exempt.join(', ')} exempt for ${engine} by the capability table (recorded)` : '';
173
+ if (s.failing.length > 0) {
174
+ return { name: 'versions', status: 'fail', detail: `cannot read ${s.failing.join(', ')} — a run must pin the builds that govern it; fix the wiring or pass --accept-unknown-versions=${s.failing.join(',')}${exemptNote}` };
175
+ }
176
+ if (s.accepted.length > 0)
177
+ return { name: 'versions', status: 'accepted', detail: `unreadable ${s.accepted.join(', ')} accepted by --accept-unknown-versions (recorded)${exemptNote}` };
178
+ return { name: 'versions', status: 'pass', detail: `the MCP and hook versions equal this CLI ${v.cli}, and every ${s.exempt.length > 0 ? 'other ' : ''}build id was read${exemptNote}` };
179
+ }
180
+ const HEADLESS = { claude: ['claude', '-p'], codex: ['codex', 'exec'], agy: ['agy', '-p'] };
181
+ const USAGE = 'usage: holmes-kit run start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]... [--accept-unknown-versions <field,...>] [--target <dir>]\n'
182
+ + ' holmes-kit run status [--target <dir>]\n'
183
+ + ' holmes-kit run transition --id <run_id> --to <stage> --key <stop_key> [--why <text>] [--target <dir>]\n'
184
+ + ' holmes-kit run stop --id <run_id> --key <stop_key> [--target <dir>]\n';
185
+ const readText = (f) => { try {
186
+ return fs.readFileSync(f, 'utf8');
187
+ }
188
+ catch {
189
+ return null;
190
+ } };
191
+ const namesHolmes = (t) => t !== null && /holmes/i.test(t);
192
+ /** Whether the engine's wiring in this worktree (and the user's home) would load the Holmes gate. */
193
+ function checks(main, worktree, engine, args, deps) {
194
+ const home = deps.home ?? os.homedir();
195
+ const out = [];
196
+ let wtMain = null;
197
+ try {
198
+ wtMain = fs.statSync(worktree).isDirectory() ? (0, run_records_1.mainCheckoutOf)(worktree) : null;
199
+ }
200
+ catch {
201
+ wtMain = null;
202
+ }
203
+ out.push(wtMain !== null && fs.realpathSync(wtMain) === fs.realpathSync(main)
204
+ ? { name: 'worktree', status: 'pass', detail: `${worktree} is a working tree of ${main}` }
205
+ : { name: 'worktree', status: 'fail', detail: `${worktree} is not a working tree of ${main}` });
206
+ out.push(fs.existsSync(path.join(worktree, '.ax', 'specs'))
207
+ ? { name: 'specs', status: 'pass', detail: '.ax/specs is present' }
208
+ : { name: 'specs', status: 'fail', detail: '.ax/specs is missing in the worktree — the gate would judge an ungoverned tree' });
209
+ const mcp = engine === 'codex' ? namesHolmes(readText(path.join(worktree, '.codex', 'config.toml')))
210
+ : engine === 'claude' ? namesHolmes(readText(path.join(worktree, '.mcp.json')))
211
+ : namesHolmes(readText(path.join(worktree, '.mcp.json'))) || fs.existsSync(path.join(worktree, '.agents'));
212
+ out.push(mcp ? { name: 'mcp', status: 'pass', detail: `the ${engine} MCP wiring in the worktree names holmes-kit` }
213
+ : { name: 'mcp', status: 'fail', detail: `the worktree carries no ${engine} MCP wiring that names holmes-kit` });
214
+ if (engine === 'claude') {
215
+ const hooked = namesHolmes(readText(path.join(worktree, '.claude', 'settings.json'))) || namesHolmes(readText(path.join(home, '.claude', 'settings.json')));
216
+ out.push(hooked ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in the project or user Claude settings' }
217
+ : { name: 'gate', status: 'fail', detail: 'no Holmes hook in <worktree>/.claude/settings.json or ~/.claude/settings.json — the Claude gate would not load' });
218
+ }
219
+ else if (engine === 'codex') {
220
+ const codexHome = deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex');
221
+ out.push(namesHolmes(readText(path.join(codexHome, 'hooks.json')))
222
+ ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in $CODEX_HOME/hooks.json' }
223
+ : { name: 'gate', status: 'fail', detail: 'no Holmes hook in $CODEX_HOME/hooks.json — the Codex gate would not load' });
224
+ }
225
+ else {
226
+ out.push({ name: 'gate', status: 'unknown', detail: 'agy hook loading cannot be read from a file here — run holmes-kit doctor --agent agy' });
227
+ }
228
+ const off = args.map((a) => (0, agent_launch_policy_1.gateOffMarker)(a)).find((m) => m !== null) ?? (0, agent_launch_policy_1.gateOffMarker)(args.join(' '));
229
+ out.push(off === null ? { name: 'engine-args', status: 'pass', detail: 'no engine argument switches the gate off' }
230
+ : { name: 'engine-args', status: 'fail', detail: `an engine argument switches the gate off (${off})` });
231
+ return out;
232
+ }
233
+ function runRun(sub, opts, io, deps = {}) {
234
+ const main = (0, run_records_1.mainCheckoutOf)(opts.target ?? process.cwd());
235
+ const random = deps.random ?? ((n) => crypto.randomBytes(n).toString('hex'));
236
+ if (sub === 'status') {
237
+ // @implements A-SPEC-779 — each run's state from its event log: running, awaiting_approval or stopped.
238
+ const cfg = (0, config_1.loadConfig)(main).run;
239
+ io.stdout(`${JSON.stringify({ runs: (0, run_records_1.listRuns)(main).map((r) => ({ run_id: r.run_id, worktree: r.worktree, engine: r.engine, started: r.started,
240
+ versions: r.versions ?? null,
241
+ ...(0, run_refusals_1.runState)(main, r.run_id, { limit: cfg.refusalRepeatLimit, waitMinutes: cfg.approvalWaitMinutes, ...(deps.now ? { now: deps.now } : {}) }),
242
+ // @implements A-SPEC-781 — where the run is in its stage machine.
243
+ stage: (0, run_stages_1.currentStage)(main, r.run_id, (0, config_1.loadConfig)(main).stages) })) }, null, 2)}\n`);
244
+ return 0;
245
+ }
246
+ // @implements A-SPEC-781 — only the holder of the stop key moves a run's stage.
247
+ if (sub === 'transition') {
248
+ if (!opts.id || !opts.to || !opts.key) {
249
+ io.stderr(USAGE);
250
+ return 2;
251
+ }
252
+ const r = (0, run_stages_1.transitionRun)(main, opts.id, opts.to, { key: opts.key, ...(opts.why ? { why: opts.why } : {}), ...(deps.now ? { now: deps.now } : {}) });
253
+ io.stdout(`${JSON.stringify({ run_id: opts.id, ...r })}\n`);
254
+ return r.ok ? 0 : 3;
255
+ }
256
+ if (sub === 'stop') {
257
+ if (!opts.id) {
258
+ io.stderr(USAGE);
259
+ return 2;
260
+ }
261
+ const result = (0, run_records_1.removeRun)(main, opts.id, opts.key);
262
+ io.stdout(`${JSON.stringify({ ok: result === 'removed', run_id: opts.id, result })}\n`);
263
+ return result === 'removed' ? 0 : result === 'bad-key' ? 3 : 4;
264
+ }
265
+ if (sub !== 'start' || !opts.worktree || !['claude', 'codex', 'agy'].includes(opts.engine ?? '')) {
266
+ io.stderr(USAGE);
267
+ return 2;
268
+ }
269
+ const engine = opts.engine;
270
+ const worktree = path.resolve(opts.worktree);
271
+ const args = opts.engineArgs ?? [];
272
+ const found = checks(main, worktree, engine, args, deps);
273
+ // @implements A-SPEC-774.18 — the builds that would govern the run, pinned before anything is written.
274
+ const versions = runVersions(worktree, engine, deps);
275
+ found.push(versionsCheck(versions, engine, opts.acceptUnknownVersions ?? []));
276
+ if (found.some((c) => c.status === 'fail')) {
277
+ io.stdout(`${JSON.stringify({ ok: false, refused: 'a check failed — the run would not be governed', checks: found, versions }, null, 2)}\n`);
278
+ return 3;
279
+ }
280
+ const now = (deps.now ?? (() => new Date()))();
281
+ const runId = (0, run_records_1.newRunId)(now, () => random(4));
282
+ const stopKey = random(16);
283
+ // The record keeps the fields runMode validates; `versions` rides along (A-SPEC-774.18).
284
+ // @implements A-SPEC-102.3 — and `base`, the worktree's HEAD now: the start of the range the run's review covers.
285
+ const base = worktreeHead(worktree);
286
+ // @implements A-SPEC-774.24 — only the named fields are accepted; the table's exemptions are recorded beside them.
287
+ const { accepted, exempt } = sortUnreadable(versions, engine, opts.acceptUnknownVersions ?? []);
288
+ const rec = {
289
+ run_id: runId, worktree: fs.realpathSync(worktree), sessions: [], engine, started: now.toISOString(), stop_key_sha256: (0, run_records_1.keyHash)(stopKey),
290
+ versions, ...(base ? { base } : {}),
291
+ ...(opts.scope && opts.scope.length > 0 ? { scope: [...opts.scope] } : {}),
292
+ ...(accepted.length > 0 ? { accepted_unknown_versions: accepted } : {}),
293
+ ...(exempt.length > 0 ? { exempt_unknown_versions: exempt } : {}),
294
+ };
295
+ const record = (0, run_records_1.writeRun)(main, rec);
296
+ // @implements A-SPEC-774.20 — the acceptance is in the run's log too, beside every later event of the run.
297
+ if (accepted.length > 0)
298
+ (0, run_refusals_1.appendRunEvent)(main, runId, { ts: now.toISOString(), event: 'versions_accepted', fields: accepted });
299
+ // @implements A-SPEC-781.2 — how this run's stage machine was read, when it was not read as written.
300
+ const stageNotes = (0, config_1.loadConfig)(main).stages.notes;
301
+ if (stageNotes.length > 0)
302
+ (0, run_refusals_1.appendRunEvent)(main, runId, { ts: now.toISOString(), event: 'stages_interpreted', notes: stageNotes });
303
+ io.stdout(`${JSON.stringify({
304
+ ok: true, run_id: runId, worktree, record, env: { HOLMES_RUN_ID: runId }, command: [...HEADLESS[engine], ...args],
305
+ stop_key: stopKey, versions, checks: found, ...(stageNotes.length > 0 ? { stage_notes: stageNotes } : {}),
306
+ }, null, 2)}\n`);
307
+ return 0;
308
+ }
@@ -1,3 +1,4 @@
1
+ import * as path from 'node:path';
1
2
  import type { RuntimeHarness, RuntimeEntry, RuntimeSelection } from '../runtime/binding';
2
3
  import type { Approval } from '../guardrail/risk-gate';
3
4
  export declare const defaultRuntimeRegistry: () => string;
@@ -17,6 +18,35 @@ export interface RuntimeBindingOptions {
17
18
  /** @implements A-SPEC-752.14 — where the operator runs remove (CLI: cwd); holds the approval of a workspace without `.ax`. */
18
19
  approvalRoot?: string;
19
20
  }
21
+ /**
22
+ * Whether one Antigravity hook command is Holmes's own direct wrapper.
23
+ *
24
+ * @implements A-SPEC-751.8
25
+ * The shape and a literal script name decide exactly as the inline test did before. Only on a win32 host, and only
26
+ * when the literal name does not, the token is read back to its long name: init writes a spaced install root as its
27
+ * 8.3 form, and `%~sI` shortens the file name too (`HOLMES~4.JS`, measured 2026-10-17), so the literal test refused
28
+ * Holmes's own entry and setup wrote nothing. A token a shell would not take literally, or one the resolver cannot
29
+ * read, is not a match — the entry stays a conflict (A-SPEC-751 rule 5). Host and resolver are injectable so either
30
+ * host can assert the other's answers.
31
+ */
32
+ export declare function holmesAgyWrapper(cmd: unknown, opts?: {
33
+ host?: path.PlatformPath;
34
+ realpath?: (p: string) => string;
35
+ }): boolean;
36
+ /**
37
+ * Whether an existing Antigravity command is the canonical dispatcher command `runtimeHookCommand` computes now.
38
+ *
39
+ * @implements A-SPEC-751.9
40
+ * Identical strings always are. On a win32 host only, two space-free two-token commands are also the same when each
41
+ * token resolves to the same long path: `shortPathIfSpaced` shortens only components that exist, so the command a first
42
+ * setup wrote (`…\operator\antigravity-stop.js`, the file not yet made) is not the string the next one computes
43
+ * (`…\operator\ANTIGR~1.JS`, measured 2026-10-18) — and setup refused its own entry while doctor counted none. A token a
44
+ * shell would not take literally, or one the resolver cannot read, makes them different (A-SPEC-751 rule 5 still holds).
45
+ */
46
+ export declare function sameAgyCommand(written: unknown, canonical: string, opts?: {
47
+ host?: path.PlatformPath;
48
+ realpath?: (p: string) => string;
49
+ }): boolean;
20
50
  export declare function runtimeHookCommand(registryPath: string, harness: RuntimeHarness, entry: RuntimeEntry): string;
21
51
  /**
22
52
  * @implements A-SPEC-752.5 — what the receipt records about a file. Claude Code rewrites its own settings file (measured