monkeyshape 0.1.0 → 0.2.0

package/src/adapters/workspace.ts

@@ -6,21 +6,8 @@ import { parseJsonc } from "../core/coverage.ts";
 import { type Integration, isTsSource, type Snapshot } from "../core/model.ts";
 import type { ResolvedConfig } from "../schemas/config.ts";
 import { WorkspaceError } from "../schemas/errors.ts";
-
-const run = (root: string, command: ReadonlyArray<string>) =>
-  Effect.tryPromise({
-    try: async () => {
-      const child = Bun.spawn([...command], { cwd: root, stdout: "pipe", stderr: "ignore" });
-      const stdout = await new Response(child.stdout).text();
-      return { stdout, code: await child.exited };
-    },
-    catch: (cause) =>
-      new WorkspaceError({ operation: "run", path: command.join(" "), reason: String(cause) }),
-  });
-
-/** For optional tools: a spawn failure is an exit code to report, not a reason to abort. */
-const runTool = (root: string, command: ReadonlyArray<string>) =>
-  run(root, command).pipe(Effect.orElseSucceed(() => ({ stdout: "", code: -1 })));
+import { run, runTool } from "./process.ts";
+import { loadSkills } from "./skills.ts";
 
 export const readText = (root: string, path: string) =>
   Effect.tryPromise({
@@ -70,34 +57,57 @@ const jsonRows = (stdout: string): ReadonlyArray<unknown> | undefined => {
   return Array.isArray(rows) ? rows : undefined;
 };
 
+/** Whether bd can be asked: absent without `.beads/config.yaml`, unavailable without bd. */
+const beadsUnreachable = (root: string) =>
+  Effect.gen(function* () {
+    if (!(yield* exists(root, ".beads/config.yaml")))
+      return { state: "absent" } satisfies Integration;
+    if (Bun.which("bd") === null)
+      return { state: "unavailable", reason: "bd is not on PATH" } satisfies Integration;
+    return undefined;
+  });
+
+/**
+ * Every bead `bd list --all <filters> --json` prints, with the integration state `check` and
+ * `track` both read: absent, unavailable, failed (bd ran and failed, its stderr kept) or ok.
+ */
+export const beadRows = (root: string, filters: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const unreachable = yield* beadsUnreachable(root);
+    if (unreachable !== undefined)
+      return { integration: unreachable, value: undefined } satisfies Loaded<
+        ReadonlyArray<unknown>
+      >;
+    const command = ["bd", "list", "--all", ...filters, "--limit", "0", "--json"];
+    // A spawn that throws is bd failing to run: reported as failed, never an abort.
+    const result = yield* Effect.try(() =>
+      Bun.spawnSync(command, { cwd: root, stdout: "pipe", stderr: "pipe" }),
+    ).pipe(Effect.orElseSucceed(() => undefined));
+    const rows = result?.exitCode === 0 ? jsonRows(result.stdout.toString()) : undefined;
+    if (rows === undefined) {
+      const stderr = result?.stderr.toString().trim() ?? "";
+      return failed<ReadonlyArray<unknown>>(
+        `\`${command.join(" ")}\` exited ${result?.exitCode ?? "without running"} or printed no rows${stderr === "" ? "" : `: ${stderr}`}`,
+      );
+    }
+    return { integration: { state: "ok" }, value: rows } satisfies Loaded<ReadonlyArray<unknown>>;
+  });
+
 /** bd memories and every bead id. A repo without `.beads` is absent; bd missing is unavailable. */
 const beads = (root: string) =>
   Effect.gen(function* () {
     type Value = { memories: ReadonlyMap<string, string>; ids: ReadonlySet<string> };
-    if (!(yield* exists(root, ".beads/config.yaml")))
-      return { integration: { state: "absent" }, value: undefined } satisfies Loaded<Value>;
-    if (Bun.which("bd") === null)
-      return {
-        integration: { state: "unavailable", reason: "bd is not on PATH" },
-        value: undefined,
-      } satisfies Loaded<Value>;
+    const unreachable = yield* beadsUnreachable(root);
+    if (unreachable !== undefined)
+      return { integration: unreachable, value: undefined } satisfies Loaded<Value>;
     const memories = yield* runTool(root, ["bd", "memories", "--json"]);
     const parsedMemories = memories.code === 0 ? parseJsonc(memories.stdout) : undefined;
     if (typeof parsedMemories !== "object" || parsedMemories === null)
       return failed<Value>(`\`bd memories --json\` exited ${memories.code} or printed no object`);
-    const list = yield* runTool(root, [
-      "bd",
-      "list",
-      "--all",
-      "--brief",
-      "--skip-labels",
-      "--limit",
-      "0",
-      "--json",
-    ]);
-    const rows = list.code === 0 ? jsonRows(list.stdout) : undefined;
+    const list = yield* beadRows(root, ["--brief", "--skip-labels"]);
+    const rows = list.value;
     if (rows === undefined)
-      return failed<Value>(`\`bd list --json\` exited ${list.code} or printed no rows`);
+      return { integration: list.integration, value: undefined } satisfies Loaded<Value>;
     const value: Value = {
       memories: new Map(
         Object.entries(parsedMemories).filter(
@@ -219,7 +229,8 @@ const linted = (root: string) =>
     return { integration: { state: "ok" }, value: files } satisfies Loaded<ReadonlySet<string>>;
   });
 
-export const loadSnapshot = (root: string, config: ResolvedConfig) =>
+/** `shippedSkills` is the running monkeyshape's `skills/`, to tell whether a sync is due. */
+export const loadSnapshot = (root: string, config: ResolvedConfig, shippedSkills: string) =>
   Effect.gen(function* () {
     const listed = yield* listFiles(root);
     // A file deleted but not yet staged is still listed; it isn't part of the repo now.
@@ -250,6 +261,7 @@ export const loadSnapshot = (root: string, config: ResolvedConfig) =>
     const loadedBeads = yield* beads(root);
     const loadedTsc = yield* typechecked(root, realRoot, config.coverage.tsconfigs);
     const loadedBiome = yield* linted(root);
+    const skills = yield* loadSkills(shippedSkills, root);
     const snapshot: Snapshot = {
       files: present,
       texts,
@@ -263,6 +275,7 @@ export const loadSnapshot = (root: string, config: ResolvedConfig) =>
         tsc: loadedTsc.integration,
         biome: loadedBiome.integration,
       },
+      skills,
     };
     return snapshot;
   });

package/src/cli/main.ts

@@ -1,31 +1,55 @@
 #!/usr/bin/env bun
 /** The `mshape` executable: the composition root, and the only place effects are run. */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Effect } from "effect";
 import pkg from "../../package.json" with { type: "json" };
 import { BASELINE_FILE, readBaseline, writeBaseline } from "../adapters/baseline.ts";
 import { loadConfig } from "../adapters/config.ts";
+import { initRepo } from "../adapters/init.ts";
+import { reviewNew, reviewRm } from "../adapters/reviews.ts";
+import { installSkills } from "../adapters/skills.ts";
+import { trackCurrent, trackList, trackNew, trackRm } from "../adapters/tracks.ts";
 import { loadSnapshot } from "../adapters/workspace.ts";
 import { CHECKS, notices, prerequisites, runChecks, unevaluated } from "../core/check.ts";
 import { garden } from "../core/garden.ts";
+import { CLAUDE_SKILLS_LINK } from "../core/layout.ts";
 import type { CheckName } from "../core/model.ts";
 import { applyBaseline, count, tighten } from "../core/ratchet.ts";
 import { formatCheck, formatGarden, formatViolation } from "../core/report.ts";
 import { RULES } from "../core/rules/registry.ts";
+import { nextStep, REPO_NAME } from "../core/scaffold.ts";
+import { formatCollisions, formatSync } from "../core/skills.ts";
+import type { ConfigError, TrackError, WorkspaceError } from "../schemas/errors.ts";
 
-const USAGE = `mshape ${pkg.version}
+/** What a command returns: the text to print, and the exit code (0 prints to stdout). */
+interface Outcome {
+  readonly output: string;
+  readonly code: number;
+}
 
-  mshape check [--only arch,refs,budgets,coverage,rules]
-      Run the checks; violations above .shape/baseline.json fail.
-  mshape baseline --tighten
-      Lower baseline counts to what is found now. Never raises one.
-  mshape baseline --init
-      Grandfather every current violation. For adopting a repo; review the diff.
-  mshape garden
-      Print budgets and escape hatches for the milestone-boundary sweep.
-  mshape rules
-      List the custom rules and the bug class each one removes.
+/**
+ * One `mshape` command. A new command is one entry in `COMMANDS`, and the help is generated
+ * from the table, so a command can't ship without its usage and no two tracks edit one switch.
+ */
+interface Command {
+  readonly name: string;
+  /** Its lines in the help: each form indented two spaces, what it does six. */
+  readonly usage: string;
+  readonly run: (
+    root: string,
+    args: ReadonlyArray<string>,
+  ) => Effect.Effect<Outcome, ConfigError | WorkspaceError | TrackError>;
+}
+
+const FLAGS = `  --config <path>   For check, baseline and garden: use this config instead of ./shape.config.ts
+                    (trying a repo before adopting).`;
+
+/** Every command's usage, in table order. A function, since the table is declared below. */
+export const help = (): string =>
+  [`mshape ${pkg.version}`, "", ...COMMANDS.map((command) => command.usage), "", FLAGS].join("\n");
 
-  --config <path>   Use this config instead of ./shape.config.ts (trying a repo before adopting).`;
+const usage = (): Outcome => ({ output: help(), code: 2 });
 
 const parseOnly = (args: ReadonlyArray<string>): ReadonlyArray<CheckName> | string => {
   const index = args.indexOf("--only");
@@ -37,23 +61,128 @@ const parseOnly = (args: ReadonlyArray<string>): ReadonlyArray<CheckName> | stri
     : (names as ReadonlyArray<CheckName>);
 };
 
-const program = (root: string, args: ReadonlyArray<string>) =>
+/** The package's own directory: `template/` and `skills/` ship beside `src/`. */
+const PACKAGE_ROOT = fileURLToPath(new URL("../..", import.meta.url)).replace(/\/$/, "");
+
+const WORKFLOW_URL = `${pkg.homepage.replace(/#.*$/, "")}/blob/main/docs/workflow.md`;
+
+const init = (root: string, args: ReadonlyArray<string>) =>
   Effect.gen(function* () {
-    const [command, ...rest] = args;
-    if (command === "--version") return { output: pkg.version, code: 0 };
-    if (command === "rules")
+    const fromFlag = args.indexOf("--from");
+    const from = fromFlag === -1 ? undefined : args[fromFlag + 1];
+    // A forgotten value would silently install from the registry, which --from exists to avoid.
+    if (fromFlag !== -1 && (from === undefined || from.startsWith("--")))
       return {
-        output: RULES.map((r) => `${r.id.padEnd(22)}${r.layer.padEnd(9)}${r.bugClass}`).join("\n"),
+        output: "mshape init: --from needs a value: a tarball path or a spec bun install accepts",
+        code: 2,
+      };
+    const positional = args.filter(
+      (_, i) => fromFlag === -1 || (i !== fromFlag && i !== fromFlag + 1),
+    );
+    const [name, ...extra] = positional;
+    if (name === undefined || !REPO_NAME.test(name) || extra.length > 0)
+      return {
+        output: `mshape init: give the new repo's name in lowercase words joined by hyphens, e.g. \`mshape init my-app\` (got ${positional.length === 0 ? "nothing" : positional.map((arg) => `'${arg}'`).join(" ")})`,
+        code: 2,
+      };
+    // A bare path is a tarball; bun would resolve it from the new repo, not from here.
+    const spec = from === undefined || from.includes(":") ? from : `file:${resolve(root, from)}`;
+    const dev = pkg.devDependencies;
+    const result = yield* initRepo(`${root}/${name}`, name, PACKAGE_ROOT, {
+      bun: Bun.version,
+      monkeyshape: spec ?? pkg.version,
+      effect: dev.effect,
+      biome: dev["@biomejs/biome"],
+      typescript: dev.typescript,
+      typesBun: dev["@types/bun"],
+    });
+    return {
+      output: [
+        `Created ${name}/: ${result.done.join(", ")}.`,
+        ...result.notes.map((note) => `note: ${note}`),
+        "",
+        nextStep(name, WORKFLOW_URL),
+      ].join("\n"),
+      code: 0,
+    };
+  });
+
+/** Today in local time, `YYYY-MM-DD`: the date a new handoff's State carries. */
+const today = (): string => {
+  const now = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+};
+
+const track = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const [sub, ...rest] = args;
+    const flags = rest.filter((arg) => arg.startsWith("--"));
+    const names = rest.filter((arg) => !arg.startsWith("--"));
+    const allowed = sub === "rm" ? ["--force", "--keep-handoff"] : [];
+    const takesName = sub === "new" || sub === "rm";
+    if (flags.some((flag) => !allowed.includes(flag))) return usage();
+    if (names.length !== (takesName ? 1 : 0)) return usage();
+    const name = names[0] ?? "";
+    if (sub === "new") return { output: yield* trackNew(root, name, today()), code: 0 };
+    if (sub === "list") return { output: yield* trackList(root), code: 0 };
+    if (sub === "current") return { output: yield* trackCurrent(root), code: 0 };
+    if (sub === "rm")
+      return {
+        output: yield* trackRm(
+          root,
+          name,
+          {
+            force: flags.includes("--force"),
+            keepHandoff: flags.includes("--keep-handoff"),
+            // rm fetches main's upstream; with no terminal to answer, a prompt would hang it.
+            fetchEnv: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+          },
+          (line) => Effect.sync(() => console.error(line)),
+        ),
+        code: 0,
+      };
+    return usage();
+  });
+
+const review = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    if (args.length === 1 && args[0] !== "rm")
+      return {
+        output: yield* reviewNew(root, args[0] ?? "", (line) =>
+          Effect.sync(() => console.error(line)),
+        ),
         code: 0,
       };
