continuous-improvement 3.1.0 → 3.9.1

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();
+}

package/bin/check-third-party-shape.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * Third-Party Snapshot Shape Invariant
+ *
+ * Verifies that every `third-party/<name>/` snapshot directory conforms to the
+ * vendor playbook documented in `third-party/README.md`. For each snapshot
+ * directory the check asserts:
+ *
+ *   1. `OUR_NOTES.md` exists and is non-empty
+ *   2. `LICENSE` exists
+ *   3. `third-party/MANIFEST.md` has at least one `### <heading>` block whose
+ *      `Local path` row points at this snapshot directory
+ *   4. The matching MANIFEST entry has a `Pinned SHA` row containing a
+ *      40-char lowercase hex string wrapped in backticks
+ *
+ * The mapping between snapshot directory and MANIFEST heading is NOT identity
+ * (e.g. dir `superpowers` <-> heading `obra/superpowers`). The check looks up
+ * by `Local path`, not by name.
+ *
+ * Usage:
+ *   node bin/check-third-party-shape.mjs              # check the current repo
+ *   node bin/check-third-party-shape.mjs <repo-root>  # check a specific repo root
+ *
+ * Exit codes:
+ *   0 - every snapshot is shape-compliant
+ *   1 - at least one drift found
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const THIRD_PARTY_DIR = "third-party";
+const MANIFEST_FILENAME = "MANIFEST.md";
+const OUR_NOTES_FILENAME = "OUR_NOTES.md";
+const LICENSE_FILENAME = "LICENSE";
+const SHA_RE = /^[0-9a-f]{40}$/;
+export function discoverSnapshots(repoRoot) {
+    const dir = join(repoRoot, THIRD_PARTY_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const snapshots = [];
+    for (const name of entries) {
+        const full = join(dir, name);
+        let entryStat;
+        try {
+            entryStat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!entryStat.isDirectory())
+            continue;
+        snapshots.push({
+            name,
+            hasOurNotes: hasNonEmptyFile(join(full, OUR_NOTES_FILENAME)),
+            hasLicense: fileExists(join(full, LICENSE_FILENAME)),
+        });
+    }
+    return snapshots;
+}
+function fileExists(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function hasNonEmptyFile(path) {
+    try {
+        const s = statSync(path);
+        return s.isFile() && s.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseManifestEntries(manifestText) {
+    const lines = manifestText.split(/\r?\n/);
+    const entries = [];
+    let current = null;
+    const flush = () => {
+        if (current && current.localPath !== null)
+            entries.push(current);
+        current = null;
+    };
+    for (const line of lines) {
+        const headingMatch = line.match(/^###\s+(.+?)\s*$/);
+        if (headingMatch) {
+            flush();
+            current = { heading: headingMatch[1], pinnedSha: null, localPath: null };
+            continue;
+        }
+        if (line.match(/^##\s+/) || line.match(/^#\s+/)) {
+            flush();
+            continue;
+        }
+        if (!current)
+            continue;
+        const shaRow = line.match(/^\|\s*Pinned SHA\s*\|\s*`?([0-9a-fA-F]+)`?\s*\|/);
+        if (shaRow) {
+            current.pinnedSha = shaRow[1].toLowerCase();
+            continue;
+        }
+        const pathRow = line.match(/^\|\s*Local path\s*\|\s*`?([^`|]+?)`?\s*\|/);
+        if (pathRow) {
+            current.localPath = pathRow[1].trim();
+            continue;
+        }
+    }
+    flush();
+    return entries;
+}
+function normalizeLocalPath(p) {
+    let out = p.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (out.startsWith("./"))
+        out = out.slice(2);
+    return out;
+}
+export function checkThirdPartyShape(repoRoot) {
+    const snapshots = discoverSnapshots(repoRoot);
+    const manifestPath = join(repoRoot, THIRD_PARTY_DIR, MANIFEST_FILENAME);
+    let manifestText = "";
+    try {
+        manifestText = readFileSync(manifestPath, "utf8");
+    }
+    catch {
+        /* no manifest at all - every snapshot will fail no-manifest-entry */
+    }
+    const entries = parseManifestEntries(manifestText);
+    const entryByLocalPath = new Map();
+    for (const e of entries) {
+        if (e.localPath)
+            entryByLocalPath.set(normalizeLocalPath(e.localPath), e);
+    }
+    const drifts = [];
+    for (const snap of snapshots) {
+        if (!snap.hasOurNotes) {
+            drifts.push({
+                kind: "missing-our-notes",
+                snapshot: snap.name,
+                detail: `expected non-empty ${OUR_NOTES_FILENAME} at ${THIRD_PARTY_DIR}/${snap.name}/`,
+            });
+        }
+        if (!snap.hasLicense) {
+            drifts.push({
+                kind: "missing-license",
+                snapshot: snap.name,
+                detail: `expected ${LICENSE_FILENAME} at ${THIRD_PARTY_DIR}/${snap.name}/`,
+            });
+        }
+        const expectedPath = `${THIRD_PARTY_DIR}/${snap.name}`;
+        const entry = entryByLocalPath.get(expectedPath);
+        if (!entry) {
+            drifts.push({
+                kind: "no-manifest-entry",
+                snapshot: snap.name,
+                detail: `no MANIFEST.md ### block has Local path \`${expectedPath}/\``,
+            });
+            continue;
+        }
+        if (!entry.pinnedSha || !SHA_RE.test(entry.pinnedSha)) {
+            drifts.push({
+                kind: "invalid-sha",
+                snapshot: snap.name,
+                detail: `MANIFEST entry "${entry.heading}" has Pinned SHA "${entry.pinnedSha ?? "(none)"}" - expected 40-char lowercase hex`,
+            });
+        }
+    }
+    return {
+        drifts,
+        snapshotCount: snapshots.length,
+        manifestEntryCount: entries.length,
+    };
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const { drifts, snapshotCount, manifestEntryCount } = checkThirdPartyShape(repoRoot);
+    if (drifts.length === 0) {
+        console.log(`OK third-party-shape: all ${snapshotCount} snapshot(s) compliant ` +
+            `(${manifestEntryCount} MANIFEST entr${manifestEntryCount === 1 ? "y" : "ies"} with Local path).`);
+        exit(0);
+    }
+    console.error(`FAIL third-party-shape: ${drifts.length} drift(s) across ${snapshotCount} snapshot(s).\n`);
+    for (const d of drifts) {
+        console.error(`  - [${d.kind}] ${d.snapshot}`);
+        if (d.detail)
+            console.error(`      ${d.detail}`);
+    }
+    console.error(`\nFix: see third-party/README.md "Layout" + third-party/MANIFEST.md ` +
+        `existing entries for the playbook shape (OUR_NOTES.md, LICENSE, ` +
+        `### <heading> block with Pinned SHA + Local path rows).`);
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-third-party-shape.mjs")) {
+    main();
+}