@venizia/vulcan 0.2.0-0 → 0.2.0-2

package/README.md

@@ -17,10 +17,10 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
 | Command | What it does |
 |---|---|
 | `init [--config ts\|mts\|mjs\|js]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.*`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, a Makefile `-include`. Never overwrites; prints what to add to existing files, and the atlas `.mcp.json` entry for projects with a wiki |
-| `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`), `.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), `.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. `--prune` also removes what sync proves stale and did not write: an old VULCAN or plugin-era hook command (a shipped hook in an old form, or a `.agents/` hook whose file is gone) and a dead `.claude/skills` link - never a developer's own hook or a real directory. Idempotent |
+| `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`), `.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. `--prune` also removes what sync proves stale and did not write: an old VULCAN or plugin-era hook command (a shipped hook exactly as an older VULCAN released it, or a `.agents/` hook whose file is gone) and a dead `.claude/skills` link - never a developer's own hook, a customised shipped command, a real directory or a symlinked `.claude/skills`. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
 | `doctor` | Check the project follows VULCAN; exit 1 on any violation |
 | `upgrade [<version\|tag>]` | Install the target `@venizia/vulcan` (default: the `next` dist-tag), then run `sync` from the newly installed CLI |
-| `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas` |
+| `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 |
 | `help`, `version` | |
 
 Diagnostics go to stderr; `vulcan` writes nothing to stdout of its own, so `vulcan x atlas mcp` is a
@@ -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/`.
 
@@ -63,7 +63,7 @@ or shadows a shipped one.
 shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
 not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
 `prune` (no stale hook command or dead skill link - `sync --prune` removes them) ·
-`style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it).
+`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`).
 
 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.
 

package/base/claude/settings.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; echo \"vulcan: the session-start hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install\" >&2; exit 2"
+            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; [ -f \"$f\" ] || echo \"vulcan: the session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-start hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
           }
         ]
       }
@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( --?[a-z][a-z0-9-]*(=[A-Za-z0-9._-]+)?)*\"'; then exit 0; fi; echo \"vulcan: the guard-writes hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install (the one command that passes until then)\" >&2; exit 2"
+            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; then exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-writes hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-writes hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
           }
         ]
       }

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-0",
+  "version": "0.2.0-2",
   "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-0",
