continuous-improvement 3.0.0 → 3.8.0

package/bin/check-everything-mirror.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Everything Mirror Check
+ *
+ * Verifies that every non-skill, non-manifest file under
+ * plugins/continuous-improvement/ has a byte-identical sibling at the same
+ * relative path under the repo root. Catches drift across commands/, hooks/
+ * (excluding the plugin-only hooks.json), instinct-packs/, templates/, lib/,
+ * bin/, and the LICENSE file — surfaces that check-skill-mirror.mjs does not
+ * cover.
+ *
+ * Skills are intentionally excluded because their flat-vs-plugin layout is
+ * structurally different (skills/<name>.md vs plugins/.../skills/<name>/SKILL.md)
+ * and check-skill-mirror.mjs already enforces that pair. A few plugin-only
+ * surfaces are explicitly allowlisted: the .claude-plugin/ manifests, the
+ * generated bundle README.md and skills/README.md, and hooks/hooks.json.
+ *
+ * Usage:
+ *   node bin/check-everything-mirror.mjs              # Check the current repo
+ *   node bin/check-everything-mirror.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every mirrored file matches its flat-tree sibling
+ *   1 — at least one drift detected (missing flat sibling or content mismatch)
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const PLUGIN_ROOT_REL = "plugins/continuous-improvement";
+// Paths under PLUGIN_ROOT_REL that are intentionally plugin-only (no flat
+// sibling expected) or are covered by another lint. Stored with forward
+// slashes; matched against the file's relative-to-plugin-root path normalized
+// the same way.
+const EXCLUDE_FILES = new Set([
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+    "README.md",
+    "hooks/hooks.json",
+    "skills/README.md",
+]);
+// Whole directories under PLUGIN_ROOT_REL that this lint never walks into.
+const EXCLUDE_DIRS = new Set(["skills", ".claude-plugin"]);
+function toForward(p) {
+    return p.split(sep).join("/");
+}
+export function discoverMirrorPairs(repoRoot) {
+    const pluginRoot = join(repoRoot, PLUGIN_ROOT_REL);
+    const out = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const full = join(dir, name);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            const relFromPlugin = toForward(relative(pluginRoot, full));
+            if (stat.isDirectory()) {
+                if (EXCLUDE_DIRS.has(relFromPlugin))
+                    continue;
+                walk(full);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            if (EXCLUDE_FILES.has(relFromPlugin))
+                continue;
+            out.push({
+                relPath: relFromPlugin,
+                pluginPath: full,
+                flatPath: join(repoRoot, relFromPlugin),
+            });
+        }
+    }
+    walk(pluginRoot);
+    return out.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+export function checkMirrorPairs(repoRoot) {
+    const pairs = discoverMirrorPairs(repoRoot);
+    const drifts = [];
+    for (const pair of pairs) {
+        let flatContent;
+        try {
+            flatContent = readFileSync(pair.flatPath);
+        }
+        catch {
+            drifts.push({
+                relPath: pair.relPath,
+                reason: "missing-flat",
+                pluginPath: pair.pluginPath,
+                flatPath: pair.flatPath,
+            });
+            continue;
+        }
+        const pluginContent = readFileSync(pair.pluginPath);
+        if (!pluginContent.equals(flatContent)) {
+            drifts.push({
+                relPath: pair.relPath,
+                reason: "content-drift",
+                pluginPath: pair.pluginPath,
+                flatPath: pair.flatPath,
+                pluginBytes: pluginContent.length,
+                flatBytes: flatContent.length,
+            });
+        }
+    }
+    return drifts;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const pairs = discoverMirrorPairs(repoRoot);
+    const drifts = checkMirrorPairs(repoRoot);
+    if (drifts.length === 0) {
+        console.log(`OK everything-mirror: all ${pairs.length} mirrored file(s) match their flat-tree sibling.`);
+        exit(0);
+    }
+    console.error(`FAIL everything-mirror: ${drifts.length} drift(s) detected across ${pairs.length} mirrored file(s).\n`);
+    for (const d of drifts) {
+        if (d.reason === "missing-flat") {
+            console.error(`  - ${d.relPath}: plugin copy exists but flat sibling is missing.`);
+            console.error(`      plugin: ${d.pluginPath}`);
+            console.error(`      flat:   ${d.flatPath} (NOT FOUND)`);
+        }
+        else {
+            console.error(`  - ${d.relPath}: byte drift between plugin and flat copy (${d.pluginBytes} vs ${d.flatBytes} bytes).`);
+            console.error(`      plugin: ${d.pluginPath}`);
+            console.error(`      flat:   ${d.flatPath}`);
+        }
+    }
+    console.error("\nFix: every change to a mirrored file under plugins/continuous-improvement/ must be applied to its flat-tree sibling at the same relative path in the same PR. Plugin-only files (.claude-plugin/manifests, hooks/hooks.json, the bundle README.md, skills/README.md) are allowlisted; skills are covered by check-skill-mirror.mjs.");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-everything-mirror.mjs")) {
+    main();
+}

