@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
package/README.md CHANGED
@@ -4,11 +4,13 @@ One setup, one workflow and one coding style for every VENIZIA project. Bun-only
4
4
 
5
5
  ```bash
6
6
  bun add -d --exact @venizia/vulcan @venizia/dev-configs
7
- bun x --no-install vulcan init
8
- bun x --no-install vulcan sync
9
- bun x --no-install vulcan doctor
7
+ bun node_modules/.bin/vulcan init
8
+ bun node_modules/.bin/vulcan sync
9
+ bun node_modules/.bin/vulcan doctor
10
10
  ```
11
11
 
12
+ `doctor` fails with `[scaffold]` until you describe the project in `.agents/knowledge/index.md` and delete the `vulcan:scaffold` line; it is the first item `init` lists under `left to do`.
13
+
12
14
  `--no-install` matters: the unscoped npm name `vulcan` belongs to an unrelated package, and without the
13
15
  flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
14
16
 
@@ -16,16 +18,28 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
16
18
 
17
19
  | Command | What it does |
18
20
  |---|---|
19
- | `init` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
20
- | `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>]` | Create a new monorepo with its first app from a framework preset: the root manifests, the app's files, the VULCAN layer and a knowledge bundle, then install, `git init` (a missing git is reported, not fatal), `sync` and the checks, and ends with `cd <project> && make dev` and the app's URL. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
21
- | `add --preset <name\|file:path> --app <name> [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app from a preset to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. A frontend says which backend app to proxy `/api` to |
22
- | `sync [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; an existing file is left alone), `.claude/settings.json` (shipped + slot + project hooks + `claude.settings` over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed, and a hook it wrote is taken back by its command even after you edited its entry), `.claude/skills/` links, and the committed `.agents/vulcan.manifest.json`. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
23
- | `doctor` | Check the project follows VULCAN; exit 1 on any violation |
21
+ | `init [--key <KEY>]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the two lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, `.dockerignore`, `bunfig.toml`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. `--key` is the project's flow key (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name); it counts only while no config exists yet. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
22
+ | `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>] [--scope <@scope>] [--key <KEY>]` | Create a new monorepo with its first app from a framework preset: the root manifests (with `.dockerignore` and `bunfig.toml`), the app's files, the VULCAN layer and a knowledge bundle, then install, `git init` (a missing git is reported, not fatal), `sync` and the checks, and ends with `cd <project> && make dev` and the app's URL. `--scope` names the app's package `@scope/<name>`; `--key` is the flow key, as for `init`. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
23
+ | `add --preset <name\|file:path> (--app <name> \| --lib <name> \| --shared <name>) [--dir <folder>] [--scope <@scope>] [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app, a library other apps import (`--lib`) or a side-neutral shared package (`--shared`) to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. `--dir` is for a library or a shared package; `--scope` names the package `@scope/<name>`. A frontend says which backend app to proxy `/api` to |
24
+ | `sync [--agents <list>\|list] [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; an existing file is left alone), `.claude/settings.json` (shipped + slot + `claude.settings`, project hooks included, over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed, and a hook it wrote is taken back by its command even after you edited its entry), `.claude/skills/` links, and the committed `.agents/vulcan.manifest.json`. It also writes the adapters of the other agents you chose (`--agents claude,omp` or `none`, kept in `.agents/vulcan.local.json`; `--agents list` prints the table), the Atlas block in `AGENTS.md`, and the clone's `commit-msg` hook when a commit check is on. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
25
+ | `preset diff <package> [--preset <name\|file:path>] [--api <app> \| --no-api] [--full] [--check]` | Read-only: set each file the preset makes now against the file the package has (same, differs, missing); `--preset` names the preset when it cannot be found from the package, `--api` or `--no-api` says what a frontend proxies to, `--full` prints the diffs, `--check` exits 1 on a difference |
26
+ | `agents [list\|add\|remove\|setup]` | See, add, remove or re-choose the coding agents you use on this machine |
27
+ | `doctor` | Check the project follows VULCAN; exit 1 on any violation. The checks are listed in `docs/wiki/content/references/commands/doctor.md` |
28
+ | `commit-check <message-file> \| --range <revs> \| --text <message>` | Check a commit message against the `commit.message` checks of the config; `sync` installs it as the `commit-msg` hook; exit 1 on a problem, 2 on bad input |
29
+ | `board [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]` | Fold the event log (and GitHub pull requests, checks and reviews when `gh` can read them) into flows and write one HTML file, by default `.agents/local/reports/board.html`; read-only. `--repo` is repeatable; `--no-github` leaves GitHub out |
30
+ | `board serve [--port <n>] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]` | Serve the same page on 127.0.0.1 (default port 4317) and push new events to the open page with no reload, until Ctrl+C |
31
+ | `event add \| tail` | Write a line to the agent event log (`.agents/local/events/<day>.jsonl`) or read it |
32
+ | `visualize <spec.json> [--out <name>] \| --schema` | Make one small static HTML page from a JSON spec, in `.agents/local/prototypes/` (`--out` names the page); `--schema` prints the spec's schema |
33
+ | `profile [show\|edit\|reset]` | Tell VULCAN how you like to work (reply language, tone, habits) in `.agents/local/profile.json` |
34
+ | `clean [--tmp\|--worktrees\|--clones\|--cache\|--all] [--include-fresh] [--yes]` | List what an agent left under `.agents/local/` (a dry run) and, with `--yes`, remove it |
24
35
  | `upgrade [--stable \| --nightly] [<version\|tag>]` | Install the target `@venizia/vulcan`, then run `sync` from the newly installed CLI. `--stable` (default) is the `latest` dist-tag, never a prerelease; `--nightly` is the higher of `latest` and `next`; a named version or tag wins over both. `--nightly` that cannot read the dist-tags exits 1; a stable upgrade from an installed prerelease says that `--nightly` keeps the prerelease line |
36
+ | `changelog check` | Check the changelog entries' `migration` blocks: a Breaking Change entry dated on or after `knowledge.migrationFrom` must carry one, and every block must be valid |
37
+ | `migrate plan --to <version>` | What an app must change to move a package between two releases, newer or older: the steps in order, where its code touches them, codemods and data warnings; read only |
38
+ | `migrate apply --to <version>` | Run the codemods the plan links (`--reverse` for a rollback) and print the steps that stay manual; refuses an app with uncommitted changes unless `--force` |
25
39
  | `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas`. `x --help` prints the help; `x <tool> --help` goes to the tool |
26
- | `help`, `version` | |
40
+ | `help`, `version` | `help` prints the usage; `version` prints the installed version |
27
41
 
28
- Diagnostics go to stderr; `vulcan` writes nothing to stdout of its own, so `vulcan x atlas mcp` is a
42
+ Diagnostics go to stderr; a command that produces a result prints only that on stdout, and `vulcan x atlas mcp` is a
29
43
  clean MCP stdio server.
30
44
 
31
45
  ## The project config
@@ -39,36 +53,29 @@ export default {
39
53
  agents: ['claude'],
40
54
  rules: { 'V-W-01': 'on-user-word' }, // slot choice: 'on-user-word' | 'read-only'
41
55
  knowledge: { bundle: '.agents/knowledge' },
42
- hooks: [{ event: 'Stop', command: 'echo done' }],
43
56
  claude: { settings: { permissions: { allow: ['Bash(make test)'] } } }, // team-shared, committed
44
57
  digest: { oftenDropped: ['V-B-03', 'W-00'] }, // repeated at every session start; base or own IDs
45
58
  layout: { backend: 'services', frontend: 'web', shared: 'libs' }, // written by init --preset and add
46
59
  } satisfies VulcanConfig;
47
60
  ```
