@venizia/vulcan 0.4.8 → 0.4.9-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.
Files changed (126) hide show
  1. package/base/hooks/antigravity-guards.ts +2 -1
  2. package/base/hooks/codex-guards.ts +2 -1
  3. package/base/hooks/guard-manifest.ts +2 -1
  4. package/base/hooks/guard-package.ts +2 -1
  5. package/base/hooks/guard-remote-hosts.ts +9 -3
  6. package/base/hooks/guard-scripting.ts +2 -1
  7. package/base/hooks/guard-writes.ts +14 -4
  8. package/base/hooks/post-tool.ts +2 -1
  9. package/base/hooks/prompt-submit.ts +2 -1
  10. package/base/hooks/session-start.ts +3 -1
  11. package/base/hooks/stop.ts +2 -1
  12. package/base/make/vulcan.mk +1 -4
  13. package/base/skills/build-a-feature/SKILL.md +1 -1
  14. package/base/skills/docs-update/SKILL.md +11 -5
  15. package/base/skills/docs-update/evals/evals.json +1 -1
  16. package/base/skills/docs-writing/SKILL.md +1 -1
  17. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +20 -6
  20. package/base/skills/visualize-work/references/spec.md +16 -5
  21. package/package.json +5 -6
  22. package/src/agents/codex-hooks.ts +11 -10
  23. package/src/agents/common/types.ts +1 -1
  24. package/src/agents/exclude.ts +1 -1
  25. package/src/agents/hooks-json.ts +4 -8
  26. package/src/agents/prompt.ts +2 -2
  27. package/src/agents/render.ts +8 -12
  28. package/src/cli.ts +3 -1
  29. package/src/commands/doctor.command.ts +3 -1
  30. package/src/commands/help.command.ts +11 -9
  31. package/src/commands/init.command.ts +3 -1
  32. package/src/commands/profile.command.ts +1 -1
  33. package/src/commands/upgrade.command.ts +5 -3
  34. package/src/commands/visualize.command.ts +23 -2
  35. package/src/common/index.ts +2 -0
  36. package/src/common/layout-folder.ts +2 -20
  37. package/src/common/record.ts +7 -0
  38. package/src/common/text.ts +7 -0
  39. package/src/config/common/constants.ts +13 -1
  40. package/src/config/common/types.ts +8 -1
  41. package/src/config/loader.ts +4 -2
  42. package/src/config/packages.ts +4 -1
  43. package/src/config/schema.ts +51 -4
  44. package/src/create/add-app.ts +170 -69
  45. package/src/create/add-lib.ts +41 -31
  46. package/src/create/common/constants.ts +1 -0
  47. package/src/create/common/failure.ts +10 -0
  48. package/src/create/common/index.ts +2 -0
  49. package/src/create/common/preset-path.ts +11 -0
  50. package/src/create/common/types.ts +7 -2
  51. package/src/create/init-monorepo.ts +5 -2
  52. package/src/create/lib-preset.ts +22 -17
  53. package/src/create/names.ts +1 -1
  54. package/src/create/next.ts +1 -1
  55. package/src/create/preset-diff.ts +232 -55
  56. package/src/create/preset-menu.ts +3 -3
  57. package/src/create/preset.ts +18 -10
  58. package/src/create/process.ts +4 -2
  59. package/src/create/scratch.ts +3 -1
  60. package/src/create/workspace.ts +37 -20
  61. package/src/doctor/checks.ts +74 -16
  62. package/src/doctor/runner.ts +2 -0
  63. package/src/doctor/tags.ts +2 -4
  64. package/src/hooks/codex-patch.ts +2 -2
  65. package/src/hooks/common/constants.ts +0 -3
  66. package/src/hooks/common/types.ts +15 -1
  67. package/src/hooks/decision.ts +1 -5
  68. package/src/hooks/guard-git.ts +1 -1
  69. package/src/hooks/guard-outside.ts +28 -9
  70. package/src/hooks/guard-package.ts +13 -7
  71. package/src/hooks/guard-scripting.ts +1 -1
  72. package/src/hooks/guard-writes.ts +73 -20
  73. package/src/hooks/owner-reply.ts +1 -1
  74. package/src/hooks/project-guards.ts +39 -4
  75. package/src/hooks/remote-hosts.ts +5 -20
  76. package/src/hooks/session-digest.ts +7 -0
  77. package/src/hooks/shell.ts +13 -4
  78. package/src/hooks/trusted-scripts.ts +80 -4
  79. package/src/init/common/types.ts +1 -1
  80. package/src/init/scaffold.ts +2 -2
  81. package/src/local/clean.ts +1 -1
  82. package/src/local/scan.ts +2 -2
  83. package/src/manifest/render.ts +20 -11
  84. package/src/owner/profile.ts +1 -3
  85. package/src/owner/shape.ts +1 -1
  86. package/src/owner/survey.ts +27 -18
  87. package/src/router.ts +4 -1
  88. package/src/rules/common/types.ts +1 -1
  89. package/src/signals/state.ts +1 -4
  90. package/src/sync/agent-removal.ts +7 -10
  91. package/src/sync/claude-launch.ts +36 -1
  92. package/src/sync/common/constants.ts +4 -0
  93. package/src/sync/common/index.ts +1 -0
  94. package/src/sync/common/symlink.ts +9 -0
  95. package/src/sync/common/types.ts +2 -2
  96. package/src/sync/planner.ts +10 -12
  97. package/src/sync/settings.ts +1 -1
  98. package/src/ui/keyboard.ts +3 -1
  99. package/src/ui/prompt.ts +4 -2
  100. package/src/visualize/assets.ts +370 -195
  101. package/src/visualize/charts.ts +11 -2
  102. package/src/visualize/compare-css.ts +30 -0
  103. package/src/visualize/compare-render.ts +194 -0
  104. package/src/visualize/compare-schema.ts +81 -0
  105. package/src/visualize/compare-validate.ts +126 -0
  106. package/src/visualize/constants.ts +29 -3
  107. package/src/visualize/diagrams.ts +1 -1
  108. package/src/visualize/gate.ts +136 -0
  109. package/src/visualize/icons.ts +5 -2
  110. package/src/visualize/index.ts +2 -0
  111. package/src/visualize/kinds-css.ts +54 -0
  112. package/src/visualize/kinds-render.ts +693 -0
  113. package/src/visualize/kinds-schema.ts +148 -0
  114. package/src/visualize/kinds-validate.ts +184 -0
  115. package/src/visualize/labels-vi.ts +109 -0
  116. package/src/visualize/labels.ts +49 -0
  117. package/src/visualize/layout.ts +10 -5
  118. package/src/visualize/page.ts +99 -61
  119. package/src/visualize/render.ts +48 -7
  120. package/src/visualize/schema.ts +21 -1
  121. package/src/visualize/sections.ts +115 -34
  122. package/src/visualize/sources.ts +270 -0
  123. package/src/visualize/theme.ts +472 -0
  124. package/src/visualize/validate.ts +6 -0
  125. package/src/wiki/anchors.ts +1 -1
  126. package/src/wiki/source-links.ts +3 -5
