@venizia/vulcan 0.2.0-1 → 0.2.0-3

package/README.md

@@ -49,7 +49,7 @@ An unknown key is an error; every error names the file and the field.
 
 - `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (37 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
 - `slots.json` - rules a project picks a wording for (V-W-01 today).
-- `skills/` - `knowledge-sync`, `docs-writing` (project-neutral; a project-specific skill stays in its project).
+- `skills/` - `knowledge-sync`, `docs-writing`, `docs-update` (project-neutral; a project-specific skill stays in its project).
 - `hooks/` - `session-start.ts` (prints the rules digest) and `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call).
 - `claude/settings.json`, `make/vulcan.mk`, `templates/`.
 

package/base/skills/docs-update/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: docs-update
+description: Updates the project's human-facing docs after a code change - refreshes the page that owns a topic, adds a page for a new feature, writes the changelog entry, then runs the docs gates until they pass. Use when the user asks to update the wiki or the docs, document a change or a feature, refresh a page, add a changelog entry, or keep the docs in step with the code.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
+---
+
+# Docs update
+
+The docs under `knowledge.wiki` are what people read; the knowledge bundle under `knowledge.bundle`
+is what agents read. Never copy a page from one into the other. **The code is ground truth**: when a
+page and the code disagree, the page is the bug. Nothing is committed: the user reviews the diff.
+
+`$ARGUMENTS` says what to document - `add a changelog entry for the retry option`, `refresh the
+storage reference`. With no arguments, ask what to document.
+
+## Checklist
+
+Copy it into your reply and tick it off, in order:
+
+```
+- [ ] 1. Paths read from the manifest
+- [ ] 2. Code read - the changed source, not a diff summary, not dist/, not another doc
+- [ ] 3. Page picked - the page that owns the topic; a new one only when none does, wired in
+- [ ] 4. Page written and self-reviewed with the docs-writing skill
+- [ ] 5. Changelog entry written (release-worthy changes only)
+- [ ] 6. Gates green (loop until they are)
+- [ ] 7. Reported; nothing committed
+```
+
+## 1. Paths
+
+1. `bun x --no-install vulcan doctor` passes, so the manifest is fresh. Fix what it names first.
+2. Read `.agents/vulcan.manifest.json`. Every path comes from it, never from a layout you expect:
+
+| Key | What it gives you |
+|---|---|
+| `knowledge.wiki` | the docs root - every page lives under it |
+| `knowledge.changelogs` | the changelog directory |
+| `packages[].path` | where each package's source lives |
+| `packages[].name` | the npm names a changelog entry declares |
+| `name` | the brand, upper case in prose |
+
+A key the manifest lacks is a part the project does not have. No `knowledge.wiki`: the human-facing
+docs are the package READMEs (`<packages[].path>/README.md`) and the changelog - ask before creating
+a docs root. No `knowledge.changelogs`: skip step 5 and say so.
+
+## 2. Code
+
+Read the source the change touched, under `packages[].path`: `git diff HEAD --stat -- <paths>` for
+uncommitted work, `git log -p -- <paths>` for committed work. Open the files themselves. Write down
+every name, signature, option and default you will mention - each one is verified here, not later.
+
+## 3. Pick the page
+
+1. Find the page that owns the topic: `grep -rln '<symbol or feature>' <knowledge.wiki>`, plus the
+   package READMEs. Edit that page. A second page on the same subject is how docs drift.
+2. No page owns it: create one in the section whose pages are the same kind, copying the frontmatter
+   and layout of 2-3 siblings. List it where a sibling is listed - the sidebar config, a nav file,
+   the section `index.md` (`grep -rn '<sibling file name>' --exclude-dir=node_modules .`).
+
+## 4. Write
+
+Write and self-review with the [docs-writing](../docs-writing/SKILL.md) skill, its mechanical gates
+included. Then apply the docs rules in `.agents/rules.md` (the generator's limits, the link style).
+Every code sample uses the names and signatures from step 2.
+
+## 5. Changelog
+
+Only for a release-worthy change: a feature, a fix a user notices, a breaking change.
+
+1. **The file.** `<knowledge.changelogs>/YYYY-MM-DD-<slug>.md`, from the directory's `template.md`.
+   No template: copy the shape of the newest entry. Keep only the sections that apply. When an
+   entry for the coming release already exists, add a bullet to it instead of opening a second.
+2. **The `packages:` list** (Project Contract v1, C3). The frontmatter lists the npm names, from
+   `packages[].name`, of every package the entry covers: `packages: ['@scope/core']`. An entry about
+   no package, such as repository tooling, carries `packages: []`. Never leave the list out -
+   `okf check --strict` fails the entry.
+3. **The content.** What changed, who is affected, how to migrate. It is not a commit log.
+4. **The index.** When the directory's `index.md` lists entries, add a row in its order.
+
+## 6. Gates - validate, fix, repeat
+
+1. `bun x --no-install vulcan doctor`
+2. `bun x --no-install vulcan x okf check --strict` - the bundle, the house rules, every changelog
+   entry's `packages:` list.
+3. The project's own docs build, when it has one. Discover it, never assume a target name: the
+   targets `.agents/rules.md` names, `make help`, the Makefile and its `*.mk` files (`grep -n '<the
+   wiki directory>'`), the `scripts` of the `package.json` nearest `knowledge.wiki`. Run every docs
+   target you find - build, link check, anchor check, docs lint. None found: say so in the report.
+
+A gate that fails: fix what it names, go back to the step that caused it, then run every gate again.
+Stop only when all of them pass. Never weaken a gate to make it pass.
+
+## 7. Report
+
+A fact an agent reads changed too? Update its concept in the knowledge bundle in the same change; a
+full re-audit is the `knowledge-sync` skill's job. Report in the user's language: the pages changed
+and created, the changelog entry and its `packages:` list, each gate with its result, anything
+skipped and why. **Do not commit.** Leave the diff for the user.

package/base/skills/docs-update/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "docs-update",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "I changed how one of our packages behaves - see the uncommitted diff, or the last commit if the tree is clean. Update the docs to match and add the changelog entry. Do not commit.",
+      "expected_output": "Reads knowledge.wiki, knowledge.changelogs and packages[].path from .agents/vulcan.manifest.json; reads the changed source itself; edits the existing page that owns the topic instead of opening a duplicate; writes a YYYY-MM-DD-<slug>.md entry from the changelog template whose packages: list carries the npm names it covers; runs vulcan doctor, okf check --strict and the docs build it discovered, looping until all pass; nothing committed",
+      "files": [".agents/vulcan.manifest.json"]
+    },
+    {
+      "id": 1,
+      "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.",
+      "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",
+      "files": [".agents/vulcan.manifest.json"]
+    },
+    {
+      "id": 2,
+      "prompt": "The docs for the first package in .agents/vulcan.manifest.json are out of date. Refresh them against the current source. No changelog entry - nothing shipped. Do not commit.",
+      "expected_output": "Finds the page or README that owns that package (under knowledge.wiki, or <packages[].path>/README.md when the manifest has no wiki); verifies every name, signature and default against the source under packages[].path and fixes each drift; creates no new page and no changelog entry; runs the gates; reports each claim that changed with its source file; nothing committed",
+      "files": [".agents/vulcan.manifest.json"]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/vulcan",
-  "version": "0.2.0-1",
+  "version": "0.2.0-3",
   "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
   "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
   "repository": {
@@ -44,8 +44,8 @@
     "test": "NODE_ENV=test bun test --env-file=.env.test"
   },
   "dependencies": {
-    "@venizia/vulcan-atlas": "0.2.0-1",
-    "@venizia/vulcan-okf": "0.2.0-1",
+    "@venizia/vulcan-atlas": "0.2.0-3",
+    "@venizia/vulcan-okf": "0.2.0-3",
     "zod": "^4.5.4"
   },
   "devDependencies": {

package/src/doctor/skills.ts

@@ -33,13 +33,46 @@ const filesOf = (opts: { directory: string }): string[] =>
 const lineCountOf = (opts: { text: string }): number =>
   opts.text.replace(/\n$/, '').split('\n').length;
 
-const frontmatterOf = (opts: { text: string }): Record<string, unknown> => {
+const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
+  try {
+    return { value: Bun.YAML.parse(opts.text) };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+/**
+ * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
+ * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
+ */
+const frontmatterOf = (opts: {
+  text: string;
+}): { data: Record<string, unknown>; error?: string } => {
   const block = FRONTMATTER.exec(opts.text)?.[1];
-  const parsed: unknown = block === undefined ? undefined : Bun.YAML.parse(block);
 
-  return typeof parsed === 'object' && parsed !== null
-    ? Object.fromEntries(Object.entries(parsed))
-    : {};
+  if (block === undefined) {
+    return { data: {} };
+  }
+
+  const parsed = parseYaml({ text: block });
+
+  if (parsed.error !== undefined) {
+    const blockLines = block.split('\n');
+    const failsAt = blockLines.findIndex(
+      (_line, index) =>
+        parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
+    );
+    const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
+
+    return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
+  }
+
+  return {
+    data:
+      typeof parsed.value === 'object' && parsed.value !== null
+        ? Object.fromEntries(Object.entries(parsed.value))
+        : {},
+  };
 };
 
 /** Every rule one skill directory breaks, each a message naming the file. */
@@ -53,19 +86,23 @@ export const lintSkill = (opts: { directory: string }): string[] => {
   const problems: string[] = [];
   const text = readFileSync(skillFile, 'utf8');
   const frontmatter = frontmatterOf({ text });
-  const { name, description } = frontmatter;
+  const { name, description } = frontmatter.data;
 
-  if (typeof name !== 'string' || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
+  // One file a project cannot parse is a finding about that file - the other checks still run.
+  if (frontmatter.error !== undefined) {
+    problems.push(`SKILL.md: ${frontmatter.error}`);
+  } else if (typeof name !== 'string' || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
     problems.push(
       `SKILL.md: name '${String(name)}' - at most 64 characters of a-z, 0-9 and hyphens, never 'claude' or 'anthropic'`,
     );
   }
 
   if (
-    typeof description !== 'string' ||
-    description.trim().length === 0 ||
-    description.length > MAX_DESCRIPTION ||
-    XML_TAG.test(description)
+    frontmatter.error === undefined &&
+    (typeof description !== 'string' ||
+      description.trim().length === 0 ||
+      description.length > MAX_DESCRIPTION ||
+      XML_TAG.test(description))
   ) {
     problems.push('SKILL.md: the description must be 1-1024 characters with no XML tags');
   }

package/src/sync/planner.ts

@@ -225,7 +225,27 @@ const planSkillLinks = (opts: { root: string }): ISyncAction[] => {
       : { path, status: SyncStatuses.CREATED, apply: link };
   });
 
-  return [...links, ...shadowing];
+  // A link into the shipped skills whose skill this VULCAN no longer has (a downgrade, a retired
+  // skill) is sync's own and dead: taken back. Any other link or directory stays.
+  const shippedRoots = [stableSkills, join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY)];
+  const linked = new Set(sources.map(source => basename(source)));
+  const stale = (existsSync(target) ? readdirSync(target) : [])
+    .filter(name => !linked.has(name))
+    .map(name => join(target, name))
+    .filter(
+      path =>
+        isSymlink({ path }) &&
+        !existsSync(path) &&
+        shippedRoots.some(root => readlinkSync(path).startsWith(`${root}/`)),
+    )
+    .map((path): ISyncAction => ({
+      path,
+      status: SyncStatuses.REMOVED,
+      note: 'a shipped skill this version no longer has',
+      apply: () => rmSync(path),
+    }));
+
+  return [...links, ...shadowing, ...stale];
 };
 
 /** The committed project manifest (Project Contract v1, C1), rendered from the config. */