@venizia/vulcan 0.4.10-1 → 0.4.10-11

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 (218) hide show
  1. package/README.md +24 -20
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +0 -11
  4. package/base/claude/settings.json +3 -74
  5. package/base/extensions/vulcan-guards.ts +9 -8
  6. package/base/hooks/event.ts +4 -3
  7. package/base/hooks/guard-git.ts +9 -3
  8. package/base/hooks/guard-outside.ts +61 -34
  9. package/base/hooks/guard-writes.ts +10 -35
  10. package/base/hooks/session-start.ts +1 -1
  11. package/base/make/vulcan.mk +1 -4
  12. package/base/packs/venizia.md +16 -0
  13. package/base/references/delegation-brief.md +3 -5
  14. package/base/references/testing.md +1 -9
  15. package/base/rules.md +32 -38
  16. package/base/skills/build-a-feature/SKILL.md +12 -3
  17. package/base/skills/docs-update/SKILL.md +16 -5
  18. package/base/skills/fix-a-bug/SKILL.md +2 -2
  19. package/base/skills/plan-a-change/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +10 -6
  22. package/base/skills/ship/SKILL.md +9 -4
  23. package/base/skills/visualize-work/SKILL.md +1 -1
  24. package/base/skills/visualize-work/references/spec.md +5 -2
  25. package/base/templates/AGENTS.md +2 -2
  26. package/base/templates/board.html +840 -4504
  27. package/base/templates/pull-request.md +31 -0
  28. package/base/templates/vulcan.config.mts +1 -0
  29. package/package.json +6 -4
  30. package/src/agents/atlas-block.ts +8 -31
  31. package/src/agents/generated-block.ts +52 -0
  32. package/src/agents/index.ts +2 -0
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/agent-setting.ts +43 -0
  36. package/src/board/command.ts +213 -30
  37. package/src/board/common/constants.ts +64 -1
  38. package/src/board/common/types.ts +37 -2
  39. package/src/board/fold.ts +81 -10
  40. package/src/board/github.ts +7 -5
  41. package/src/board/gitlab.ts +436 -0
  42. package/src/board/index.ts +3 -0
  43. package/src/board/logo.ts +49 -0
  44. package/src/board/open-file.ts +110 -0
  45. package/src/board/page.ts +57 -5
  46. package/src/board/schema.ts +35 -0
  47. package/src/board/server.ts +409 -0
  48. package/src/board/settings.ts +115 -36
  49. package/src/board/watch.ts +88 -0
  50. package/src/commands/clean.command.ts +6 -1
  51. package/src/commands/help.command.ts +2 -62
  52. package/src/commands/index.ts +0 -1
  53. package/src/commands/init.command.ts +26 -1
  54. package/src/commands/sync.command.ts +8 -4
  55. package/src/commands/table.ts +298 -0
  56. package/src/commit/check.ts +1 -0
  57. package/src/commit/common/constants.ts +2 -0
  58. package/src/commit/hook.ts +84 -5
  59. package/src/common/constants.ts +11 -4
  60. package/src/common/env-variables.ts +37 -0
  61. package/src/common/git-files.ts +11 -0
  62. package/src/common/index.ts +2 -0
  63. package/src/common/layout-folder.ts +4 -5
  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 +259 -152
  68. package/src/create/add-app.ts +5 -0
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +6 -3
  71. package/src/create/dockerignore.ts +5 -3
  72. package/src/create/init-monorepo.ts +28 -4
  73. package/src/create/preset.ts +1 -0
  74. package/src/create/project-key.ts +60 -0
  75. package/src/create/scratch.ts +2 -1
  76. package/src/create/workspace.ts +2 -1
  77. package/src/doctor/checks.ts +243 -411
  78. package/src/doctor/common/constants.ts +68 -16
  79. package/src/doctor/common/types.ts +2 -1
  80. package/src/doctor/index.ts +2 -0
  81. package/src/doctor/private-values.ts +111 -0
  82. package/src/doctor/runner.ts +7 -11
  83. package/src/doctor/schema.ts +33 -0
  84. package/src/events/actor.ts +10 -5
  85. package/src/events/command.ts +209 -19
  86. package/src/events/common/actor-names.ts +12 -0
  87. package/src/events/common/constants.ts +135 -18
  88. package/src/events/common/index.ts +1 -0
  89. package/src/events/common/types.ts +18 -0
  90. package/src/events/flow-id.ts +89 -0
  91. package/src/events/flow.ts +4 -4
  92. package/src/events/hook.ts +9 -13
  93. package/src/events/index.ts +2 -0
  94. package/src/events/log.ts +78 -3
  95. package/src/events/project-key.ts +22 -0
  96. package/src/events/retention.ts +2 -4
  97. package/src/events/settings.ts +16 -0
  98. package/src/events/text.ts +64 -6
  99. package/src/hooks/command-view.ts +80 -19
  100. package/src/hooks/common/constants.ts +0 -17
  101. package/src/hooks/common/types.ts +4 -24
  102. package/src/hooks/git-queries.ts +113 -0
  103. package/src/hooks/guard-git.ts +65 -21
  104. package/src/hooks/guard-outside.ts +167 -310
  105. package/src/hooks/guard-writes.ts +84 -183
  106. package/src/hooks/hook-input.ts +57 -0
  107. package/src/hooks/index.ts +2 -6
  108. package/src/hooks/project-guards.ts +24 -40
  109. package/src/hooks/project-tmp.ts +39 -4
  110. package/src/hooks/script-runners.ts +392 -0
  111. package/src/hooks/session-digest.ts +27 -117
  112. package/src/hooks/shell-folders.ts +338 -0
  113. package/src/hooks/shell-writes.ts +529 -0
  114. package/src/hooks/shell.ts +1387 -193
  115. package/src/hooks/subagent-card.ts +2 -2
  116. package/src/hooks/write-commands.ts +898 -0
  117. package/src/init/common/constants.ts +1 -0
  118. package/src/init/scaffold.ts +38 -7
  119. package/src/local/auto-clean.ts +2 -1
  120. package/src/local/browser-socket.ts +33 -0
  121. package/src/local/clean.ts +37 -6
  122. package/src/local/constants.ts +15 -1
  123. package/src/local/index.ts +1 -0
  124. package/src/local/scan.ts +41 -10
  125. package/src/manifest/render.ts +81 -31
  126. package/src/owner/constants.ts +4 -5
  127. package/src/owner/index.ts +0 -2
  128. package/src/owner/profile.ts +1 -0
  129. package/src/owner/schema.ts +51 -27
  130. package/src/owner/survey.ts +0 -3
  131. package/src/owner/view.ts +0 -9
  132. package/src/router.ts +4 -123
  133. package/src/rules/base.ts +12 -7
  134. package/src/rules/index.ts +1 -0
  135. package/src/rules/packs.ts +44 -0
  136. package/src/skills/frontmatter.ts +1 -0
  137. package/src/sync/agents-block.ts +104 -0
  138. package/src/sync/base-rules.ts +3 -3
  139. package/src/sync/claude-launch.ts +66 -11
  140. package/src/sync/common/constants.ts +0 -2
  141. package/src/sync/index.ts +1 -1
  142. package/src/sync/local-choice.ts +32 -3
  143. package/src/sync/planner.ts +2 -15
  144. package/src/sync/settings.ts +0 -17
  145. package/src/theme/index.ts +1 -0
  146. package/src/theme/tokens.ts +410 -0
  147. package/src/ui/prompt.ts +1 -0
  148. package/src/visualize/architecture.ts +504 -0
  149. package/src/visualize/assets.ts +41 -30
  150. package/src/visualize/compare-render.ts +22 -24
  151. package/src/visualize/constants.ts +27 -0
  152. package/src/visualize/diagrams.ts +13 -121
  153. package/src/visualize/kinds-render.ts +2 -2
  154. package/src/visualize/kinds-schema.ts +49 -0
  155. package/src/visualize/labels-vi.ts +25 -0
  156. package/src/visualize/labels.ts +2 -0
  157. package/src/visualize/layout.ts +415 -66
  158. package/src/visualize/page.ts +82 -15
  159. package/src/visualize/render.ts +2 -1
  160. package/src/visualize/schema.ts +29 -1
  161. package/src/visualize/sections.ts +78 -9
  162. package/src/visualize/theme.ts +49 -18
  163. package/src/wiki/anchors.ts +1 -0
  164. package/src/wiki/command.ts +10 -3
  165. package/src/wiki/source-links.ts +62 -22
  166. package/base/ci-global.json +0 -13
  167. package/base/claude/remote-hosts.json +0 -15
  168. package/base/hooks/guard-manifest.ts +0 -27
  169. package/base/hooks/guard-package.ts +0 -30
  170. package/base/hooks/guard-remote-hosts.ts +0 -70
  171. package/base/hooks/guard-scripting.ts +0 -32
  172. package/base/hooks/post-tool.ts +0 -37
  173. package/base/hooks/prompt-submit.ts +0 -54
  174. package/base/hooks/stop.ts +0 -40
  175. package/base/skills/build-a-feature/evals/evals.json +0 -29
  176. package/base/skills/docs-update/evals/evals.json +0 -23
  177. package/base/skills/docs-writing/evals/evals.json +0 -17
  178. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  179. package/base/skills/knowledge-sync/SKILL.md +0 -81
  180. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  181. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  182. package/base/skills/plan-a-change/evals/evals.json +0 -47
  183. package/base/skills/report-back/evals/evals.json +0 -23
  184. package/base/skills/research/evals/evals.json +0 -17
  185. package/base/skills/retro/evals/evals.json +0 -17
  186. package/base/skills/review-a-change/evals/evals.json +0 -17
  187. package/base/skills/ship/evals/evals.json +0 -23
  188. package/base/skills/visualize-work/evals/evals.json +0 -17
  189. package/base/templates/ci/github-actions.yml +0 -75
  190. package/base/templates/ci/gitlab-ci.yml +0 -52
  191. package/src/ci/affected.ts +0 -176
  192. package/src/ci/command.ts +0 -166
  193. package/src/ci/common/constants.ts +0 -76
  194. package/src/ci/common/index.ts +0 -2
  195. package/src/ci/common/types.ts +0 -37
  196. package/src/ci/git.ts +0 -72
  197. package/src/ci/global.ts +0 -48
  198. package/src/ci/graph.ts +0 -43
  199. package/src/ci/index.ts +0 -7
  200. package/src/ci/workspace.ts +0 -119
  201. package/src/commands/ci.command.ts +0 -4
  202. package/src/hooks/guard-manifest.ts +0 -109
  203. package/src/hooks/guard-package.ts +0 -226
  204. package/src/hooks/guard-scripting.ts +0 -36
  205. package/src/hooks/host-pattern.ts +0 -17
  206. package/src/hooks/owner-reply.ts +0 -162
  207. package/src/hooks/post-tool.ts +0 -138
  208. package/src/hooks/remote-hosts.ts +0 -1013
  209. package/src/hooks/trusted-scripts.ts +0 -212
  210. package/src/owner/shape.ts +0 -496
  211. package/src/owner/violations.ts +0 -332
  212. package/src/signals/claims.ts +0 -73
  213. package/src/signals/classify.ts +0 -137
  214. package/src/signals/constants.ts +0 -88
  215. package/src/signals/index.ts +0 -5
  216. package/src/signals/loop.ts +0 -48
  217. package/src/signals/state.ts +0 -271
  218. package/src/sync/atlas-block.ts +0 -56
