@venizia/vulcan 0.1.0-2 → 0.2.0-1

package/src/router.ts

@@ -1,9 +1,25 @@
 import { COMMAND_HANDLERS } from './commands/index.ts';
+import { runHelpCommand } from './commands/help.command.ts';
 import { ExitCodes, VulcanCommands } from './common/index.ts';
 
 const HELP_ALIASES = new Set(['--help', '-h']);
 const VERSION_ALIASES = new Set(['--version', '-v']);
 
+interface IAcceptedArgs {
+  flags: string[];
+  /** Flags that take the next argument as their value. */
+  values: string[];
+  positionals: number;
+}
+
+/** What each command takes; `x` hands everything to its tool, `help` and `version` take nothing. */
+const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
+  [VulcanCommands.INIT]: { flags: [], values: ['--config'], positionals: 0 },
+  [VulcanCommands.SYNC]: { flags: ['--dry-run', '--prune'], values: [], positionals: 0 },
+  [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
+  [VulcanCommands.UPGRADE]: { flags: [], values: [], positionals: 1 },
+};
+
 /** The command name an argv asks for: no argument or a help flag means help. */
 const resolveCommandName = (opts: { first: string | undefined }): string => {
   if (opts.first === undefined || HELP_ALIASES.has(opts.first)) {
@@ -13,6 +29,32 @@ const resolveCommandName = (opts: { first: string | undefined }): string => {
   return VERSION_ALIASES.has(opts.first) ? VulcanCommands.VERSION : opts.first;
 };
 
+/** The first argument `accepted` does not cover - a typo must never run the command as if unsaid. */
+const findUnknownArg = (opts: { args: string[]; accepted: IAcceptedArgs }): string | undefined => {
+  let positionals = 0;
+
+  for (let index = 0; index < opts.args.length; index++) {
+    const arg = opts.args[index];
+
+    if (opts.accepted.values.includes(arg)) {
+      index++;
+      continue;
+    }
+
+    if (opts.accepted.flags.includes(arg)) {
+      continue;
+    }
+
+    if (arg.startsWith('-') || positionals === opts.accepted.positionals) {
+      return arg;
+    }
+
+    positionals++;
+  }
+
+  return undefined;
+};
+
 export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<number> => {
   const [first, ...args] = opts.argv;
   const name = resolveCommandName({ first });
@@ -24,5 +66,28 @@ 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) {
+    if (args.some(arg => HELP_ALIASES.has(arg))) {
+      return runHelpCommand();
+    }
+
+    const unknown = findUnknownArg({ args, accepted });
+
+    if (unknown !== undefined) {
+      process.stderr.write(
+        `vulcan ${name}: unknown argument '${unknown}' - run 'bun x vulcan help'\n`,
+      );
+
+      return ExitCodes.FAILURE;
+    }
+  }
+
   return handler({ args, cwd: opts.cwd });
 };

package/src/rules/base.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BASE_DIRECTORY } from '../common/index.ts';
+import { extractRuleRows, parseRetiredRuleIds, parseRuleIds } from './parser.ts';
+
+const readBaseMarkdown = (): string => readFileSync(join(BASE_DIRECTORY, 'rules.md'), 'utf8');
+
+/** Each base rule's ID with its table row, verbatim. */
+export const readBaseRules = (): Record<string, string> =>
+  Object.fromEntries(
+    extractRuleRows({ markdown: readBaseMarkdown() }).map(row => {
+      const [id] = parseRuleIds({ markdown: row });
+
+      return [id, row];
+    }),
+  );
+
+export const readRetiredRuleIds = (): string[] =>
+  parseRetiredRuleIds({ markdown: readBaseMarkdown() });

package/src/rules/common/constants.ts

@@ -4,4 +4,7 @@ export class RuleConstants {
 
   /** `W-01` (a project's own) or `V-W-01` (namespaced). */
   static readonly ID_SOURCE = '(?:[A-Z]+-)?[A-Z]-\\d{2}';
+
+  /** `V-W-01`: an ID in the base namespace, defined in the base or pointing at it. */
+  static readonly BASE_ID_SOURCE = `${this.BASE_NAMESPACE}[A-Z]-\\d{2}`;
 }

