@venizia/vulcan 0.4.10-2 → 0.4.10-21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -1,6 +1,8 @@
1
1
  import { existsSync, readdirSync, readFileSync } from 'node:fs';
2
2
  import { join, relative, resolve } from 'node:path';
3
3
  import { GitFiles } from '../common/git-files.ts';
4
+ import { LayoutFolder, LayoutKeys } from '../common/layout-folder.ts';
5
+ import type { ILayout } from '../common/layout-folder.ts';
4
6
  import { TextValue } from '../common/text.ts';
5
7
  import { WikiDefaults } from './constants.ts';
6
8
 
@@ -12,16 +14,44 @@ import { WikiDefaults } from './constants.ts';
12
14
  * value (checked only under `.agents/knowledge`). `git ls-files` is the truth, not the disk: a
13
15
  * gitignored artifact is not on GitHub.
14
16
  */
15
- const SOURCE_ROOTS = ['packages/', 'examples/', 'scripts/', 'docs/', '.agents/'];
16
17
  const SOURCE_EXTENSIONS = ['ts', 'tsx', 'md', 'json', 'mjs', 'js', 'yaml', 'yml'];
17
18
  const RESOURCE_LINE_PATTERN = /^resource:\s*(.+)$/;
18
19
  const LINE_SUFFIX_PATTERN = /(:\d+|#L\d+)$/;
19
20
 
20
- // `{}` and `*` mark a template or a glob and `<>` a placeholder, never one real file.
21
- const BACKTICK_PATTERN = new RegExp(
22
- `\`((?:${SOURCE_ROOTS.map((root) => TextValue.escapeLiteral({ text: root })).join('|')})[^\`{}*<>]+?\\.(?:${SOURCE_EXTENSIONS.join('|')})(?::\\d+|#L\\d+)?)\``,
23
- 'g',
24
- );
21
+ /**
22
+ * The folders whose paths the check holds to git: where a project's source lives. With a `layout` they are the layout's
23
+ * folders (backend, frontend, shared, other) and the folders every project has; without one, the list VULCAN's own
24
+ * repository uses.
25
+ */
26
+ export class SourceRoots {
27
+ /** The folders every project has: its docs, its scripts and its agent files. */
28
+ static readonly FIXED = ['docs/', 'scripts/', '.agents/'];
29
+ /** What the check reads when the config has no layout. */
30
+ static readonly DEFAULT = ['packages/', 'examples/', ...SourceRoots.FIXED];
31
+
32
+ /** Each root ends with `/`. A layout folder the config would refuse is left out, and so is a repeat. */
33
+ static of(opts: { layout?: ILayout }): string[] {
34
+ const folders = LayoutKeys.ALL.flatMap((key) =>
35
+ LayoutFolder.valid({ value: opts.layout?.[key] }),
36
+ );
37
+
38
+ if (folders.length === 0) {
39
+ return SourceRoots.DEFAULT;
40
+ }
41
+
42
+ return [...new Set([...folders.map((folder) => `${folder}/`), ...SourceRoots.FIXED])];
43
+ }
44
+
45
+ /** A backticked path under a root. `{}` and `*` mark a template or a glob and `<>` a placeholder, never one real file. */
46
+ static backtickPatternOf(opts: { roots: string[] }): RegExp {
47
+ const roots = opts.roots.map((root) => TextValue.escapeLiteral({ text: root })).join('|');
48
+
49
+ return new RegExp(
50
+ `\`((?:${roots})[^\`{}*<>]+?\\.(?:${SOURCE_EXTENSIONS.join('|')})(?::\\d+|#L\\d+)?)\``,
51
+ 'g',
52
+ );
53
+ }
54
+ }
25
55
 
26
56
  export interface IMissingSourceLink {
27
57
  file: string;
@@ -74,7 +104,12 @@ const walkMarkdown = (opts: { directory: string }): string[] => {
74
104
  });
75
105
  };
76
106
 
