@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.
- package/README.md +30 -23
- package/base/checks/wiki-source-links.ts +17 -1
- package/base/claude/events.json +1 -11
- package/base/claude/settings.json +5 -76
- package/base/extensions/vulcan-guards.ts +81 -18
- package/base/hooks/guard-git.ts +95 -19
- package/base/hooks/guard-outside.ts +163 -43
- package/base/hooks/guard-writes.ts +15 -36
- package/base/hooks/session-start.ts +1 -1
- package/base/make/vulcan.mk +8 -5
- package/base/packs/venizia.md +16 -0
- package/base/references/delegation-brief.md +3 -5
- package/base/references/testing.md +1 -9
- package/base/rules.md +33 -38
- package/base/skills/build-a-feature/SKILL.md +4 -4
- package/base/skills/docs-update/SKILL.md +19 -8
- package/base/skills/fix-a-bug/SKILL.md +4 -2
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/research/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +2 -2
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +3 -3
- package/base/skills/visualize-work/references/spec.md +6 -3
- package/base/templates/AGENTS.md +9 -7
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +8 -31
- package/src/agents/codex-hooks.ts +1 -1
- package/src/agents/generated-block.ts +52 -0
- package/src/agents/hooks-json.ts +22 -3
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +15 -2
- package/src/agents/resolve.ts +1 -0
- package/src/agents/rules-block.ts +92 -0
- package/src/board/command.ts +92 -30
- package/src/board/common/constants.ts +26 -0
- package/src/board/common/types.ts +10 -3
- package/src/board/fold.ts +1 -1
- package/src/board/github.ts +1 -2
- package/src/board/gitlab.ts +436 -0
- package/src/board/index.ts +1 -0
- package/src/board/logo.ts +49 -0
- package/src/board/open-file.ts +110 -0
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +87 -3
- package/src/board/settings.ts +21 -24
- package/src/commands/changelog.command.ts +40 -0
- package/src/commands/clean.command.ts +6 -1
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +6 -1
- package/src/commands/migrate.command.ts +71 -0
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/runners.command.ts +43 -0
- package/src/commands/sync.command.ts +8 -4
- package/src/commands/table.ts +362 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +4 -0
- package/src/commit/hook.ts +112 -8
- package/src/common/constants.ts +11 -9
- package/src/common/env-variables.ts +41 -0
- package/src/common/index.ts +1 -0
- package/src/common/layout-folder.ts +3 -4
- package/src/common/record.ts +5 -0
- package/src/config/common/constants.ts +28 -22
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +330 -146
- package/src/create/add-app.ts +7 -2
- package/src/create/add-lib.ts +2 -4
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +277 -448
- package/src/doctor/common/constants.ts +27 -19
- package/src/doctor/private-values.ts +4 -1
- package/src/doctor/runner.ts +5 -12
- package/src/doctor/schema.ts +4 -0
- package/src/events/common/actor-names.ts +12 -0
- package/src/events/common/constants.ts +65 -38
- package/src/events/common/index.ts +1 -0
- package/src/events/hook.ts +5 -56
- package/src/events/text.ts +41 -6
- package/src/hooks/command-view.ts +80 -19
- package/src/hooks/common/constants.ts +26 -17
- package/src/hooks/common/types.ts +13 -24
- package/src/hooks/decision.ts +30 -12
- package/src/hooks/git-queries.ts +113 -0
- package/src/hooks/guard-git.ts +76 -24
- package/src/hooks/guard-outside.ts +334 -311
- package/src/hooks/guard-runner.ts +206 -0
- package/src/hooks/guard-writes.ts +87 -184
- package/src/hooks/hook-input.ts +57 -0
- package/src/hooks/index.ts +3 -6
- package/src/hooks/link-makers.ts +315 -0
- package/src/hooks/package-runners.ts +268 -0
- package/src/hooks/project-guards.ts +81 -44
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/runner-scan.ts +257 -0
- package/src/hooks/script-runners.ts +400 -0
- package/src/hooks/session-digest.ts +27 -117
- package/src/hooks/shell-folders.ts +760 -0
- package/src/hooks/shell-writes.ts +646 -0
- package/src/hooks/shell.ts +1421 -194
- package/src/hooks/subagent-card.ts +2 -2
- package/src/hooks/write-commands.ts +898 -0
- package/src/init/scaffold.ts +2 -3
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +37 -6
- package/src/local/constants.ts +15 -1
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +41 -10
- package/src/manifest/render.ts +84 -30
- package/src/owner/constants.ts +4 -5
- package/src/owner/index.ts +0 -2
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +51 -27
- package/src/owner/survey.ts +0 -3
- package/src/owner/view.ts +0 -9
- package/src/router.ts +8 -132
- package/src/rules/base.ts +12 -7
- package/src/rules/index.ts +1 -0
- package/src/rules/packs.ts +44 -0
- package/src/runners/check.ts +130 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/agents-block.ts +104 -0
- package/src/sync/base-rules.ts +3 -3
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/common/constants.ts +0 -2
- package/src/sync/index.ts +1 -1
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +2 -15
- package/src/sync/settings.ts +0 -17
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/architecture.ts +504 -0
- package/src/visualize/assets.ts +41 -30
- package/src/visualize/compare-render.ts +22 -24
- package/src/visualize/constants.ts +27 -0
- package/src/visualize/diagrams.ts +13 -121
- package/src/visualize/kinds-render.ts +2 -2
- package/src/visualize/kinds-schema.ts +49 -0
- package/src/visualize/labels-vi.ts +25 -0
- package/src/visualize/labels.ts +2 -0
- package/src/visualize/layout.ts +415 -66
- package/src/visualize/page.ts +82 -15
- package/src/visualize/render.ts +2 -1
- package/src/visualize/schema.ts +29 -1
- package/src/visualize/sections.ts +78 -9
- package/src/visualize/theme.ts +49 -18
- package/src/wiki/anchors.ts +1 -0
- package/src/wiki/command.ts +10 -3
- package/src/wiki/source-links.ts +57 -18
- package/base/ci-global.json +0 -13
- package/base/claude/remote-hosts.json +0 -15
- package/base/hooks/guard-manifest.ts +0 -27
- package/base/hooks/guard-package.ts +0 -30
- package/base/hooks/guard-remote-hosts.ts +0 -70
- package/base/hooks/guard-scripting.ts +0 -32
- package/base/hooks/post-tool.ts +0 -37
- package/base/hooks/prompt-submit.ts +0 -54
- package/base/hooks/stop.ts +0 -40
- package/base/skills/build-a-feature/evals/evals.json +0 -29
- package/base/skills/docs-update/evals/evals.json +0 -23
- package/base/skills/docs-writing/evals/evals.json +0 -17
- package/base/skills/fix-a-bug/evals/evals.json +0 -17
- package/base/skills/knowledge-sync/SKILL.md +0 -81
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
- package/base/skills/knowledge-sync/references/workflow.md +0 -44
- package/base/skills/plan-a-change/evals/evals.json +0 -47
- package/base/skills/report-back/evals/evals.json +0 -23
- package/base/skills/research/evals/evals.json +0 -17
- package/base/skills/retro/evals/evals.json +0 -17
- package/base/skills/review-a-change/evals/evals.json +0 -17
- package/base/skills/ship/evals/evals.json +0 -23
- package/base/skills/visualize-work/evals/evals.json +0 -17
- package/base/templates/ci/github-actions.yml +0 -75
- package/base/templates/ci/gitlab-ci.yml +0 -52
- package/base/templates/trusted-hosts.local.example +0 -11
- package/src/ci/affected.ts +0 -176
- package/src/ci/command.ts +0 -166
- package/src/ci/common/constants.ts +0 -76
- package/src/ci/common/index.ts +0 -2
- package/src/ci/common/types.ts +0 -37
- package/src/ci/git.ts +0 -72
- package/src/ci/global.ts +0 -48
- package/src/ci/graph.ts +0 -43
- package/src/ci/index.ts +0 -7
- package/src/ci/workspace.ts +0 -119
- package/src/commands/ci.command.ts +0 -4
- package/src/hooks/guard-manifest.ts +0 -109
- package/src/hooks/guard-package.ts +0 -226
- package/src/hooks/guard-scripting.ts +0 -36
- package/src/hooks/host-pattern.ts +0 -17
- package/src/hooks/owner-reply.ts +0 -162
- package/src/hooks/post-tool.ts +0 -138
- package/src/hooks/remote-hosts.ts +0 -1013
- package/src/hooks/trusted-scripts.ts +0 -212
- package/src/owner/shape.ts +0 -496
- package/src/owner/violations.ts +0 -332
- package/src/signals/claims.ts +0 -73
- package/src/signals/classify.ts +0 -137
- package/src/signals/constants.ts +0 -88
- package/src/signals/index.ts +0 -5
- package/src/signals/loop.ts +0 -48
- package/src/signals/state.ts +0 -271
- package/src/sync/atlas-block.ts +0 -56
|
@@ -3,16 +3,25 @@
|
|
|
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
|
-
*
|
|
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
|
-
*
|
|
10
|
-
* is
|
|
11
|
-
* `
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
13
|
+
* A write to a file the guards read their policy from (the manifest, the config, `.claude/settings*.json` and the installed
|
|
14
|
+
* package) is always DENIED: an agent that can write one can switch a guard off, and the owner changes them by hand or through
|
|
15
|
+
* `vulcan sync`. A missing package, `bun` or hook file is the settings wrapper's to answer: it blocks, bar `bun install` and
|
|
16
|
+
* `vulcan sync`.
|
|
17
|
+
*
|
|
18
|
+
* It guards against drift, not against an attacker. A hook input it cannot read ASKS, because nothing was checked and the agent
|
|
19
|
+
* cannot repair that. A guard that started and then failed - a crash or a timeout, here an internal error or an unloadable
|
|
20
|
+
* module - ASKS instead of passing the call unchecked. Where the project (`guard.asks: 'deny'`) or the launch environment
|
|
21
|
+
* (`VULCAN_GUARD_ASKS=deny`) holds every ask, each is a deny; a manifest that exists and cannot be read holds them too. `VULCAN_GUARDS=off` switches it off,
|
|
22
|
+
* read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
|
|
23
|
+
* from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
|
|
24
|
+
* VULCAN cannot parse, then changes nothing here.
|
|
16
25
|
*/
|
|
17
26
|
|
|
18
27
|
// A module, so the awaits below are top-level; it has no static import, by design.
|
|
@@ -28,65 +37,143 @@ try {
|
|
|
28
37
|
const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
|
|
29
38
|
const { HookDecision } = await import('../../src/hooks/decision.ts');
|
|
30
39
|
const { OutsideGuard } = await import('../../src/hooks/guard-outside.ts');
|
|
31
|
-
const {
|
|
32
|
-
const
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
}
|
|
40
|
+
const { HookInput } = await import('../../src/hooks/hook-input.ts');
|
|
41
|
+
const { ProjectTmp } = await import('../../src/hooks/project-tmp.ts');
|
|
42
|
+
const { relative } = await import('node:path');
|
|
43
|
+
const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
|
|
44
|
+
const input = HookInput.parse({ text });
|
|
45
|
+
const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
|
|
46
|
+
const { toolOwnedPaths, outside, asks, asksNote } = ProjectGuards.readPolicy({
|
|
47
|
+
root: projectRoot,
|
|
48
|
+
});
|
|
49
|
+
const isHeld = asks === GuardDecisions.DENY;
|
|
50
50
|
|
|
51
|
+
if (!input) {
|
|
52
|
+
console.log(
|
|
53
|
+
JSON.stringify(
|
|
54
|
+
HookDecision.buildTool({
|
|
55
|
+
asks,
|
|
56
|
+
asksNote,
|
|
57
|
+
decision: GuardDecisions.ASK,
|
|
58
|
+
reason: [
|
|
59
|
+
'The hook input could not be read, so this call was not checked for files outside the project (V-B-08).',
|
|
60
|
+
'Confirm only if the call stays inside the project.',
|
|
61
|
+
],
|
|
62
|
+
}),
|
|
63
|
+
),
|
|
64
|
+
);
|
|
65
|
+
} else {
|
|
51
66
|
const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
|
|
52
67
|
|
|
53
68
|
if (hits.length > 0) {
|
|
54
|
-
const
|
|
55
|
-
const
|
|
56
|
-
const
|
|
57
|
-
|
|
69
|
+
const read = hits.filter((hit) => !hit.isUnread);
|
|
70
|
+
const isScratchpad = read.some((hit) => hit.isAgentToolScratchpad);
|
|
71
|
+
const linesOf = (list: typeof hits) => list.map((hit) => ` - ${hit.message} (${hit.path})`);
|
|
72
|
+
const tmpFolder = relative(projectRoot, ProjectTmp.projectOf({ root: projectRoot }));
|
|
73
|
+
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.`;
|
|
74
|
+
const owned =
|
|
75
|
+
'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.';
|
|
58
76
|
|
|
59
|
-
|
|
77
|
+
// A line the check could not read is denied, whatever the project sets: the agent can write it again so that it is read.
|
|
78
|
+
const unreadHits = hits.filter((hit) => hit.isUnread);
|
|
79
|
+
const unread =
|
|
80
|
+
unreadHits.length === 0
|
|
81
|
+
? []
|
|
82
|
+
: [
|
|
83
|
+
...(read.length > 0 ? [''] : []),
|
|
84
|
+
'Part of this call could not be read, so it was not checked for files outside the project (V-B-08):',
|
|
85
|
+
...linesOf(unreadHits),
|
|
86
|
+
];
|
|
87
|
+
// 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.
|
|
88
|
+
const linkHits = read.filter((hit) => hit.isLink === true);
|
|
89
|
+
// A file the guards read their policy from: denied, so no agent loosens a guard by editing it.
|
|
90
|
+
const protectedHits = read.filter((hit) => hit.isProtected === true);
|
|
91
|
+
const isDeny =
|
|
92
|
+
isScratchpad ||
|
|
93
|
+
protectedHits.length > 0 ||
|
|
94
|
+
linkHits.length > 0 ||
|
|
95
|
+
unreadHits.length > 0 ||
|
|
96
|
+
((outside === GuardDecisions.DENY || isHeld) && read.length > 0);
|
|
60
97
|
let reason: string[];
|
|
61
98
|
|
|
62
|
-
if (isScratchpad) {
|
|
99
|
+
if (unreadHits.length > 0 && !isScratchpad) {
|
|
100
|
+
reason = [
|
|
101
|
+
'Part of this call could not be read, so it cannot be checked for files outside the project (V-B-08):',
|
|
102
|
+
...linesOf(unreadHits),
|
|
103
|
+
...(read.length > 0
|
|
104
|
+
? [
|
|
105
|
+
'',
|
|
106
|
+
'The part that was read would also create files outside the project:',
|
|
107
|
+
...linesOf(read),
|
|
108
|
+
]
|
|
109
|
+
: []),
|
|
110
|
+
'',
|
|
111
|
+
`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}`,
|
|
112
|
+
owned,
|
|
113
|
+
];
|
|
114
|
+
} else if (isScratchpad) {
|
|
63
115
|
reason = [
|
|
64
116
|
'This would write into the scratchpad folder the agent tool offers (V-B-08):',
|
|
65
|
-
...
|
|
117
|
+
...linesOf(read),
|
|
118
|
+
...unread,
|
|
66
119
|
'',
|
|
67
120
|
`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
121
|
];
|
|
122
|
+
} else if (protectedHits.length > 0) {
|
|
123
|
+
reason = [
|
|
124
|
+
'This would change a file the guards read their policy from (V-B-08):',
|
|
125
|
+
...linesOf(protectedHits),
|
|
126
|
+
...(read.length > protectedHits.length
|
|
127
|
+
? [
|
|
128
|
+
'',
|
|
129
|
+
'It would also create files outside the project:',
|
|
130
|
+
...linesOf(read.filter((hit) => hit.isProtected !== true)),
|
|
131
|
+
]
|
|
132
|
+
: []),
|
|
133
|
+
...unread,
|
|
134
|
+
'',
|
|
135
|
+
'Nothing was run. These files are changed by the owner, by hand or through bun node_modules/.bin/vulcan sync; an agent that could edit them could switch a guard off.',
|
|
136
|
+
];
|
|
137
|
+
} else if (linkHits.length > 0) {
|
|
138
|
+
reason = [
|
|
139
|
+
'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:',
|
|
140
|
+
...linesOf(linkHits),
|
|
141
|
+
...(read.length > linkHits.length
|
|
142
|
+
? [
|
|
143
|
+
'',
|
|
144
|
+
'It would also create files outside the project:',
|
|
145
|
+
...linesOf(read.filter((hit) => hit.isLink !== true)),
|
|
146
|
+
]
|
|
147
|
+
: []),
|
|
148
|
+
'',
|
|
149
|
+
`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}`,
|
|
150
|
+
owned,
|
|
151
|
+
];
|
|
69
152
|
} else if (isDeny) {
|
|
70
153
|
reason = [
|
|
71
|
-
|
|
72
|
-
...
|
|
154
|
+
`This would create files outside the project (V-B-08), and this project denies it (${isHeld ? 'guard.asks' : 'guard.outside'}):`,
|
|
155
|
+
...linesOf(read),
|
|
156
|
+
...unread,
|
|
73
157
|
'',
|
|
74
158
|
`Nothing was written. ${places}`,
|
|
75
|
-
|
|
159
|
+
...(isHeld && asksNote !== undefined ? ['', asksNote] : []),
|
|
160
|
+
owned,
|
|
76
161
|
];
|
|
77
162
|
} else {
|
|
78
163
|
reason = [
|
|
79
164
|
'This would create files outside the project (V-B-08):',
|
|
80
|
-
...
|
|
165
|
+
...linesOf(read),
|
|
166
|
+
...unread,
|
|
81
167
|
'',
|
|
82
168
|
`${places} Use that place, or confirm only if the owner asked for this exact path.`,
|
|
83
|
-
|
|
169
|
+
owned,
|
|
84
170
|
];
|
|
85
171
|
}
|
|
86
172
|
|
|
87
173
|
console.log(
|
|
88
174
|
JSON.stringify(
|
|
89
175
|
HookDecision.buildTool({
|
|
176
|
+
asks,
|
|
90
177
|
decision: isDeny ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
91
178
|
reason,
|
|
92
179
|
}),
|
|
@@ -99,17 +186,50 @@ try {
|
|
|
99
186
|
|
|
100
187
|
console.error(`vulcan: the guard-outside hook failed (${message}); run bun install`);
|
|
101
188
|
|
|
102
|
-
// The imports may be what failed, so the answer is written by hand
|
|
189
|
+
// The imports may be what failed, so the answer is written by hand, and a project that sets guard.asks to deny is read from the manifest by hand too.
|
|
190
|
+
let isHeldOnCrash = false;
|
|
191
|
+
|
|
192
|
+
try {
|
|
193
|
+
const { existsSync, readFileSync } = await import('node:fs');
|
|
194
|
+
const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
|
|
195
|
+
const file = `${root}/.agents/vulcan.manifest.json`;
|
|
196
|
+
|
|
197
|
+
isHeldOnCrash = process.env.VULCAN_GUARD_ASKS === 'deny';
|
|
198
|
+
|
|
199
|
+
if (!isHeldOnCrash && existsSync(file)) {
|
|
200
|
+
try {
|
|
201
|
+
const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
|
|
202
|
+
const guard =
|
|
203
|
+
typeof manifest === 'object' && manifest !== null && 'guard' in manifest
|
|
204
|
+
? manifest.guard
|
|
205
|
+
: undefined;
|
|
206
|
+
|
|
207
|
+
isHeldOnCrash =
|
|
208
|
+
typeof manifest !== 'object' ||
|
|
209
|
+
manifest === null ||
|
|
210
|
+
Array.isArray(manifest) ||
|
|
211
|
+
(typeof guard === 'object' && guard !== null && 'asks' in guard && guard.asks === 'deny');
|
|
212
|
+
} catch {
|
|
213
|
+
// A manifest that exists and cannot be read holds every ask.
|
|
214
|
+
isHeldOnCrash = true;
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
} catch {
|
|
218
|
+
isHeldOnCrash = false;
|
|
219
|
+
}
|
|
220
|
+
|
|
103
221
|
console.log(
|
|
104
222
|
JSON.stringify({
|
|
105
223
|
hookSpecificOutput: {
|
|
106
224
|
hookEventName: 'PreToolUse',
|
|
107
|
-
permissionDecision: 'ask',
|
|
225
|
+
permissionDecision: isHeldOnCrash ? 'deny' : 'ask',
|
|
108
226
|
permissionDecisionReason: [
|
|
109
227
|
'The guard-outside hook failed, so this call was not checked for files outside the project (V-B-08):',
|
|
110
228
|
` - ${message}`,
|
|
111
229
|
'',
|
|
112
|
-
|
|
230
|
+
isHeldOnCrash
|
|
231
|
+
? 'This project denies every call that would need a human to confirm it (guard.asks: deny). Nothing was run: run bun install to repair the install.'
|
|
232
|
+
: 'Confirm only if the call stays inside the project; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
|
|
113
233
|
].join('\n'),
|
|
114
234
|
},
|
|
115
235
|
}),
|
|
@@ -1,12 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* PreToolUse hook on Bash: catches the writes V-W-02 and V-W-03 reserve for a human,
|
|
3
|
-
*
|
|
2
|
+
* PreToolUse hook on Bash: catches the writes V-W-02 and V-W-03 reserve for a human, matching each command
|
|
3
|
+
* the shell parser finds against the command table (src/hooks/write-commands.ts). It asks rather than denies
|
|
4
|
+
* (src/hooks/common/constants.ts).
|
|
4
5
|
* The project's own deploy and migrate commands (`guard.writes.commands`) are read from the manifest and
|
|
5
6
|
* checked beside the fixed list, inside compound commands too.
|
|
6
|
-
* A script the project lists in `guard.writes.trustedScripts` is not read for writes while git says it
|
|
7
|
-
* is tracked and unchanged; a config that cannot be read leaves the list empty, so every script is read.
|
|
8
|
-
* An entry of `guard.writes.readOnlyScripts` in the manifest (the object form of `trustedScripts`, written by
|
|
9
|
-
* `vulcan sync`) skips that read for the calls whose first argument after the script is one of its words.
|
|
10
7
|
*
|
|
11
8
|
* It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so a hook that throws - a
|
|
12
9
|
* partial install, say, where its own modules are missing - would let every command through. The
|
|
@@ -22,41 +19,23 @@ try {
|
|
|
22
19
|
const stdin = await Bun.stdin.text();
|
|
23
20
|
const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
|
|
24
21
|
const cwd = hookCommand?.cwd ?? process.cwd();
|
|
25
|
-
let scripts: string[] = [];
|
|
26
|
-
|
|
27
|
-
// Only a command that names a .ts file can use the list; the config loader (and zod) loads last, on its
|
|
28
|
-
// own, and may fail alone.
|
|
29
|
-
if (hookCommand && /\.ts\b/.test(hookCommand.command)) {
|
|
30
|
-
try {
|
|
31
|
-
const { ConfigLoader } = await import('../../src/config/index.ts');
|
|
32
|
-
const loaded = await ConfigLoader.load({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
|
|
33
|
-
|
|
34
|
-
// The objects are the read-only entries: the manifest carries them, so only the paths count here.
|
|
35
|
-
scripts = loaded.ok
|
|
36
|
-
? loaded.config.guard.writes.trustedScripts.filter(
|
|
37
|
-
(entry): entry is string => typeof entry === 'string',
|
|
38
|
-
)
|
|
39
|
-
: [];
|
|
40
|
-
} catch (error) {
|
|
41
|
-
console.error(
|
|
42
|
-
`vulcan: the guard-writes hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - every script is read`,
|
|
43
|
-
);
|
|
44
|
-
}
|
|
45
|
-
}
|
|
46
|
-
|
|
47
22
|
const root = process.env.CLAUDE_PROJECT_DIR ?? cwd;
|
|
48
23
|
const policy = ProjectGuards.readPolicy({ root });
|
|
49
24
|
const hits = hookCommand
|
|
50
|
-
? WriteGuard.inspectCommand({
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
25
|
+
? WriteGuard.inspectCommand({ command: hookCommand.command, extra: policy.commands })
|
|
26
|
+
: [
|
|
27
|
+
{
|
|
28
|
+
rule: 'V-W-02',
|
|
29
|
+
message: 'the hook input could not be read, so the command was not checked',
|
|
30
|
+
},
|
|
31
|
+
];
|
|
57
32
|
|
|
58
33
|
if (hits.length > 0) {
|
|
59
|
-
console.log(
|
|
34
|
+
console.log(
|
|
35
|
+
JSON.stringify(
|
|
36
|
+
WriteGuard.buildDecision({ hits, asks: policy.asks, asksNote: policy.asksNote }),
|
|
37
|
+
),
|
|
38
|
+
);
|
|
60
39
|
}
|
|
61
40
|
} catch (error) {
|
|
62
41
|
console.error(
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* SessionStart hook: prints
|
|
2
|
+
* SessionStart hook: prints what only this session knows - a config problem, a launch warning, the owner card (src/hooks/session-digest.ts). The rules are the block of AGENTS.md.
|
|
3
3
|
* Stdout becomes session context. With `VULCAN_OWNER_REPLY=off` the owner shape and profile cards are left out.
|
|
4
4
|
* It also exports `TMPDIR` (the project's `.agents/local/tmp`) into the file Claude Code sources before each Bash command.
|
|
5
5
|
*/
|
package/base/make/vulcan.mk
CHANGED
|
@@ -2,12 +2,14 @@
|
|
|
2
2
|
# -include node_modules/@venizia/vulcan/base/make/vulcan.mk
|
|
3
3
|
# A project adds its own targets after the include; redefining one of these fails `vulcan doctor`.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
# The linked bin by path, not `bun run vulcan`: `bun run` falls back to a program on $PATH, or to one bun cached, when the bin is not linked
|
|
6
|
+
# here, and the include above needs this same node_modules. A missing bin fails the target instead of running another program.
|
|
7
|
+
VULCAN ?= bun $(CURDIR)/node_modules/.bin/vulcan
|
|
6
8
|
VULCAN_BASE ?= node_modules/@venizia/vulcan/base
|
|
7
9
|
# The GitHub repository the wiki links point into, owner/name; the link gate checks only links into it.
|
|
8
10
|
WIKI_REPO ?=
|
|
9
11
|
|
|
10
|
-
.PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage
|
|
12
|
+
.PHONY: vulcan-sync vulcan-doctor runners-check okf-check okf-check-strict okf-gen okf-coverage \
|
|
11
13
|
surface-gen surface-check atlas-symbols atlas-releases wiki-links-check wiki-anchors-check
|
|
12
14
|
|
|
13
15
|
vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
|
|
@@ -16,6 +18,10 @@ vulcan-sync: ## Write the agent adapters, settings, skill links and manifest fro
|
|
|
16
18
|
vulcan-doctor: ## Check the project against the VULCAN contract
|
|
17
19
|
@$(VULCAN) doctor
|
|
18
20
|
|
|
21
|
+
# V-S-08: no tracked file runs a package by name (bunx, bun x, npx, pnpm dlx). Allow a name with guard.runners.allow.
|
|
22
|
+
runners-check: ## Fail when a tracked file runs an unscoped package by name (bunx, bun x, npx, pnpm dlx)
|
|
23
|
+
@$(VULCAN) runners check
|
|
24
|
+
|
|
19
25
|
# OKF v0.2 conformance only; okf-check-strict adds the house rules (links, style, coverage, freshness).
|
|
20
26
|
okf-check: ## Check the knowledge bundle against OKF v0.2
|
|
21
27
|
@$(VULCAN) x okf check
|
|
@@ -29,9 +35,6 @@ okf-gen: ## Regenerate the generated pages and regions of the knowledge bundle
|
|
|
29
35
|
okf-coverage: ## Report how much of the code the knowledge bundle covers
|
|
30
36
|
@$(VULCAN) x okf coverage
|
|
31
37
|
|
|
32
|
-
okf-viz: ## Build the knowledge graph view
|
|
33
|
-
@$(VULCAN) x okf viz
|
|
34
|
-
|
|
35
38
|
# The public surface: an optional API gate a project commits and checks. It reads the built .d.ts -
|
|
36
39
|
# build first.
|
|
37
40
|
surface-gen: ## Write the public API surface from the built .d.ts
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Rules - the Venizia pack
|
|
2
|
+
|
|
3
|
+
<!-- Shipped by @venizia/vulcan, never edited in a project. These rules bind the Venizia stack (Bun, devz, the vite
|
|
4
|
+
builders, the house lint rules), so they are not in the base rules: a project turns the pack on with
|
|
5
|
+
`packs: ['venizia']` in `.configs/vulcan.config.*`, and `vulcan sync` names it in the rules block of AGENTS.md.
|
|
6
|
+
The IDs are the ones they had in the base rules and keep their `V-` namespace. -->
|
|
7
|
+
|
|
8
|
+
Cite by ID. Every rule has "Enforced by".
|
|
9
|
+
|
|
10
|
+
| ID | Rule | Enforced by |
|
|
11
|
+
|----|------|-------------|
|
|
12
|
+
| V-B-05 | **One script set for every app**, backend and frontend: `server:dev` (`NODE_ENV=development bun run src/index.ts` for a backend, `vite --config .configs/builders/vite.config.mts` for a frontend), `compile` (`bun .configs/builders/compile.ts` for a backend, `vite build --config .configs/builders/vite.config.mts` for a frontend), `typecheck` (`bun check`), `lint` (`devz lint`), `lint:fix` (`devz lint --fix`), `test` (`bun test`), `clean` (`devz clean`). The logic lives in `.configs/builders/` or in `devz`, never in the `package.json` string. No `dev`, `start`, `build`, `rebuild`, `preview` or `server:prod`; a domain extra such as `migrate:dev` is fine. **An app root holds only `.configs/`, `src/`, `package.json`, `tsconfig.json` and `.env.example`**; every other config lives in `.configs/{lints,formatters,builders}/`. A library package keeps Makefile targets: `build`, `typecheck`, `lint`, `lint-fix`, `test`, `clean`. | SOFT |
|
|
13
|
+
| V-B-09 | **Agent scripting uses bun by default.** A script you write to do a task is `bun -e '…'` or `bun file.ts`, with `Bun.file()` for files. Python or another language is allowed when the task needs it - an existing project script, a tool only that language has - and you say so in one line. | SOFT |
|
|
14
|
+
| V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`; `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
|
|
15
|
+
| V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. When something validates against such a class, it carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first); a class nothing validates against needs neither. The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed. | SOFT - lint (`const-class-values`) in a project that enables `houseConfigs` of `@venizia/dev-configs` |
|
|
16
|
+
| V-C-20 | **Declare the instance, then await on its own line.** Never `await new X({...}).method({...})`: write `const runner = new X({...});` and then `await runner.run({...});`. A constructor inside an awaited call chain hides the object that does the work - a reader cannot name it, a second call cannot reuse it, and a failure in the constructor reads like a failure in the method. A longer chain (`await new X().a().b()`) is the same defect. It covers tests and scripts. `await new Promise(...)` is not this form: the constructor call is the awaited value itself and the promise needs no name. | SOFT - lint (`venizia/no-await-new-chain`, `@venizia/dev-configs` from 0.4.8-3) in a project that enables `houseConfigs` |
|
|
@@ -69,13 +69,11 @@ unit that does not fit is split before it starts.
|
|
|
69
69
|
|
|
70
70
|
A subagent started through the tool's own subagent mechanism is already exempt from the owner's report
|
|
71
71
|
shape: it gets the subagent card, not the owner shape or the profile. A session you start another way (a
|
|
72
|
-
new terminal, `claude -p`, a script, a session another agent works in) is not: its
|
|
73
|
-
|
|
74
|
-
you.
|
|
72
|
+
new terminal, `claude -p`, a script, a session another agent works in) is not: its session digest carries the
|
|
73
|
+
owner's shape card and the profile card, although its reader is you.
|
|
75
74
|
|
|
76
75
|
Start it with `VULCAN_OWNER_REPLY=off` on the command that starts it (`VULCAN_OWNER_REPLY=off claude -p ...`), never with `export`, which reaches every later session started from that shell. Only the exact value `off` counts. The
|
|
77
|
-
session then gets no owner shape card and no profile card,
|
|
78
|
-
blocked; everything else (the guards, the rules, the signals) stays on. A session started for one piece of
|
|
76
|
+
session then gets no owner shape card and no profile card; everything else (the guards, the rules) stays on. A session started for one piece of
|
|
79
77
|
work is handed the item and the format ("take item X, return as Y"), not a long message. Say in the brief which plain
|
|
80
78
|
format you want back (the four statuses and the evidence table above are the default), in the language
|
|
81
79
|
you work in. Never set it in a shell the owner works in, or in the `env` of a settings file: `vulcan doctor` prints a
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
How a claim is turned into a test, and how the test is kept honest. It is loaded by `plan-a-change`,
|
|
4
4
|
`build-a-feature` (steps 3 and 5), `fix-a-bug` and `review-a-change`.
|
|
5
5
|
|
|
6
|
-
**Contents**: [Where a test lives](#where-a-test-lives) · [The loop](#the-loop) · [Anti-patterns](#anti-patterns) · [Mocking](#mocking) · [Fixtures and environment](#fixtures-and-environment) · [Blast radius](#blast-radius) · [Async UI and shipped UI](#async-ui-and-shipped-ui) · [When a verifier cannot run](#when-a-verifier-cannot-run) · [Regression tests](#regression-tests)
|
|
6
|
+
**Contents**: [Where a test lives](#where-a-test-lives) · [The loop](#the-loop) · [Anti-patterns](#anti-patterns) · [Mocking](#mocking) · [Fixtures and environment](#fixtures-and-environment) · [Blast radius](#blast-radius) · [Async UI and shipped UI](#async-ui-and-shipped-ui) · [When a verifier cannot run](#when-a-verifier-cannot-run) · [Regression tests](#regression-tests)
|
|
7
7
|
|
|
8
8
|
## Where a test lives
|
|
9
9
|
|
|
@@ -79,11 +79,3 @@ deferred-verify. It is never described as works, live, verified or shipped.
|
|
|
79
79
|
|
|
80
80
|
A regression test goes in before the fix, at a seam that reproduces the real bug pattern. If no such seam
|
|
81
81
|
exists, that is itself a finding: report it, and do not write a test that cannot fail.
|
|
82
|
-
|
|
83
|
-
## Evals for skills and rules
|
|
84
|
-
|
|
85
|
-
A suite has should-do cases and should-not cases: an eval that only checks the wanted behaviour optimises
|
|
86
|
-
for it blindly. The grader is a different model level from the one under test, gives its reasons before
|
|
87
|
-
its verdict, and answers UNKNOWN when it cannot tell (counted as a miss). Always include a baseline arm
|
|
88
|
-
(the same case with no skill) so the skill's effect is visible. Read the transcripts before trusting a
|
|
89
|
-
score. Changing a rule or a skill is a reason to run its eval again.
|