@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.4

package/templates/core/bin/lib/harness-rules.mjs

@@ -5,9 +5,10 @@
  * points at nothing, a skill with no frontmatter -- and fail the gate.
  * Rubric rules encode Anthropic's published guidance and only ever warn.
  *
- * This file is the emitted twin of m3l-groundwork's own
- * `packages/cli/src/harness/{rules,grade}.ts`; a parity test runs both over
- * the real baseline and asserts identical findings.
+ * Also used by m3l-groundwork's own adopt mode (the tool that generated this
+ * project's harness); if you're contributing a change back upstream, keep
+ * this file's behavior in sync with its source at
+ * `packages/cli/src/harness/{rules,grade}.ts` there.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
@@ -15,10 +16,14 @@ import { join, relative } from "node:path";
 import { fieldList, fieldText, parseFrontmatter } from "./frontmatter.mjs";
 
 /**
- * Model ids and aliases considered current. Bump alongside a harness-guidance
- * refresh sweep.
- * @public Exported for the parity test that compares this file with its TypeScript twin in
- * m3l-groundwork; nothing else in a bootstrapped project imports it.
+ * 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 a harness-guidance refresh sweep.
+ * @public Not imported anywhere else in this project -- exported only for
+ * m3l-groundwork's own upstream parity check (see the file header above).
  */
 export const CURRENT_MODELS = [
   "inherit",
@@ -29,6 +34,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",
@@ -40,6 +46,11 @@ const DESCRIPTION_MAX = 1024;
 const PROJECT_WALK_DEPTH = 8;
 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;
@@ -57,6 +68,13 @@ const SKIP_DIR_NAMES = new Set([
   ".nx",
 ]);
 
+// Claude Code creates git worktrees at `.claude/worktrees/<name>/` -- each a
+// full second checkout that must not be walked twice. Matched as an exact
+// path relative to the walk root, never by bare name: a directory literally
+// named `worktrees` elsewhere (`src/worktrees/`, `.claude/skills/worktrees/`)
+// is real project content and must stay visible to every grade.
+const SKIP_REL_DIR_PATHS = new Set([".claude/worktrees"]);
+
 const isRecord = (value) =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
@@ -76,9 +94,11 @@ function walkBounded(root, maxDepth) {
     for (const entry of entries) {
       if (entry.isDirectory() && SKIP_DIR_NAMES.has(entry.name)) continue;
       const path = join(dir, entry.name);
+      const relPath = relative(root, path).split("\\").join("/");
+      if (entry.isDirectory() && SKIP_REL_DIR_PATHS.has(relPath)) continue;
       results.push({
         path,
-        relPath: relative(root, path).split("\\").join("/"),
+        relPath,
         isDirectory: entry.isDirectory(),
       });
       if (entry.isDirectory()) visit(path, depth + 1);
@@ -203,9 +223,9 @@ function loadSnapshot(root) {
 
   const settingsPath = join(root, ".claude", "settings.json");
   const settingsResult = readJsonc(settingsPath);
-  const settingsLocalResult = readJsonc(
-    join(root, ".claude", "settings.local.json"),
-  );
+  const settingsLocalPath = join(root, ".claude", "settings.local.json");
+  const settingsLocalResult = readJsonc(settingsLocalPath);
+  const mcpJsonResult = readJsonc(join(root, ".mcp.json"));
 
   return {
     settings: !existsSync(settingsPath)
@@ -216,6 +236,15 @@ function loadSnapshot(root) {
     settingsLocal: settingsLocalResult.ok
       ? settingsLocalResult.value
       : undefined,
+    // Only a file that exists can fail to parse -- an absent one is not an error.
+    settingsLocalError:
+      !settingsLocalResult.ok && existsSync(settingsLocalPath)
+        ? settingsLocalResult.error
+        : undefined,
+    // 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,
@@ -351,6 +380,7 @@ function bodyLineCount(body) {
 
 // --- rules -----------------------------------------------------------------
 
+/** 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",
@@ -369,12 +399,35 @@ 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) return { checked: 0, failures: [] };
+    // 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 {
       checked: referenced.size,
@@ -388,12 +441,16 @@ 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) return { checked: 0, failures: [] };
+    // 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"),
@@ -411,6 +468,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",
@@ -425,17 +483,19 @@ const hookEntrypoint = {
         .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",
+            "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",
@@ -470,6 +530,7 @@ const skillShape = {
   },
 };
 
+/** 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",
@@ -505,6 +566,7 @@ const agentShape = {
   },
 };
 
+/** 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",
@@ -532,6 +594,7 @@ const ruleShape = {
   },
 };
 
+/** 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",
@@ -568,6 +631,7 @@ const claudeMdRefs = {
   },
 };
 
+/** 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",
@@ -592,6 +656,7 @@ const skillBodySize = {
   },
 };
 
+/** 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",
@@ -640,6 +705,7 @@ const descriptionSubstance = {
   },
 };
 
+/** 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",
@@ -669,6 +735,7 @@ const modelPinCurrency = {
   },
 };
 
+/** 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",
@@ -691,6 +758,56 @@ const agentToolScope = {
   },
 };
 
+/** 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",
@@ -709,6 +826,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",
@@ -734,6 +852,7 @@ const ruleGlobsLive = {
   },
 };
 
+/** 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",
@@ -762,11 +881,12 @@ const skillReferencesResolve = {
 
 /**
  * Every rule, structural first. Order is the order findings are reported in.
- * @public Exported for the parity test that compares this file with its TypeScript twin in
- * m3l-groundwork; nothing else in a bootstrapped project imports it.
+ * @public Not imported anywhere else in this project -- exported only for
+ * m3l-groundwork's own upstream parity check (see the file header above).
  */
 export const RULES = [
   settingsParses,
+  settingsLocalParses,
   hookDangling,
   hookOrphan,
   hookEntrypoint,
@@ -778,6 +898,7 @@ export const RULES = [
   descriptionSubstance,
   modelPinCurrency,
   agentToolScope,
+  agentMcpSource,
   hookTimeout,
   ruleGlobsLive,
   skillReferencesResolve,
@@ -835,6 +956,7 @@ export function reportGrade(grade, reporter) {
 export function reportOfficialValidation(rootDir, reporter) {
   let ran = false;
   let findings = 0;
+  let unreadable = 0;
   for (const dir of [".claude/skills", ".claude/agents"]) {
     const target = join(rootDir, dir);
     if (!existsSync(target)) continue;
@@ -851,22 +973,49 @@ export function reportOfficialValidation(rootDir, reporter) {
     try {
       report = JSON.parse(result.stdout);
     } catch {
+      report = undefined;
+    }
+    // Anything other than a real report -- a spawn failure other than
+    // ENOENT (result.stdout is then null, and JSON.parse(null) parses as
+    // the value `null` rather than throwing), or a valid-JSON error payload
+    // with no `contents` array -- is treated the same as unreadable, never
+    // silently read as "zero findings" or allowed to crash on `.contents`.
+    if (!Array.isArray(report?.contents)) {
       reporter.warn(
         `claude plugin validate gave no readable report for ${dir}`,
       );
+      unreadable++;
       continue;
     }
     ran = true;
-    for (const entry of report.contents ?? []) {
-      for (const item of [...(entry.errors ?? []), ...(entry.warnings ?? [])]) {
+    // Each entry and finding is external data too: a malformed one is
+    // reported and skipped, never allowed to crash the gate or vanish.
+    for (const entry of report.contents) {
+      if (!isRecord(entry) || typeof entry.file !== "string") {
+        reporter.warn(
+          `claude plugin validate reported a malformed entry for ${dir} -- skipped`,
+        );
+        unreadable++;
+        continue;
+      }
+      const errors = Array.isArray(entry.errors) ? entry.errors : [];
+      const warnings = Array.isArray(entry.warnings) ? entry.warnings : [];
+      const file = relative(rootDir, entry.file);
+      for (const item of [...errors, ...warnings]) {
         findings++;
+        if (!isRecord(item)) {
+          reporter.warn(
+            `[claude-validate] ${file} -- malformed finding (not an object)`,
+          );
+          continue;
+        }
         reporter.warn(
-          `[claude-validate] ${relative(rootDir, entry.file)} -- ${item.path}: ${item.message}`,
+          `[claude-validate] ${file} -- ${String(item.path)}: ${String(item.message)}`,
         );
       }
     }
   }
-  if (ran && findings === 0) {
+  if (ran && findings === 0 && unreadable === 0) {
     reporter.ok("claude plugin validate: no findings");
   }
 }

package/templates/core/bin/lib/protected-paths.mjs

@@ -3,21 +3,109 @@
 // source and test trees. Shared by:
 //   - .claude/hooks/guard-branch-isolation.mjs  (blocks writes while HEAD is main)
 //   - .claude/hooks/guard-hub-src-writes.mjs    (blocks hub writes on any branch)
+//   - .claude/hooks/post-edit-verify.mjs        (decides whether to run the gate)
 //
 // Keeping the regex in one place means neither guard can silently diverge
 // from the other when the protected glob set evolves.
 
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+const WINDOWS_DRIVE = /^[A-Za-z]:/;
+
+/** `\` and `/` both normalized to `/`, so a Windows-style path is matched the same as a POSIX one. */
+function normalizeSlashes(path) {
+  return path.replace(/\\/g, "/");
+}
+
+/** Exported so a caller can decide whether canonicalizing a path even makes sense (a relative path has no filesystem anchor of its own to resolve against). */
+export function isAbsoluteLike(path) {
+  return path.startsWith("/") || WINDOWS_DRIVE.test(path);
+}
+
 /**
- * Returns true if `filePath` has any `src/` or `tests/` path segment --
- * this single check covers a flat `src/`/`tests/` layout AND a nested one
+ * Returns true if `filePath` has a `src/` or `tests/` path segment -- this
+ * single check covers a flat `src/`/`tests/` layout AND a nested one
  * (`packages/<pkg>/src/`), since both contain the literal substring
  * `/src/` preceded by a path boundary.
  *
- * Matches both relative and absolute paths (the `(^|\/)` anchor).
+ * `projectDir`, when given, scopes an ABSOLUTE `filePath` to the project
+ * before applying that check: the path is made relative to `projectDir` by
+ * literal string prefix, not `node:path` (whose `relative`/`isAbsolute` are
+ * host-OS-dependent), so the same logic works identically on POSIX and
+ * Windows-style paths regardless of which OS is actually running the hook.
+ * An absolute path that does not start with `projectDir` is outside the
+ * project entirely and is never protected -- this is what stops a checkout
+ * living under a path that happens to contain the literal substring `/src/`
+ * (e.g. `~/src/other-project`) from being treated as protected merely
+ * because that substring appears somewhere above the real project root.
+ *
+ * A relative `filePath` (or a call with no `projectDir`) is matched as-is,
+ * after slash normalization -- the same behavior this function has always had.
  *
  * @param {string} filePath
+ * @param {string} [projectDir]
  * @returns {boolean}
  */
-export function isProtectedPath(filePath) {
-  return /(^|\/)src\//.test(filePath) || /(^|\/)tests\//.test(filePath);
+export function isProtectedPath(filePath, projectDir) {
+  const path = normalizeSlashes(filePath);
+  let candidate = path;
+
+  if (isAbsoluteLike(path) && typeof projectDir === "string") {
+    const root = normalizeSlashes(projectDir).replace(/\/+$/, "");
+    // Compared case-INSENSITIVELY (macOS's default APFS, and Windows, are
+    // both case-insensitive-but-case-preserving -- a `filePath` spelled with
+    // different case than `projectDir` can still denote the identical real
+    // file). This holds even when the caller couldn't fully canonicalize a
+    // not-yet-existing path against the real filesystem (see
+    // `canonicalize()` below) and matters more than it costs: on a
+    // genuinely case-SENSITIVE filesystem this can only make the check
+    // MORE conservative (occasionally treating two truly-different,
+    // same-spelled-but-cased directories as the same project), never less --
+    // and erring toward "still protected" is the safe side for a guard.
+    const pathLower = path.toLowerCase();
+    const rootLower = root.toLowerCase();
+    if (pathLower === rootLower || pathLower.startsWith(`${rootLower}/`)) {
+      candidate = path.slice(root.length).replace(/^\/+/, "");
+    } else {
+      return false;
+    }
+  }
+
+  return /(^|\/)src\//.test(candidate) || /(^|\/)tests\//.test(candidate);
+}
+
+/**
+ * Resolves `path` to its canonical, case-correct, symlink-resolved form,
+ * via the deepest existing ancestor -- never throws, even for a path (or a
+ * tail of one) that doesn't exist yet, e.g. a file a Write is about to
+ * create in a directory that doesn't exist yet either.
+ *
+ * Uses `realpathSync.native`, not plain `realpathSync`: on a
+ * case-insensitive-but-case-preserving filesystem (macOS's default APFS),
+ * only the native variant corrects a wrongly-cased spelling to the real
+ * on-disk case -- the same canonical case `git rev-parse --show-toplevel`
+ * already returns. Comparing an un-canonicalized `filePath` against a
+ * canonicalized `projectDir`/worktree root (or vice versa) would otherwise
+ * make two spellings of the identical file compare as different paths,
+ * which is exactly the shape of bug this function exists to close.
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+export function canonicalize(path) {
+  const absolute = resolve(path);
+  const tail = [];
+  let candidate = absolute;
+  while (true) {
+    try {
+      const real = realpathSync.native(candidate);
+      return tail.length === 0 ? real : join(real, ...tail.reverse());
+    } catch {
+      const parent = dirname(candidate);
+      if (parent === candidate) return absolute; // filesystem root; give up
+      tail.push(basename(candidate));
+      candidate = parent;
+    }
+  }
 }