77
- const extractPaths = (opts: { text: string; repo: string; skipProse: boolean }): string[] => {
107
+ const extractPaths = (opts: {
108
+ text: string;
109
+ repo: string;
110
+ skipProse: boolean;
111
+ pattern: RegExp;
112
+ }): string[] => {
78
113
  const github = new RegExp(
79
114
  `${TextValue.escapeLiteral({ text: opts.repo })}/(?:blob|tree)/main/([^\\s)\\]"'\`<>]+)`,
80
115
  'g',
@@ -87,7 +122,7 @@ const extractPaths = (opts: { text: string; repo: string; skipProse: boolean }):
87
122
  return found;
88
123
  }
89
124
 
90
- const prose = [...opts.text.matchAll(BACKTICK_PATTERN)].map((match) =>
125
+ const prose = [...opts.text.matchAll(opts.pattern)].map((match) =>
91
126
  (match[1] ?? '').replace(LINE_SUFFIX_PATTERN, ''),
92
127
  );
93
128
 
@@ -95,8 +130,11 @@ const extractPaths = (opts: { text: string; repo: string; skipProse: boolean }):
95
130
  };
96
131
 
97
132
  /** The `resource:` line of a concept's frontmatter, or none when it has no tracked prefix. */
98
- const extractResource = (opts: { lines: string[] }): { line: number; path: string } | undefined => {
99
- const { lines } = opts;
133
+ const extractResource = (opts: {
134
+ lines: string[];
135
+ roots: string[];
136
+ }): { line: number; path: string } | undefined => {
137
+ const { lines, roots } = opts;
100
138
 
101
139
  if (lines[0] !== '---') {
102
140
  return undefined;
@@ -115,11 +153,7 @@ const extractResource = (opts: { lines: string[] }): { line: number; path: strin
115
153
  .replace(/^["']|["']$/g, '')
116
154
  .replace(/\/+$/, '');
117
155
 
118
- if (
119
- value !== undefined &&
120
- value !== '' &&
121
- SOURCE_ROOTS.some((root) => value.startsWith(root))
122
- ) {
156
+ if (value !== undefined && value !== '' && roots.some((root) => value.startsWith(root))) {
123
157
  return { line: index + 1, path: value };
124
158
  }
125
159
  }
@@ -130,7 +164,8 @@ const extractResource = (opts: { lines: string[] }): { line: number; path: strin
130
164
  export class SourceLinkCheck {
131
165
  /**
132
166
  * Walks the `.md` files under `directories` (paths relative to `root`) and reports every source path
133
- * that git does not track. `skipFiles` are generated pages that are never held to the gate.
167
+ * that git does not track. `skipFiles` are generated pages that are never held to the gate. `roots` are the
168
+ * folders a path must start with to be checked (`SourceRoots.of`); the default list when left out.
134
169
  */
135
170
  static check(opts: {
136
171
  root: string;
@@ -138,8 +173,12 @@ export class SourceLinkCheck {
138
173
  directories: string[];
139
174
  skipProseUnder: string[];
140
175
  skipFiles: string[];
176
+ roots?: string[];
141
177
  }): { checked: number; missing: IMissingSourceLink[] } {
142
178
  const { root, repo, skipFiles, skipProseUnder } = opts;
179
+ const roots =
180
+ opts.roots === undefined || opts.roots.length === 0 ? SourceRoots.DEFAULT : opts.roots;
181
+ const pattern = SourceRoots.backtickPatternOf({ roots });
143
182
  const tracked = loadTracked({ root });
144
183
  const exists = (path: string): boolean =>
145
184
  tracked.files.has(path) || tracked.directories.has(path);
@@ -157,7 +196,7 @@ export class SourceLinkCheck {
157
196
  const skipProse = skipProseUnder.some((skip) => isUnder({ path, directory: skip }));
158
197
  const lines = readFileSync(file, 'utf8').split('\n');
159
198
  const resource = isUnder({ path, directory: WikiDefaults.KNOWLEDGE_DIRECTORY })
160
- ? extractResource({ lines })
199
+ ? extractResource({ lines, roots })
161
200
  : undefined;
162
201
 
163
202
  if (resource !== undefined) {
@@ -169,7 +208,7 @@ export class SourceLinkCheck {
169
208
  }
170
209
 
171
210
  for (const [index, text] of lines.entries()) {
172
- for (const found of extractPaths({ text, repo, skipProse })) {
211
+ for (const found of extractPaths({ text, repo, skipProse, pattern })) {
173
212
  checked += 1;
174
213
 
175
214
  if (!exists(found)) {
@@ -1,13 +0,0 @@
1
- {
2
- "files": [
3
- "bun.lock",
4
- "bun.lockb",
5
- "package.json",
6
- "bunfig.toml",
7
- "tsconfig*.json",
8
- ".configs/**",
9
- ".github/workflows/**",
10
- ".gitlab-ci.yml",
11
- ".gitlab/**"
12
- ]
13
- }
@@ -1,15 +0,0 @@
1
- {
2
- "hooks": {
3
- "PreToolUse": [
4
- {
5
- "matcher": "Bash",
6
- "hooks": [
7
- {
8
- "type": "command",
9
- "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-remote-hosts.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -f \"$f\" ] || echo \"vulcan: the guard-remote-hosts hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-remote-hosts hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
10
- }
11
- ]
12
- }
13
- ]
14
- }
15
- }
@@ -1,27 +0,0 @@
1
- /**
2
- * PreToolUse hook on Write, Edit, MultiEdit, NotebookEdit and Bash: refuses a write to
3
- * .agents/vulcan.manifest.json. The file is rendered from the config by `vulcan sync`, so a hand
4
- * edit is either lost on the next sync or hides a config change from the doctor.
5
- *
6
- * Unlike guard-writes it denies rather than asks, and it fails closed for the same reason: Claude
7
- * Code blocks a PreToolUse call only on exit 2, so a hook that throws would let every write through.
8
- * The modules load inside the try for that reason.
9
- */
10
-
11
- // A module, so the awaits below are top-level; it has no static import, by design.
12
- export {};
13
-
14
- try {
15
- const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
16
- const stdin = await Bun.stdin.text();
17
- const input = ManifestGuard.parseHookInput({ text: stdin });
18
-
19
- if (input && ManifestGuard.inspectWrite({ input })) {
20
- console.log(JSON.stringify(ManifestGuard.buildDecision()));
21
- }
22
- } catch (error) {
23
- console.error(
24
- `vulcan: the guard-manifest hook failed (${error instanceof Error ? error.message : String(error)}) - blocked; run bun install`,
25
- );
26
- process.exit(2);
27
- }
@@ -1,30 +0,0 @@
1
- /**
2
- * PreToolUse hook on Write: a new package.json inside a backend, frontend or shared folder is the
3
- * start of a hand-made app or library. When the project recorded a preset that makes it, the call
4
- * is denied with the exact `vulcan add` command; with no preset behind the folder it only adds a
5
- * note, because a block with no command to offer would leave the agent stuck.
6
- *
7
- * Reads only the generated manifest; an existing file, node_modules, or a folder outside the
8
- * layout passes silently. It fails closed like the other guards: Claude Code blocks a PreToolUse
9
- * call only on exit 2, so the modules load inside the try.
10
- */
11
-
12
- // A module, so the awaits below are top-level; it has no static import, by design.
13
- export {};
14
-
15
- try {
16
- const { PackageGuard } = await import('../../src/hooks/guard-package.ts');
17
- const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
18
- const stdin = await Bun.stdin.text();
19
- const input = ManifestGuard.parseHookInput({ text: stdin });
20
- const verdict = input && PackageGuard.inspectWrite({ input });
21
-
22
- if (verdict) {
23
- console.log(JSON.stringify(PackageGuard.buildDecision({ verdict })));
24
- }
25
- } catch (error) {
26
- console.error(
27
- `vulcan: the guard-package hook failed (${error instanceof Error ? error.message : String(error)}) - blocked; run bun install`,
28
- );
29
- process.exit(2);
30
- }
@@ -1,70 +0,0 @@
1
- /**
2
- * PreToolUse hook on Bash: asks before a command reaches a host the project has not listed in
3
- * `remoteHosts` (trusted, or readOnly for the strict read-only forms). The policy is read from the
4
- * committed manifest, `.agents/vulcan.manifest.json`, plus the personal list `remoteHosts.localFile`: one host per
5
- * line is trusted, `readonly: <host>` is a read-only host, and a line that is not a host name or a `*` pattern is
6
- * skipped (said once on stderr) and never trusted.
7
- *
8
- * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so every error here - a missing
9
- * module, a manifest without the policy - exits 2. The modules load inside the try for that reason.
10
- */
11
-
12
- // A module, so the awaits below are top-level; it has no static import, by design.
13
- export {};
14
-
15
- try {
16
- const { RemoteHosts } = await import('../../src/hooks/remote-hosts.ts');
17
- const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
18
- const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
19
- const manifestFile = Bun.file(`${root}/.agents/vulcan.manifest.json`);
20
-
21
- const manifestExists = await manifestFile.exists();
22
-
23
- if (!manifestExists) {
24
- throw new Error('.agents/vulcan.manifest.json is missing - run vulcan sync');
25
- }
26
-
27
- const manifest = await manifestFile.json();
28
- const remoteHosts = manifest?.remoteHosts;
29
-
30
- if (typeof remoteHosts !== 'object' || remoteHosts === null) {
31
- throw new Error('the manifest has no remoteHosts - run vulcan sync');
32
- }
33
-
34
- const localFile = typeof remoteHosts.localFile === 'string' ? remoteHosts.localFile : undefined;
35
- const local = localFile === undefined ? undefined : Bun.file(`${root}/${localFile}`);
36
- const localExists = await local?.exists();
37
- const readingPersonal = localExists === true ? local?.text() : undefined;
38
- const personalText = await readingPersonal;
39
- const personal = RemoteHosts.parsePersonalList({ text: personalText ?? '' });
40
- const trusted: string[] = Array.isArray(remoteHosts.trusted) ? remoteHosts.trusted : [];
41
- const readOnly: string[] = Array.isArray(remoteHosts.readOnly) ? remoteHosts.readOnly : [];
42
- const stdin = await Bun.stdin.text();
43
-
44
- if (personal.skipped.length > 0) {
45
- console.error(
46
- `vulcan: the guard-remote-hosts hook skipped lines ${personal.skipped.join(', ')} of ${localFile}: not a host name or a * pattern, so they trust nothing`,
47
- );
48
- }
49
-
50
- const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
51
- const hits = hookCommand
52
- ? RemoteHosts.inspectCommand({
53
- command: hookCommand.command,
54
- policy: {
55
- trusted: [...trusted, ...personal.trusted],
56
- readOnly: [...readOnly, ...personal.readOnly],
57
- ...(localFile === undefined ? {} : { localFile }),
58
- },
59
- })
60
- : [{ rule: 'remote-hosts', message: 'the hook input could not be read' }];
61
-
62
- if (hits.length > 0) {
63
- console.log(JSON.stringify(RemoteHosts.buildDecision({ hits })));
64
- }
65
- } catch (error) {
66
- console.error(
67
- `vulcan: the guard-remote-hosts hook failed (${error instanceof Error ? error.message : String(error)}) - blocked`,
68
- );
69
- process.exit(2);
70
- }
@@ -1,32 +0,0 @@
1
- /**
2
- * PreToolUse hook on Bash: when the command runs python, python3 or pip (read with the shell parser of
3
- * guard-git, so a message or an argument that only mentions python is not one) it adds one line to the
4
- * model's context - agent scripting uses bun by default, another language is fine when the task needs
5
- * it (V-B-09) - and lets the call through. It never asks and never blocks.
6
- *
7
- * It fails OPEN: a reminder is not worth a stopped session. Input it cannot read, a missing module or an
8
- * internal error pass the call with a note on stderr. `VULCAN_GUARDS=off` switches it off, read before
9
- * anything is imported. It imports only the modules it needs - no config, no zod.
10
- */
11
-
12
- // A module, so the awaits below are top-level; it has no static import, by design.
13
- export {};
14
-
15
- if (process.env.VULCAN_GUARDS === 'off') {
16
- process.exit(0);
17
- }
18
-
19
- try {
20
- const { ScriptingGuard } = await import('../../src/hooks/guard-scripting.ts');
21
- const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
22
- const stdin = await Bun.stdin.text();
23
- const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
24
-
25
- if (hookCommand && ScriptingGuard.inspect({ command: hookCommand.command }).length > 0) {
26
- console.log(JSON.stringify(ScriptingGuard.buildAdvice()));
27
- }
28
- } catch (error) {
29
- console.error(
30
- `vulcan: the guard-scripting hook failed (${error instanceof Error ? error.message : String(error)}) - the call passes; run bun install`,
31
- );
32
- }
@@ -1,37 +0,0 @@
1
- /**
2
- * PostToolUse and PostToolUseFailure hook: keeps small notes about the turn for the Stop check (was public
3
- * state probed, did the last gate pass) and tells the model when it seems stuck - the same call three times,
4
- * two calls alternating, one tool failing again and again - or when it just changed a skill or a rules file.
5
- * It never blocks and it fails OPEN. It imports only the signals module: no config, no zod, because it runs
6
- * after every tool call. `VULCAN_GUARDS=off` switches it off, read before anything is imported.
7
- */
8
-
9
- // A module, so the awaits below are top-level; it has no static import, by design.
10
- export {};
11
-
12
- if (process.env.VULCAN_GUARDS === 'off') {
13
- process.exit(0);
14
- }
15
-
16
- try {
17
- const { PostToolOutput } = await import('../../src/hooks/post-tool.ts');
18
- const stdin = await Bun.stdin.text();
19
- const output = PostToolOutput.build({
20
- projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
21
- input: JSON.parse(stdin),
22
- });
23
-
24
- if (output !== undefined) {
25
- console.log(JSON.stringify(output));
26
- }
27
- } catch (error) {
28
- // Input that is not JSON is not echoed: Bun's parse error quotes it.
29
- const reason =
30
- error instanceof SyntaxError
31
- ? 'unreadable input'
32
- : error instanceof Error
33
- ? error.message
34
- : String(error);
35
-
36
- console.error(`vulcan: the post-tool hook failed (${reason}) - the call is unaffected`);
37
- }
@@ -1,54 +0,0 @@
1
- /**
2
- * UserPromptSubmit hook: adds one line to the prompt while the owner's report shape is held - the
3
- * contract, and the faults of the previous reply when it had any. Nothing is added when the shape is not
4
- * enforced. It never blocks a prompt: any failure prints a note and the prompt goes through.
5
- * `VULCAN_GUARDS=off` switches it off, read before anything is imported.
6
- * `VULCAN_OWNER_REPLY=off` exempts a session whose reader is an agent; the check is made in the builder.
7
- */
8
-
9
- // A module, so the awaits below are top-level; it has no static import, by design.
10
- export {};
11
-
12
- if (process.env.VULCAN_GUARDS === 'off') {
13
- process.exit(0);
14
- }
15
-
16
- try {
17
- const { OwnerReply } = await import('../../src/hooks/owner-reply.ts');
18
- let session = '';
19
-
20
- try {
21
- const stdin = await Bun.stdin.text();
22
- const event: unknown = JSON.parse(stdin);
23
-
24
- if (
25
- typeof event === 'object' &&
26
- event !== null &&
27
- 'session_id' in event &&
28
- typeof event.session_id === 'string'
29
- ) {
30
- session = event.session_id;
31
- }
32
- } catch {
33
- // No readable event: the turn is noted for no session, and nothing is echoed.
34
- }
35
-
36
- const line = await OwnerReply.buildPromptContract({
37
- projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
38
- session,
39
- });
40
-
41
- if (line !== '') {
42
- console.log(line);
43
- }
44
- } catch (error) {
45
- // Input that is not JSON is not echoed: Bun's parse error quotes it, and it can hold the reply.
46
- const reason =
47
- error instanceof SyntaxError
48
- ? 'unreadable input'
49
- : error instanceof Error
50
- ? error.message
51
- : String(error);
52
-
53
- console.error(`vulcan: the prompt-submit hook failed (${reason}) - the prompt goes through`);
54
- }
@@ -1,40 +0,0 @@
1
- /**
2
- * Stop hook: checks the reply that just ended against the owner's report shape (src/owner/shape.ts) and
3
- * records its faults by class and date, never the text. Under `enforce: block` a structural fault sends
4
- * the reply back once to be restated; otherwise it only logs, and the next prompt's contract names it.
5
- *
6
- * It fails OPEN: a Stop hook runs after the message is on screen, and one that fails must not hold a
7
- * session. Input it cannot read, a missing module or an internal error pass with a note on stderr.
8
- * `VULCAN_GUARDS=off` switches it off, read before anything is imported.
9
- * `VULCAN_OWNER_REPLY=off` exempts a session whose reader is an agent; the check is made in the builder.
10
- */
11
-
12
- // A module, so the awaits below are top-level; it has no static import, by design.
13
- export {};
14
-
15
- if (process.env.VULCAN_GUARDS === 'off') {
16
- process.exit(0);
17
- }
18
-
19
- try {
20
- const { OwnerReply } = await import('../../src/hooks/owner-reply.ts');
21
- const stdin = await Bun.stdin.text();
22
- const output = await OwnerReply.buildStopOutput({
23
- projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
24
- input: JSON.parse(stdin),
25
- });
26
-
27
- if (output !== undefined) {
28
- console.log(JSON.stringify(output));
29
- }
30
- } catch (error) {
31
- // Input that is not JSON is not echoed: Bun's parse error quotes it, and it can hold the reply.
32
- const reason =
33
- error instanceof SyntaxError
34
- ? 'unreadable input'
35
- : error instanceof Error
36
- ? error.message
37
- : String(error);
38
-
39
- console.error(`vulcan: the stop hook failed (${reason}) - the reply passes`);
40
- }
@@ -1,29 +0,0 @@
1
- {
2
- "skill_name": "build-a-feature",
3
- "evals": [
4
- {
5
- "id": 0,
6
- "prompt": "If I want to implement a feature with you, what will you do with me? Which skill or workflow do you use?",
7
- "expected_output": "Calls atlas search for how a feature is built in this project and atlas presets before its first answer; opens with one quoted hit and the preset list (the frontend preset included); then describes the workflow, naming the atlas call at each step it depends on; claims no lookup it has not made; nothing is written or committed",
8
- "files": [".agents/vulcan.manifest.json"]
9
- },
10
- {
11
- "id": 1,
12
- "prompt": "Add a GET endpoint that returns the server time to the first backend app. Propose the surface first; do not write code yet.",
13
- "expected_output": "Calls atlas search for how a controller and a route are written here and get on the hits; proposes the route, its response schema and the controller and method names, each convention backed by the atlas hit it came from; waits for approval; no source file changed",
14
- "files": [".agents/vulcan.manifest.json"]
15
- },
16
- {
17
- "id": 2,
18
- "prompt": "We need a second backend app named billing and a shared library named money. Set them up.",
19
- "expected_output": "Calls atlas presets, then runs the exact vulcan add commands it returned (an app with --app billing, a library with --lib money); never hand-writes a package.json, a tsconfig or scripts; runs the new packages' checks and vulcan doctor; nothing committed",
20
- "files": [".agents/vulcan.manifest.json"]
21
- },
22
- {
23
- "id": 3,
24
- "prompt": "Add an endpoint that lists the products under a price. Walk me through it.",
25
- "expected_output": "Asks its open decisions in one numbered round with a recommended answer each (filter shape, sorting, paging, empty result) and looks up the conventions in atlas instead of asking; proposes the route, schemas and class names with the seams to test; plans vertical slices starting with the simplest end-to-end path; writes no code before the user approves",
26
- "files": [".agents/vulcan.manifest.json"]
27
- }
28
- ]
29
- }
@@ -1,23 +0,0 @@
1
- {
2
- "skill_name": "docs-update",
3
- "evals": [
4
- {
5
- "id": 0,
6
- "prompt": "I changed how one of our packages behaves - see the uncommitted diff, or the last commit if the tree is clean. Update the docs to match and add the changelog entry. Do not commit.",
7
- "expected_output": "Reads knowledge.wiki, knowledge.changelogs and packages[].path from .agents/vulcan.manifest.json; reads the changed source itself; edits the existing page that owns the topic instead of opening a duplicate; writes a YYYY-MM-DD-<slug>.md entry from the changelog template whose packages: list carries the npm names it covers; runs vulcan doctor, okf check --strict and the docs build it discovered, looping until all pass; nothing committed",
8
- "files": [".agents/vulcan.manifest.json"]
9
- },
10
- {
11
- "id": 1,
12
- "prompt": "Add a changelog entry for last week's change to the repository's CI and release tooling. It touches no package. Do not commit.",
13
- "expected_output": "Writes no changelog entry: CI and release tooling is internal work that touches no package and affects no user of the published packages, and the changelog records only what affects users; says so in one line and names what would need an entry (a feature, a changed behaviour, a fix a user could hit, a security fix, a removal); changes no file; nothing committed",
14
- "files": [".agents/vulcan.manifest.json"]
15
- },
16
- {
17
- "id": 2,
18
- "prompt": "The docs for the first package in .agents/vulcan.manifest.json are out of date. Refresh them against the current source. No changelog entry - nothing shipped. Do not commit.",
19
- "expected_output": "Finds the page or README that owns that package (under knowledge.wiki, or <packages[].path>/README.md when the manifest has no wiki); verifies every name, signature and default against the source under packages[].path and fixes each drift; creates no new page and no changelog entry; runs the gates; reports each claim that changed with its source file; nothing committed",
20
- "files": [".agents/vulcan.manifest.json"]
21
- }
22
- ]
23
- }
@@ -1,17 +0,0 @@
1
- {
2
- "skill_name": "docs-writing",
3
- "evals": [
4
- {
5
- "id": 0,
6
- "prompt": "The page docs/wiki/content/guides/get-started/philosophy.md in the IGNIS repo is 670 lines and exhausting to read. Rewrite it so a first-time reader understands what IGNIS is and why it exists after one read. Keep every real fact. Save the rewritten page to the output path given - do NOT edit the original file.",
7
- "expected_output": "A drastically shorter, scannable concept page: purpose stated in the first screen, short sentences, no essay walls, options/comparisons in tables, why-content bounded",
8
- "files": ["docs/wiki/content/guides/get-started/philosophy.md"]
9
- },
10
- {
11
- "id": 1,
12
- "prompt": "The page docs/wiki/content/best-practices/error-handling.md in the IGNIS repo is 599 lines and very dense. Rewrite it so a developer can find and apply the right error-handling pattern quickly. Keep every real fact and code sample that matters. Save the rewritten page to the output path given - do NOT edit the original file.",
13
- "expected_output": "A task-oriented page: happy path first, patterns as short recipes, edge cases separated, sentences under 20 words, tables for enumerable facts",
14
- "files": ["docs/wiki/content/best-practices/error-handling.md"]
15
- }
16
- ]
17
- }
@@ -1,17 +0,0 @@
1
- {
2
- "skill_name": "fix-a-bug",
3
- "evals": [
4
- {
5
- "id": 0,
6
- "prompt": "A function in this repository sometimes returns the wrong value for one input and I do not know why. Find and fix it.",
7
- "expected_output": "Builds and runs a red-capable, deterministic, fast command that reproduces the failure before any theory; minimises it; lists three to five ranked falsifiable hypotheses and shows them; changes one variable at a time; writes a regression test that is red before the fix and green after; removes any tagged debug output; says what was ruled out; commits nothing",
8
- "files": []
9
- },
10
- {
11
- "id": 1,
12
- "prompt": "The page renders blank on a phone but fine on my laptop. Fix it.",
13
- "expected_output": "Reproduces the bug in a real browser at a mobile width before reading code for a cause; builds a loop an agent can rerun; does not guess a cause first; writes the regression check at a seam that reproduces the real pattern, or says plainly that no correct seam exists",
14
- "files": []
15
- }
16
- ]
17
- }
@@ -1,81 +0,0 @@
1
- ---
2
- name: knowledge-sync
3
- description: "Use when asked to sync, refresh or audit the knowledge bundle (the project's okf concepts) against the source code: after a refactor, before a release, on a schedule, or when a concept may be stale. Checks each concept whose code changed (delta) or all of them (full) and applies the confirmed fixes. Skip for writing a new knowledge page for a feature you just built (build-a-feature), updating the wiki or changelog (docs-update), and general documentation."
4
- user-invocable: true
5
- allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, Workflow
6
- ---
7
-
8
- # Knowledge sync
9
-
10
- The generated layer (`vulcan x okf gen`) heals itself; curated concepts stay true only when someone
11
- re-reads the code. Code is ground truth - never fix a concept from docs, `AGENTS.md` or memory. Every
12
- finding cites a `file:line` witness. Nothing is committed: the user reviews the diff.
13
-
14
- This skill is the periodic audit, run when asked or on a schedule - not once per change. The facts a
15
- single change alters are updated by the change itself (`build-a-feature` step 7).
16
-
17
- ## Requirements
18
-
19
- - Bun, git, and `@venizia/vulcan` installed in the project (`bun x --no-install vulcan`).
20
- - The Workflow tool, for the fan-out in Step 3.
21
-
22
- ## Checklist
23
-
24
- Copy it into your reply and tick it off:
25
-
26
- ```
27
- - [ ] 1. Prerequisites hold
28
- - [ ] 2. Baseline: gen, check, last sync, changed areas
29
- - [ ] 3. Targets built, workflow run
30
- - [ ] 4. Gaps decided
31
- - [ ] 5. Gates green (loop until they are)
32
- - [ ] 6. Reported
33
- ```
34
-
35
- ## 1. Prerequisites
36
-
37
- 1. `bun x --no-install vulcan doctor` passes - the manifest is fresh. Fix what it names first.
38
- 2. Read `.agents/vulcan.manifest.json`: `knowledge.bundle` (the bundle), `packages[].path` (the code
39
- areas), `knowledge.syncAreas` (the area map, optional), `name` (the brand, upper case).
40
-
41
- ## 2. Baseline
42
-
43
- 1. `bun x --no-install vulcan x okf gen`, then `vulcan x okf check --strict` - it must pass before
44
- anything else, so no verifier chases a fact `gen` fixes.
45
- 2. Anchor the last sync by commit, never by date: the last commit that touched the bundle,
46
- `LAST_SYNC=$(git log -1 --format=%H -- <bundle>)`, and its date `SINCE=$(git log -1 --format=%cs -- <bundle>)`
47
- (a label for the workflow). The user may name another commit or date instead - use theirs. Empty:
48
- no sync yet - run `full`, or anchor on the commit that added `<bundle>/index.md`. A bare
49
- `--since=<date>` is wrong: git reads today's date as "now" and returns nothing.
50
- 3. Changed areas: `git log $LAST_SYNC..HEAD --no-merges --name-only --format= -- <package paths> Makefile make/ scripts/ .github/`,
51
- plus `git diff HEAD --stat` for uncommitted code. Commits that touch only the bundle or `docs/` are
52
- knowledge maintenance, not drift.
53
- 4. Delta mode, nothing changed: report "already in sync", run Step 5's gates, stop.
54
-
55
- ## 3. Targets and the workflow
56
-
57
- Mode: `delta` by default; `full` when asked (monthly, quarterly, "full") or when the last commit
58
- that touched the bundle (`SINCE`) is over 30 days old. Build the targets and run the workflow as
59
- [references/workflow.md](references/workflow.md) describes - one target per changed area, from the
60
- area map when the project has one, else from each concept's `resource`.
61
-
62
- ## 4. Gaps
63
-
64
- For each gap the critics propose: durable, load-bearing, and no existing home? Create the concept -
65
- copy frontmatter, voice and length from 2-3 siblings, verify every claim in source, link it from
66
- `index.md`. A gap that is really one fact in several files: make one file its home, the rest point
67
- to it. Never lose a unique fact.
68
-
69
- ## 5. Gates - validate, fix, repeat
70
-
71
- 1. `vulcan x okf gen`
72
- 2. `vulcan x okf check --strict`
73
- 3. `vulcan x okf coverage --min 100` - structural coverage stays at 100%.
74
-
75
- A gate that fails: fix what it names, run all three again. Stop only when all three pass.
76
-
77
- ## 6. Report
78
-
79
- Report in the user's language: gate status and scale first (findings applied, files, claims
80
- confirmed), then each notable correction (was -> is, with its witness), new or merged concepts, and
81
- anything an applier skipped, with the reason. Do not commit.