@venizia/vulcan 0.4.10-2 → 0.4.10-20

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 (205) 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 +3 -74
  5. package/base/extensions/vulcan-guards.ts +9 -8
  6. package/base/hooks/guard-git.ts +39 -11
  7. package/base/hooks/guard-outside.ts +94 -35
  8. package/base/hooks/guard-writes.ts +10 -35
  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/generated-block.ts +52 -0
  29. package/src/agents/index.ts +2 -0
  30. package/src/agents/render.ts +15 -2
  31. package/src/agents/resolve.ts +1 -0
  32. package/src/agents/rules-block.ts +92 -0
  33. package/src/board/command.ts +92 -30
  34. package/src/board/common/constants.ts +26 -0
  35. package/src/board/common/types.ts +10 -3
  36. package/src/board/fold.ts +1 -1
  37. package/src/board/github.ts +1 -2
  38. package/src/board/gitlab.ts +436 -0
  39. package/src/board/index.ts +1 -0
  40. package/src/board/logo.ts +49 -0
  41. package/src/board/open-file.ts +110 -0
  42. package/src/board/page.ts +57 -5
  43. package/src/board/schema.ts +4 -1
  44. package/src/board/server.ts +87 -3
  45. package/src/board/settings.ts +21 -24
  46. package/src/commands/changelog.command.ts +40 -0
  47. package/src/commands/clean.command.ts +6 -1
  48. package/src/commands/help.command.ts +2 -63
  49. package/src/commands/index.ts +6 -1
  50. package/src/commands/migrate.command.ts +71 -0
  51. package/src/commands/profile.command.ts +1 -1
  52. package/src/commands/runners.command.ts +43 -0
  53. package/src/commands/sync.command.ts +8 -4
  54. package/src/commands/table.ts +362 -0
  55. package/src/commit/check.ts +1 -0
  56. package/src/commit/common/constants.ts +4 -0
  57. package/src/commit/hook.ts +112 -8
  58. package/src/common/constants.ts +11 -9
  59. package/src/common/env-variables.ts +37 -0
  60. package/src/common/index.ts +1 -0
  61. package/src/common/layout-folder.ts +3 -4
  62. package/src/common/record.ts +5 -0
  63. package/src/config/common/constants.ts +28 -22
  64. package/src/config/loader.ts +22 -0
  65. package/src/config/schema.ts +298 -144
  66. package/src/create/add-app.ts +7 -2
  67. package/src/create/add-lib.ts +2 -4
  68. package/src/create/common/constants.ts +5 -3
  69. package/src/create/preset.ts +1 -0
  70. package/src/create/scratch.ts +2 -1
  71. package/src/doctor/checks.ts +277 -448
  72. package/src/doctor/common/constants.ts +27 -19
  73. package/src/doctor/private-values.ts +4 -1
  74. package/src/doctor/runner.ts +5 -12
  75. package/src/doctor/schema.ts +4 -0
  76. package/src/events/common/actor-names.ts +12 -0
  77. package/src/events/common/constants.ts +65 -38
  78. package/src/events/common/index.ts +1 -0
  79. package/src/events/hook.ts +5 -56
  80. package/src/events/text.ts +41 -6
  81. package/src/hooks/command-view.ts +80 -19
  82. package/src/hooks/common/constants.ts +0 -17
  83. package/src/hooks/common/types.ts +11 -24
  84. package/src/hooks/git-queries.ts +113 -0
  85. package/src/hooks/guard-git.ts +76 -24
  86. package/src/hooks/guard-outside.ts +282 -311
  87. package/src/hooks/guard-runner.ts +206 -0
  88. package/src/hooks/guard-writes.ts +84 -183
  89. package/src/hooks/hook-input.ts +57 -0
  90. package/src/hooks/index.ts +3 -6
  91. package/src/hooks/link-makers.ts +315 -0
  92. package/src/hooks/package-runners.ts +268 -0
  93. package/src/hooks/project-guards.ts +29 -40
  94. package/src/hooks/project-tmp.ts +39 -4
  95. package/src/hooks/runner-scan.ts +257 -0
  96. package/src/hooks/script-runners.ts +400 -0
  97. package/src/hooks/session-digest.ts +27 -117
  98. package/src/hooks/shell-folders.ts +760 -0
  99. package/src/hooks/shell-writes.ts +574 -0
  100. package/src/hooks/shell.ts +1421 -194
  101. package/src/hooks/subagent-card.ts +2 -2
  102. package/src/hooks/write-commands.ts +898 -0
  103. package/src/init/scaffold.ts +2 -3
  104. package/src/local/auto-clean.ts +2 -1
  105. package/src/local/browser-socket.ts +33 -0
  106. package/src/local/clean.ts +37 -6
  107. package/src/local/constants.ts +15 -1
  108. package/src/local/index.ts +1 -0
  109. package/src/local/scan.ts +41 -10
  110. package/src/manifest/render.ts +83 -30
  111. package/src/owner/constants.ts +4 -5
  112. package/src/owner/index.ts +0 -2
  113. package/src/owner/profile.ts +1 -0
  114. package/src/owner/schema.ts +51 -27
  115. package/src/owner/survey.ts +0 -3
  116. package/src/owner/view.ts +0 -9
  117. package/src/router.ts +8 -132
  118. package/src/rules/base.ts +12 -7
  119. package/src/rules/index.ts +1 -0
  120. package/src/rules/packs.ts +44 -0
  121. package/src/runners/check.ts +130 -0
  122. package/src/skills/frontmatter.ts +1 -0
  123. package/src/sync/agents-block.ts +104 -0
  124. package/src/sync/base-rules.ts +3 -3
  125. package/src/sync/claude-launch.ts +12 -12
  126. package/src/sync/common/constants.ts +0 -2
  127. package/src/sync/index.ts +1 -1
  128. package/src/sync/local-choice.ts +32 -3
  129. package/src/sync/planner.ts +2 -15
  130. package/src/sync/settings.ts +0 -17
  131. package/src/theme/index.ts +1 -0
  132. package/src/theme/tokens.ts +410 -0
  133. package/src/ui/prompt.ts +1 -0
  134. package/src/visualize/architecture.ts +504 -0
  135. package/src/visualize/assets.ts +41 -30
  136. package/src/visualize/compare-render.ts +22 -24
  137. package/src/visualize/constants.ts +27 -0
  138. package/src/visualize/diagrams.ts +13 -121
  139. package/src/visualize/kinds-render.ts +2 -2
  140. package/src/visualize/kinds-schema.ts +49 -0
  141. package/src/visualize/labels-vi.ts +25 -0
  142. package/src/visualize/labels.ts +2 -0
  143. package/src/visualize/layout.ts +415 -66
  144. package/src/visualize/page.ts +82 -15
  145. package/src/visualize/render.ts +2 -1
  146. package/src/visualize/schema.ts +29 -1
  147. package/src/visualize/sections.ts +78 -9
  148. package/src/visualize/theme.ts +49 -18
  149. package/src/wiki/anchors.ts +1 -0
  150. package/src/wiki/command.ts +10 -3
  151. package/src/wiki/source-links.ts +57 -18
  152. package/base/ci-global.json +0 -13
  153. package/base/claude/remote-hosts.json +0 -15
  154. package/base/hooks/guard-manifest.ts +0 -27
  155. package/base/hooks/guard-package.ts +0 -30
  156. package/base/hooks/guard-remote-hosts.ts +0 -70
  157. package/base/hooks/guard-scripting.ts +0 -32
  158. package/base/hooks/post-tool.ts +0 -37
  159. package/base/hooks/prompt-submit.ts +0 -54
  160. package/base/hooks/stop.ts +0 -40
  161. package/base/skills/build-a-feature/evals/evals.json +0 -29
  162. package/base/skills/docs-update/evals/evals.json +0 -23
  163. package/base/skills/docs-writing/evals/evals.json +0 -17
  164. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  165. package/base/skills/knowledge-sync/SKILL.md +0 -81
  166. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  167. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  168. package/base/skills/plan-a-change/evals/evals.json +0 -47
  169. package/base/skills/report-back/evals/evals.json +0 -23
  170. package/base/skills/research/evals/evals.json +0 -17
  171. package/base/skills/retro/evals/evals.json +0 -17
  172. package/base/skills/review-a-change/evals/evals.json +0 -17
  173. package/base/skills/ship/evals/evals.json +0 -23
  174. package/base/skills/visualize-work/evals/evals.json +0 -17
  175. package/base/templates/ci/github-actions.yml +0 -75
  176. package/base/templates/ci/gitlab-ci.yml +0 -52
  177. package/base/templates/trusted-hosts.local.example +0 -11
  178. package/src/ci/affected.ts +0 -176
  179. package/src/ci/command.ts +0 -166
  180. package/src/ci/common/constants.ts +0 -76
  181. package/src/ci/common/index.ts +0 -2
  182. package/src/ci/common/types.ts +0 -37
  183. package/src/ci/git.ts +0 -72
  184. package/src/ci/global.ts +0 -48
  185. package/src/ci/graph.ts +0 -43
  186. package/src/ci/index.ts +0 -7
  187. package/src/ci/workspace.ts +0 -119
  188. package/src/commands/ci.command.ts +0 -4
  189. package/src/hooks/guard-manifest.ts +0 -109
  190. package/src/hooks/guard-package.ts +0 -226
  191. package/src/hooks/guard-scripting.ts +0 -36
  192. package/src/hooks/host-pattern.ts +0 -17
  193. package/src/hooks/owner-reply.ts +0 -162
  194. package/src/hooks/post-tool.ts +0 -138
  195. package/src/hooks/remote-hosts.ts +0 -1013
  196. package/src/hooks/trusted-scripts.ts +0 -212
  197. package/src/owner/shape.ts +0 -496
  198. package/src/owner/violations.ts +0 -332
  199. package/src/signals/claims.ts +0 -73
  200. package/src/signals/classify.ts +0 -137
  201. package/src/signals/constants.ts +0 -88
  202. package/src/signals/index.ts +0 -5
  203. package/src/signals/loop.ts +0 -48
  204. package/src/signals/state.ts +0 -271
  205. 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 \"$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,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 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"
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 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
  }