package/bin/check-routing-targets.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Routing-Target Invariant Check
+ *
+ * Verifies that every routing target named in the orchestrator skill at
+ * skills/proceed-with-the-recommendation.md § "Routing Table (with Inline
+ * Fallbacks)" either:
+ *   (a) ships bundled at plugins/continuous-improvement/skills/<name>/SKILL.md, or
+ *   (b) is declared in the root-level optional-companions.json file.
+ *
+ * Catches: a routing-table row that names a skill the bundle does not ship and
+ * the maintainer has not declared as an optional companion. Without this gate,
+ * such drift only surfaces at runtime when the orchestrator routes to a target
+ * that resolves to neither a bundled skill nor an inline fallback the
+ * maintainer was tracking.
+ *
+ * Usage:
+ *   node bin/check-routing-targets.mjs              # Check the current repo
+ *   node bin/check-routing-targets.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every routing target is accounted for (bundled or optional-declared)
+ *   1 — at least one routing target is unaccounted for
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const ORCHESTRATOR_SKILL_PATH = "skills/proceed-with-the-recommendation.md";
+const OPTIONAL_COMPANIONS_PATH = "optional-companions.json";
+const PLUGIN_SKILLS_DIR = "plugins/continuous-improvement/skills";
+const SECTION_HEADER = "### Routing Table (with Inline Fallbacks)";
+export function discoverBundledSkills(repoRoot) {
+    const dir = join(repoRoot, PLUGIN_SKILLS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return new Set();
+    }
+    const names = new Set();
+    for (const name of entries) {
+        const skillFile = join(dir, name, "SKILL.md");
+        try {
+            const stat = statSync(skillFile);
+            if (stat.isFile())
+                names.add(name);
+        }
+        catch {
+            /* not a skill dir */
+        }
+    }
+    return names;
+}
+export function loadOptionalCompanions(repoRoot) {
+    const path = join(repoRoot, OPTIONAL_COMPANIONS_PATH);
+    const raw = readFileSync(path, "utf8");
+    const data = JSON.parse(raw);
+    if (!Array.isArray(data.optional_companions)) {
+        throw new Error(`${OPTIONAL_COMPANIONS_PATH}: missing or non-array "optional_companions" field`);
+    }
+    return new Set(data.optional_companions);
+}
+export function extractRoutingTargets(orchestratorMarkdown) {
+    const lines = orchestratorMarkdown.split(/\r?\n/);
+    const headerIdx = lines.findIndex((line) => line.trim() === SECTION_HEADER);
+    if (headerIdx === -1) {
+        throw new Error(`Routing-table section header not found: "${SECTION_HEADER}"`);
+    }
+    const targets = [];
+    let inTable = false;
+    let sawHeaderRow = false;
+    let sawDividerRow = false;
+    for (let i = headerIdx + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed.startsWith("## ") || trimmed.startsWith("### "))
+            break;
+        if (!trimmed.startsWith("|")) {
+            if (inTable)
+                break;
+            continue;
+        }
+        if (!sawHeaderRow) {
+            sawHeaderRow = true;
+            inTable = true;
+            continue;
+        }
+        if (!sawDividerRow) {
+            sawDividerRow = true;
+            continue;
+        }
+        const cells = trimmed.split("|").map((c) => c.trim());
+        // cells[0] and cells[last] are empty strings from leading/trailing pipes.
+        // cells[1] = "Recommendation type", cells[2] = "Preferred skill", cells[3] = "Inline fallback".
+        const preferredCell = cells[2] ?? "";
+        const tokens = [...preferredCell.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+        for (const token of tokens) {
+            targets.push({
+                rowIndex: targets.length,
+                recommendationType: cells[1] ?? "",
+                target: token,
+            });
+        }
+    }
+    return targets;
+}
+export function checkRoutingTargets(repoRoot) {
+    const orchestratorPath = join(repoRoot, ORCHESTRATOR_SKILL_PATH);
+    const orchestratorContent = readFileSync(orchestratorPath, "utf8");
+    const targets = extractRoutingTargets(orchestratorContent);
+    const bundled = discoverBundledSkills(repoRoot);
+    const optional = loadOptionalCompanions(repoRoot);
+    const drifts = [];
+    for (const t of targets) {
+        if (bundled.has(t.target))
+            continue;
+        if (optional.has(t.target))
+            continue;
+        drifts.push(t);
+    }
+    return {
+        targets,
+        drifts,
+        bundledCount: bundled.size,
+        optionalCount: optional.size,
+    };
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const { targets, drifts, bundledCount, optionalCount } = checkRoutingTargets(repoRoot);
+    if (drifts.length === 0) {
+        console.log(`OK routing-targets: all ${targets.length} routing target(s) accounted for ` +
+            `(${bundledCount} bundled skill(s), ${optionalCount} optional companion(s) declared).`);
+        exit(0);
+    }
+    console.error(`FAIL routing-targets: ${drifts.length} unaccounted target(s) in ${ORCHESTRATOR_SKILL_PATH}.\n`);
+    for (const d of drifts) {
+        console.error(`  - "${d.target}" — referenced by row "${d.recommendationType}"`);
+        console.error(`      Not bundled at ${PLUGIN_SKILLS_DIR}/${d.target}/SKILL.md`);
+        console.error(`      Not declared in ${OPTIONAL_COMPANIONS_PATH}`);
+    }
+    console.error(`\nFix: either bundle the skill (add plugins/continuous-improvement/skills/<name>/SKILL.md ` +
+        `via the source skill + 'npm run build'), OR declare it in ${OPTIONAL_COMPANIONS_PATH} ` +
+        `with a pointer note in docs/audits/.`);
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-routing-targets.mjs")) {
+    main();
+}

