@venizia/vulcan 0.4.10-2 → 0.4.10-4
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/README.md +26 -18
- package/base/hooks/guard-outside.ts +10 -19
- package/base/hooks/guard-writes.ts +3 -24
- package/base/make/vulcan.mk +1 -4
- package/base/rules.md +4 -4
- package/base/skills/visualize-work/SKILL.md +1 -1
- package/base/skills/visualize-work/references/spec.md +1 -1
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/resolve.ts +1 -0
- package/src/board/command.ts +16 -1
- package/src/board/common/constants.ts +2 -0
- package/src/board/common/types.ts +2 -2
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +13 -2
- package/src/board/settings.ts +1 -1
- package/src/commands/graph.command.ts +6 -0
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +2 -0
- package/src/commands/sync.command.ts +5 -1
- package/src/commands/table.ts +327 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +2 -0
- package/src/commit/hook.ts +44 -4
- package/src/common/constants.ts +7 -3
- package/src/common/env-variables.ts +37 -0
- package/src/common/index.ts +1 -0
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +162 -20
- package/src/create/add-app.ts +5 -0
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +106 -4
- package/src/doctor/common/constants.ts +26 -0
- package/src/doctor/runner.ts +3 -0
- package/src/doctor/schema.ts +4 -0
- package/src/hooks/owner-reply.ts +5 -0
- package/src/hooks/project-guards.ts +28 -4
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/session-digest.ts +9 -0
- package/src/init/scaffold.ts +1 -0
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +1 -0
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +33 -9
- package/src/manifest/render.ts +70 -9
- package/src/owner/constants.ts +3 -1
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +37 -6
- package/src/router.ts +4 -130
- package/src/rules/base.ts +1 -0
- package/src/signals/loop.ts +1 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +1 -0
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/page.ts +4 -4
- package/src/visualize/render.ts +2 -1
- package/src/visualize/theme.ts +43 -12
- package/src/wiki/anchors.ts +1 -0
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,28 @@ 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
|
|
20
|
-
| `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
|
|
22
|
-
| `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
|
-
| `
|
|
21
|
+
| `init [--key <KEY>]` | 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`, `.dockerignore`, `bunfig.toml`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. `--key` is the project's flow key (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name); it counts only while no config exists yet. 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 |
|
|
22
|
+
| `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>] [--scope <@scope>] [--key <KEY>]` | Create a new monorepo with its first app from a framework preset: the root manifests (with `.dockerignore` and `bunfig.toml`), 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. `--scope` names the app's package `@scope/<name>`; `--key` is the flow key, as for `init`. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
|
|
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 |
|
|
24
|
+
| `sync [--agents <list>\|list] [--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`. It also writes the adapters of the other agents you chose (`--agents claude,omp` or `none`, kept in `.agents/vulcan.local.json`; `--agents list` prints the table), the Atlas block in `AGENTS.md`, and the clone's `commit-msg` hook when a commit check is on. 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 |
|
|
25
|
+
| `preset diff <package> [--preset <name\|file:path>] [--api <app> \| --no-api] [--full] [--check]` | Read-only: set each file the preset makes now against the file the package has (same, differs, missing); `--preset` names the preset when it cannot be found from the package, `--api` or `--no-api` says what a frontend proxies to, `--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 [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]` | 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. `--repo` is repeatable; `--no-github` leaves GitHub out |
|
|
30
|
+
| `board serve [--port <n>] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]` | Serve the same page on 127.0.0.1 (default port 4317) and push new events to the open page with no reload, until Ctrl+C |
|
|
31
|
+
| `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 |
|
|
32
|
+
| `event add \| tail` | Write a line to the agent event log (`.agents/local/events/<day>.jsonl`) or read it |
|
|
33
|
+
| `visualize <spec.json> [--out <name>] \| --schema` | Make one small static HTML page from a JSON spec, in `.agents/local/prototypes/` (`--out` names the page); `--schema` prints the spec's schema |
|
|
34
|
+
| `profile [show\|edit\|reset]` | Tell VULCAN how you like to work (reply language, tone, habits) in `.agents/local/profile.json` |
|
|
35
|
+
| `clean [--tmp\|--worktrees\|--clones\|--cache\|--all] [--yes]` | List what an agent left under `.agents/local/` (a dry run) and, with `--yes`, remove it |
|
|
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 |
|
|
37
|
+
| `graph build [--full]` | Write the code graph of the project (the short name of `x atlas graph build`); `--full` reads everything again |
|
|
38
|
+
| `graph status [--json]` | Say whether the graph still matches the files it was built from (fresh, behind, diverged or unknown) |
|
|
25
39
|
| `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
|
-
| `help`, `version` | |
|
|
40
|
+
| `help`, `version` | `help` prints the usage; `version` prints the installed version |
|
|
27
41
|
|
|
28
|
-
Diagnostics go to stderr;
|
|
42
|
+
Diagnostics go to stderr; a command that produces a result prints only that on stdout, and `vulcan x atlas mcp` is a
|
|
29
43
|
clean MCP stdio server.
|
|
30
44
|
|
|
31
45
|
## The project config
|
|
@@ -46,29 +60,23 @@ export default {
|
|
|
46
60
|
} satisfies VulcanConfig;
|
|
47
61
|
```
|
|
48
62
|
|
|
49
|
-
An unknown key is an error; every error names the file and the field.
|
|
63
|
+
An unknown key is an error; every error names the file and the field. The example shows a few keys; each key, with its type and default, is in `docs/wiki/content/references/configuration/index.md`. Three that a new project often wants: `local.tmp` (a short folder for the temporary files of a session, so a browser socket path fits), `theme` (the colours, fonts and radius of the board and the pages VULCAN makes) and `board` (the owner, title, logo and agents of `vulcan board`).
|
|
50
64
|
|
|
51
65
|
## What ships (`base/`)
|
|
52
66
|
|
|
53
67
|
- `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (51 rules).
|
|
54
68
|
- `slots.json` - rules a project picks a wording for (V-W-01 today).
|
|
55
|
-
- `skills/` -
|
|
56
|
-
- `hooks/` -
|
|
69
|
+
- `skills/` - 12 project-neutral skills, described in `docs/wiki/content/references/skills.md` (a project-specific skill stays in its project). Each but `knowledge-sync` has an `evals/evals.json`; `make skill-evals` runs them against models and spends quota.
|
|
70
|
+
- `hooks/` - 16 hook files, described in `docs/wiki/content/references/hooks/index.md`.
|
|
57
71
|
- `claude/settings.json`, `make/vulcan.mk`, `templates/`.
|
|
72
|
+
- `agents.json` (the coding agents `sync` can write adapters for), `commit-agents.json` (the agent names, addresses and phrases `commit-check` looks for in a message), `ci-global.json` (the files that make `ci affected` select every package), `checks/` (the wiki link and anchor gates), `extensions/` (the guards for an agent that loads an extension, such as omp or pi) and `references/` (testing, design pass, evidence and the other pages the skills link to).
|
|
58
73
|
|
|
59
74
|
A project **extends** this: it adds rules with bare IDs (the base owns `V-`), skills, hooks and make targets, and never edits
|
|
60
75
|
or shadows a shipped one.
|
|
61
76
|
|
|
62
77
|
## `doctor` checks
|
|
63
78
|
|
|
64
|
-
`
|
|
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).
|
|
79
|
+
`doctor` runs its checks in order; each is described in `docs/wiki/content/references/commands/doctor.md`.
|
|
72
80
|
|
|
73
81
|
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
82
|
|
|
@@ -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
|
-
*
|
|
14
|
-
* read before anything is imported. It
|
|
15
|
-
*
|
|
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.
|
|
@@ -29,32 +30,22 @@ try {
|
|
|
29
30
|
const { HookDecision } = await import('../../src/hooks/decision.ts');
|
|
30
31
|
const { OutsideGuard } = await import('../../src/hooks/guard-outside.ts');
|
|
31
32
|
const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
|
|
33
|
+
const { ProjectTmp } = await import('../../src/hooks/project-tmp.ts');
|
|
34
|
+
const { relative } = await import('node:path');
|
|
32
35
|
const input = ManifestGuard.parseHookInput({ text });
|
|
33
36
|
|
|
34
37
|
if (input) {
|
|
35
38
|
const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
}
|
|
39
|
+
const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
|
|
40
|
+
const { toolOwnedPaths, outside } = ProjectGuards.readPolicy({ root: projectRoot });
|
|
50
41
|
|
|
51
42
|
const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
|
|
52
43
|
|
|
53
44
|
if (hits.length > 0) {
|
|
54
45
|
const isScratchpad = hits.some((hit) => hit.isAgentToolScratchpad);
|
|
55
46
|
const hitLines = hits.map((hit) => ` - ${hit.message} (${hit.path})`);
|
|
56
|
-
const
|
|
57
|
-
|
|
47
|
+
const tmpFolder = relative(projectRoot, ProjectTmp.projectOf({ root: projectRoot }));
|
|
48
|
+
const places = `Scratch files go under ${tmpFolder}/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder.`;
|
|
58
49
|
|
|
59
50
|
const isDeny = isScratchpad || outside === GuardDecisions.DENY;
|
|
60
51
|
let reason: string[];
|
|
@@ -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
|
|
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/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 okf-check okf-check-strict okf-gen okf-coverage
|
|
10
|
+
.PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage \
|
|
11
11
|
surface-gen surface-check atlas-symbols atlas-releases wiki-links-check wiki-anchors-check
|
|
12
12
|
|
|
13
13
|
vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
|
|
@@ -29,9 +29,6 @@ okf-gen: ## Regenerate the generated pages and regions of the knowledge bundle
|
|
|
29
29
|
okf-coverage: ## Report how much of the code the knowledge bundle covers
|
|
30
30
|
@$(VULCAN) x okf coverage
|
|
31
31
|
|
|
32
|
-
okf-viz: ## Build the knowledge graph view
|
|
33
|
-
@$(VULCAN) x okf viz
|
|
34
|
-
|
|
35
32
|
# The public surface: an optional API gate a project commits and checks. It reads the built .d.ts -
|
|
36
33
|
# build first.
|
|
37
34
|
surface-gen: ## Write the public API surface from the built .d.ts
|
package/base/rules.md
CHANGED
|
@@ -49,20 +49,20 @@ 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). 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
|
|
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) |
|
|
63
63
|
| V-B-06 | **Small never cuts safety.** Saving code never removes input validation, error handling, security checks or data safety: they are part of the task at any size (V-S-03, V-C-06 and V-B-04 still apply). | SOFT |
|
|
64
64
|
| V-B-07 | **Say what you skipped.** Report plainly what was not done, not checked or left as a shortcut; never let a check that did not run read as one that did. A deliberate shortcut in code is marked `// SHORTCUT: <what>, <why>, <revisit when>` so it can be found again. | SOFT - build-a-feature step 8 summary, session-start digest |
|
|
65
|
-
| V-B-08 | **Leave no trace, and none outside the project.** Everything you create while you work - scratch files, temporary files, logs, worktrees, clones of other repositories, subagent output - lives under the project's gitignored `.agents/local
|
|
65
|
+
| V-B-08 | **Leave no trace, and none outside the project.** Everything you create while you work - scratch files, temporary files, logs, worktrees, clones of other repositories, subagent output - lives under the project's gitignored `.agents/local/`, or in the folder `local.tmp` names, always inside the project (`tmp/`, `worktrees/`, `clones/`; each directory's lifetime is in the table of the rules reference) and you remove it when its lifetime ends: scratch when the task ends, a worktree when its branch is merged or abandoned, a clone when the research is reported. Nothing goes in the system temp directory, the home directory or any other place outside the project; the done report says what was removed and what was kept, and why. The scratchpad folder an agent tool offers is a system temp directory, not one of its own files: never use it, even when the tool's text says to. What a tool writes for itself (its task output, its memory) is outside this rule's reach. | SOFT |
|
|
66
66
|
| V-B-09 | **Agent scripting uses bun by default.** A script you write to do a task (an edit, a check, a report) is `bun -e '…'` or `bun file.ts`, with `Bun.file()` for files. Python or another language is allowed when the task needs it - an existing project script, a tool only that language has - and you say so in one line. | SOFT - the guard-scripting hook adds a reminder when a command runs python, python3 or pip; it never blocks |
|
|
67
67
|
|
|
68
68
|
## C - Code and writing
|
|
@@ -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
|
|
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 TSDoc when it tells the reader what the name and the types do not: a summary first, `@param`/`@returns` without `{type}`, `@default`, `@deprecated` with what replaces it, `@example` when use is not obvious, on the declaration itself; it stays within the three-line limit except an `@example`. Write it when you write or change that export, never as a sweep; a TSDoc that no longer matches the code is wrong and is fixed in the same change. 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 |
|
|
@@ -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
|
|
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,
|
|
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 |
|