@venizia/vulcan 0.4.6 → 0.4.7
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/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/package.json +3 -3
- package/src/hooks/command-view.ts +24 -0
- package/src/hooks/common/constants.ts +5 -0
- package/src/hooks/guard-git.ts +56 -0
|
@@ -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 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.7",
|
|
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.7",
|
|
48
|
+
"@venizia/vulcan-okf": "0.4.7",
|
|
49
49
|
"zod": "^4.6.7"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
@@ -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
|
/**
|
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;
|
|
@@ -270,6 +322,10 @@ const inspectOne = (opts: {
|
|
|
270
322
|
return inspectBranch({ rest: call.rest, cwd, run: opts.run });
|
|
271
323
|
}
|
|
272
324
|
|
|
325
|
+
if (call.sub === 'add' || call.sub === 'commit') {
|
|
326
|
+
return inspectStage({ sub: call.sub, rest: call.rest, cwd, run: opts.run });
|
|
327
|
+
}
|
|
328
|
+
|
|
273
329
|
if (call.sub === 'update-ref' && call.rest.some((word) => word === '-d' || word === '--delete')) {
|
|
274
330
|
const refs = call.rest.filter((word) => !word.startsWith('-'));
|
|
275
331
|
|