@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -3,16 +3,25 @@
3
3
  * created outside the project (V-B-08). Stores a package manager, runtime or the agent tool manage
4
4
  * themselves are allowed - a default list, extended by `guard.toolOwnedPaths` in the project config.
5
5
  * `TMPDIR` or `mktemp` pointed at the system temp directory is not allowed.
6
- * It asks by default; `guard.outside: 'deny'` in the project config refuses instead, for agents where an ask can be
7
- * approved unseen. A write into the agent tool scratchpad is always denied.
6
+ * A write outside the project asks by default; `guard.outside: 'deny'` in the project config refuses instead, for agents
7
+ * where an ask can be approved unseen. A write into the agent tool scratchpad is always denied. A part of the call it
8
+ * cannot read (a program or a target named by a variable it cannot resolve, a line it cannot follow to its end) is always
9
+ * DENIED, never asked: the agent can write the call again with a literal path, so a person is not stopped for it, and the
10
+ * reason says how. Literal assignments of the same line (`S=dir; ... > $S/a`, `export X=dir`, `for i in 1 2`) are
11
+ * resolved first, so the usual safe forms are read.
8
12
  *
9
- * It guards against drift, not against an attacker, and a guard that blocks every call when its install
10
- * is broken costs more than it protects. So input it cannot read passes, and so does a missing package or
11
- * `bun` (the settings wrapper says so on stderr). A guard that started and then failed - a crash or a
12
- * timeout, here an internal error or an unloadable module - ASKS instead of passing the call unchecked; a
13
- * project config that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
14
- * read before anything is imported. It imports only the modules it needs - the config loader (and zod) is
15
- * loaded on its own, last, and may fail alone.
13
+ * A write to a file the guards read their policy from (the manifest, the config, `.claude/settings*.json` and the installed
14
+ * package) is always DENIED: an agent that can write one can switch a guard off, and the owner changes them by hand or through
15
+ * `vulcan sync`. A missing package, `bun` or hook file is the settings wrapper's to answer: it blocks, bar `bun install` and
16
+ * `vulcan sync`.
17
+ *
18
+ * It guards against drift, not against an attacker. A hook input it cannot read ASKS, because nothing was checked and the agent
19
+ * cannot repair that. A guard that started and then failed - a crash or a timeout, here an internal error or an unloadable
20
+ * module - ASKS instead of passing the call unchecked. Where the project (`guard.asks: 'deny'`) or the launch environment
21
+ * (`VULCAN_GUARD_ASKS=deny`) holds every ask, each is a deny; a manifest that exists and cannot be read holds them too. `VULCAN_GUARDS=off` switches it off,
22
+ * read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
23
+ * from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
24
+ * VULCAN cannot parse, then changes nothing here.
16
25
  */
17
26
 
