@venizia/vulcan 0.4.10-1 → 0.4.10-3

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 (93) hide show
  1. package/README.md +19 -14
  2. package/base/claude/events.json +0 -1
  3. package/base/hooks/event.ts +4 -3
  4. package/base/hooks/guard-outside.ts +6 -17
  5. package/base/hooks/guard-writes.ts +3 -24
  6. package/base/rules.md +3 -3
  7. package/base/skills/build-a-feature/SKILL.md +11 -2
  8. package/base/skills/review-a-change/SKILL.md +10 -6
  9. package/base/skills/ship/SKILL.md +9 -4
  10. package/base/skills/visualize-work/SKILL.md +1 -1
  11. package/base/skills/visualize-work/references/spec.md +1 -1
  12. package/base/templates/board.html +835 -4399
  13. package/base/templates/pull-request.md +31 -0
  14. package/base/templates/trusted-hosts.local.example +11 -0
  15. package/base/templates/vulcan.config.mts +1 -0
  16. package/package.json +6 -4
  17. package/src/agents/resolve.ts +1 -0
  18. package/src/board/agent-setting.ts +43 -0
  19. package/src/board/command.ts +138 -17
  20. package/src/board/common/constants.ts +38 -1
  21. package/src/board/common/types.ts +30 -2
  22. package/src/board/fold.ts +80 -9
  23. package/src/board/github.ts +6 -3
  24. package/src/board/index.ts +2 -0
  25. package/src/board/schema.ts +35 -0
  26. package/src/board/server.ts +325 -0
  27. package/src/board/settings.ts +99 -17
  28. package/src/board/watch.ts +88 -0
  29. package/src/commands/help.command.ts +2 -62
  30. package/src/commands/init.command.ts +26 -1
  31. package/src/commands/table.ts +315 -0
  32. package/src/commit/check.ts +1 -0
  33. package/src/commit/common/constants.ts +2 -0
  34. package/src/commit/hook.ts +44 -4
  35. package/src/common/constants.ts +14 -3
  36. package/src/common/env-variables.ts +37 -0
  37. package/src/common/git-files.ts +11 -0
  38. package/src/common/index.ts +2 -0
  39. package/src/common/layout-folder.ts +1 -1
  40. package/src/config/loader.ts +22 -0
  41. package/src/config/schema.ts +142 -15
  42. package/src/create/add-app.ts +5 -0
  43. package/src/create/common/constants.ts +6 -3
  44. package/src/create/dockerignore.ts +5 -3
  45. package/src/create/init-monorepo.ts +28 -4
  46. package/src/create/preset.ts +1 -0
  47. package/src/create/project-key.ts +60 -0
  48. package/src/create/workspace.ts +2 -1
  49. package/src/doctor/checks.ts +99 -2
  50. package/src/doctor/common/constants.ts +74 -0
  51. package/src/doctor/common/types.ts +2 -1
  52. package/src/doctor/index.ts +2 -0
  53. package/src/doctor/private-values.ts +108 -0
  54. package/src/doctor/runner.ts +5 -0
  55. package/src/doctor/schema.ts +33 -0
  56. package/src/events/actor.ts +10 -5
  57. package/src/events/command.ts +209 -19
  58. package/src/events/common/constants.ts +96 -6
  59. package/src/events/common/types.ts +18 -0
  60. package/src/events/flow-id.ts +89 -0
  61. package/src/events/flow.ts +4 -4
  62. package/src/events/hook.ts +53 -6
  63. package/src/events/index.ts +2 -0
  64. package/src/events/log.ts +78 -3
  65. package/src/events/project-key.ts +22 -0
  66. package/src/events/retention.ts +2 -4
  67. package/src/events/settings.ts +16 -0
  68. package/src/events/text.ts +23 -0
  69. package/src/hooks/owner-reply.ts +5 -0
  70. package/src/hooks/project-guards.ts +25 -4
  71. package/src/hooks/session-digest.ts +9 -0
  72. package/src/init/common/constants.ts +1 -0
  73. package/src/init/scaffold.ts +40 -7
  74. package/src/local/auto-clean.ts +2 -1
  75. package/src/local/clean.ts +1 -0
  76. package/src/manifest/render.ts +53 -7
  77. package/src/owner/constants.ts +3 -1
  78. package/src/owner/profile.ts +1 -0
  79. package/src/owner/schema.ts +37 -6
  80. package/src/router.ts +4 -123
  81. package/src/rules/base.ts +1 -0
  82. package/src/signals/loop.ts +1 -0
  83. package/src/skills/frontmatter.ts +1 -0
  84. package/src/sync/claude-launch.ts +62 -7
  85. package/src/sync/planner.ts +1 -0
  86. package/src/theme/index.ts +1 -0
  87. package/src/theme/tokens.ts +305 -0
  88. package/src/ui/prompt.ts +1 -0
  89. package/src/visualize/page.ts +4 -4
  90. package/src/visualize/render.ts +2 -1
  91. package/src/visualize/theme.ts +27 -10
  92. package/src/wiki/anchors.ts +1 -0
  93. package/src/wiki/source-links.ts +5 -4
