@monte3l/groundwork 0.0.0

package/dist/harness/rules.js

@@ -0,0 +1,580 @@
+/**
+ * The harness rule set: a declarative list of checks, each a pure function
+ * over a `HarnessSnapshot` (everything the grader read from disk, already in
+ * memory). Rules never touch the filesystem, so they are testable without
+ * temp directories and cannot drift on I/O behaviour.
+ *
+ * Structural rules encode wiring integrity. Rubric rules encode Anthropic's
+ * published guidance (skill body at most 500 lines, a scoped tool list, a
+ * description substantial enough to trigger on) and only ever warn.
+ *
+ * `templates/core/bin/lib/harness-rules.mjs` is the emitted ESM twin of this
+ * file; `tests/harness-parity.test.ts` runs both over the real baseline and
+ * asserts identical findings, so the two cannot silently diverge.
+ */
+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.
+ */
+export const CURRENT_MODELS = [
+    "inherit",
+    "opus",
+    "sonnet",
+    "haiku",
+    "fable",
+    "claude-opus-5",
+    "claude-sonnet-5",
+    "claude-fable-5-1",
+    "claude-haiku-4-5",
+    "claude-haiku-4-5-20251001",
+];
+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\)/;
+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;
+function hookRegistrations(settings) {
+    if (!isRecord(settings) || !isRecord(settings["hooks"]))
+        return [];
+    const registrations = [];
+    for (const [event, entries] of Object.entries(settings["hooks"])) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (!isRecord(entry) || !Array.isArray(entry["hooks"]))
+                continue;
+            for (const hook of entry["hooks"]) {
+                if (!isRecord(hook) || typeof hook["command"] !== "string")
+                    continue;
+                registrations.push({
+                    event,
+                    command: hook["command"],
+                    hasTimeout: typeof hook["timeout"] === "number",
+                });
+            }
+        }
+    }
+    return registrations;
+}
+function allRegistrations(snapshot) {
+    return [
+        ...hookRegistrations(snapshot.settings.parsed),
+        ...hookRegistrations(snapshot.settingsLocal),
+    ];
+}
+/** Every string anywhere inside a parsed JSON value. */
+function collectStrings(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value)) {
+        return value.flatMap(collectStrings);
+    }
+    if (isRecord(value))
+        return Object.values(value).flatMap(collectStrings);
+    return [];
+}
+/**
+ * Hook files named by any command in settings -- `hooks` registrations and
+ * also top-level command keys such as `statusLine` -- named directly, since
+ * a wiring reference is a wiring reference wherever it sits.
+ */
+function registeredHookFiles(snapshot) {
+    const names = new Set();
+    for (const text of [
+        ...collectStrings(snapshot.settings.parsed),
+        ...collectStrings(snapshot.settingsLocal),
+    ]) {
+        for (const match of text.matchAll(HOOK_PATH)) {
+            if (match[1] !== undefined)
+                names.add(match[1]);
+        }
+    }
+    return names;
+}
+/**
+ * `registeredHookFiles` plus every hook file a reachable hook's source
+ * mentions by name -- a helper module imported by a registered script is
+ * wired in even though no settings command names it. Followed to a
+ * fixpoint, so a helper's own helpers count too.
+ */
+function reachableHookFiles(snapshot) {
+    const reachable = registeredHookFiles(snapshot);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const name of snapshot.hooks.keys()) {
+            if (reachable.has(name))
+                continue;
+            const mentioned = [...reachable].some((other) => snapshot.hooks.get(other)?.includes(name));
+            if (mentioned) {
+                reachable.add(name);
+                grew = true;
+            }
+        }
+    }
+    return reachable;
+}
+/** Translates a Claude Code `paths` glob (`**`, `*`, `?`, `{a,b}`) into a RegExp. */
+function globToRegExp(glob) {
+    const translate = (source) => {
+        let out = "";
+        for (let i = 0; i < source.length; i++) {
+            const ch = source[i] ?? "";
+            if (ch === "*") {
+                if (source[i + 1] === "*") {
+                    i++;
+                    if (source[i + 1] === "/") {
+                        i++;
+                        out += "(?:.*/)?";
+                    }
+                    else {
+                        out += ".*";
+                    }
+                }
+                else {
+                    out += "[^/]*";
+                }
+            }
+            else if (ch === "?") {
+                out += "[^/]";
+            }
+            else if (ch === "{" && source.indexOf("}", i) !== -1) {
+                const close = source.indexOf("}", i);
+                out += `(?:${source
+                    .slice(i + 1, close)
+                    .split(",")
+                    .map(translate)
+                    .join("|")})`;
+                i = close;
+            }
+            else {
+                out += ch.replace(/[.+^$()|[\]\\{}]/g, "\\$&");
+            }
+        }
+        return out;
+    };
+    return new RegExp(`^${translate(glob)}$`);
+}
+function bodyLineCount(body) {
+    return body.replace(/\n+$/, "").split("\n").length;
+}
+const settingsParses = {
+    id: "settings-parses",
+    level: "structural",
+    category: "settings",
+    check: (s) => ({
+        checked: s.settings.present ? 1 : 0,
+        failures: s.settings.error === undefined
+            ? []
+            : [
+                {
+                    subject: ".claude/settings.json",
+                    message: `does not parse: ${s.settings.error}`,
+                },
+            ],
+    }),
+};
+const hookDangling = {
+    id: "hook-dangling",
+    level: "structural",
+    category: "hooks",
+    check: (s) => {
+        if (s.settings.error !== undefined)
+            return { checked: 0, failures: [] };
+        const referenced = registeredHookFiles(s);
+        return {
+            checked: referenced.size,
+            failures: [...referenced]
+                .filter((name) => !s.hooks.has(name))
+                .map((name) => ({
+                subject: `.claude/hooks/${name}`,
+                message: "is named by a hook registration but does not exist on disk",
+            })),
+        };
+    },
+};
+const hookOrphan = {
+    id: "hook-orphan",
+    level: "structural",
+    category: "hooks",
+    check: (s) => {
+        if (s.settings.error !== undefined)
+            return { checked: 0, failures: [] };
+        const referenced = reachableHookFiles(s);
+        const hookFiles = [...s.hooks.keys()].filter((name) => name.endsWith(".mjs") || name.endsWith(".js"));
+        return {
+            checked: hookFiles.length,
+            failures: hookFiles
+                .filter((name) => !referenced.has(name))
+                .map((name) => ({
+                subject: `.claude/hooks/${name}`,
+                message: "exists but nothing runs it -- no settings.json command names it and no registered hook imports it",
+            })),
+        };
+    },
+};
+const hookEntrypoint = {
+    id: "hook-entrypoint",
+    level: "structural",
+    category: "hooks",
+    check: (s) => {
+        const sources = [...s.hooks].filter(([, source]) => source.includes("process.argv[1]"));
+        return {
+            checked: sources.length,
+            failures: sources
+                .filter(([, source]) => BARE_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",
+            })),
+        };
+    },
+};
+const skillShape = {
+    id: "skill-shape",
+    level: "structural",
+    category: "skills",
+    check: (s) => {
+        const failures = [];
+        for (const skill of s.skills) {
+            const subject = `.claude/skills/${skill.name}`;
+            if (skill.skillMd === undefined) {
+                failures.push({ subject, message: "has no SKILL.md" });
+                continue;
+            }
+            const parsed = parseFrontmatter(skill.skillMd);
+            if (!parsed.ok) {
+                failures.push({ subject, message: `SKILL.md: ${parsed.error}` });
+                continue;
+            }
+            for (const problem of parsed.problems) {
+                failures.push({ subject, message: `SKILL.md: ${problem}` });
+            }
+            // `name` is optional for a skill (it defaults to the directory), so
+            // only a name that is present and different is a wiring defect.
+            const name = fieldText(parsed.fields, "name");
+            if (name !== undefined && name !== "" && name !== skill.name) {
+                failures.push({
+                    subject,
+                    message: `SKILL.md \`name\` is "${name}" but the directory is "${skill.name}"`,
+                });
+            }
+        }
+        return { checked: s.skills.length, failures };
+    },
+};
+const agentShape = {
+    id: "agent-shape",
+    level: "structural",
+    category: "agents",
+    check: (s) => {
+        const failures = [];
+        for (const [file, text] of s.agents) {
+            const subject = `.claude/agents/${file}`;
+            const parsed = parseFrontmatter(text);
+            if (!parsed.ok) {
+                failures.push({ subject, message: parsed.error });
+                continue;
+            }
+            for (const problem of parsed.problems) {
+                failures.push({ subject, message: problem });
+            }
+            const expected = file.replace(/\.md$/, "");
+            const name = fieldText(parsed.fields, "name");
+            if (name === undefined || name === "") {
+                failures.push({ subject, message: "has no `name`" });
+            }
+            else if (name !== expected) {
+                failures.push({
+                    subject,
+                    message: `\`name\` is "${name}" but the file is "${file}"`,
+                });
+            }
+            const description = fieldText(parsed.fields, "description");
+            if (description === undefined || description === "") {
+                failures.push({ subject, message: "has no `description`" });
+            }
+        }
+        return { checked: s.agents.size, failures };
+    },
+};
+const ruleShape = {
+    id: "rule-shape",
+    level: "structural",
+    category: "rules",
+    check: (s) => {
+        const failures = [];
+        for (const [file, text] of s.rules) {
+            const subject = `.claude/rules/${file}`;
+            // A rule with no frontmatter at all is a legitimate unconditional rule.
+            if (!text.startsWith("---"))
+                continue;
+            const parsed = parseFrontmatter(text);
+            if (!parsed.ok) {
+                failures.push({ subject, message: parsed.error });
+                continue;
+            }
+            for (const problem of parsed.problems) {
+                failures.push({ subject, message: problem });
+            }
+            const paths = fieldList(parsed.fields, "paths");
+            if (paths !== undefined && paths.length === 0) {
+                failures.push({ subject, message: "declares `paths` but it is empty" });
+            }
+        }
+        return { checked: s.rules.size, failures };
+    },
+};
+const claudeMdRefs = {
+    id: "claudemd-refs",
+    level: "structural",
+    category: "claude-md",
+    check: (s) => {
+        if (s.claudeMd === undefined)
+            return { checked: 0, failures: [] };
+        const failures = [];
+        const refs = new Set();
+        for (const match of s.claudeMd.matchAll(CLAUDE_PATH)) {
+            const path = match[0].replace(/[.,;:]+$/, "").replace(/\/+$/, "");
+            if (path.includes("*") || path === ".claude/settings.local.json")
+                continue;
+            if (path === ".claude")
+                continue;
+            refs.add(path);
+        }
+        for (const path of refs) {
+            if (!s.claudeTree.has(path)) {
+                failures.push({
+                    subject: "CLAUDE.md",
+                    message: `names ${path}, which does not exist`,
+                });
+            }
+        }
+        for (const file of s.rules.keys()) {
+            if (!s.claudeMd.includes(`.claude/rules/${file}`)) {
+                failures.push({
+                    subject: `.claude/rules/${file}`,
+                    message: "exists but CLAUDE.md never names it",
+                });
+            }
+        }
+        return { checked: refs.size + s.rules.size, failures };
+    },
+};
+const skillBodySize = {
+    id: "skill-body-size",
+    level: "rubric",
+    category: "skills",
+    check: (s) => {
+        const failures = [];
+        let checked = 0;
+        for (const skill of s.skills) {
+            if (skill.skillMd === undefined)
+                continue;
+            const parsed = parseFrontmatter(skill.skillMd);
+            if (!parsed.ok)
+                continue;
+            checked++;
+            const lines = bodyLineCount(parsed.body);
+            if (lines > SKILL_BODY_LINE_LIMIT) {
+                failures.push({
+                    subject: `.claude/skills/${skill.name}`,
+                    message: `SKILL.md body is ${lines} lines; Anthropic's guidance is <= ${SKILL_BODY_LINE_LIMIT} -- move detail into references/`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+const descriptionSubstance = {
+    id: "description-substance",
+    level: "rubric",
+    category: "skills",
+    check: (s) => {
+        const failures = [];
+        let checked = 0;
+        const examine = (subject, text, required) => {
+            const parsed = parseFrontmatter(text);
+            if (!parsed.ok)
+                return;
+            const description = fieldText(parsed.fields, "description");
+            if (description === undefined || description === "") {
+                // Agents require one and shape-check it; a skill may omit it (Claude
+                // falls back to the first paragraph), which is a quality gap.
+                if (required)
+                    return;
+                checked++;
+                failures.push({
+                    subject,
+                    message: "has no `description`, so Claude has nothing to match the skill against but its first paragraph",
+                });
+                return;
+            }
+            checked++;
+            if (description.length < DESCRIPTION_MIN) {
+                failures.push({
+                    subject,
+                    message: `description is ${description.length} chars -- too thin to trigger on reliably (>= ${DESCRIPTION_MIN})`,
+                });
+            }
+            else if (description.length > DESCRIPTION_MAX) {
+                failures.push({
+                    subject,
+                    message: `description is ${description.length} chars; over ${DESCRIPTION_MAX} it is truncated in the skill listing`,
+                });
+            }
+        };
+        for (const skill of s.skills) {
+            if (skill.skillMd !== undefined) {
+                examine(`.claude/skills/${skill.name}`, skill.skillMd, false);
+            }
+        }
+        for (const [file, text] of s.agents) {
+            examine(`.claude/agents/${file}`, text, true);
+        }
+        return { checked, failures };
+    },
+};
+const modelPinCurrency = {
+    id: "model-pin-currency",
+    level: "rubric",
+    category: "agents",
+    check: (s) => {
+        const failures = [];
+        let checked = 0;
+        for (const [file, text] of s.agents) {
+            const parsed = parseFrontmatter(text);
+            if (!parsed.ok)
+                continue;
+            checked++;
+            const model = fieldText(parsed.fields, "model");
+            const subject = `.claude/agents/${file}`;
+            if (model === undefined || model === "") {
+                failures.push({
+                    subject,
+                    message: "pins no `model`, so it inherits whatever the session runs",
+                });
+            }
+            else if (!CURRENT_MODELS.includes(model)) {
+                failures.push({
+                    subject,
+                    message: `\`model: ${model}\` is not a known-current model id or alias`,
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+const agentToolScope = {
+    id: "agent-tool-scope",
+    level: "rubric",
+    category: "agents",
+    check: (s) => {
+        const failures = [];
+        let checked = 0;
+        for (const [file, text] of s.agents) {
+            const parsed = parseFrontmatter(text);
+            if (!parsed.ok)
+                continue;
+            checked++;
+            if (fieldText(parsed.fields, "tools") === undefined) {
+                failures.push({
+                    subject: `.claude/agents/${file}`,
+                    message: "declares no `tools`, so it inherits every tool",
+                });
+            }
+        }
+        return { checked, failures };
+    },
+};
+const hookTimeout = {
+    id: "hook-timeout",
+    level: "rubric",
+    category: "hooks",
+    check: (s) => {
+        const registrations = allRegistrations(s);
+        return {
+            checked: registrations.length,
+            failures: registrations
+                .filter((registration) => !registration.hasTimeout)
+                .map((registration) => ({
+                subject: `${registration.event} hook`,
+                message: `\`${registration.command}\` has no \`timeout\``,
+            })),
+        };
+    },
+};
+const ruleGlobsLive = {
+    id: "rule-globs-live",
+    level: "rubric",
+    category: "rules",
+    check: (s) => {
+        const failures = [];
+        let checked = 0;
+        for (const [file, text] of s.rules) {
+            const parsed = parseFrontmatter(text);
+            if (!parsed.ok)
+                continue;
+            for (const glob of fieldList(parsed.fields, "paths") ?? []) {
+                checked++;
+                const pattern = globToRegExp(glob);
+                if (!s.projectFiles.some((path) => pattern.test(path))) {
+                    failures.push({
+                        subject: `.claude/rules/${file}`,
+                        message: `\`paths\` glob "${glob}" matches no file in the project, so the rule never loads`,
+                    });
+                }
+            }
+        }
+        return { checked, failures };
+    },
+};
+const skillReferencesResolve = {
+    id: "skill-references-resolve",
+    level: "rubric",
+    category: "skills",
+    check: (s) => {
+        const failures = [];
+        let checked = 0;
+        for (const skill of s.skills) {
+            if (skill.skillMd === undefined)
+                continue;
+            const referenced = new Set([...skill.skillMd.matchAll(REFERENCE_PATH)].map((match) => match[0]));
+            for (const path of referenced) {
+                checked++;
+                if (!skill.files.includes(path)) {
+                    failures.push({
+                        subject: `.claude/skills/${skill.name}`,
+                        message: `SKILL.md points at ${path}, which does not exist`,
+                    });
+                }
+            }
+        }
+        return { checked, failures };
+    },
+};
+/** Every rule, structural first. Order is the order findings are reported in. */
+export const RULES = [
+    settingsParses,
+    hookDangling,
+    hookOrphan,
+    hookEntrypoint,
+    skillShape,
+    agentShape,
+    ruleShape,
+    claudeMdRefs,
+    skillBodySize,
+    descriptionSubstance,
+    modelPinCurrency,
+    agentToolScope,
+    hookTimeout,
+    ruleGlobsLive,
+    skillReferencesResolve,
+];
+//# sourceMappingURL=rules.js.map

package/dist/harness/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shapes shared by the harness grader. `structural` findings are defects in
+ * the harness's own wiring (a hook that points at nothing, a skill with no
+ * frontmatter) and fail a gate; `rubric` findings are quality judgements
+ * distilled from Anthropic's published guidance and only ever warn -- a
+ * subjective rule must never block a push.
+ */
+export type RuleLevel = "structural" | "rubric";
+export type HarnessCategory = "settings" | "hooks" | "skills" | "agents" | "rules" | "claude-md";
+export declare const HARNESS_CATEGORIES: readonly HarnessCategory[];
+export interface HarnessFinding {
+    ruleId: string;
+    level: RuleLevel;
+    category: HarnessCategory;
+    /** The file, skill, agent, or registration the finding is about. */
+    subject: string;
+    message: string;
+}
+/** How many subjects a set of rules examined, and how many of those failed. */
+export interface CheckTally {
+    checked: number;
+    failed: number;
+}
+export interface HarnessGrade {
+    findings: HarnessFinding[];
+    structural: CheckTally;
+    /** Rubric tallies per category -- the absolute-quality measurement. */
+    rubric: Record<HarnessCategory, CheckTally>;
+    /** `1 - failed/checked` over every rubric check; `1` when nothing was checked. */
+    rubricScore: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/harness/types.js

@@ -0,0 +1,9 @@
+export const HARNESS_CATEGORIES = [
+    "settings",
+    "hooks",
+    "skills",
+    "agents",
+    "rules",
+    "claude-md",
+];
+//# sourceMappingURL=types.js.map

package/dist/inventory.d.ts

@@ -0,0 +1,63 @@
+import type { CapCounts } from "./caps.js";
+import type { FileConflict } from "./conflicts.js";
+import type { HarnessConformance } from "./harness/conformance.js";
+import type { HarnessGrade } from "./harness/types.js";
+import type { ModeDetection } from "./mode.js";
+import type { PackWiring } from "./packs.js";
+import type { ProjectSurvey } from "./survey/survey.js";
+import type { ToolchainConformance } from "./toolchain/conformance.js";
+import type { ToolchainGrade } from "./toolchain/types.js";
+export declare const INVENTORY_SCHEMA_VERSION = 4;
+export interface PackSurvey {
+    name: string;
+    modes: string[];
+    budget: CapCounts;
+    /** File collisions a pack's `files/` tree would have against the target -- the same shape `conflicts` uses for `templates/core`. */
+    fileConflicts: FileConflict[];
+    /** The pack's declared wiring, verbatim and unapplied -- adopt mode never applies it. */
+    wiring: PackWiring;
+    /** Index-level facts about how the wiring would land, never a verdict. */
+    wiringObservations: string[];
+    adoptNotes: string | undefined;
+}
+export interface Inventory {
+    schemaVersion: number;
+    cliVersion: string;
+    generatedAt: string;
+    modeSignal: string;
+    templateRoot: string;
+    targetDir: string;
+    survey: ProjectSurvey;
+    conflicts: FileConflict[];
+    packs: PackSurvey[];
+    /** Wiring integrity and rubric quality of the project's existing harness. Absent when schemaVersion is below 3. */
+    harnessGrade: HarnessGrade;
+    /** How far the existing harness has drifted from the baseline's -- information, never a defect. Absent when schemaVersion is below 3. */
+    harnessConformance: HarnessConformance;
+    /** Wiring integrity and rubric quality of the project's TypeScript toolchain. Absent when schemaVersion is below 4. */
+    toolchainGrade: ToolchainGrade;
+    /** How far the project's toolchain files have drifted from the baseline's -- information, never a defect. Absent when schemaVersion is below 4. */
+    toolchainConformance: ToolchainConformance;
+}
+/**
+ * Resolves this CLI package's own declared version. `packageJsonPath`
+ * defaults to this module's own `package.json` -- overridable so callers
+ * (and tests) can exercise the missing-file/unparseable/non-string-version
+ * fallbacks without needing a broken real package.json on disk.
+ */
+export declare function resolveCliVersion(packageJsonPath?: string): string;
+export interface BuildInventoryParams {
+    detection: ModeDetection;
+    templateRoot: string;
+    targetDir: string;
+    survey: ProjectSurvey;
+    conflicts: FileConflict[];
+    packs: PackSurvey[];
+    harnessGrade: HarnessGrade;
+    toolchainGrade: ToolchainGrade;
+}
+/** Builds the inventory object. Does not write anything -- see `writeInventory`. */
+export declare function buildInventory(params: BuildInventoryParams): Inventory;
+/** Writes `inventory.json` into `groundworkDir`, creating it if needed. */
+export declare function writeInventory(inventory: Inventory, groundworkDir: string): string;
+//# sourceMappingURL=inventory.d.ts.map