@venizia/vulcan 0.4.0 → 0.4.1

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 (141) hide show
  1. package/base/claude/remote-hosts.json +1 -1
  2. package/base/claude/settings.json +75 -3
  3. package/base/hooks/guard-git.ts +55 -0
  4. package/base/hooks/guard-manifest.ts +1 -1
  5. package/base/hooks/guard-outside.ts +66 -0
  6. package/base/hooks/guard-package.ts +3 -2
  7. package/base/hooks/guard-remote-hosts.ts +3 -2
  8. package/base/hooks/guard-writes.ts +1 -1
  9. package/base/hooks/post-tool.ts +36 -0
  10. package/base/hooks/prompt-submit.ts +52 -0
  11. package/base/hooks/stop.ts +38 -0
  12. package/base/hooks/subagent-start.ts +18 -0
  13. package/base/references/delegation-brief.md +63 -0
  14. package/base/references/design-pass.md +39 -0
  15. package/base/references/evidence.md +36 -0
  16. package/base/references/phase-boundaries.md +20 -0
  17. package/base/references/testing.md +89 -0
  18. package/base/rules.md +11 -2
  19. package/base/skills/build-a-feature/SKILL.md +49 -23
  20. package/base/skills/docs-update/SKILL.md +12 -1
  21. package/base/skills/docs-writing/SKILL.md +2 -2
  22. package/base/skills/docs-writing/references/agent-documents.md +53 -0
  23. package/base/skills/fix-a-bug/SKILL.md +84 -0
  24. package/base/skills/fix-a-bug/evals/evals.json +17 -0
  25. package/base/skills/knowledge-sync/SKILL.md +4 -1
  26. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
  27. package/base/skills/plan-a-change/SKILL.md +95 -0
  28. package/base/skills/plan-a-change/evals/evals.json +23 -0
  29. package/base/skills/plan-a-change/references/spec-card.md +39 -0
  30. package/base/skills/report-back/SKILL.md +112 -0
  31. package/base/skills/report-back/evals/evals.json +23 -0
  32. package/base/skills/research/SKILL.md +64 -0
  33. package/base/skills/research/evals/evals.json +17 -0
  34. package/base/skills/retro/SKILL.md +69 -0
  35. package/base/skills/retro/evals/evals.json +17 -0
  36. package/base/skills/review-a-change/SKILL.md +90 -0
  37. package/base/skills/review-a-change/evals/evals.json +17 -0
  38. package/base/skills/ship/SKILL.md +82 -0
  39. package/base/skills/ship/evals/evals.json +23 -0
  40. package/base/skills/visualize-work/SKILL.md +87 -0
  41. package/base/skills/visualize-work/evals/evals.json +17 -0
  42. package/base/skills/visualize-work/references/spec.md +65 -0
  43. package/package.json +3 -3
  44. package/src/agents/common/schema.ts +2 -2
  45. package/src/agents/detect.ts +5 -5
  46. package/src/agents/exclude.ts +3 -3
  47. package/src/agents/local.ts +1 -1
  48. package/src/agents/prompt.ts +2 -2
  49. package/src/agents/render.ts +2 -2
  50. package/src/agents/resolve.ts +6 -6
  51. package/src/agents/table.ts +1 -1
  52. package/src/commands/agents.command.ts +4 -4
  53. package/src/commands/clean.command.ts +72 -0
  54. package/src/commands/help.command.ts +11 -0
  55. package/src/commands/index.ts +6 -0
  56. package/src/commands/init.command.ts +4 -1
  57. package/src/commands/profile.command.ts +255 -0
  58. package/src/commands/sync.command.ts +6 -4
  59. package/src/commands/upgrade.command.ts +1 -1
  60. package/src/commands/visualize.command.ts +107 -0
  61. package/src/common/constants.ts +23 -0
  62. package/src/config/common/constants.ts +2 -0
  63. package/src/config/loader.ts +4 -4
  64. package/src/config/packages.ts +1 -1
  65. package/src/config/schema.ts +16 -5
  66. package/src/create/add-app.ts +15 -15
  67. package/src/create/add-lib.ts +7 -7
  68. package/src/create/bunfig.ts +1 -1
  69. package/src/create/dockerignore.ts +4 -4
  70. package/src/create/init-monorepo.ts +3 -1
  71. package/src/create/lib-preset.ts +1 -1
  72. package/src/create/names.ts +7 -6
  73. package/src/create/next.ts +4 -4
  74. package/src/create/preset-menu.ts +4 -4
  75. package/src/create/preset.ts +3 -3
  76. package/src/create/scratch.ts +27 -6
  77. package/src/create/workspace.ts +11 -11
  78. package/src/doctor/checks.ts +231 -45
  79. package/src/doctor/common/constants.ts +4 -0
  80. package/src/doctor/makefile.ts +3 -3
  81. package/src/doctor/runner.ts +16 -1
  82. package/src/doctor/skills.ts +8 -8
  83. package/src/doctor/tags.ts +5 -5
  84. package/src/hooks/common/constants.ts +29 -0
  85. package/src/hooks/common/types.ts +20 -0
  86. package/src/hooks/decision.ts +15 -0
  87. package/src/hooks/guard-git.ts +288 -0
  88. package/src/hooks/guard-manifest.ts +1 -1
  89. package/src/hooks/guard-outside.ts +399 -0
  90. package/src/hooks/guard-package.ts +4 -4
  91. package/src/hooks/guard-writes.ts +5 -5
  92. package/src/hooks/index.ts +6 -0
  93. package/src/hooks/owner-reply.ts +148 -0
  94. package/src/hooks/post-tool.ts +137 -0
  95. package/src/hooks/remote-hosts.ts +25 -23
  96. package/src/hooks/session-digest.ts +24 -4
  97. package/src/hooks/shell.ts +325 -0
  98. package/src/hooks/subagent-card.ts +32 -0
  99. package/src/init/scaffold.ts +6 -6
  100. package/src/local/clean.ts +88 -0
  101. package/src/local/constants.ts +50 -0
  102. package/src/local/format.ts +25 -0
  103. package/src/local/index.ts +4 -0
  104. package/src/local/scan.ts +368 -0
  105. package/src/manifest/render.ts +1 -1
  106. package/src/owner/card.ts +85 -0
  107. package/src/owner/constants.ts +105 -0
  108. package/src/owner/index.ts +8 -0
  109. package/src/owner/profile.ts +123 -0
  110. package/src/owner/schema.ts +147 -0
  111. package/src/owner/shape.ts +380 -0
  112. package/src/owner/survey.ts +289 -0
  113. package/src/owner/view.ts +76 -0
  114. package/src/owner/violations.ts +202 -0
  115. package/src/router.ts +18 -1
  116. package/src/rules/base.ts +1 -1
  117. package/src/rules/parser.ts +5 -5
  118. package/src/signals/claims.ts +71 -0
  119. package/src/signals/classify.ts +132 -0
  120. package/src/signals/constants.ts +88 -0
  121. package/src/signals/index.ts +5 -0
  122. package/src/signals/loop.ts +46 -0
  123. package/src/signals/state.ts +276 -0
  124. package/src/sync/agent-files.ts +4 -4
  125. package/src/sync/agent-removal.ts +6 -6
  126. package/src/sync/atlas-block.ts +1 -1
  127. package/src/sync/base-rules.ts +1 -1
  128. package/src/sync/exclude.ts +9 -9
  129. package/src/sync/local-choice.ts +35 -5
  130. package/src/sync/planner.ts +16 -16
  131. package/src/sync/prune.ts +3 -3
  132. package/src/sync/settings.ts +15 -15
  133. package/src/ui/prompt.ts +3 -3
  134. package/src/visualize/assets.ts +80 -0
  135. package/src/visualize/constants.ts +126 -0
  136. package/src/visualize/index.ts +6 -0
  137. package/src/visualize/layout.ts +107 -0
  138. package/src/visualize/page.ts +211 -0
  139. package/src/visualize/render.ts +161 -0
  140. package/src/visualize/schema.ts +178 -0
  141. package/src/visualize/validate.ts +127 -0
