@venizia/vulcan 0.4.8 → 0.4.9-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -221,56 +221,59 @@ export interface IVerdict {
221
221
  reason: string;
222
222
  }
223
223
 
224
- /**
225
- * What the guards say about one tool call: `deny` (blocked), `ask` (the owner decides; one reason holds every
226
- * guard that asked) or `allow`. Exported so a host that is not an extension (Antigravity's hook command) can
227
- * use the same policy.
228
- */
229
- export const verdictOf = (opts: {
230
- toolName: string;
231
- input: Record<string, unknown>;
232
- cwd: string;
233
- }): IVerdict => {
234
- const root = rootOf({ cwd: opts.cwd });
235
- const claudeEvent = claudeEventOf({ event: opts, root });
236
- const asks: string[] = [];
237
-
238
- if (claudeEvent === undefined) {
239
- return { kind: Verdicts.ALLOW, reason: '' };
240
- }
241
-
242
- for (const guard of GUARDS.filter((item) => item.tools.includes(opts.toolName))) {
243
- const answer = runGuard({ guard, root, claudeEvent });
244
-
245
- if (answer.kind === Answers.DENY) {
246
- return { kind: Verdicts.DENY, reason: answer.reason };
247
- }
248
-
249
- if (answer.kind === Answers.ASK) {
250
- asks.push(answer.reason);
224
+ export class GuardVerdict {
225
+ /**
226
+ * What the guards say about one tool call: `deny` (blocked), `ask` (the owner decides; one reason holds every
227
+ * guard that asked) or `allow`. Exported so a host that is not an extension (Antigravity's hook command) can
228
+ * use the same policy.
229
+ */
230
+ static verdictOf(opts: {
231
+ toolName: string;
232
+ input: Record<string, unknown>;
233
+ cwd: string;
234
+ }): IVerdict {
235
+ const root = rootOf({ cwd: opts.cwd });
236
+ const claudeEvent = claudeEventOf({ event: opts, root });
237
+ const asks: string[] = [];
238
+
239
+ if (claudeEvent === undefined) {
240
+ return { kind: Verdicts.ALLOW, reason: '' };
251
241
  }
252
242
 
253
- if (answer.kind === Answers.MISSING) {
254
- const isRepair = opts.toolName === Tools.BASH && BUN_INSTALL.test(String(opts.input.command));
243
+ for (const guard of GUARDS.filter((item) => item.tools.includes(opts.toolName))) {
244
+ const answer = runGuard({ guard, root, claudeEvent });
255
245
 
256
- if (guard.onFailure === Failures.BLOCK && !isRepair) {
246
+ if (answer.kind === Answers.DENY) {
257
247
  return { kind: Verdicts.DENY, reason: answer.reason };
258
248
  }
259
- }
260
249
 
261
- if (answer.kind === Answers.FAILED) {
262
- if (guard.onFailure === Failures.BLOCK) {
263
- return { kind: Verdicts.DENY, reason: answer.reason };
250
+ if (answer.kind === Answers.ASK) {
251
+ asks.push(answer.reason);
264
252
  }
265
253
 
266
- asks.push(answer.reason);
254
+ if (answer.kind === Answers.MISSING) {
255
+ const isRepair =
256
+ opts.toolName === Tools.BASH && BUN_INSTALL.test(String(opts.input.command));
257
+
258
+ if (guard.onFailure === Failures.BLOCK && !isRepair) {
259
+ return { kind: Verdicts.DENY, reason: answer.reason };
260
+ }
261
+ }
262
+
263
+ if (answer.kind === Answers.FAILED) {
264
+ if (guard.onFailure === Failures.BLOCK) {
265
+ return { kind: Verdicts.DENY, reason: answer.reason };
266
+ }
267
+
268
+ asks.push(answer.reason);
269
+ }
267
270
  }
268
- }
269
271
 
270
- return asks.length > 0
271
- ? { kind: Verdicts.ASK, reason: asks.join('\n\n') }
272
- : { kind: Verdicts.ALLOW, reason: '' };
273
- };
272
+ return asks.length > 0
273
+ ? { kind: Verdicts.ASK, reason: asks.join('\n\n') }
274
+ : { kind: Verdicts.ALLOW, reason: '' };
275
+ }
276
+ }
274
277
 
275
278
  /** Asks the owner when there is a UI to ask; without one the call is blocked, never let through. */
276
279
  const askOwner = async (opts: {
@@ -288,7 +291,11 @@ const askOwner = async (opts: {
288
291
 
289
292
  export default function vulcanGuards(host: IHost): void {
290
293
  host.on('tool_call', async (event, context) => {
291
- const verdict = verdictOf({ toolName: event.toolName, input: event.input, cwd: context.cwd });
294
+ const verdict = GuardVerdict.verdictOf({
295
+ toolName: event.toolName,
296
+ input: event.input,
297
+ cwd: context.cwd,
298
+ });
292
299
 
293
300
  if (verdict.kind === Verdicts.DENY) {
294
301
  return { block: true, reason: verdict.reason };
@@ -41,7 +41,8 @@ const parseJson = (opts: { text: string }): unknown => {
41
41
  }
42
42
  };
43
43
 
44
- const parsed = parseJson({ text: await Bun.stdin.text() });
44
+ const stdin = await Bun.stdin.text();
45
+ const parsed = parseJson({ text: stdin });
45
46
  const toolCall = isRecord(parsed) ? parsed.toolCall : undefined;
46
47
  const args = isRecord(toolCall) ? toolCall.args : undefined;
47
48
  const toolName = isRecord(toolCall) ? textOf(toolCall.name) : undefined;
@@ -52,10 +53,10 @@ const workspaces =
52
53
  if (tool === undefined || !isRecord(args)) {
53
54
  answer({ decision: 'allow' });
54
55
  } else {
55
- const { verdictOf } = await import('../extensions/vulcan-guards.ts');
56
+ const { GuardVerdict } = await import('../extensions/vulcan-guards.ts');
56
57
  const command = textOf(args.CommandLine);
57
58
  const path = textOf(args.TargetFile);
58
- const verdict = verdictOf({
59
+ const verdict = GuardVerdict.verdictOf({
59
60
  toolName: tool,
60
61
  input: Object.fromEntries([
61
62
  ['command', command],
@@ -29,20 +29,31 @@ const parseJson = (opts: { text: string }): unknown => {
29
29
  }
30
30
  };
31
31
 
32
- const parsed = parseJson({ text: await Bun.stdin.text() });
32
+ const stdin = await Bun.stdin.text();
33
+ const parsed = parseJson({ text: stdin });
33
34
  const toolInput = isRecord(parsed) ? parsed['tool_input'] : undefined;
34
35
  const tool = isRecord(parsed) ? textOf(parsed['tool_name']) : undefined;
35
36
  const command = isRecord(toolInput) ? textOf(toolInput['command']) : undefined;
36
37
  const cwd = (isRecord(parsed) ? textOf(parsed['cwd']) : undefined) ?? process.cwd();
37
38
 
38
39
  if (command !== undefined && (tool === 'Bash' || tool === 'apply_patch')) {
39
- const { verdictOf } = await import('../extensions/vulcan-guards.ts');
40
- const { patchedFilesOf } = await import('../../src/hooks/codex-patch.ts');
40
+ const { GuardVerdict } = await import('../extensions/vulcan-guards.ts');
41
+ const { CodexPatch } = await import('../../src/hooks/codex-patch.ts');
41
42
  const verdicts =
42
43
  tool === 'Bash'
43
- ? [verdictOf({ toolName: 'bash', input: Object.fromEntries([['command', command]]), cwd })]
44
- : patchedFilesOf({ patch: command, cwd }).map((file) =>
45
- verdictOf({ toolName: file.tool, input: Object.fromEntries([['path', file.path]]), cwd }),
44
+ ? [
45
+ GuardVerdict.verdictOf({
46
+ toolName: 'bash',
47
+ input: Object.fromEntries([['command', command]]),
48
+ cwd,
49
+ }),
50
+ ]
51
+ : CodexPatch.patchedFilesOf({ patch: command, cwd }).map((file) =>
52
+ GuardVerdict.verdictOf({
53
+ toolName: file.tool,
54
+ input: Object.fromEntries([['path', file.path]]),
55
+ cwd,
56
+ }),
46
57
  );
47
58
  const refused = verdicts.find((verdict) => verdict.kind === 'deny');
48
59
  const asked = verdicts.filter((verdict) => verdict.kind === 'ask');
@@ -25,17 +25,17 @@ const text = await Bun.stdin.text();
25
25
 
26
26
  try {
27
27
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
28
- const { buildToolDecision } = await import('../../src/hooks/decision.ts');
29
- const { inspectGit } = await import('../../src/hooks/guard-git.ts');
30
- const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
31
- const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
32
- const hookCommand = parseHookCommand({ text });
28
+ const { HookDecision } = await import('../../src/hooks/decision.ts');
29
+ const { GitGuard } = await import('../../src/hooks/guard-git.ts');
30
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
31
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
32
+ const hookCommand = WriteGuard.parseHookCommand({ text });
33
33
  const cwd = hookCommand?.cwd ?? process.cwd();
34
34
  const hits = hookCommand
35
- ? inspectGit({
35
+ ? GitGuard.inspect({
36
36
  command: hookCommand.command,
37
37
  cwd,
38
- askPush: readGuardPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).askPush,
38
+ askPush: ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).askPush,
39
39
  })
40
40
  : [];
41
41
 
@@ -44,7 +44,7 @@ try {
44
44
 
45
45
  console.log(
46
46
  JSON.stringify(
47
- buildToolDecision({
47
+ HookDecision.buildTool({
48
48
  decision: denied ? GuardDecisions.DENY : GuardDecisions.ASK,
49
49
  reason: [
50
50
  denied
@@ -12,12 +12,12 @@
12
12
  export {};
13
13
 
14
14
  try {
15
- const { buildManifestDecision, inspectManifestWrite, parseManifestHookInput } =
16
- await import('../../src/hooks/guard-manifest.ts');
17
- const input = parseManifestHookInput({ text: await Bun.stdin.text() });
15
+ const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
16
+ const stdin = await Bun.stdin.text();
17
+ const input = ManifestGuard.parseHookInput({ text: stdin });
18
18
 
19
- if (input && inspectManifestWrite({ input })) {
20
- console.log(JSON.stringify(buildManifestDecision()));
19
+ if (input && ManifestGuard.inspectWrite({ input })) {
20
+ console.log(JSON.stringify(ManifestGuard.buildDecision()));
21
21
  }
22
22
  } catch (error) {
23
23
  console.error(
@@ -24,18 +24,18 @@ const text = await Bun.stdin.text();
24
24
 
25
25
  try {
26
26
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
27
- const { buildToolDecision } = await import('../../src/hooks/decision.ts');
28
- const { inspectOutside } = await import('../../src/hooks/guard-outside.ts');
29
- const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
30
- const input = parseManifestHookInput({ text });
27
+ const { HookDecision } = await import('../../src/hooks/decision.ts');
28
+ const { OutsideGuard } = await import('../../src/hooks/guard-outside.ts');
29
+ const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
30
+ const input = ManifestGuard.parseHookInput({ text });
31
31
 
32
32
  if (input) {
33
33
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
34
34
  let toolOwnedPaths: string[] = [];
35
35
 
36
36
  try {
37
- const { loadConfig } = await import('../../src/config/index.ts');
38
- const loaded = await loadConfig({ root: projectRoot });
37
+ const { ConfigLoader } = await import('../../src/config/index.ts');
38
+ const loaded = await ConfigLoader.load({ root: projectRoot });
39
39
 
40
40
  toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
41
41
  } catch (error) {
@@ -44,7 +44,7 @@ try {
44
44
  );
45
45
  }
46
46
 
47
- const hits = inspectOutside({ input, projectRoot, toolOwnedPaths });
47
+ const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
48
48
 
49
49
  if (hits.length > 0) {
50
50
  const isScratchpad = hits.some((hit) => hit.isAgentToolScratchpad);
@@ -54,7 +54,7 @@ try {
54
54
 
55
55
  console.log(
56
56
  JSON.stringify(
57
- buildToolDecision({
57
+ HookDecision.buildTool({
58
58
  decision: isScratchpad ? GuardDecisions.DENY : GuardDecisions.ASK,
59
59
  reason: isScratchpad
60
60
  ? [
@@ -13,14 +13,14 @@
13
13
  export {};
14
14
 
15
15
  try {
16
- const { buildPackageDecision, inspectPackageWrite } =
17
- await import('../../src/hooks/guard-package.ts');
18
- const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
19
- const input = parseManifestHookInput({ text: await Bun.stdin.text() });
20
- const verdict = input && inspectPackageWrite({ input });
16
+ const { PackageGuard } = await import('../../src/hooks/guard-package.ts');
17
+ const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
18
+ const stdin = await Bun.stdin.text();
19
+ const input = ManifestGuard.parseHookInput({ text: stdin });
20
+ const verdict = input && PackageGuard.inspectWrite({ input });
21
21
 
22
22
  if (verdict) {
23
- console.log(JSON.stringify(buildPackageDecision({ verdict })));
23
+ console.log(JSON.stringify(PackageGuard.buildDecision({ verdict })));
24
24
  }
25
25
  } catch (error) {
26
26
  console.error(
@@ -11,13 +11,14 @@
11
11
  export {};
12
12
 
13
13
  try {
14
- const { buildRemoteDecision, inspectRemoteCommand, parseTrustedList } =
15
- await import('../../src/hooks/remote-hosts.ts');
16
- const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
14
+ const { RemoteHosts } = await import('../../src/hooks/remote-hosts.ts');
15
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
17
16
  const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
18
17
  const manifestFile = Bun.file(`${root}/.agents/vulcan.manifest.json`);
19
18
 
20
- if (!(await manifestFile.exists())) {
19
+ const manifestExists = await manifestFile.exists();
20
+
21
+ if (!manifestExists) {
21
22
  throw new Error('.agents/vulcan.manifest.json is missing - run vulcan sync');
22
23
  }
23
24
 
@@ -30,15 +31,19 @@ try {
30
31
 
31
32
  const localFile = typeof remoteHosts.localFile === 'string' ? remoteHosts.localFile : undefined;
32
33
  const local = localFile === undefined ? undefined : Bun.file(`${root}/${localFile}`);
33
- const personal = local !== undefined && (await local.exists()) ? await local.text() : '';
34
+ const localExists = await local?.exists();
35
+ const readingPersonal = localExists === true ? local?.text() : undefined;
36
+ const personalText = await readingPersonal;
37
+ const personal = personalText ?? '';
34
38
  const trusted: string[] = Array.isArray(remoteHosts.trusted) ? remoteHosts.trusted : [];
35
39
  const readOnly: string[] = Array.isArray(remoteHosts.readOnly) ? remoteHosts.readOnly : [];
36
- const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
40
+ const stdin = await Bun.stdin.text();
41
+ const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
37
42
  const hits = hookCommand
38
- ? inspectRemoteCommand({
43
+ ? RemoteHosts.inspectCommand({
39
44
  command: hookCommand.command,
40
45
  policy: {
41
- trusted: [...trusted, ...parseTrustedList({ text: personal })],
46
+ trusted: [...trusted, ...RemoteHosts.parseTrustedList({ text: personal })],
42
47
  readOnly,
43
48
  ...(localFile === undefined ? {} : { localFile }),
44
49
  },
@@ -46,7 +51,7 @@ try {
46
51
  : [{ rule: 'remote-hosts', message: 'the hook input could not be read' }];
47
52
 
48
53
  if (hits.length > 0) {
49
- console.log(JSON.stringify(buildRemoteDecision({ hits })));
54
+ console.log(JSON.stringify(RemoteHosts.buildDecision({ hits })));
50
55
  }
51
56
  } catch (error) {
52
57
  console.error(
@@ -17,13 +17,13 @@ if (process.env.VULCAN_GUARDS === 'off') {
17
17
  }
18
18
 
19
19
  try {
20
- const { buildScriptingAdvice, inspectScripting } =
21
- await import('../../src/hooks/guard-scripting.ts');
22
- const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
23
- const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
20
+ const { ScriptingGuard } = await import('../../src/hooks/guard-scripting.ts');
21
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
22
+ const stdin = await Bun.stdin.text();
23
+ const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
24
24
 
25
- if (hookCommand && inspectScripting({ command: hookCommand.command }).length > 0) {
26
- console.log(JSON.stringify(buildScriptingAdvice()));
25
+ if (hookCommand && ScriptingGuard.inspect({ command: hookCommand.command }).length > 0) {
26
+ console.log(JSON.stringify(ScriptingGuard.buildAdvice()));
27
27
  }
28
28
  } catch (error) {
29
29
  console.error(
@@ -5,6 +5,8 @@
5
5
  * checked beside the fixed list, inside compound commands too.
6
6
  * A script the project lists in `guard.writes.trustedScripts` is not read for writes while git says it
7
7
  * is tracked and unchanged; a config that cannot be read leaves the list empty, so every script is read.
8
+ * An entry of `guard.writes.readOnlyScripts` in the manifest (the object form of `trustedScripts`, written by
9
+ * `vulcan sync`) skips that read for the calls whose first argument after the script is one of its words.
8
10
  *
9
11
  * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so a hook that throws - a
10
12
  * partial install, say, where its own modules are missing - would let every command through. The
@@ -15,10 +17,10 @@
15
17
  export {};
16
18
 
17
19
  try {
18
- const { buildGuardDecision, inspectCommand, parseHookCommand } =
19
- await import('../../src/hooks/guard-writes.ts');
20
- const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
21
- const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
20
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
21
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
22
+ const stdin = await Bun.stdin.text();
23
+ const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
22
24
  const cwd = hookCommand?.cwd ?? process.cwd();
23
25
  let scripts: string[] = [];
24
26
 
@@ -26,10 +28,15 @@ try {
26
28
  // own, and may fail alone.
27
29
  if (hookCommand && /\.ts\b/.test(hookCommand.command)) {
28
30
  try {
29
- const { loadConfig } = await import('../../src/config/index.ts');
30
- const loaded = await loadConfig({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
31
+ const { ConfigLoader } = await import('../../src/config/index.ts');
32
+ const loaded = await ConfigLoader.load({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
31
33
 
32
- scripts = loaded.ok ? loaded.config.guard.writes.trustedScripts : [];
34
+ // The objects are the read-only entries: the manifest carries them, so only the paths count here.
35
+ scripts = loaded.ok
36
+ ? loaded.config.guard.writes.trustedScripts.filter(
37
+ (entry): entry is string => typeof entry === 'string',
38
+ )
39
+ : [];
33
40
  } catch (error) {
34
41
  console.error(
35
42
  `vulcan: the guard-writes hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - every script is read`,
@@ -37,17 +44,19 @@ try {
37
44
  }
38
45
  }
39
46
 
47
+ const root = process.env.CLAUDE_PROJECT_DIR ?? cwd;
48
+ const policy = ProjectGuards.readPolicy({ root });
40
49
  const hits = hookCommand
41
- ? inspectCommand({
50
+ ? WriteGuard.inspectCommand({
42
51
  command: hookCommand.command,
43
52
  cwd,
44
- trust: { root: process.env.CLAUDE_PROJECT_DIR ?? cwd, scripts },
45
- extra: readGuardPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).commands,
53
+ trust: { root, scripts, readOnlyScripts: policy.readOnlyScripts },
54
+ extra: policy.commands,
46
55
  })
47
56
  : [];
48
57
 
49
58
  if (hits.length > 0) {
50
- console.log(JSON.stringify(buildGuardDecision({ hits })));
59
+ console.log(JSON.stringify(WriteGuard.buildDecision({ hits })));
51
60
  }
52
61
  } catch (error) {
53
62
  console.error(
@@ -14,10 +14,11 @@ if (process.env.VULCAN_GUARDS === 'off') {
14
14
  }
15
15
 
16
16
  try {
17
- const { buildPostToolOutput } = await import('../../src/hooks/post-tool.ts');
18
- const output = buildPostToolOutput({
17
+ const { PostToolOutput } = await import('../../src/hooks/post-tool.ts');
18
+ const stdin = await Bun.stdin.text();
19
+ const output = PostToolOutput.build({
19
20
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
20
- input: JSON.parse(await Bun.stdin.text()),
21
+ input: JSON.parse(stdin),
21
22
  });
22
23
 
23
24
  if (output !== undefined) {
@@ -14,11 +14,12 @@ if (process.env.VULCAN_GUARDS === 'off') {
14
14
  }
15
15
 
16
16
  try {
17
- const { buildPromptContract } = await import('../../src/hooks/owner-reply.ts');
17
+ const { OwnerReply } = await import('../../src/hooks/owner-reply.ts');
18
18
  let session = '';
19
19
 
20
20
  try {
21
- const event: unknown = JSON.parse(await Bun.stdin.text());
21
+ const stdin = await Bun.stdin.text();
22
+ const event: unknown = JSON.parse(stdin);
22
23
 
23
24
  if (
24
25
  typeof event === 'object' &&
@@ -32,7 +33,7 @@ try {
32
33
  // No readable event: the turn is noted for no session, and nothing is echoed.
33
34
  }
34
35
 
35
- const line = await buildPromptContract({
36
+ const line = await OwnerReply.buildPromptContract({
36
37
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
37
38
  session,
38
39
  });
@@ -3,15 +3,17 @@
3
3
  * Stdout becomes session context. With `VULCAN_OWNER_REPLY=off` the owner shape and profile cards are left out.
4
4
  * It also exports `TMPDIR` (the project's `.agents/local/tmp`) into the file Claude Code sources before each Bash command.
5
5
  */
6
- import { buildSessionDigest, exportProjectTmp } from '../../src/hooks/index.ts';
6
+ import { ProjectTmp, SessionDigest } from '../../src/hooks/index.ts';
7
7
 
8
8
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
9
9
 
10
- process.stdout.write(await buildSessionDigest({ projectRoot }));
10
+ const digest = await SessionDigest.build({ projectRoot });
11
+
12
+ process.stdout.write(digest);
11
13
 
12
14
  // Claude Code gives this hook a file it sources before each Bash command: the project's temp folder goes in it.
13
15
  try {
14
- exportProjectTmp({ root: projectRoot, envFile: process.env.CLAUDE_ENV_FILE });
16
+ ProjectTmp.exportProjectTmp({ root: projectRoot, envFile: process.env.CLAUDE_ENV_FILE });
15
17
  } catch (error) {
16
18
  console.error(
17
19
  `vulcan: [session-start] could not make TMPDIR the project's temp folder: ${error}`,
@@ -17,10 +17,11 @@ if (process.env.VULCAN_GUARDS === 'off') {
17
17
  }
18
18
 
19
19
  try {
20
- const { buildStopOutput } = await import('../../src/hooks/owner-reply.ts');
21
- const output = await buildStopOutput({
20
+ const { OwnerReply } = await import('../../src/hooks/owner-reply.ts');
21
+ const stdin = await Bun.stdin.text();
22
+ const output = await OwnerReply.buildStopOutput({
22
23
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
23
- input: JSON.parse(await Bun.stdin.text()),
24
+ input: JSON.parse(stdin),
24
25
  });
25
26
 
26
27
  if (output !== undefined) {
@@ -8,9 +8,9 @@
8
8
  export {};
9
9
 
10
10
  try {
11
- const { buildSubagentStartOutput } = await import('../../src/hooks/subagent-card.ts');
11
+ const { SubagentCard } = await import('../../src/hooks/subagent-card.ts');
12
12
 
13
- console.log(JSON.stringify(buildSubagentStartOutput()));
13
+ console.log(JSON.stringify(SubagentCard.buildStartOutput()));
14
14
  } catch (error) {
15
15
  console.error(
16
16
  `vulcan: the subagent-start hook could not build the card (${error instanceof Error ? error.message : String(error)}) - the subagent starts without it`,
@@ -7,7 +7,7 @@ VULCAN_BASE ?= node_modules/@venizia/vulcan/base
7
7
  # The GitHub repository the wiki links point into, owner/name; the link gate checks only links into it.
8
8
  WIKI_REPO ?=
9
9
 
10
- .PHONY: vulcan-sync vulcan-doctor agent-setup okf-check okf-check-strict okf-gen okf-coverage okf-viz \
10
+ .PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage okf-viz \
11
11
  surface-gen surface-check atlas-symbols atlas-releases changelogs-migrate \
12
12
  knowledge-symbols-check wiki-links-check wiki-anchors-check
13
13
 
@@ -17,9 +17,6 @@ vulcan-sync: ## Write the agent adapters, settings, skill links and manifest fro
17
17
  vulcan-doctor: ## Check the project against the VULCAN contract
18
18
  @$(VULCAN) doctor
19
19
 
20
- # The older name for the same job, kept for muscle memory.
21
- agent-setup: vulcan-sync ## The older name for vulcan-sync
22
-
23
20
  # OKF v0.2 conformance only; okf-check-strict adds the house rules (links, style, coverage, freshness).
24
21
  okf-check: ## Check the knowledge bundle against OKF v0.2
25
22
  @$(VULCAN) x okf check
@@ -129,7 +129,7 @@ Done when every check passed in this session and the behaviour is shown.
129
129
 
130
130
  When **Docs impact** is not `none`, run the `docs-update` skill now, after the checks of step 6 and
131
131
  before review: it refreshes the page that owns the
132
- topic, writes the changelog entry when the change is release-worthy, and runs the docs gates. Then each
132
+ topic, writes the changelog entry when the change affects users of the published packages, and runs the docs gates. Then each
133
133
  fact about the project that changed - a new concept, a decision, a gotcha - goes into the knowledge
134
134
  bundle in the same change. The reviewer sees the docs in the diff.
135
135
 
@@ -34,7 +34,7 @@ Copy it into your reply and tick it off, in order:
34
34
  - [ ] 2. Code read - the changed source, not a diff summary, not dist/, not another doc
35
35
  - [ ] 3. Page picked - the page that owns the topic; a new one only when none does, wired in
36
36
  - [ ] 4. Page written and self-reviewed with the docs-writing skill
37
- - [ ] 5. Changelog entry written (release-worthy changes only)
37
+ - [ ] 5. Changelog entry written (only when the change affects users of the published packages)
38
38
  - [ ] 6. Gates green (loop until they are)
39
39
  - [ ] 7. Reported; nothing committed
40
40
  ```
@@ -78,16 +78,22 @@ Every code sample uses the names and signatures from step 2.
78
78
 
79
79
  ## 5. Changelog
80
80
 
81
- Only for a release-worthy change: a feature, a fix a user notices, a breaking change.
81
+ Only for a change that affects the users of the published packages and what they can use: a new feature,
82
+ command, option or config key; changed behaviour or a breaking change (with its upgrade step); a bug fix a user
83
+ could hit; a security fix; a deprecation or a removal. Internal work gets no entry: release tooling, CI and
84
+ workflows, guards and gates, a refactor with no behaviour change, tests, agent rules and skills for the repo's
85
+ own sessions, internal docs and knowledge pages, repo hygiene. A change that is only internal skips this step
86
+ and says so.
82
87
 
83
88
  1. **The file.** `<knowledge.changelogs>/YYYY-MM-DD-<slug>.md`, from the directory's `template.md`.
84
89
  No template: copy the shape of the newest entry. Keep only the sections that apply. When an
85
90
  entry for the coming release already exists, add a bullet to it instead of opening a second.
86
91
  2. **The `packages:` list** (Project Contract v1, C3). The frontmatter lists the npm names, from
87
- `packages[].name`, of every package the entry covers: `packages: ['@scope/core']`. An entry about
88
- no package, such as repository tooling, carries `packages: []`. Never leave the list out -
92
+ `packages[].name`, of every package the entry covers: `packages: ['@scope/core']`. An entry that covers
93
+ no package is internal work, and internal work has no entry. Never leave the list out -
89
94
  `okf check --strict` fails the entry.
90
- 3. **The content.** What changed, who is affected, how to migrate. It is not a commit log.
95
+ 3. **The content.** Short, and in the user's terms: what changed and the benefit, who is affected, how to
96
+ migrate. It is not a commit log, and it does not say how the change was built.
91
97
  4. **The index.** When the directory's `index.md` lists entries, add a row in its order.
92
98
 
93
99
  ## 6. Gates - validate, fix, repeat
@@ -10,7 +10,7 @@
10
10
  {
11
11
  "id": 1,
12
12
  "prompt": "Add a changelog entry for last week's change to the repository's CI and release tooling. It touches no package. Do not commit.",
13
- "expected_output": "One dated entry under the manifest's knowledge.changelogs, shaped by the directory's template, carrying packages: [] in its frontmatter, added to the changelog index when one lists entries; okf check --strict passes; nothing committed",
13
+ "expected_output": "Writes no changelog entry: CI and release tooling is internal work that touches no package and affects no user of the published packages, and the changelog records only what affects users; says so in one line and names what would need an entry (a feature, a changed behaviour, a fix a user could hit, a security fix, a removal); changes no file; nothing committed",
14
14
  "files": [".agents/vulcan.manifest.json"]
15
15
  },
16
16
  {
@@ -85,7 +85,7 @@ Read the finished page once, top to bottom, as the reader from Step 1. If any se
85
85
  - Never abbreviate identifiers (Repository, not Repo; TDocument, not TDoc) - in prose and in samples (V-C-04).
86
86
  - Every code sample must compile against the real source. Verify names and signatures in the source before writing them. Examples import what app code imports; prose names the canonical name and lists aliases.
87
87
  - File links point at a file, never at a line number: lines move, files rarely do.
88
- - Changelogs are user-facing: what changed, who is affected, how to migrate. Not a commit log.
88
+ - Changelogs are user-facing and short: what changed and the benefit, who is affected, how to migrate. Not a commit log, and nothing internal.
89
89
  - The project's docs-site rules (its generator's limits, link style) live in `.agents/rules.md` or its own skill.
90
90
  - The knowledge bundle (`.agents/knowledge`) follows the same sentence rules. Its readers are agents, but a wall of text fails them too - use short paragraphs and bullets, keep the "constraint the code cannot show" focus.
91
91
 
@@ -17,7 +17,7 @@ In this order:
17
17
  | Claims | `C1..Cn`: one observable behaviour each, and for each the probe that would show it false. Behaviour is phrased WHEN ... THEN ... |
18
18
  | Anti-claims | What must not happen, in the universal form where you can ("no X in any path"). Lane L has at least one |
19
19
  | Seams | The public boundaries tests attach to. An existing seam is preferred; the ideal count is one |
20
- | Docs impact | The pages, knowledge concepts and changelog entry that change, or `none` with the reason |
20
+ | Docs impact | The pages, knowledge concepts and changelog entry that change (an entry only when users of the published packages are affected), or `none` with the reason |
21
21
  | Open | Questions too dim to be claims, each naming who resolves it. Empty before work starts |
22
22
  | Decisions | Dated, append-only. Dead ends and rejected alternatives stay. A `refined:` prefix marks a change of goal or claim |
23
23
 
@@ -28,7 +28,7 @@ It rises with the lane (see `plan-a-change`). A small edit (lane S) ends as `rep
28
28
 
29
29
  - Every claim of the card is closed with an evidence stub (the probe and its result).
30
30
  - The docs slice is done and the docs gates are green (`docs-update` skill).
31
- - A changelog entry exists when the change is worth releasing.
31
+ - A changelog entry exists when the change affects users of the published packages (a feature, a changed behaviour, a fix a user could hit, a security fix, a removal). A change that is only internal (tooling, CI, refactors, tests, internal docs) has none.
32
32
  - The checks are quoted with their results, from this session: build, lint, tests, the project's own gates.
33
33
  - **Open** (the card's open decisions) is empty, or each item is named for the owner.
34
34
  - The class sweep is done: the same defect was looked for elsewhere, not only where it was found.