@monte3l/groundwork 0.1.0-next.1 → 1.0.0-rc.3

package/dist/fs-guard.js

@@ -0,0 +1,222 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * The one symlink refusal adopt mode's staging writers share
+ * (`staging.ts`, used by `baseline-stage.ts` and `pack-stage.ts`; `main.ts`'s
+ * `.groundwork/` cleanup): a staging directory that is a symlink would
+ * redirect a recursive delete or a write outside the adopted project. Also
+ * the one recogniser for the "re-run the CLI" advice that refusal (and every
+ * other adopt-mode failure) ends with, so a wrapper never states it twice.
+ * Fresh mode's writers (`emit.ts`, `plugin.ts`) share the same refusals with
+ * fresh mode's own single retry instruction ({@link FRESH_RETRY}) instead.
+ */
+import { lstatSync } from "node:fs";
+import { isAbsentError, permissionCode } from "./survey/internal/read-guard.js";
+/** The tail every adopt-mode re-run instruction ends with, {@link assertNotSymlink}'s default advice included. */
+const RERUN_TAIL = "re-run the CLI";
+/**
+ * Adopt mode's generic re-run instruction, stated once so every adopt-mode
+ * failure that appends it (`main.ts`'s post-point-of-no-return error, the
+ * guarded `/customize` install) words it identically. Ends with the tail
+ * {@link endsWithRerunAdvice} recognises.
+ *
+ * @example
+ * ```ts
+ * import { FIX_AND_RERUN_ADVICE, endsWithRerunAdvice } from "./fs-guard.js";
+ *
+ * const message = `could not write x: EACCES; ${FIX_AND_RERUN_ADVICE}`;
+ * endsWithRerunAdvice(message); // true
+ * ```
+ */
+export const FIX_AND_RERUN_ADVICE = `fix the cause and ${RERUN_TAIL}`;
+/**
+ * Whether `message` already ENDS with "re-run the CLI" advice, in any
+ * wording that ends that way (e.g. {@link assertNotSymlink}'s "remove it and
+ * re-run the CLI", or "fix the cause and re-run the CLI"), so a caller about
+ * to append its own re-run advice can skip it rather than state it twice.
+ * End-anchored: the phrase appearing earlier in the message -- e.g. inside
+ * an embedded path -- does not count.
+ *
+ * @example
+ * ```ts
+ * import { endsWithRerunAdvice } from "./fs-guard.js";
+ *
+ * endsWithRerunAdvice("x is a symlink -- remove it and re-run the CLI"); // true
+ * endsWithRerunAdvice("could not write /tmp/re-run the CLI/a: EACCES"); // false
+ * ```
+ */
+export function endsWithRerunAdvice(message) {
+    return message.endsWith(RERUN_TAIL);
+}
+/**
+ * Fresh mode's retry instruction. Its target is no longer empty after a
+ * failed write, so a plain re-run would adopt it; only `--fresh --force`
+ * repeats that run. Never contains adopt mode's bare "re-run the CLI".
+ *
+ * @example
+ * ```ts
+ * import { FRESH_RETRY } from "./fs-guard.js";
+ *
+ * const advice = `fix the cause, then ${FRESH_RETRY}`;
+ * ```
+ */
+export const FRESH_RETRY = "retry the same command with --fresh --force added";
+/**
+ * The advice for a permission failure (`EACCES`/`EPERM`) inspecting a path:
+ * "remove it" (the symlink refusal's remedy) would be wrong there, so the
+ * caller's `advice` is replaced by a permissions fix that keeps the same
+ * mode-specific retry -- fresh mode's {@link FRESH_RETRY}, or adopt mode's
+ * "re-run the CLI" (so {@link endsWithRerunAdvice} still recognises it). A
+ * caller advice ending with neither is kept whole after the permissions fix,
+ * so its own retry is never dropped.
+ */
+function permissionAdvice(advice) {
+    if (advice.endsWith(FRESH_RETRY)) {
+        return `fix its permissions, then ${FRESH_RETRY}`;
+    }
+    if (endsWithRerunAdvice(advice)) {
+        return `fix its permissions and ${RERUN_TAIL}`;
+    }
+    return `fix its permissions; ${advice}`;
+}
+/**
+ * `lstat` without its one blind spot: `throwIfNoEntry: false` only answers a
+ * missing path with `undefined`, so any other failure (most realistically
+ * `EACCES` on a search-permission-denied ancestor) would escape raw -- no
+ * path in a readable message, no retry advice. An absent path (`ENOENT`, or
+ * `ENOTDIR` below a regular file) answers `undefined`, leaving the write
+ * that follows to raise its own error; anything else is wrapped here once,
+ * naming `path`, with the original as `cause`. A permission failure ends
+ * with {@link permissionAdvice}'s permissions fix; any other ends with
+ * `advice` unchanged.
+ */
+function inspect(path, advice) {
+    try {
+        return lstatSync(path, { throwIfNoEntry: false });
+    }
+    catch (cause) {
+        if (isAbsentError(cause))
+            return undefined;
+        const code = permissionCode(cause);
+        if (code !== undefined) {
+            throw new Error(`could not inspect ${path}: permission denied (${code}) -- ${permissionAdvice(advice)}`, { cause });
+        }
+        throw new Error(`could not inspect ${path} -- ${advice}`, { cause });
+    }
+}
+/**
+ * Throws when `path` exists and is a symbolic link; a missing path passes.
+ * Uses `lstat`, so the link itself is inspected, never its target. Call it
+ * on every staging directory before the first `rm` or write under it.
+ *
+ * @param advice - What the message ends with after `--`; defaults to
+ *   "remove it and re-run the CLI". A caller whose run needs a different
+ *   retry (fresh mode's `--fresh --force`) passes its own, so the error
+ *   never carries a second, contradicting instruction.
+ * @throws `Error` naming `path` when it is a symlink, or when it cannot be
+ *   inspected at all (any `lstat` failure but `ENOENT`/`ENOTDIR`, chained
+ *   as `cause`).
+ *
+ * @example
+ * ```ts
+ * import { rmSync } from "node:fs";
+ * import { assertNotSymlink } from "./fs-guard.js";
+ *
+ * assertNotSymlink("/work/app/.groundwork"); // throws if it's a symlink
+ * rmSync("/work/app/.groundwork/inventory.json", { force: true });
+ * ```
+ */
+export function assertNotSymlink(path, advice = `remove it and ${RERUN_TAIL}`) {
+    const stat = inspect(path, advice);
+    if (stat?.isSymbolicLink() === true) {
+        throw new Error(`refusing to write through a symlink: ${path} -- ${advice}`);
+    }
+}
+/**
+ * Throws when `path` exists and is not a real directory -- a symlink
+ * (dangling or not) or a file where a writer needs a directory. A missing
+ * path passes. Uses `lstat`, so a symlinked directory is refused rather
+ * than followed out of the tree being written.
+ *
+ * @param advice - What the message ends with after `--`, same convention as
+ *   {@link assertNotSymlink}'s.
+ * @throws `Error` naming `path` when it is a symlink or a non-directory, or
+ *   when it cannot be inspected (the original chained as `cause`).
+ *
+ * @example
+ * ```ts
+ * import { assertDirectoryComponent, FRESH_SYMLINK_ADVICE } from "./fs-guard.js";
+ *
+ * assertDirectoryComponent("/work/app/.claude", FRESH_SYMLINK_ADVICE);
+ * ```
+ */
+export function assertDirectoryComponent(path, advice) {
+    assertNotSymlink(path, advice);
+    const stat = inspect(path, advice);
+    if (stat !== undefined && !stat.isDirectory()) {
+        throw new Error(`refusing to write under a non-directory: ${path} -- ${advice}`);
+    }
+}
+/**
+ * Throws when `path` exists and cannot be written as a plain file -- a
+ * symlink (dangling or not), which a write would follow, or a directory,
+ * which a write would fail on only after earlier writes had landed. A
+ * missing path or an existing regular file passes. Uses `lstat`, so the
+ * entry itself is inspected, never a link's target.
+ *
+ * @param advice - What the message ends with after `--`, same convention as
+ *   {@link assertNotSymlink}'s.
+ * @throws `Error` naming `path` when it is a symlink or a directory, or
+ *   when it cannot be inspected (the original chained as `cause`).
+ *
+ * @example
+ * ```ts
+ * import { assertFileDestination, FRESH_SYMLINK_ADVICE } from "./fs-guard.js";
+ *
+ * assertFileDestination("/work/app/tsconfig.json", FRESH_SYMLINK_ADVICE);
+ * ```
+ */
+export function assertFileDestination(path, advice) {
+    assertNotSymlink(path, advice);
+    assertNotDirectory(path, advice);
+}
+/**
+ * Throws when `path` exists and is a real directory, which a file write
+ * would fail on only after earlier writes had landed. A missing path, a
+ * file, or a symlink passes -- for a destination whose writer replaces a
+ * symlink rather than following it (fresh mode's `/customize` install),
+ * this is the one shape left to refuse up front. Uses `lstat`.
+ *
+ * @param advice - What the message ends with after `--`, same convention as
+ *   {@link assertNotSymlink}'s.
+ * @throws `Error` naming `path` when it is a directory, or when it cannot be
+ *   inspected (the original chained as `cause`).
+ *
+ * @example
+ * ```ts
+ * import { assertNotDirectory, FRESH_SYMLINK_ADVICE } from "./fs-guard.js";
+ *
+ * assertNotDirectory("/work/app/.claude/skills/customize/SKILL.md", FRESH_SYMLINK_ADVICE);
+ * ```
+ */
+export function assertNotDirectory(path, advice) {
+    const stat = inspect(path, advice);
+    if (stat?.isDirectory() === true) {
+        throw new Error(`refusing to write a file over a directory: ${path} -- ${advice}`);
+    }
+}
+/**
+ * Fresh mode's advice for a refused destination path (a symlink, or a
+ * non-directory where a directory is needed), replacing
+ * {@link assertNotSymlink}'s adopt-mode default. Carries {@link FRESH_RETRY}
+ * exactly once.
+ *
+ * @example
+ * ```ts
+ * import { assertNotSymlink, FRESH_SYMLINK_ADVICE } from "./fs-guard.js";
+ *
+ * assertNotSymlink("/work/app/package.json", FRESH_SYMLINK_ADVICE);
+ * ```
+ */
+export const FRESH_SYMLINK_ADVICE = `remove it, then ${FRESH_RETRY}`;
+//# sourceMappingURL=fs-guard.js.map