package/README.md CHANGED
@@ -9,6 +9,8 @@ bun x --no-install vulcan sync
9
9
  bun x --no-install 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,25 @@ 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 |
25
36
  | `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` | |
37
+ | `help`, `version` | `help` prints the usage; `version` prints the installed version |
27
38
 
28
- Diagnostics go to stderr; `vulcan` writes nothing to stdout of its own, so `vulcan x atlas mcp` is a
39
+ Diagnostics go to stderr; a command that produces a result prints only that on stdout, and `vulcan x atlas mcp` is a
29
40
  clean MCP stdio server.
30
41
 
31
42
  ## The project config
@@ -39,36 +50,29 @@ export default {
39
50
  agents: ['claude'],
40
51
  rules: { 'V-W-01': 'on-user-word' }, // slot choice: 'on-user-word' | 'read-only'
41
52
  knowledge: { bundle: '.agents/knowledge' },
42
- hooks: [{ event: 'Stop', command: 'echo done' }],
43
53
  claude: { settings: { permissions: { allow: ['Bash(make test)'] } } }, // team-shared, committed
44
54
  digest: { oftenDropped: ['V-B-03', 'W-00'] }, // repeated at every session start; base or own IDs
45
55
  layout: { backend: 'services', frontend: 'web', shared: 'libs' }, // written by init --preset and add
46
56
  } satisfies VulcanConfig;