-    "@venizia/vulcan-okf": "0.2.0-0",
+    "@venizia/vulcan-atlas": "0.2.0-2",
+    "@venizia/vulcan-okf": "0.2.0-2",
     "zod": "^4.5.4"
   },
   "devDependencies": {

package/src/commands/sync.command.ts

@@ -6,6 +6,15 @@ import { diffBaseRules, planPrune, planSync, SyncConstants, SyncStatuses } from
 
 const DRY_RUN_FLAG = '--dry-run';
 const PRUNE_FLAG = '--prune';
+const LABEL_WIDTH = 9;
+
+/** Under --dry-run nothing is written, so a write is labelled as what it would do. */
+const DRY_RUN_LABELS: Record<string, string> = {
+  [SyncStatuses.CREATED]: 'would create',
+  [SyncStatuses.REPLACED]: 'would replace',
+  [SyncStatuses.REMOVED]: 'would remove',
+};
+const DRY_RUN_LABEL_WIDTH = Math.max(...Object.values(DRY_RUN_LABELS).map(label => label.length));
 
 export const runSyncCommand = async (opts: ICommandContext): Promise<number> => {
   const loaded = await loadConfig({ root: opts.cwd });
@@ -22,6 +31,7 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
   const actions = [...planSync({ root: opts.cwd, config: loaded.config }), ...pruned];
   // Read before the manifest action rewrites the hashes it compares against.
   const changes = diffBaseRules({ root: opts.cwd });
+  const width = dryRun ? DRY_RUN_LABEL_WIDTH : LABEL_WIDTH;
 
   for (const action of actions) {
     if (!dryRun) {
@@ -29,14 +39,13 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
     }
 
     const note = action.note === undefined ? '' : ` (${action.note})`;
+    const label = (dryRun ? DRY_RUN_LABELS[action.status] : undefined) ?? action.status;
 
-    process.stderr.write(
-      `  ${action.status.padEnd(9)} ${relative(opts.cwd, action.path)}${note}\n`,
-    );
+    process.stderr.write(`  ${label.padEnd(width)} ${relative(opts.cwd, action.path)}${note}\n`);
   }
 
   for (const { id, change, text } of changes) {
-    process.stderr.write(`  ${change.padEnd(9)} ${[id, text].filter(Boolean).join(' ')}\n`);
+    process.stderr.write(`  ${change.padEnd(width)} ${[id, text].filter(Boolean).join(' ')}\n`);
   }
 
   const settingsBroken = actions.some(

package/src/doctor/checks.ts

@@ -2,6 +2,7 @@ import { Glob } from 'bun';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
+import { resolvePackages } from '../config/index.ts';
 import type { TResolvedConfig } from '../config/index.ts';
 import {
   parseBaseReferences,
@@ -271,15 +272,20 @@ const hasStylePackage = (opts: { directory: string }): boolean => {
 /**
  * D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
  * holds the config declares it, or the root does. A project with no lint config declares it at the
- * root.
+ * root. Owners are `packages/*` and every configured package's `path`, such as `umbras/kit`.
  */
 export const checkStyle = (opts: ICheckContext): IViolation[] => {
   const violations: IViolation[] = [];
   const owners = [
-    '.',
-    ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
-      join('packages', name),
-    ),
+    ...new Set([
+      '.',
+      ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
+        join('packages', name),
+      ),
+      ...resolvePackages({ config: opts.config }).map(
+        entry => relative(opts.root, join(opts.root, entry.path)) || '.',
+      ),
+    ]),
   ];
   const isRootDeclared = hasStylePackage({ directory: opts.root });
   let lintConfigs = 0;

package/src/router.ts

@@ -66,6 +66,11 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
     return ExitCodes.FAILURE;
   }
 
+  // `x` hands its arguments to the tool, so only a help flag in the tool's place is vulcan's.
+  if (name === VulcanCommands.X && HELP_ALIASES.has(args[0] ?? '')) {
+    return runHelpCommand();
+  }
+
   const accepted = ACCEPTED_ARGS[name];
 
   if (accepted !== undefined) {

package/src/sync/common/constants.ts

@@ -26,6 +26,8 @@ export class SyncConstants {
   static readonly MANAGED_FILE = 'vulcan-managed.json';
   static readonly SKILLS_DIRECTORY = 'skills';
   static readonly SKILL_FILE = 'SKILL.md';
+  /** The settings key of hook entries: sync takes a managed hook back by its command, not its whole entry. */
+  static readonly HOOKS_KEY = 'hooks';
   /** Objects of independent entries: merged one level deep, so personal entries survive shared ones. */
   static readonly MERGE_ONE_LEVEL = new Set(['permissions', 'hooks', 'enabledPlugins', 'env']);
 }

package/src/sync/planner.ts

@@ -162,6 +162,19 @@ const findSkillDirectories = (opts: { directory: string }): string[] =>
 /** Shipped and project skills, linked flat into `.claude/skills/<name>`; a real directory there is left alone. */
 const planSkillLinks = (opts: { root: string }): ISyncAction[] => {
   const target = join(opts.root, SyncConstants.CLAUDE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY);
+
+  // A symlinked skills directory points outside the project: writing links through it would land them there.
+  if (isSymlink({ path: target })) {
+    return [
+      {
+        path: target,
+        status: SyncStatuses.SKIPPED,
+        note: 'a symlink - left untouched',
+        apply: NO_CHANGE,
+      },
+    ];
+  }
+
   const stableSkills = join(stableBaseDirectoryOf(opts), SyncConstants.SKILLS_DIRECTORY);
   const shipped = findSkillDirectories({
     directory: join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY),

package/src/sync/prune.ts

@@ -3,9 +3,18 @@ import { join } from 'node:path';
 import { BASE_DIRECTORY } from '../common/index.ts';
 import { SyncConstants, SyncStatuses } from './common/index.ts';
 import type { ISyncAction, TSettings } from './common/index.ts';
+import { extractHookCommands, isSettingsObject, removeHookCommands } from './settings.ts';
 
-/** The directory every shipped hook lives in; a command that runs one is VULCAN's. */
-const SHIPPED_HOOKS_PATH = '@venizia/vulcan/base/hooks/';
+/**
+ * The exact hook commands released VULCAN versions shipped (0.1.0-x, then 0.2.0-0). Only these are
+ * an old VULCAN form: a shipped hook a developer customised is theirs, and never pruned.
+ */
+const RETIRED_SHIPPED_COMMANDS = new Set([
+  `bun "\${CLAUDE_PROJECT_DIR}"/node_modules/@venizia/vulcan/base/hooks/session-start.ts`,
+  `bun "\${CLAUDE_PROJECT_DIR}"/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts`,
+  `f="\${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/session-start.ts"; if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then bun "$f"; s=$?; [ "$s" -eq 0 ] && exit 0; exit 2; fi; echo "vulcan: the session-start hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install" >&2; exit 2`,
+  `f="\${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts"; if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then bun "$f"; s=$?; [ "$s" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '"command" *: *"bun (install|i)( --?[a-z][a-z0-9-]*(=[A-Za-z0-9._-]+)?)*"'; then exit 0; fi; echo "vulcan: the guard-writes hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install (the one command that passes until then)" >&2; exit 2`,
+]);
 
 /**
  * A hook a project kept under its own `.agents/` - where plugin-era setups put theirs: the whole
@@ -15,15 +24,15 @@ const SHIPPED_HOOKS_PATH = '@venizia/vulcan/base/hooks/';
 const AGENTS_HOOK =
   /^(?:bun|node)\s+(?:"?\$\{?CLAUDE_PROJECT_DIR\}?"?\/)?(\.agents\/[\w./-]+\.ts)\s*$/;
 
-type THookEntries = Record<string, { hooks?: { command?: string }[] }[]>;
-
 const readJson = (opts: { path: string }): TSettings | undefined => {
   if (!existsSync(opts.path)) {
     return undefined;
   }
 
   try {
-    return JSON.parse(readFileSync(opts.path, 'utf8'));
+    const parsed = { value: JSON.parse(readFileSync(opts.path, 'utf8')) };
+
+    return isSettingsObject(parsed) ? parsed.value : undefined;
   } catch (error) {
     console.error(
       `[readJson] ${opts.path} | ${error instanceof Error ? error.message : String(error)}`,
@@ -33,17 +42,12 @@ const readJson = (opts: { path: string }): TSettings | undefined => {
   }
 };
 
-const commandsOf = (opts: { settings: TSettings | undefined }): string[] =>
-  Object.values((opts.settings?.hooks ?? {}) as THookEntries).flatMap(entries =>
-    entries.flatMap(entry => (entry.hooks ?? []).flatMap(hook => hook.command ?? [])),
-  );
-
 /**
- * A command sync did not write that is known to be stale: a shipped hook in a form this VULCAN no
- * longer writes, or a `.agents/` hook whose file is gone. Any other command is a developer's own.
+ * A command sync did not write that is known to be stale: a shipped hook exactly as an older VULCAN
+ * released it, or a `.agents/` hook whose file is gone. Any other command is a developer's own.
  */
 const isStaleCommand = (opts: { root: string; command: string; shipped: Set<string> }): boolean => {
-  if (opts.command.includes(SHIPPED_HOOKS_PATH)) {
+  if (RETIRED_SHIPPED_COMMANDS.has(opts.command)) {
     return !opts.shipped.has(opts.command);
   }
 
@@ -55,24 +59,23 @@ const isStaleCommand = (opts: { root: string; command: string; shipped: Set<stri
 /** Takes one command out of the settings file; an entry or an event left empty goes with it. */
 const removeHookCommand = (opts: { path: string; command: string }): void => {
   const settings = readJson({ path: opts.path });
-  const hooks = (settings?.hooks ?? {}) as THookEntries;
+  const hooks = { value: settings?.[SyncConstants.HOOKS_KEY] };
 
-  if (settings === undefined) {
+  if (settings === undefined || !isSettingsObject(hooks)) {
     return;
   }
 
-  for (const [event, entries] of Object.entries(hooks)) {
-    const kept = entries
-      .map(entry => ({
-        ...entry,
-        hooks: (entry.hooks ?? []).filter(hook => hook.command !== opts.command),
-      }))
-      .filter(entry => entry.hooks.length > 0);
+  for (const [event, entries] of Object.entries(hooks.value)) {
+    if (!Array.isArray(entries)) {
+      continue;
+    }
+
+    const kept = removeHookCommands({ entries, commands: new Set([opts.command]) });
 
     if (kept.length > 0) {
-      hooks[event] = kept;
+      hooks.value[event] = kept;
     } else {
-      delete hooks[event];
+      delete hooks.value[event];
     }
   }
 
@@ -96,20 +99,23 @@ export const planPrune = (opts: { root: string }): ISyncAction[] => {
   const directory = join(opts.root, SyncConstants.CLAUDE_DIRECTORY);
   const settingsPath = join(directory, SyncConstants.SETTINGS_FILE);
   const managed = new Set(
-    commandsOf({ settings: readJson({ path: join(directory, SyncConstants.MANAGED_FILE) }) }),
+    extractHookCommands({
+      settings: readJson({ path: join(directory, SyncConstants.MANAGED_FILE) }),
+    }),
   );
   const shipped = new Set(
-    commandsOf({
+    extractHookCommands({
       settings: readJson({ path: join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE) }),
     }),
   );
   const staleCommands = [
-    ...new Set(commandsOf({ settings: readJson({ path: settingsPath }) })),
+    ...new Set(extractHookCommands({ settings: readJson({ path: settingsPath }) })),
   ].filter(
     command => !managed.has(command) && isStaleCommand({ root: opts.root, command, shipped }),
   );
   const skills = join(directory, SyncConstants.SKILLS_DIRECTORY);
-  const deadLinks = existsSync(skills)
+  // lstat, not stat: a symlinked skills directory leads out of the project and is never walked.
+  const deadLinks = lstatSync(skills, { throwIfNoEntry: false })?.isDirectory()
     ? readdirSync(skills)
         .map(name => join(skills, name))
         .filter(path => isDeadLink({ path }))

package/src/sync/settings.ts

@@ -48,6 +48,71 @@ export const mergeSettings = (opts: { base: TSettings; overlay: TSettings }): TS
 
 const toKey = (opts: { value: unknown }): string => JSON.stringify(opts.value);
 
+/** The command of a hook; `undefined` when `hook` is not an object with a command string. */
+const toHookCommand = (opts: { hook: unknown }): string | undefined => {
+  const hook = { value: opts.hook };
+
+  return isSettingsObject(hook) && typeof hook.value.command === 'string'
+    ? hook.value.command
+    : undefined;
+};
+
+/** A hook entry and its hooks; `undefined` when `entry` is not an object with a `hooks` array. */
+const toHookEntry = (opts: {
+  entry: unknown;
+}): { entry: TSettings; hooks: unknown[] } | undefined => {
+  const entry = { value: opts.entry };
+
+  return isSettingsObject(entry) && Array.isArray(entry.value.hooks)
+    ? { entry: entry.value, hooks: entry.value.hooks }
+    : undefined;
+};
+
+/** Every hook command in one event's entries; anything that is not an entry or a command is skipped. */
+export const extractEntryCommands = (opts: { entries: unknown }): string[] =>
+  Array.isArray(opts.entries)
+    ? opts.entries.flatMap(entry =>
+        (toHookEntry({ entry })?.hooks ?? []).flatMap(hook => toHookCommand({ hook }) ?? []),
+      )
+    : [];
+
+/** Every hook command of a settings file, across its events. */
+export const extractHookCommands = (opts: { settings: TSettings | undefined }): string[] => {
+  const hooks = { value: opts.settings?.[SyncConstants.HOOKS_KEY] };
+
+  return isSettingsObject(hooks)
+    ? Object.values(hooks.value).flatMap(entries => extractEntryCommands({ entries }))
+    : [];
+};
+
+/**
+ * `entries` without the hooks whose command is in `commands`: an entry's other hooks and keys stay,
+ * an entry left with no hooks goes, and anything that is not an entry is kept as it is.
+ */
+export const removeHookCommands = (opts: {
+  entries: unknown[];
+  commands: Set<string>;
+}): unknown[] =>
+  opts.entries.flatMap(entry => {
+    const hookEntry = toHookEntry({ entry });
+
+    if (hookEntry === undefined) {
+      return [entry];
+    }
+
+    const kept = hookEntry.hooks.filter(hook => {
+      const command = toHookCommand({ hook });
+
+      return command === undefined || !opts.commands.has(command);
+    });
+
+    if (kept.length === hookEntry.hooks.length) {
+      return [entry];
+    }
+
+    return kept.length > 0 ? [{ ...hookEntry.entry, hooks: kept }] : [];
+  });
+
 /** `settings` with its keys in `reference`'s order: keys `reference` has keep their place, new keys follow. */
 const orderKeysLike = (opts: { settings: TSettings; reference: TSettings }): TSettings => {
   const keys = [
@@ -109,7 +174,15 @@ export const removeManagedSettings = (opts: {
 
       if (Array.isArray(innerCurrent) && Array.isArray(innerManaged)) {
         const managedKeys = new Set(innerManaged.map(entry => toKey({ value: entry })));
-        const kept = innerCurrent.filter(entry => !managedKeys.has(toKey({ value: entry })));
+        const unmatched = innerCurrent.filter(entry => !managedKeys.has(toKey({ value: entry })));
+        // A hand-edited entry no longer matches whole: its managed hooks still go, by command.
+        const kept =
+          key === SyncConstants.HOOKS_KEY
+            ? removeHookCommands({
+                entries: unmatched,
+                commands: new Set(extractEntryCommands({ entries: innerManaged })),
+              })
+            : unmatched;
 
         if (kept.length > 0) {
           inner[innerKey] = kept;