-    if (command !== "check" && command !== "baseline" && command !== "garden")
+    if (args.length === 2 && args[0] === "rm")
       return {
-        output: USAGE,
-        code: command === undefined || command === "help" || command === "--help" ? 0 : 2,
+        output: yield* reviewRm(root, args[1] ?? "", (line) =>
+          Effect.sync(() => console.error(line)),
+        ),
+        code: 0,
       };
+    return usage();
+  });
+
+const skills = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    if (args[0] !== "sync") return usage();
+    const { sync, linked } = yield* installSkills(`${PACKAGE_ROOT}/skills`, root);
+    return {
+      output: [
+        formatSync(sync),
+        ...(linked ? [`${CLAUDE_SKILLS_LINK}: linked`] : []),
+        ...formatCollisions(sync),
+      ].join("\n"),
+      code: sync.collisions.length > 0 ? 1 : 0,
+    };
+  });
 
-    const configFlag = rest.indexOf("--config");
-    const configPath = configFlag === -1 ? undefined : rest[configFlag + 1];
+/** What `check`, `baseline` and `garden` all read: the config, the snapshot, the baseline. */
+const load = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const configFlag = args.indexOf("--config");
+    const configPath = configFlag === -1 ? undefined : args[configFlag + 1];
     const config = yield* loadConfig(
       root,
       configPath === undefined
@@ -62,39 +191,16 @@ const program = (root: string, args: ReadonlyArray<string>) =>
           ? configPath
           : `${root}/${configPath}`,
     );
