@venizia/vulcan 0.4.10-1 → 0.4.10-2

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.
Files changed (60) hide show
  1. package/base/claude/events.json +0 -1
  2. package/base/hooks/event.ts +4 -3
  3. package/base/rules.md +1 -1
  4. package/base/skills/build-a-feature/SKILL.md +11 -2
  5. package/base/skills/review-a-change/SKILL.md +10 -6
  6. package/base/skills/ship/SKILL.md +9 -4
  7. package/base/templates/board.html +835 -4399
  8. package/base/templates/pull-request.md +31 -0
  9. package/base/templates/trusted-hosts.local.example +11 -0
  10. package/base/templates/vulcan.config.mts +1 -0
  11. package/package.json +6 -4
  12. package/src/board/agent-setting.ts +43 -0
  13. package/src/board/command.ts +138 -17
  14. package/src/board/common/constants.ts +38 -1
  15. package/src/board/common/types.ts +29 -1
  16. package/src/board/fold.ts +80 -9
  17. package/src/board/github.ts +6 -3
  18. package/src/board/index.ts +2 -0
  19. package/src/board/schema.ts +32 -0
  20. package/src/board/server.ts +325 -0
  21. package/src/board/settings.ts +99 -17
  22. package/src/board/watch.ts +88 -0
  23. package/src/commands/help.command.ts +4 -3
  24. package/src/commands/init.command.ts +26 -1
  25. package/src/common/constants.ts +8 -0
  26. package/src/common/git-files.ts +11 -0
  27. package/src/common/index.ts +1 -0
  28. package/src/common/layout-folder.ts +1 -1
  29. package/src/config/schema.ts +21 -11
  30. package/src/create/common/constants.ts +1 -0
  31. package/src/create/dockerignore.ts +5 -3
  32. package/src/create/init-monorepo.ts +28 -4
  33. package/src/create/project-key.ts +60 -0
  34. package/src/create/workspace.ts +2 -1
  35. package/src/doctor/checks.ts +89 -2
  36. package/src/doctor/common/constants.ts +48 -0
  37. package/src/doctor/common/types.ts +2 -1
  38. package/src/doctor/index.ts +2 -0
  39. package/src/doctor/private-values.ts +108 -0
  40. package/src/doctor/runner.ts +4 -0
  41. package/src/doctor/schema.ts +29 -0
  42. package/src/events/actor.ts +10 -5
  43. package/src/events/command.ts +209 -19
  44. package/src/events/common/constants.ts +96 -6
  45. package/src/events/common/types.ts +18 -0
  46. package/src/events/flow-id.ts +89 -0
  47. package/src/events/flow.ts +4 -4
  48. package/src/events/hook.ts +53 -6
  49. package/src/events/index.ts +2 -0
  50. package/src/events/log.ts +78 -3
  51. package/src/events/project-key.ts +22 -0
  52. package/src/events/retention.ts +2 -4
  53. package/src/events/settings.ts +16 -0
  54. package/src/events/text.ts +23 -0
  55. package/src/init/common/constants.ts +1 -0
  56. package/src/init/scaffold.ts +39 -7
  57. package/src/manifest/render.ts +5 -1
  58. package/src/router.ts +9 -2
  59. package/src/sync/claude-launch.ts +62 -7
  60. package/src/wiki/source-links.ts +5 -4
@@ -46,7 +46,6 @@
46
46
  ],