package/README.md CHANGED
@@ -9,6 +9,8 @@ bun x --no-install vulcan sync
9
9
  bun x --no-install vulcan doctor
10
10
  ```
11
11
 
12
+ `doctor` fails with `[scaffold]` until you describe the project in `.agents/knowledge/index.md` and delete the `vulcan:scaffold` line; it is the first item `init` lists under `left to do`.
13
+
12
14
  `--no-install` matters: the unscoped npm name `vulcan` belongs to an unrelated package, and without the
13
15
  flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
14
16
 
@@ -16,16 +18,26 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
16
18
 
17
19
  | Command | What it does |
18
20
  |---|---|
19
- | `init` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
21
+ | `init` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the two lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, `.agents/hooks/trusted-hosts.local.example`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
20
22
  | `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>]` | Create a new monorepo with its first app from a framework preset: the root manifests, the app's files, the VULCAN layer and a knowledge bundle, then install, `git init` (a missing git is reported, not fatal), `sync` and the checks, and ends with `cd <project> && make dev` and the app's URL. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
21
- | `add --preset <name\|file:path> --app <name> [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app from a preset to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. A frontend says which backend app to proxy `/api` to |
23
+ | `add --preset <name\|file:path> (--app <name> \| --lib <name> \| --shared <name>) [--dir <folder>] [--scope <@scope>] [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app, a library other apps import (`--lib`) or a side-neutral shared package (`--shared`) to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. `--dir` is for a library or a shared package; `--scope` names the package `@scope/<name>`. A frontend says which backend app to proxy `/api` to |
22
24
  | `sync [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; an existing file is left alone), `.claude/settings.json` (shipped + slot + project hooks + `claude.settings` over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed, and a hook it wrote is taken back by its command even after you edited its entry), `.claude/skills/` links, and the committed `.agents/vulcan.manifest.json`. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
23
- | `doctor` | Check the project follows VULCAN; exit 1 on any violation |
25
+ | `preset diff <package>` | Read-only: set each file the preset makes now against the file the package has (same, differs, missing); `--full` prints the diffs, `--check` exits 1 on a difference |
26
+ | `agents [list\|add\|remove\|setup]` | See, add, remove or re-choose the coding agents you use on this machine |
27
+ | `doctor` | Check the project follows VULCAN; exit 1 on any violation. The checks are listed in `docs/wiki/content/references/commands/doctor.md` |
28
+ | `commit-check <message-file> \| --range <revs> \| --text <message>` | Check a commit message against the `commit.message` checks of the config; `sync` installs it as the `commit-msg` hook; exit 1 on a problem, 2 on bad input |
29
+ | `board` | Fold the event log (and GitHub pull requests, checks and reviews when `gh` can read them) into flows and write one HTML file, by default `.agents/local/reports/board.html`; read-only |
30
+ | `ci affected --base <ref> \| template <github\|gitlab>` | List the workspace packages a change touches with the checks each has; `template` prints a CI file that runs exactly those |
31
+ | `event add \| tail` | Write a line to the agent event log (`.agents/local/events/<day>.jsonl`) or read it |
32
+ | `visualize <spec.json>` | Make one small static HTML page from a JSON spec, in `.agents/local/prototypes/` |
33
+ | `profile [show\|edit\|reset]` | Tell VULCAN how you like to work (reply language, tone, habits) in `.agents/local/profile.json` |
34
+ | `clean [--tmp\|--worktrees\|--clones\|--cache\|--all] [--yes]` | List what an agent left under `.agents/local/` (a dry run) and, with `--yes`, remove it |
35
+
24
36
  | `upgrade [--stable \| --nightly] [<version\|tag>]` | Install the target `@venizia/vulcan`, then run `sync` from the newly installed CLI. `--stable` (default) is the `latest` dist-tag, never a prerelease; `--nightly` is the higher of `latest` and `next`; a named version or tag wins over both. `--nightly` that cannot read the dist-tags exits 1; a stable upgrade from an installed prerelease says that `--nightly` keeps the prerelease line |
25
37
  | `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas`. `x --help` prints the help; `x <tool> --help` goes to the tool |
26
38
  | `help`, `version` | |
27
39
 
28
- Diagnostics go to stderr; `vulcan` writes nothing to stdout of its own, so `vulcan x atlas mcp` is a
40
+ Diagnostics go to stderr; a command that produces a result prints only that on stdout, and `vulcan x atlas mcp` is a
29
41
  clean MCP stdio server.
30
42
 
31
43
  ## The project config
@@ -52,8 +64,8 @@ An unknown key is an error; every error names the file and the field.
52
64
 
53
65
  - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (51 rules).
54
66
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
- - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update`, `build-a-feature` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
- - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) `guard-package.ts` (denies a hand-written new `package.json` in a layout folder when a recorded preset has a `vulcan add` command for it, else only warns) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
67
+ - `skills/` - 12 project-neutral skills, described in `docs/wiki/content/references/skills.md` (a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
68
+ - `hooks/` - 16 hook files, described in `docs/wiki/content/references/hooks/index.md`.
57
69
  - `claude/settings.json`, `make/vulcan.mk`, `templates/`.
58
70
 
59
71
  A project **extends** this: it adds rules with bare IDs (the base owns `V-`), skills, hooks and make targets, and never edits
@@ -61,14 +73,7 @@ or shadows a shipped one.
61
73
 
62
74
  ## `doctor` checks
63
75
 
64
- `config` (exactly one valid config) · `layout` (AGENTS.md, rules, knowledge bundle) · `rule-ids` (every
65
- `V-` ID a project rule points at - an `Extends` list or a first cell - is a base rule) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
66
- shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
67
- not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
68
- `manifest` (`.agents/vulcan.manifest.json` exists and matches the config) · `tags` (every release tag `atlas.tagPattern` reads names a declared package, an alias or an ignored tag) ·
69
- `apps` (every `layout` folder is a workspace and every package lives in one; skipped without `layout`) ·
70
- `style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it; the packages are `packages/*` and every configured package `path`) ·
71
- `scaffold` (the config is filled in: a project whose `package.json` declares `workspaces` lists its `packages`, and `.agents/knowledge/index.md` no longer holds the `vulcan:scaffold` line `init` writes).
76
+ `doctor` runs 26 checks; each is described in `docs/wiki/content/references/commands/doctor.md`.
72
77
 
