vigiles 2.1.1 → 2.3.0

package/dist/cli.js

@@ -21,7 +21,13 @@ 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 compile_generator_js_1 = require("./compile-generator.js");
+const action_gate_js_1 = require("./action-gate.js");
+const refs_js_1 = require("./refs.js");
+const skill_runtime_js_1 = require("./skill-runtime.js");
 const linters_js_1 = require("./linters.js");
+const harness_test_js_1 = require("./harness-test.js");
+const run_scripts_js_1 = require("./run-scripts.js");
 const integrity_js_1 = require("./integrity.js");
 const coverage_js_1 = require("./coverage.js");
 const orphans_js_1 = require("./orphans.js");
@@ -102,9 +108,84 @@ function printErrors(specFile, errors) {
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
+/** Compile a generator-skill spec from source → SKILL.md. Returns validity. */
+function compileGeneratorSkillToFile(specPath, source) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_generator_js_1.compileGeneratorSkill)(source, {
+        basePath: process.cwd(),
+        specFile: specPath,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath} (generator skill)`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    for (const e of errors)
+        console.log(`  ${e.type}: ${e.message}`);
+    return false;
+}
+/** Compile a ClaudeSpec → its primary + any additional targets. */
+function compileClaudeToFile(spec, specPath, config) {
+    const basePath = process.cwd();
+    const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
+        basePath,
+        specFile: specPath,
+        maxRules: config.maxRules,
+        maxTokens: config.maxTokens,
+        maxSectionLines: config.maxSectionLines,
+        catalogOnly: config.catalogOnly,
+        linters: config.linters,
+    });
+    const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
+    if (errors.length > 0) {
+        console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+        printErrors(specPath, errors);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+        return false;
+    }
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+    const outputNames = [primaryOutput];
+    for (const t of targets.slice(1)) {
+        const body = markdown
+            .replace(/^<!-- vigiles:[^\n]+\n\n?/, "")
+            .replace(/^# [^\n]+/, `# ${t}`);
+        const dir = primaryOutput.substring(0, primaryOutput.lastIndexOf("/") + 1);
+        const targetPath = dir + t;
+        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, targetPath), (0, compile_js_1.addHash)(body, specPath));
+        outputNames.push(targetPath);
+    }
+    const linterCount = linterResults.filter((r) => r.exists).length;
+    console.log(`\n✓ ${specPath} → ${outputNames.join(", ")}`);
+    console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
+    return true;
+}
+/** Compile a declarative SkillSpec → SKILL.md. */
+function compileSkillToFile(spec, specPath) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
+        basePath: process.cwd(),
+        specFile: specPath,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    printErrors(specPath, errors);
+    return false;
+}
 async function compile(specPaths, config) {
     let allValid = true;
     for (const specPath of specPaths) {
+        // Generator skills can't be executed to markdown — compile from source.
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), specPath), "utf-8");
+        if (/\bgenSkill\s*\(/.test(source)) {
+            if (!compileGeneratorSkillToFile(specPath, source))
+                allValid = false;
+            continue;
+        }
         const spec = await loadSpec(specPath);
         if (!spec) {
             console.log(`\n✗ ${specPath} — failed to load`);
@@ -112,62 +193,13 @@ async function compile(specPaths, config) {
             allValid = false;
             continue;
         }
-        const basePath = process.cwd();
         if (spec._specType === "claude") {
-            const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
-                basePath,
-                specFile: specPath,
-                maxRules: config.maxRules,
-                maxTokens: config.maxTokens,
-                maxSectionLines: config.maxSectionLines,
-                catalogOnly: config.catalogOnly,
-                linters: config.linters,
-            });
-            const linterCount = linterResults.filter((r) => r.exists).length;
-            const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
-            if (errors.length === 0) {
-                // Write primary target
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
-                const outputNames = [primaryOutput];
-                // Write additional targets with swapped heading + recomputed hash
-                for (const t of targets.slice(1)) {
-                    // Strip hash, replace heading, recompute hash
-                    const body = markdown
-                        .replace(/^<!-- vigiles:[^\n]+\n\n?/, "")
-                        .replace(/^# [^\n]+/, `# ${t}`);
-                    const additional = (0, compile_js_1.addHash)(body, specPath);
-                    const dir = primaryOutput.substring(0, primaryOutput.lastIndexOf("/") + 1);
-                    const targetPath = dir + t;
-                    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, targetPath), additional);
-                    outputNames.push(targetPath);
-                }
-                console.log(`\n✓ ${specPath} → ${outputNames.join(", ")}`);
-                console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
-            }
-            else {
-                console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
-                printErrors(specPath, errors);
+            if (!compileClaudeToFile(spec, specPath, config))
                 allValid = false;
-                // Still write the file so the user can see partial output
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
-            }
         }
         else if (spec._specType === "skill") {
-            const outputPath = specPath.replace(/\.spec\.ts$/, "");
-            const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
-                basePath,
-                specFile: specPath,
-            });
-            if (errors.length === 0) {
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, outputPath), markdown);
-                console.log(`\n✓ ${specPath} → ${outputPath}`);
-            }
-            else {
-                console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
-                printErrors(specPath, errors);
+            if (!compileSkillToFile(spec, specPath))
                 allValid = false;
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, outputPath), markdown);
-            }
         }
     }
     return allValid;