package/dist/git.js

@@ -1,4 +1,13 @@
-/** The two mechanical steps after emission: `git init`, then the first install. */
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * The two mechanical steps fresh mode runs after emission -- writing the
+ * baseline template tree into the target directory (`emitTemplate` in
+ * `emit.ts`, called from `main.ts`'s `runFresh`). `gitInit` initializes a
+ * fresh git repository there (`git init -q`); `runInstall` then runs the
+ * first package install (`pnpm install`). Both run synchronously in the
+ * target directory with the child's output passed straight through.
+ */
 import { execFileSync } from "node:child_process";
 export function gitInit(cwd) {
     execFileSync("git", ["init", "-q"], { cwd, stdio: "inherit" });

package/dist/harness/conformance.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 function isHarnessPath(relPath) {
     return relPath.startsWith(".claude/") || relPath === "CLAUDE.md";
 }

package/dist/harness/frontmatter.js

@@ -1,16 +1,5 @@
-/**
- * A reader for the YAML subset Claude Code frontmatter actually uses --
- * `SKILL.md`, agent, and rule files. Hand-rolled because this package has no
- * runtime dependencies (see `jsonc.ts` for the same trade-off). It handles
- * the scalar forms real harness files contain: plain, single/double quoted,
- * block scalars (`>-`, `>`, `|`, `|-`), block lists, and flow lists.
- *
- * Deliberately NOT supported: nested mappings (a key whose value is an
- * indented map, e.g. `mcpServers:` with inline server definitions) -- such a
- * key is recorded with an empty string value rather than misparsed -- plus
- * anchors, tags, and multi-document streams. Every string result is
- * trimmed; a block scalar's trailing newline is not preserved.
- */
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 const KEY_LINE = /^([A-Za-z_][\w-]*):(?:[ \t]+(.*))?$/;
 const BLOCK_SCALAR = /^([>|])(?:[+-]\d?|\d[+-]?)?$/;
 /** Removes the smallest common indent from every non-blank line. */

package/dist/harness/grade.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Grades a project's Claude Code harness. `gradeHarness` reads the `.claude/`
  * tree and `CLAUDE.md` once into a `HarnessSnapshot`, then runs every rule in
@@ -6,8 +8,8 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readJsoncFile } from "../jsonc.js";
-import { walkBounded } from "../survey/fs-walk.js";
+import { parseJsonc } from "../jsonc.js";
+import { walkBoundedForGrading } from "../survey/fs-walk.js";
 import { RULES } from "./rules.js";
 import { HARNESS_CATEGORIES } from "./types.js";
 const PROJECT_WALK_DEPTH = 8;
@@ -19,17 +21,40 @@ function readText(path) {
         return undefined;
     }
 }