package/src/rules/index.ts

@@ -1,3 +1,4 @@
 export * from './common/index.ts';
+export * from './base.ts';
 export * from './parser.ts';
 export * from './slots.ts';

package/src/rules/parser.ts

@@ -12,3 +12,38 @@ export const parseRuleIds = (opts: { markdown: string }): string[] =>
 /** The table rows of every rule, verbatim, in order. */
 export const extractRuleRows = (opts: { markdown: string }): string[] =>
   opts.markdown.split('\n').filter(line => RULE_ROW.test(line));
+
+const BASE_ID = new RegExp(`(?<![A-Z-])${RuleConstants.BASE_ID_SOURCE}\\b`, 'g');
+const EXTENDS_LIST = new RegExp(
+  `\\bExtends\\s+${RuleConstants.BASE_ID_SOURCE}(?:(?:\\s*,\\s*|\\s+and\\s+)${RuleConstants.BASE_ID_SOURCE})*`,
+  'g',
+);
+const RETIRED_ITEM = new RegExp(`^- \`(${RuleConstants.BASE_ID_SOURCE})\` - `);
+
+/**
+ * The base IDs a project's rules point at, once each, in order: an `Extends V-X, V-Y and V-Z` list
+ * in a table row, and every `V-` ID in a row's first cell. A `V-` ID in prose or a later cell is not one.
+ */
+export const parseBaseReferences = (opts: { markdown: string }): string[] => {
+  const references = new Set<string>();
+
+  for (const line of opts.markdown.split('\n').filter(row => row.startsWith('|'))) {
+    const firstCell = line.split('|')[1] ?? '';
+    const lists = [...line.matchAll(EXTENDS_LIST)].map(match => match[0]);
+
+    for (const text of [...lists, firstCell]) {
+      for (const match of text.matchAll(BASE_ID)) {
+        references.add(match[0]);
+      }
+    }
+  }
+
+  return [...references];
+};
+
+/** The IDs the base retired, one `` - `V-X-NN` - why `` bullet each; they are never reused. */
+export const parseRetiredRuleIds = (opts: { markdown: string }): string[] =>
+  opts.markdown
+    .split('\n')
+    .map(line => RETIRED_ITEM.exec(line)?.[1])
+    .filter((id): id is string => id !== undefined);

package/src/sync/base-rules.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildBaseRuleHashes, ManifestConstants } from '../manifest/index.ts';
+import { readBaseRules, readRetiredRuleIds } from '../rules/index.ts';
+import { BaseRuleChanges } from './common/index.ts';
+import type { IBaseRuleChange } from './common/index.ts';
+
+/** `| V-W-02 | Never write ... | HARD |` gives `Never write ... | HARD`. */
+const toRuleText = (opts: { row: string }): string =>
+  opts.row
+    .trim()
+    .replace(/^\|[^|]*\|\s*/, '')
+    .replace(/\s*\|$/, '');
+
+/** The hashes the committed manifest recorded; none before a first sync or when it is unreadable. */
+const readSyncedHashes = (opts: { root: string }): Record<string, unknown> => {
+  const file = join(opts.root, ManifestConstants.FILE);
+
+  if (!existsSync(file)) {
+    return {};
+  }
+
+  try {
+    const manifest: { rules?: { base?: Record<string, unknown> } } = JSON.parse(
+      readFileSync(file, 'utf8'),
+    );
+
+    return manifest.rules?.base ?? {};
+  } catch (error) {
+    console.error(
+      `[readSyncedHashes] ${file} | ${error instanceof Error ? error.message : String(error)}`,
+    );
+
+    return {};
+  }
+};
+
+/** V3: each base rule added, changed or removed since the committed manifest's last sync. */
+export const diffBaseRules = (opts: { root: string }): IBaseRuleChange[] => {
+  const synced = readSyncedHashes(opts);
+
+  if (Object.keys(synced).length === 0) {
+    return [];
+  }
+
+  const installed = buildBaseRuleHashes();
+  const rows = readBaseRules();
+  const retired = new Set(readRetiredRuleIds());
+  const changes: IBaseRuleChange[] = [];
+
+  for (const [id, hash] of Object.entries(installed)) {
+    if (synced[id] === hash) {
+      continue;
+    }
+
+    changes.push({
+      id,
+      change: synced[id] === undefined ? BaseRuleChanges.ADDED : BaseRuleChanges.CHANGED,
+      text: toRuleText({ row: rows[id] }),
+    });
+  }
+
+  for (const id of Object.keys(synced).filter(syncedId => installed[syncedId] === undefined)) {
+    changes.push({
+      id,
+      change: BaseRuleChanges.REMOVED,
+      text: retired.has(id) ? '(retired)' : '',
+    });
+  }
+
+  return changes;
+};