@@ -41,7 +41,8 @@ const parseJson = (opts: { text: string }): unknown => {
41
41
  }
42
42
  };
43
43
 
44
- const parsed = parseJson({ text: await Bun.stdin.text() });
44
+ const stdin = await Bun.stdin.text();
45
+ const parsed = parseJson({ text: stdin });
45
46
  const toolCall = isRecord(parsed) ? parsed.toolCall : undefined;
46
47
  const args = isRecord(toolCall) ? toolCall.args : undefined;
47
48
  const toolName = isRecord(toolCall) ? textOf(toolCall.name) : undefined;
@@ -29,7 +29,8 @@ const parseJson = (opts: { text: string }): unknown => {
29
29
  }
30
30
  };
31
31
 
32
- const parsed = parseJson({ text: await Bun.stdin.text() });
32
+ const stdin = await Bun.stdin.text();
33
+ const parsed = parseJson({ text: stdin });
33
34
  const toolInput = isRecord(parsed) ? parsed['tool_input'] : undefined;
34
35
  const tool = isRecord(parsed) ? textOf(parsed['tool_name']) : undefined;
35
36
  const command = isRecord(toolInput) ? textOf(toolInput['command']) : undefined;
@@ -14,7 +14,8 @@ export {};
14
14
  try {
15
15
  const { buildManifestDecision, inspectManifestWrite, parseManifestHookInput } =
16
16
  await import('../../src/hooks/guard-manifest.ts');
17
- const input = parseManifestHookInput({ text: await Bun.stdin.text() });
17
+ const stdin = await Bun.stdin.text();
18
+ const input = parseManifestHookInput({ text: stdin });
18
19
 
19
20
  if (input && inspectManifestWrite({ input })) {
20
21
  console.log(JSON.stringify(buildManifestDecision()));
@@ -16,7 +16,8 @@ try {
16
16
  const { buildPackageDecision, inspectPackageWrite } =
17
17
  await import('../../src/hooks/guard-package.ts');
18
18
  const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
19
- const input = parseManifestHookInput({ text: await Bun.stdin.text() });
19
+ const stdin = await Bun.stdin.text();
20
+ const input = parseManifestHookInput({ text: stdin });
20
21
  const verdict = input && inspectPackageWrite({ input });
21
22
 
22
23
  if (verdict) {
@@ -17,7 +17,9 @@ try {
17
17
  const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
18
18
  const manifestFile = Bun.file(`${root}/.agents/vulcan.manifest.json`);
19
19
 
20
- if (!(await manifestFile.exists())) {
20
+ const manifestExists = await manifestFile.exists();
21
+
22
+ if (!manifestExists) {
21
23
  throw new Error('.agents/vulcan.manifest.json is missing - run vulcan sync');
22
24
  }
23
25
 
@@ -30,10 +32,14 @@ try {
30
32
 
31
33
  const localFile = typeof remoteHosts.localFile === 'string' ? remoteHosts.localFile : undefined;
32
34
  const local = localFile === undefined ? undefined : Bun.file(`${root}/${localFile}`);
33
- const personal = local !== undefined && (await local.exists()) ? await local.text() : '';
35
+ const localExists = await local?.exists();
36
+ const readingPersonal = localExists === true ? local?.text() : undefined;
37
+ const personalText = await readingPersonal;
38
+ const personal = personalText ?? '';
34
39
  const trusted: string[] = Array.isArray(remoteHosts.trusted) ? remoteHosts.trusted : [];
35
40
  const readOnly: string[] = Array.isArray(remoteHosts.readOnly) ? remoteHosts.readOnly : [];
36
- const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
41
+ const stdin = await Bun.stdin.text();
42
+ const hookCommand = parseHookCommand({ text: stdin });
37
43
  const hits = hookCommand
38
44
  ? inspectRemoteCommand({
39
45
  command: hookCommand.command,
@@ -20,7 +20,8 @@ try {
20
20
  const { buildScriptingAdvice, inspectScripting } =
21
21
  await import('../../src/hooks/guard-scripting.ts');
22
22
  const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
23
- const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
23
+ const stdin = await Bun.stdin.text();
24
+ const hookCommand = parseHookCommand({ text: stdin });
24
25
 
25
26
  if (hookCommand && inspectScripting({ command: hookCommand.command }).length > 0) {
26
27
  console.log(JSON.stringify(buildScriptingAdvice()));
@@ -5,6 +5,8 @@
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
7
  * is tracked and unchanged; a config that cannot be read leaves the list empty, so every script is read.
8
+ * An entry of `guard.writes.readOnlyScripts` in the manifest (the object form of `trustedScripts`, written by
9
+ * `vulcan sync`) skips that read for the calls whose first argument after the script is one of its words.
8
10
  *
9
11
  * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so a hook that throws - a
10
12
  * partial install, say, where its own modules are missing - would let every command through. The
@@ -18,7 +20,8 @@ try {
18
20
  const { buildGuardDecision, inspectCommand, parseHookCommand } =
19
21
  await import('../../src/hooks/guard-writes.ts');
20
22
  const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
21
- const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
23
+ const stdin = await Bun.stdin.text();
24
+ const hookCommand = parseHookCommand({ text: stdin });
22
25
  const cwd = hookCommand?.cwd ?? process.cwd();
23
26
  let scripts: string[] = [];
24
27
 
@@ -29,7 +32,12 @@ try {
29
32
  const { loadConfig } = await import('../../src/config/index.ts');
30
33
  const loaded = await loadConfig({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
31
34
 
32
- scripts = loaded.ok ? loaded.config.guard.writes.trustedScripts : [];
35
+ // The objects are the read-only entries: the manifest carries them, so only the paths count here.
36
+ scripts = loaded.ok
37
+ ? loaded.config.guard.writes.trustedScripts.filter(
38
+ (entry): entry is string => typeof entry === 'string',
39
+ )
40
+ : [];
33
41
  } catch (error) {
34
42
  console.error(
35
43
  `vulcan: the guard-writes hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - every script is read`,
@@ -37,12 +45,14 @@ try {
37
45
  }
38
46
  }
39
47
 
48
+ const root = process.env.CLAUDE_PROJECT_DIR ?? cwd;
49
+ const policy = readGuardPolicy({ root });
40
50
  const hits = hookCommand
41
51
  ? inspectCommand({
42
52
  command: hookCommand.command,
43
53
  cwd,
44
- trust: { root: process.env.CLAUDE_PROJECT_DIR ?? cwd, scripts },
45
- extra: readGuardPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).commands,
54
+ trust: { root, scripts, readOnlyScripts: policy.readOnlyScripts },
55
+ extra: policy.commands,
46
56
  })
47
57
  : [];
48
58
 
@@ -15,9 +15,10 @@ if (process.env.VULCAN_GUARDS === 'off') {
15
15
 
16
16
  try {
17
17
  const { buildPostToolOutput } = await import('../../src/hooks/post-tool.ts');
18
+ const stdin = await Bun.stdin.text();
18
19
  const output = buildPostToolOutput({
19
20
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
20
- input: JSON.parse(await Bun.stdin.text()),
21
+ input: JSON.parse(stdin),
21
22
  });
22
23
 
23
24
  if (output !== undefined) {
@@ -18,7 +18,8 @@ try {
18
18
  let session = '';
19
19
 
20
20
  try {
21
- const event: unknown = JSON.parse(await Bun.stdin.text());
21
+ const stdin = await Bun.stdin.text();
22
+ const event: unknown = JSON.parse(stdin);
22
23
 
23
24
  if (
24
25
  typeof event === 'object' &&
@@ -7,7 +7,9 @@ import { buildSessionDigest, exportProjectTmp } from '../../src/hooks/index.ts';
7
7
 
8
8
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
9
9
 
10
- process.stdout.write(await buildSessionDigest({ projectRoot }));
10
+ const digest = await buildSessionDigest({ projectRoot });
11
+
12
+ process.stdout.write(digest);
11
13
 
12
14
  // Claude Code gives this hook a file it sources before each Bash command: the project's temp folder goes in it.
13
15
  try {
@@ -18,9 +18,10 @@ if (process.env.VULCAN_GUARDS === 'off') {
18
18
 
19
19
  try {
20
20
  const { buildStopOutput } = await import('../../src/hooks/owner-reply.ts');
21
+ const stdin = await Bun.stdin.text();
21
22
  const output = await buildStopOutput({
22
23
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
23
- input: JSON.parse(await Bun.stdin.text()),
24
+ input: JSON.parse(stdin),
24
25
  });
25
26
 
26
27
  if (output !== undefined) {
@@ -7,7 +7,7 @@ VULCAN_BASE ?= node_modules/@venizia/vulcan/base
7
7
  # The GitHub repository the wiki links point into, owner/name; the link gate checks only links into it.
8
8
  WIKI_REPO ?=
9
9
 
10
- .PHONY: vulcan-sync vulcan-doctor agent-setup okf-check okf-check-strict okf-gen okf-coverage okf-viz \
10
+ .PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage okf-viz \
11
11
  surface-gen surface-check atlas-symbols atlas-releases changelogs-migrate \
12
12
  knowledge-symbols-check wiki-links-check wiki-anchors-check
13
13
 
@@ -17,9 +17,6 @@ vulcan-sync: ## Write the agent adapters, settings, skill links and manifest fro
17
17
  vulcan-doctor: ## Check the project against the VULCAN contract
18
18
  @$(VULCAN) doctor
19
19
 
20
- # The older name for the same job, kept for muscle memory.
21
- agent-setup: vulcan-sync ## The older name for vulcan-sync
22
-
23
20
  # OKF v0.2 conformance only; okf-check-strict adds the house rules (links, style, coverage, freshness).
24
21
  okf-check: ## Check the knowledge bundle against OKF v0.2
25
22
  @$(VULCAN) x okf check
@@ -129,7 +129,7 @@ Done when every check passed in this session and the behaviour is shown.
129
129
 
130
130
  When **Docs impact** is not `none`, run the `docs-update` skill now, after the checks of step 6 and
131
131
  before review: it refreshes the page that owns the
132
- topic, writes the changelog entry when the change is release-worthy, and runs the docs gates. Then each
132
+ topic, writes the changelog entry when the change affects users of the published packages, and runs the docs gates. Then each
133
133
  fact about the project that changed - a new concept, a decision, a gotcha - goes into the knowledge
134
134
  bundle in the same change. The reviewer sees the docs in the diff.
135
135
 
@@ -34,7 +34,7 @@ Copy it into your reply and tick it off, in order:
34
34
  - [ ] 2. Code read - the changed source, not a diff summary, not dist/, not another doc
35
35
  - [ ] 3. Page picked - the page that owns the topic; a new one only when none does, wired in
36
36
  - [ ] 4. Page written and self-reviewed with the docs-writing skill
37
- - [ ] 5. Changelog entry written (release-worthy changes only)
37
+ - [ ] 5. Changelog entry written (only when the change affects users of the published packages)
38
38
  - [ ] 6. Gates green (loop until they are)
39
39
  - [ ] 7. Reported; nothing committed
40
40
  ```
@@ -78,16 +78,22 @@ Every code sample uses the names and signatures from step 2.
78
78
 
79
79
  ## 5. Changelog
80
80
 
81
- Only for a release-worthy change: a feature, a fix a user notices, a breaking change.
81
+ Only for a change that affects the users of the published packages and what they can use: a new feature,
82
+ command, option or config key; changed behaviour or a breaking change (with its upgrade step); a bug fix a user
83
+ could hit; a security fix; a deprecation or a removal. Internal work gets no entry: release tooling, CI and
84
+ workflows, guards and gates, a refactor with no behaviour change, tests, agent rules and skills for the repo's
85
+ own sessions, internal docs and knowledge pages, repo hygiene. A change that is only internal skips this step
86
+ and says so.
82
87
 
83
88
  1. **The file.** `<knowledge.changelogs>/YYYY-MM-DD-<slug>.md`, from the directory's `template.md`.
84
89
  No template: copy the shape of the newest entry. Keep only the sections that apply. When an
85
90
  entry for the coming release already exists, add a bullet to it instead of opening a second.
86
91
  2. **The `packages:` list** (Project Contract v1, C3). The frontmatter lists the npm names, from
87
- `packages[].name`, of every package the entry covers: `packages: ['@scope/core']`. An entry about
88
- no package, such as repository tooling, carries `packages: []`. Never leave the list out -
92
+ `packages[].name`, of every package the entry covers: `packages: ['@scope/core']`. An entry that covers
93
+ no package is internal work, and internal work has no entry. Never leave the list out -
89
94
  `okf check --strict` fails the entry.
90
- 3. **The content.** What changed, who is affected, how to migrate. It is not a commit log.
95
+ 3. **The content.** Short, and in the user's terms: what changed and the benefit, who is affected, how to
96
+ migrate. It is not a commit log, and it does not say how the change was built.
91
97
  4. **The index.** When the directory's `index.md` lists entries, add a row in its order.
92
98
 
93
99
  ## 6. Gates - validate, fix, repeat
@@ -10,7 +10,7 @@
10
10
  {
11
11
  "id": 1,
12
12
  "prompt": "Add a changelog entry for last week's change to the repository's CI and release tooling. It touches no package. Do not commit.",
13
- "expected_output": "One dated entry under the manifest's knowledge.changelogs, shaped by the directory's template, carrying packages: [] in its frontmatter, added to the changelog index when one lists entries; okf check --strict passes; nothing committed",
13
+ "expected_output": "Writes no changelog entry: CI and release tooling is internal work that touches no package and affects no user of the published packages, and the changelog records only what affects users; says so in one line and names what would need an entry (a feature, a changed behaviour, a fix a user could hit, a security fix, a removal); changes no file; nothing committed",
14
14
  "files": [".agents/vulcan.manifest.json"]
15
15
  },
16
16
  {
@@ -85,7 +85,7 @@ Read the finished page once, top to bottom, as the reader from Step 1. If any se
85
85
  - Never abbreviate identifiers (Repository, not Repo; TDocument, not TDoc) - in prose and in samples (V-C-04).
86
86
  - Every code sample must compile against the real source. Verify names and signatures in the source before writing them. Examples import what app code imports; prose names the canonical name and lists aliases.
87
87
  - File links point at a file, never at a line number: lines move, files rarely do.
88
- - Changelogs are user-facing: what changed, who is affected, how to migrate. Not a commit log.
88
+ - Changelogs are user-facing and short: what changed and the benefit, who is affected, how to migrate. Not a commit log, and nothing internal.
89
89
  - The project's docs-site rules (its generator's limits, link style) live in `.agents/rules.md` or its own skill.
90
90
  - The knowledge bundle (`.agents/knowledge`) follows the same sentence rules. Its readers are agents, but a wall of text fails them too - use short paragraphs and bullets, keep the "constraint the code cannot show" focus.
91
91
 
@@ -17,7 +17,7 @@ In this order:
17
17
  | Claims | `C1..Cn`: one observable behaviour each, and for each the probe that would show it false. Behaviour is phrased WHEN ... THEN ... |
18
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 |
19
19
  | Seams | The public boundaries tests attach to. An existing seam is preferred; the ideal count is one |
20
- | Docs impact | The pages, knowledge concepts and changelog entry that change, or `none` with the reason |
20
+ | Docs impact | The pages, knowledge concepts and changelog entry that change (an entry only when users of the published packages are affected), or `none` with the reason |
21
21
  | Open | Questions too dim to be claims, each naming who resolves it. Empty before work starts |
22
22
  | Decisions | Dated, append-only. Dead ends and rejected alternatives stay. A `refined:` prefix marks a change of goal or claim |
23
23
 
@@ -28,7 +28,7 @@ It rises with the lane (see `plan-a-change`). A small edit (lane S) ends as `rep
28
28
 
29
29
  - Every claim of the card is closed with an evidence stub (the probe and its result).
30
30
  - The docs slice is done and the docs gates are green (`docs-update` skill).
31
- - A changelog entry exists when the change is worth releasing.
31
+ - A changelog entry exists when the change affects users of the published packages (a feature, a changed behaviour, a fix a user could hit, a security fix, a removal). A change that is only internal (tooling, CI, refactors, tests, internal docs) has none.
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.
@@ -32,6 +32,10 @@ One page answers one question, and the question picks the kind (the table is in
32
32
  |---|---|
33
33
  | Where does the round stand, what do I do | status or handoff: `strip`, `actions`, `minimap`, `decisions` |
34
34
  | How does it move, how is it built | `flow`, `architecture` |
35
+ | What differs between two ways of doing it | `compare` |
36
+ | Who calls whom, in what order | `sequence` |
37
+ | Which states, and how it moves between them | `lifecycle` |
38
+ | What is inside what | `tree` |
35
39
  | Which option, and why | `comparison` |
36
40
  | What could we do | `ideaMap` |
37
41
  | How does it work | `explainer` |
@@ -40,7 +44,7 @@ One page answers one question, and the question picks the kind (the table is in
40
44
  | What did we decide | `decisionRecord` |
41
45
  | What changes | `beforeAfter` |
42
46
 
43
- A page holds at most 25 boxes and 40 arrows, and stays under 100 KB; what does not fit is two pages, not one
47
+ A page holds at most 25 boxes and 40 arrows, and stays under 80 KB; what does not fit is two pages, not one
44
48
  dense page. A long explanation is a document (see `docs-writing`), not a page.
45
49
 
46
50
  Done when you can say the question in one sentence and name the kind.
@@ -70,9 +74,18 @@ The rules that make a page worth opening:
70
74
  - **A timeline item has a date and a state**, so a roadmap reads as done, in progress and not started.
71
75
  - **Decisions are one to five forks**, each with a recommended default and the claim it changes.
72
76
  - **No secrets, no private data** in any field: the page is a file others may open.
73
- - **The owner's language is a setting**: when the reply language of the profile is not English, set
74
- `language` and translate the words you need into `chrome` (every key is optional); never invent a label
75
- set the owner did not give. Otherwise leave `chrome` out.
77
+ - **The owner's language is a setting**: the page takes the reply language of the owner's profile (English and
78
+ Vietnamese words are bundled; `language` in the spec overrides it). For any other language, translate the
79
+ words you need into `chrome` (every key is optional); never invent a label set the owner did not give.
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`)
82
+ only when you draw a page about another project from outside it. A colour that fails the contrast checks is
83
+ refused, never swapped; state colours (done, waiting, blocked) are fixed and always carry an icon and a word.
84
+ - **Say where a claim comes from.** A box or step that states how the code works carries a `source`
85
+ (`repo`, the full 40-character `commit`, `path`, `lines`) you have read in this session; the page refuses a
86
+ short commit. Explain the words the reader may not know in `terms`, and use each in the page.
87
+ - **Tiles only when the numbers are the point.** A flow or a comparison opens the page with its figure, not with
88
+ a row of tiles.
76
89
 
77
90
  Done when each arrow has a verb and each evidence row has a label you can defend.
78
91
 
@@ -84,7 +97,7 @@ bun x --no-install vulcan visualize .agents/local/tmp/<name>.json --out <name>
84
97
 
85
98
  It validates the spec (shape, limits, unique ids, every arrow and step pointing at a box, one box per cell),
86
99
  escapes all text, applies a policy that allows only the page's own style and script, refuses a page over
87
- 100 KB, and writes `.agents/local/prototypes/<name>.html` whole - a failed spec never replaces the last good
100
+ 150 KB (it warns over 80 KB), and writes `.agents/local/prototypes/<name>.html` whole - a failed spec never replaces the last good
88
101
  page. It prints the path and the checks that ran. Fix every problem it lists and run it again.
89
102
 
90
103
  Done when it prints the path.
@@ -93,7 +106,8 @@ Done when it prints the path.
93
106
 
94
107
  The command cannot see the page. Open it in a browser at 390 px and at 1280 px (a browser tool, or ask the
95
108
  owner to open it) and check: the page does not scroll sideways (at 390 px a figure gives way to a list),
96
- no text is smaller than 12 px, nothing overlaps (arrow labels against boxes), the dark theme is readable,
109
+ no text is smaller than 12 px, nothing overlaps (arrow labels against boxes), both themes are readable (the
110
+ sun and moon switch in the top bar flips them), the page is complete with the script off,
97
111
  hover or focus on a box shows its detail, Next steps through the lit boxes, the **Present** button (or
98
112
  `?present=1`) walks the sections as slides with the arrow keys and Escape leaves, and the console is clean.
99
113
 
@@ -8,15 +8,19 @@ never markup. `bun x --no-install vulcan visualize --schema` prints the full JSO
8
8
  ## The kinds
9
9
 
10
10
  A page is the sections its spec has, in a fixed order: the banner (title, verdict, state), the tiles, the minimap,
11
- what you need to do and what blocks it, then the flow, the architecture, the comparison, the idea map, the
12
- explainer, the timeline, the findings, the before and after, the decision record, the decisions, the evidence,
13
- the risks, the log and the links. Pick the sections the question needs and leave the rest out:
11
+ what you need to do and what blocks it, then the flow (drawn in the top slab, under the verdict, when there is
12
+ one), the architecture, the compare view, the sequence, the lifecycle, the tree, the comparison, the idea map, the explainer, the timeline, the findings, the before and after, the decision record, the decisions, the evidence,
13
+ the risks, the log, the words of the page (`terms`), the sources and the links. Pick the sections the question needs and leave the rest out:
14
14
 
15
15
  | The page is | Use |
16
16
  |---|---|
17
17
  | A status or a handoff for the owner | `strip`, `actions`, `minimap`, `decisions`, `evidence`, `risks`, `log` |
18
18
  | How something moves | `flow` (boxes on a grid, labelled arrows, numbered steps) |
19
19
  | How a system is built | `architecture` (layers of boxes with links) |
20
+ | What differs between two ways of doing it | `compare` (one figure: edges in both, only in A, only in B) |
21
+ | Who calls whom, in what order | `sequence` (lanes for the participants, one arrow per message) |
22
+ | The states of a thing | `lifecycle` (states, with a start and ends, and what moves it between them) |
23
+ | What is inside what | `tree` (a root with children, up to four levels) |
20
24
  | Options compared, with a pick | `comparison` (scores per criterion, pros and cons, a recommended option) |
21
25
  | A brainstorm | `ideaMap` (a centre and clusters of ideas) |
22
26
  | An idea explained | `explainer` (numbered steps, a small diagram for each) |
@@ -34,7 +38,8 @@ Space, Home, End and Escape, one section per slide; print gives one section afte
34
38
  |---|---|
35
39
  | `schemaVersion` | `1` |
36
40
  | `title` | The takeaway, at most 120 characters |
37
- | `language` | A language code (`en`, `pt-BR`); default `en` |
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 |
38
43
  | `status` | `{ state: ok \| warn \| blocked \| info, label? }`; the banner's colour, icon and word |
39
44
  | `asOf`, `scope` | An ISO date, and a sentence on what the page covers |
40
45
  | `verdict`, `caption` | One sentence the reader can stop at; one line under it |
@@ -63,6 +68,12 @@ minimap words, or `info`) adds a colour, an icon and a word, so the figure can s
63
68
  | `ideaMap` | `center`, and 2 to 8 `branches` of `{ label, items (1 to 6), note? }` |
64
69
  | `explainer` | 1 to 8 `steps` of `{ title, text, diagram? }`; a diagram is `{ type: "row", nodes, arrows? }` (2 to 5 boxes, one arrow label fewer than boxes) or `{ type: "layers", layers }` |
65
70
  | `architecture` | `layers` (up to 5) of `{ label, boxes }`, a box `{ id, label, sub?, state? }`, and `links` of `{ from, to, label? }` between box ids |
71
+ | `compare` | `a` and `b` (the names of the two ways, 24 characters each), `nodes` (2 to 25 of `{ id, label, sublabel?, row, col, kind?, state?, source? }`, shared by both ways), `edges` (1 to 40 of `{ from, to, label, in? }`, `in` one of `both` (default), `a`, `b`), optional `caption`. An edge only in B is drawn heavy and solid with `+`, an edge only in A dotted with `-`, and the legend says the words; at least one edge has to differ, or the spec is refused |
72
+ | `terms` | 1 to 12 of `{ term (40 characters), meaning (200) }`, shown as "Words in this page"; a term that never appears in the rest of the page text is a warning |
73
+ | `source` | On a flow node, a flow step or a compare node: `{ repo, commit, path, lines? }`. `repo` is `owner/name`, `commit` is exactly 40 lowercase hex characters, `path` is relative with no `..`, `lines` is `12` or `12-30`. Shown as `repo@commit:path:lines`, and a "Sources" part lists each source once with what points at it |
74
+ | `sequence` | `participants` (2 to 6 of `{ id, label, sublabel? }`), `messages` (1 to 20 of `{ from, to, label, kind?, note? }`, `kind` one of `call`, `reply`, `async`, in the order they happen), optional `caption` |
75
+ | `lifecycle` | `states` (2 to 10 of `{ id, label, sublabel?, kind? }`, `kind` one of `start`, `normal`, `end`; one start, at least one end), `transitions` (up to 20 of `{ from, to, label }`, the label is the trigger), optional `caption` |
76
+ | `tree` | `root`, a node `{ id, label, sublabel?, state?, children? }` nested up to four levels below the root, at most 25 nodes in all; optional `caption` |
66
77
  | `timeline` | 2 to 20 `items` of `{ date, title, text?, state? }` |
67
78
  | `findings` | `numbers` (`{ value, label, state? }`), `charts`, `callouts` (`{ text, state? }`) |
68
79
  | `decisionRecord` | `context`, 2 to 5 `options` of `{ name, summary, chosen? }`, the `decision`, `consequences` |
@@ -76,7 +87,7 @@ only way to tell parts apart: the legend names them and the values are printed.
76
87
 
77
88
  At most 25 boxes, 40 arrows, 12 steps, 5 decisions and 30 rows per table; grid cells 0 to 9; labels 60
78
89
  characters (an arrow label 20), sentences 300, a box detail 600; 6 tiles, 4 charts, 12 points per chart.
79
- The page is refused over 100 KB and warned over 60 KB; a typical page is 20 to 40 KB, most of it the page's own style.
90
+ The page is refused over 150 KB and warned over 80 KB; a typical page is 30 to 60 KB, most of it the page's own style.
80
91
 
81
92
  ## Two worked specs
82
93
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.8",
3
+ "version": "0.4.9-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,17 +44,16 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.8",
48
- "@venizia/vulcan-okf": "0.4.8",
47
+ "@venizia/vulcan-atlas": "0.4.9-0",
48
+ "@venizia/vulcan-okf": "0.4.9-0",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
52
52
  "@types/bun": "1.4.3",
53
- "@venizia/dev-configs": "0.4.4",
53
+ "@venizia/dev-configs": "0.4.7-0",
54
54
  "eslint": "10.13.0",
55
55
  "oxlint": "1.89.0",
56
- "oxlint-tsgolint": "7.0.2004",
57
- "typescript": "^6.0.3"
56
+ "oxlint-tsgolint": "7.0.2004"
58
57
  },
59
58
  "engines": {
60
59
  "bun": ">=1.4.4"
@@ -1,8 +1,6 @@
1
+ import { RecordValue } from '../common/record.ts';
1
2
  import { RemoveOutcomes } from './common/index.ts';
2
3
 
3
- const isRecord = (value: unknown): value is Record<string, unknown> =>
4
- typeof value === 'object' && value !== null && !Array.isArray(value);
5
-
6
4
  /** The script every VULCAN entry runs: it is how an entry of ours is told from a hook of the user's. */
7
5
  const GUARD_SCRIPT = 'codex-guards.ts';
8
6
 
@@ -37,11 +35,13 @@ const guardEntry = (): Record<string, unknown> => ({
37
35
  });
38
36
 
39
37
  const isGuardEntry = (entry: unknown): boolean =>
40
- isRecord(entry) &&
38
+ RecordValue.isRecord(entry) &&
41
39
  Array.isArray(entry.hooks) &&
42
40
  entry.hooks.some(
43
41
  (hook) =>
44
- isRecord(hook) && typeof hook.command === 'string' && hook.command.includes(GUARD_SCRIPT),
42
+ RecordValue.isRecord(hook) &&
43
+ typeof hook.command === 'string' &&
44
+ hook.command.includes(GUARD_SCRIPT),
45
45
  );
46
46
 
47
47
  interface IParsedFile {
@@ -58,14 +58,15 @@ const parseFile = (opts: { text: string | undefined }): IParsedFile | { reason:
58
58
  try {
59
59
  const file: unknown = JSON.parse(opts.text);
60
60
 
61
- if (!isRecord(file)) {
61
+ if (!RecordValue.isRecord(file)) {
62
62
  return { reason: 'the hooks file is not a JSON object' };
63
63
  }
64
64
 
65
65
  const hooks = file.hooks === undefined ? {} : file.hooks;
66
- const entries = isRecord(hooks) && hooks.PreToolUse !== undefined ? hooks.PreToolUse : [];
66
+ const entries =
67
+ RecordValue.isRecord(hooks) && hooks.PreToolUse !== undefined ? hooks.PreToolUse : [];
67
68
 
68
- return isRecord(hooks) && Array.isArray(entries)
69
+ return RecordValue.isRecord(hooks) && Array.isArray(entries)
69
70
  ? { file, hooks, entries }
70
71
  : { reason: 'the hooks file has a hooks or PreToolUse value that is not what Codex reads' };
71
72
  } catch (error) {
@@ -75,7 +76,7 @@ const parseFile = (opts: { text: string | undefined }): IParsedFile | { reason:
75
76
  }
76
77
  };
77
78
 
78
- export type TCodexHooksMerge =
79
+ type TCodexHooksMerge =
79
80
  | { ok: true; changed: boolean; text: string }
80
81
  | { ok: false; reason: string };
81
82
 
@@ -102,7 +103,7 @@ export const mergeCodexHooks = (opts: { text: string | undefined }): TCodexHooks
102
103
  };
103
104
  };
104
105
 
105
- export type TCodexHooksRemoval =
106
+ type TCodexHooksRemoval =
106
107
  | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
107
108
  | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
108
109
  | { ok: false; reason: string };
@@ -13,7 +13,7 @@ export interface IAgentQuestion {
13
13
 
14
14
  export type TAskAgents = (question: IAgentQuestion) => string | null;
15
15
 
16
- export type TAgentSource = TConstValue<typeof AgentSources>;
16
+ type TAgentSource = TConstValue<typeof AgentSources>;
17
17
 
18
18
  export type TAgentResolution =
19
19
  | {
@@ -10,7 +10,7 @@ const START_PREFIX = '# vulcan:start';
10
10
  const START_PATTERN = /^# vulcan:start(?: \((.*)\))? - written/;
11
11
  const CLAUDE_SKILLS_DIRECTORY = '.claude/skills';
12
12
 
13
- export interface IExcludeGroup {
13
+ interface IExcludeGroup {
14
14
  title: string;
15
15
  /** Root-relative and anchored with a leading slash; a folder ends with one. */
16
16
  paths: string[];
@@ -1,8 +1,6 @@
1
+ import { RecordValue } from '../common/record.ts';
1
2
  import { RemoveOutcomes } from './common/index.ts';
2
3
 
3
- const isRecord = (value: unknown): value is Record<string, unknown> =>
4
- typeof value === 'object' && value !== null && !Array.isArray(value);
5
-
6
4
  /** The key of VULCAN's entry in Antigravity's hooks file: the file maps a hook name to its events. */
7
5
  export const GUARD_HOOK_NAME = 'vulcan-guards';
8
6
 
@@ -49,7 +47,7 @@ const parseHooks = (opts: { text: string | undefined }): TParsedHooks => {
49
47
  try {
50
48
  const parsed: unknown = JSON.parse(opts.text);
51
49
 
52
- return isRecord(parsed)
50
+ return RecordValue.isRecord(parsed)
53
51
  ? { ok: true, hooks: parsed }
54
52
  : { ok: false, reason: 'the hooks file is not a JSON object' };
55
53
  } catch (error) {
@@ -60,9 +58,7 @@ const parseHooks = (opts: { text: string | undefined }): TParsedHooks => {
60
58
  }
61
59
  };
62
60
 
63
- export type THooksMerge =
64
- | { ok: true; changed: boolean; text: string }
65
- | { ok: false; reason: string };
61
+ type THooksMerge = { ok: true; changed: boolean; text: string } | { ok: false; reason: string };
66
62
 
67
63
  /** The hooks file with VULCAN's entry in it, every other hook as the user wrote it. */
68
64
  export const mergeGuardHook = (opts: { text: string | undefined }): THooksMerge => {
@@ -82,7 +78,7 @@ export const mergeGuardHook = (opts: { text: string | undefined }): THooksMerge
82
78
  };
83
79
  };
84
80
 
85
- export type THooksRemoval =
81
+ type THooksRemoval =
86
82
  | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
87
83
  | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
88
84
  | { ok: false; reason: string };
@@ -28,13 +28,13 @@ export const renderAgentsQuestion = (question: IAgentQuestion): string => {
28
28
  ].join('\n');
29
29
  };
30
30
 
31
- export const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
31
+ const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
32
32
  process.stdout.write(`${renderAgentsQuestion(question)}\n`);
33
33
 
34
34
  return askWithPrompt({ question: 'Agents' });
35
35
  };
36
36
 
37
- export type TResolveAgentsInput = Omit<Parameters<typeof resolveAgents>[0], 'ask'>;
37
+ type TResolveAgentsInput = Omit<Parameters<typeof resolveAgents>[0], 'ask'>;
38
38
 
39
39
  const hintOf = (opts: { id: string; question: IAgentQuestion }): string | undefined => {
40
40
  const notes = [