+/**
+ * Reads and parses a JSONC file the way the emitted twin
+ * (`templates/core/bin/lib/harness-rules.mjs`'s `readJsonc`) does, so both
+ * graders agree finding for finding: any read failure -- a directory at the
+ * path, a permission failure, even `EIO` -- becomes the failure's own
+ * message, never a throw. Not `jsonc.ts`'s `readJsoncFile`, which throws on
+ * a machine-level errno and words its errors differently: a grade reports
+ * what it could not read rather than aborting the whole report.
+ */
+function readJsoncLenient(path) {
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stage: "read",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return parseJsonc(content);
+}
 function readSettings(path) {
     if (!existsSync(path)) {
         return { present: false, error: undefined, parsed: undefined };
     }
-    const result = readJsoncFile(path);
+    const result = readJsoncLenient(path);
     return result.ok
         ? { present: true, error: undefined, parsed: result.value }
         : { present: true, error: result.error, parsed: undefined };
 }
 function loadSnapshot(root) {
-    const entries = walkBounded(root, PROJECT_WALK_DEPTH);
+    const entries = walkBoundedForGrading(root, PROJECT_WALK_DEPTH);
     const claudeEntries = entries.filter((entry) => entry.relPath.startsWith(".claude/"));
     const readEach = (pattern, strip) => new Map(claudeEntries
         .filter((entry) => !entry.isDirectory && pattern.test(entry.relPath))
@@ -52,12 +77,16 @@ function loadSnapshot(root) {
             files,
         };
     });