48
61
 
49
- An unknown key is an error; every error names the file and the field.
62
+ An unknown key is an error; every error names the file and the field. The example shows a few keys; each key, with its type and default, is in `docs/wiki/content/references/configuration/index.md`. Three that a new project often wants: `local.tmp` (a short folder for the temporary files of a session, so a browser socket path fits), `theme` (the colours, fonts and radius of the board and the pages VULCAN makes) and `board` (the owner, title, logo and agents of `vulcan board`).
50
63
 
51
64
  ## What ships (`base/`)
52
65
 
53
- - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (51 rules).
66
+ - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-* (36 rules).
54
67
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
- - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update`, `build-a-feature` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
- - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) `guard-package.ts` (denies a hand-written new `package.json` in a layout folder when a recorded preset has a `vulcan add` command for it, else only warns) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
68
+ - `skills/` - 11 project-neutral skills, described in `docs/wiki/content/references/skills.md` (a project-specific skill stays in its project).
69
+ - `hooks/` - 16 hook files, described in `docs/wiki/content/references/hooks/index.md`.
57
70
  - `claude/settings.json`, `make/vulcan.mk`, `templates/`.
71
+ - `agents.json` (the coding agents `sync` can write adapters for), `commit-agents.json` (the agent names, addresses and phrases `commit-check` looks for in a message), `checks/` (the wiki link and anchor gates), `extensions/` (the guards for an agent that loads an extension, such as omp or pi) and `references/` (testing, design pass, evidence and the other pages the skills link to).
58
72
 
59
73
  A project **extends** this: it adds rules with bare IDs (the base owns `V-`), skills, hooks and make targets, and never edits
60
74
  or shadows a shipped one.
61
75
 
62
76
  ## `doctor` checks
63
77
 
64
- `config` (exactly one valid config) · `layout` (AGENTS.md, rules, knowledge bundle) · `rule-ids` (every
65
- `V-` ID a project rule points at - an `Extends` list or a first cell - is a base rule) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
66
- shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
67
- not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
68
- `manifest` (`.agents/vulcan.manifest.json` exists and matches the config) · `tags` (every release tag `atlas.tagPattern` reads names a declared package, an alias or an ignored tag) ·
69
- `apps` (every `layout` folder is a workspace and every package lives in one; skipped without `layout`) ·
70
- `style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it; the packages are `packages/*` and every configured package `path`) ·
71
- `scaffold` (the config is filled in: a project whose `package.json` declares `workspaces` lists its `packages`, and `.agents/knowledge/index.md` no longer holds the `vulcan:scaffold` line `init` writes).
78
+ `doctor` runs its checks in order; each is described in `docs/wiki/content/references/commands/doctor.md`.
72
79
 