18
27
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -28,65 +37,143 @@ try {
28
37
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
29
38
  const { HookDecision } = await import('../../src/hooks/decision.ts');
30
39
  const { OutsideGuard } = await import('../../src/hooks/guard-outside.ts');
31
- const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
32
- const input = ManifestGuard.parseHookInput({ text });
33
-
34
- if (input) {
35
- const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
36
- let toolOwnedPaths: string[] = [];
37
- let outside: string = GuardDecisions.ASK;
38
-
39
- try {
40
- const { ConfigLoader } = await import('../../src/config/index.ts');
41
- const loaded = await ConfigLoader.load({ root: projectRoot });
42
-
43
- toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
44
- outside = loaded.ok ? loaded.config.guard.outside : GuardDecisions.ASK;
45
- } catch (error) {
46
- console.error(
47
- `vulcan: the guard-outside hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - the default allowlist applies`,
48
- );
49
- }
40
+ const { HookInput } = await import('../../src/hooks/hook-input.ts');
41
+ const { ProjectTmp } = await import('../../src/hooks/project-tmp.ts');
42
+ const { relative } = await import('node:path');
43
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
44
+ const input = HookInput.parse({ text });
45
+ const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
46
+ const { toolOwnedPaths, outside, asks, asksNote } = ProjectGuards.readPolicy({
47
+ root: projectRoot,
48
+ });
49
+ const isHeld = asks === GuardDecisions.DENY;
50
50
 
51
+ if (!input) {
52
+ console.log(
53
+ JSON.stringify(
54
+ HookDecision.buildTool({
55
+ asks,
56
+ asksNote,
57
+ decision: GuardDecisions.ASK,
58
+ reason: [
59
+ 'The hook input could not be read, so this call was not checked for files outside the project (V-B-08).',
60
+ 'Confirm only if the call stays inside the project.',
61
+ ],
62
+ }),
63
+ ),
64
+ );
65
+ } else {
51
66
  const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
52
67
 
53
68
  if (hits.length > 0) {
54
- const isScratchpad = hits.some((hit) => hit.isAgentToolScratchpad);
55
- const hitLines = hits.map((hit) => ` - ${hit.message} (${hit.path})`);
56
- const places =
57
- 'Scratch files go under .agents/local/tmp/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder.';
69
+ const read = hits.filter((hit) => !hit.isUnread);
70
+ const isScratchpad = read.some((hit) => hit.isAgentToolScratchpad);
71
+ const linesOf = (list: typeof hits) => list.map((hit) => ` - ${hit.message} (${hit.path})`);
72
+ const tmpFolder = relative(projectRoot, ProjectTmp.projectOf({ root: projectRoot }));
73
+ const places = `Scratch files go under ${tmpFolder}/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder.`;
74
+ const owned =
75
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.';
58
76
 
59
- const isDeny = isScratchpad || outside === GuardDecisions.DENY;
77
+ // A line the check could not read is denied, whatever the project sets: the agent can write it again so that it is read.
78
+ const unreadHits = hits.filter((hit) => hit.isUnread);
79
+ const unread =
80
+ unreadHits.length === 0
81
+ ? []
82
+ : [
83
+ ...(read.length > 0 ? [''] : []),
84
+ 'Part of this call could not be read, so it was not checked for files outside the project (V-B-08):',
85
+ ...linesOf(unreadHits),
86
+ ];
87
+ // A link to a path outside the project is a way to write there with a name inside it: denied, as the agent can copy or link inside.
88
+ const linkHits = read.filter((hit) => hit.isLink === true);
89
+ // A file the guards read their policy from: denied, so no agent loosens a guard by editing it.
90
+ const protectedHits = read.filter((hit) => hit.isProtected === true);
91
+ const isDeny =
92
+ isScratchpad ||
93
+ protectedHits.length > 0 ||
94
+ linkHits.length > 0 ||
95
+ unreadHits.length > 0 ||
96
+ ((outside === GuardDecisions.DENY || isHeld) && read.length > 0);
60
97
  let reason: string[];
61
98
 
62
- if (isScratchpad) {
99
+ if (unreadHits.length > 0 && !isScratchpad) {
100
+ reason = [
101
+ 'Part of this call could not be read, so it cannot be checked for files outside the project (V-B-08):',
102
+ ...linesOf(unreadHits),
103
+ ...(read.length > 0
104
+ ? [
105
+ '',
106
+ 'The part that was read would also create files outside the project:',
107
+ ...linesOf(read),
108
+ ]
109
+ : []),
110
+ '',
111
+ `Nothing was run. Write it again so the guard can read it: a literal path in every redirect (no $VAR or $(...) in a target; after a cd the guard cannot work out, an absolute path), a cd to a literal folder, the folder assigned on the same line (S=${tmpFolder}/x; ... > "$S/a") or named by a for loop over literal words; or put the script in a file under ${tmpFolder}/<task>/ and run it by that literal path (bun ${tmpFolder}/<task>/step.ts), with literal paths inside the project in its own redirects too: the guard does not read the script. ${places}`,
112
+ owned,
113
+ ];
114
+ } else if (isScratchpad) {
63
115
  reason = [
64
116
  'This would write into the scratchpad folder the agent tool offers (V-B-08):',
65
- ...hitLines,
117
+ ...linesOf(read),
118
+ ...unread,
66
119
  '',
67
120
  `That folder is under /tmp, and V-B-08 overrides the tool line that says to use it. Nothing was written. ${places} Read a fetched file through a pipe (for example gh api ... | grep) rather than saving it.`,
68
121
  ];
122
+ } else if (protectedHits.length > 0) {
123
+ reason = [
124
+ 'This would change a file the guards read their policy from (V-B-08):',
125
+ ...linesOf(protectedHits),
126
+ ...(read.length > protectedHits.length
127
+ ? [
128
+ '',
129
+ 'It would also create files outside the project:',
130
+ ...linesOf(read.filter((hit) => hit.isProtected !== true)),
131
+ ]
132
+ : []),
133
+ ...unread,
134
+ '',
135
+ 'Nothing was run. These files are changed by the owner, by hand or through bun node_modules/.bin/vulcan sync; an agent that could edit them could switch a guard off.',
136
+ ];
137
+ } else if (linkHits.length > 0) {
138
+ reason = [
139
+ 'This would hard-link a path outside the project (V-B-08); a hard link cannot be told from the file, so a write through it changes that path later too:',
140
+ ...linesOf(linkHits),
141
+ ...(read.length > linkHits.length
142
+ ? [
143
+ '',
144
+ 'It would also create files outside the project:',
145
+ ...linesOf(read.filter((hit) => hit.isLink !== true)),
146
+ ]
147
+ : []),
148
+ '',
149
+ `Nothing was run. Copy the file into the project (cp) instead of linking it, link a path inside the project, or make a symbolic link (ln -s), which is read once it exists. ${places}`,
150
+ owned,
151
+ ];
69
152
  } else if (isDeny) {
70
153
  reason = [
71
- 'This would create files outside the project (V-B-08), and this project denies it (guard.outside):',
72
- ...hitLines,
154
+ `This would create files outside the project (V-B-08), and this project denies it (${isHeld ? 'guard.asks' : 'guard.outside'}):`,
155
+ ...linesOf(read),
156
+ ...unread,
73
157
  '',
74
158
  `Nothing was written. ${places}`,
75
- 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
159
+ ...(isHeld && asksNote !== undefined ? ['', asksNote] : []),
160
+ owned,
76
161
  ];
77
162
  } else {
78
163
  reason = [
79
164
  'This would create files outside the project (V-B-08):',
80
- ...hitLines,
165
+ ...linesOf(read),
166
+ ...unread,
81
167
  '',
82
168
  `${places} Use that place, or confirm only if the owner asked for this exact path.`,
83
- 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
169
+ owned,
84
170
  ];
85
171
  }
86
172
 
87
173
  console.log(
88
174
  JSON.stringify(
89
175
  HookDecision.buildTool({
176
+ asks,
90
177
  decision: isDeny ? GuardDecisions.DENY : GuardDecisions.ASK,
91
178
  reason,
92
179
  }),
@@ -99,17 +186,50 @@ try {
99
186
 
100
187
  console.error(`vulcan: the guard-outside hook failed (${message}); run bun install`);
101
188
 
102
- // The imports may be what failed, so the answer is written by hand: no module is needed to ask.
189
+ // The imports may be what failed, so the answer is written by hand, and a project that sets guard.asks to deny is read from the manifest by hand too.
190
+ let isHeldOnCrash = false;
191
+
192
+ try {
193
+ const { existsSync, readFileSync } = await import('node:fs');
194
+ const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
195
+ const file = `${root}/.agents/vulcan.manifest.json`;
196
+
197
+ isHeldOnCrash = process.env.VULCAN_GUARD_ASKS === 'deny';
198
+
199
+ if (!isHeldOnCrash && existsSync(file)) {
200
+ try {
201
+ const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
202
+ const guard =
203
+ typeof manifest === 'object' && manifest !== null && 'guard' in manifest
204
+ ? manifest.guard
205
+ : undefined;
206
+
207
+ isHeldOnCrash =
208
+ typeof manifest !== 'object' ||
209
+ manifest === null ||
210
+ Array.isArray(manifest) ||
211
+ (typeof guard === 'object' && guard !== null && 'asks' in guard && guard.asks === 'deny');
212
+ } catch {
213
+ // A manifest that exists and cannot be read holds every ask.
214
+ isHeldOnCrash = true;
215
+ }
216
+ }
217
+ } catch {
218
+ isHeldOnCrash = false;
219
+ }
220
+
103
221
  console.log(
104
222
  JSON.stringify({
105
223
  hookSpecificOutput: {
106
224
  hookEventName: 'PreToolUse',
107
- permissionDecision: 'ask',
225
+ permissionDecision: isHeldOnCrash ? 'deny' : 'ask',
108
226
  permissionDecisionReason: [
109
227
  'The guard-outside hook failed, so this call was not checked for files outside the project (V-B-08):',
110
228
  ` - ${message}`,
111
229
  '',
112
- 'Confirm only if the call stays inside the project; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
230
+ isHeldOnCrash
231
+ ? 'This project denies every call that would need a human to confirm it (guard.asks: deny). Nothing was run: run bun install to repair the install.'
232
+ : 'Confirm only if the call stays inside the project; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
113
233
  ].join('\n'),
114
234
  },
115
235
  }),
@@ -1,12 +1,9 @@
1
1
  /**
2
- * PreToolUse hook on Bash: catches the writes V-W-02 and V-W-03 reserve for a human, reading the
3
- * command and any local script it runs. It asks rather than denies (src/hooks/common/constants.ts).
2
+ * PreToolUse hook on Bash: catches the writes V-W-02 and V-W-03 reserve for a human, matching each command
3
+ * the shell parser finds against the command table (src/hooks/write-commands.ts). It asks rather than denies
4
+ * (src/hooks/common/constants.ts).
4
5
  * The project's own deploy and migrate commands (`guard.writes.commands`) are read from the manifest and
5
6
  * checked beside the fixed list, inside compound commands too.
6
- * A script the project lists in `guard.writes.trustedScripts` is not read for writes while git says it
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.
10
7
  *
11
8
  * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so a hook that throws - a
12
9
  * partial install, say, where its own modules are missing - would let every command through. The
@@ -22,41 +19,23 @@ try {
22
19
  const stdin = await Bun.stdin.text();
23
20
  const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
24
21
  const cwd = hookCommand?.cwd ?? process.cwd();
25
- let scripts: string[] = [];
26
-
27
- // Only a command that names a .ts file can use the list; the config loader (and zod) loads last, on its
28
- // own, and may fail alone.
29
- if (hookCommand && /\.ts\b/.test(hookCommand.command)) {
30
- try {
31
- const { ConfigLoader } = await import('../../src/config/index.ts');
32
- const loaded = await ConfigLoader.load({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
33
-
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
- : [];
40
- } catch (error) {
41
- console.error(
42
- `vulcan: the guard-writes hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - every script is read`,
43
- );
44
- }
45
- }
46
-
47
22
  const root = process.env.CLAUDE_PROJECT_DIR ?? cwd;
48
23
  const policy = ProjectGuards.readPolicy({ root });
49
24
  const hits = hookCommand
50
- ? WriteGuard.inspectCommand({
51
- command: hookCommand.command,
52
- cwd,
53
- trust: { root, scripts, readOnlyScripts: policy.readOnlyScripts },
54
- extra: policy.commands,
55
- })
56
- : [];
25
+ ? WriteGuard.inspectCommand({ command: hookCommand.command, extra: policy.commands })
26
+ : [
27
+ {
28
+ rule: 'V-W-02',
29
+ message: 'the hook input could not be read, so the command was not checked',
30
+ },
31
+ ];
57
32
 
58
33
  if (hits.length > 0) {
59
- console.log(JSON.stringify(WriteGuard.buildDecision({ hits })));
34
+ console.log(
35
+ JSON.stringify(
36
+ WriteGuard.buildDecision({ hits, asks: policy.asks, asksNote: policy.asksNote }),
37
+ ),
38
+ );
60
39
  }
61
40
  } catch (error) {
62
41
  console.error(
@@ -1,5 +1,5 @@
1
1
  /**
2
- * SessionStart hook: prints the rules that cost the most when skipped (src/hooks/session-digest.ts).
2
+ * SessionStart hook: prints what only this session knows - a config problem, a launch warning, the owner card (src/hooks/session-digest.ts). The rules are the block of AGENTS.md.
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
  */
@@ -2,12 +2,14 @@
2
2
  # -include node_modules/@venizia/vulcan/base/make/vulcan.mk
3
3
  # A project adds its own targets after the include; redefining one of these fails `vulcan doctor`.
4
4
 
5
- VULCAN ?= bun x --no-install vulcan
5
+ # The linked bin by path, not `bun run vulcan`: `bun run` falls back to a program on $PATH, or to one bun cached, when the bin is not linked
6
+ # here, and the include above needs this same node_modules. A missing bin fails the target instead of running another program.
7
+ VULCAN ?= bun $(CURDIR)/node_modules/.bin/vulcan
6
8
  VULCAN_BASE ?= node_modules/@venizia/vulcan/base
7
9
  # The GitHub repository the wiki links point into, owner/name; the link gate checks only links into it.
8
10
  WIKI_REPO ?=
9
11
 
10
- .PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage okf-viz \
12
+ .PHONY: vulcan-sync vulcan-doctor runners-check okf-check okf-check-strict okf-gen okf-coverage \
11
13
  surface-gen surface-check atlas-symbols atlas-releases wiki-links-check wiki-anchors-check
12
14
 
13
15
  vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
@@ -16,6 +18,10 @@ vulcan-sync: ## Write the agent adapters, settings, skill links and manifest fro
16
18
  vulcan-doctor: ## Check the project against the VULCAN contract
17
19
  @$(VULCAN) doctor
18
20
 
21
+ # V-S-08: no tracked file runs a package by name (bunx, bun x, npx, pnpm dlx). Allow a name with guard.runners.allow.
22
+ runners-check: ## Fail when a tracked file runs an unscoped package by name (bunx, bun x, npx, pnpm dlx)
23
+ @$(VULCAN) runners check
24
+
19
25
  # OKF v0.2 conformance only; okf-check-strict adds the house rules (links, style, coverage, freshness).
20
26
  okf-check: ## Check the knowledge bundle against OKF v0.2
21
27
  @$(VULCAN) x okf check
@@ -29,9 +35,6 @@ okf-gen: ## Regenerate the generated pages and regions of the knowledge bundle
29
35
  okf-coverage: ## Report how much of the code the knowledge bundle covers
30
36
  @$(VULCAN) x okf coverage
31
37
 
32
- okf-viz: ## Build the knowledge graph view
33
- @$(VULCAN) x okf viz
34
-
35
38
  # The public surface: an optional API gate a project commits and checks. It reads the built .d.ts -
36
39
  # build first.
37
40
  surface-gen: ## Write the public API surface from the built .d.ts
@@ -0,0 +1,16 @@
1
+ # Rules - the Venizia pack
2
+
3
+ <!-- Shipped by @venizia/vulcan, never edited in a project. These rules bind the Venizia stack (Bun, devz, the vite
4
+ builders, the house lint rules), so they are not in the base rules: a project turns the pack on with
5
+ `packs: ['venizia']` in `.configs/vulcan.config.*`, and `vulcan sync` names it in the rules block of AGENTS.md.
6
+ The IDs are the ones they had in the base rules and keep their `V-` namespace. -->
7
+
8
+ Cite by ID. Every rule has "Enforced by".
9
+
10
+ | ID | Rule | Enforced by |
11
+ |----|------|-------------|
12
+ | V-B-05 | **One script set for every app**, backend and frontend: `server:dev` (`NODE_ENV=development bun run src/index.ts` for a backend, `vite --config .configs/builders/vite.config.mts` for a frontend), `compile` (`bun .configs/builders/compile.ts` for a backend, `vite build --config .configs/builders/vite.config.mts` for a frontend), `typecheck` (`bun check`), `lint` (`devz lint`), `lint:fix` (`devz lint --fix`), `test` (`bun test`), `clean` (`devz clean`). The logic lives in `.configs/builders/` or in `devz`, never in the `package.json` string. No `dev`, `start`, `build`, `rebuild`, `preview` or `server:prod`; a domain extra such as `migrate:dev` is fine. **An app root holds only `.configs/`, `src/`, `package.json`, `tsconfig.json` and `.env.example`**; every other config lives in `.configs/{lints,formatters,builders}/`. A library package keeps Makefile targets: `build`, `typecheck`, `lint`, `lint-fix`, `test`, `clean`. | SOFT |
13
+ | V-B-09 | **Agent scripting uses bun by default.** A script you write to do a task is `bun -e '…'` or `bun file.ts`, with `Bun.file()` for files. Python or another language is allowed when the task needs it - an existing project script, a tool only that language has - and you say so in one line. | SOFT |
14
+ | V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`; `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
15
+ | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. When something validates against such a class, it carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first); a class nothing validates against needs neither. The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed. | SOFT - lint (`const-class-values`) in a project that enables `houseConfigs` of `@venizia/dev-configs` |
16
+ | V-C-20 | **Declare the instance, then await on its own line.** Never `await new X({...}).method({...})`: write `const runner = new X({...});` and then `await runner.run({...});`. A constructor inside an awaited call chain hides the object that does the work - a reader cannot name it, a second call cannot reuse it, and a failure in the constructor reads like a failure in the method. A longer chain (`await new X().a().b()`) is the same defect. It covers tests and scripts. `await new Promise(...)` is not this form: the constructor call is the awaited value itself and the promise needs no name. | SOFT - lint (`venizia/no-await-new-chain`, `@venizia/dev-configs` from 0.4.8-3) in a project that enables `houseConfigs` |
@@ -69,13 +69,11 @@ unit that does not fit is split before it starts.
69
69
 
70
70
  A subagent started through the tool's own subagent mechanism is already exempt from the owner's report
71
71
  shape: it gets the subagent card, not the owner shape or the profile. A session you start another way (a
72
- new terminal, `claude -p`, a script, a session another agent works in) is not: its hooks hold its replies to
73
- the owner's shape, log them as faults and, under `enforce: block`, send them back, although its reader is
74
- you.
72
+ new terminal, `claude -p`, a script, a session another agent works in) is not: its session digest carries the
73
+ owner's shape card and the profile card, although its reader is you.
75
74
 
76
75
  Start it with `VULCAN_OWNER_REPLY=off` on the command that starts it (`VULCAN_OWNER_REPLY=off claude -p ...`), never with `export`, which reaches every later session started from that shell. Only the exact value `off` counts. The
77
- session then gets no owner shape card and no profile card, and its replies are not checked, logged or
78
- blocked; everything else (the guards, the rules, the signals) stays on. A session started for one piece of
76
+ session then gets no owner shape card and no profile card; everything else (the guards, the rules) stays on. A session started for one piece of
79
77
  work is handed the item and the format ("take item X, return as Y"), not a long message. Say in the brief which plain
80
78
  format you want back (the four statuses and the evidence table above are the default), in the language
81
79
  you work in. Never set it in a shell the owner works in, or in the `env` of a settings file: `vulcan doctor` prints a
@@ -3,7 +3,7 @@
3
3
  How a claim is turned into a test, and how the test is kept honest. It is loaded by `plan-a-change`,
4
4
  `build-a-feature` (steps 3 and 5), `fix-a-bug` and `review-a-change`.
5
5
 
6
- **Contents**: [Where a test lives](#where-a-test-lives) · [The loop](#the-loop) · [Anti-patterns](#anti-patterns) · [Mocking](#mocking) · [Fixtures and environment](#fixtures-and-environment) · [Blast radius](#blast-radius) · [Async UI and shipped UI](#async-ui-and-shipped-ui) · [When a verifier cannot run](#when-a-verifier-cannot-run) · [Regression tests](#regression-tests) · [Evals for skills and rules](#evals-for-skills-and-rules)
6
+ **Contents**: [Where a test lives](#where-a-test-lives) · [The loop](#the-loop) · [Anti-patterns](#anti-patterns) · [Mocking](#mocking) · [Fixtures and environment](#fixtures-and-environment) · [Blast radius](#blast-radius) · [Async UI and shipped UI](#async-ui-and-shipped-ui) · [When a verifier cannot run](#when-a-verifier-cannot-run) · [Regression tests](#regression-tests)
7
7
 
8
8
  ## Where a test lives
9
9
 
@@ -79,11 +79,3 @@ deferred-verify. It is never described as works, live, verified or shipped.
79
79
 
80
80
  A regression test goes in before the fix, at a seam that reproduces the real bug pattern. If no such seam
81
81
  exists, that is itself a finding: report it, and do not write a test that cannot fail.
82
-
83
- ## Evals for skills and rules
84
-
85
- A suite has should-do cases and should-not cases: an eval that only checks the wanted behaviour optimises
86
- for it blindly. The grader is a different model level from the one under test, gives its reasons before
87
- its verdict, and answers UNKNOWN when it cannot tell (counted as a miss). Always include a baseline arm
88
- (the same case with no skill) so the skill's effect is visible. Read the transcripts before trusting a
89
- score. Changing a rule or a skill is a reason to run its eval again.