@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.
@@ -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.6",
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.6",
48
- "@venizia/vulcan-okf": "0.4.6",
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
  /**
@@ -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