@venizia/vulcan 0.3.13 → 0.4.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 (141) hide show
  1. package/base/claude/remote-hosts.json +1 -1
  2. package/base/claude/settings.json +75 -3
  3. package/base/hooks/guard-git.ts +55 -0
  4. package/base/hooks/guard-manifest.ts +1 -1
  5. package/base/hooks/guard-outside.ts +66 -0
  6. package/base/hooks/guard-package.ts +3 -2
  7. package/base/hooks/guard-remote-hosts.ts +3 -2
  8. package/base/hooks/guard-writes.ts +1 -1
  9. package/base/hooks/post-tool.ts +36 -0
  10. package/base/hooks/prompt-submit.ts +52 -0
  11. package/base/hooks/stop.ts +38 -0
  12. package/base/hooks/subagent-start.ts +18 -0
  13. package/base/references/delegation-brief.md +63 -0
  14. package/base/references/design-pass.md +39 -0
  15. package/base/references/evidence.md +36 -0
  16. package/base/references/phase-boundaries.md +20 -0
  17. package/base/references/testing.md +89 -0
  18. package/base/rules.md +11 -2
  19. package/base/skills/build-a-feature/SKILL.md +49 -23
  20. package/base/skills/docs-update/SKILL.md +12 -1
  21. package/base/skills/docs-writing/SKILL.md +2 -2
  22. package/base/skills/docs-writing/references/agent-documents.md +53 -0
  23. package/base/skills/fix-a-bug/SKILL.md +84 -0
  24. package/base/skills/fix-a-bug/evals/evals.json +17 -0
  25. package/base/skills/knowledge-sync/SKILL.md +4 -1
  26. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
  27. package/base/skills/plan-a-change/SKILL.md +95 -0
  28. package/base/skills/plan-a-change/evals/evals.json +23 -0
  29. package/base/skills/plan-a-change/references/spec-card.md +39 -0
  30. package/base/skills/report-back/SKILL.md +112 -0
  31. package/base/skills/report-back/evals/evals.json +23 -0
  32. package/base/skills/research/SKILL.md +64 -0
  33. package/base/skills/research/evals/evals.json +17 -0
  34. package/base/skills/retro/SKILL.md +69 -0
  35. package/base/skills/retro/evals/evals.json +17 -0
  36. package/base/skills/review-a-change/SKILL.md +90 -0
  37. package/base/skills/review-a-change/evals/evals.json +17 -0
  38. package/base/skills/ship/SKILL.md +82 -0
  39. package/base/skills/ship/evals/evals.json +23 -0
  40. package/base/skills/visualize-work/SKILL.md +87 -0
  41. package/base/skills/visualize-work/evals/evals.json +17 -0
  42. package/base/skills/visualize-work/references/spec.md +65 -0
  43. package/package.json +4 -4
  44. package/src/agents/common/schema.ts +2 -2
  45. package/src/agents/detect.ts +5 -5
  46. package/src/agents/exclude.ts +3 -3
  47. package/src/agents/local.ts +1 -1
  48. package/src/agents/prompt.ts +2 -2
  49. package/src/agents/render.ts +2 -2
  50. package/src/agents/resolve.ts +6 -6
  51. package/src/agents/table.ts +1 -1
  52. package/src/commands/agents.command.ts +4 -4
  53. package/src/commands/clean.command.ts +72 -0
  54. package/src/commands/help.command.ts +11 -0
  55. package/src/commands/index.ts +6 -0
  56. package/src/commands/init.command.ts +4 -1
  57. package/src/commands/profile.command.ts +255 -0
  58. package/src/commands/sync.command.ts +6 -4
  59. package/src/commands/upgrade.command.ts +1 -1
  60. package/src/commands/visualize.command.ts +107 -0
  61. package/src/common/constants.ts +23 -0
  62. package/src/config/common/constants.ts +2 -0
  63. package/src/config/loader.ts +4 -4
  64. package/src/config/packages.ts +1 -1
  65. package/src/config/schema.ts +16 -5
  66. package/src/create/add-app.ts +15 -15
  67. package/src/create/add-lib.ts +7 -7
  68. package/src/create/bunfig.ts +1 -1
  69. package/src/create/dockerignore.ts +4 -4
  70. package/src/create/init-monorepo.ts +3 -1
  71. package/src/create/lib-preset.ts +1 -1
  72. package/src/create/names.ts +7 -6
  73. package/src/create/next.ts +4 -4
  74. package/src/create/preset-menu.ts +4 -4
  75. package/src/create/preset.ts +3 -3
  76. package/src/create/scratch.ts +27 -6
  77. package/src/create/workspace.ts +11 -11
  78. package/src/doctor/checks.ts +231 -45
  79. package/src/doctor/common/constants.ts +4 -0
  80. package/src/doctor/makefile.ts +3 -3
  81. package/src/doctor/runner.ts +16 -1
  82. package/src/doctor/skills.ts +8 -8
  83. package/src/doctor/tags.ts +5 -5
  84. package/src/hooks/common/constants.ts +29 -0
  85. package/src/hooks/common/types.ts +20 -0
  86. package/src/hooks/decision.ts +15 -0
  87. package/src/hooks/guard-git.ts +288 -0
  88. package/src/hooks/guard-manifest.ts +1 -1
  89. package/src/hooks/guard-outside.ts +399 -0
  90. package/src/hooks/guard-package.ts +4 -4
  91. package/src/hooks/guard-writes.ts +5 -5
  92. package/src/hooks/index.ts +6 -0
  93. package/src/hooks/owner-reply.ts +148 -0
  94. package/src/hooks/post-tool.ts +137 -0
  95. package/src/hooks/remote-hosts.ts +25 -23
  96. package/src/hooks/session-digest.ts +24 -4
  97. package/src/hooks/shell.ts +325 -0
  98. package/src/hooks/subagent-card.ts +32 -0
  99. package/src/init/scaffold.ts +6 -6
  100. package/src/local/clean.ts +88 -0
  101. package/src/local/constants.ts +50 -0
  102. package/src/local/format.ts +25 -0
  103. package/src/local/index.ts +4 -0
  104. package/src/local/scan.ts +368 -0
  105. package/src/manifest/render.ts +1 -1
  106. package/src/owner/card.ts +85 -0
  107. package/src/owner/constants.ts +105 -0
  108. package/src/owner/index.ts +8 -0
  109. package/src/owner/profile.ts +123 -0
  110. package/src/owner/schema.ts +147 -0
  111. package/src/owner/shape.ts +380 -0
  112. package/src/owner/survey.ts +289 -0
  113. package/src/owner/view.ts +76 -0
  114. package/src/owner/violations.ts +202 -0
  115. package/src/router.ts +18 -1
  116. package/src/rules/base.ts +1 -1
  117. package/src/rules/parser.ts +5 -5
  118. package/src/signals/claims.ts +71 -0
  119. package/src/signals/classify.ts +132 -0
  120. package/src/signals/constants.ts +88 -0
  121. package/src/signals/index.ts +5 -0
  122. package/src/signals/loop.ts +46 -0
  123. package/src/signals/state.ts +276 -0
  124. package/src/sync/agent-files.ts +4 -4
  125. package/src/sync/agent-removal.ts +6 -6
  126. package/src/sync/atlas-block.ts +1 -1
  127. package/src/sync/base-rules.ts +1 -1
  128. package/src/sync/exclude.ts +9 -9
  129. package/src/sync/local-choice.ts +35 -5
  130. package/src/sync/planner.ts +16 -16
  131. package/src/sync/prune.ts +3 -3
  132. package/src/sync/settings.ts +15 -15
  133. package/src/ui/prompt.ts +3 -3
  134. package/src/visualize/assets.ts +80 -0
  135. package/src/visualize/constants.ts +126 -0
  136. package/src/visualize/index.ts +6 -0
  137. package/src/visualize/layout.ts +107 -0
  138. package/src/visualize/page.ts +211 -0
  139. package/src/visualize/render.ts +161 -0
  140. package/src/visualize/schema.ts +178 -0
  141. package/src/visualize/validate.ts +127 -0
