@holmes-lab/holmes-kit 0.35.24 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/CHANGELOG.md +363 -0
  2. package/README.md +4 -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 +34 -4
  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 +31 -1
  13. package/dist/holmes/cli/doctor.js +204 -7
  14. package/dist/holmes/cli/index.js +115 -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-approval.js +3 -2
  27. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  28. package/dist/holmes/cli/runtime-binding.js +116 -11
  29. package/dist/holmes/cli/scratch.d.ts +12 -0
  30. package/dist/holmes/cli/scratch.js +20 -0
  31. package/dist/holmes/cli/test-platform.d.ts +16 -0
  32. package/dist/holmes/cli/test-platform.js +31 -1
  33. package/dist/holmes/config/config.d.ts +49 -0
  34. package/dist/holmes/config/config.js +146 -3
  35. package/dist/holmes/config/project-caps.d.ts +21 -0
  36. package/dist/holmes/config/project-caps.js +114 -0
  37. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  38. package/dist/holmes/governance/approval-queue.js +51 -8
  39. package/dist/holmes/governance/autonomy.d.ts +6 -0
  40. package/dist/holmes/governance/autonomy.js +21 -0
  41. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  42. package/dist/holmes/governance/push-gate-runner.js +49 -1
  43. package/dist/holmes/governance/replica-id.d.ts +9 -0
  44. package/dist/holmes/governance/replica-id.js +44 -7
  45. package/dist/holmes/governance/role-policy.d.ts +41 -1
  46. package/dist/holmes/governance/role-policy.js +137 -20
  47. package/dist/holmes/governance/run-mode.d.ts +14 -0
  48. package/dist/holmes/governance/run-mode.js +120 -0
  49. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  50. package/dist/holmes/governance/tool-actions.js +121 -0
  51. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  52. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  53. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  54. package/dist/holmes/guardrail/classification-mode.js +135 -0
  55. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  56. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  57. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  58. package/dist/holmes/guardrail/impact-gate.js +34 -11
  59. package/dist/holmes/guardrail/phase.d.ts +2 -1
  60. package/dist/holmes/guardrail/phase.js +22 -8
  61. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  62. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  63. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  64. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  65. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  66. package/dist/holmes/guardrail/risk-classifier.js +255 -27
  67. package/dist/holmes/guardrail/risk-types.d.ts +16 -0
  68. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  69. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  70. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  71. package/dist/holmes/guardrail/run-refusals.js +348 -0
  72. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  73. package/dist/holmes/guardrail/run-stages.js +188 -0
  74. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  75. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  76. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  77. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  78. package/dist/holmes/guardrail/shell-words.js +7 -7
  79. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  80. package/dist/holmes/guardrail/write-target.js +118 -16
  81. package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
  82. package/dist/holmes/hooks/pre-tool-use.js +740 -81
  83. package/dist/holmes/hooks/session-start.js +5 -3
  84. package/dist/holmes/hooks/stop.d.ts +35 -1
  85. package/dist/holmes/hooks/stop.js +142 -7
  86. package/dist/holmes/mcp/elicit-approval.js +4 -4
  87. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  89. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  90. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  91. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  92. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  93. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  94. package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
  95. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  96. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  97. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  98. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  99. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  100. package/dist/holmes/mcp/handlers.d.ts +2 -3
  101. package/dist/holmes/mcp/handlers.js +22 -2
  102. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  103. package/dist/holmes/mcp/harness-attestation.js +3 -1
  104. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  105. package/dist/holmes/mcp/operator-recovery.js +4 -3
  106. package/dist/holmes/mcp/server.js +9 -0
  107. package/dist/holmes/mcp/tool-schemas.js +6 -3
  108. package/dist/holmes/project/npx-bin.d.ts +26 -0
  109. package/dist/holmes/project/npx-bin.js +272 -2
  110. package/dist/holmes/project/root.js +6 -1
  111. package/dist/holmes/project/run-records.d.ts +17 -0
  112. package/dist/holmes/project/run-records.js +126 -0
  113. package/dist/holmes/project/scratch-root.d.ts +12 -0
  114. package/dist/holmes/project/scratch-root.js +132 -0
  115. package/dist/holmes/review/mrp.d.ts +35 -0
  116. package/dist/holmes/review/mrp.js +119 -0
  117. package/dist/holmes/review/verdicts.d.ts +117 -0
  118. package/dist/holmes/review/verdicts.js +345 -0
  119. package/dist/holmes/runtime/dispatch.js +6 -3
  120. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  121. package/dist/holmes/semantic/cloud-usage.js +106 -0
  122. package/dist/holmes/semantic/embedder.d.ts +15 -6
  123. package/dist/holmes/semantic/embedder.js +84 -3
  124. package/dist/holmes/semantic/local-model.d.ts +21 -2
  125. package/dist/holmes/semantic/local-model.js +14 -3
  126. package/dist/holmes/semantic/tier.d.ts +25 -0
  127. package/dist/holmes/semantic/tier.js +86 -1
  128. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  129. package/dist/holmes/semantic/vector-cache.js +4 -1
  130. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  131. package/dist/holmes/spec/approval-blockers.js +70 -2
  132. package/dist/holmes/spec/renumber.d.ts +1 -1
  133. package/dist/holmes/spec/renumber.js +5 -2
  134. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  135. package/dist/holmes/spec/transition-policy.js +17 -2
  136. package/package.json +1 -1