package/src/sync/common/constants.ts

@@ -3,11 +3,14 @@ export class SyncStatuses {
   static readonly REPLACED = 'replaced';
   static readonly UNCHANGED = 'unchanged';
   static readonly SKIPPED = 'skipped';
+  /** Taken out by `sync --prune`. */
+  static readonly REMOVED = 'removed';
   static readonly SCHEME_SET = new Set<string>([
     this.CREATED,
     this.REPLACED,
     this.UNCHANGED,
     this.SKIPPED,
+    this.REMOVED,
   ]);
   static isValid(value: string): boolean {
     return this.SCHEME_SET.has(value);
@@ -23,6 +26,19 @@ 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']);
 }
+
+/** How a base rule moved between the manifest's last sync and the installed base. */
+export class BaseRuleChanges {
+  static readonly ADDED = 'added';
+  static readonly CHANGED = 'changed';
+  static readonly REMOVED = 'removed';
+  static readonly SCHEME_SET = new Set<string>([this.ADDED, this.CHANGED, this.REMOVED]);
+  static isValid(value: string): boolean {
+    return this.SCHEME_SET.has(value);
+  }
+}

package/src/sync/common/types.ts

@@ -1,5 +1,5 @@
 import type { TConstValue } from '../../common/index.ts';
-import type { SyncStatuses } from './constants.ts';
+import type { BaseRuleChanges, SyncStatuses } from './constants.ts';
 
 export type TSyncStatus = TConstValue<typeof SyncStatuses>;
 
@@ -12,3 +12,12 @@ export interface ISyncAction {
   note?: string;
   apply: () => void;
 }
+
+export type TBaseRuleChange = TConstValue<typeof BaseRuleChanges>;
+
+/** One base rule that moved since the last sync; `text` is its new text, or `(retired)` when the base retired it. */
+export interface IBaseRuleChange {
+  id: string;
+  change: TBaseRuleChange;
+  text: string;
+}

package/src/sync/index.ts

@@ -1,3 +1,5 @@
 export * from './common/index.ts';
+export * from './base-rules.ts';
 export * from './planner.ts';
+export * from './prune.ts';
 export * from './settings.ts';

package/src/sync/planner.ts

@@ -9,10 +9,11 @@ import {
   symlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
-import { BASE_DIRECTORY } from '../common/index.ts';
+import { basename, dirname, join, resolve } from 'node:path';
+import { BASE_DIRECTORY, stableBaseDirectoryOf } from '../common/index.ts';
 import { CodingAgents } from '../config/index.ts';
 import type { TResolvedConfig } from '../config/index.ts';
+import { ManifestConstants, renderManifest } from '../manifest/index.ts';
 import { readSlots } from '../rules/index.ts';
 import { SyncConstants, SyncStatuses } from './common/index.ts';
 import type { ISyncAction, TSettings } from './common/index.ts';
@@ -161,9 +162,23 @@ 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),
-  });
+  }).map(source => join(stableSkills, basename(source)));
   const shippedNames = new Set(shipped.map(source => basename(source)));
   const project = findSkillDirectories({
     directory: join(opts.root, '.agents', SyncConstants.SKILLS_DIRECTORY),
@@ -213,12 +228,32 @@ const planSkillLinks = (opts: { root: string }): ISyncAction[] => {
   return [...links, ...shadowing];
 };
 
-/** Every adapter the project's agents need, planned, not written. */
-export const planSync = (opts: { root: string; config: TResolvedConfig }): ISyncAction[] =>
-  opts.config.agents.includes(CodingAgents.CLAUDE)
+/** The committed project manifest (Project Contract v1, C1), rendered from the config. */
+export const planManifest = (opts: { root: string; config: TResolvedConfig }): ISyncAction => {
+  const path = join(opts.root, ManifestConstants.FILE);
+  const text = renderManifest(opts);
+  const write = (): void => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+  };
+
+  if (!existsSync(path)) {
+    return { path, status: SyncStatuses.CREATED, apply: write };
+  }
+
+  return readFileSync(path, 'utf8') === text
+    ? { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }
+    : { path, status: SyncStatuses.REPLACED, apply: write };
+};
+
+/** Every adapter the project's agents need, and the manifest every project carries - planned, not written. */
+export const planSync = (opts: { root: string; config: TResolvedConfig }): ISyncAction[] => [
+  ...(opts.config.agents.includes(CodingAgents.CLAUDE)
     ? [
         planClaudeImport({ root: opts.root }),
         planSettings(opts),
         ...planSkillLinks({ root: opts.root }),
       ]
-    : [];
+    : []),
+  planManifest(opts),
+];

package/src/sync/prune.ts

@@ -0,0 +1,138 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+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 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
+ * command is `bun` or `node` on that file, from the project root. Any other shape - another
+ * directory's `.agents/`, `$HOME`, a `cd` first - is a developer's own and never pruned.
+ */
+const AGENTS_HOOK =
+  /^(?:bun|node)\s+(?:"?\$\{?CLAUDE_PROJECT_DIR\}?"?\/)?(\.agents\/[\w./-]+\.ts)\s*$/;
+
+const readJson = (opts: { path: string }): TSettings | undefined => {
+  if (!existsSync(opts.path)) {
+    return undefined;
+  }
+
+  try {
+    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)}`,
+    );
+
+    return undefined;
+  }
+};
+
+/**
+ * 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 (RETIRED_SHIPPED_COMMANDS.has(opts.command)) {
+    return !opts.shipped.has(opts.command);
+  }
+
+  const agentsHook = AGENTS_HOOK.exec(opts.command)?.[1];
+
+  return agentsHook !== undefined && !existsSync(join(opts.root, agentsHook));
+};
+
+/** 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 = { value: settings?.[SyncConstants.HOOKS_KEY] };
+
+  if (settings === undefined || !isSettingsObject(hooks)) {
+    return;
+  }
+
+  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.value[event] = kept;
+    } else {
+      delete hooks.value[event];
+    }
+  }
+
+  writeFileSync(opts.path, `${JSON.stringify(settings, null, 2)}\n`);
+};
+
+const isDeadLink = (opts: { path: string }): boolean => {
+  try {
+    return lstatSync(opts.path).isSymbolicLink() && !existsSync(opts.path);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * `sync --prune`: what sync can prove is stale and did not write itself - old VULCAN and plugin-era
+ * hook commands, and skill links whose target is gone. What sync wrote last time it takes back on
+ * every run; a developer's own hooks and any real directory are never touched.
+ */
+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(
+    extractHookCommands({
+      settings: readJson({ path: join(directory, SyncConstants.MANAGED_FILE) }),
+    }),
+  );
+  const shipped = new Set(
+    extractHookCommands({
+      settings: readJson({ path: join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE) }),
+    }),
+  );
+  const staleCommands = [
+    ...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);
+  // 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 }))
+    : [];
+
+  return [
+    ...staleCommands.map((command): ISyncAction => ({
+      path: settingsPath,
+      status: SyncStatuses.REMOVED,
+      note: `stale hook: ${command}`,
+      apply: () => removeHookCommand({ path: settingsPath, command }),
+    })),
+    ...deadLinks.map((path): ISyncAction => ({
+      path,
+      status: SyncStatuses.REMOVED,
+      note: 'dead link',
+      apply: () => rmSync(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;