73
80
  The session-start digest prints the base write boundaries, the slot choices, the project's own rules (bold `| **W-00** |` rows and `| V-W-02, V-W-03 |` rows that elaborate base rules), the project's `<!-- minimap-shape:start -->` ... `<!-- minimap-shape:end -->` block from `.agents/rules.md` verbatim, and the `digest.oftenDropped` rules.
74
81
 
@@ -2,7 +2,23 @@
2
2
  * Gate: every source path the wiki and the knowledge bundle name is tracked by git. Run from the
3
3
  * repository root, through `make wiki-links-check WIKI_REPO=<owner/name>` or directly:
4
4
  * bun node_modules/@venizia/vulcan/base/checks/wiki-source-links.ts --repo <owner/name>
5
+ * The folders it checks come from the `layout` of `.configs/vulcan.config.mts`; with no layout, the default list.
5
6
  */
7
+ import { ConfigLoader } from '../../src/config/index.ts';
6
8
  import { runSourceLinksCommand } from '../../src/wiki/index.ts';
7
9
 
8
- process.exit(runSourceLinksCommand({ args: process.argv.slice(2), root: process.cwd() }));
10
+ const root = process.cwd();
11
+ const loaded = await ConfigLoader.load({ root });
12
+ const note = ConfigLoader.unreadableNote({ loaded });
13
+
14
+ if (note !== undefined) {
15
+ console.error(`wiki-source-links: ${note}`);
16
+ }
17
+
18
+ process.exit(
19
+ runSourceLinksCommand({
20
+ args: process.argv.slice(2),
21
+ root,
22
+ layout: loaded.ok ? loaded.config.layout : undefined,
23
+ }),
24
+ );
@@ -11,17 +11,6 @@
11
11
  ]
12
12
  }
13
13
  ],