@@ -27,3 +27,23 @@ export interface IManifestHookInput {
27
27
  command: string | undefined;
28
28
  cwd: string | undefined;
29
29
  }
30
+
31
+ /** One thing a guard found: how to answer (`ask` or `deny`), the rule it enforces, and what the command does. */
32
+ export interface IGitHit {
33
+ decision: TGuardDecision;
34
+ rule: string;
35
+ message: string;
36
+ }
37
+
38
+ /** Runs a read-only `git` or `gh` query for a guard; `undefined` when it cannot answer. */
39
+ export type IGitRunner = (opts: {
40
+ program: string;
41
+ args: string[];
42
+ cwd: string | undefined;
43
+ }) => string | undefined;
44
+
45
+ /** A path a command would create or write outside the project, and what writes it. */
46
+ export interface IOutsideHit {
47
+ path: string;
48
+ message: string;
49
+ }
@@ -0,0 +1,15 @@
1
+ import { HookConstants } from './common/index.ts';
2
+ import type { TGuardDecision } from './common/index.ts';
3
+
4
+ /** The PreToolUse answer Claude Code reads from stdout: the decision and why, shown to the human or to the model. */
5
+ export const buildToolDecision = (opts: { decision: TGuardDecision; reason: string[] }) => ({
6
+ hookSpecificOutput: {
7
+ hookEventName: HookConstants.PRE_TOOL_USE,
8
+ permissionDecision: opts.decision,
9
+ permissionDecisionReason: opts.reason.join('\n'),
10
+ },
11
+ });
12
+
13
+ /** Whether the session switched the guards off (`VULCAN_GUARDS=off`): every call then passes. */
14
+ export const guardsAreOff = (opts: { env?: Record<string, string | undefined> } = {}): boolean =>
15
+ (opts.env ?? process.env)[HookConstants.KILL_SWITCH_ENV] === HookConstants.KILL_SWITCH_OFF;
@@ -0,0 +1,288 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { basenameOf, parseShell, programOf } from './shell.ts';
3
+ import type { ISimpleCommand } from './shell.ts';
4
+ import { GuardDecisions, HookConstants } from './common/index.ts';
5
+ import type { IGitHit, IGitRunner } from './common/index.ts';
6
+
7
+ /** `git` and `gh` read-only queries the guard makes; `undefined` when the tool is missing, slow or fails. */
8
+ export const runQuery: IGitRunner = (opts) => {
9
+ const result = spawnSync(opts.program, opts.args, {
10
+ cwd: opts.cwd,
11
+ encoding: 'utf8',
12
+ timeout: HookConstants.QUERY_TIMEOUT_MS,
13
+ env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
14
+ });
15
+
16
+ return result.status === 0 ? result.stdout.trim() : undefined;
17
+ };
18
+
19
+ /** Options of `git` before its subcommand, and how many words each takes. */
20
+ const GIT_OPTIONS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace']);
21
+
22
+ /** The subcommand of a `git` line and the words after it, past `-C <dir>`, `-c k=v` and the like. */
23
+ const gitCall = (opts: { args: string[] }): { sub: string; rest: string[]; dir?: string } => {
24
+ let index = 0;
25
+ let dir: string | undefined;
26
+
27
+ while (index < opts.args.length) {
28
+ const word = opts.args[index];
29
+
30
+ if (word === '-C') {
31
+ dir = opts.args[index + 1];
32
+ index += 2;
33
+ } else if (GIT_OPTIONS_WITH_VALUE.has(word)) {
34
+ index += 2;
35
+ } else if (word.startsWith('-')) {
36
+ index += 1;
37
+ } else {
38
+ return { sub: word, rest: opts.args.slice(index + 1), dir };
39
+ }
40
+ }
41
+
42
+ return { sub: '', rest: [], dir };
43
+ };
44
+
45
+ const isProtected = (opts: { name: string }): boolean =>
46
+ HookConstants.PROTECTED_BRANCHES.has(opts.name.replace(/^\+/, '').replace(/^refs\/heads\//, ''));
47
+
48
+ /** The branch a push refspec writes to: `dst` of `src:dst`, else the name itself. */
49
+ const pushTargetOf = (opts: { refspec: string; current: () => string | undefined }): string => {
50
+ const bare = opts.refspec.replace(/^\+/, '');
51
+ const target = bare.includes(':') ? bare.slice(bare.lastIndexOf(':') + 1) : bare;
52
+
53
+ return target === 'HEAD' || target === '' ? (opts.current() ?? '') : target;
54
+ };
55
+
56
+ const inspectPush = (opts: {
57
+ rest: string[];
58
+ cwd: string | undefined;
59
+ run: IGitRunner;
60
+ }): IGitHit[] => {
61
+ const flags = opts.rest.filter((word) => word.startsWith('-') && word !== '-');
62
+ const positional = opts.rest.filter((word) => !word.startsWith('-'));
63
+ const [, ...refspecs] = positional;
64
+ const forced =
65
+ flags.some((flag) => /^-[a-zA-Z]*f[a-zA-Z]*$/.test(flag) || flag.startsWith('--force')) ||
66
+ refspecs.some((refspec) => refspec.startsWith('+'));
67
+ const deleting =
68
+ flags.some((flag) => /^-[a-zA-Z]*d[a-zA-Z]*$/.test(flag) || flag === '--delete') ||
69
+ refspecs.some((r) => r.startsWith(':'));
70
+ const current = (): string | undefined =>
71
+ opts.run({
72
+ program: 'git',
73
+ args: ['rev-parse', '--abbrev-ref', 'HEAD'],
74
+ cwd: opts.cwd,
75
+ });
76
+ const targets = (refspecs.length > 0 ? refspecs : [':current'])
77
+ .map((refspec) => (refspec === ':current' ? (current() ?? '') : refspec))
78
+ .map((refspec) =>
79
+ deleting && !refspec.includes(':') ? refspec : pushTargetOf({ refspec, current }),
80
+ )
81
+ .filter((name) => name !== '');
82
+ const hits: IGitHit[] = [];
83
+
84
+ for (const name of targets.filter((target) => isProtected({ name: target }))) {
85
+ if (deleting) {
86
+ hits.push({
87
+ decision: GuardDecisions.DENY,
88
+ rule: 'V-W-06',
89
+ message: `deleting the remote branch '${name}'`,
90
+ });
91
+ } else if (forced) {
92
+ hits.push({
93
+ decision: GuardDecisions.DENY,
94
+ rule: 'V-W-06',
95
+ message: `force-pushing to '${name}'`,
96
+ });
97
+ }
98
+ }
99
+
100
+ if (flags.includes('--mirror')) {
101
+ hits.push({
102
+ decision: GuardDecisions.ASK,
103
+ rule: 'V-W-06',
104
+ message: 'git push --mirror overwrites and deletes remote branches to match this clone',
105
+ });
106
+ }
107
+
108
+ if (forced && !hits.some((hit) => hit.message.startsWith('force-pushing'))) {
109
+ hits.push({
110
+ decision: GuardDecisions.ASK,
111
+ rule: 'V-W-06',
112
+ message: 'a force-push rewrites history others may have pulled',
113
+ });
114
+ }
115
+
116
+ return hits;
117
+ };
118
+
119
+ const inspectBranch = (opts: {
120
+ rest: string[];
121
+ cwd: string | undefined;
122
+ run: IGitRunner;
123
+ }): IGitHit[] => {
124
+ const flags = opts.rest.filter((word) => word.startsWith('-') && word !== '--');
125
+ const renaming = flags.some(
126
+ (flag) => flag === '--move' || (/^-[a-zA-Z]+$/.test(flag) && /[mM]/.test(flag)),
127
+ );
128
+ const deleting = flags.some(
129
+ (flag) => flag === '--delete' || (/^-[a-zA-Z]+$/.test(flag) && /[dD]/.test(flag)),
130
+ );
131
+
132
+ if (renaming) {
133
+ const [from] = opts.rest.filter((word) => !word.startsWith('-'));
134
+
135
+ return from !== undefined && isProtected({ name: from })
136
+ ? [
137
+ {
138
+ decision: GuardDecisions.DENY,
139
+ rule: 'V-W-06',
140
+ message: `renaming the branch '${from}'`,
141
+ },
142
+ ]
143
+ : [];
144
+ }
145
+
146
+ if (!deleting) {
147
+ return [];
148
+ }
149
+
150
+ const names = opts.rest.filter((word) => !word.startsWith('-'));
151
+ const hits: IGitHit[] = names
152
+ .filter((name) => isProtected({ name }))
153
+ .map((name) => ({
154
+ decision: GuardDecisions.DENY,
155
+ rule: 'V-W-06',
156
+ message: `deleting the branch '${name}'`,
157
+ }));
158
+ const forced = flags.some(
159
+ (flag) => /^-[a-zA-Z]*D/.test(flag) || flag === '-f' || flag === '--force',
160
+ );
161
+ const merged = opts.run({
162
+ program: 'git',
163
+ args: ['branch', '--format=%(refname:short)', '--merged'],
164
+ cwd: opts.cwd,
165
+ });
166
+
167
+ if (forced && merged !== undefined) {
168
+ const mergedNames = new Set(merged.split('\n').map((line) => line.trim()));
169
+
170
+ for (const name of names.filter((item) => !isProtected({ name: item }))) {
171
+ if (!mergedNames.has(name)) {
172
+ hits.push({
173
+ decision: GuardDecisions.ASK,
174
+ rule: 'V-W-06',
175
+ message: `'${name}' is not merged into the current branch; force-deleting it loses its commits`,
176
+ });
177
+ }
178
+ }
179
+ }
180
+
181
+ return hits;
182
+ };
183
+
184
+ /** `gh pr merge [<pr>] --delete-branch`: the PR's head branch decides, and `gh` is asked for it. */
185
+ const inspectGhMerge = (opts: {
186
+ args: string[];
187
+ cwd: string | undefined;
188
+ run: IGitRunner;
189
+ }): IGitHit[] => {
190
+ const [group, action, ...rest] = opts.args;
191
+
192
+ if (group !== 'pr' || action !== 'merge') {
193
+ return [];
194
+ }
195
+
196
+ const deletes = rest.some((word) => word === '--delete-branch' || /^-[a-zA-Z]*d/.test(word));
197
+
198
+ if (!deletes) {
199
+ return [];
200
+ }
201
+
202
+ const [target] = rest.filter((word) => !word.startsWith('-'));
203
+ const head = opts.run({
204
+ program: 'gh',
205
+ args: [
206
+ 'pr',
207
+ 'view',
208
+ ...(target === undefined ? [] : [target]),
209
+ '--json',
210
+ 'headRefName',
211
+ '-q',
212
+ '.headRefName',
213
+ ],
214
+ cwd: opts.cwd,
215
+ });
216
+
217
+ return head !== undefined && isProtected({ name: head })
218
+ ? [
219
+ {
220
+ decision: GuardDecisions.DENY,
221
+ rule: 'V-W-06',
222
+ message: `'gh pr merge --delete-branch' would delete '${head}', the head branch of this pull request`,
223
+ },
224
+ ]
225
+ : [];
226
+ };
227
+
228
+ const inspectOne = (opts: {
229
+ command: ISimpleCommand;
230
+ cwd: string | undefined;
231
+ run: IGitRunner;
232
+ }): IGitHit[] => {
233
+ const program = programOf({ command: opts.command });
234
+ const name = basenameOf({ word: program.name });
235
+
236
+ if (name === 'gh') {
237
+ return inspectGhMerge({ args: program.args, cwd: opts.cwd, run: opts.run });
238
+ }
239
+
240
+ if (name !== 'git') {
241
+ return [];
242
+ }
243
+
244
+ const call = gitCall({ args: program.args });
245
+ const cwd = call.dir ?? opts.cwd;
246
+
247
+ if (call.sub === 'push') {
248
+ return inspectPush({ rest: call.rest, cwd, run: opts.run });
249
+ }
250
+
251
+ if (call.sub === 'branch') {
252
+ return inspectBranch({ rest: call.rest, cwd, run: opts.run });
253
+ }
254
+
255
+ if (call.sub === 'update-ref' && call.rest.some((word) => word === '-d' || word === '--delete')) {
256
+ const refs = call.rest.filter((word) => !word.startsWith('-'));
257
+
258
+ return refs
259
+ .filter((ref) => isProtected({ name: ref }))
260
+ .map((ref) => ({
261
+ decision: GuardDecisions.DENY,
262
+ rule: 'V-W-06',
263
+ message: `deleting the ref '${ref}'`,
264
+ }));
265
+ }
266
+
267
+ if (call.sub === 'reset' && call.rest.includes('--hard')) {
268
+ return [
269
+ {
270
+ decision: GuardDecisions.ASK,
271
+ rule: 'V-W-04',
272
+ message: 'git reset --hard discards every uncommitted change',
273
+ },
274
+ ];
275
+ }
276
+
277
+ return [];
278
+ };
279
+
280
+ /** Every reason `command` is a git or gh action that loses history or a protected branch. */
281
+ export const inspectGit = (opts: {
282
+ command: string;
283
+ cwd: string | undefined;
284
+ run?: IGitRunner;
285
+ }): IGitHit[] =>
286
+ parseShell({ command: opts.command }).flatMap((command) =>
287
+ inspectOne({ command, cwd: opts.cwd, run: opts.run ?? runQuery }),
288
+ );
@@ -71,7 +71,7 @@ export const inspectManifestWrite = (opts: { input: IManifestHookInput }): boole
71
71
  const { tool, filePath, command, cwd } = opts.input;
72
72
 
73
73
  if (tool === BASH_TOOL) {
74
- return command !== undefined && WRITE_PATTERNS.some(pattern => pattern.test(command));
74
+ return command !== undefined && WRITE_PATTERNS.some((pattern) => pattern.test(command));
75
75
  }
76
76
 
77
77
  if (filePath === undefined) {