@venizia/vulcan 0.4.6 → 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.
- 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/plan-a-change/SKILL.md +1 -1
- package/base/skills/plan-a-change/evals/evals.json +6 -0
- package/base/skills/plan-a-change/references/spec-card.md +1 -0
- package/base/skills/ship/SKILL.md +7 -3
- package/package.json +3 -3
- package/src/config/schema.ts +6 -0
- package/src/hooks/command-view.ts +24 -0
- package/src/hooks/common/constants.ts +15 -0
- package/src/hooks/common/types.ts +2 -0
- package/src/hooks/guard-git.ts +148 -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
|
|
@@ -21,7 +21,7 @@ Copy it into your reply and tick each box when its criterion holds:
|
|
|
21
21
|
```
|
|
22
22
|
- [ ] 1. Lane chosen - S, M or L, with the reason in one line
|
|
23
23
|
- [ ] 2. Intake done - the goal restated, what will NOT be done said, every open decision asked once
|
|
24
|
-
- [ ] 3. Card written - goal verbatim, claims each with a probe, out of scope, docs impact
|
|
24
|
+
- [ ] 3. Card written - goal verbatim, claims each with a probe, out of scope, docs impact, who runs each outward action
|
|
25
25
|
- [ ] 4. Design pass - lane L or a trigger below: decisions only where implementers could diverge
|
|
26
26
|
- [ ] 5. Slices planned - each a work item: one behaviour, one seam, its key interfaces, Blocked by and Parent
|
|
27
27
|
- [ ] 6. Handed over - the card shown, the turn ended, nothing started
|
|
@@ -36,6 +36,12 @@
|
|
|
36
36
|
"prompt": "Plan adding a retry option to the HTTP client helper, write the first slice as a work item, then check it cold: give a fresh subagent only the item and the knowledge bundle, ask it whether it could start without asking anything, and fix the item for every gap it names. Do not implement.",
|
|
37
37
|
"expected_output": "Writes the first slice as a work item with the nine fixed English headings; launches a fresh subagent whose brief is the item (by reference, not restated) plus the knowledge bundle and asks the single question whether it could start; the subagent is read-only and its brief names the plain format to return; every gap it reports changes the item (a missing interface name, an untestable criterion, a missing out-of-scope line) and the report says what changed; nothing is implemented",
|
|
38
38
|
"files": []
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"id": 6,
|
|
42
|
+
"prompt": "Plan this: publish the next patch release of the project's package, then close the release issue and delete the temporary probe repository we made for it. Show me the plan, do not start it.",
|
|
43
|
+
"expected_output": "Ends with the plan and starts no work; the card has a Runs by line that names who runs each outward action (the release dispatch, closing the issue, deleting the repository) and marks the ones the session's permission check may refuse as the owner's to run, so the plan hands them over instead of attempting them; goal verbatim, claims with probes, out of scope and docs impact as usual",
|
|
44
|
+
"files": []
|
|
39
45
|
}
|
|
40
46
|
]
|
|
41
47
|
}
|
|
@@ -13,6 +13,7 @@ In this order:
|
|
|
13
13
|
|---|---|
|
|
14
14
|
| Goal | The owner's words, verbatim. It changes only through a dated Decisions line |
|
|
15
15
|
| Out of scope | What is not built, in prose |
|
|
16
|
+
| Runs by | Each outward action the plan needs and who runs it: a release dispatch, creating or deleting a repository, closing an issue, a push to a shared ref, writing a setting. Name the agent, or the owner where the session's permission check may refuse the action; the plan then stops there and hands it over instead of finding out mid-run. Left out when the plan has none |
|
|
16
17
|
| Claims | `C1..Cn`: one observable behaviour each, and for each the probe that would show it false. Behaviour is phrased WHEN ... THEN ... |
|
|
17
18
|
| Anti-claims | What must not happen, in the universal form where you can ("no X in any path"). Lane L has at least one |
|
|
18
19
|
| Seams | The public boundaries tests attach to. An existing seam is preferred; the ideal count is one |
|
|
@@ -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-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.
|
|
48
|
-
"@venizia/vulcan-okf": "0.4.
|
|
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": {
|
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({
|
|
@@ -30,6 +30,15 @@ const READ_ONLY_PROGRAMS = new Set([
|
|
|
30
30
|
/** Programs whose arguments are messages and titles for the write guards (a commit message, an issue body). */
|
|
31
31
|
const MESSAGE_PROGRAMS = new Set(['git', 'gh']);
|
|
32
32
|
|
|
33
|
+
/**
|
|
34
|
+
* The `gh` subcommands whose arguments are a request and not a message: the project's own patterns match them
|
|
35
|
+
* (`gh api -X PUT .../rulesets`, `gh secret set`). The arguments of every other `gh` subcommand stay data.
|
|
36
|
+
*/
|
|
37
|
+
const GH_REQUESTS = new Set(['api', 'secret', 'variable']);
|
|
38
|
+
|
|
39
|
+
/** The `gh` options that take the repository as their value: that value is not the subcommand. */
|
|
40
|
+
const GH_REPOSITORY_FLAGS = new Set(['-R', '--repo']);
|
|
41
|
+
|
|
33
42
|
/** `find` runs a command only with these; without them it only lists. */
|
|
34
43
|
const FIND_RUNS = new Set(['-exec', '-execdir', '-ok', '-okdir', '-delete']);
|
|
35
44
|
|
|
@@ -54,6 +63,17 @@ const HEREDOC_READERS = new Set([
|
|
|
54
63
|
const PIPED_INTO_RUNNER =
|
|
55
64
|
/\|\s*(?:sudo\s+)?(?:sh|bash|zsh|dash|psql|mysql|mongosh|sqlite3|python3?|node|bun|ssh)\b/;
|
|
56
65
|
|
|
66
|
+
/** Whether a `gh` command is a request: its subcommand (the first word that is not an option or an option's value) is one of `GH_REQUESTS`. */
|
|
67
|
+
const isGhRequest = (opts: { command: ISimpleCommand }): boolean => {
|
|
68
|
+
const { args } = programOf({ command: opts.command });
|
|
69
|
+
const subcommand = args.find(
|
|
70
|
+
(word, index) =>
|
|
71
|
+
!word.startsWith('-') && !(index > 0 && GH_REPOSITORY_FLAGS.has(args[index - 1] ?? '')),
|
|
72
|
+
);
|
|
73
|
+
|
|
74
|
+
return subcommand !== undefined && GH_REQUESTS.has(subcommand);
|
|
75
|
+
};
|
|
76
|
+
|
|
57
77
|
/**
|
|
58
78
|
* Whether the arguments of a command are data. `withMessages` adds `git` and `gh` (their arguments are
|
|
59
79
|
* messages to the write guards, but a `git` remote is a host to the remote-host guard).
|
|
@@ -65,6 +85,10 @@ export const isDataOnly = (opts: { command: ISimpleCommand; withMessages: boolea
|
|
|
65
85
|
return !opts.command.words.some((word) => FIND_RUNS.has(word));
|
|
66
86
|
}
|
|
67
87
|
|
|
88
|
+
if (name === 'gh' && isGhRequest({ command: opts.command })) {
|
|
89
|
+
return false;
|
|
90
|
+
}
|
|
91
|
+
|
|
68
92
|
return READ_ONLY_PROGRAMS.has(name) || (opts.withMessages && MESSAGE_PROGRAMS.has(name));
|
|
69
93
|
};
|
|
70
94
|
|
|
@@ -56,6 +56,11 @@ export class HookConstants {
|
|
|
56
56
|
static readonly QUERY_TIMEOUT_MS = 5000;
|
|
57
57
|
/** The `git` and `gh` queries one command line may make; past it the guard asks instead of querying on. */
|
|
58
58
|
static readonly MAX_QUERIES = 4;
|
|
59
|
+
/**
|
|
60
|
+
* A blanket stage (`git add -A`, `git commit -a`) asks past this many changed paths. A formatter run once put 152
|
|
61
|
+
* unintended files into one commit; on this repository's develop the median commit touches 7 files and 2.2% touch more than 50.
|
|
62
|
+
*/
|
|
63
|
+
static readonly BLANKET_STAGE_PATHS = 50;
|
|
59
64
|
/** Branches no agent deletes or force-pushes (V-W-06). */
|
|
60
65
|
static readonly PROTECTED_BRANCHES = new Set(['develop', 'main']);
|
|
61
66
|
/**
|
|
@@ -63,6 +68,16 @@ export class HookConstants {
|
|
|
63
68
|
* Spelt out here because the blocking hooks import nothing that reads the package (a test holds the two equal).
|
|
64
69
|
*/
|
|
65
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
|
+
];
|
|
66
81
|
/** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
|
|
67
82
|
static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
|
|
68
83
|
static readonly KILL_SWITCH_OFF = 'off';
|
package/src/hooks/guard-git.ts
CHANGED
|
@@ -133,6 +133,58 @@ const inspectPush = (opts: {
|
|
|
133
133
|
return hits;
|
|
134
134
|
};
|
|
135
135
|
|
|
136
|
+
/**
|
|
137
|
+
* `git add -A`, `--all`, `.`, `-u` and `git commit -a` stage every change, a formatter's or a generator's included. Past
|
|
138
|
+
* `HookConstants.BLANKET_STAGE_PATHS` changed paths the guard asks, so the files are named. A stage of named paths, `-p` and a
|
|
139
|
+
* status that cannot be read pass: the guard asks, it does not deny, and it is not a sandbox.
|
|
140
|
+
*/
|
|
141
|
+
const inspectStage = (opts: {
|
|
142
|
+
sub: string;
|
|
143
|
+
rest: string[];
|
|
144
|
+
cwd: string | undefined;
|
|
145
|
+
run: IGitRunner;
|
|
146
|
+
}): IGitHit[] => {
|
|
147
|
+
const flags = opts.rest.filter((word) => word.startsWith('-') && word !== '--');
|
|
148
|
+
const paths = opts.rest.filter((word) => !word.startsWith('-'));
|
|
149
|
+
const everything =
|
|
150
|
+
opts.sub === 'add' &&
|
|
151
|
+
(flags.some((flag) => flag === '--all' || /^-[a-zA-Z]*A[a-zA-Z]*$/.test(flag)) ||
|
|
152
|
+
paths.includes('.')) &&
|
|
153
|
+
paths.every((path) => path === '.');
|
|
154
|
+
const tracked =
|
|
155
|
+
(opts.sub === 'add' && flags.some((flag) => flag === '-u' || flag === '--update')) ||
|
|
156
|
+
(opts.sub === 'commit' &&
|
|
157
|
+
flags.some((flag) => flag === '--all' || /^-[a-zA-Z]*a[a-zA-Z]*$/.test(flag)));
|
|
158
|
+
|
|
159
|
+
if (!everything && !tracked) {
|
|
160
|
+
return [];
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// One line per file: the default status prints a new folder as one line, which would undercount what `git add -A` takes.
|
|
164
|
+
const status = opts.run({
|
|
165
|
+
program: 'git',
|
|
166
|
+
args: ['status', '--porcelain', '--untracked-files=all'],
|
|
167
|
+
cwd: opts.cwd,
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
if (status === undefined) {
|
|
171
|
+
return [];
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
const lines = status.split('\n').filter((line) => line.length > 0);
|
|
175
|
+
const count = (everything ? lines : lines.filter((line) => !line.startsWith('??'))).length;
|
|
176
|
+
|
|
177
|
+
return count > HookConstants.BLANKET_STAGE_PATHS
|
|
178
|
+
? [
|
|
179
|
+
{
|
|
180
|
+
decision: GuardDecisions.ASK,
|
|
181
|
+
rule: 'V-W-06',
|
|
182
|
+
message: `this stages ${count} changed paths at once (more than ${HookConstants.BLANKET_STAGE_PATHS}), a formatter's or a generator's included; name the files you mean`,
|
|
183
|
+
},
|
|
184
|
+
]
|
|
185
|
+
: [];
|
|
186
|
+
};
|
|
187
|
+
|
|
136
188
|
const inspectBranch = (opts: {
|
|
137
189
|
rest: string[];
|
|
138
190
|
cwd: string | undefined;
|
|
@@ -198,13 +250,61 @@ const inspectBranch = (opts: {
|
|
|
198
250
|
return hits;
|
|
199
251
|
};
|
|
200
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
|
+
|
|
201
301
|
/** `gh pr merge [<pr>] --delete-branch`: the PR's head branch decides, and `gh` is asked for it. */
|
|
202
302
|
const inspectGhMerge = (opts: {
|
|
203
303
|
args: string[];
|
|
204
304
|
cwd: string | undefined;
|
|
205
305
|
run: IGitRunner;
|
|
206
306
|
}): IGitHit[] => {
|
|
207
|
-
const
|
|
307
|
+
const { group, action, rest } = ghCall({ args: opts.args });
|
|
208
308
|
|
|
209
309
|
if (group !== 'pr' || action !== 'merge') {
|
|
210
310
|
return [];
|
|
@@ -242,6 +342,45 @@ const inspectGhMerge = (opts: {
|
|
|
242
342
|
: [];
|
|
243
343
|
};
|
|
244
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
|
+
|
|
245
384
|
const inspectOne = (opts: {
|
|
246
385
|
command: ISimpleCommand;
|
|
247
386
|
cwd: string | undefined;
|
|
@@ -252,7 +391,10 @@ const inspectOne = (opts: {
|
|
|
252
391
|
const name = basenameOf({ word: program.name });
|
|
253
392
|
|
|
254
393
|
if (name === 'gh') {
|
|
255
|
-
return
|
|
394
|
+
return [
|
|
395
|
+
...inspectGhMerge({ args: program.args, cwd: opts.cwd, run: opts.run }),
|
|
396
|
+
...inspectGhCreate({ args: program.args }),
|
|
397
|
+
];
|
|
256
398
|
}
|
|
257
399
|
|
|
258
400
|
if (name !== 'git') {
|
|
@@ -270,6 +412,10 @@ const inspectOne = (opts: {
|
|
|
270
412
|
return inspectBranch({ rest: call.rest, cwd, run: opts.run });
|
|
271
413
|
}
|
|
272
414
|
|
|
415
|
+
if (call.sub === 'add' || call.sub === 'commit') {
|
|
416
|
+
return inspectStage({ sub: call.sub, rest: call.rest, cwd, run: opts.run });
|
|
417
|
+
}
|
|
418
|
+
|
|
273
419
|
if (call.sub === 'update-ref' && call.rest.some((word) => word === '-d' || word === '--delete')) {
|
|
274
420
|
const refs = call.rest.filter((word) => !word.startsWith('-'));
|
|
275
421
|
|
|
@@ -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() },
|