@@ -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
 
@@ -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
@@ -27,20 +27,39 @@ try {
27
27
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
28
28
  const { HookDecision } = await import('../../src/hooks/decision.ts');
29
29
  const { GitGuard } = await import('../../src/hooks/guard-git.ts');
30
+ const { RunnerGuard } = await import('../../src/hooks/guard-runner.ts');
30
31
  const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
31
32
  const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
32
33
  const hookCommand = WriteGuard.parseHookCommand({ text });
33
34
  const cwd = hookCommand?.cwd ?? process.cwd();
35
+ const policy = ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
34
36
  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
- : [];
37
+ ? [
38
+ ...GitGuard.inspect({ command: hookCommand.command, cwd, askPush: policy.askPush }),
39
+ ...RunnerGuard.inspect({ command: hookCommand.command, cwd, allow: policy.runnersAllow }),
40
+ ]
41
+ : [
42
+ {
43
+ rule: 'V-W-01',
44
+ message: 'the hook input could not be read, so the command was not checked',
45
+ decision: GuardDecisions.ASK,
46
+ fix: undefined,
47
+ },
48
+ ];
41
49
 
42
50
  if (hits.length > 0) {
43
51
  const denied = hits.some((hit) => hit.decision === GuardDecisions.DENY);
52
+ // A denial the agent can repair says how; one that is the owner's to decide is handed to the owner.
53
+ const fixes = [
54
+ ...new Set(
55
+ hits.flatMap((hit) =>
56
+ hit.decision === GuardDecisions.DENY && hit.fix !== undefined ? [hit.fix] : [],
57
+ ),
58
+ ),
59
+ ];
60
+ const isOwners = hits.some(
61
+ (hit) => hit.decision === GuardDecisions.DENY && hit.fix === undefined,
62
+ );
44
63
 
45
64
  console.log(
46
65
  JSON.stringify(
@@ -52,9 +71,18 @@ try {
52
71
  : 'This command needs a human to confirm:',
53
72
  ...hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
54
73
  '',
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.',
74
+ ...(denied
75
+ ? [
76
+ ...(fixes.length > 0
77
+ ? [`Nothing was run. Write it again: ${fixes.join('; ')}.`]
78
+ : []),
79
+ ...(isOwners || fixes.length === 0
80
+ ? [
81
+ 'Hand the exact command to the owner instead (V-W-06); VULCAN_GUARDS=off switches the guards off for a session.',
82
+ ]
83
+ : []),
84
+ ]
85
+ : ['Confirm only if the owner asked for exactly this.']),
58
86
  ],
59
87
  }),
60
88
  ),
@@ -3,16 +3,21 @@
3
3
  * created outside the project (V-B-08). Stores a package manager, runtime or the agent tool manage
4
4
  * themselves are allowed - a default list, extended by `guard.toolOwnedPaths` in the project config.
5
5
  * `TMPDIR` or `mktemp` pointed at the system temp directory is not allowed.
6
- * It asks by default; `guard.outside: 'deny'` in the project config refuses instead, for agents where an ask can be
7
- * approved unseen. A write into the agent tool scratchpad is always denied.
6
+ * A write outside the project asks by default; `guard.outside: 'deny'` in the project config refuses instead, for agents
7
+ * where an ask can be approved unseen. A write into the agent tool scratchpad is always denied. A part of the call it
8
+ * cannot read (a program or a target named by a variable it cannot resolve, a line it cannot follow to its end) is always
9
+ * DENIED, never asked: the agent can write the call again with a literal path, so a person is not stopped for it, and the
10
+ * reason says how. Literal assignments of the same line (`S=dir; ... > $S/a`, `export X=dir`, `for i in 1 2`) are
11
+ * resolved first, so the usual safe forms are read.
8
12
  *
9
13
  * 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
14
+ * is broken costs more than it protects. So a missing package or `bun` passes (the settings wrapper says so on
15
+ * stderr); a hook input it cannot read ASKS, because nothing was checked and the agent cannot repair that. A guard that started and then failed - a crash or a
12
16
  * 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.
17
+ * manifest that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
18
+ * read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
19
+ * from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
20
+ * VULCAN cannot parse, then changes nothing here.
16
21
  */
17
22
 
18
23
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -28,59 +33,113 @@ try {
28
33
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
29
34
  const { HookDecision } = await import('../../src/hooks/decision.ts');
30
35
  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 });