@@ -6,7 +6,7 @@
6
6
  "hooks": [
7
7
  {
8
8
  "type": "command",
9
- "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-remote-hosts.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-remote-hosts hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-remote-hosts hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
9
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-remote-hosts.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -f \"$f\" ] || echo \"vulcan: the guard-remote-hosts hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-remote-hosts hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
10
10
  }
11
11
  ]
12
12
  }
@@ -19,7 +19,7 @@
19
19
  "hooks": [
20
20
  {
21
21
  "type": "command",
22
- "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; then exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-writes hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-writes hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
22
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -f \"$f\" ] || echo \"vulcan: the guard-writes hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-writes hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
23
23
  }
24
24
  ]
25
25
  },
@@ -28,7 +28,7 @@
28
28
  "hooks": [
29
29
  {
30
30
  "type": "command",
31
- "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-manifest.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; then exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-manifest hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-manifest hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
31
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-manifest.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -f \"$f\" ] || echo \"vulcan: the guard-manifest hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-manifest hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
32
32
  }
33
33
  ]
34
34
  },
@@ -37,7 +37,79 @@
37
37
  "hooks": [
38
38
  {
39
39
  "type": "command",
40
- "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-package.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; then exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-package hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-package hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
40
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-package.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -f \"$f\" ] || echo \"vulcan: the guard-package hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-package hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
41
+ }
42
+ ]
43
+ },
44
+ {
45
+ "matcher": "Bash",
46
+ "hooks": [
47
+ {
48
+ "type": "command",
49
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-git.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the guard-git hook failed - the call passes\" >&2; exit 0; fi; echo \"vulcan: the guard-git hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes\" >&2; exit 0"
50
+ }
51
+ ]
52
+ },
53
+ {
54
+ "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
55
+ "hooks": [
56
+ {
57
+ "type": "command",
58
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-outside.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the guard-outside hook failed - the call passes\" >&2; exit 0; fi; echo \"vulcan: the guard-outside hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes\" >&2; exit 0"
59
+ }
60
+ ]
61
+ }
62
+ ],
63
+ "SubagentStart": [
64
+ {
65
+ "hooks": [
66
+ {
67
+ "type": "command",
68
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/subagent-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; [ -f \"$f\" ] || echo \"vulcan: the subagent-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the subagent-start hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
69
+ }
70
+ ]
71
+ }
72
+ ],
73
+ "UserPromptSubmit": [
74
+ {
75
+ "hooks": [
76
+ {
77
+ "type": "command",
78
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/prompt-submit.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the prompt-submit hook failed - the prompt goes through\" >&2; exit 0; fi; echo \"vulcan: the prompt-submit hook cannot run: node_modules/@venizia/vulcan or bun is missing - the prompt goes through\" >&2; exit 0",
79
+ "timeout": 15
80
+ }
81
+ ]
82
+ }
83
+ ],
84
+ "Stop": [
85
+ {
86
+ "hooks": [
87
+ {
88
+ "type": "command",
89
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/stop.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the stop hook failed - the reply passes\" >&2; exit 0; fi; echo \"vulcan: the stop hook cannot run: node_modules/@venizia/vulcan or bun is missing - the reply passes\" >&2; exit 0",
90
+ "timeout": 15
91
+ }
92
+ ]
93
+ }
94
+ ],
95
+ "PostToolUse": [
96
+ {
97
+ "hooks": [
98
+ {
99
+ "type": "command",
100
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/post-tool.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the post-tool hook failed - the call is unaffected\" >&2; exit 0; fi; echo \"vulcan: the post-tool hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call is unaffected\" >&2; exit 0",
101
+ "timeout": 15
102
+ }
103
+ ]
104
+ }
105
+ ],
106
+ "PostToolUseFailure": [
107
+ {
108
+ "hooks": [
109
+ {
110
+ "type": "command",
111
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/post-tool.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the post-tool hook failed - the call is unaffected\" >&2; exit 0; fi; echo \"vulcan: the post-tool hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call is unaffected\" >&2; exit 0",
112
+ "timeout": 15
41
113
  }
42
114
  ]
43
115
  }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * PreToolUse hook on Bash: parses the command (quotes, `&&`, `;`, `git -C`, heredocs) and catches the git
3
+ * and gh actions that lose history or a protected branch - deleting, renaming or force-pushing develop
4
+ * or main, `gh pr merge --delete-branch` on a pull request whose head is one of them (deny), and
5
+ * `reset --hard`, other force-pushes and `branch -D` of an unmerged branch (ask).
6
+ *
7
+ * It fails OPEN: it guards against drift, it is not the last line of defence, and a guard that blocks
8
+ * every command when it breaks costs more than it protects. Input it cannot read, a missing module or an
9
+ * internal error pass the call with a note on stderr. `VULCAN_GUARDS=off` switches it off, read before
10
+ * anything is imported. It imports only the modules it needs - no config, no zod.
11
+ */
12
+
13
+ // A module, so the awaits below are top-level; it has no static import, by design.
14
+ export {};
15
+
16
+ if (process.env.VULCAN_GUARDS === 'off') {
17
+ process.exit(0);
18
+ }
19
+
20
+ try {
21
+ const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
22
+ const { buildToolDecision } = await import('../../src/hooks/decision.ts');
23
+ const { inspectGit } = await import('../../src/hooks/guard-git.ts');
24
+ const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
25
+ const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
26
+ const hits = hookCommand
27
+ ? inspectGit({ command: hookCommand.command, cwd: hookCommand.cwd ?? process.cwd() })
28
+ : [];
29
+
30
+ if (hits.length > 0) {
31
+ const denied = hits.some((hit) => hit.decision === GuardDecisions.DENY);
32
+
33
+ console.log(
34
+ JSON.stringify(
35
+ buildToolDecision({
36
+ decision: denied ? GuardDecisions.DENY : GuardDecisions.ASK,
37
+ reason: [
38
+ denied
39
+ ? 'This command is refused by the base rules:'
40
+ : 'This command needs a human to confirm:',
41
+ ...hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
42
+ '',
43
+ denied
44
+ ? 'Hand the exact command to the owner instead (V-W-06); VULCAN_GUARDS=off switches the guards off for a session.'
45
+ : 'Confirm only if the owner asked for exactly this.',
46
+ ],
47
+ }),
48
+ ),
49
+ );
50
+ }
51
+ } catch (error) {
52
+ console.error(
53
+ `vulcan: the guard-git hook failed (${error instanceof Error ? error.message : String(error)}) - the call passes; run bun install`,
54
+ );
55
+ }
@@ -13,7 +13,7 @@ export {};
13
13
 
14
14
  try {
15
15
  const { buildManifestDecision, inspectManifestWrite, parseManifestHookInput } =
16
- await import('../../src/hooks/index.ts');
16
+ await import('../../src/hooks/guard-manifest.ts');
17
17
  const input = parseManifestHookInput({ text: await Bun.stdin.text() });
18
18
 
19
19
  if (input && inspectManifestWrite({ input })) {
@@ -0,0 +1,66 @@
1
+ /**
2
+ * PreToolUse hook on Bash and file writes: asks when a file, worktree, clone or temp file would be
3
+ * created outside the project (V-B-08). Stores a package manager, runtime or the agent tool manage
4
+ * themselves are allowed - a default list, extended by `guard.toolOwnedPaths` in the project config.
5
+ * `TMPDIR` or `mktemp` pointed at the system temp directory is not allowed.
6
+ *
7
+ * It fails OPEN: it guards against drift, not against an attacker, and a guard that blocks every call
8
+ * when it breaks costs more than it protects. Input it cannot read, a missing module or an internal
9
+ * error pass the call with a note on stderr; a project config that cannot be read leaves the default
10
+ * allowlist. `VULCAN_GUARDS=off` switches it off, read before anything is imported. It imports only
11
+ * the modules it needs - the config loader (and zod) is loaded on its own, last, and may fail alone.
12
+ */
13
+
14
+ // A module, so the awaits below are top-level; it has no static import, by design.
15
+ export {};
16
+
17
+ if (process.env.VULCAN_GUARDS === 'off') {
18
+ process.exit(0);
19
+ }
20
+
21
+ try {
22
+ const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
23
+ const { buildToolDecision } = await import('../../src/hooks/decision.ts');
24
+ const { inspectOutside } = await import('../../src/hooks/guard-outside.ts');
25
+ const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
26
+ const input = parseManifestHookInput({ text: await Bun.stdin.text() });
27
+
28
+ if (input) {
29
+ const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
30
+ let toolOwnedPaths: string[] = [];
31
+
32
+ try {
33
+ const { loadConfig } = await import('../../src/config/index.ts');
34
+ const loaded = await loadConfig({ root: projectRoot });
35
+
36
+ toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
37
+ } catch (error) {
38
+ console.error(
39
+ `vulcan: the guard-outside hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - the default allowlist applies`,
40
+ );
41
+ }
42
+
43
+ const hits = inspectOutside({ input, projectRoot, toolOwnedPaths });
44
+
45
+ if (hits.length > 0) {
46
+ console.log(
47
+ JSON.stringify(
48
+ buildToolDecision({
49
+ decision: GuardDecisions.ASK,
50
+ reason: [
51
+ 'This would create files outside the project (V-B-08):',
52
+ ...hits.map((hit) => ` - ${hit.message} (${hit.path})`),
53
+ '',
54
+ 'Everything an agent creates lives under .agents/local/ (tmp/, worktrees/, clones/). Use it, or confirm if the owner asked for this exact path.',
55
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
56
+ ],
57
+ }),
58
+ ),
59
+ );
60
+ }
61
+ }
62
+ } catch (error) {
63
+ console.error(
64
+ `vulcan: the guard-outside hook failed (${error instanceof Error ? error.message : String(error)}) - the call passes; run bun install`,
65
+ );
66
+ }
@@ -13,8 +13,9 @@
13
13
  export {};
14
14
 
15
15
  try {
16
- const { buildPackageDecision, inspectPackageWrite, parseManifestHookInput } =
17
- await import('../../src/hooks/index.ts');
16
+ const { buildPackageDecision, inspectPackageWrite } =
17
+ await import('../../src/hooks/guard-package.ts');
18
+ const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
18
19
  const input = parseManifestHookInput({ text: await Bun.stdin.text() });
19
20
  const verdict = input && inspectPackageWrite({ input });
20
21
 
@@ -11,8 +11,9 @@
11
11
  export {};
12
12
 
13
13
  try {
14
- const { buildRemoteDecision, inspectRemoteCommand, parseHookCommand, parseTrustedList } =
15
- await import('../../src/hooks/index.ts');
14
+ const { buildRemoteDecision, inspectRemoteCommand, parseTrustedList } =
15
+ await import('../../src/hooks/remote-hosts.ts');
16
+ const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
16
17
  const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
17
18
  const manifestFile = Bun.file(`${root}/.agents/vulcan.manifest.json`);
18
19
 
@@ -12,7 +12,7 @@ export {};
12
12
 
13
13
  try {
14
14
  const { buildGuardDecision, inspectCommand, parseHookCommand } =
15
- await import('../../src/hooks/index.ts');
15
+ await import('../../src/hooks/guard-writes.ts');
16
16
  const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
17
17
  const hits = hookCommand
18
18
  ? inspectCommand({ command: hookCommand.command, cwd: hookCommand.cwd ?? process.cwd() })
@@ -0,0 +1,36 @@
1
+ /**
2
+ * PostToolUse and PostToolUseFailure hook: keeps small notes about the turn for the Stop check (was public
3
+ * state probed, did the last gate pass) and tells the model when it seems stuck - the same call three times,
4
+ * two calls alternating, one tool failing again and again - or when it just changed a skill or a rules file.
5
+ * It never blocks and it fails OPEN. It imports only the signals module: no config, no zod, because it runs
6
+ * after every tool call. `VULCAN_GUARDS=off` switches it off, read before anything is imported.
7
+ */
8
+
9
+ // A module, so the awaits below are top-level; it has no static import, by design.
10
+ export {};
11
+
12
+ if (process.env.VULCAN_GUARDS === 'off') {
13
+ process.exit(0);
14
+ }
15
+
16
+ try {
17
+ const { buildPostToolOutput } = await import('../../src/hooks/post-tool.ts');
18
+ const output = buildPostToolOutput({
19
+ projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
20
+ input: JSON.parse(await Bun.stdin.text()),
21
+ });
22
+
23
+ if (output !== undefined) {
24
+ console.log(JSON.stringify(output));
25
+ }
26
+ } catch (error) {
27
+ // Input that is not JSON is not echoed: Bun's parse error quotes it.
28
+ const reason =
29
+ error instanceof SyntaxError
30
+ ? 'unreadable input'
31
+ : error instanceof Error
32
+ ? error.message
33
+ : String(error);
34
+
35
+ console.error(`vulcan: the post-tool hook failed (${reason}) - the call is unaffected`);
36
+ }
@@ -0,0 +1,52 @@
1
+ /**
2
+ * UserPromptSubmit hook: adds one line to the prompt while the owner's report shape is held - the
3
+ * contract, and the faults of the previous reply when it had any. Nothing is added when the shape is not
4
+ * enforced. It never blocks a prompt: any failure prints a note and the prompt goes through.
5
+ * `VULCAN_GUARDS=off` switches it off, read before anything is imported.
6
+ */
7
+
8
+ // A module, so the awaits below are top-level; it has no static import, by design.
9
+ export {};
10
+
11
+ if (process.env.VULCAN_GUARDS === 'off') {
12
+ process.exit(0);
13
+ }
14
+
15
+ try {
16
+ const { buildPromptContract } = await import('../../src/hooks/owner-reply.ts');
17
+ let session = '';
18
+
19
+ try {
20
+ const event: unknown = JSON.parse(await Bun.stdin.text());
21
+
22
+ if (
23
+ typeof event === 'object' &&
24
+ event !== null &&
25
+ 'session_id' in event &&
26
+ typeof event.session_id === 'string'
27
+ ) {
28
+ session = event.session_id;
29
+ }
30
+ } catch {
31
+ // No readable event: the turn is noted for no session, and nothing is echoed.
32
+ }
33
+
34
+ const line = await buildPromptContract({
35
+ projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
36
+ session,
37
+ });
38
+
39
+ if (line !== '') {
40
+ console.log(line);
41
+ }
42
+ } catch (error) {
43
+ // Input that is not JSON is not echoed: Bun's parse error quotes it, and it can hold the reply.
44
+ const reason =
45
+ error instanceof SyntaxError
46
+ ? 'unreadable input'
47
+ : error instanceof Error
48
+ ? error.message
49
+ : String(error);
50
+
51
+ console.error(`vulcan: the prompt-submit hook failed (${reason}) - the prompt goes through`);
52
+ }
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Stop hook: checks the reply that just ended against the owner's report shape (src/owner/shape.ts) and
3
+ * records its faults by class and date, never the text. Under `enforce: block` a structural fault sends
4
+ * the reply back once to be restated; otherwise it only logs, and the next prompt's contract names it.
5
+ *
6
+ * It fails OPEN: a Stop hook runs after the message is on screen, and one that fails must not hold a
7
+ * session. Input it cannot read, a missing module or an internal error pass with a note on stderr.
8
+ * `VULCAN_GUARDS=off` switches it off, read before anything is imported.
9
+ */
10
+
11
+ // A module, so the awaits below are top-level; it has no static import, by design.
12
+ export {};
13
+
14
+ if (process.env.VULCAN_GUARDS === 'off') {
15
+ process.exit(0);
16
+ }
17
+
18
+ try {
19
+ const { buildStopOutput } = await import('../../src/hooks/owner-reply.ts');
20
+ const output = await buildStopOutput({
21
+ projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
22
+ input: JSON.parse(await Bun.stdin.text()),
23
+ });
24
+
25
+ if (output !== undefined) {
26
+ console.log(JSON.stringify(output));
27
+ }
28
+ } catch (error) {
29
+ // Input that is not JSON is not echoed: Bun's parse error quotes it, and it can hold the reply.
30
+ const reason =
31
+ error instanceof SyntaxError
32
+ ? 'unreadable input'
33
+ : error instanceof Error
34
+ ? error.message
35
+ : String(error);
36
+
37
+ console.error(`vulcan: the stop hook failed (${reason}) - the reply passes`);
38
+ }
@@ -0,0 +1,18 @@
1
+ /**
2
+ * SubagentStart hook: injects the subagent card (src/hooks/subagent-card.ts) into every subagent as added
3
+ * context: the few rules a subagent must keep, each citing its base rule (V-P-12). It imports only the
4
+ * card - no config, no rules reader, no zod - and it never blocks: any failure prints a note and passes.
5
+ */
6
+
7
+ // A module, so the awaits below are top-level; it has no static import, by design.
8
+ export {};
9
+
10
+ try {
11
+ const { buildSubagentStartOutput } = await import('../../src/hooks/subagent-card.ts');
12
+
13
+ console.log(JSON.stringify(buildSubagentStartOutput()));
14
+ } catch (error) {
15
+ console.error(
16
+ `vulcan: the subagent-start hook could not build the card (${error instanceof Error ? error.message : String(error)}) - the subagent starts without it`,
17
+ );
18
+ }
@@ -0,0 +1,63 @@
1
+ # The delegation brief
2
+
3
+ A subagent knows only what the brief says. This is the template, and the rules around it. Rule `V-P-12`
4
+ puts mechanical work (sweeps, greps, renames, gates, counting) with a smaller-model subagent and keeps
5
+ judgment with the main agent, which re-checks what comes back.
6
+
7
+ **Contents**: [The brief](#the-brief) · [What comes back](#what-comes-back) · [Liveness](#liveness) · [Verifier and reviewer briefs](#verifier-and-reviewer-briefs) · [Parallel work](#parallel-work) · [Multi-session work](#multi-session-work)
8
+
9
+ ## The brief
10
+
11
+ A brief is built only from files you read this turn, never from memory. It holds:
12
+
13
+ 1. **The goal**, in one paragraph, and the claim or claims this piece of work serves.
14
+ 2. **Pointers**, not pasted text: the paths of the card, the notes and the files to read.
15
+ 3. **The rules**: the digest reaches the subagent through the tool's subagent-start hook where one
16
+ exists; otherwise name the rule IDs it must keep.
17
+ 4. **Limits**: read-only unless the brief says otherwise; **no git writes**; every file it creates goes
18
+ under `.agents/local/` (V-B-08); no network beyond what the task needs.
19
+ 5. **What to return**: one of four statuses and the evidence (below), in a stated shape, under 400 words.
20
+ 6. **A completion checklist** the subagent ticks, and a size bound, so one silent failure loses little.
21
+
22
+ Do not paste a summary of what you found into a brief: pass the path. A summary is a secondary source,
23
+ and a subagent that trusts it inherits your mistakes.
24
+
25
+ ## What comes back
26
+
27
+ Each report ends with one status:
28
+
29
+ | Status | Means |
30
+ |---|---|
31
+ | done | The work is complete and the evidence is attached |
32
+ | done with concerns | Complete, with doubts named |
33
+ | needs context | Stopped for a fact only the main agent has |
34
+ | blocked | Cannot continue; the reason is named |
35
+
36
+ Treat the report as unverified claims about the files. Check the result on disk, or by running the
37
+ command, before a claim closes on it. A brief that asks for a count asks for the command that produced it.
38
+
39
+ ## Liveness
40
+
41
+ A subagent that goes silent gets one nudge. If it stays silent it is reported as failed, and no claim
42
+ closes on its absence. A fix loop is capped at two rounds; then the owner decides.
43
+
44
+ ## Verifier and reviewer briefs
45
+
46
+ List the steps to take and the evidence to return. Never write the answer you expect to find: a verifier
47
+ told what a pass looks like rationalises toward it. A reviewer's brief also asks for the list of what it
48
+ set aside and did not judge (see `review-a-change`).
49
+
50
+ ## Parallel work
51
+
52
+ Read-only subagents may run in parallel in one checkout. Parallel agents that **write** collide at merge
53
+ time: give each parallel slice its own worktree under `.agents/local/worktrees/`, or run the slices one
54
+ after another. Making a worktree and merging are git writes: they happen on the owner's word (V-W-01),
55
+ and a merge into the integration branch is a class B action (V-W-06). A slice that merges the
56
+ integration tip first leaves the last merge a fast-forward. Subagents get pointers to files, not each
57
+ other's summaries.
58
+
59
+ ## Multi-session work
60
+
61
+ Keep a small ledger next to the card: slice, state, evidence stub. A fresh context resumes from the
62
+ ledger and the card, never from the conversation. Size each unit of work to about one fresh context; a
63
+ unit that does not fit is split before it starts.
@@ -0,0 +1,39 @@
1
+ # The design pass
2
+
3
+ A design pass is a section of the card, not a separate document. It runs for lane L and for any of: a new
4
+ public API, a cross-package change, auth or security, a data model, a new dependency, a new abstraction.
5
+
6
+ **Contents**: [What to write](#what-to-write) · [Design it twice](#design-it-twice) · [What becomes knowledge](#what-becomes-knowledge)
7
+
8
+ ## What to write
9
+
10
+ Write a decision only where two implementers could choose differently and both choices would compile. For
11
+ each decision:
12
+
13
+ - the choice, in one sentence;
14
+ - the alternative rejected, and why;
15
+ - for a new dependency or a new abstraction: "simpler alternative rejected because ...".
16
+
17
+ List what is deferred, each with its reason. A deferred item without a reason is an open question: move it
18
+ to Open.
19
+
20
+ ## Design it twice
21
+
22
+ For a new interface, ask three or more read-only subagents for radically different designs, each briefed
23
+ with the goal, the seams and the constraints, and nothing about the others. Compare them on three things:
24
+
25
+ - **Depth**: the fewest methods and parameters that cover the behaviour, with the complexity behind them.
26
+ - **Locality**: a change in one place stays in one place.
27
+ - **Seam placement**: where a test can observe the behaviour.
28
+
29
+ Keep the deeper design. Record the rejected ones in Decisions.
30
+
31
+ Test a module by deleting it in your head: if the complexity reappears across its callers, the module
32
+ earned its place; if it vanishes, it was a pass-through. One adapter means a hypothetical seam; two
33
+ adapters mean a real one.
34
+
35
+ ## What becomes knowledge
36
+
37
+ A decision is promoted to a concept in the knowledge bundle only when all three hold: it is hard to
38
+ reverse, it would surprise a reader without context, and it is a real trade-off. If one is missing, it
39
+ stays in the card.
@@ -0,0 +1,36 @@
1
+ # Evidence by claim type
2
+
3
+ A claim is shown by a probe run in this session, of the kind that suits what the claim is about. "Should
4
+ work" is never evidence. An unavailable verifier is reported as deferred-verify, never as works, live,
5
+ verified or shipped.
6
+
7
+ | The claim is about | The evidence |
8
+ |---|---|
9
+ | A file | Read it |
10
+ | Code | Grep, or atlas `symbol` |
11
+ | A command | Its output, checked, from this session |
12
+ | An HTTP route | `curl -i` against the running route |
13
+ | A publish, a release or a deploy | A probe of public state: `npm view`, `gh`, `git ls-remote`, the tarball answering 200 |
14
+ | A UI | A real browser; how it looks is shown in pixels, at mobile width and at desktop width |
15
+ | A configuration | A read-back of the file or setting |
16
+ | Behavioural quality (a skill, a rule) | An eval: cases passed over cases run, with a baseline arm beside it |
17
+
18
+ Words that describe a local state - staged, local, candidate - need no public-state probe. Words that
19
+ describe a public state - published, released, live, deployed - always do.
20
+
21
+ The probe kinds a card names on a claim's line, and what each means:
22
+
23
+ | Probe | Means |
24
+ |---|---|
25
+ | `test` | A test file, or a `-t` pattern, run at the agreed seam |
26
+ | `property` | A property test for a pure function |
27
+ | `cli` | A command, with its exit code and output |
28
+ | `http` | `curl -i` |
29
+ | `browser` | A real browser view, at mobile and desktop width |
30
+ | `eval` | A skill or rule eval |
31
+ | `gate` | `vulcan doctor`, lint, `okf check` or the project's own gate |
32
+ | `read` | A read-back of a file or a configuration |
33
+ | `manual` | Attested by the owner, dated; never enough alone for secrets, auth, money, publishing or deletion |
34
+
35
+ A probe's strictness scales with the blast radius: secrets, auth, money, a public push or production
36
+ need a deterministic probe, never `manual`.
@@ -0,0 +1,20 @@
1
+ # Phase boundaries
2
+
3
+ At the end of a unit of work, and whenever the context is long, pick the next move by asking these
4
+ questions in order. The first yes wins, because every move except continuing turns a primary source into a
5
+ secondary one.
6
+
7
+ | # | Question | If yes |
8
+ |---|---|---|
9
+ | 1 | Does the next work need what is in this conversation, and is the context still sharp? | **Continue** |
10
+ | 2 | Is the unit done, with nothing the next one needs from this conversation? | **Clear** the context and start from the card |
11
+ | 3 | Does the next unit need a fresh window but not this conversation? | **Hand off**: write a pointer file (see the `report-back` skill) and start there |
12
+ | 4 | Is the next piece isolated, with a clear input and a clear output? | **Subagent**, with a brief (`node_modules/@venizia/vulcan/base/references/delegation-brief.md`) |
13
+ | 5 | None of the above, and the context must shrink? | **Compact**, last, because it keeps a summary of a summary |
14
+
15
+ Sizing: a unit of work fits one fresh context, roughly the part of a window a model uses well, not the
16
+ whole of it. Prefer closing a coherent unit and re-entering from the card over pushing one long session
17
+ through compaction. The artifact (the card, the ledger, the commits) carries the state; the conversation
18
+ does not.
19
+
20
+ Save before you move: the card and the ledger say what is done, what is open, and what is not verified.