vigiles 2.0.0 → 2.1.1

package/dist/cli.js

@@ -15,17 +15,21 @@ const node_path_1 = require("node:path");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./generate-types.js");
 const validate_js_1 = require("./validate.js");
+const types_js_1 = require("./types.js");
 const compile_js_1 = require("./compile.js");
 const proofs_js_1 = require("./proofs.js");
 const inline_js_1 = require("./inline.js");
+const frontmatter_js_1 = require("./frontmatter.js");
+const generate_schema_js_1 = require("./generate-schema.js");
 const linters_js_1 = require("./linters.js");
-const freshness_js_1 = require("./freshness.js");
+const integrity_js_1 = require("./integrity.js");
+const coverage_js_1 = require("./coverage.js");
+const orphans_js_1 = require("./orphans.js");
+const doc_refs_js_1 = require("./doc-refs.js");
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const IGNORE_NODE_MODULES = ["node_modules/**"];
-// Config is loaded from .vigilesrc.json via validate.ts::loadConfig().
-// All settings (validation, compilation, freshness) are in one place.
 // ---------------------------------------------------------------------------
 // Spec loading
 // ---------------------------------------------------------------------------
@@ -110,7 +114,7 @@ async function compile(specPaths, config) {
         }
         const basePath = process.cwd();
         if (spec._specType === "claude") {
-            const { markdown: rawMarkdown, errors, linterResults, targets, } = (0, compile_js_1.compileClaude)(spec, {
+            const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
                 basePath,
                 specFile: specPath,
                 maxRules: config.maxRules,
@@ -119,13 +123,6 @@ async function compile(specPaths, config) {
                 catalogOnly: config.catalogOnly,
                 linters: config.linters,
             });
-            // Embed input hash for freshness tracking
-            let markdown = rawMarkdown;
-            if (config.freshnessMode === "input-hash") {
-                const inputs = (0, freshness_js_1.discoverInputs)(specPath, spec, basePath, config.freshnessInputs);
-                const inputHash = (0, freshness_js_1.computeInputHash)(inputs.files, basePath);
-                markdown = (0, freshness_js_1.addInputHash)(rawMarkdown, inputHash);
-            }
             const linterCount = linterResults.filter((r) => r.exists).length;
             const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
             if (errors.length === 0) {
@@ -343,17 +340,7 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
         const ruleCount = Object.keys(rules).length;
         if (ruleCount < 2)
             continue;
-        // Guard against unknown rule kinds (legacy "check" artifacts, JS
-        // callers) that would crash ruleToText inside findSimilarRules.
-        // Same pattern as the try/catch in runProofSuite.
-        let pairs;
-        try {
-            pairs = (0, proofs_js_1.findSimilarRules)(rules, threshold);
-        }
-        catch (e) {
-            log(`  ⚠ ${specPath}: similarity check failed (${e instanceof Error ? e.message : String(e)})`);
-            continue;
-        }
+        const pairs = (0, proofs_js_1.findSimilarRules)(rules, threshold);
         if (pairs.length === 0)
             continue;
         if (specsWithDuplicates === 0) {
@@ -381,19 +368,44 @@ function auditExitCode(report) {
     if (report.hashErrors > 0 ||
         report.validationErrors > 0 ||
         report.inlineErrors > 0 ||
-        report.freshnessErrors > 0)
+        report.frontmatterErrors > 0 ||
+        report.integrityErrors > 0 ||
+        report.coverageErrors > 0)
         return 2;
-    if (report.duplicatePairs > 0)
+    if (report.duplicatePairs > 0 ||
+        report.orphanCount > 0 ||
+        report.docRefErrors > 0)
         return 1;
-    // Coverage gaps and guidance counts are informational, not failures
+    // Guidance counts are informational, not failures
     return 0;
 }
 /**
- * Verify inline `<!-- vigiles:enforce ... -->` comments in an instruction
- * file. Each comment's linter rule goes through the same verification as
- * spec-declared enforce rules (existence, enabled status, closest-match
- * suggestions on typo).
+ * Verify one parsed enforce rule against the linter catalog/config, logging
+ * and annotating on failure. Returns true when the rule is valid+enabled.
  */
+function verifyOneRule(rule, filePath, silent, linterOptions) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    const result = (0, linters_js_1.checkLinterRule)(rule.linterRule, process.cwd(), linterOptions);
+    if (!result.exists) {
+        const message = result.error ?? `Rule "${rule.linterRule}" not found`;
+        log(`  ✗ line ${String(rule.line)}: ${message}`);
+        if (!silent)
+            ghAnnotate("error", message, filePath, rule.line);
+        return false;
+    }
+    if (result.enabled === "disabled") {
+        const message = `Rule "${rule.linterRule}" exists but is disabled in ${result.linter} config`;
+        log(`  ✗ line ${String(rule.line)}: ${message}`);
+        if (!silent)
+            ghAnnotate("error", message, filePath, rule.line);
+        return false;
+    }
+    log(`  ✓ line ${String(rule.line)}: ${rule.linterRule}`);
+    return true;
+}
 function verifyInlineRules(filePath, silent, linterOptions) {
     const log = (msg) => {
         if (!silent)
@@ -404,11 +416,11 @@ function verifyInlineRules(filePath, silent, linterOptions) {
         content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), filePath), "utf-8");
     }
     catch {
-        return { ok: true, errorCount: 0, ruleCount: 0 };
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
     }
     const { rules, errors: parseErrors } = (0, inline_js_1.parseInlineRules)(content);
     if (rules.length === 0 && parseErrors.length === 0) {
-        return { ok: true, errorCount: 0, ruleCount: 0 };
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
     }
     let errorCount = 0;
     log(`\n${filePath} (inline mode):`);
@@ -420,28 +432,113 @@ function verifyInlineRules(filePath, silent, linterOptions) {
         }
     }
     for (const rule of rules) {
-        const result = (0, linters_js_1.checkLinterRule)(rule.linterRule, process.cwd(), linterOptions);
-        if (!result.exists) {
-            const message = result.error ?? `Rule "${rule.linterRule}" not found`;
-            log(`  ✗ line ${String(rule.line)}: ${message}`);
+        if (!verifyOneRule(rule, filePath, silent, linterOptions))
             errorCount++;
-            if (!silent) {
-                ghAnnotate("error", message, filePath, rule.line);
-            }
+    }
+    return {
+        ok: errorCount === 0,
+        errorCount,
+        ruleCount: rules.length,
+        ruleNames: rules.map((r) => r.linterRule),
+    };
+}
+/**
+ * Verify `vigiles.enforce` rules declared in a file's YAML frontmatter.
+ * Same engine as inline/spec rules. Rules whose reference already appeared
+ * in `exclude` (e.g. declared inline in the same file) are skipped so a
+ * rule present in both sources is reported once, not twice.
+ */
+function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), filePath), "utf-8");
+    }
+    catch {
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
+    }
+    const { rules: allRules, errors: parseErrors } = (0, frontmatter_js_1.parseFrontmatterRules)(content);
+    const rules = allRules.filter((r) => !exclude.has(r.linterRule));
+    if (rules.length === 0 && parseErrors.length === 0) {
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
+    }
+    let errorCount = 0;
+    log(`\n${filePath} (frontmatter mode):`);
+    for (const err of parseErrors) {
+        log(`  ✗ line ${String(err.line)}: ${err.message}`);
+        errorCount++;
+        if (!silent) {
+            ghAnnotate("error", err.message, filePath, err.line);
         }
-        else if (result.enabled === "disabled") {
-            const message = `Rule "${rule.linterRule}" exists but is disabled in ${result.linter} config`;
-            log(`  ✗ line ${String(rule.line)}: ${message}`);
+    }
+    for (const rule of rules) {
+        if (!verifyOneRule(rule, filePath, silent, linterOptions))
             errorCount++;
-            if (!silent) {
-                ghAnnotate("error", message, filePath, rule.line);
-            }
+    }
+    return {
+        ok: errorCount === 0,
+        errorCount,
+        ruleCount: rules.length,
+        ruleNames: rules.map((r) => r.linterRule),
+    };
+}
+/**
+ * Verify inline `<!-- vigiles:enforce -->` comments and `vigiles:` YAML
+ * frontmatter in instruction files that aren't managed by a spec.
+ *
+ * Spec mode is the source of truth when it exists, so a literal
+ * `<!-- vigiles:enforce ... -->` snippet that survived into compiled
+ * markdown (or an example in a spec-managed file) must not trip audit. A
+ * file is spec-managed iff it has a sibling `<file>.spec.ts` OR its own
+ * `<!-- vigiles:sha256:... compiled from <spec> -->` header. A rule
+ * declared both inline and in frontmatter is verified once (inline wins as
+ * the first source). See docs/markdown-mode.md.
+ */
+function verifyMarkdownModeRules(files, silent, config) {
+    const totals = {
+        inlineErrors: 0,
+        inlineRules: 0,
+        frontmatterErrors: 0,
+        frontmatterRules: 0,
+    };
+    if (!silent && files.length > 0) {
+        console.log("\nInline + frontmatter rule verification:");
+    }
+    const linterOptions = {
+        catalogOnly: config?.catalogOnly,
+        linters: config?.linters,
+    };
+    const compiledFromRe = /<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from .+?\s*-->/;
+    for (const filePath of files) {
+        const abs = (0, node_path_1.resolve)(process.cwd(), filePath);
+        if ((0, node_fs_1.existsSync)(`${abs}.spec.ts`))
+            continue; // managed by sibling spec
+        let content;
+        try {
+            content = (0, node_fs_1.readFileSync)(abs, "utf-8");
         }
-        else {
-            log(`  ✓ line ${String(rule.line)}: ${rule.linterRule}`);
+        catch {
+            continue;
         }
-    }
-    return { ok: errorCount === 0, errorCount, ruleCount: rules.length };
+        if (compiledFromRe.test(content))
+            continue; // managed via hash header
+        const inline = verifyInlineRules(filePath, silent, linterOptions);
+        totals.inlineErrors += inline.errorCount;
+        totals.inlineRules += inline.ruleCount;
+        const fm = verifyFrontmatterRules(filePath, silent, new Set(inline.ruleNames), linterOptions);
+        totals.frontmatterErrors += fm.errorCount;
+        totals.frontmatterRules += fm.ruleCount;
+    }
+    if (!silent &&
+        files.length > 0 &&
+        totals.inlineRules === 0 &&
+        totals.frontmatterRules === 0) {
+        console.log("  (no inline vigiles:enforce comments or vigiles: frontmatter found)");
+    }
+    return totals;
 }
 /**
  * Unified audit command: verify hashes, report coverage gaps, detect duplicates,
@@ -468,45 +565,10 @@ async function audit(restArgs, flags, config) {
     const hashResult = files.length > 0
         ? check(files, silent)
         : { valid: true, hashErrors: 0, validationErrors: 0 };
-    // 1b. Verify inline vigiles:enforce comments in any instruction file
-    // that isn't already managed by a .spec.ts. Spec mode is the source of
-    // truth when it exists, so a literal `<!-- vigiles:enforce ... -->`
-    // snippet that survived into the compiled markdown (or an
-    // explanatory example in a spec-managed file) must not trip audit.
-    // A file is spec-managed iff it has a sibling `<file>.spec.ts` OR its
-    // own `<!-- vigiles:sha256:... compiled from <spec> -->` header.
-    // See docs/inline-mode.md.
-    let inlineErrors = 0;
-    let inlineRules = 0;
-    if (!silent && files.length > 0) {
-        console.log("\nInline rule verification:");
-    }
-    const compiledFromRe = /<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from .+?\s*-->/;
-    for (const filePath of files) {
-        const abs = (0, node_path_1.resolve)(process.cwd(), filePath);
-        if ((0, node_fs_1.existsSync)(`${abs}.spec.ts`)) {
-            continue; // managed by sibling spec
-        }
-        let content;
-        try {
-            content = (0, node_fs_1.readFileSync)(abs, "utf-8");
-        }
-        catch {
-            continue;
-        }
-        if (compiledFromRe.test(content)) {
-            continue; // managed by the spec referenced in the hash header
-        }
-        const result = verifyInlineRules(filePath, silent, {
-            catalogOnly: config?.catalogOnly,
-            linters: config?.linters,
-        });
-        inlineErrors += result.errorCount;
-        inlineRules += result.ruleCount;
-    }
-    if (!silent && files.length > 0 && inlineRules === 0) {
-        console.log("  (no inline vigiles:enforce comments found)");
-    }
+    // 1b. Verify inline + frontmatter rules in instruction files not managed
+    // by a spec. See verifyMarkdownModeRules / docs/markdown-mode.md.
+    const md = verifyMarkdownModeRules(files, silent, config);
+    const { inlineErrors, inlineRules, frontmatterErrors, frontmatterRules } = md;
     // 2. Coverage gaps (discover)
     if (!silent)
         console.log("\nLinter rule coverage:\n");
@@ -519,25 +581,60 @@ async function audit(restArgs, flags, config) {
     const dups = await findDuplicateRules(0.3, silent, restArgs.length > 0 ? files : undefined);
     // 4. Guidance rule count (strengthen suggestions moved to /strengthen skill)
     const guidanceCount = await countGuidanceRules(silent);
-    // 5. Freshness check
-    const freshnessSeverity = config?.rules.freshness;
-    let freshnessErrors = 0;
-    if (freshnessSeverity) {
+    // 5. Integrity check (hand-edit detection via SHA-256 hash)
+    const integritySeverity = config?.rules.integrity ?? "warn";
+    let integrityErrors = 0;
+    if (integritySeverity) {
         if (!silent)
-            console.log("\nFreshness check:\n");
-        const mode = config?.freshnessMode ?? "strict";
-        freshnessErrors = await checkFreshness(files, mode, config, freshnessSeverity, silent);
+            console.log("\nIntegrity check:\n");
+        integrityErrors = checkIntegrityForFiles(files, integritySeverity, silent);
+    }
+    // 6. Coverage thresholds (gates CI when severity is "error")
+    const coverageErrors = await checkCoverageThresholds(coverage, config, silent);
+    // 7. Orphan docs check — find .md files no other markdown references.
+    // Enforces the `vigiles/orphan-docs` built-in rule when declared in a
+    // spec. Include/exclude come from .vigilesrc.json#orphans (tsconfig-
+    // style globs); default include is docs/ + research/ for the
+    // vigiles-repo convention.
+    if (!silent)
+        console.log("\nOrphan docs check:\n");
+    const orphanReport = (0, orphans_js_1.findOrphanDocs)({
+        basePath: process.cwd(),
+        include: config?.orphans?.include,
+        exclude: config?.orphans?.exclude,
+    });
+    if (!silent) {
+        for (const line of (0, orphans_js_1.formatOrphanReport)(orphanReport).split("\n")) {
+            console.log(`  ${line}`);
+        }
+    }
+    // 8. Validate vigiles builder calls inside markdown code blocks. Default
+    // is to validate every ref; illustrative blocks opt out via
+    // `<!-- vigiles:ignore -->` (single block) or
+    // `<!-- vigiles:ignore-file -->` (whole file). Same engine as spec.ts.
+    if (!silent)
+        console.log("\nMarkdown code block refs:\n");
+    const docRefReport = (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd() });
+    if (!silent) {
+        for (const line of (0, doc_refs_js_1.formatDocRefReport)(docRefReport).split("\n")) {
+            console.log(`  ${line}`);
+        }
     }
     const report = {
         hashErrors: hashResult.hashErrors,
         validationErrors: hashResult.validationErrors,
         inlineErrors,
         inlineRules,
+        frontmatterErrors,
+        frontmatterRules,
         duplicatePairs: dups.pairCount,
         coverageEnabled: coverage.enabled,
         coverageDocumented: coverage.documented,
         strengthenSuggestions: guidanceCount,
-        freshnessErrors,
+        integrityErrors,
+        coverageErrors,
+        orphanCount: orphanReport.orphans.length,
+        docRefErrors: docRefReport.errors.length,
         files,
     };
     if (summary) {
@@ -557,15 +654,21 @@ function printAuditSummary(report) {
         parts.push(`${String(report.validationErrors)} validation errors`);
     if (report.inlineErrors > 0)
         parts.push(`${String(report.inlineErrors)} inline errors`);
+    if (report.frontmatterErrors > 0)
+        parts.push(`${String(report.frontmatterErrors)} frontmatter errors`);
     if (report.duplicatePairs > 0)
         parts.push(`${String(report.duplicatePairs)} duplicates`);
+    if (report.orphanCount > 0)
+        parts.push(`${String(report.orphanCount)} orphan docs`);
+    if (report.docRefErrors > 0)
+        parts.push(`${String(report.docRefErrors)} broken doc refs`);
     const undocumented = report.coverageEnabled - report.coverageDocumented;
     if (undocumented > 0)
         parts.push(`${String(undocumented)} undocumented rules`);
     if (report.strengthenSuggestions > 0)
         parts.push(`${String(report.strengthenSuggestions)} guidance (run /strengthen to upgrade)`);
-    if (report.freshnessErrors > 0)
-        parts.push(`${String(report.freshnessErrors)} stale (run vigiles compile)`);
+    if (report.integrityErrors > 0)
+        parts.push(`${String(report.integrityErrors)} tampered (edit the .spec.ts source)`);
     if (parts.length === 0) {
         console.log("vigiles: clean");
     }
@@ -883,6 +986,15 @@ async function setup(args) {
         console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
     }
     console.log(`✓ Generated ${outPath}`);
+    // Also emit a JSON Schema so `vigiles:` markdown frontmatter (Level 1)
+    // gets rule-name autocomplete + typo squiggles from the editor's YAML LSP.
+    const schemaResult = (0, generate_schema_js_1.generateSchema)({
+        basePath: process.cwd(),
+        linters: (0, validate_js_1.loadConfig)().linters,
+    });
+    const schemaPath = ".vigiles/schema.json";
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), schemaPath), schemaResult.json);
+    console.log(`✓ Generated ${schemaPath} (point frontmatter at it with \`# yaml-language-server: $schema=./${schemaPath}\`)`);
     // Step 5: Compile specs
     console.log("\nCompiling specs...");
     const specs = findSpecs();
@@ -991,6 +1103,7 @@ async function setup(args) {
         ...targets,
         ...specPathsList,
         ".vigiles/generated.d.ts",
+        ".vigiles/schema.json",
         ...(shouldInstallPlugin ? [".claude/settings.json"] : []),
         ...(strict ? [".vigilesrc.json"] : []),
     ];
@@ -999,7 +1112,7 @@ async function setup(args) {
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
 // ---------------------------------------------------------------------------
-async function checkFreshness(files, mode, config, severity, silent) {
+function checkIntegrityForFiles(files, severity, silent) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
@@ -1010,79 +1123,66 @@ async function checkFreshness(files, mode, config, severity, silent) {
         const abs = (0, node_path_1.resolve)(basePath, filePath);
         if (!(0, node_fs_1.existsSync)(abs))
             continue;
-        const content = (0, node_fs_1.readFileSync)(abs, "utf-8");
-        // Find the spec that compiled this file
-        const hashMatch = content.match(/<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from (.+?)\s*-->/);
-        if (!hashMatch) {
-            // No hash = hand-written file, skip freshness check
-            continue;
-        }
-        let result;
-        const specFile = hashMatch[1];
-        if (mode === "strict") {
-            // Recompile in memory and diff
-            const spec = await loadSpec(specFile);
-            if (!spec || spec._specType !== "claude") {
-                log(`  ? ${filePath} — can't load spec "${specFile}", skipping`);
-                continue;
-            }
-            const compiled = (0, compile_js_1.compileClaude)(spec, {
-                basePath,
-                specFile,
-                maxRules: config?.maxRules,
-                maxTokens: config?.maxTokens,
-                maxSectionLines: config?.maxSectionLines,
-                catalogOnly: config?.catalogOnly,
-                linters: config?.linters,
-            });
-            // Compare markdown body (strip hash/input lines)
-            const metaRe = /^<!-- vigiles:(sha256|inputs):[^\n]+ -->\r?\n?/gm;
-            const existingBody = content.replace(metaRe, "").trim();
-            const compiledBody = compiled.markdown.replace(metaRe, "").trim();
-            if (existingBody === compiledBody) {
-                result = { fresh: true, mode: "strict" };
-            }
-            else {
-                result = {
-                    fresh: false,
-                    mode: "strict",
-                    reason: "Output would differ if recompiled — run `vigiles compile`",
-                };
-            }
-        }
-        else if (mode === "input-hash") {
-            const specFile = hashMatch[1];
-            const spec = await loadSpec(specFile);
-            if (!spec || spec._specType !== "claude") {
-                log(`  ? ${filePath} — can't load spec "${specFile}", skipping`);
-                continue;
-            }
-            const inputs = (0, freshness_js_1.discoverInputs)(specFile, spec, basePath, config?.freshnessInputs);
-            result = (0, freshness_js_1.checkInputHashFreshness)(content, inputs.files, basePath);
-        }
-        else {
-            // output-hash mode
-            result = (0, freshness_js_1.checkOutputHashFreshness)(content);
-        }
-        if (!result.fresh) {
+        const result = (0, integrity_js_1.checkIntegrity)((0, node_fs_1.readFileSync)(abs, "utf-8"));
+        if (!result.intact) {
             errorCount++;
             const marker = severity === "error" ? "✗" : "⚠";
-            log(`  ${marker} ${filePath} — ${result.reason ?? "stale"}`);
-            if (result.changedFiles && result.changedFiles.length > 0) {
-                for (const f of result.changedFiles) {
-                    log(`    changed: ${f}`);
-                }
-            }
+            log(`  ${marker} ${filePath} — ${result.reason ?? "tampered"}`);
         }
         else if (!silent) {
-            log(`  ✓ ${filePath} — fresh (${mode})`);
+            log(`  ✓ ${filePath}`);
         }
     }
     if (errorCount === 0) {
-        log("  All files fresh.");
+        log("  All compiled files intact.");
     }
     return severity === "error" ? errorCount : 0;
 }
+/**
+ * Apply the configured coverage thresholds. Returns the number of failing
+ * thresholds (so the audit can fail CI when severity is "error").
+ *
+ * Loads specs directly via loadSpec() when the scripts threshold is set —
+ * avoids depending on a pre-built `dist/` tree, which the setup-generated
+ * CI step doesn't guarantee.
+ */
+async function checkCoverageThresholds(coverage, config, silent) {
+    const severity = (0, types_js_1.ruleSeverity)(config?.rules.coverage);
+    if (!severity)
+        return 0;
+    const opts = (0, types_js_1.ruleOptions)(config?.rules.coverage);
+    if (!opts)
+        return 0;
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    let failing = 0;
+    if (!silent)
+        console.log("\nCoverage thresholds:\n");
+    if (opts.linterRules !== undefined) {
+        const pct = coverage.enabled > 0
+            ? Math.round((coverage.documented / coverage.enabled) * 100)
+            : 100;
+        const ok = pct >= opts.linterRules;
+        if (!ok)
+            failing++;
+        const marker = ok ? "✓" : severity === "error" ? "✗" : "⚠";
+        log(`  ${marker} linterRules: ${String(pct)}% (threshold: ${String(opts.linterRules)}%)`);
+    }
+    if (opts.scripts !== undefined) {
+        // Load all claude specs so coverage doesn't depend on a built dist/.
+        const loaded = await Promise.all(findSpecs().map(loadSpec));
+        const claudeSpecs = loaded.filter((s) => s?._specType === "claude");
+        const metric = (0, coverage_js_1.computeScriptCoverage)(process.cwd(), opts.scripts, claudeSpecs);
+        const ok = metric.passing;
+        if (!ok)
+            failing++;
+        const marker = ok ? "✓" : severity === "error" ? "✗" : "⚠";
+        log(`  ${marker} scripts: ${String(metric.percent)}% (threshold: ${String(opts.scripts)}%)`);
+    }
+    return severity === "error" ? failing : 0;
+}
 async function countGuidanceRules(silent = false) {
     const specs = findSpecs();
     if (specs.length === 0)
@@ -1165,6 +1265,43 @@ function handleGenerateTypes(args, restArgs) {
     (0, node_fs_1.writeFileSync)(fullOut, result.dts);
     console.log(`\n✓ Generated ${outPath}`);
 }
+function handleGenerateSchema(args, restArgs) {
+    const checkOnly = args.includes("--check");
+    const outPath = restArgs[0] ?? ".vigiles/schema.json";
+    console.log("Scanning linters...\n");
+    const result = (0, generate_schema_js_1.generateSchema)({
+        basePath: process.cwd(),
+        linters: (0, validate_js_1.loadConfig)().linters,
+    });
+    for (const l of result.linters) {
+        console.log(`  ${l.linter}: ${String(l.count)} rules`);
+    }
+    console.log(`  schema enum: ${String(result.ruleNames.length)} rule names`);
+    const fullOut = (0, node_path_1.resolve)(process.cwd(), outPath);
+    if (checkOnly) {
+        if (!(0, node_fs_1.existsSync)(fullOut)) {
+            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate-schema\` to create it.`);
+            process.exit(1);
+        }
+        const existing = (0, node_fs_1.readFileSync)(fullOut, "utf-8");
+        if (existing.trim() === result.json.trim()) {
+            console.log(`\n✓ ${outPath} is up to date`);
+        }
+        else {
+            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate-schema\` to update.`);
+            process.exit(1);
+        }
+        return;
+    }
+    const outDir = fullOut.substring(0, fullOut.lastIndexOf("/"));
+    if (outDir && !(0, node_fs_1.existsSync)(outDir)) {
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    }
+    (0, node_fs_1.writeFileSync)(fullOut, result.json);
+    console.log(`\n✓ Generated ${outPath}`);
+    console.log("  Add to your markdown frontmatter:\n" +
+        `    # yaml-language-server: $schema=./${outPath}`);
+}
 function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
@@ -1181,6 +1318,8 @@ function printUsage(command) {
     console.log("Plumbing:");
     console.log("  vigiles generate-types [out]  Emit .d.ts from project state");
     console.log("  vigiles generate-types --check  Verify .d.ts is up to date");
+    console.log("  vigiles generate-schema [out] Emit JSON Schema for vigiles: frontmatter");
+    console.log("  vigiles generate-schema --check Verify schema.json is up to date");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
         process.exit(1);
@@ -1258,6 +1397,9 @@ async function main() {
         case "generate-types":
             handleGenerateTypes(args, restArgs);
             break;
+        case "generate-schema":
+            handleGenerateSchema(args, restArgs);
+            break;
         default:
             printUsage(command);
             break;

package/dist/compile.d.ts

@@ -28,6 +28,7 @@ export interface CompileError {
     message: string;
     path?: string;
 }
+export declare function readPackageScripts(basePath: string): Record<string, string> | null;
 export interface CompileClaudeResult {
     markdown: string;
     errors: CompileError[];