14
- "Stop": [
15
- {
16
- "hooks": [
17
- {
18
- "type": "command",
19
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/event.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; fi; exit 0",
20
- "timeout": 5
21
- }
22
- ]
23
- }
24
- ],
25
14
  "SubagentStop": [
26
15
  {
27
16
  "hooks": [
@@ -46,6 +35,7 @@
46
35
  ],
47
36
  "PostToolUse": [
48
37
  {
38
+ "matcher": "SendMessage",
49
39
  "hooks": [
50
40
  {
51
41
  "type": "command",
@@ -8,7 +8,7 @@
8
8
  "hooks": [
9
9
  {
10
10
  "type": "command",
11
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/session-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 session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-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"
11
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the session-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-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"
12
12
  }
13
13
  ]
14
14
  }
@@ -19,34 +19,7 @@
19
19
  "hooks": [
20
20
  {
21
21
  "type": "command",
22
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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
- }
24
- ]
25
- },
26
- {
27
- "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
28
- "hooks": [
29
- {
30
- "type": "command",
31
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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
- }
33
- ]
34
- },
35
- {
36
- "matcher": "Write",
37
- "hooks": [
38
- {
39
- "type": "command",
40
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-git.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then in=$(cat); t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_])(git|gh)([^[:alnum:]_]|$)'; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; exit 0; fi; 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"
22
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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 --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the guard-writes hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; 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"
50
23
  }
51
24
  ]
52
25
  },
@@ -55,7 +28,7 @@
55
28
  "hooks": [
56
29
  {
57
30
  "type": "command",
58
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-scripting.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the guard-scripting hook failed - the call passes\" >&2; exit 0; fi; echo \"vulcan: the guard-scripting hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes\" >&2; exit 0"
31
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-git.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"tool_name\" *: *\"Bash\"' && printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules/[.]bin/vulcan sync( --?[a-z][a-z-]*( [[:alnum:]_./@-]+)?)*)\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun --no-env-file --config=/dev/null \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_]|\\\\[ntr]|\\\\u00[0-9a-fA-F]{2})(git|gh)([^[:alnum:]_]|$)'; then m=\"${CLAUDE_PROJECT_DIR:-$PWD}/.agents/vulcan.manifest.json\"; [ \"$VULCAN_GUARD_ASKS\" = deny ] || { [ -f \"$m\" ] && ! M=\"$m\" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require(\"node:fs\").readFileSync(process.env.M, \"utf8\")); if (typeof v !== \"object\" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; } || grep -Eq '\"asks\" *: *\"deny\"' \"$m\" 2>/dev/null; if [ $? -eq 0 ]; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: run bun install to repair the install.\"}}'; else printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; fi; exit 0; fi; echo \"vulcan: the guard-git hook failed - the call passes\" >&2; exit 0; fi; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_]|\\\\[ntr]|\\\\u00[0-9a-fA-F]{2})(git|gh)([^[:alnum:]_]|$)'; then ok && exit 0; echo \"vulcan: VULCAN guards unavailable: the guard-git hook cannot run (node_modules/@venizia/vulcan or bun is missing, or the hook is not in the installed package): finish bun install, or run bun node_modules/.bin/vulcan sync - the commands that pass until then\" >&2; exit 2; fi; echo \"vulcan: the guard-git hook cannot run, and this call names no git or gh - the call passes\" >&2; exit 0"
59
32
  }
60
33
  ]
61
34
  },
@@ -64,7 +37,7 @@
64
37
  "hooks": [
65
38
  {
66
39
  "type": "command",
67
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-outside.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then in=$(cat); t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-outside hook crashed or timed out, so this call was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; 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"
40
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-outside.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"tool_name\" *: *\"Bash\"' && printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules/[.]bin/vulcan sync( --?[a-z][a-z-]*( [[:alnum:]_./@-]+)?)*)\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun --no-env-file --config=/dev/null \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; m=\"${CLAUDE_PROJECT_DIR:-$PWD}/.agents/vulcan.manifest.json\"; [ \"$VULCAN_GUARD_ASKS\" = deny ] || { [ -f \"$m\" ] && ! M=\"$m\" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require(\"node:fs\").readFileSync(process.env.M, \"utf8\")); if (typeof v !== \"object\" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; } || grep -Eq '\"asks\" *: *\"deny\"' \"$m\" 2>/dev/null; if [ $? -eq 0 ]; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"The guard-outside hook crashed or timed out, so this call was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: run bun install to repair the install.\"}}'; else printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-outside hook crashed or timed out, so this call was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; fi; exit 0; fi; ok && exit 0; echo \"vulcan: VULCAN guards unavailable: the guard-outside hook cannot run (node_modules/@venizia/vulcan or bun is missing, or the hook is not in the installed package): finish bun install, or run bun node_modules/.bin/vulcan sync - the commands that pass until then\" >&2; exit 2"
68
41
  }
69
42
  ]
70
43
  }