47
57
  ```
48
58
 
49
- An unknown key is an error; every error names the file and the field.
59
+ 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
60
 
51
61
  ## What ships (`base/`)
52
62
 
53
- - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (51 rules).
63
+ - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-* (35 rules).
54
64
  - `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).
65
+ - `skills/` - 11 project-neutral skills, described in `docs/wiki/content/references/skills.md` (a project-specific skill stays in its project).
66
+ - `hooks/` - 16 hook files, described in `docs/wiki/content/references/hooks/index.md`.
57
67
  - `claude/settings.json`, `make/vulcan.mk`, `templates/`.
68
+ - `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
69
 
59
70
  A project **extends** this: it adds rules with bare IDs (the base owns `V-`), skills, hooks and make targets, and never edits
60
71
  or shadows a shipped one.
61
72
 
62
73
  ## `doctor` checks
63
74
 
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).
75
+ `doctor` runs its checks in order; each is described in `docs/wiki/content/references/commands/doctor.md`.
72
76
 
73
77
  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
78
 
@@ -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": [
@@ -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 \"$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 x 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,25 +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"
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; 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 x 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"
41
23
  }
42
24
  ]
43
25
  },
@@ -50,15 +32,6 @@
50
32
  }
51
33
  ]
52
34
  },
53
- {
54
- "matcher": "Bash",
55
- "hooks": [
56
- {
57
- "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"
59
- }
60
- ]
61
- },
62
35
  {
63
36
  "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
64
37
  "hooks": [
@@ -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 \"$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 x 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
  }
@@ -5,7 +5,8 @@
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
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.
8
+ // except for the safety guards, which block - bar a bare `bun install`, the way to repair it. A guard that
9
+ // is gone from an installed package passes: there is nothing to run.
9
10
  // Only node: modules are imported, so any host that loads TypeScript can load it.
10
11
 
11
12
  import { spawnSync } from 'node:child_process';
@@ -66,7 +67,8 @@ interface IAnswer {
66
67
  reason: string;
67
68
  }
68
69
 
69
- const HOOKS_DIRECTORY = join('node_modules', '@venizia', 'vulcan', 'base', 'hooks');
70
+ const PACKAGE_DIRECTORY = join('node_modules', '@venizia', 'vulcan');
71
+ const HOOKS_DIRECTORY = join(PACKAGE_DIRECTORY, 'base', 'hooks');
70
72
  const TIMEOUT_MS = 30_000;
71
73
  /** The one command that passes while the install is missing: it is how the install is repaired. */
72
74
  const BUN_INSTALL =
@@ -75,12 +77,6 @@ const BUN_INSTALL =
75
77
  /** The guards of `.claude/settings.json`, with the tools each covers and what each does when it cannot answer. */
76
78
  const GUARDS: IGuard[] = [
77
79
  { name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK },
78
- {
79
- name: 'guard-manifest',
80
- tools: [Tools.BASH, Tools.WRITE, Tools.EDIT],
81
- onFailure: Failures.BLOCK,
82
- },
83
- { name: 'guard-package', tools: [Tools.WRITE], onFailure: Failures.BLOCK },
84
80
  { name: 'guard-git', tools: [Tools.BASH], onFailure: Failures.ASK },
85
81
  { name: 'guard-outside', tools: [Tools.BASH, Tools.WRITE, Tools.EDIT], onFailure: Failures.ASK },
86
82
  ];
@@ -187,6 +183,11 @@ const runGuard = (opts: {
187
183
  const script = join(opts.root, HOOKS_DIRECTORY, `${opts.guard.name}.ts`);
188
184
 
189
185
  if (!existsSync(script)) {
186
+ // The package is installed and only this guard is gone from it: nothing to run, the call passes.
187
+ if (existsSync(join(opts.root, PACKAGE_DIRECTORY, 'package.json'))) {
188
+ return { kind: Answers.ALLOW, reason: '' };
189
+ }
190
+
190
191
  return { kind: Answers.MISSING, reason: `${opts.guard.name} is missing: run bun install` };
191
192
  }
192
193
 
@@ -1,7 +1,8 @@
1
1
  /**
2
- * Event log hook (SessionStart, Stop, SubagentStop, Notification, PostToolUse on SendMessage): appends one
3
- * line to the agent event log (src/events/hook.ts) when the manifest says `events.log` is on. It stores
4
- * names and short labels only - never a message body, the last reply, a command or a file path.
2
+ * Event log hook (SessionStart, Stop, SubagentStop, Notification and PostToolUse: a SendMessage is a message,
3
+ * any other tool at most one tick per session every 30 seconds): appends one line to the agent event log
4
+ * (src/events/hook.ts) when the manifest says `events.log` is on. It stores names and short labels only -
5
+ * never a message body, the last reply, a command, a path or anything of a tool's input or result.
5
6
  *
6
7
  * It fails OPEN and says nothing on stdout: input it cannot read, a missing module or a write that fails
7
8
  * pass with a note on stderr, and the agent is never held. It imports only the events module, no config and
@@ -6,8 +6,8 @@
6
6
  * (ask: the pull request would land on the default branch).
7
7
  *
8
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
9
+ * its install is broken costs more than it protects. So a missing package or `bun` passes (the settings wrapper
10
+ * says so on stderr); input it cannot read ASKS, because nothing was checked. A guard that started and then failed - a crash
11
11
  * or a timeout, here an internal error or an unloadable module - ASKS about a command that names `git` or
12
12
  * `gh`, instead of passing it unchecked. `VULCAN_GUARDS=off` switches it off, read before anything is
13
13
  * imported. It imports only the modules it needs - no config, no zod. The branches the project lists in
@@ -37,7 +37,13 @@ try {
37
37
  cwd,
38
38
  askPush: ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).askPush,
39
39
  })
40
- : [];
40
+ : [
41
+ {
42
+ rule: 'V-W-01',
43
+ message: 'the hook input could not be read, so the command was not checked',
44
+ decision: GuardDecisions.ASK,
45
+ },
46
+ ];
41
47
 
42
48
  if (hits.length > 0) {
43
49
  const denied = hits.some((hit) => hit.decision === GuardDecisions.DENY);
@@ -4,15 +4,18 @@
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
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.
7
+ * approved unseen. A write into the agent tool scratchpad is always denied. A part of the call it cannot read (a
8
+ * program or a target named by a variable, a line it cannot follow to its end) is asked about even under `deny`: it
9
+ * does not know that anything is outside.
8
10
  *
9
11
  * 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
+ * is broken costs more than it protects. So a missing package or `bun` passes (the settings wrapper says so on
13
+ * stderr); input it cannot read ASKS, because nothing was checked. A guard that started and then failed - a crash or a
12
14
  * 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.
15
+ * manifest that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
16
+ * read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
17
+ * from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
18
+ * VULCAN cannot parse, then changes nothing here.
16
19
  */
17
20
 
18
21
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -28,59 +31,83 @@ try {
28
31
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
29
32
  const { HookDecision } = await import('../../src/hooks/decision.ts');
30
33
  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 });
34
+ const { HookInput } = await import('../../src/hooks/hook-input.ts');
35
+ const { ProjectTmp } = await import('../../src/hooks/project-tmp.ts');
36
+ const { relative } = await import('node:path');
37
+ const input = HookInput.parse({ text });
33
38
 
34
- if (input) {
39
+ if (!input) {
40
+ console.log(
41
+ JSON.stringify(
42
+ HookDecision.buildTool({
43
+ decision: GuardDecisions.ASK,
44
+ reason: [
45
+ 'The hook input could not be read, so this call was not checked for files outside the project (V-B-08).',
46
+ 'Confirm only if the call stays inside the project.',
47
+ ],
48
+ }),
49
+ ),
50
+ );
51
+ } else {
35
52
  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
- }
53
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
54
+ const { toolOwnedPaths, outside } = ProjectGuards.readPolicy({ root: projectRoot });
50
55
 
51
56
  const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
52
57
 
53
58
  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.';
59
+ const read = hits.filter((hit) => !hit.isUnread);
60
+ const isScratchpad = read.some((hit) => hit.isAgentToolScratchpad);
61
+ const linesOf = (list: typeof hits) => list.map((hit) => ` - ${hit.message} (${hit.path})`);
62
+ const tmpFolder = relative(projectRoot, ProjectTmp.projectOf({ root: projectRoot }));
63
+ 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.`;
64
+ const owned =
65
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.';
58
66
 
