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

package/dist/survey/survey.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * The survey aggregate: runs all four collectors against a target directory
  * and returns the combined `ProjectSurvey`. See `types.ts` for the shape
@@ -11,11 +13,11 @@ import { surveyToolchain } from "./survey-toolchain.js";
 export function surveyProject(dir) {
     const undetermined = [];
     return {
-        shape: surveyShape(dir),
+        shape: surveyShape(dir, undetermined),
         toolchain: surveyToolchain(dir, undetermined),
-        harness: surveyHarness(dir),
-        docs: surveyDocs(dir),
-        undetermined,
+        harness: surveyHarness(dir, undetermined),
+        docs: surveyDocs(dir, undetermined),
+        undetermined: [...new Set(undetermined)],
     };
 }
 //# sourceMappingURL=survey.js.map

package/dist/survey/types.d.ts

@@ -4,32 +4,56 @@
  * `ProjectSurvey`, and `conflicts.ts`/`report.ts` need to name these shapes
  * without importing a collector module just for its types.
  */
+/** The package manager, inferred from which lockfile is present -- `unknown` when none is. */
 export type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "unknown";
+/** The monorepo tooling, inferred from its marker file (or `package.json`'s `workspaces`) -- `none` when nothing is found. */
 export type MonorepoTool = "pnpm-workspaces" | "turbo" | "nx" | "lerna" | "npm-workspaces" | "none";
+/** `package.json`'s `type` field as declared -- `unspecified` when it is absent or not one of the two known values. */
 export type ModuleType = "module" | "commonjs" | "unspecified";
+/** Where source lives: a `src/` or `lib/` directory, loose source files at the root, or `unknown`. */
 export type SourceLayout = "src" | "lib" | "root" | "unknown";
+/** Where tests live: a `tests/`/`test/` directory, `*.test`/`*.spec` files next to the source, or `unknown`. */
 export type TestPlacement = "tests-dir" | "colocated" | "unknown";
+/** A Node.js version pin, and the file or field it was read from. */
 export interface NodeVersionPin {
+    /** Where the pin was found: `.node-version`, `.nvmrc`, or `package.json#engines.node`. */
     source: string;
+    /** The pin's value verbatim (trimmed), never normalized to a semver range. */
     value: string;
 }
+/** Raw `package.json` facts that hint at what kind of project this is -- evidence only, never the verdict. */
 export interface KindEvidence {
+    /** Whether `package.json` declares an `exports` field. */
     hasExportsMap: boolean;
+    /** Whether `package.json` declares a `bin` field. */
     hasBinField: boolean;
+    /** Whether `package.json` declares a `main` field. */
     hasMainField: boolean;
+    /** Well-known framework packages found among `dependencies`/`devDependencies`. */
     frameworkDeps: string[];
 }
+/** Codebase-shape facts: package manager, monorepo tooling, module system, pins, and layout. */
 export interface ShapeSurvey {
+    /** The package manager, from which lockfile is present. */
     packageManager: PackageManager;
+    /** The monorepo tool, from its marker file or `package.json`'s `workspaces`. */
     monorepoTool: MonorepoTool;
+    /** The workspace package globs the monorepo tool declares -- empty when it declares none or none were read. */
     workspaceGlobs: string[];
+    /** `package.json`'s declared module system. */
     moduleType: ModuleType;
+    /** The `typescript` version range from `devDependencies` (preferred) or `dependencies`, verbatim. */
     typescriptVersion: string | undefined;
+    /** The first Node.js version pin found, or `undefined` when there is none. */
     nodeVersionPin: NodeVersionPin | undefined;
+    /** Where the project's source files live. */
     sourceLayout: SourceLayout;
+    /** Where the project's test files live. */
     testPlacement: TestPlacement;
+    /** Evidence for what kind of project this is, left for `/customize` to interpret. */
     kindEvidence: KindEvidence;
 }