@@ -74,51 +47,7 @@
74
47
  "hooks": [
75
48
  {
76
49
  "type": "command",
77
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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"
78
- }
79
- ]
80
- }
81
- ],
82
- "UserPromptSubmit": [
83
- {
84
- "hooks": [
85
- {
86
- "type": "command",
87
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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",
88
- "timeout": 15
89
- }
90
- ]
91
- }
92
- ],
93
- "Stop": [
94
- {
95
- "hooks": [
96
- {
97
- "type": "command",
98
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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",
99
- "timeout": 15
100
- }
101
- ]
102
- }
103
- ],
104
- "PostToolUse": [
105
- {
106
- "hooks": [
107
- {
108
- "type": "command",
109
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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",
110
- "timeout": 15
111
- }
112
- ]
113
- }
114
- ],
115
- "PostToolUseFailure": [
116
- {
117
- "hooks": [
118
- {
119
- "type": "command",
120
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/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",
121
- "timeout": 15
50
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/subagent-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the subagent-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; 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"
122
51
  }
123
52
  ]
124
53
  }
@@ -4,12 +4,14 @@
4
4
  // tool call it runs the same guard scripts Claude Code runs (node_modules/@venizia/vulcan/base/hooks/*.ts),
5
5
  // with a Claude-shaped event on stdin, and turns the answer into this agent's: `deny` blocks, `ask` asks
6
6
  // the owner (and blocks when there is no UI to ask). A guard that cannot give an answer follows the same
7
- // policy as the Claude wrappers: the safety guards block, the others ask, and a missing install passes
8
- // except for the safety guards, which block - bar a bare `bun install`, the way to repair it.
7
+ // policy as the Claude wrappers: the safety guards block, the others ask, and a missing install blocks
8
+ // too - bar a bare `bun install` or `vulcan sync`, the way to repair it (guard-git only for a git or gh line).
9
+ // A guard that is gone from an installed package blocks, except guard-writes, which passes: there is nothing
10
+ // to run. A project that sets `guard.asks: 'deny'` has every ask answered as a block.
9
11
  // Only node: modules are imported, so any host that loads TypeScript can load it.
10
12
 
11
13
  import { spawnSync } from 'node:child_process';
12
- import { existsSync } from 'node:fs';
14
+ import { existsSync, readFileSync } from 'node:fs';
13
15
  import { dirname, join } from 'node:path';
14
16
 
15
17
  class Tools {
@@ -59,6 +61,10 @@ interface IGuard {
59
61
  name: string;
60
62
  tools: string[];
61
63
  onFailure: string;
64
+ /** Whether the call is blocked when the package is installed and only this guard is gone from it. */
65
+ isClosedWhenGone: boolean;
66
+ /** The lines the guard covers when it is missing: a line that does not match passes. Every line when absent. */
67
+ onlyLines?: RegExp;
62
68
  }
63
69
 
64
70
  interface IAnswer {
@@ -66,23 +72,34 @@ interface IAnswer {
66
72
  reason: string;
67
73
  }
68
74
 
69
- const HOOKS_DIRECTORY = join('node_modules', '@venizia', 'vulcan', 'base', 'hooks');
75
+ const PACKAGE_DIRECTORY = join('node_modules', '@venizia', 'vulcan');
76
+ const HOOKS_DIRECTORY = join(PACKAGE_DIRECTORY, 'base', 'hooks');
70
77
  const TIMEOUT_MS = 30_000;
71
- /** The one command that passes while the install is missing: it is how the install is repaired. */
72
- const BUN_INSTALL =
73
- /^\s*bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\s*$/;
78
+ /** The commands that pass while the install is missing or out of step: they are how it is repaired (`bun install`, `vulcan sync`). */
79
+ const REPAIR =
80
+ /^\s*(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules\/\.bin\/vulcan sync( --?[a-z][a-z-]*( [\w./@-]+)?)*)\s*$/;
81
+ /** A command line that names git or gh as a word. */
82
+ const GIT_LINE = /(^|[^A-Za-z0-9_])(git|gh)([^A-Za-z0-9_]|$)/;
83
+ const MANIFEST_FILE = join('.agents', 'vulcan.manifest.json');
84
+ const HELD_ASK =
85
+ 'Every call that would need a human to confirm it is denied here (guard.asks: deny, VULCAN_GUARD_ASKS=deny, or a manifest that cannot be read). Nothing was run: hand this to the owner.';
74
86
 
75
87
  /** The guards of `.claude/settings.json`, with the tools each covers and what each does when it cannot answer. */
76
88
  const GUARDS: IGuard[] = [
77
- { name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK },
89
+ { name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK, isClosedWhenGone: false },
78
90
  {
79
- name: 'guard-manifest',
91
+ name: 'guard-git',
92
+ tools: [Tools.BASH],
93
+ onFailure: Failures.ASK,
94
+ isClosedWhenGone: true,
95
+ onlyLines: GIT_LINE,
96
+ },
97
+ {
98
+ name: 'guard-outside',
80
99
  tools: [Tools.BASH, Tools.WRITE, Tools.EDIT],
81
- onFailure: Failures.BLOCK,
100
+ onFailure: Failures.ASK,
101
+ isClosedWhenGone: true,
82
102
  },
83
- { name: 'guard-package', tools: [Tools.WRITE], onFailure: Failures.BLOCK },
84
- { name: 'guard-git', tools: [Tools.BASH], onFailure: Failures.ASK },
85
- { name: 'guard-outside', tools: [Tools.BASH, Tools.WRITE, Tools.EDIT], onFailure: Failures.ASK },
86
103
  ];
87
104
 
88
105
  const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -107,6 +124,31 @@ const rootOf = (opts: { cwd: string }): string => {
107
124
  }
108
125
  };
109
126
 
127
+ /**
128
+ * Whether every ask is a deny in the project at `root`: the launch environment says `VULCAN_GUARD_ASKS=deny`, the manifest sets
129
+ * `guard.asks` to `deny`, or the manifest exists and cannot be read. No manifest means asks stay asks.
130
+ */
131
+ const isHeldIn = (opts: { root: string }): boolean => {
132
+ if (process.env.VULCAN_GUARD_ASKS === Answers.DENY) {
133
+ return true;
134
+ }
135
+
136
+ const file = join(opts.root, MANIFEST_FILE);
137
+
138
+ if (!existsSync(file)) {
139
+ return false;
140
+ }
141
+
142
+ try {
143
+ const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
144
+ const guard = isRecord(manifest) ? manifest.guard : undefined;
145
+
146
+ return !isRecord(manifest) || (isRecord(guard) && guard.asks === Answers.DENY);
147
+ } catch {
148
+ return true;
149
+ }
150
+ };
151
+
110
152
  /** The event Claude Code sends: snake_case keys on the wire, written through string-literal keys. */
111
153
  const wireEventOf = (opts: {
112
154
  tool: string;
@@ -187,10 +229,24 @@ const runGuard = (opts: {
187
229
  const script = join(opts.root, HOOKS_DIRECTORY, `${opts.guard.name}.ts`);
188
230
 
189
231
  if (!existsSync(script)) {
190
- return { kind: Answers.MISSING, reason: `${opts.guard.name} is missing: run bun install` };
232
+ // The package is installed and only this guard is gone from it: guard-writes passes (nothing to run), the others block.
233
+ if (existsSync(join(opts.root, PACKAGE_DIRECTORY, 'package.json'))) {
234
+ return opts.guard.isClosedWhenGone
235
+ ? {
236
+ kind: Answers.MISSING,
237
+ reason: `VULCAN guards unavailable: ${opts.guard.name} is not in the installed package; run bun node_modules/.bin/vulcan sync`,
238
+ }
239
+ : { kind: Answers.ALLOW, reason: '' };
240
+ }
241
+
242
+ return {
243
+ kind: Answers.MISSING,
244
+ reason: `VULCAN guards unavailable: ${opts.guard.name} is missing; finish bun install`,
245
+ };
191
246
  }
192
247
 
193
- const result = spawnSync('bun', [script], {
248
+ // bun reads `.env` and `bunfig.toml` from the working directory: a file an agent writes there (a `VULCAN_GUARDS=off`, a preload) must not reach a guard.
249
+ const result = spawnSync('bun', ['--no-env-file', '--config=/dev/null', script], {
194
250
  input: JSON.stringify(opts.claudeEvent),
195
251
  encoding: 'utf8',
196
252
  timeout: TIMEOUT_MS,
@@ -252,10 +308,13 @@ export class GuardVerdict {
252
308
  }
253
309
 
254
310
  if (answer.kind === Answers.MISSING) {
255
- const isRepair =
256
- opts.toolName === Tools.BASH && BUN_INSTALL.test(String(opts.input.command));
311
+ const command = String(opts.input.command);
312
+ const isRepair = opts.toolName === Tools.BASH && REPAIR.test(command);
313
+ const isCovered =
314
+ guard.onlyLines === undefined ||
315
+ (opts.toolName === Tools.BASH && guard.onlyLines.test(command));
257
316
 
258
- if (guard.onFailure === Failures.BLOCK && !isRepair) {
317
+ if (!isRepair && isCovered) {
259
318
  return { kind: Verdicts.DENY, reason: answer.reason };
260
319
  }
261
320
  }
@@ -269,6 +328,10 @@ export class GuardVerdict {
269
328
  }
270
329
  }
271
330
 
331
+ if (asks.length > 0 && isHeldIn({ root })) {
332
+ return { kind: Verdicts.DENY, reason: `${asks.join('\n\n')}\n\n${HELD_ASK}` };
333
+ }
334
+
272
335
  return asks.length > 0
273
336
  ? { kind: Verdicts.ASK, reason: asks.join('\n\n') }
274
337
  : { kind: Verdicts.ALLOW, reason: '' };
@@ -5,11 +5,12 @@
5
5
  * `reset --hard`, other force-pushes, `branch -D` of an unmerged branch and `gh pr create` with no `--base`
6
6
  * (ask: the pull request would land on the default branch).
7
7
  *
8
- * It guards against drift, it is not the last line of defence, and a guard that blocks every command when
9
- * its install is broken costs more than it protects. So input it cannot read passes, and so does a missing
10
- * package or `bun` (the settings wrapper says so on stderr). A guard that started and then failed - a crash
11
- * or a timeout, here an internal error or an unloadable module - ASKS about a command that names `git` or
12
- * `gh`, instead of passing it unchecked. `VULCAN_GUARDS=off` switches it off, read before anything is
8
+ * It guards against drift, it is not the last line of defence. A missing package, `bun` or hook file is the settings wrapper's
9
+ * to answer: it blocks a command that names `git` or `gh`, bar `bun install` and `vulcan sync`. Input it cannot read ASKS,
10
+ * because nothing was checked. A guard that started and then failed - a crash or a timeout, here an internal error or an
11
+ * unloadable module - ASKS about a command that names `git` or `gh`, instead of passing it unchecked. Where the project
12
+ * (`guard.asks: 'deny'`) or the launch environment (`VULCAN_GUARD_ASKS=deny`) holds every ask, each ask is a deny, and so is a
13
+ * crash when the manifest exists and cannot be read. `VULCAN_GUARDS=off` switches it off, read before anything is
13
14
  * imported. It imports only the modules it needs - no config, no zod. The branches the project lists in
14
15
  * `guard.git.askPush` are read from the manifest, and a plain push to one of them asks.
15
16
  */
@@ -27,34 +28,73 @@ try {
27
28
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
28
29
  const { HookDecision } = await import('../../src/hooks/decision.ts');
29
30
  const { GitGuard } = await import('../../src/hooks/guard-git.ts');
31
+ const { RunnerGuard } = await import('../../src/hooks/guard-runner.ts');
30
32
  const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
31
33
  const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
32
34
  const hookCommand = WriteGuard.parseHookCommand({ text });
33
35
  const cwd = hookCommand?.cwd ?? process.cwd();
36
+ const policy = ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
34
37
  const hits = hookCommand
35
- ? GitGuard.inspect({
36
- command: hookCommand.command,
37
- cwd,
38
- askPush: ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).askPush,
39
- })
40
- : [];
38
+ ? [
39
+ ...GitGuard.inspect({ command: hookCommand.command, cwd, askPush: policy.askPush }),
40
+ ...RunnerGuard.inspect({ command: hookCommand.command, cwd, allow: policy.runnersAllow }),
41
+ ]
42
+ : [
43
+ {
44
+ rule: 'V-W-01',
45
+ message: 'the hook input could not be read, so the command was not checked',
46
+ decision: GuardDecisions.ASK,
47
+ fix: undefined,
48
+ },
49
+ ];
41
50
 
42
51
  if (hits.length > 0) {
43
52
  const denied = hits.some((hit) => hit.decision === GuardDecisions.DENY);
53
+ // A project that sets guard.asks to deny refuses what would ask a human, with the owner to hand it to.
54
+ const isHeld = !denied && policy.asks === GuardDecisions.DENY;
55
+ // A denial the agent can repair says how; one that is the owner's to decide is handed to the owner.
56
+ const fixes = [
57
+ ...new Set(
58
+ hits.flatMap((hit) =>
59
+ hit.decision === GuardDecisions.DENY && hit.fix !== undefined ? [hit.fix] : [],
60
+ ),
61
+ ),
62
+ ];
63
+ const isOwners = hits.some(
64
+ (hit) => hit.decision === GuardDecisions.DENY && hit.fix === undefined,
65
+ );
44
66
 
45
67
  console.log(
46
68
  JSON.stringify(
47
69
  HookDecision.buildTool({
48
- decision: denied ? GuardDecisions.DENY : GuardDecisions.ASK,
70
+ asks: policy.asks,
71
+ asksNote: policy.asksNote,
72
+ decision: denied || isHeld ? GuardDecisions.DENY : GuardDecisions.ASK,
49
73
  reason: [
50
74
  denied
51
75
  ? 'This command is refused by the base rules:'
52
- : 'This command needs a human to confirm:',
76
+ : isHeld
77
+ ? 'This command needs a human to confirm, and every ask is denied here:'
78
+ : 'This command needs a human to confirm:',
53
79
  ...hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
54
80
  '',
55
- denied
56
- ? 'Hand the exact command to the owner instead (V-W-06); VULCAN_GUARDS=off switches the guards off for a session.'
57
- : 'Confirm only if the owner asked for exactly this.',
81
+ ...(denied
82
+ ? [
83
+ ...(fixes.length > 0
84
+ ? [`Nothing was run. Write it again: ${fixes.join('; ')}.`]
85
+ : []),
86
+ ...(isOwners || fixes.length === 0
87
+ ? [
88
+ 'Hand the exact command to the owner instead (V-W-06); VULCAN_GUARDS=off switches the guards off for a session.',
89
+ ]
90
+ : []),
91
+ ]
92
+ : isHeld
93
+ ? [
94
+ 'Nothing was run. Hand the exact command to the owner instead (V-W-06).',
95
+ ...(policy.asksNote === undefined ? [] : [policy.asksNote]),
96
+ ]
97
+ : ['Confirm only if the owner asked for exactly this.']),
58
98
  ],
59
99
  }),
60
100
  ),
@@ -65,18 +105,54 @@ try {
65
105
 
66
106
  console.error(`vulcan: the guard-git hook failed (${message}); run bun install`);
67
107
 
68
- // The imports may be what failed, so the answer is written by hand: no module is needed to ask.
108
+ // 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.
69
109
  if (/(^|[^A-Za-z0-9_])(git|gh)([^A-Za-z0-9_]|$)/.test(text)) {
110
+ let isHeldOnCrash = false;
111
+
112
+ try {
113
+ const { existsSync, readFileSync } = await import('node:fs');
114
+ const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
115
+ const file = `${root}/.agents/vulcan.manifest.json`;
116
+
117
+ isHeldOnCrash = process.env.VULCAN_GUARD_ASKS === 'deny';
118
+
119
+ if (!isHeldOnCrash && existsSync(file)) {
120
+ try {
121
+ const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
122
+ const guard =
123
+ typeof manifest === 'object' && manifest !== null && 'guard' in manifest
124
+ ? manifest.guard
125
+ : undefined;
126
+
127
+ isHeldOnCrash =
128
+ typeof manifest !== 'object' ||
129
+ manifest === null ||
130
+ Array.isArray(manifest) ||
131
+ (typeof guard === 'object' &&
132
+ guard !== null &&
133
+ 'asks' in guard &&
134
+ guard.asks === 'deny');
135
+ } catch {
136
+ // A manifest that exists and cannot be read holds every ask.
137
+ isHeldOnCrash = true;
138
+ }
139
+ }
140
+ } catch {
141
+ isHeldOnCrash = false;
142
+ }
143
+
70
144
  console.log(
71
145
  JSON.stringify({
72
146
  hookSpecificOutput: {
73
147
  hookEventName: 'PreToolUse',
74
- permissionDecision: 'ask',
148
+ permissionDecision: isHeldOnCrash ? 'deny' : 'ask',
75
149
  permissionDecisionReason: [
76
150
  'The guard-git hook failed, so this command was not checked:',
77
151
  ` - ${message}`,
78
152
  '',
79
- 'Confirm only if the owner asked for exactly this; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
153
+ isHeldOnCrash
154
+ ? '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.'
155
+ : 'Confirm only if the owner asked for exactly this; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
80
156
  ].join('\n'),
81
157
  },
82
158
  }),