36
+ const { HookInput } = await import('../../src/hooks/hook-input.ts');
37
+ const { ProjectTmp } = await import('../../src/hooks/project-tmp.ts');
38
+ const { relative } = await import('node:path');
39
+ const input = HookInput.parse({ text });
33
40
 
34
- if (input) {
41
+ if (!input) {
42
+ console.log(
43
+ JSON.stringify(
44
+ HookDecision.buildTool({
45
+ decision: GuardDecisions.ASK,
46
+ reason: [
47
+ 'The hook input could not be read, so this call was not checked for files outside the project (V-B-08).',
48
+ 'Confirm only if the call stays inside the project.',
49
+ ],
50
+ }),
51
+ ),
52
+ );
53
+ } else {
35
54
  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
- }
55
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
56
+ const { toolOwnedPaths, outside } = ProjectGuards.readPolicy({ root: projectRoot });
50
57
 
51
58
  const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
52
59
 
53
60
  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.';
61
+ const read = hits.filter((hit) => !hit.isUnread);
62
+ const isScratchpad = read.some((hit) => hit.isAgentToolScratchpad);
63
+ const linesOf = (list: typeof hits) => list.map((hit) => ` - ${hit.message} (${hit.path})`);
64
+ const tmpFolder = relative(projectRoot, ProjectTmp.projectOf({ root: projectRoot }));
65
+ 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.`;
66
+ const owned =
67
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.';
58
68
 
59
- const isDeny = isScratchpad || outside === GuardDecisions.DENY;
69
+ // A line the check could not read is denied, whatever the project sets: the agent can write it again so that it is read.
70
+ const unreadHits = hits.filter((hit) => hit.isUnread);
71
+ const unread =
72
+ unreadHits.length === 0
73
+ ? []
74
+ : [
75
+ ...(read.length > 0 ? [''] : []),
76
+ 'Part of this call could not be read, so it was not checked for files outside the project (V-B-08):',
77
+ ...linesOf(unreadHits),
78
+ ];
79
+ // A link to a path outside the project is a way to write there with a name inside it: denied, as the agent can copy or link inside.
80
+ const linkHits = read.filter((hit) => hit.isLink === true);
81
+ const isDeny =
82
+ isScratchpad ||
83
+ linkHits.length > 0 ||
84
+ unreadHits.length > 0 ||
85
+ (outside === GuardDecisions.DENY && read.length > 0);
60
86
  let reason: string[];
61
87
 
62
- if (isScratchpad) {
88
+ if (unreadHits.length > 0 && !isScratchpad) {
89
+ reason = [
90
+ 'Part of this call could not be read, so it cannot be checked for files outside the project (V-B-08):',
91
+ ...linesOf(unreadHits),
92
+ ...(read.length > 0
93
+ ? [
94
+ '',
95
+ 'The part that was read would also create files outside the project:',
96
+ ...linesOf(read),
97
+ ]
98
+ : []),
99
+ '',
100
+ `Nothing was run. Write it again so the guard can read it: a literal path in every redirect (no $VAR or $(...) in a target; after a cd the guard cannot work out, an absolute path), a cd to a literal folder, the folder assigned on the same line (S=${tmpFolder}/x; ... > "$S/a") or named by a for loop over literal words; or put the script in a file under ${tmpFolder}/<task>/ and run it by that literal path (bun ${tmpFolder}/<task>/step.ts), with literal paths inside the project in its own redirects too: the guard does not read the script. ${places}`,
101
+ owned,
102
+ ];
103
+ } else if (isScratchpad) {
63
104
  reason = [
64
105
  'This would write into the scratchpad folder the agent tool offers (V-B-08):',
65
- ...hitLines,
106
+ ...linesOf(read),
107
+ ...unread,
66
108
  '',
67
109
  `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
110
  ];