59
- const isDeny = isScratchpad || outside === GuardDecisions.DENY;
67
+ // A line the check could not read is asked about even where the project denies: it does not know of a path outside.
68
+ const unread =
69
+ read.length === hits.length
70
+ ? []
71
+ : [
72
+ ...(read.length > 0 ? [''] : []),
73
+ 'Part of this call could not be read, so it was not checked for files outside the project (V-B-08):',
74
+ ...linesOf(hits.filter((hit) => hit.isUnread)),
75
+ ];
76
+ const isDeny = isScratchpad || (outside === GuardDecisions.DENY && read.length > 0);
60
77
  let reason: string[];
61
78
 
62
- if (isScratchpad) {
79
+ if (read.length === 0) {
80
+ reason = [
81
+ ...unread,
82
+ '',
83
+ `Confirm only if it creates nothing outside the project. ${places} A literal path can be read.`,
84
+ owned,
85
+ ];
86
+ } else if (isScratchpad) {
63
87
  reason = [
64
88
  'This would write into the scratchpad folder the agent tool offers (V-B-08):',
65
- ...hitLines,
89
+ ...linesOf(read),
90
+ ...unread,
66
91
  '',
67
92
  `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
93
  ];
69
94
  } else if (isDeny) {
70
95
  reason = [
71
96
  'This would create files outside the project (V-B-08), and this project denies it (guard.outside):',
72
- ...hitLines,
97
+ ...linesOf(read),
98
+ ...unread,
73
99
  '',
74
100
  `Nothing was written. ${places}`,
75
- 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
101
+ owned,
76
102
  ];
77
103
  } else {
78
104
  reason = [
79
105
  'This would create files outside the project (V-B-08):',
80
- ...hitLines,
106
+ ...linesOf(read),
107
+ ...unread,
81
108
  '',
82
109
  `${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.*.',
110
+ owned,
84
111
  ];
85
112
  }
86
113
 
@@ -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,38 +19,16 @@ 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
34
  console.log(JSON.stringify(WriteGuard.buildDecision({ hits })));
@@ -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
  */
@@ -7,7 +7,7 @@ VULCAN_BASE ?= node_modules/@venizia/vulcan/base
7
7
  # The GitHub repository the wiki links point into, owner/name; the link gate checks only links into it.
8
8
  WIKI_REPO ?=
9
9
 
10
- .PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage okf-viz \
10
+ .PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage \
11
11
  surface-gen surface-check atlas-symbols atlas-releases wiki-links-check wiki-anchors-check
12
12
 
13
13
  vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
@@ -29,9 +29,6 @@ okf-gen: ## Regenerate the generated pages and regions of the knowledge bundle
29
29
  okf-coverage: ## Report how much of the code the knowledge bundle covers
30
30
  @$(VULCAN) x okf coverage
31
31
 
32
- okf-viz: ## Build the knowledge graph view
33
- @$(VULCAN) x okf viz
34
-
35
32
  # The public surface: an optional API gate a project commits and checks. It reads the built .d.ts -
36
33
  # build first.
37
34
  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