-    const settingsLocalResult = readJsoncFile(join(root, ".claude", "settings.local.json"));
+    const settingsLocal = readSettings(join(root, ".claude", "settings.local.json"));
+    const mcpJsonResult = readJsoncLenient(join(root, ".mcp.json"));
     return {
         settings: readSettings(join(root, ".claude", "settings.json")),
-        settingsLocal: settingsLocalResult.ok
-            ? settingsLocalResult.value
-            : undefined,
+        settingsLocal: settingsLocal.parsed,
+        settingsLocalError: settingsLocal.error,
+        // A malformed or absent .mcp.json is never a structural failure -- it
+        // just means agent-mcp-source (a rubric-only rule) can't see anything
+        // it supplies.
+        mcpJson: mcpJsonResult.ok ? mcpJsonResult.value : undefined,
         hooks: readEach(/^\.claude\/hooks\/[^/]+$/, ".claude/hooks/"),
         agents: readEach(/^\.claude\/agents\/[^/]+\.md$/, ".claude/agents/"),
         skills,

package/dist/harness/rules.d.ts

@@ -15,6 +15,18 @@ export interface HarnessSnapshot {
     };
     /** `.claude/settings.local.json`, parsed, or `undefined` when absent/unparseable. */
     settingsLocal: unknown;
+    /**
+     * Why `.claude/settings.local.json` failed to parse, or `undefined` when it
+     * parsed or is absent -- the distinction `settingsLocal` alone cannot make.
+     */
+    settingsLocalError: string | undefined;
+    /**
+     * Root `.mcp.json`, parsed, or `undefined` when absent/unparseable. A
+     * malformed or absent `.mcp.json` is never a structural failure -- it just
+     * means `agent-mcp-source` (a rubric-only rule) can't see anything it
+     * supplies.
+     */
+    mcpJson: unknown;
     /** Hook filename to source text. */
     hooks: Map<string, string>;
     /** Agent filename (with `.md`) to text. */
@@ -44,9 +56,14 @@ export interface HarnessRule {
     check: (snapshot: HarnessSnapshot) => RuleResult;
 }
 /**
- * Model ids and aliases considered current. Bump alongside the
- * `harness-guidance` refresh sweep; `templates/core/bin/lib/harness-rules.mjs`
- * carries the same list and the parity test keeps the two equal.
+ * Model ids and aliases the rubric accepts: the current ids and aliases, plus
+ * ids that were once listed here, kept until Anthropic deprecates them. The
+ * ids follow Anthropic's models overview and model-deprecations pages
+ * (retrieved 2026-10-01). A legacy id that was never listed here is
+ * deliberately not added, so the rule keeps nudging pins toward current
+ * models. Bump alongside the `harness-guidance` refresh sweep;
+ * `templates/core/bin/lib/harness-rules.mjs` carries the same list and the
+ * parity test keeps the two equal.
  */
 export declare const CURRENT_MODELS: readonly string[];
 /** Every rule, structural first. Order is the order findings are reported in. */

package/dist/harness/rules.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * The harness rule set: a declarative list of checks, each a pure function
  * over a `HarnessSnapshot` (everything the grader read from disk, already in
@@ -15,9 +17,14 @@
 import { isRecord } from "../merge-json.js";
 import { fieldList, fieldText, parseFrontmatter } from "./frontmatter.js";
 /**
- * Model ids and aliases considered current. Bump alongside the
- * `harness-guidance` refresh sweep; `templates/core/bin/lib/harness-rules.mjs`
- * carries the same list and the parity test keeps the two equal.
+ * Model ids and aliases the rubric accepts: the current ids and aliases, plus
+ * ids that were once listed here, kept until Anthropic deprecates them. The
+ * ids follow Anthropic's models overview and model-deprecations pages
+ * (retrieved 2026-10-01). A legacy id that was never listed here is
+ * deliberately not added, so the rule keeps nudging pins toward current
+ * models. Bump alongside the `harness-guidance` refresh sweep;
+ * `templates/core/bin/lib/harness-rules.mjs` carries the same list and the
+ * parity test keeps the two equal.
  */
 export const CURRENT_MODELS = [
     "inherit",
@@ -28,6 +35,7 @@ export const CURRENT_MODELS = [
     "claude-opus-5",
     "claude-opus-5-5",
     "claude-sonnet-5",
+    "claude-sonnet-5-5",
     "claude-fable-5-1",
     "claude-haiku-4-5",
     "claude-haiku-4-5-20251001",
@@ -36,6 +44,10 @@ const SKILL_BODY_LINE_LIMIT = 500;
 const DESCRIPTION_MIN = 40;
 const DESCRIPTION_MAX = 1024;
 const BARE_ENTRY_POINT = /process\.argv\[1\]\s*===\s*fileURLToPath\(import\.meta\.url\)/;
+// Contains `realpathSync(process.argv[1])`, but compares it to a URL-encoded
+// pathname rather than an OS path -- the two never agree under a symlinked
+// or percent-encoded path, so this form fails open too.
+const URL_PATHNAME_ENTRY_POINT = /realpathSync\(process\.argv\[1\]\)\s*===\s*new URL\(import\.meta\.url\)\.pathname/;
 const HOOK_PATH = /\.claude\/hooks\/([A-Za-z0-9_.-]+)/g;
 const CLAUDE_PATH = /\.claude\/[A-Za-z0-9_.*/-]+/g;
 const REFERENCE_PATH = /\breferences\/[A-Za-z0-9_./-]+\.md/g;
@@ -164,6 +176,7 @@ function globToRegExp(glob) {
 function bodyLineCount(body) {
     return body.replace(/\n+$/, "").split("\n").length;
 }
+/** Every rule that reads hook registrations depends on settings.json parsing cleanly -- isolating the parse failure here keeps a downstream rule from either failing confusingly or silently missing every registration. */
 const settingsParses = {
     id: "settings-parses",
     level: "structural",
@@ -180,12 +193,32 @@ const settingsParses = {
             ],
     }),
 };
+/** settings.local.json can register hooks too, and a downstream rule reading hook registrations needs to know when this file failed to parse rather than silently treating it as absent. */
+const settingsLocalParses = {
+    id: "settings-local-parses",
+    level: "structural",
+    category: "settings",
+    check: (s) => ({
+        checked: s.settingsLocalError === undefined ? 0 : 1,
+        failures: s.settingsLocalError === undefined
+            ? []
+            : [
+                {
+                    subject: ".claude/settings.local.json",
+                    message: `does not parse: ${s.settingsLocalError}`,
+                },
+            ],
+    }),
+};
+/** A hook registration naming a file that doesn't exist on disk fails only at the moment Claude Code actually tries to run it -- this is the only check that catches it earlier. */
 const hookDangling = {
     id: "hook-dangling",
     level: "structural",
     category: "hooks",
     check: (s) => {
-        if (s.settings.error !== undefined)
+        // A broken settings.local.json hides its registrations; judging off
+        // settings.json alone would misreport them.
+        if (s.settings.error !== undefined || s.settingsLocalError !== undefined)
             return { checked: 0, failures: [] };
         const referenced = registeredHookFiles(s);
         return {
@@ -199,12 +232,15 @@ const hookDangling = {
         };
     },
 };
+/** A hook file that nothing registers and no reachable hook imports is dead code that silently never runs -- easy to leave behind after refactoring settings.json. */
 const hookOrphan = {
     id: "hook-orphan",
     level: "structural",
     category: "hooks",
     check: (s) => {
-        if (s.settings.error !== undefined)
+        // A broken settings.local.json hides its registrations; judging off
+        // settings.json alone would misreport them.
+        if (s.settings.error !== undefined || s.settingsLocalError !== undefined)
             return { checked: 0, failures: [] };
         const referenced = reachableHookFiles(s);
         const hookFiles = [...s.hooks.keys()].filter((name) => name.endsWith(".mjs") || name.endsWith(".js"));
@@ -219,6 +255,7 @@ const hookOrphan = {
         };
     },
 };
+/** The two weaker entry-point comparisons this rule flags both fail open under a symlinked or URL-encoded path -- the hook's own guard against running twice silently stops working exactly when it matters. */
 const hookEntrypoint = {
     id: "hook-entrypoint",
     level: "structural",
@@ -229,14 +266,16 @@ const hookEntrypoint = {
             checked: sources.length,
             failures: sources
                 .filter(([, source]) => BARE_ENTRY_POINT.test(source) ||
+                URL_PATHNAME_ENTRY_POINT.test(source) ||
                 !source.includes("realpathSync(process.argv[1])"))
                 .map(([name]) => ({
                 subject: `.claude/hooks/${name}`,
-                message: "compares process.argv[1] to import.meta.url without realpathSync -- false under any symlinked path, so the hook fails open",
+                message: "does not compare realpathSync(process.argv[1]) to fileURLToPath(import.meta.url) -- false under a symlinked or URL-encoded path, so the hook fails open",
             })),
         };
     },
 };
+/** A skill with no SKILL.md, malformed frontmatter, or a `name` that doesn't match its directory won't load the way Claude Code expects -- these are wiring defects, not style choices. */
 const skillShape = {
     id: "skill-shape",
     level: "structural",
@@ -270,6 +309,7 @@ const skillShape = {
         return { checked: s.skills.length, failures };
     },
 };
+/** An agent file needs valid frontmatter with a `name` matching its filename and a `description`, or Claude Code either can't dispatch to it or dispatches under the wrong identity. */
 const agentShape = {
     id: "agent-shape",
     level: "structural",
@@ -305,6 +345,7 @@ const agentShape = {
         return { checked: s.agents.size, failures };
     },
 };
+/** A rule file whose frontmatter fails to parse, or whose `paths` list is empty, silently loads never or loads unconditionally when it was meant to be scoped to specific files. */
 const ruleShape = {
     id: "rule-shape",
     level: "structural",
@@ -332,6 +373,7 @@ const ruleShape = {
         return { checked: s.rules.size, failures };
     },
 };
+/** CLAUDE.md naming a `.claude/` path that doesn't exist misleads whoever reads it next; a rule file CLAUDE.md never mentions is just as easy to forget was ever wired in. */
 const claudeMdRefs = {
     id: "claudemd-refs",
     level: "structural",
@@ -368,6 +410,7 @@ const claudeMdRefs = {
         return { checked: refs.size + s.rules.size, failures };
     },
 };
+/** Anthropic's guidance caps a skill body so loading SKILL.md into context stays cheap -- detail past the limit belongs in references/, not inline. */
 const skillBodySize = {
     id: "skill-body-size",
     level: "rubric",
@@ -393,6 +436,7 @@ const skillBodySize = {
         return { checked, failures };
     },
 };
+/** A thin or missing description gives Claude nothing reliable to match the skill or agent against -- it either never triggers, or triggers on the wrong request. */
 const descriptionSubstance = {
     id: "description-substance",
     level: "rubric",
@@ -442,6 +486,7 @@ const descriptionSubstance = {
         return { checked, failures };
     },
 };
+/** An agent that pins no model inherits whatever the calling session happens to run, and a stale model id may reference an alias that's since been retired. */
 const modelPinCurrency = {
     id: "model-pin-currency",
     level: "rubric",
@@ -472,6 +517,7 @@ const modelPinCurrency = {
         return { checked, failures };
     },
 };
+/** An agent that declares no `tools` inherits every tool available, wider access than the agent's actual job usually needs. */
 const agentToolScope = {
     id: "agent-tool-scope",
     level: "rubric",
@@ -494,6 +540,58 @@ const agentToolScope = {
         return { checked, failures };
     },
 };
+/** Assumes a plugin id's name segment (`context7` in `context7@claude-plugins-official`) is the MCP server name it supplies -- true for context7, not guaranteed in general. Reads only `.claude/settings.json`'s `enabledPlugins`, never user-scope settings or `.claude/settings.local.json`, so a plugin enabled only there yields a false positive. */
+function enabledPluginNames(settings) {
+    const names = new Set();
+    if (!isRecord(settings) || !isRecord(settings["enabledPlugins"])) {
+        return names;
+    }
+    for (const [key, value] of Object.entries(settings["enabledPlugins"])) {
+        if (value !== true)
+            continue;
+        const name = key.split("@")[0];
+        if (name !== undefined && name !== "")
+            names.add(name);
+    }
+    return names;
+}
+/** Reads only a root `.mcp.json`, never user-scope or `.claude/settings.local.json` MCP config, so a server supplied only there yields a false positive. */
+function mcpJsonServerNames(mcpJson) {
+    if (!isRecord(mcpJson) || !isRecord(mcpJson["mcpServers"])) {
+        return new Set();
+    }
+    return new Set(Object.keys(mcpJson["mcpServers"]));
+}
+/** An agent whose `mcpServers` names a server no `enabledPlugins` entry or `.mcp.json` actually supplies is a grant that silently does nothing -- exactly the gap the baseline's own code-implementer.md has (`mcpServers: [context7]`) until a project enables the context7 plugin. Rubric, not structural: this is expected mid-customize, only a nudge to finish wiring it. */
+const agentMcpSource = {
+    id: "agent-mcp-source",
+    level: "rubric",
+    category: "agents",
+    check: (s) => {
+        const failures = [];
+        let checked = 0;
+        const supplied = new Set([
+            ...enabledPluginNames(s.settings.parsed),
+            ...mcpJsonServerNames(s.mcpJson),
+        ]);
+        for (const [file, text] of s.agents) {
+            const parsed = parseFrontmatter(text);
+            if (!parsed.ok)
+                continue;
+            for (const server of fieldList(parsed.fields, "mcpServers") ?? []) {
+                checked++;
+                if (!supplied.has(server)) {
+                    failures.push({
+                        subject: `.claude/agents/${file}`,
+                        message: `mcpServers names "${server}", which is not supplied by any enabledPlugins entry or .mcp.json`,
+                    });
+                }
+            }
+        }
+        return { checked, failures };
+    },
+};
+/** A hook registration with no `timeout` can hang the whole session indefinitely if the hook itself ever gets stuck. */
 const hookTimeout = {
     id: "hook-timeout",
     level: "rubric",
@@ -511,6 +609,7 @@ const hookTimeout = {
         };
     },
 };
+/** A rule scoped to a `paths` glob that matches no file in the project silently never loads -- its checklist becomes advice nobody ever sees. */
 const ruleGlobsLive = {
     id: "rule-globs-live",
     level: "rubric",
@@ -536,6 +635,7 @@ const ruleGlobsLive = {
         return { checked, failures };
     },
 };
+/** SKILL.md pointing at a references/ file that doesn't exist promises detail that simply isn't there when someone follows the link. */
 const skillReferencesResolve = {
     id: "skill-references-resolve",
     level: "rubric",
@@ -563,6 +663,7 @@ const skillReferencesResolve = {
 /** Every rule, structural first. Order is the order findings are reported in. */
 export const RULES = [
     settingsParses,
+    settingsLocalParses,
     hookDangling,
     hookOrphan,
     hookEntrypoint,
@@ -574,6 +675,7 @@ export const RULES = [
     descriptionSubstance,
     modelPinCurrency,
     agentToolScope,
+    agentMcpSource,
     hookTimeout,
     ruleGlobsLive,
     skillReferencesResolve,