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

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

@@ -17,19 +17,20 @@
  * not a JavaScript tokenizer; it can mis-handle a regex literal or a template
  * string, which none of the graded baseline files contain.
  *
- * This file is the emitted twin of m3l-groundwork's own
- * `packages/cli/src/toolchain/{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 toolchain); if you're contributing a change back upstream, keep
+ * this file's behavior in sync with its source at
+ * `packages/cli/src/toolchain/{rules,grade}.ts` there.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 /**
  * Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them
  * (`outFile` and `moduleResolution: classic` already went in 6.0).
  * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
- * @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 LEGACY_OPTIONS = [
   {
@@ -113,8 +114,8 @@ export const LEGACY_OPTIONS = [
  * (`@typescript-eslint/no-unused-vars` covers both with an `^_` escape hatch
  * tsc's flags lack), and `forceConsistentCasingInFileNames` (defaults on).
  * `allowUnreachableCode` is graded separately -- it must be `false`.
- * @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 STRICT_FLAGS = [
   "strict",
@@ -132,8 +133,8 @@ export const STRICT_FLAGS = [
 
 /**
  * The rubric categories, in report order.
- * @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 CATEGORIES = [
   "tsconfig",
@@ -207,6 +208,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);
 const lower = (value) =>
@@ -228,9 +236,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);
@@ -293,13 +303,123 @@ function stripJsoncNoise(content) {
   return result.replace(/,(\s*[}\]])/g, "$1");
 }
 
+/**
+ * Strips `//` and block comments from JS/TS source, leaving `'`, `"` and
+ * `` ` `` string literals alone. Keeps trailing commas -- valid JS, and
+ * removing them is a JSON-only cleanup.
+ *
+ * A character scanner, not a parser: a regex literal containing a quote
+ * (`/["']/`) can be misread as opening a string, and a `${...}` expression
+ * inside a template literal containing its own backtick or quote can close
+ * the outer template early. Neither shape appears in this project's actual
+ * `eslint.config.js`/`vitest.config.ts`/`verify-steps.mjs` files.
+ */
+function stripJsComments(content) {
+  let result = "";
+  let quote;
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (inLineComment) {
+      if (ch === "\n") {
+        inLineComment = false;
+        result += ch;
+      }
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === "*" && next === "/") {
+        inBlockComment = false;
+        i++;
+      }
+      continue;
+    }
+    if (quote !== undefined) {
+      result += ch;
+      if (ch === "\\") {
+        result += next ?? "";
+        i++;
+        continue;
+      }
+      if (ch === quote) quote = undefined;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      result += ch;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      inLineComment = true;
+      i++;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      inBlockComment = true;
+      i++;
+      continue;
+    }
+    result += ch;
+  }
+  return result;
+}
+
+// --- errno classification (twin of packages/cli/src/survey/internal/read-guard.ts) ---
+
+/** The `code` of a Node system error, or `undefined` for anything without a string `code`. */
+function errnoCode(error) {
+  if (typeof error !== "object" || error === null) return undefined;
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : undefined;
+}
+
+/** "Nothing is at this path": nothing there, or an ancestor is a file. */
+const ABSENT_CODES = new Set(["ENOENT", "ENOTDIR"]);
+
+/**
+ * "Something is at this path this process cannot read or resolve": a
+ * permission failure, or a symlink loop. Never folded into "absent".
+ */
+const UNRESOLVABLE_CODES = new Set(["EACCES", "EPERM", "ELOOP"]);
+
+const isAbsentError = (error) => ABSENT_CODES.has(errnoCode(error) ?? "");
+
+function unresolvableCode(error) {
+  const code = errnoCode(error);
+  return code !== undefined && UNRESOLVABLE_CODES.has(code) ? code : undefined;
+}
+
+/**
+ * Reads and parses a JSONC file. A missing (`ENOENT`/`ENOTDIR`), unreadable
+ * (`EACCES`/`EPERM`), unresolvable (`ELOOP`), not-a-regular-file (`EISDIR`)
+ * or unparseable file is reported, not thrown. The existence check is a real
+ * `stat`, never `existsSync`, so a file under a directory this process cannot
+ * search is reported with its errno rather than as absent. Any other failure
+ * (`EIO`, `EMFILE`, ...) throws an `Error` naming the path, with the original
+ * as `cause`.
+ */
 function readJsonc(path) {
-  if (!existsSync(path)) return { ok: false, error: `${path} does not exist` };
+  let content;
   try {
-    return {
-      ok: true,
-      value: JSON.parse(stripJsoncNoise(readFileSync(path, "utf8"))),
-    };
+    statSync(path);
+    content = readFileSync(path, "utf8");
+  } catch (error) {
+    if (isAbsentError(error)) {
+      return { ok: false, error: `${path} does not exist` };
+    }
+    if (errnoCode(error) === "EISDIR") {
+      return { ok: false, error: `${path} is not a regular file` };
+    }
+    const code = unresolvableCode(error);
+    if (code === undefined) {
+      throw new Error(`could not read ${path}`, { cause: error });
+    }
+    return { ok: false, error: `${path} is unreadable (${code})` };
+  }
+  try {
+    return { ok: true, value: JSON.parse(stripJsoncNoise(content)) };
   } catch (error) {
     return {
       ok: false,
@@ -311,7 +431,7 @@ function readJsonc(path) {
 /** File text with comments stripped, or `undefined` when unreadable. */
 function readSource(path) {
   try {
-    return stripJsoncNoise(readFileSync(path, "utf8"));
+    return stripJsComments(readFileSync(path, "utf8"));
   } catch {
     return undefined;
   }
@@ -326,12 +446,25 @@ function readRaw(path) {
   }
 }
 
+/**
+ * Whether `path` is a candidate `extends` target: a regular file, or
+ * something this process cannot reach (`EACCES`/`EPERM`/`ELOOP`). The latter
+ * is taken as the target so `readJsonc` records it as unreadable with its
+ * errno -- never reported as resolving to no file when it may well be there.
+ * `ENOENT`/`ENOTDIR` is not a candidate; any other errno throws.
+ */
 function isFile(path) {
+  let stats;
   try {
-    return statSync(path).isFile();
-  } catch {
-    return false;
+    stats = statSync(path);
+  } catch (error) {
+    if (isAbsentError(error)) return false;
+    if (unresolvableCode(error) !== undefined) return true;
+    throw new Error(`could not check whether ${path} exists`, {
+      cause: error,
+    });
   }
+  return stats.isFile();
 }
 
 /** The `extends` value as a list: a string, or TypeScript 5.0+'s array form. */
@@ -469,20 +602,34 @@ function scrapeGateSteps(text) {
  * Reads every `verify.mjs` invocation out of one YAML surface as data: the
  * `--group`/`--step` each names. YAML is scraped, never parsed. An invocation
  * naming neither (a matrix, or a bare full run) marks the surface `dynamic`.
+ * Comments are stripped per line before any `\` line continuation is joined,
+ * so a comment ending in `\` cannot swallow the next line. A quoted value is
+ * read unquoted. A mention inside an `echo` (in the same shell command, not an
+ * earlier `&&`/`;`/`|` segment) or inside a step's `name:` with no `run:`
+ * before it on the line is not an invocation.
  */
 function scrapeLaneInvocations(text) {
   const groups = [];
   const steps = [];
   let dynamic = false;
   let seen = false;
-  for (const raw of text.split("\n")) {
-    const line = raw.replace(/(^|\s)#.*$/, "");
+  const logicalLines = text
+    .split("\n")
+    .map((raw) => raw.replace(/(^|\s)#.*$/, ""))
+    .join("\n")
+    .replace(/\\\r?\n[ \t]*/g, " ")
+    .split("\n");
+  for (const line of logicalLines) {
     const at = line.indexOf("verify.mjs");
     if (at === -1) continue;
+    const prefix = line.slice(0, at);
+    const lastSegment = prefix.split(/&&|\|\||[;|]/).pop() ?? "";
+    if (/\becho\b/.test(lastSegment)) continue;
+    if (/\bname\s*:/.test(prefix) && !/\brun\s*:/.test(prefix)) continue;
     seen = true;
     const rest = line.slice(at);
-    const group = /--group[ =]+([A-Za-z][\w-]*)/.exec(rest);
-    const step = /--step[ =]+([A-Za-z][\w-]*)/.exec(rest);
+    const group = /--group[ =]+["']?([A-Za-z][\w-]*)["']?/.exec(rest);
+    const step = /--step[ =]+["']?([A-Za-z][\w-]*)["']?/.exec(rest);
     if (group !== null) groups.push(group[1]);
     else if (step !== null) steps.push(step[1]);
     else dynamic = true;
@@ -657,6 +804,7 @@ const NONE = { checked: 0, failures: [] };
 
 // --- structural rules ------------------------------------------------------
 
+/** A tsconfig that fails to parse breaks every rule that reads its chain -- reporting the parse error itself, first, keeps a later rule's silence from being mistaken for a clean file. */
 const tsconfigParses = {
   id: "tsconfig-parses",
   level: "structural",
@@ -672,6 +820,7 @@ const tsconfigParses = {
   }),
 };
 
+/** An `extends` specifier that resolves to no file silently drops every option the base file would have set -- tsc itself gives no error until something downstream trips on the missing option. */
 const tsconfigExtendsResolves = {
   id: "tsconfig-extends-resolves",
   level: "structural",
@@ -694,6 +843,7 @@ const tsconfigExtendsResolves = {
   },
 };
 
+/** The tsconfig `build` compiles must actually set an outDir (or `build` emits .js next to sources) and must not set noEmit -- and if a separate tooling tsconfig sits beside it, that one must set noEmit, or typecheck starts emitting too. */
 const tsconfigEmitCoherence = {
   id: "tsconfig-emit-coherence",
   level: "structural",
@@ -732,6 +882,7 @@ const tsconfigEmitCoherence = {
   },
 };
 
+/** A verify step naming a package.json script, a file, or a group that doesn't exist is a wiring defect no offline check other than this one would catch before someone actually runs it. */
 const gateWiring = {
   id: "gate-wiring",
   level: "structural",
@@ -800,6 +951,7 @@ const gateWiring = {
   },
 };
 
+/** Confirms every CI/lefthook lane invokes verify.mjs by static group name, not by step id or a dynamic matrix -- otherwise a new gate can silently go unenforced in one surface while it passes in another. */
 const gateLaneParity = {
   id: "gate-lane-parity",
   level: "structural",
@@ -853,6 +1005,7 @@ function enginesBounds(range) {
   };
 }
 
+/** `.node-version` outside the range package.json's `engines.node` declares means the pinned dev/CI Node isn't even a Node version the project claims to support. */
 const nodePinCoherence = {
   id: "node-pin-coherence",
   level: "structural",
@@ -885,6 +1038,7 @@ const nodePinCoherence = {
 
 // --- rubric rules ----------------------------------------------------------
 
+/** The strict-family flags are the floor current TypeScript guidance recommends; tsc raises no warning for a flag simply left off, so this is the only check that notices. */
 const strictFlags = {
   id: "strict-flags",
   level: "rubric",
@@ -910,6 +1064,7 @@ const strictFlags = {
   },
 };
 
+/** Warns ahead of a TypeScript major that removes an option outright -- by the time tsc itself rejects it, the fix is no longer a choice, it's an emergency. */
 const tsconfigOptionLifecycle = {
   id: "tsconfig-option-lifecycle",
   level: "rubric",
@@ -947,6 +1102,7 @@ const tsconfigOptionLifecycle = {
   },
 };
 
+/** An outdated `module`/`moduleResolution`/`target` still compiles fine today, but forgoes current Node/bundler resolution semantics and syntax the project doesn't need to lower. */
 const moduleTargetModern = {
   id: "module-target-modern",
   level: "rubric",
@@ -989,6 +1145,7 @@ const moduleTargetModern = {
   },
 };
 
+/** ESLint 10 reads only eslint.config.* -- a lingering legacy eslintrc file means either an old ESLint is still in play, or a current one is silently linting nothing. */
 const eslintFlatConfig = {
   id: "eslint-flat-config",
   level: "rubric",
@@ -1008,6 +1165,7 @@ const eslintFlatConfig = {
   },
 };
 
+/** Without a type-checked preset and `projectService`, typescript-eslint runs syntax-only rules and silently skips every rule that needs real type information. */
 const eslintTypedLinting = {
   id: "eslint-typed-linting",
   level: "rubric",
@@ -1054,6 +1212,7 @@ const eslintTypedLinting = {
   },
 };
 
+/** `bin/**` and `.claude/hooks/**` are code this project actually runs, not incidental scripts -- if ESLint has no config block for them, or actively ignores src, they ship unlinted. */
 const eslintCoversEmittedCode = {
   id: "eslint-covers-emitted-code",
   level: "rubric",
@@ -1093,6 +1252,7 @@ const eslintCoversEmittedCode = {
   },
 };
 
+/** A coverage threshold without `perFile: true` lets one well-tested file's coverage average out another file with none -- the gate passes while a whole file goes untested. */
 const coverageGate = {
   id: "coverage-gate",
   level: "rubric",
@@ -1119,6 +1279,7 @@ const coverageGate = {
   },
 };
 
+/** An unpinned toolchain package, a missing `packageManager`, or an `@types/node` major that doesn't match the pinned Node version each make installs non-reproducible across machines and CI runs. */
 const toolchainPinShape = {
   id: "toolchain-pin-shape",
   level: "rubric",
@@ -1172,8 +1333,8 @@ const toolchainPinShape = {
 
 /**
  * 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 = [
   tsconfigParses,

package/templates/core/bin/lib/verify-steps.mjs

@@ -2,11 +2,17 @@
 /**
  * The single source of truth for what `pnpm verify` runs locally, what the
  * lefthook `pre-push` lanes run, and what each `.github/workflows/ci.yml`
- * job runs. Both YAML files name a *group*, never a step id: groups are a
- * closed, five-member set (see GROUPS below); steps are not. That's what
- * lets a new step -- core or pack-contributed -- join `pnpm verify` without
- * ever touching either YAML file, and what keeps this the one list to keep
- * in sync instead of three that agree by hand.
+ * job runs.
+ *
+ * Two words, two meanings: a *step* is one gate (e.g. "Lint", cmd
+ * `pnpm lint`); a *group* is one of five fixed buckets a step belongs to
+ * (`format`/`lint`/`typecheck`/`build`/`test`, see GROUPS below). A *lane* is
+ * the outside caller that runs a whole group at once -- a lefthook
+ * `pre-push` lane, or a CI job in `.github/workflows/ci.yml`. Both YAML files
+ * name a *group*, never a step id: that's what lets a new step -- core or
+ * pack-contributed -- join `pnpm verify` without ever touching either YAML
+ * file, and what keeps this the one list to keep in sync instead of three
+ * that agree by hand.
  *
  * Pack-installed steps live in verify-steps.packs.json, a plain JSON array
  * the bootstrapper CLI appends to when installing a pack -- it has no JS
@@ -25,9 +31,11 @@ import { fileURLToPath } from "node:url";
 export const GROUPS = ["format", "lint", "typecheck", "build", "test"];
 
 /**
- * The gate steps this baseline ships, before any pack's are appended.
- * @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.
+ * The gate steps this project ships out of the box, before any pack's own
+ * steps are appended.
+ * @public Not imported anywhere else in this project -- exported only so
+ * m3l-groundwork can compare it against its own upstream copy when it
+ * updates this tooling.
  */
 export const CORE_STEPS = [
   {
@@ -90,11 +98,21 @@ function readPackSteps() {
   let raw;
   try {
     raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw new Error(`verify-steps.packs.json: cannot read ${path}`, {
+      cause: error,
+    });
   }
 
-  const parsed = JSON.parse(raw);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`verify-steps.packs.json: failed to parse ${path}`, {
+      cause: error,
+    });
+  }
   if (!Array.isArray(parsed)) {
     throw new Error("verify-steps.packs.json must be a JSON array of steps");
   }

package/templates/core/bin/verify.mjs

@@ -7,6 +7,10 @@
  * `lefthook.yml` each invoke `--group <name>`, never individual step ids, so
  * a new step -- core or pack-contributed -- is picked up by both without
  * either file changing.
+ *
+ * "Group" and "lane" are two different things: a group is one of the five
+ * fixed buckets above; a lane is the outside caller that runs a whole group
+ * at once -- one lefthook `pre-push` lane, or one CI job in `ci.yml`.
  */
 import process from "node:process";
 import { spawnSync } from "node:child_process";
@@ -19,8 +23,16 @@ import {
 
 const args = process.argv.slice(2);
 const stepIndex = args.indexOf("--step");
+if (stepIndex !== -1 && !args[stepIndex + 1]) {
+  console.error("verify: --step requires a value");
+  process.exit(1);
+}
 const requestedId = stepIndex === -1 ? null : args[stepIndex + 1];
 const groupIndex = args.indexOf("--group");
+if (groupIndex !== -1 && !args[groupIndex + 1]) {
+  console.error("verify: --group requires a value");
+  process.exit(1);
+}
 const requestedGroup = groupIndex === -1 ? null : args[groupIndex + 1];
 
 if (requestedGroup && !GROUPS.includes(requestedGroup)) {

package/templates/core/eslint.config.js

@@ -22,6 +22,11 @@ export default defineConfig(
       ".claude/agents/**",
       ".claude/skills/**",
       ".claude/rules/**",
+      // A worktree the harness creates (see .prettierignore) is a full,
+      // independent checkout under here, with its own eslint-relevant files
+      // -- without this, `pnpm lint` from the main checkout also walks (and
+      // can fail on) that copy's own in-progress state.
+      ".claude/worktrees/**",
     ],
   },
   js.configs.recommended,

package/templates/core/package.json

@@ -3,8 +3,8 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "Bootstrapped by m3l-groundwork.",
-  "packageManager": "pnpm@12.4.0",
+  "description": "TODO: describe __PROJECT_NAME__ (bootstrapped by m3l-groundwork).",
+  "packageManager": "pnpm@12.8.1",
   "engines": {
     "node": ">=24"
   },
@@ -41,18 +41,18 @@
     "@commitlint/types": "^21.2.0",
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.13.3",
-    "@vitest/coverage-v8": "^4.1.11",
-    "eslint": "^10.9.1",
+    "@vitest/coverage-v8": "^5.0.2",
+    "eslint": "^10.11.0",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-tsdoc": "^0.5.2",
     "globals": "^17.12.0",
-    "knip": "^6.34.0",
+    "knip": "^6.38.0",
     "lefthook": "^2.1.12",
     "prettier": "^3.9.6",
     "publint": "^0.3.24",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.69.0",
-    "vitest": "^4.1.11"
+    "typescript-eslint": "^8.71.0",
+    "vitest": "^5.0.2"
   }
 }

package/templates/core/vitest.config.ts

@@ -4,7 +4,14 @@ export default defineConfig({
   test: {
     pool: "forks",
     include: ["**/tests/**/*.test.ts", "**/*.test.ts"],
-    exclude: ["**/dist/**", "**/node_modules/**"],
+    exclude: [
+      "**/dist/**",
+      "**/node_modules/**",
+      // A worktree the harness creates (see .prettierignore) is a full,
+      // independent checkout under here, with its own tests/ tree --
+      // without this every test in the project runs twice, once per copy.
+      "**/.claude/worktrees/**",
+    ],
     coverage: {
       provider: "v8",
       include: ["src/**/*.ts"],

package/templates/packs/README.md

@@ -18,24 +18,33 @@ templates/packs/<name>/
 
 ## The wiring contract
 
-**A pack never edits YAML or JavaScript.** It may add files under `files/`,
-and may extend three JSON files the baseline already reads at runtime:
+**A pack never edits YAML or JavaScript.** It may add files under `files/`.
+**A pack also can't ship a `.claude/rules/*.md` file**: the harness grader's
+structural `claudemd-refs` rule fails on any rule `CLAUDE.md` doesn't name
+by path, and a pack has no way to edit `CLAUDE.md` (that's not one of the
+three JSON files below either). If a pack needs to state a project-wide
+policy, put it in the body of a skill it ships instead — see the `worktrees`
+pack's `working-in-worktrees` skill for the pattern.
+It may also extend three JSON files the baseline already reads at runtime:
 `.claude/settings.json` (hook registrations, and top-level harness settings
 such as `statusLine`), `package.json` (`scripts`), and
-`bin/lib/verify-steps.packs.json` (gate steps, keyed to one of the five
-fixed verify groups `templates/core/bin/lib/verify-steps.mjs` defines —
-`format`/`lint`/`typecheck`/`build`/`test`). A gate registered this way runs
+`bin/lib/verify-steps.packs.json`. That last file holds gate steps, each
+keyed to one of the five fixed verify groups
+`templates/core/bin/lib/verify-steps.mjs` defines —
+`format`/`lint`/`typecheck`/`build`/`test`. A gate registered this way runs
 under `pnpm verify`, every `lefthook.yml` `pre-push` lane, and every
-`.github/workflows/ci.yml` job automatically, because all three already
-enumerate groups rather than individual steps.
+`.github/workflows/ci.yml` job automatically. That works because all three
+already enumerate groups rather than individual steps.
 
 `pack.json` fields:
 
 - `schemaVersion` — currently `1`.
-- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. Only artifacts with no
-  dependency on the baseline's exact file layout (an agent, most hooks) are
-  safely adopt-capable; a gate that assumes a specific source layout should
-  say so honestly in `adoptNotes` instead of claiming `adopt`.
+- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. "Adopt-capable" means
+  an artifact has no dependency on the baseline's exact file layout (an
+  agent, most hooks), so it's safe to install into an already-existing
+  project's own layout. A gate that assumes a specific source layout isn't
+  adopt-capable -- it should say so honestly in `adoptNotes` instead of
+  claiming `adopt`.
 - `budget` — the pack's cap deltas (`agents`/`skills`/`hooks`/`workflows`/
   `scripts`), checked against `templates/core`'s own counts by a structural
   test, never against `templates/core` + every other pack.
@@ -63,19 +72,21 @@ enumerate groups rather than individual steps.
   repeatable) — it wrote the baseline moments ago, so there's no uncertainty
   to defer.
 - **Adopt mode**: the CLI never installs a pack. It surveys which packs
-  apply and stages their payload at `.groundwork/packs/<name>/`;
-  `/customize`'s Step 0 confirms and Round 1 installs, translating
-  `wiring.verifySteps`/`wiring.settings` against the project's _real_ gate
-  runner and hook config — read for real by that point, not guessed at
-  offline.
+  apply and stages their payload at `.groundwork/packs/<name>/`. Later,
+  `/customize` confirms the install in **Step 0** (its first, up-front
+  confirmation round, before any file is written) and performs it in
+  **Round 1** (the first pass of deterministic edits that follows). That
+  installation translates `wiring.verifySteps`/`wiring.settings` against
+  the project's _real_ gate runner and hook config — read for real by that
+  point, not guessed at offline.
 
 ## Available packs
 
-| Pack             | Contents                                                                                                                                                                                                                                                            |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `harness-extras` | A type-design-analyzer agent, the compaction-handoff hook pair, a read-only Bash guard, and a per-file size ratchet gate — the four artifacts the original baseline build cut purely to hold its caps.                                                              |
-| `statusline`     | A five-row Claude Code status line (session, model, context, quota, work) plus a per-subagent row renderer, both width-fit to the terminal. Registers top-level `statusLine`/`subagentStatusLine` settings, no hooks and no gate. Runs the same on macOS and Linux. |
-
-`github-ops` (dependabot/scan-alert triage skills) and `publishing` (a
-release workflow + npm-publish gates) are documented follow-ups, not yet
-built — see root `CLAUDE.md`'s Known gaps.
+| Pack             | Contents                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `harness-extras` | Claude Code session ergonomics: the compaction-handoff hook pair, a read-only Bash guard, and a five-row status line (session, model, context, quota, work) plus a per-subagent row renderer. The only pack that sets top-level settings keys (`statusLine`, `subagentStatusLine`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `quality`        | Two language-level review aids: a per-file size ratchet gate (`check-file-budget.mjs`, a `build`-group verify step) and a read-only `type-design-analyzer` agent. No hooks, no settings. Adopt-capable and recommended for every project kind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `github`         | GitHub-hosted collaboration: Anthropic's official Claude Code GitHub Action wired for `@claude` mention-mode, a second Action that posts an automated Claude review comment on every PR, and three `gh`-CLI skills — `reviewing-dependabot-prs`, `triaging-scan-alerts`, `watching-pr-checks`. No hooks, no gate. The two workflows need an auth secret this pack cannot create; see its `adoptNotes`.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `publishing`     | A release pipeline: `release.yml` (changesets version-PR / staged, provenance-attested npm publish via trusted publishing), `check-publish-version.mjs`, `check-dts-deps.mjs`, `check-license-headers.mjs` and a `REUSE.toml` template. Fresh mode only — see "Install path" below and its `adoptNotes`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `supply-chain`   | Secret scanning (`gitleaks.yml` with a `.gitleaks.toml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any project on GitHub, published or not. A pure file drop of two read-only workflows: no hooks, no settings, no scripts, no gate. Adopt-capable and recommended for every project kind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `worktrees`      | Enforces that all src/tests development happens inside an isolated git worktree, on any branch, for any caller: a `working-in-worktrees` skill (start/status/sync/finish/fan-out), a `SessionStart` hook that installs dependencies into a freshly created worktree, a `PreToolUse` guard stricter than the baseline's own `guard-branch-isolation.mjs`/`guard-hub-src-writes.mjs`, a `repair-core-bare.mjs` hook (`SessionStart`, and `PostToolUse` after `EnterWorktree`/`ExitWorktree`/`Agent`) that resets the `core.bare = true` Claude Code's worktree tools are reported to leave in a normal repo's shared config, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow, not just a nicety — see its `adoptNotes`. |