@@ -363,6 +395,44 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
     log(`\n  ${String(totalPairs)} duplicate pair(s) in ${String(specsWithDuplicates)} spec(s). Consider merging or rewording.`);
     return { valid: false, pairCount: totalPairs };
 }
+/**
+ * Verify the file-qualified symbol references (`path.ext#symbol`) in instruction
+ * files: the named file must exist and define the named symbol. The author
+ * names the file, so this is a *declared* reference — a broken one is an error.
+ * Each named file is parsed on demand; there is no project-wide index. Returns
+ * the count of broken references.
+ */
+function verifyMarkdownSymbols(files, silent) {
+    if (files.length === 0)
+        return 0;
+    const cwd = process.cwd();
+    let printedHeader = false;
+    let errors = 0;
+    for (const f of files) {
+        let markdown;
+        try {
+            markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, f), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const broken = (0, refs_js_1.verifySymbolRefs)(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, f)));
+        if (broken.length === 0)
+            continue;
+        if (!silent) {
+            if (!printedHeader) {
+                console.log("\nSymbol reference check:\n");
+                printedHeader = true;
+            }
+            for (const b of broken) {
+                console.log(`  ✗ ${f}:${String(b.line)} ${b.reason}`);
+                ghAnnotate("error", b.reason, f, b.line);
+            }
+        }
+        errors += broken.length;
+    }
+    return errors;
+}
 /** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
 function auditExitCode(report) {
     if (report.hashErrors > 0 ||
@@ -370,7 +440,8 @@ function auditExitCode(report) {
         report.inlineErrors > 0 ||
         report.frontmatterErrors > 0 ||
         report.integrityErrors > 0 ||
-        report.coverageErrors > 0)
+        report.coverageErrors > 0 ||
+        report.symbolRefErrors > 0)
         return 2;
     if (report.duplicatePairs > 0 ||
         report.orphanCount > 0 ||
@@ -406,6 +477,35 @@ function verifyOneRule(rule, filePath, silent, linterOptions) {
     log(`  ✓ line ${String(rule.line)}: ${rule.linterRule}`);
     return true;
 }
+/**
+ * Verify the `vigiles:file` / `vigiles:cmd` references a markdown file declares
+ * (inline comments or frontmatter lists), using the same engine spec mode uses:
+ * file paths via existsSync, npm scripts and script-runner commands via
+ * package.json / the filesystem. References resolve relative to the markdown
+ * file's own directory. Returns the number of stale references found.
+ */
+function verifyMarkdownRefs(files, commands, filePath, silent) {
+    const basePath = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), filePath));
+    let errorCount = 0;
+    const report = (err, line) => {
+        if (!silent) {
+            console.log(`  ✗ line ${String(line)}: ${err.message}`);
+            ghAnnotate("error", err.message, filePath, line);
+        }
+        errorCount++;
+    };
+    for (const f of files) {
+        const err = (0, compile_js_1.validateFileRef)(f.path, basePath);
+        if (err)
+            report(err, f.line);
+    }
+    for (const c of commands) {
+        const err = (0, compile_js_1.validateCommandRef)(c.command, basePath);
+        if (err)
+            report(err, c.line);
+    }
+    return errorCount;
+}
 function verifyInlineRules(filePath, silent, linterOptions) {
     const log = (msg) => {
         if (!silent)
@@ -418,8 +518,11 @@ function verifyInlineRules(filePath, silent, linterOptions) {
     catch {
         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) {
+    const { rules, files, commands, errors: parseErrors, } = (0, inline_js_1.parseInlineRules)(content);
+    if (rules.length === 0 &&
+        files.length === 0 &&
+        commands.length === 0 &&
+        parseErrors.length === 0) {
         return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
     }
     let errorCount = 0;
@@ -435,10 +538,11 @@ function verifyInlineRules(filePath, silent, linterOptions) {
         if (!verifyOneRule(rule, filePath, silent, linterOptions))
             errorCount++;
     }
+    errorCount += verifyMarkdownRefs(files, commands, filePath, silent);
     return {
         ok: errorCount === 0,
         errorCount,
-        ruleCount: rules.length,
+        ruleCount: rules.length + files.length + commands.length,
         ruleNames: rules.map((r) => r.linterRule),
     };
 }
@@ -460,9 +564,12 @@ function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
     catch {
         return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
     }
-    const { rules: allRules, errors: parseErrors } = (0, frontmatter_js_1.parseFrontmatterRules)(content);
+    const { rules: allRules, files, commands, errors: parseErrors, } = (0, frontmatter_js_1.parseFrontmatterRules)(content);
     const rules = allRules.filter((r) => !exclude.has(r.linterRule));
-    if (rules.length === 0 && parseErrors.length === 0) {
+    if (rules.length === 0 &&
+        files.length === 0 &&
+        commands.length === 0 &&
+        parseErrors.length === 0) {
         return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
     }
     let errorCount = 0;
@@ -478,10 +585,11 @@ function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
         if (!verifyOneRule(rule, filePath, silent, linterOptions))
             errorCount++;
     }
+    errorCount += verifyMarkdownRefs(files, commands, filePath, silent);
     return {
         ok: errorCount === 0,
         errorCount,
-        ruleCount: rules.length,
+        ruleCount: rules.length + files.length + commands.length,
         ruleNames: rules.map((r) => r.linterRule),
     };
 }
@@ -620,6 +728,8 @@ async function audit(restArgs, flags, config) {
             console.log(`  ${line}`);
         }
     }
+    // 9. Verify code-shaped symbol references live (see src/refs.ts).
+    const symbolRefErrors = verifyMarkdownSymbols(files, silent);
     const report = {
         hashErrors: hashResult.hashErrors,
         validationErrors: hashResult.validationErrors,
@@ -635,6 +745,7 @@ async function audit(restArgs, flags, config) {
         coverageErrors,
         orphanCount: orphanReport.orphans.length,
         docRefErrors: docRefReport.errors.length,
+        symbolRefErrors,
         files,
     };
     if (summary) {
@@ -662,6 +773,8 @@ function printAuditSummary(report) {
         parts.push(`${String(report.orphanCount)} orphan docs`);
     if (report.docRefErrors > 0)
         parts.push(`${String(report.docRefErrors)} broken doc refs`);
+    if (report.symbolRefErrors > 0)
+        parts.push(`${String(report.symbolRefErrors)} broken symbol refs`);
     const undocumented = report.coverageEnabled - report.coverageDocumented;
     if (undocumented > 0)
         parts.push(`${String(undocumented)} undocumented rules`);
@@ -1302,6 +1415,38 @@ function handleGenerateSchema(args, restArgs) {
     console.log("  Add to your markdown frontmatter:\n" +
         `    # yaml-language-server: $schema=./${outPath}`);
 }
+/**
+ * `vigiles test` / `vigiles eval` — discover and run the two-tier harness
+ * scripts (deterministic `*.harness.mjs` / real-model `*.eval.mjs`) as child
+ * `node` processes, aggregating exit codes so they work as a CI command. See
+ * src/run-scripts.ts.
+ *
+ * `vigiles test` skips clean when the `claude` CLI is absent (the deterministic
+ * tier needs it, just like the node:test suite). `--trials=N` is forwarded to
+ * eval scripts via the `VIGILES_TRIALS` env var.
+ */
+function handleRunScripts(kind, args, restArgs) {
+    const cwd = process.cwd();
+    const defaultGlob = kind === "test" ? "**/*.harness.mjs" : "**/*.eval.mjs";
+    if (kind === "test" && !(0, harness_test_js_1.claudeAvailable)()) {
+        console.log("vigiles test: `claude` CLI not found — skipping harness tests.");
+        return;
+    }
+    const files = (0, run_scripts_js_1.discoverScripts)(restArgs, defaultGlob, cwd);
+    if (files.length === 0) {
+        console.log(`No ${defaultGlob} files found.`);
+        return;
+    }
+    const trialsFlag = args.find((a) => a.startsWith("--trials="));
+    const env = {};
+    if (trialsFlag)
+        env.VIGILES_TRIALS = trialsFlag.split("=")[1];
+    console.log(`Running ${String(files.length)} ${kind} file(s):\n`);
+    const results = (0, run_scripts_js_1.runScripts)(files, cwd, env);
+    console.log("\n" + (0, run_scripts_js_1.formatScriptSummary)(results));
+    if (results.some((r) => r.code !== 0))
+        process.exit(1);
+}
 function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
@@ -1309,6 +1454,8 @@ function printUsage(command) {
     console.log("  vigiles init [flags]           Setup project (--target=X.md, --strict, --no-gha)");
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
     console.log("  vigiles audit [files...]       Verify, find gaps, suggest improvements");
+    console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
+    console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N)");
     console.log("");
     console.log("Examples:");
     console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
@@ -1328,6 +1475,242 @@ function printUsage(command) {
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
+/**
+ * Emit GitHub Actions annotations for an audit report. Skipped when --json or
+ * --summary is active — those modes promise clean machine-readable stdout, and
+ * ::error/::warning lines would contaminate output parsed as JSON.
+ */
+function annotateAuditForGitHub(report, flags) {
+    const structuredOutput = flags.includes("--json") || flags.includes("--summary");
+    if (!isGitHubActions() || structuredOutput)
+        return;
+    if (report.hashErrors > 0) {
+        ghAnnotate("error", `${String(report.hashErrors)} compiled file(s) with stale hash — run vigiles compile`);
+    }
+    if (report.validationErrors > 0) {
+        ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see audit output`);
+    }
+    if (report.duplicatePairs > 0) {
+        ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
+    }
+}
+/**
+ * Run a compiled skill's deterministic gate ladder: execute each step gate in
+ * order (short-circuiting on the first failure), then the result gate. This is
+ * the v0 runtime — it enforces the `vigiles:gate`/`vigiles:result` markers a
+ * compiled SKILL.md carries. It does not yet drive the model through the prose
+ * steps (that needs a live harness).
+ */
+function runSkillCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles run-skill <SKILL.md>");
+        process.exit(2);
+    }
+    const path = (0, node_path_1.resolve)(process.cwd(), target);
+    if (!(0, node_fs_1.existsSync)(path)) {
+        console.error(`Not found: ${target}`);
+        process.exit(2);
+    }
+    const gates = (0, skill_runtime_js_1.parseSkillGates)((0, node_fs_1.readFileSync)(path, "utf-8"));
+    if (gates.steps.length === 0 && !gates.result) {
+        console.log(`No vigiles:gate / vigiles:result markers in ${target}.`);
+        return;
+    }
+    console.log(`Running gate ladder for ${target}:\n`);
+    const report = (0, skill_runtime_js_1.runSkillGates)(gates, process.cwd());
+    for (const r of report.results) {
+        const label = r.at === "result" ? "result" : `step ${String(r.at)}`;
+        console.log(`  ${r.ok ? "✓" : "✗"} ${label} — ${(0, skill_runtime_js_1.gateLabel)(r.gate)}`);
+        if (!r.ok && r.output) {
+            console.log(r.output
+                .split("\n")
+                .map((l) => `      ${l}`)
+                .join("\n"));
+        }
+    }
+    if (report.ok) {
+        console.log("\n✓ All gates passed.");
+    }
+    else {
+        const where = report.blockedAt === "result"
+            ? "the result gate"
+            : `step ${String(report.blockedAt)}`;
+        console.log(`\n✗ Blocked at ${where} — fix it before the skill is done.`);
+        process.exit(2);
+    }
+}
+/**
+ * Stop-hook entrypoint: run the active skill's result gate and decide whether
+ * the agent may stop. Exit 2 (with the reason on stderr) blocks the stop and
+ * feeds the message back to the model; exit 0 allows it and clears the marker.
+ */
+function skillHookCommand() {
+    const decision = (0, skill_runtime_js_1.evaluateStopHook)(process.cwd());
+    if (decision.allow) {
+        if (decision.message)
+            console.log(decision.message);
+        (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+        return;
+    }
+    console.error(decision.message);
+    process.exit(2);
+}
+/** Mark a skill active so the Stop hook enforces its result gate. */
+function skillStartCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles skill-start <SKILL.md>");
+        process.exit(2);
+    }
+    (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
+    console.log(`Active skill: ${target}`);
+}
+/** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
+function handleSkillCommand(command, restArgs) {
+    switch (command) {
+        case "run-skill":
+            runSkillCommand(restArgs[0]);
+            return true;
+        case "skill-start":
+            skillStartCommand(restArgs[0]);
+            return true;
+        case "skill-done":
+            (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+            return true;
+        case "skill-hook":
+            skillHookCommand();
+            return true;
+        case "action-hook":
+            actionHookCommand();
+            return true;
+        case "refs":
+            refsCommand(restArgs[0]);
+            return true;
+        case "refs-hook":
+            refsHookCommand();
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * PostToolUse-hook entrypoint for action gates. Reads the tool event on stdin,
+ * runs the matching action gates from `.vigiles/action-gates.json`, and blocks
+ * (exit 2 + reason on stderr) if any fails — plan-agnostic, so it works inside
+ * dynamic workflows where there is no static step to attach a gate to.
+ */
+function actionHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let event = { tool: "" };
+    try {
+        const j = JSON.parse(raw);
+        event = { tool: j.tool_name ?? "", input: j.tool_input };
+    }
+    catch {
+        /* malformed input → no event, allow */
+    }
+    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(process.cwd()), process.cwd());
+    if (!decision.allow) {
+        console.error(decision.message);
+        process.exit(2);
+    }
+}
+const INSTRUCTION_FILE = /^(SKILL|CLAUDE|AGENTS)\.md$/;
+function isInstructionFile(file) {
+    return INSTRUCTION_FILE.test((0, node_path_1.basename)(file));
+}
+/**
+ * Inspect an instruction file's symbol references: broken file-qualified refs
+ * (`path.ext#symbol` whose file/symbol is wrong) and code-shaped references not
+ * yet marked. Emits one line per finding via `log`; returns whether any issue
+ * was found. `basePath` is the file's own directory (where paths resolve).
+ */
+function reportRefIssues(markdown, basePath, log) {
+    const broken = (0, refs_js_1.verifySymbolRefs)(markdown, basePath);
+    const unmarked = (0, refs_js_1.unmarkedCodeRefs)(markdown);
+    for (const b of broken) {
+        log(`  ✗ line ${String(b.line)}: ${b.reason}`);
+    }
+    for (const u of unmarked) {
+        const callee = u.text.replace(/\s*\([^)]*\)\s*$/, "");
+        log(`  ✗ line ${String(u.line)}: \`${u.text}\` is an unmarked code reference — ` +
+            `mark it as \`vigiles:symbol path/to/file.ext#${callee}\` or add <!-- vigiles:ignore --> if it is prose`);
+    }
+    return broken.length > 0 || unmarked.length > 0;
+}
+/** `vigiles refs <file>` — check a file's symbol references (exit 2 on issues). */
+function refsCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles refs <instruction-file.md>");
+        process.exit(2);
+    }
+    const cwd = process.cwd();
+    let markdown;
+    try {
+        markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, target), "utf-8");
+    }
+    catch {
+        console.error(`Cannot read ${target}`);
+        process.exit(2);
+    }
+    const bad = reportRefIssues(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, target)), (m) => {
+        console.log(m);
+    });
+    if (bad)
+        process.exit(2);
+    console.log(`✓ ${target}: all code references are marked and resolve.`);
+}
+/**
+ * PostToolUse-hook entrypoint: when the agent edits an instruction file, force
+ * every code reference to carry a file-qualified mark (`path.ext#symbol`) and
+ * verify the marked ones against the named file. Exit 2 (reason on stderr)
+ * blocks the edit and feeds the fix back to the agent — the harness makes the
+ * agent mark its references, at write time, with full context. `vigiles:ignore`
+ * opts a prose span out.
+ */
+function refsHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let file = "";
+    try {
+        const j = JSON.parse(raw);
+        file = j.tool_input?.file_path ?? "";
+    }
+    catch {
+        /* malformed → nothing to do */
+    }
+    if (!file || !isInstructionFile(file))
+        return;
+    const cwd = process.cwd();
+    const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
+    let markdown;
+    try {
+        markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, file), "utf-8");
+    }
+    catch {
+        return;
+    }
+    const lines = [];
+    const bad = reportRefIssues(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file)), (m) => {
+        lines.push(m);
+    });
+    if (bad) {
+        console.error(`vigiles: fix the code references in ${target}:`);
+        for (const l of lines)
+            console.error(l);
+        process.exit(2);
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -1371,28 +1754,19 @@ async function main() {
             // audit = verify + discover + guidance count
             const flags = args.slice(1).filter((a) => a.startsWith("--"));
             const report = await audit(restArgs, flags, config);
+            annotateAuditForGitHub(report, flags);
             const exitCode = auditExitCode(report);
-            // Skip GH annotations when --json or --summary is active —
-            // those modes promise clean machine-readable stdout, and
-            // ::error/::warning lines would contaminate the output for
-            // callers parsing it as JSON.
-            const structuredOutput = flags.includes("--json") || flags.includes("--summary");
-            if (isGitHubActions() && !structuredOutput) {
-                if (report.hashErrors > 0) {
-                    ghAnnotate("error", `${String(report.hashErrors)} compiled file(s) with stale hash — run vigiles compile`);
-                }
-                if (report.validationErrors > 0) {
-                    ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see audit output`);
-                }
-                if (report.duplicatePairs > 0) {
-                    ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
-                }
-            }
             if (exitCode !== 0) {
                 process.exit(exitCode);
             }
             break;
         }
+        case "test":
+            handleRunScripts("test", args, restArgs);
+            break;
+        case "eval":
+            handleRunScripts("eval", args, restArgs);
+            break;
         // --- Plumbing ---
         case "generate-types":
             handleGenerateTypes(args, restArgs);
@@ -1401,7 +1775,8 @@ async function main() {
             handleGenerateSchema(args, restArgs);
             break;
         default:
-            printUsage(command);
+            if (!handleSkillCommand(command, restArgs))
+                printUsage(command);
             break;
     }
 }

package/dist/community-skills.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Ported community skills — proof that the generator form expresses the real,
+ * praised "agentic" skills (the deep tail the flat model can't hold), and that
+ * they are deterministically testable. Structural ports (not verbatim prose) of:
+ *
+ *  - devonjones/pr-review-loop — the corpus stress test: a bounded round loop
+ *    (7-round ceiling) with a quality-weighted exit, a per-finding for-each, and
+ *    a nested bounded CI retry sub-loop.
+ *  - test-driven-development (superpowers) — the red→green→refactor cycle.
+ *  - subagent-driven-development (superpowers) — per-task for-each with two
+ *    nested bounded review loops.
+ *
+ * These are exercised in community-skills.test.ts with a scripted model.
+ */
+import { type SkillProgram } from "./skill-driver.js";
+/** COLLECT → BATCH → FIX rounds; ceiling 7; exit when no actionable feedback. */
+export declare const prReviewLoop: SkillProgram;
+/** Red → Green → Refactor, once per behavior until done. */
+export declare const tdd: SkillProgram;
+/** Per task: bounded spec review, implement, bounded quality review, gate. */
+export declare const subagentDriven: SkillProgram;
+//# sourceMappingURL=community-skills.d.ts.map