-    const snapshot = yield* loadSnapshot(root, config);
+    const snapshot = yield* loadSnapshot(root, config, `${PACKAGE_ROOT}/skills`);
     const baseline = yield* readBaseline(root);
+    return { config, snapshot, baseline };
+  });
 
-    if (command === "garden")
-      return { output: formatGarden(garden(config, snapshot, baseline)), code: 0 };
-
+const check = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const { config, snapshot, baseline } = yield* load(root, args);
     const blocked = prerequisites(config, snapshot);
-    if (command === "baseline") {
-      // A baseline written without a required integration would grandfather an incomplete count.
-      if (blocked.length > 0)
-        return {
-          output: [
-            ...blocked.map(formatViolation),
-            "mshape baseline: not written, because a prerequisite fails",
-          ].join("\n\n"),
-          code: 1,
-        };
-      const violations = runChecks(config, snapshot);
-      if (rest.includes("--init")) {
-        yield* writeBaseline(root, count(violations));
-        return {
-          output: `${BASELINE_FILE}: grandfathered ${violations.length} violation(s)`,
-          code: 0,
-        };
-      }
-      if (rest.includes("--tighten")) {
-        yield* writeBaseline(root, tighten(baseline, violations, unevaluated(snapshot)));
-        return { output: `${BASELINE_FILE}: tightened`, code: 0 };
-      }
-      return { output: USAGE, code: 2 };
-    }
-
-    const only = parseOnly(rest);
+    const only = parseOnly(args);
     if (typeof only === "string") return { output: only, code: 2 };
     const ratcheted = applyBaseline(
       runChecks(config, snapshot, only),
@@ -109,14 +215,145 @@ const program = (root: string, args: ReadonlyArray<string>) =>
     };
   });
 