73
78
  The session-start digest prints the base write boundaries, the slot choices, the project's own rules (bold `| **W-00** |` rows and `| V-W-02, V-W-03 |` rows that elaborate base rules), the project's `<!-- minimap-shape:start -->` ... `<!-- minimap-shape:end -->` block from `.agents/rules.md` verbatim, and the `digest.oftenDropped` rules.
74
79
 
@@ -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
@@ -10,9 +10,10 @@
10
10
  * is broken costs more than it protects. So input it cannot read passes, and so does a missing package or
11
11
  * `bun` (the settings wrapper says so on stderr). A guard that started and then failed - a crash or a
12
12
  * timeout, here an internal error or an unloadable module - ASKS instead of passing the call unchecked; a
13
- * project config that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
14
- * read before anything is imported. It imports only the modules it needs - the config loader (and zod) is
15
- * loaded on its own, last, and may fail alone.
13
+ * manifest that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
14
+ * read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
15
+ * from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
16
+ * VULCAN cannot parse, then changes nothing here.
16
17
  */
17
18
 
18
19
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -33,20 +34,8 @@ try {
33
34
 
34
35
  if (input) {
35
36
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
36
- let toolOwnedPaths: string[] = [];
37
- let outside: string = GuardDecisions.ASK;
38
-
39
- try {
40
- const { ConfigLoader } = await import('../../src/config/index.ts');
41
- const loaded = await ConfigLoader.load({ root: projectRoot });
42
-
43
- toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
44
- outside = loaded.ok ? loaded.config.guard.outside : GuardDecisions.ASK;
45
- } catch (error) {
46
- console.error(
47
- `vulcan: the guard-outside hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - the default allowlist applies`,
48
- );
49
- }
37
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
38
+ const { toolOwnedPaths, outside } = ProjectGuards.readPolicy({ root: projectRoot });
50
39
 
51
40
  const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
52
41
 
@@ -4,7 +4,8 @@
4
4
  * The project's own deploy and migrate commands (`guard.writes.commands`) are read from the manifest and
5
5
  * checked beside the fixed list, inside compound commands too.
6
6
  * A script the project lists in `guard.writes.trustedScripts` is not read for writes while git says it
7
- * is tracked and unchanged; a config that cannot be read leaves the list empty, so every script is read.
7
+ * is tracked and unchanged. The list is read from the manifest, never from the config: a config this VULCAN cannot
8
+ * parse changes nothing here.
8
9
  * An entry of `guard.writes.readOnlyScripts` in the manifest (the object form of `trustedScripts`, written by
9
10
  * `vulcan sync`) skips that read for the calls whose first argument after the script is one of its words.
10
11
  *
@@ -22,35 +23,13 @@ try {
22
23
  const stdin = await Bun.stdin.text();
23
24
  const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
24
25
  const cwd = hookCommand?.cwd ?? process.cwd();
25
- let scripts: string[] = [];
26
-
27
- // Only a command that names a .ts file can use the list; the config loader (and zod) loads last, on its
28
- // own, and may fail alone.
29
- if (hookCommand && /\.ts\b/.test(hookCommand.command)) {
30
- try {
31
- const { ConfigLoader } = await import('../../src/config/index.ts');
32
- const loaded = await ConfigLoader.load({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
33
-
34
- // The objects are the read-only entries: the manifest carries them, so only the paths count here.
35
- scripts = loaded.ok
36
- ? loaded.config.guard.writes.trustedScripts.filter(
37
- (entry): entry is string => typeof entry === 'string',
38
- )
39
- : [];
40
- } catch (error) {
41
- console.error(
42
- `vulcan: the guard-writes hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - every script is read`,
43
- );
44
- }
45
- }
46
-
47
26
  const root = process.env.CLAUDE_PROJECT_DIR ?? cwd;
48
27
  const policy = ProjectGuards.readPolicy({ root });
49
28
  const hits = hookCommand
50
29
  ? WriteGuard.inspectCommand({
51
30
  command: hookCommand.command,
52
31
  cwd,
53
- trust: { root, scripts, readOnlyScripts: policy.readOnlyScripts },
32
+ trust: { root, scripts: policy.trustedScripts, readOnlyScripts: policy.readOnlyScripts },
54
33
  extra: policy.commands,
55
34
  })
56
35
  : [];
package/base/rules.md CHANGED
@@ -49,14 +49,14 @@ 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. | SOFT |
53
53
 
54
54
  ## B - Build and quality
55
55
 
56
56
  | ID | Rule | Enforced by |
57
57
  |----|------|-------------|
58
58
  | V-B-01 | TDD: failing test first. | SOFT |
59
- | V-B-02 | The project's lint and test gates pass with zero warnings before "done". | SOFT - pre-commit runs `vulcan doctor` and lint |
59
+ | V-B-02 | The project's lint and test gates pass with zero warnings before "done". | SOFT - the project's own pre-commit, if it has one, runs `vulcan doctor` and lint |
60
60
  | V-B-03 | Run it, read real output, then claim. Evidence before assertions. | SOFT |
61
61
  | V-B-04 | Never green the suite by weakening it: no deleted/skipped tests, loosened asserts, relaxed strictness, `any`. Red test = information. | SOFT |
62
62
  | 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) |
@@ -75,7 +75,7 @@ An ID the base drops is never reused.
75
75
  | V-C-06 | **Never a silent catch - log it.** Always braces. Early return. `switch` with `default` over a long if-else chain. Strict TypeScript; no `any` where a type exists. | LINT (braces, floating promises) + SOFT |
76
76
  | V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`, so the code after it needs none - reach for `assert*` when every caller would throw on `false` anyway. `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
77
77
  | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. When something validates against such a class, it carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (`IsolationLevels` in connectors is the model; a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first); a class nothing validates against needs neither. The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed, and no tool catches it - grep both directions. | SOFT |
78
- | V-C-09 | **Comments state only a lasting fact the code cannot show** - a constraint, an external contract, a non-obvious invariant; one to three lines; no history, no dates, no decision or review notes, no restating the code. An exported declaration may carry a short JSDoc: one summary line, `@param`/`@returns` without `{type}`. Machine directives stay. The one other exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none; remove a meaningless comment in the lines you touch. | SOFT |
78
+ | V-C-09 | **Comments state only a lasting fact the code cannot show** - a constraint, an external contract, a non-obvious invariant; one to three lines; no history, no dates, no decision or review notes, no restating the code. An exported declaration carries TSDoc: plain markdown, a summary first, `@param`/`@returns` without `{type}`, `@default` for a default, `@deprecated` with what replaces it, `@example` when use is not obvious; it sits on the declaration itself (a destructured export has nowhere for it), and it is read by people and agents from the generated reference. TSDoc is exempt from the three-line limit. Machine directives stay. The one other exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none; remove a meaningless comment in the lines you touch. | SOFT |
79
79
  | V-C-10 | **No explicit cast in new code.** `as X`, `as any`, `as unknown as X` and `as never` assert nothing; they silence the compiler where the type is wrong. Fix the type instead: a generic on the setter, a narrower parameter, a typed helper, `satisfies`. A pre-existing cast is removed when the line is touched, never copied. Generic parameters are full words (`ApplicationType`, `TDocument`), never `App` or `TDoc` (V-C-04). | SOFT |
80
80
  | V-C-11 | **SIMPLE FIRST, in code and in prose.** Fewest concepts, plainest words, smallest surface. Complexity must buy correctness, speed or safety the simple version cannot, and the artifact says what it bought. Something a reader cannot follow in one pass is a defect even when it works. Fix the root cause with the smallest change; never layer an abstraction on a misdiagnosed problem. Small means the code holds only what the task needs - not golfed: no clever one-liners to save lines, and no code for a need nobody has yet. | SOFT |
81
81
  | V-C-12 | **Consistent, never self-invented.** Before writing anything new - a constant, file, binding key, error shape - find the nearest precedent in this repo and copy its shape. Binding keys are namespaced (`controllers.X`, `services.X`, `repositories.X`, `datasources.X`). Every scope is one folder with nested `common/{types,constants}.ts` and an index barrel (`inversion` is the model). A second style for something that already has one is a defect. | SOFT |
@@ -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.
@@ -78,7 +78,7 @@ The rules that make a page worth opening:
78
78
  Vietnamese words are bundled; `language` in the spec overrides it). For any other language, translate the
79
79
  words you need into `chrome` (every key is optional); never invent a label set the owner did not give.
80
80
  - **The colour is the project's, not yours**: leave `accent` out. The page uses the project's `theme` (config key,
81
- written into the manifest by `vulcan sync`), else a neutral slate. Give `accent` (and `accentDark`, `accentText`)
81
+ written into the manifest by `vulcan sync`), else the `venizia` preset. Give `accent` (and `accentDark`, `accentText`)
82
82
  only when you draw a page about another project from outside it. A colour that fails the contrast checks is
83
83
  refused, never swapped; state colours (done, waiting, blocked) are fixed and always carry an icon and a word.
84
84
  - **Say where a claim comes from.** A box or step that states how the code works carries a `source`
@@ -39,7 +39,7 @@ Space, Home, End and Escape, one section per slide; print gives one section afte
39
39
  | `schemaVersion` | `1` |
40
40
  | `title` | The takeaway, at most 120 characters |
41
41
  | `language` | A language code (`en`, `pt-BR`); default: the reply language of the owner's profile, else `en`. The page's own words are bundled for `en` and `vi` (a regional code such as `vi-VN` picks `vi`); any other language takes its words from `chrome` |
42
- | `accent`, `accentDark`, `accentText` | Optional six-digit hex colours that override the project's page colour (the `theme` config key, written into the manifest by `vulcan sync`; without one, a neutral slate). Give them only for a page about another project. A colour that fails the contrast checks (text 4.5:1, marks 3:1) is refused, never swapped; with no `accentDark` it is derived by mixing toward white |
42
+ | `accent`, `accentDark`, `accentText` | Optional six-digit hex colours that override the project's page colour (the `theme` config key, written into the manifest by `vulcan sync`; without one, the `venizia` preset). Give them only for a page about another project. A colour that fails the contrast checks (text 4.5:1, marks 3:1) is refused, never swapped; with no `accentDark` it is derived by mixing toward white |
43
43
  | `status` | `{ state: ok \| warn \| blocked \| info, label? }`; the banner's colour, icon and word |
44
44
  | `asOf`, `scope` | An ISO date, and a sentence on what the page covers |
45
45
  | `verdict`, `caption` | One sentence the reader can stop at; one line under it |