@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.
- package/base/hooks/antigravity-guards.ts +2 -1
- package/base/hooks/codex-guards.ts +2 -1
- package/base/hooks/guard-manifest.ts +2 -1
- package/base/hooks/guard-package.ts +2 -1
- package/base/hooks/guard-remote-hosts.ts +9 -3
- package/base/hooks/guard-scripting.ts +2 -1
- package/base/hooks/guard-writes.ts +14 -4
- package/base/hooks/post-tool.ts +2 -1
- package/base/hooks/prompt-submit.ts +2 -1
- package/base/hooks/session-start.ts +3 -1
- package/base/hooks/stop.ts +2 -1
- package/base/make/vulcan.mk +1 -4
- package/base/skills/build-a-feature/SKILL.md +1 -1
- package/base/skills/docs-update/SKILL.md +11 -5
- package/base/skills/docs-update/evals/evals.json +1 -1
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/plan-a-change/references/spec-card.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +20 -6
- package/base/skills/visualize-work/references/spec.md +16 -5
- package/package.json +5 -6
- package/src/agents/codex-hooks.ts +11 -10
- package/src/agents/common/types.ts +1 -1
- package/src/agents/exclude.ts +1 -1
- package/src/agents/hooks-json.ts +4 -8
- package/src/agents/prompt.ts +2 -2
- package/src/agents/render.ts +8 -12
- package/src/cli.ts +3 -1
- package/src/commands/doctor.command.ts +3 -1
- package/src/commands/help.command.ts +11 -9
- package/src/commands/init.command.ts +3 -1
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/upgrade.command.ts +5 -3
- package/src/commands/visualize.command.ts +23 -2
- package/src/common/index.ts +2 -0
- package/src/common/layout-folder.ts +2 -20
- package/src/common/record.ts +7 -0
- package/src/common/text.ts +7 -0
- package/src/config/common/constants.ts +13 -1
- package/src/config/common/types.ts +8 -1
- package/src/config/loader.ts +4 -2
- package/src/config/packages.ts +4 -1
- package/src/config/schema.ts +51 -4
- package/src/create/add-app.ts +170 -69
- package/src/create/add-lib.ts +41 -31
- package/src/create/common/constants.ts +1 -0
- package/src/create/common/failure.ts +10 -0
- package/src/create/common/index.ts +2 -0
- package/src/create/common/preset-path.ts +11 -0
- package/src/create/common/types.ts +7 -2
- package/src/create/init-monorepo.ts +5 -2
- package/src/create/lib-preset.ts +22 -17
- package/src/create/names.ts +1 -1
- package/src/create/next.ts +1 -1
- package/src/create/preset-diff.ts +232 -55
- package/src/create/preset-menu.ts +3 -3
- package/src/create/preset.ts +18 -10
- package/src/create/process.ts +4 -2
- package/src/create/scratch.ts +3 -1
- package/src/create/workspace.ts +37 -20
- package/src/doctor/checks.ts +74 -16
- package/src/doctor/runner.ts +2 -0
- package/src/doctor/tags.ts +2 -4
- package/src/hooks/codex-patch.ts +2 -2
- package/src/hooks/common/constants.ts +0 -3
- package/src/hooks/common/types.ts +15 -1
- package/src/hooks/decision.ts +1 -5
- package/src/hooks/guard-git.ts +1 -1
- package/src/hooks/guard-outside.ts +28 -9
- package/src/hooks/guard-package.ts +13 -7
- package/src/hooks/guard-scripting.ts +1 -1
- package/src/hooks/guard-writes.ts +73 -20
- package/src/hooks/owner-reply.ts +1 -1
- package/src/hooks/project-guards.ts +39 -4
- package/src/hooks/remote-hosts.ts +5 -20
- package/src/hooks/session-digest.ts +7 -0
- package/src/hooks/shell.ts +13 -4
- package/src/hooks/trusted-scripts.ts +80 -4
- package/src/init/common/types.ts +1 -1
- package/src/init/scaffold.ts +2 -2
- package/src/local/clean.ts +1 -1
- package/src/local/scan.ts +2 -2
- package/src/manifest/render.ts +20 -11
- package/src/owner/profile.ts +1 -3
- package/src/owner/shape.ts +1 -1
- package/src/owner/survey.ts +27 -18
- package/src/router.ts +4 -1
- package/src/rules/common/types.ts +1 -1
- package/src/signals/state.ts +1 -4
- package/src/sync/agent-removal.ts +7 -10
- package/src/sync/claude-launch.ts +36 -1
- package/src/sync/common/constants.ts +4 -0
- package/src/sync/common/index.ts +1 -0
- package/src/sync/common/symlink.ts +9 -0
- package/src/sync/common/types.ts +2 -2
- package/src/sync/planner.ts +10 -12
- package/src/sync/settings.ts +1 -1
- package/src/ui/keyboard.ts +3 -1
- package/src/ui/prompt.ts +4 -2
- package/src/visualize/assets.ts +370 -195
- package/src/visualize/charts.ts +11 -2
- package/src/visualize/compare-css.ts +30 -0
- package/src/visualize/compare-render.ts +194 -0
- package/src/visualize/compare-schema.ts +81 -0
- package/src/visualize/compare-validate.ts +126 -0
- package/src/visualize/constants.ts +29 -3
- package/src/visualize/diagrams.ts +1 -1
- package/src/visualize/gate.ts +136 -0
- package/src/visualize/icons.ts +5 -2
- package/src/visualize/index.ts +2 -0
- package/src/visualize/kinds-css.ts +54 -0
- package/src/visualize/kinds-render.ts +693 -0
- package/src/visualize/kinds-schema.ts +148 -0
- package/src/visualize/kinds-validate.ts +184 -0
- package/src/visualize/labels-vi.ts +109 -0
- package/src/visualize/labels.ts +49 -0
- package/src/visualize/layout.ts +10 -5
- package/src/visualize/page.ts +99 -61
- package/src/visualize/render.ts +48 -7
- package/src/visualize/schema.ts +21 -1
- package/src/visualize/sections.ts +115 -34
- package/src/visualize/sources.ts +270 -0
- package/src/visualize/theme.ts +472 -0
- package/src/visualize/validate.ts +6 -0
- package/src/wiki/anchors.ts +1 -1
- 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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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:
|
|
45
|
-
extra:
|
|
54
|
+
trust: { root, scripts, readOnlyScripts: policy.readOnlyScripts },
|
|
55
|
+
extra: policy.commands,
|
|
46
56
|
})
|
|
47
57
|
: [];
|
|
48
58
|
|
package/base/hooks/post-tool.ts
CHANGED
|
@@ -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(
|
|
21
|
+
input: JSON.parse(stdin),
|
|
21
22
|
});
|
|
22
23
|
|
|
23
24
|
if (output !== undefined) {
|
|
@@ -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
|
-
|
|
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 {
|
package/base/hooks/stop.ts
CHANGED
|
@@ -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(
|
|
24
|
+
input: JSON.parse(stdin),
|
|
24
25
|
});
|
|
25
26
|
|
|
26
27
|
if (output !== undefined) {
|
package/base/make/vulcan.mk
CHANGED
|
@@ -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
|
|
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
|
|
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 (
|
|
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
|
|
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
|
|
88
|
-
no package,
|
|
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.**
|
|
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": "
|
|
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
|
|
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
|
|
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**:
|
|
74
|
-
|
|
75
|
-
set the owner did not give.
|
|
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
|
+
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),
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
48
|
-
"@venizia/vulcan-okf": "0.4.
|
|
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.
|
|
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) &&
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
16
|
+
type TAgentSource = TConstValue<typeof AgentSources>;
|
|
17
17
|
|
|
18
18
|
export type TAgentResolution =
|
|
19
19
|
| {
|
package/src/agents/exclude.ts
CHANGED
|
@@ -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
|
-
|
|
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[];
|
package/src/agents/hooks-json.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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 };
|
package/src/agents/prompt.ts
CHANGED
|
@@ -28,13 +28,13 @@ export const renderAgentsQuestion = (question: IAgentQuestion): string => {
|
|
|
28
28
|
].join('\n');
|
|
29
29
|
};
|
|
30
30
|
|
|
31
|
-
|
|
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
|
-
|
|
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 = [
|