-const outcome = await Effect.runPromise(
-  program(process.cwd(), process.argv.slice(2)).pipe(
-    Effect.catchTags({
-      ConfigError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 2 }),
-      WorkspaceError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 2 }),
-    }),
-  ),
-);
-if (outcome.code === 0) console.log(outcome.output);
-else console.error(outcome.output);
-process.exitCode = outcome.code;
+const baseline = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const loaded = yield* load(root, args);
+    const { config, snapshot } = loaded;
+    const blocked = prerequisites(config, snapshot);
+    // A baseline written without a required integration would grandfather an incomplete count.
+    if (blocked.length > 0)
+      return {
+        output: [
+          ...blocked.map(formatViolation),
+          "mshape baseline: not written, because a prerequisite fails",
+        ].join("\n\n"),
+        code: 1,
+      };
+    const violations = runChecks(config, snapshot);
+    if (args.includes("--init")) {
+      yield* writeBaseline(root, count(violations));
+      return {
+        output: `${BASELINE_FILE}: grandfathered ${violations.length} violation(s)`,
+        code: 0,
+      };
+    }
+    if (args.includes("--tighten")) {
+      yield* writeBaseline(root, tighten(loaded.baseline, violations, unevaluated(snapshot)));
+      return { output: `${BASELINE_FILE}: tightened`, code: 0 };
+    }
+    return usage();
+  });
+
+const gardenCommand = (root: string, args: ReadonlyArray<string>) =>
+  Effect.map(load(root, args), ({ config, snapshot, baseline }) => ({
+    output: formatGarden(garden(config, snapshot, baseline)),
+    code: 0,
+  }));
+
+const rules = () =>
+  Effect.succeed({
+    output: RULES.map((r) => `${r.id.padEnd(22)}${r.layer.padEnd(9)}${r.bugClass}`).join("\n"),
+    code: 0,
+  });
+
+/** Every command, in the order the help lists them. */
+export const COMMANDS: ReadonlyArray<Command> = [
+  {
+    name: "init",
+    usage: `  mshape init <name> [--from <spec>]
+      Create ./<name>: a new repo whose gate passes, with one starter test. --from installs
+      monkeyshape from <spec> (a tarball path) instead of the registry, to try a release first.`,
+    run: init,
+  },
+  {
+    name: "skills",
+    usage: `  mshape skills sync
+      Refresh the shared skills in .agents/skills from the installed package, after a bump.
+      Skills the package doesn't ship are the repo's own and are left alone.`,
+    run: skills,
+  },
+  {
+    name: "check",
+    usage: `  mshape check [--only arch,refs,budgets,coverage,rules,skills]
+      Run the checks; violations above .shape/baseline.json fail.`,
+    run: check,
+  },
+  {
+    name: "baseline",
+    usage: `  mshape baseline --tighten
+      Lower baseline counts to what is found now. Never raises one.
+  mshape baseline --init
+      Grandfather every current violation. For adopting a repo; review the diff.`,
+    run: baseline,
+  },
+  {
+    name: "garden",
+    usage: `  mshape garden
+      Print budgets and escape hatches for the milestone-boundary sweep.`,
+    run: gardenCommand,
+  },
+  {
+    name: "rules",
+    usage: `  mshape rules
+      List the custom rules and the bug class each one removes.`,
+    run: rules,
+  },
+  {
+    name: "track",
+    usage: `  mshape track new <name>
+      Start a track: worktree .agents/worktrees/<repo>@<name> on track/<name> from main,
+      the shared handoffs and tracks.sharedPaths linked in, and a stub handoff. Shared paths
+      come from the main checkout's shape.config.ts, from whichever checkout this runs.
+  mshape track list
+      Every track: handoff status, open beads, commits in neither main nor origin/main,
+      worktree. Restores missing handoff links; a track label with open beads and no track
+      left is listed too. Offline: run git fetch to see merges done on the remote.
+  mshape track current
+      The track of this directory, name only; exit 1, saying why, outside a track.
+  mshape track rm <name> [--force] [--keep-handoff]
+      Remove a finished track: worktree, branch, handoff. Fetches main's upstream first, then
+      refuses on uncommitted changes or work in neither main nor origin/main (by merge,
+      rebase or squash); --force discards them. Also refuses while beads labelled
+      track:<name> aren't closed, which --force doesn't override. Never touches main or other tracks.`,
+    run: track,
+  },
+  {
+    name: "review",
+    usage: `  mshape review <n>
+      Pull request <n>'s head from origin in a detached worktree .agents/worktrees/<repo>.pr-<n>,
+      tracks.sharedPaths linked in. Again later: put it exactly at the new head, printing the
+      old one; edits to tracked files there are listed, then discarded.
+  mshape review rm <n>
+      Remove that worktree, listing what it discards, and its fetched ref. Never the shared data.`,
+    run: review,
+  },
+];
+
+const HELP: ReadonlyArray<string | undefined> = [undefined, "help", "--help"];
+
+export const program = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const [name, ...rest] = args;
+    if (name === "--version") return { output: pkg.version, code: 0 };
+    if (HELP.includes(name)) return { output: help(), code: 0 };
+    const command = COMMANDS.find((entry) => entry.name === name);
+    if (command === undefined)
+      return { output: `mshape: unknown command '${name}'\n\n${help()}`, code: 2 };
+    return yield* command.run(root, rest);
+  });
+
+// Only as the executable: tests import the table and the help without running a command.
+if (import.meta.main) {
+  const outcome = await Effect.runPromise(
+    program(process.cwd(), process.argv.slice(2)).pipe(
+      Effect.catchTags({
+        ConfigError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 2 }),
+        WorkspaceError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 2 }),
+        TrackError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 1 }),
+      }),
+    ),
+  );
+  if (outcome.code === 0) console.log(outcome.output);
+  else console.error(outcome.output);
+  process.exitCode = outcome.code;
+}