@@ -1,7 +1,8 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.notificationBody = notificationBody;
3
4
  exports.notifyQueueArrival = notifyQueueArrival;
4
- // @implements A-SPEC-497.2
5
+ // @implements A-SPEC-497.2, A-SPEC-770.12
5
6
  /**
6
7
  * OS-native arrival notification for the approval queue — the MAIN LANE's "you are needed" ping.
7
8
  * Fire-and-forget by doctrine: a notification failure must change NOTHING about the watch loop,
@@ -13,11 +14,16 @@ exports.notifyQueueArrival = notifyQueueArrival;
13
14
  */
14
15
  const node_child_process_1 = require("node:child_process");
15
16
  const screen_safe_1 = require("./screen-safe");
17
+ /** @implements A-SPEC-770.12 — the notification text: kind, target and, when the request carries one, its title. */
18
+ function notificationBody(item) {
19
+ const kind = (0, screen_safe_1.flattenField)(item.kind, 40);
20
+ const target = (0, screen_safe_1.flattenField)(item.target, 80);
21
+ const title = typeof item.title === 'string' && item.title.trim() !== '' ? ` 「${(0, screen_safe_1.flattenField)(item.title, 80)}」` : '';
22
+ return `${kind} — ${target}${title} · 결정: holmes approve`;
23
+ }
16
24
  function notifyQueueArrival(item, deps = { platform: process.platform, spawn: (cmd, args) => (0, node_child_process_1.spawn)(cmd, args, { stdio: 'ignore', detached: false }) }) {
17
25
  try {
18
- const kind = (0, screen_safe_1.flattenField)(item.kind, 40);
19
- const target = (0, screen_safe_1.flattenField)(item.target, 80);
20
- const body = `${kind} — ${target} · 결정: holmes approve`;
26
+ const body = notificationBody(item);
21
27
  let cmd;
22
28
  let args;
23
29
  if (deps.platform === 'darwin') {
@@ -0,0 +1,25 @@
1
+ export interface ReviewOptions {
2
+ target?: string;
3
+ base?: string;
4
+ head?: string;
5
+ verdict?: string;
6
+ findings?: string[];
7
+ engine?: string;
8
+ model?: string;
9
+ session?: string;
10
+ strict?: boolean;
11
+ /** @implements A-SPEC-102.7 — `--solid <S|O|L|I|D>=<compliant|violation|n-a>:<evidence>`, repeatable. */
12
+ solid?: string[];
13
+ }
14
+ export interface ReviewDeps {
15
+ env?: NodeJS.ProcessEnv;
16
+ cwd?: string;
17
+ interactive?: boolean;
18
+ }
19
+ type Io = {
20
+ stdout: (t: string) => void;
21
+ stderr: (t: string) => void;
22
+ };
23
+ export declare const REVIEW_USAGE: string;
24
+ export declare function runReview(sub: string | undefined, opts: ReviewOptions, io: Io, deps?: ReviewDeps): number;
25
+ export {};
@@ -0,0 +1,111 @@
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.REVIEW_USAGE = void 0;
37
+ exports.runReview = runReview;
38
+ // @implements A-SPEC-102.2, A-SPEC-102.6, A-SPEC-102.7
39
+ // `holmes-kit review record|status|gate|mrp` — the review verdict surface for callers that are not MCP clients.
40
+ const path = __importStar(require("node:path"));
41
+ const verdicts_1 = require("../review/verdicts");
42
+ /** The checklist from `--solid` values; an unreadable value is named. */
43
+ function parseSolid(values) {
44
+ const out = {};
45
+ for (const v of values) {
46
+ const m = /^([SOLID])=(compliant|violation|n-a):(.*)$/s.exec(v);
47
+ if (!m)
48
+ return { error: `--solid ${v} is not <S|O|L|I|D>=<compliant|violation|n-a>:<evidence>` };
49
+ out[m[1]] = { status: m[2], evidence: m[3].trim() };
50
+ }
51
+ return { solid: out };
52
+ }
53
+ exports.REVIEW_USAGE = 'usage: holmes-kit review record --base <rev> --head <rev> --verdict pass|fail [--finding <id>]… [--solid <S|O|L|I|D>=<compliant|violation|n-a>:<evidence>]… [--engine e] [--model m] [--session s] [--target <dir>]\n'
54
+ + ' holmes-kit review status --base <rev> --head <rev> [--target <dir>]\n'
55
+ + ' holmes-kit review gate --base <rev> --head <rev> [--strict] [--target <dir>]\n'
56
+ + ' holmes-kit review mrp --base <rev> --head <rev> [--target <dir>]\n';
57
+ function runReview(sub, opts, io, deps = {}) {
58
+ const root = path.resolve(opts.target ?? deps.cwd ?? process.cwd());
59
+ if (!opts.base || !opts.head || !['record', 'status', 'gate', 'mrp'].includes(sub ?? '')) {
60
+ io.stderr(exports.REVIEW_USAGE);
61
+ return 2;
62
+ }
63
+ // @implements A-SPEC-102.6 — the merge-ready package; exit 0 only when it is ready.
64
+ if (sub === 'mrp') {
65
+ const { buildMrp } = require('../review/mrp');
66
+ const m = buildMrp(root, opts.base, opts.head);
67
+ if ('error' in m) {
68
+ io.stderr(`✗ ${m.error}\n`);
69
+ return 1;
70
+ }
71
+ io.stdout(`${JSON.stringify(m, null, 2)}\n`);
72
+ return m.ready ? 0 : 1;
73
+ }
74
+ if (sub === 'record') {
75
+ if (opts.verdict !== 'pass' && opts.verdict !== 'fail') {
76
+ io.stderr(exports.REVIEW_USAGE);
77
+ return 2;
78
+ }
79
+ const solid = opts.solid && opts.solid.length > 0 ? parseSolid(opts.solid) : undefined;
80
+ if (solid && 'error' in solid) {
81
+ io.stderr(`✗ ${solid.error}\n`);
82
+ return 2;
83
+ }
84
+ const r = (0, verdicts_1.recordVerdict)(root, {
85
+ base: opts.base, head: opts.head, verdict: opts.verdict, findings: opts.findings ?? [],
86
+ ...(solid ? { solid: solid.solid } : {}),
87
+ ...(opts.engine ? { engine: opts.engine } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.session ? { session: opts.session } : {}),
88
+ }, {
89
+ env: deps.env ?? process.env, cwd: deps.cwd ?? process.cwd(),
90
+ interactive: deps.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
91
+ });
92
+ if (!r.ok) {
93
+ io.stderr(`✗ ${r.reason}\n`);
94
+ return 1;
95
+ }
96
+ io.stdout(`${JSON.stringify(r.record)}\n`);
97
+ return 0;
98
+ }
99
+ if (sub === 'status') {
100
+ const s = (0, verdicts_1.rangeStatus)(root, opts.base, opts.head);
101
+ if ('error' in s) {
102
+ io.stderr(`✗ ${s.error}\n`);
103
+ return 1;
104
+ }
105
+ io.stdout(`${JSON.stringify(s, null, 2)}\n`);
106
+ return 0;
107
+ }
108
+ const g = (0, verdicts_1.gateRange)(root, opts.base, opts.head, { strict: opts.strict === true });
109
+ io.stdout(`${JSON.stringify(g)}\n`);
110
+ return g.ok ? 0 : 1;
111
+ }
@@ -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 {};