@venizia/vulcan 0.4.7 → 0.4.8-0

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.
@@ -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 and `branch -D` of an unmerged branch (ask).
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
- 'This would create files outside the project (V-B-08):',
56
- ...hits.map((hit) => ` - ${hit.message} (${hit.path})`),
57
- '',
58
- '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. Use that place, or confirm only if the owner asked for this exact path.',
59
- 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
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); no network beyond what the task needs.
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 own internal files are outside this rule's reach. | SOFT |
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
- The issue is closed by the body (`Closes #N`). Follow the project's rule on signatures in commits and
52
- pull requests: add no agent signature the project does not ask for.
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 closes it, its acceptance criteria are the checklist, and the item is updated rather than a local file written.
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.7",
3
+ "version": "0.4.8-0",
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.7",
48
- "@venizia/vulcan-okf": "0.4.7",
47
+ "@venizia/vulcan-atlas": "0.4.8-0",
48
+ "@venizia/vulcan-okf": "0.4.8-0",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
@@ -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';
@@ -54,4 +54,6 @@ export type IGitRunner = (opts: {
54
54
  export interface IOutsideHit {
55
55
  path: string;
56
56
  message: string;
57
+ /** Whether the path is under the scratchpad folder an agent tool offers: the hook denies it, it does not ask. */
58
+ isAgentToolScratchpad: boolean;
57
59
  }
@@ -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 [group, action, ...rest] = opts.args;
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 inspectGhMerge({ args: program.args, cwd: opts.cwd, run: opts.run });
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 isAllowed = (opts: { path: string; patterns: string[] }): boolean =>
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 }) && !isAllowed({ path, patterns })) {
426
- hits.push({ path, message: target.message });
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` or the home folder; remove it when done (V-B-08).',
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).',
@@ -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() },