package/src/core/check.ts

@@ -3,12 +3,20 @@ import type { ResolvedConfig } from "../schemas/config.ts";
 import { checkArch } from "./arch.ts";
 import { checkBudgets } from "./budgets.ts";
 import { checkCoverage } from "./coverage.ts";
-import type { CheckName, Snapshot, Violation } from "./model.ts";
+import type { CheckName, Integration, Snapshot, Violation } from "./model.ts";
 import { checkRefs } from "./refs.ts";
 import { checkRules } from "./rules/engine.ts";
 import { RULES } from "./rules/registry.ts";
+import { checkSkills } from "./skills.ts";
 
-export const CHECKS: ReadonlyArray<CheckName> = ["arch", "refs", "budgets", "coverage", "rules"];
+export const CHECKS: ReadonlyArray<CheckName> = [
+  "arch",
+  "refs",
+  "budgets",
+  "coverage",
+  "rules",
+  "skills",
+];
 
 const run: Record<
   CheckName,
@@ -19,6 +27,7 @@ const run: Record<
   budgets: checkBudgets,
   coverage: checkCoverage,
   rules: (config, snapshot) => checkRules(config, snapshot, RULES),
+  skills: checkSkills,
 };
 
 const BEADS_RULES = ["refs/bead-in-code", "budgets/memories-count", "budgets/memories-bytes"];