47
47
  "PostToolUse": [
48
48
  {
49
- "matcher": "SendMessage",
50
49
  "hooks": [
51
50
  {
52
51
  "type": "command",
@@ -1,7 +1,8 @@
1
1
  /**
2
- * Event log hook (SessionStart, Stop, SubagentStop, Notification, PostToolUse on SendMessage): appends one
3
- * line to the agent event log (src/events/hook.ts) when the manifest says `events.log` is on. It stores
4
- * names and short labels only - never a message body, the last reply, a command or a file path.
2
+ * Event log hook (SessionStart, Stop, SubagentStop, Notification and PostToolUse: a SendMessage is a message,
3
+ * any other tool at most one tick per session every 30 seconds): appends one line to the agent event log
4
+ * (src/events/hook.ts) when the manifest says `events.log` is on. It stores names and short labels only -
5
+ * never a message body, the last reply, a command, a path or anything of a tool's input or result.
5
6
  *
6
7
  * It fails OPEN and says nothing on stdout: input it cannot read, a missing module or a write that fails
7
8
  * pass with a note on stderr, and the agent is never held. It imports only the events module, no config and
package/base/rules.md CHANGED
@@ -49,7 +49,7 @@ An ID the base drops is never reused.
49
49
  | V-P-10 | **Ask once, with a recommendation.** All open decisions in one numbered round, each with a recommended answer worded so that "yes" accepts it; never ask for a fact you can look up; for a reversible choice state the default in one line and continue, only inside what V-P-02, V-P-03 and V-W-06 already allow; stop for an action they reserve, a plan awaiting approval, a change of shape, or a real fork. | SOFT |
50
50
  | V-P-11 | **Reports: answer first, in the reader's form.** Two lines before any detail; evidence as a table, not prose; a long report goes in a file and the message carries the path. The reader decides the form: the owner gets the project's report shape in their own language, with labels and form of address taken from the `owner` config and their profile, never from fixed words; another agent (a session it started, a cross-session message, a subagent) gets the plain format it asked for and nothing more. | SOFT |
51
51
  | V-P-12 | **Delegate by kind; the brief carries the rules.** Mechanical work (sweeps, greps, renames, gates, counting) goes to a smaller-model subagent; judgment stays with the main agent, which re-checks what comes back. A subagent brief carries the goal, the files, read-only by default, "no git writes", the report shape and a size under 400 words, and the rules digest reaches the subagent (through the tool's subagent-start hook where one exists, otherwise in the brief); the template is `node_modules/@venizia/vulcan/base/references/delegation-brief.md`. | SOFT - the brief; a subagent-start hook where the tool has one |
52
- | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). When you start work that belongs to a flow (`F-n`), log it, in the owner's language: `vulcan event add --kind flow --flow F-n --title "<a title the owner reads>" --why "<one line, why it exists>" --context "<2-4 sentences: what this is, what is done, what is left>" --next "<the next step and who does it>"`. Log a new one when the title, the reason, the context or the next step changes materially; the newest line wins as a whole, so repeat the fields that still hold. A board shows the title as the flow's heading, with the reason, context and next step under it; without a flow line it shows the words of its pull request or its first line, marked as having no title yet. | SOFT |
52
+ | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). Work that belongs to a flow starts with the flow: run `vulcan event add --kind flow --title "<a title the owner reads>" --why "<one line, why it exists>" --context "<2-4 sentences: what this is, what is done, what is left>" --next "<the next step and who does it>"` with no `--flow`, in the owner's language. VULCAN gives the flow its id (`VULZ-<project.key>-<number>`) and prints it; use that id on every other line of the flow (`--flow <id>`, `Flow: <id>` in the first line of a message or in a pull request body, the branch name). Never type an id by hand or make one up: a `--flow` that no line of the log carries is refused. Give what is to be done and what must hold as lists, not prose: `--step "<text>"` for a step still to do and `--step-done "<text>"` for one done (the same for acceptance checks with `--check` and `--check-done`), `--app <name>` for each app or module it touches, `--due YYYY-MM-DD`, and `--ref <tracker id>`. To change a flow, run the same command with `--flow <id>`; the newest line wins as a whole, so repeat every list and field that still holds, the lists in the order you want them shown. Log `vulcan event add --kind deploy --flow <id> --summary "<what went live>"` when something is deployed. A board shows the title as the flow's heading, with the reason, context and next step under it; without a flow line it shows the words of its pull request or its first line, marked as having no title yet. | SOFT |
53
53
 
54
54
  ## B - Build and quality
55
55
 
@@ -33,7 +33,7 @@ Copy it into your reply and tick each box when its criterion holds:
33
33
  - [ ] 5. Slices built - every slice went red, then green; every import came from `symbol`
34
34
  - [ ] 6. Checks green - typecheck, lint, test, vulcan doctor passed; the real behaviour shown
35
35
  - [ ] 7. Docs and knowledge current - Docs impact delivered, the docs gates green, each changed fact in the bundle
36
- - [ ] 8. Diff reviewed - reviewed as the lane asks, findings dispositioned, summary given with what was skipped
36
+ - [ ] 8. Diff reviewed - checked against the rules and reviewed as the lane asks, findings dispositioned, summary given with what was skipped
37
37
  ```
38
38
 
39
39
  ## 1. Settle the goal
@@ -138,6 +138,14 @@ are green and the bundle matches the change.
138
138
 
139
139
  ## 8. Review and hand over
140
140
 
141
+ First check the whole diff against the rules (code changes; a docs-only or release change needs none). List the
142
+ files of the diff, read the base rules (`rules.md`, the P, C and B sections) and the project's own once, and
143
+ write one line per rule that changed something: the rule id and what you changed because of it. A rule you
144
+ checked that changed nothing is listed by id only. Add one line, "Kept out to stay small": what you did not
145
+ add or removed to keep the change small (`V-C-11`), or "nothing". That list is the "Rules checked" section of
146
+ the pull request (`ship`). The commonest misses are `V-P-08` and `V-C-16` (what already exists, one implementation of
147
+ one concept) and `V-C-18` (derived types).
148
+
141
149
  Review with the `review-a-change` skill: lane L gets an independent, non-forked reviewer per axis; lane
142
150
  M reviews its own diff and may ask for a fresh review; lane S reads the diff once. Refactor here, with the
143
151
  tests green. Fix what the findings adopt, then report with the `report-back` skill: the checks you ran
@@ -145,4 +153,5 @@ and their results, and an end line "Skipped / not checked / shortcuts": what you
145
153
  did not verify, and every `SHORTCUT:` you added - or the words "none" (V-B-07).
146
154
  The user decides when to commit.
147
155
 
148
- Done when the diff is clean, the summary names every check and its result, and the skipped line is there.
156
+ Done when the diff is clean, the rules list is written, the summary names every check and its result, and the
157
+ skipped line is there.
@@ -21,7 +21,7 @@ is read-only: it reports, it does not fix. Nothing is committed.
21
21
  - [ ] 3. Reviewers briefed - parallel, one brief per axis, read-only
22
22
  - [ ] 4. Findings triaged - each verified against the code, then adopted, rebutted or deferred
23
23
  - [ ] 5. Loop closed - fixes, then only the findings re-checked; two rounds at most, never "until clean"
24
- - [ ] 6. Reported - which axes ran, which did not and why
24
+ - [ ] 6. Reported - which axes ran, which did not and why, and the rule ids the Standards pass checked
25
25
  ```
26
26
 
27
27
  ## 1. Fix the point
@@ -43,8 +43,11 @@ axis hide the failing one.
43
43
 
44
44
  - **Spec**: does the diff do what the claims say, nothing more, nothing missing? Look for a claim that is
45
45
  missing or only partly done, scope creep, and work that is implemented but wrong. Quote the claim.
46
- - **Standards**: the base rules and the project's own, plus common smells as judgement calls. Skip what a
47
- linter or formatter already enforces. The project's own standard wins over a general smell.
46
+ - **Standards**: a pass over the rules, then common smells as judgement calls. Read the files the diff
47
+ touches, then the base rules (`rules.md`, the P, C and B sections) and the project's own rules once, and
48
+ judge the whole diff against them. Every rule finding names its rule id (`V-C-16`); a finding with no id is
49
+ a judgement call and says so. Skip what a linter or formatter already enforces. The project's own standard
50
+ wins over a general smell.
48
51
  - **Security** (lane L or a security-class change): injection, secrets in output or logs, authority and
49
52
  permission changes, supply chain.
50
53
 
@@ -57,7 +60,8 @@ Each brief is under 400 words and holds:
57
60
  - the **steps** to take and the **evidence to return** - never the answer you expect to find, because a
58
61
  reviewer told what a pass looks like rationalises toward it;
59
62
  - "read-only: no edits, no git writes";
60
- - a citation rule: every finding cites `path:line` or the claim ID, and no citation means no finding;
63
+ - a citation rule: every finding cites `path:line` or the claim ID, and no citation means no finding; a
64
+ Standards finding also names the rule id it breaks;
61
65
  - "end with a list of what you set aside and did not judge".
62
66
 
63
67
  Start the reviewers in parallel (they are read-only, so they share the checkout), before you read any
@@ -86,5 +90,5 @@ Last, read the diff against the claims for additions no claim asked for. That ch
86
90
 
87
91
  ## 6. Report
88
92
 
89
- Use the `report-back` skill. State which axes ran, which did not and why, every disposition, and the list
90
- of what the reviewers declined to judge. Do not state an overall verdict the axes did not give.
93
+ Use the `report-back` skill. State which axes ran, which did not and why, the rule ids the Standards pass checked, every disposition, and
94
+ the list of what the reviewers declined to judge. Do not state an overall verdict the axes did not give.
@@ -16,7 +16,7 @@ claim has its evidence, the owner knows what was not checked, and nothing shared
16
16
 
17
17
  ```
18
18
  - [ ] 1. Done checklist - every line true, or said not to be
19
- - [ ] 2. PR body written - smallest visual, before and after, checks, the door call
19
+ - [ ] 2. PR body written - smallest visual, before and after, rules checked, checks, the door call
20
20
  - [ ] 3. Public claims - each has a probe run in this session
21
21
  - [ ] 4. Approval - a shared action has the owner's own words naming it
22
22
  - [ ] 5. Handed over - the report, or a pointer for the next session
@@ -32,6 +32,7 @@ It rises with the lane (see `plan-a-change`). A small edit (lane S) ends as `rep
32
32
  - The checks are quoted with their results, from this session: build, lint, tests, the project's own gates.
33
33
  - **Open** (the card's open decisions) is empty, or each item is named for the owner.
34
34
  - The class sweep is done: the same defect was looked for elsewhere, not only where it was found.
35
+ - The rules check is done on a code change (`build-a-feature` step 8): the ids checked and what changed because of them are written down. An empty list on a code change is not done; a docs-only or release change needs none.
35
36
  - Review dispositions are recorded (`review-a-change` skill): adopted, rebutted or deferred, each with a reason.
36
37
  - What was **not** verified is stated plainly (V-B-07). A check that did not run never reads as one that did.
37
38
 
@@ -43,14 +44,18 @@ The body is read by a person who has not seen the work. In this order:
43
44
 
44
45
  1. **What changed**, as the smallest visual that shows it: one table, one before and after, one screenshot.
45
46
  2. **Before and after** of the behaviour, not of the files.
46
- 3. **The checks and their output**, as a table: the command, the result.
47
- 4. **The door call**: a one-way door (a published package, a migration, a deleted branch) or a two-way door
47
+ 3. **Rules checked** (a code change): a table of the rule ids checked, what was looked at and what changed because of the rule, or "nothing" for a rule that changed nothing, and one line "Kept out to stay small": what was not added or was removed to keep the change small (`V-C-11`), or "nothing".
48
+ 4. **The checks and their output**, as a table: the command, the result.
49
+ 5. **The door call**: a one-way door (a published package, a migration, a deleted branch) or a two-way door
48
50
  (revert and it is gone), and the blast radius if it is wrong.
49
- 5. **Not verified**: the items from the checklist.
51
+ 6. **Not verified**: the items from the checklist.
50
52
 
51
53
  Open the pull request with its base named, `gh pr create --base <branch>`. Take the branch from the project's rules.
52
54
  A missing base targets the repository's default branch, which may not be where the change goes.
53
55
 
56
+ A project that has no pull request template can start from `node_modules/@venizia/vulcan/base/templates/pull-request.md`,
57
+ which holds these sections; copy it to the project's own place on the owner's word.
58
+
54
59
  The body names the issue the way the project's rules say. `Closes #N` closes it only when the pull request reaches
55
60
  the default branch. Follow the project's rule on signatures in commits and pull requests: add no agent signature
56
61
  the project does not ask for.