package/bin/check-skill-law-tag.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Skill Law-Tag Check
+ *
+ * Verifies that every source skill in skills/<name>.md announces — in its
+ * YAML frontmatter `description:` — which of the 7 Laws of AI Agent
+ * Discipline it enforces. The brand-alignment audit (PR #43) made the Law
+ * tag the first clause of every skill description so the discipline shows
+ * up every time the skill is loaded; this lint guards against silent
+ * regression of that work.
+ *
+ * Recognized Law tags (case-insensitive):
+ *   "Law 1" through "Law 7"
+ *   "all 7 Laws"          (used by the orchestrator skill)
+ *   "Law activator"       (used by skills that route to other Law-aligned skills)
+ *
+ * The core skill (root SKILL.md, `tier: core`) is exempt — it IS the 7 Laws
+ * spec, not a Law-aligned skill that enforces one. Every other skill must
+ * carry a tag.
+ *
+ * Usage:
+ *   node bin/check-skill-law-tag.mjs              # Check the current repo
+ *   node bin/check-skill-law-tag.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every non-core source skill carries a recognized Law tag
+ *   1 — at least one skill has a description with no recognized Law tag
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+import { normalizeTier, parseSkillFrontmatter } from "../lib/skill-tiers.mjs";
+const SKILLS_DIR = "skills";
+const CORE_SKILL_FILE = "SKILL.md";
+const CORE_SKILL_NAME = "continuous-improvement";
+const LAW_TAG_PATTERNS = [
+    /\bLaw\s*[1-7]\b/i,
+    /\ball\s+7\s+Laws\b/i,
+    /\bLaw\s+activator\b/i,
+];
+export function descriptionHasLawTag(description) {
+    if (!description)
+        return false;
+    return LAW_TAG_PATTERNS.some((p) => p.test(description));
+}
+export function discoverSkillSources(repoRoot) {
+    // Mirrors check-skill-tiers' discovery — the core SKILL.md is included so
+    // the caller can decide whether to exempt it. This lint exempts it.
+    const out = [];
+    const corePath = join(repoRoot, CORE_SKILL_FILE);
+    try {
+        statSync(corePath);
+        out.push({ name: CORE_SKILL_NAME, path: corePath });
+    }
+    catch {
+        // No root SKILL.md — misconfigured repo, but skill-mirror lint covers it.
+    }
+    const skillsDir = join(repoRoot, SKILLS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(skillsDir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".md"))
+            continue;
+        if (entry === "README.md")
+            continue;
+        const fullPath = join(skillsDir, entry);
+        try {
+            const stat = statSync(fullPath);
+            if (!stat.isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push({ name: entry.replace(/\.md$/, ""), path: fullPath });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function checkSkillLawTags(repoRoot) {
+    const sources = discoverSkillSources(repoRoot);
+    const problems = [];
+    for (const src of sources) {
+        const content = readFileSync(src.path, "utf8");
+        const front = parseSkillFrontmatter(content);
+        // Exempt the core skill — it IS the 7 Laws spec itself.
+        if (normalizeTier(front.tier) === "core")
+            continue;
+        const description = (front.description ?? "").toString();
+        if (!descriptionHasLawTag(description)) {
+            problems.push({
+                name: src.name,
+                path: src.path,
+                description,
+            });
+        }
+    }
+    return problems;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const sources = discoverSkillSources(repoRoot);
+    const problems = checkSkillLawTags(repoRoot);
+    const checked = sources.length; // includes core, even though we exempt it from problems
+    if (problems.length === 0) {
+        console.log(`OK skill-law-tag: every non-core source skill carries a recognized Law tag (out of ${checked} source(s) discovered).`);
+        exit(0);
+    }
+    console.error(`FAIL skill-law-tag: ${problems.length} skill(s) with no recognized Law tag in their description.\n`);
+    for (const p of problems) {
+        console.error(`  - ${p.name}`);
+        console.error(`      file: ${p.path}`);
+        console.error(`      description: ${p.description.slice(0, 160)}${p.description.length > 160 ? "..." : ""}`);
+    }
+    console.error("\nFix: edit the skill's YAML frontmatter `description:` so it announces which of the 7 Laws it enforces.\n" +
+        "Recognized tags (case-insensitive): \"Law 1\"–\"Law 7\", \"all 7 Laws\" (orchestrator), \"Law activator\" (dispatcher).\n" +
+        "Lead with the tag in the first clause — the brand should fire every time the skill is loaded.\n" +
+        "Example: \"Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. <existing description>\"");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-skill-law-tag.mjs")) {
+    main();
+}

package/bin/check-skill-mirror.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * Skill Mirror Check
+ *
+ * Verifies that every skill exists as both a plugin copy
+ * (plugins/continuous-improvement/skills/<name>/SKILL.md) and a standalone
+ * copy (skills/<name>.md, or root SKILL.md for the core continuous-improvement
+ * skill), and that the two copies are byte-identical.
+ *
+ * Enforces the "Skill mirror rule" from CONTRIBUTING.md so the curl-install
+ * path and the plugin-bundle path produce the same skill content.
+ *
+ * Usage:
+ *   node bin/check-skill-mirror.mjs              # Check the current repo
+ *   node bin/check-skill-mirror.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every pair matches
+ *   1 — at least one drift detected (missing standalone or content mismatch)
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const PLUGIN_SKILLS_DIR = "plugins/continuous-improvement/skills";
+const CORE_SKILL_NAME = "continuous-improvement";
+export function discoverPairs(repoRoot) {
+    const pluginDir = join(repoRoot, PLUGIN_SKILLS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(pluginDir);
+    }
+    catch {
+        return [];
+    }
+    const pairs = [];
+    for (const name of entries) {
+        const skillDir = join(pluginDir, name);
+        let stat;
+        try {
+            stat = statSync(skillDir);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const skillFile = join(skillDir, "SKILL.md");
+        try {
+            statSync(skillFile);
+        }
+        catch {
+            continue;
+        }
+        const standalonePath = name === CORE_SKILL_NAME
+            ? join(repoRoot, "SKILL.md")
+            : join(repoRoot, "skills", `${name}.md`);
+        pairs.push({ name, pluginPath: skillFile, standalonePath });
+    }
+    return pairs.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function checkPairs(repoRoot) {
+    const pairs = discoverPairs(repoRoot);
+    const drifts = [];
+    for (const pair of pairs) {
+        let standaloneContent;
+        try {
+            standaloneContent = readFileSync(pair.standalonePath, "utf8");
+        }
+        catch {
+            drifts.push({
+                name: pair.name,
+                reason: "missing-standalone",
+                pluginPath: pair.pluginPath,
+                standalonePath: pair.standalonePath,
+            });
+            continue;
+        }
+        const pluginContent = readFileSync(pair.pluginPath, "utf8");
+        if (pluginContent !== standaloneContent) {
+            drifts.push({
+                name: pair.name,
+                reason: "content-drift",
+                pluginPath: pair.pluginPath,
+                standalonePath: pair.standalonePath,
+                pluginLines: pluginContent.split("\n").length,
+                standaloneLines: standaloneContent.split("\n").length,
+            });
+        }
+    }
+    return drifts;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const pairs = discoverPairs(repoRoot);
+    const drifts = checkPairs(repoRoot);
+    if (drifts.length === 0) {
+        console.log(`OK skill-mirror: all ${pairs.length} skill pair(s) match between plugin and standalone copies.`);
+        exit(0);
+    }
+    console.error(`FAIL skill-mirror: ${drifts.length} drift(s) detected across ${pairs.length} skill pair(s).\n`);
+    for (const d of drifts) {
+        if (d.reason === "missing-standalone") {
+            console.error(`  - ${d.name}: plugin copy exists but standalone copy is missing.`);
+            console.error(`      plugin:     ${d.pluginPath}`);
+            console.error(`      standalone: ${d.standalonePath} (NOT FOUND)`);
+        }
+        else {
+            console.error(`  - ${d.name}: content drift between plugin and standalone copy (${d.pluginLines} vs ${d.standaloneLines} lines).`);
+            console.error(`      plugin:     ${d.pluginPath}`);
+            console.error(`      standalone: ${d.standalonePath}`);
+        }
+    }
+    console.error("\nFix per CONTRIBUTING.md \"Skill mirror rule\": every change to a skill must be applied to both the plugin copy and the standalone copy in the same PR. The two distribution paths (curl-install and plugin-bundle) must produce identical content.");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-skill-mirror.mjs")) {
+    main();
+}

package/bin/check-skill-tiers.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Skill Tier Check
+ *
+ * Verifies that every source skill in skills/<name>.md (and the core
+ * SKILL.md at the repo root) declares a recognized `tier:` value in its
+ * YAML frontmatter. The generator groups skills into the bundled README
+ * by tier; an untagged skill silently slides into the "Other skills"
+ * bucket, which is easy to miss in review. This lint surfaces missing or
+ * unrecognized tiers as a hard failure.
+ *
+ * Recognized tier values (see src/lib/skill-tiers.mts):
+ *   "core" "featured" "1" "2" "companion"
+ *
+ * Usage:
+ *   node bin/check-skill-tiers.mjs              # Check the current repo
+ *   node bin/check-skill-tiers.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every source skill declares a recognized tier
+ *   1 — at least one skill is missing or has an unrecognized tier
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+import { normalizeTier, parseSkillFrontmatter, } from "../lib/skill-tiers.mjs";
+const SKILLS_DIR = "skills";
+const CORE_SKILL_FILE = "SKILL.md";
+const CORE_SKILL_NAME = "continuous-improvement";
+export function discoverSkillSources(repoRoot) {
+    const out = [];
+    // Core skill (root SKILL.md) is always present and represents the
+    // continuous-improvement framework itself; treat it as a checked source.
+    const corePath = join(repoRoot, CORE_SKILL_FILE);
+    try {
+        statSync(corePath);
+        out.push({ name: CORE_SKILL_NAME, path: corePath });
+    }
+    catch {
+        // No root SKILL.md — this is a misconfigured repo, but the lint should
+        // not error here; the skill-mirror lint covers that case.
+    }
+    const skillsDir = join(repoRoot, SKILLS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(skillsDir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".md"))
+            continue;
+        if (entry === "README.md")
+            continue;
+        const fullPath = join(skillsDir, entry);
+        try {
+            const stat = statSync(fullPath);
+            if (!stat.isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push({ name: entry.replace(/\.md$/, ""), path: fullPath });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function checkSkillTiers(repoRoot) {
+    const sources = discoverSkillSources(repoRoot);
+    const problems = [];
+    for (const src of sources) {
+        const content = readFileSync(src.path, "utf8");
+        const front = parseSkillFrontmatter(content);
+        const rawTier = front.tier;
+        if (!rawTier || rawTier.trim() === "") {
+            problems.push({ name: src.name, path: src.path, reason: "missing" });
+            continue;
+        }
+        const normalized = normalizeTier(rawTier);
+        if (normalized === "unknown") {
+            problems.push({
+                name: src.name,
+                path: src.path,
+                reason: "unrecognized",
+                rawTier,
+            });
+        }
+    }
+    return problems;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const sources = discoverSkillSources(repoRoot);
+    const problems = checkSkillTiers(repoRoot);
+    if (problems.length === 0) {
+        console.log(`OK skill-tiers: all ${sources.length} skill source(s) declare a recognized tier.`);
+        exit(0);
+    }
+    console.error(`FAIL skill-tiers: ${problems.length} skill(s) with missing or unrecognized tier (out of ${sources.length} source(s)).\n`);
+    for (const p of problems) {
+        if (p.reason === "missing") {
+            console.error(`  - ${p.name}: no \`tier:\` field in frontmatter`);
+        }
+        else {
+            console.error(`  - ${p.name}: \`tier: ${p.rawTier ?? ""}\` is not a recognized value`);
+        }
+        console.error(`      file: ${p.path}`);
+    }
+    console.error("\nFix: add a `tier:` field to the source skill's YAML frontmatter. Recognized values: core, featured, \"1\", \"2\", companion. The generator uses this to group skills into the bundled README by tier; an untagged skill slides into the catch-all 'Other skills' bucket and is easy to miss in review.");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-skill-tiers.mjs")) {
+    main();
+}