@@ -64,6 +73,21 @@ const prerequisite = (rule: string, message: string): Violation => ({
   message,
 });
 
+/**
+ * When beads can't be trusted, whatever asks it: `failed` when bd ran and failed, whatever the
+ * config says; `required` when `beads: "required"` and beads isn't ok. `check` and
+ * `track rm` both decide with this, so a beads failure means one thing everywhere.
+ */
+export const beadsBlocker = (
+  setting: ResolvedConfig["beads"],
+  beads: Integration,
+): "failed" | "required" | undefined =>
+  beads.state === "failed"
+    ? "failed"
+    : setting === "required" && beads.state !== "ok"
+      ? "required"
+      : undefined;
+
 /**
  * Integrations that must work for a result to mean anything: bd failing outright, or bd
  * unavailable when `beads: "required"`. These are facts about the environment, not the code,
@@ -74,11 +98,12 @@ export const prerequisites = (
   snapshot: Snapshot,
 ): ReadonlyArray<Violation> => {
   const beads = snapshot.integrations.beads;
-  if (beads.state === "failed")
+  const blocker = beadsBlocker(config.beads, beads);
+  if (blocker === "failed" && beads.state === "failed")
     return [
       prerequisite("beads-failed", `bd failed, so beads checks did not run: ${beads.reason}`),
     ];
-  if (config.beads === "required" && beads.state !== "ok")
+  if (blocker === "required" && beads.state !== "ok")
     return [
       prerequisite(
         "beads-required",