@venizia/vulcan 0.4.7 → 0.4.8
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/base/hooks/guard-git.ts +2 -1
- package/base/hooks/guard-outside.ts +20 -8
- package/base/references/delegation-brief.md +3 -1
- package/base/rules.md +1 -1
- package/base/skills/ship/SKILL.md +7 -3
- package/package.json +3 -3
- package/src/config/schema.ts +6 -0
- package/src/hooks/common/constants.ts +10 -0
- package/src/hooks/common/types.ts +2 -0
- package/src/hooks/guard-git.ts +92 -2
- package/src/hooks/guard-outside.ts +11 -3
- package/src/hooks/session-digest.ts +1 -1
- package/src/hooks/subagent-card.ts +1 -1
- package/src/manifest/render.ts +4 -0
package/base/hooks/guard-git.ts
CHANGED
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
* PreToolUse hook on Bash: parses the command (quotes, `&&`, `;`, `git -C`, heredocs) and catches the git
|
|
3
3
|
* and gh actions that lose history or a protected branch - deleting, renaming or force-pushing develop
|
|
4
4
|
* or main, `gh pr merge --delete-branch` on a pull request whose head is one of them (deny), and
|
|
5
|
-
* `reset --hard`, other force-pushes
|
|
5
|
+
* `reset --hard`, other force-pushes, `branch -D` of an unmerged branch and `gh pr create` with no `--base`
|
|
6
|
+
* (ask: the pull request would land on the default branch).
|
|
6
7
|
*
|
|
7
8
|
* It guards against drift, it is not the last line of defence, and a guard that blocks every command when
|
|
8
9
|
* its install is broken costs more than it protects. So input it cannot read passes, and so does a missing
|
|
@@ -47,17 +47,29 @@ try {
|
|
|
47
47
|
const hits = inspectOutside({ input, projectRoot, toolOwnedPaths });
|
|
48
48
|
|
|
49
49
|
if (hits.length > 0) {
|
|
50
|
+
const isScratchpad = hits.some((hit) => hit.isAgentToolScratchpad);
|
|
51
|
+
const hitLines = hits.map((hit) => ` - ${hit.message} (${hit.path})`);
|
|
52
|
+
const places =
|
|
53
|
+
'Scratch files go under .agents/local/tmp/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder.';
|
|
54
|
+
|
|
50
55
|
console.log(
|
|
51
56
|
JSON.stringify(
|
|
52
57
|
buildToolDecision({
|
|
53
|
-
decision: GuardDecisions.ASK,
|
|
54
|
-
reason:
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
58
|
+
decision: isScratchpad ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
59
|
+
reason: isScratchpad
|
|
60
|
+
? [
|
|
61
|
+
'This would write into the scratchpad folder the agent tool offers (V-B-08):',
|
|
62
|
+
...hitLines,
|
|
63
|
+
'',
|
|
64
|
+
`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.`,
|
|
65
|
+
]
|
|
66
|
+
: [
|
|
67
|
+
'This would create files outside the project (V-B-08):',
|
|
68
|
+
...hitLines,
|
|
69
|
+
'',
|
|
70
|
+
`${places} Use that place, or confirm only if the owner asked for this exact path.`,
|
|
71
|
+
'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
|
|
72
|
+
],
|
|
61
73
|
}),
|
|
62
74
|
),
|
|
63
75
|
);
|
|
@@ -16,7 +16,9 @@ A brief is built only from files you read this turn, never from memory. It holds
|
|
|
16
16
|
4. **The rules**: the digest reaches the subagent through the tool's subagent-start hook where one
|
|
17
17
|
exists; otherwise name the rule IDs it must keep.
|
|
18
18
|
5. **Limits**: read-only unless the brief says otherwise; **no git writes**; every file it creates goes
|
|
19
|
-
under `.agents/local/` (V-B-08)
|
|
19
|
+
under one named folder of `.agents/local/` (V-B-08), never `/tmp` and never the scratchpad folder its
|
|
20
|
+
tool offers (that is a `/tmp` folder: say so, because the tool's own text tells it to use it); no
|
|
21
|
+
network beyond what the task needs.
|
|
20
22
|
6. **What to return**: one of four statuses and the evidence (below), in a stated shape, under 400 words.
|
|
21
23
|
7. **A completion checklist** the subagent ticks, and a size bound, so one silent failure loses little.
|
|
22
24
|
|
package/base/rules.md
CHANGED
|
@@ -66,7 +66,7 @@ Retired IDs are never reused (2026-10-17):
|
|
|
66
66
|
| 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 allowed on top. **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 instead: `build`, `typecheck`, `lint`, `lint-fix`, `test`, `clean`. | SOFT - `vulcan doctor` notes an app that lacks one or carries a legacy name (info, never a failure) |
|
|
67
67
|
| V-B-06 | **Small never cuts safety.** Saving code never removes input validation, error handling, security checks or data safety: they are part of the task at any size (V-S-03, V-C-06 and V-B-04 still apply). | SOFT |
|
|
68
68
|
| V-B-07 | **Say what you skipped.** Report plainly what was not done, not checked or left as a shortcut; never let a check that did not run read as one that did. A deliberate shortcut in code is marked `// SHORTCUT: <what>, <why>, <revisit when>` so it can be found again. | SOFT - build-a-feature step 8 summary, session-start digest |
|
|
69
|
-
| V-B-08 | **Leave no trace, and none outside the project.** Everything you create while you work - scratch files, temporary files, logs, worktrees, clones of other repositories, subagent output - lives under the project's gitignored `.agents/local/` (`tmp/`, `worktrees/`, `clones/`; each directory's lifetime is in the table of the rules reference) and you remove it when its lifetime ends: scratch when the task ends, a worktree when its branch is merged or abandoned, a clone when the research is reported. Nothing goes in the system temp directory, the home directory or any other place outside the project; the done report says what was removed and what was kept, and why. The agent tool's
|
|
69
|
+
| V-B-08 | **Leave no trace, and none outside the project.** Everything you create while you work - scratch files, temporary files, logs, worktrees, clones of other repositories, subagent output - lives under the project's gitignored `.agents/local/` (`tmp/`, `worktrees/`, `clones/`; each directory's lifetime is in the table of the rules reference) and you remove it when its lifetime ends: scratch when the task ends, a worktree when its branch is merged or abandoned, a clone when the research is reported. Nothing goes in the system temp directory, the home directory or any other place outside the project; the done report says what was removed and what was kept, and why. The scratchpad folder an agent tool offers is a system temp directory, not one of its own files: never use it, even when the tool's text says to. What a tool writes for itself (its task output, its memory) is outside this rule's reach. | SOFT |
|
|
70
70
|
| V-B-09 | **Agent scripting uses bun by default.** A script you write to do a task (an edit, a check, a report) 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 - the guard-scripting hook adds a reminder when a command runs python, python3 or pip; it never blocks |
|
|
71
71
|
|
|
72
72
|
## C - Code and writing
|
|
@@ -48,8 +48,12 @@ The body is read by a person who has not seen the work. In this order:
|
|
|
48
48
|
(revert and it is gone), and the blast radius if it is wrong.
|
|
49
49
|
5. **Not verified**: the items from the checklist.
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
Open the pull request with its base named, `gh pr create --base <branch>`. Take the branch from the project's rules.
|
|
52
|
+
A missing base targets the repository's default branch, which may not be where the change goes.
|
|
53
|
+
|
|
54
|
+
The body names the issue the way the project's rules say. `Closes #N` closes it only when the pull request reaches
|
|
55
|
+
the default branch. Follow the project's rule on signatures in commits and pull requests: add no agent signature
|
|
56
|
+
the project does not ask for.
|
|
53
57
|
|
|
54
58
|
## 3. Claims about public state
|
|
55
59
|
|
|
@@ -79,4 +83,4 @@ Where the tool has a dry run, run it first and show it; then run the real action
|
|
|
79
83
|
## 5. Hand over
|
|
80
84
|
|
|
81
85
|
End with the `report-back` skill: a done report, or a handoff by pointer when the work passes to another
|
|
82
|
-
session (the card, the commits and the pull request by path or link, never copied). Where the work has a work item, the pull request
|
|
86
|
+
session (the card, the commits and the pull request by path or link, never copied). Where the work has a work item, the pull request names it, its acceptance criteria are the checklist, and the item is updated rather than a local file written.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.8",
|
|
4
4
|
"description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
|
|
6
6
|
"bugs": {
|
|
@@ -44,8 +44,8 @@
|
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
46
|
"@clack/prompts": "1.8.1",
|
|
47
|
-
"@venizia/vulcan-atlas": "0.4.
|
|
48
|
-
"@venizia/vulcan-okf": "0.4.
|
|
47
|
+
"@venizia/vulcan-atlas": "0.4.8",
|
|
48
|
+
"@venizia/vulcan-okf": "0.4.8",
|
|
49
49
|
"zod": "^4.6.7"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
package/src/config/schema.ts
CHANGED
|
@@ -275,6 +275,12 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
275
275
|
typescriptFrom: removedAtlasKey({ key: 'typescriptFrom' }),
|
|
276
276
|
legacyTagPrefixes: removedAtlasKey({ key: 'legacyTagPrefixes' }),
|
|
277
277
|
tagPattern: RELEASE_TEMPLATE.default('<dir>-v<version>'),
|
|
278
|
+
/**
|
|
279
|
+
* Templates of an earlier tag layout that are still releases: atlas and the changelog check read a tag
|
|
280
|
+
* through `tagPattern` first and then through each of these, so a rename of the tags keeps the old
|
|
281
|
+
* releases. Unlike `ignoreTags`, a tag matched here counts as a release.
|
|
282
|
+
*/
|
|
283
|
+
legacyTagPatterns: z.array(RELEASE_TEMPLATE).optional(),
|
|
278
284
|
sources: z
|
|
279
285
|
.array(
|
|
280
286
|
z.strictObject({
|
|
@@ -68,6 +68,16 @@ export class HookConstants {
|
|
|
68
68
|
* Spelt out here because the blocking hooks import nothing that reads the package (a test holds the two equal).
|
|
69
69
|
*/
|
|
70
70
|
static readonly PROJECT_TMP = '.agents/local/tmp';
|
|
71
|
+
/**
|
|
72
|
+
* The scratchpad folder an agent tool offers a session sits under the system temp directory (Claude Code:
|
|
73
|
+
* `/tmp/claude-<uid>/<project>/<session>/scratchpad`), so guard-outside denies a write there instead of asking.
|
|
74
|
+
* The folder itself and everything below it; the tool's sibling folders (`tasks`) are not covered.
|
|
75
|
+
* Only this Linux path is covered; another system's folder was not verified.
|
|
76
|
+
*/
|
|
77
|
+
static readonly AGENT_TOOL_SCRATCHPAD_PATTERNS = [
|
|
78
|
+
'/tmp/claude-[0-9]*/*/*/scratchpad',
|
|
79
|
+
'/tmp/claude-[0-9]*/*/*/scratchpad/**',
|
|
80
|
+
];
|
|
71
81
|
/** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
|
|
72
82
|
static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
|
|
73
83
|
static readonly KILL_SWITCH_OFF = 'off';
|
package/src/hooks/guard-git.ts
CHANGED
|
@@ -250,13 +250,61 @@ const inspectBranch = (opts: {
|
|
|
250
250
|
return hits;
|
|
251
251
|
};
|
|
252
252
|
|
|
253
|
+
/** Options of `gh` that take a value, which `ghCall` skips together with it. */
|
|
254
|
+
const GH_OPTIONS_WITH_VALUE = new Set(['-R', '--repo', '--hostname']);
|
|
255
|
+
|
|
256
|
+
/** Options of `gh pr create` that take a value: a word after one is its value, never an option. */
|
|
257
|
+
const GH_CREATE_OPTIONS_WITH_VALUE = new Set([
|
|
258
|
+
'--title',
|
|
259
|
+
'-t',
|
|
260
|
+
'--body',
|
|
261
|
+
'-b',
|
|
262
|
+
'--body-file',
|
|
263
|
+
'-F',
|
|
264
|
+
'--head',
|
|
265
|
+
'-H',
|
|
266
|
+
'--assignee',
|
|
267
|
+
'-a',
|
|
268
|
+
'--label',
|
|
269
|
+
'-l',
|
|
270
|
+
'--milestone',
|
|
271
|
+
'-m',
|
|
272
|
+
'--project',
|
|
273
|
+
'-p',
|
|
274
|
+
'--reviewer',
|
|
275
|
+
'-r',
|
|
276
|
+
'--template',
|
|
277
|
+
'-T',
|
|
278
|
+
]);
|
|
279
|
+
|
|
280
|
+
/** The group, the action and the words after them of a `gh` line, past options such as `-R <repo>`. */
|
|
281
|
+
const ghCall = (opts: { args: string[] }): { group: string; action: string; rest: string[] } => {
|
|
282
|
+
const names: string[] = [];
|
|
283
|
+
let index = 0;
|
|
284
|
+
|
|
285
|
+
while (index < opts.args.length && names.length < 2) {
|
|
286
|
+
const word = opts.args[index];
|
|
287
|
+
|
|
288
|
+
if (GH_OPTIONS_WITH_VALUE.has(word)) {
|
|
289
|
+
index += 2;
|
|
290
|
+
} else if (word.startsWith('-')) {
|
|
291
|
+
index += 1;
|
|
292
|
+
} else {
|
|
293
|
+
names.push(word);
|
|
294
|
+
index += 1;
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
return { group: names[0] ?? '', action: names[1] ?? '', rest: opts.args.slice(index) };
|
|
299
|
+
};
|
|
300
|
+
|
|
253
301
|
/** `gh pr merge [<pr>] --delete-branch`: the PR's head branch decides, and `gh` is asked for it. */
|
|
254
302
|
const inspectGhMerge = (opts: {
|
|
255
303
|
args: string[];
|
|
256
304
|
cwd: string | undefined;
|
|
257
305
|
run: IGitRunner;
|
|
258
306
|
}): IGitHit[] => {
|
|
259
|
-
const
|
|
307
|
+
const { group, action, rest } = ghCall({ args: opts.args });
|
|
260
308
|
|
|
261
309
|
if (group !== 'pr' || action !== 'merge') {
|
|
262
310
|
return [];
|
|
@@ -294,6 +342,45 @@ const inspectGhMerge = (opts: {
|
|
|
294
342
|
: [];
|
|
295
343
|
};
|
|
296
344
|
|
|
345
|
+
/**
|
|
346
|
+
* `gh pr create` with no base: the pull request would target the repository's default branch, which may not be
|
|
347
|
+
* the branch the project's changes go to (a project whose default is `main` takes its features on `develop`).
|
|
348
|
+
* `--help` only reads.
|
|
349
|
+
*/
|
|
350
|
+
const inspectGhCreate = (opts: { args: string[] }): IGitHit[] => {
|
|
351
|
+
const { group, action, rest } = ghCall({ args: opts.args });
|
|
352
|
+
|
|
353
|
+
if (group !== 'pr' || (action !== 'create' && action !== 'new')) {
|
|
354
|
+
return [];
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
let namesBase = false;
|
|
358
|
+
|
|
359
|
+
for (let index = 0; index < rest.length; index += 1) {
|
|
360
|
+
const word = rest[index];
|
|
361
|
+
|
|
362
|
+
if (word === '--base' || word.startsWith('--base=') || word.startsWith('-B')) {
|
|
363
|
+
namesBase = true;
|
|
364
|
+
break;
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
if (GH_CREATE_OPTIONS_WITH_VALUE.has(word)) {
|
|
368
|
+
index += 1;
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
return namesBase || rest.includes('--help') || rest.includes('-h')
|
|
373
|
+
? []
|
|
374
|
+
: [
|
|
375
|
+
{
|
|
376
|
+
decision: GuardDecisions.ASK,
|
|
377
|
+
rule: 'V-W-06',
|
|
378
|
+
message:
|
|
379
|
+
"'gh pr create' names no --base, so the pull request targets the default branch; pass --base <branch>",
|
|
380
|
+
},
|
|
381
|
+
];
|
|
382
|
+
};
|
|
383
|
+
|
|
297
384
|
const inspectOne = (opts: {
|
|
298
385
|
command: ISimpleCommand;
|
|
299
386
|
cwd: string | undefined;
|
|
@@ -304,7 +391,10 @@ const inspectOne = (opts: {
|
|
|
304
391
|
const name = basenameOf({ word: program.name });
|
|
305
392
|
|
|
306
393
|
if (name === 'gh') {
|
|
307
|
-
return
|
|
394
|
+
return [
|
|
395
|
+
...inspectGhMerge({ args: program.args, cwd: opts.cwd, run: opts.run }),
|
|
396
|
+
...inspectGhCreate({ args: program.args }),
|
|
397
|
+
];
|
|
308
398
|
}
|
|
309
399
|
|
|
310
400
|
if (name !== 'git') {
|
|
@@ -103,7 +103,7 @@ const allowPatterns = (opts: { patterns: string[]; home: string; env: TEnvironme
|
|
|
103
103
|
return [concrete, /[*?[]/.test(concrete) ? concrete : `${concrete}/**`];
|
|
104
104
|
});
|
|
105
105
|
|
|
106
|
-
const
|
|
106
|
+
const matchesAny = (opts: { path: string; patterns: string[] }): boolean =>
|
|
107
107
|
opts.patterns.some((pattern) => new Bun.Glob(pattern).match(opts.path));
|
|
108
108
|
|
|
109
109
|
interface ITarget {
|
|
@@ -409,6 +409,7 @@ export const inspectOutside = (opts: {
|
|
|
409
409
|
path: '(the command line)',
|
|
410
410
|
message:
|
|
411
411
|
'this command line is larger, or nests deeper, than the guard reads, so it could not be checked',
|
|
412
|
+
isAgentToolScratchpad: false,
|
|
412
413
|
},
|
|
413
414
|
]
|
|
414
415
|
: [];
|
|
@@ -422,8 +423,15 @@ export const inspectOutside = (opts: {
|
|
|
422
423
|
|
|
423
424
|
const path = realOf({ path: resolve(target.base, expanded) });
|
|
424
425
|
|
|
425
|
-
if (!isInside({ path, root }) && !
|
|
426
|
-
hits.push({
|
|
426
|
+
if (!isInside({ path, root }) && !matchesAny({ path, patterns })) {
|
|
427
|
+
hits.push({
|
|
428
|
+
path,
|
|
429
|
+
message: target.message,
|
|
430
|
+
isAgentToolScratchpad: matchesAny({
|
|
431
|
+
path,
|
|
432
|
+
patterns: HookConstants.AGENT_TOOL_SCRATCHPAD_PATTERNS,
|
|
433
|
+
}),
|
|
434
|
+
});
|
|
427
435
|
}
|
|
428
436
|
}
|
|
429
437
|
|
|
@@ -99,7 +99,7 @@ export const buildSessionDigest = async (opts: {
|
|
|
99
99
|
'',
|
|
100
100
|
'## Temporary files',
|
|
101
101
|
'',
|
|
102
|
-
`Scratch and temporary files go in \`${projectTmpOf({ root: opts.projectRoot })}\`, never /tmp (V-B-08). In Claude Code every Bash command already runs with \`TMPDIR\` set to it; in any other agent run \`export TMPDIR=${projectTmpOf({ root: opts.projectRoot })}\` first. Remove what you made when the task ends.`,
|
|
102
|
+
`Scratch and temporary files go in \`${projectTmpOf({ root: opts.projectRoot })}\`, never /tmp (V-B-08). The scratchpad folder your tool offers is under /tmp too: do not use it, this rule wins over the tool's line. In Claude Code every Bash command already runs with \`TMPDIR\` set to it; in any other agent run \`export TMPDIR=${projectTmpOf({ root: opts.projectRoot })}\` first. Remove what you made when the task ends.`,
|
|
103
103
|
'',
|
|
104
104
|
"## This project's slot choices",
|
|
105
105
|
'',
|
|
@@ -14,7 +14,7 @@ export const SUBAGENT_CARD = [
|
|
|
14
14
|
'',
|
|
15
15
|
'- Read-only unless your brief says otherwise. No git writes (V-W-01, V-P-12).',
|
|
16
16
|
'- Never write a database, deploy, or touch secrets; ask before anything irreversible (V-W-02, V-W-03, V-W-04).',
|
|
17
|
-
'- Everything you create (scratch, clones, logs, output) goes under `.agents/local/`, never `/tmp
|
|
17
|
+
'- Everything you create (scratch, clones, logs, output) goes under `.agents/local/`, never `/tmp`, the home folder or the scratchpad folder your tool offers (it is under `/tmp`; this rule wins); remove it when done (V-B-08).',
|
|
18
18
|
'- Reuse before you write: look for what already does the job (V-P-08).',
|
|
19
19
|
'- Small never cuts safety: keep validation, error handling and security checks (V-B-06).',
|
|
20
20
|
'- Say what you skipped or could not check; a check that did not run never reads as one that did (V-B-07).',
|
package/src/manifest/render.ts
CHANGED
|
@@ -111,6 +111,10 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
|
|
|
111
111
|
},
|
|
112
112
|
release: {
|
|
113
113
|
tagPattern: config.atlas.tagPattern,
|
|
114
|
+
...(config.atlas.legacyTagPatterns === undefined ||
|
|
115
|
+
config.atlas.legacyTagPatterns.length === 0
|
|
116
|
+
? {}
|
|
117
|
+
: { legacyTagPatterns: config.atlas.legacyTagPatterns }),
|
|
114
118
|
ignoreTags: config.atlas.ignoreTags ?? [],
|
|
115
119
|
},
|
|
116
120
|
rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
|