+/** The project's tsconfig `extends` chain and the strict-family flags it resolves to. */
 export interface TsconfigSurvey {
     /** The extends chain, entry file first (child before parent), as absolute paths. */
     files: string[];
@@ -38,77 +62,132 @@ export interface TsconfigSurvey {
     /** False if any file in the chain failed to parse -- see `undetermined` on the parent survey. */
     parsed: boolean;
 }
+/** The project's ESLint config file and what it references. */
 export interface EslintSurvey {
+    /** The config file found at the project root, or `undefined` when there is none. */
     configFile: string | undefined;
+    /** True for a flat config (`eslint.config.*`); false for a legacy `.eslintrc*` one or when there is no config. */
     flat: boolean;
+    /** Plugin names found in the config's source text -- scraped, never by executing it. */
     referencedPlugins: string[];
 }
 type TestRunnerTool = "vitest" | "jest" | "mocha" | "node-test" | "unknown";
+/** The project's test runner, from its config file or `test` script. */
 export interface TestRunnerSurvey {
+    /** The runner detected -- `unknown` when neither a config file nor the `test` script names one. */
     tool: TestRunnerTool;
+    /** The runner's config file, or `undefined` when none was found. */
     configFile: string | undefined;
 }
 type FormatterTool = "prettier" | "biome" | "unknown";
+/** The project's code formatter, from its config file. */
 export interface FormatterSurvey {
+    /** The formatter detected -- `unknown` when no known config file is present. */
     tool: FormatterTool;
+    /** The formatter's config file, or `undefined` when none was found. */
     configFile: string | undefined;
 }
 type GitHookManager = "lefthook" | "husky" | "simple-git-hooks" | "none";
+/** The project's git-hook manager and where its config lives. */
 export interface GitHooksSurvey {
+    /** The hook manager detected from its config file or directory -- `none` when none is found. */
     manager: GitHookManager;
+    /** The manager's config file or directory, or `undefined` when there is no manager. */
     configFile: string | undefined;
     /** True whenever the manager's config is YAML/shell-script shaped -- this module indexes it, never parses it. */
     needsReading: boolean;
 }
+/** The project's CI workflow files under `.github/workflows/`. */
 export interface WorkflowsSurvey {
+    /** Workflow file names (`.yml`/`.yaml`), relative to `.github/workflows/`. */
     files: string[];
+    /** True whenever any workflow file exists -- YAML is indexed, never parsed, so its steps need reading. */
     needsReading: boolean;
 }
+/** Every toolchain enforcement mechanism the survey found in effect. */
 export interface ToolchainSurvey {
+    /** The tsconfig `extends` chain and its effective strict-family flags. */
     tsconfig: TsconfigSurvey;
+    /** The ESLint config, if any. */
     eslint: EslintSurvey;
+    /** The test runner, if one was detected. */
     testRunner: TestRunnerSurvey;
+    /** The code formatter, if one was detected. */
     formatter: FormatterSurvey;
+    /** The git-hook manager, if one was detected. */
     gitHooks: GitHooksSurvey;
+    /** The CI workflow files, if any. */
     workflows: WorkflowsSurvey;
+    /** `package.json`'s `scripts`, name to command, verbatim (string values only). */
     scripts: Record<string, string>;
 }
+/** One agent file under `.claude/agents/`. */
 export interface HarnessAgent {
+    /** The agent's file name without its `.md` extension. */
     name: string;
+    /** The agent's frontmatter `model` field, or `undefined` when absent or empty. */
     model: string | undefined;
 }
+/** One skill directory under `.claude/skills/` that has a `SKILL.md`. */
 export interface HarnessSkill {
+    /** The skill's frontmatter `name`, falling back to its directory name. */
     name: string;
+    /** The skill's frontmatter `description`, or `undefined` when absent or empty. */
     description: string | undefined;
 }
+/** One rule file under `.claude/rules/` -- the survey's index entry, unrelated to the harness grader's rule type. */
 export interface HarnessRule {
+    /** The rule's file name without its `.md` extension. */
     name: string;
+    /** The rule's frontmatter `paths` scope as text (a list joined with commas), or `undefined` when absent or empty. */
     paths: string | undefined;
 }
+/** The project's existing Claude Code harness: its `.claude/` directory plus `CLAUDE.md`. */
 export interface HarnessSurvey {
+    /** Whether a `.claude/` directory exists at all. */
     present: boolean;
+    /** `settings.json` when `.claude/settings.json` exists, otherwise `undefined`. */
     settingsFile: string | undefined;
+    /** Every agent found under `.claude/agents/`. */
     agents: HarnessAgent[];
+    /** Every skill found under `.claude/skills/`. */
     skills: HarnessSkill[];
+    /** Hook script file names (`.mjs`/`.js`) under `.claude/hooks/`. */
     hooks: string[];
+    /** Every rule file found under `.claude/rules/`. */
     rules: HarnessRule[];
+    /** Command file names (`.md`) under `.claude/commands/`. */
     commands: string[];
+    /** Whether a `.claude/settings.local.json` exists, which may shadow shared settings. */
     hasSettingsLocal: boolean;
+    /** Whether a root `CLAUDE.md` exists -- recorded even when `.claude/` does not. */
     hasClaudeMd: boolean;
+    /** `CLAUDE.md`'s level 1-3 headings in document order -- empty when there is no `CLAUDE.md`. */
     claudeMdHeadings: string[];
 }
+/** One indexed human-facing doc: where it is and its outline, never its content. */
 export interface DocFile {
+    /** The doc's path on disk. */
     path: string;
+    /** The doc's size on disk, in bytes. */
     sizeBytes: number;
+    /** The doc's level 1-3 Markdown headings in document order. */
     headings: string[];
 }
+/** The index of human-facing docs and guidelines the survey found. */
 export interface DocsSurvey {
+    /** Every indexed doc: root README/CONTRIBUTING/style guides, then named doc directories. */
     files: DocFile[];
 }
+/** The aggregate output of all four survey collectors -- adopt mode's offline index of the project. */
 export interface ProjectSurvey {
+    /** Codebase-shape facts. */
     shape: ShapeSurvey;
+    /** Toolchain enforcement in effect. */
     toolchain: ToolchainSurvey;
+    /** The existing Claude Code harness. */
     harness: HarnessSurvey;
+    /** The human-facing docs index. */
     docs: DocsSurvey;
     /** Things the survey attempted and could not parse or classify -- never silently dropped. */
     undetermined: string[];

package/dist/survey/types.js

@@ -1,8 +1,4 @@
-/**
- * Shared type definitions for the four survey collectors and their
- * aggregate. Kept in one file since every collector's output composes into
- * `ProjectSurvey`, and `conflicts.ts`/`report.ts` need to name these shapes
- * without importing a collector module just for its types.
- */
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 export {};
 //# sourceMappingURL=types.js.map

package/dist/term.d.ts

@@ -0,0 +1,80 @@
+import { type PaletteRoleColors } from "./palette.js";
+/**
+ * A semantic color role the palette defines for both themes.
+ *
+ * @example
+ * ```ts
+ * import type { PaletteRole } from "./term.js";
+ * const role: PaletteRole = "success";
+ * ```
+ */
+export type PaletteRole = keyof PaletteRoleColors;
+/**
+ * Decides whether `stream` should receive color escapes. `NO_COLOR` (any
+ * value, even empty) disables color outright; otherwise `FORCE_COLOR` set to
+ * anything but `"0"` enables it; otherwise color follows `stream.isTTY`.
+ *
+ * @example
+ * ```ts
+ * import process from "node:process";
+ * import { supportsColor } from "./term.js";
+ * if (supportsColor(process.stdout, process.env)) {
+ *   // safe to emit escapes
+ * }
+ * ```
+ */
+export declare function supportsColor(stream: {
+    readonly isTTY?: boolean;
+}, env: NodeJS.ProcessEnv): boolean;
+/**
+ * Converts a `#rrggbb` color into a 24-bit SGR foreground escape.
+ *
+ * @throws RangeError if `hex` is not exactly `#` plus six hex digits.
+ * @example
+ * ```ts
+ * import { truecolorSgr } from "./term.js";
+ * truecolorSgr("#086d31"); // "\x1b[38;2;8;109;49m"
+ * ```
+ */
+export declare function truecolorSgr(hex: string): string;
+/**
+ * Converts a `#rrggbb` color into the SGR foreground escape of the nearest
+ * of the 16 standard ANSI colors (squared Euclidean RGB distance).
+ *
+ * @throws RangeError if `hex` is not exactly `#` plus six hex digits.
+ * @example
+ * ```ts
+ * import { nearest16Sgr } from "./term.js";
+ * nearest16Sgr("#cd0000"); // "\x1b[31m"
+ * ```
+ */
+export declare function nearest16Sgr(hex: string): string;
+/**
+ * Picks the palette theme from `COLORFGBG` (`"fg;bg"`): `"light"` when the
+ * last segment is `15` or `7` (a white/light-grey background), `"dark"`
+ * otherwise, including when the variable is absent or malformed.
+ *
+ * @example
+ * ```ts
+ * import { resolveThemeId } from "./term.js";
+ * resolveThemeId({ COLORFGBG: "0;15" }); // "light"
+ * ```
+ */
+export declare function resolveThemeId(env: NodeJS.ProcessEnv): "light" | "dark";
+/**
+ * Wraps `text` in the palette color for `role`, or returns it unchanged when
+ * {@link supportsColor} says `stream` should not receive color. Uses a 24-bit
+ * escape when `COLORTERM` is `truecolor`/`24bit`, the nearest ANSI-16 color
+ * otherwise.
+ *
+ * @example
+ * ```ts
+ * import process from "node:process";
+ * import { paint } from "./term.js";
+ * console.log(paint(process.stdout, "success", "done"));
+ * ```
+ */
+export declare function paint(stream: {
+    readonly isTTY?: boolean;
+}, role: PaletteRole, text: string, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=term.d.ts.map

package/dist/term.js

@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * Zero-dependency terminal coloring over the generated {@link PALETTE}
+ * (`./palette.ts`, built from the vendored m3l-design tokens). Every function
+ * here is pure: color support, theme and color depth are all decided from
+ * the stream and environment the caller passes in.
+ */
+import process from "node:process";
+import { PALETTE } from "./palette.js";
+const HEX_COLOR = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i;
+/** The 16 standard ANSI foreground colors, as xterm's default RGB values. */
+const ANSI_16 = [
+    { code: 30, rgb: [0, 0, 0] },
+    { code: 31, rgb: [205, 0, 0] },
+    { code: 32, rgb: [0, 205, 0] },
+    { code: 33, rgb: [205, 205, 0] },
+    { code: 34, rgb: [0, 0, 238] },
+    { code: 35, rgb: [205, 0, 205] },
+    { code: 36, rgb: [0, 205, 205] },
+    { code: 37, rgb: [229, 229, 229] },
+    { code: 90, rgb: [127, 127, 127] },
+    { code: 91, rgb: [255, 0, 0] },
+    { code: 92, rgb: [0, 255, 0] },
+    { code: 93, rgb: [255, 255, 0] },
+    { code: 94, rgb: [92, 92, 255] },
+    { code: 95, rgb: [255, 0, 255] },
+    { code: 96, rgb: [0, 255, 255] },
+    { code: 97, rgb: [255, 255, 255] },
+];
+const RESET = "\x1b[0m";
+/** Parses a strict `#rrggbb` string; throws a `RangeError` naming the value otherwise. */
+function parseHex(hex) {
+    const match = HEX_COLOR.exec(hex);
+    const [, r, g, b] = match ?? [];
+    if (r === undefined || g === undefined || b === undefined) {
+        throw new RangeError(`invalid hex color ${JSON.stringify(hex)}: expected #rrggbb`);
+    }
+    return [
+        Number.parseInt(r, 16),
+        Number.parseInt(g, 16),
+        Number.parseInt(b, 16),
+    ];
+}
+/**
+ * Decides whether `stream` should receive color escapes. `NO_COLOR` (any
+ * value, even empty) disables color outright; otherwise `FORCE_COLOR` set to
+ * anything but `"0"` enables it; otherwise color follows `stream.isTTY`.
+ *
+ * @example
+ * ```ts
+ * import process from "node:process";
+ * import { supportsColor } from "./term.js";
+ * if (supportsColor(process.stdout, process.env)) {
+ *   // safe to emit escapes
+ * }
+ * ```
+ */
+export function supportsColor(stream, env) {
+    if (env["NO_COLOR"] !== undefined)
+        return false;
+    const forceColor = env["FORCE_COLOR"];
+    if (forceColor !== undefined)
+        return forceColor !== "0";
+    return stream.isTTY === true;
+}
+/**
+ * Converts a `#rrggbb` color into a 24-bit SGR foreground escape.
+ *
+ * @throws RangeError if `hex` is not exactly `#` plus six hex digits.
+ * @example
+ * ```ts
+ * import { truecolorSgr } from "./term.js";
+ * truecolorSgr("#086d31"); // "\x1b[38;2;8;109;49m"
+ * ```
+ */
+export function truecolorSgr(hex) {
+    const [r, g, b] = parseHex(hex);
+    return `\x1b[38;2;${String(r)};${String(g)};${String(b)}m`;
+}
+/**
+ * Converts a `#rrggbb` color into the SGR foreground escape of the nearest
+ * of the 16 standard ANSI colors (squared Euclidean RGB distance).
+ *
+ * @throws RangeError if `hex` is not exactly `#` plus six hex digits.
+ * @example
+ * ```ts
+ * import { nearest16Sgr } from "./term.js";
+ * nearest16Sgr("#cd0000"); // "\x1b[31m"
+ * ```
+ */
+export function nearest16Sgr(hex) {
+    const [r, g, b] = parseHex(hex);
+    let bestCode = 30;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const { code, rgb } of ANSI_16) {
+        const distance = (r - rgb[0]) ** 2 + (g - rgb[1]) ** 2 + (b - rgb[2]) ** 2;
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            bestCode = code;
+        }
+    }
+    return `\x1b[${String(bestCode)}m`;
+}
+/**
+ * Picks the palette theme from `COLORFGBG` (`"fg;bg"`): `"light"` when the
+ * last segment is `15` or `7` (a white/light-grey background), `"dark"`
+ * otherwise, including when the variable is absent or malformed.
+ *
+ * @example
+ * ```ts
+ * import { resolveThemeId } from "./term.js";
+ * resolveThemeId({ COLORFGBG: "0;15" }); // "light"
+ * ```
+ */
+export function resolveThemeId(env) {
+    const colorfgbg = env["COLORFGBG"];
+    if (colorfgbg?.includes(";") !== true)
+        return "dark";
+    const background = colorfgbg.slice(colorfgbg.lastIndexOf(";") + 1);
+    return background === "15" || background === "7" ? "light" : "dark";
+}
+/**
+ * Wraps `text` in the palette color for `role`, or returns it unchanged when
+ * {@link supportsColor} says `stream` should not receive color. Uses a 24-bit
+ * escape when `COLORTERM` is `truecolor`/`24bit`, the nearest ANSI-16 color
+ * otherwise.
+ *
+ * @example
+ * ```ts
+ * import process from "node:process";
+ * import { paint } from "./term.js";
+ * console.log(paint(process.stdout, "success", "done"));
+ * ```
+ */
+export function paint(stream, role, text, env = process.env) {
+    if (!supportsColor(stream, env))
+        return text;
+    const hex = PALETTE[resolveThemeId(env)][role];
+    const colorterm = env["COLORTERM"];
+    const truecolor = colorterm === "truecolor" || colorterm === "24bit";
+    const sgr = truecolor ? truecolorSgr(hex) : nearest16Sgr(hex);
+    return `${sgr}${text}${RESET}`;
+}
+//# sourceMappingURL=term.js.map

package/dist/tokens.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Replaces every `__KEY__` occurrence in `content` with `tokens[KEY]`, for
  * every key in `tokens`. Unmatched `__KEY__`-shaped text that isn't a known

package/dist/toolchain/conformance.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 const TOOLCHAIN_FILES = new Set([
     "package.json",
     ".node-version",

package/dist/toolchain/grade.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Grades a project's TypeScript toolchain. `gradeToolchain` reads the tsconfig
  * chains, ESLint and vitest configs, `package.json`, and the verify-step
@@ -7,8 +9,8 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readJsoncFile, stripJsoncNoise } from "../jsonc.js";
-import { walkBounded } from "../survey/fs-walk.js";
+import { readJsoncFile, stripJsComments } from "../jsonc.js";
+import { walkBoundedForGrading } from "../survey/fs-walk.js";
 import { RULES } from "./rules.js";
 import { loadTsconfigChain } from "./tsconfig-chain.js";
 import { TOOLCHAIN_CATEGORIES } from "./types.js";
@@ -45,7 +47,7 @@ function readRaw(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;
@@ -72,21 +74,37 @@ 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?.[1] !== undefined)
             groups.push(group[1]);
         else if (step?.[1] !== undefined)
@@ -97,7 +115,7 @@ function scrapeLaneInvocations(text) {
     return { seen, groups, steps, dynamic };
 }
 function loadSnapshot(root) {
-    const entries = walkBounded(root, PROJECT_WALK_DEPTH);
+    const entries = walkBoundedForGrading(root, PROJECT_WALK_DEPTH);
     const projectFiles = new Set(entries.filter((e) => !e.isDirectory).map((e) => e.relPath));
     const rootFiles = [...projectFiles].filter((p) => !p.includes("/"));
     const packageRead = readJsoncFile(join(root, "package.json"));

package/dist/toolchain/rules.d.ts

@@ -1,10 +1,19 @@
 /**
  * The toolchain grader's rules. Each rule is a pure function over a
  * `ToolchainSnapshot` read once by `grade.ts`, so none of them touches the
- * filesystem. Structural rules catch wiring defects `tsc` and ESLint do not --
- * a build project that emits nowhere, a verify step naming a script that does
- * not exist -- and fail a gate. Rubric rules encode the floor official
- * TypeScript / typescript-eslint guidance sets and only ever warn.
+ * filesystem. Rules come in two levels.
+ *
+ * Structural rules are pass/fail wiring checks: they catch defects `tsc` and
+ * ESLint do not -- a build project that emits nowhere, a verify step naming a
+ * script that does not exist -- and fail a gate.
+ *
+ * Rubric rules are a quality-judgement checklist rather than a wiring check:
+ * each scores how closely the project follows a recommended practice, and a
+ * miss only ever warns. What they encode is the floor -- the minimum baseline
+ * of practice that current official TypeScript / typescript-eslint guidance
+ * recommends (strict-family flags on, a modern module target, type-aware
+ * linting, and so on). A project can go beyond the floor; falling below it is
+ * what a rubric rule reports.
  *
  * `eslint.config.js`, `vitest.config.ts` and `verify-steps.mjs` are executable
  * JavaScript, so their rules are regex scrapes over comment-stripped source,