111
+ } else if (linkHits.length > 0) {
112
+ reason = [
113
+ 'This would hard-link a path outside the project (V-B-08); a hard link cannot be told from the file, so a write through it changes that path later too:',
114
+ ...linesOf(linkHits),
115
+ ...(read.length > linkHits.length
116
+ ? [
117
+ '',
118
+ 'It would also create files outside the project:',
119
+ ...linesOf(read.filter((hit) => hit.isLink !== true)),
120
+ ]
121
+ : []),
122
+ '',
123
+ `Nothing was run. Copy the file into the project (cp) instead of linking it, link a path inside the project, or make a symbolic link (ln -s), which is read once it exists. ${places}`,
124
+ owned,
125
+ ];
69
126
  } else if (isDeny) {
70
127
  reason = [
71
128
  'This would create files outside the project (V-B-08), and this project denies it (guard.outside):',
72
- ...hitLines,
129
+ ...linesOf(read),
130
+ ...unread,
73
131
  '',
74
132
  `Nothing was written. ${places}`,
75
- 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
133
+ owned,
76
134
  ];
77
135
  } else {
78
136
  reason = [
79
137
  'This would create files outside the project (V-B-08):',
80
- ...hitLines,
138
+ ...linesOf(read),
139
+ ...unread,
81
140
  '',
82
141
  `${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.*.',
142
+ owned,
84
143
  ];
85
144
  }
86
145