vigiles 4.0.1 → 4.1.0

package/dist/cli.js

@@ -21,9 +21,9 @@ const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const scan_js_1 = require("./scan.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
+const skill_harness_js_1 = require("./skill-harness.js");
 const leaderboard_js_1 = require("./leaderboard.js");
 const compile_js_1 = require("./core/compile.js");
-const dialect_js_1 = require("./adapters/claude-code/dialect.js");
 const proofs_js_1 = require("./core/proofs.js");
 const inline_js_1 = require("./core/inline.js");
 const frontmatter_js_1 = require("./core/frontmatter.js");
@@ -54,7 +54,7 @@ function findSpecs(pattern) {
     return (0, glob_1.globSync)(glob, {
         // `dot: true` so specs that live in a sync tool's source slot (e.g.
         // `.ruler/AGENTS.md.spec.ts`, the redirect target) are discovered by
-        // compile/audit/the recompile hook — not just root-level specs.
+        // compile/lint/the recompile hook — not just root-level specs.
         dot: true,
         ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**"],
         cwd: process.cwd(),
@@ -140,12 +140,12 @@ function compileGeneratorSkillToFile(specPath, source) {
     return false;
 }
 /** Compile a ClaudeSpec → its primary + any additional targets. */
-function compileClaudeToFile(spec, specPath, config) {
+function compileClaudeToFile(spec, specPath, config, dialect) {
     const basePath = process.cwd();
     const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
         basePath,
         specFile: specPath,
-        dialect: dialect_js_1.claudeCodeDialect,
+        dialect,
         maxRules: config.maxRules,
         maxTokens: config.maxTokens,
         maxSectionLines: config.maxSectionLines,
@@ -175,15 +175,54 @@ function compileClaudeToFile(spec, specPath, config) {
     console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
     return true;
 }
+/**
+ * Branch 3 of the mirror story (research/multi-harness-compile.md): when a repo
+ * declares ≥2 harnesses and nothing else fans out the instruction file, write a
+ * byte-identical copy to each other harness's instruction file (e.g. CLAUDE.md →
+ * AGENTS.md). A copy — not a symlink — because it works everywhere and carries
+ * the source's embedded integrity hash by construction, so a hand-edit of the
+ * mirror trips the existing `integrity` check. Never fights a sync tool or
+ * clobbers a target that owns its own spec.
+ */
+function writeInstructionMirrors(primaryOutput, harnesses) {
+    if (harnesses.length < 2)
+        return;
+    const cwd = process.cwd();
+    // A sync tool (Ruler/rulesync) owns fan-out — don't fight it.
+    if ((0, compose_js_1.detectSyncTools)(cwd).length > 0)
+        return;
+    const primaryName = (0, node_path_1.basename)(primaryOutput);
+    const primaryAbs = (0, node_path_1.resolve)(cwd, primaryOutput);
+    if (!(0, node_fs_1.existsSync)(primaryAbs))
+        return;
+    const content = (0, node_fs_1.readFileSync)(primaryAbs, "utf-8");
+    for (const name of harnesses) {
+        const adapter = (0, adapter_registry_js_1.getAdapter)(name);
+        if (!adapter)
+            continue;
+        const target = adapter.layout.instructionFile;
+        if (target === primaryName)
+            continue; // the file we just compiled
+        // Never clobber a target that has its own spec (a genuinely separate file).
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, `${target}.spec.ts`)))
+            continue;
+        const targetAbs = (0, node_path_1.resolve)(cwd, target);
+        if ((0, node_fs_1.existsSync)(targetAbs) && (0, node_fs_1.readFileSync)(targetAbs, "utf-8") === content) {
+            continue; // already byte-identical
+        }
+        (0, node_fs_1.writeFileSync)(targetAbs, content);
+        console.log(`  ↳ mirrored ${primaryName} → ${target} (byte-identical)`);
+    }
+}
 /** Compile a declarative SkillSpec → SKILL.md. */
-function compileSkillToFile(spec, specPath) {
+function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
     const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
-        // Pick the SKILL.md frontmatter profile from the detected harness — a Codex
+        // The SKILL.md frontmatter profile comes from the resolved harness — a Codex
         // repo gets a minimal (name + description) SKILL.md; CC gets the full set.
-        dialect: (0, adapter_registry_js_1.detectAdapter)(process.cwd()).dialect,
+        dialect,
     });
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
@@ -195,12 +234,12 @@ function compileSkillToFile(spec, specPath) {
     return false;
 }
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
-function compileAgentToFile(spec, specPath) {
+function compileAgentToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
     const { markdown, errors } = (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
-        dialect: (0, adapter_registry_js_1.detectAdapter)(process.cwd()).dialect,
+        dialect,
     });
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
@@ -241,8 +280,21 @@ async function collectAgentNames() {
     }
     return names;
 }
-async function compile(specPaths, config) {
+async function compile(specPaths, config, opts = {}) {
     let allValid = true;
+    // Parse the declared harness set ONCE (alias-normalized) and feed both the
+    // dialect pick and the mirror from it — no re-parsing, no cwd-sniffing in the
+    // helpers. A loud notice (never a silent guess) on a multi-harness or
+    // ambiguous-detection pick.
+    const declaredHarnesses = (0, adapter_registry_js_1.normalizeHarnessList)(config.harness);
+    const selection = (0, adapter_registry_js_1.resolveHarnessSelection)({
+        root: process.cwd(),
+        flag: opts.harnessFlag,
+        configHarness: declaredHarnesses,
+    });
+    if (selection.kind === "notice")
+        console.log(`⚠ ${selection.notice}`);
+    const dialect = selection.adapter.dialect;
     // Resolved lazily on the first railway spec — every delegate() target is
     // checked against the agents defined anywhere in the project.
     let knownAgents = null;
@@ -262,15 +314,36 @@ async function compile(specPaths, config) {
             continue;
         }
         if (spec._specType === "claude") {
-            if (!compileClaudeToFile(spec, specPath, config))
+            // Spec-target disambiguation: a CLAUDE.md.spec.ts is a claude-code file, an
+            // AGENTS.md.spec.ts a codex one — the strongest dialect signal for THIS
+            // spec. The flag still overrides; absent one, the spec's own target wins
+            // over config/detect. (Skill/agent targets don't name a harness, so they
+            // keep the run-level dialect.)
+            const targetFile = (0, node_path_1.basename)(specPath).replace(/\.spec\.ts$/, "");
+            const specDialect = opts.harnessFlag === undefined
+                ? ((0, adapter_registry_js_1.adapterForInstructionFile)(targetFile)?.dialect ?? dialect)
+                : dialect;
+            if (compileClaudeToFile(spec, specPath, config, specDialect)) {
+                writeInstructionMirrors(specPath.replace(/\.spec\.ts$/, ""), declaredHarnesses);
+            }
+            else {
                 allValid = false;
+            }
         }
         else if (spec._specType === "skill") {
-            if (!compileSkillToFile(spec, specPath))
+            // Cross-harness verify: flag CC-only frontmatter a declared minimal-profile
+            // harness (Codex/OpenCode) would silently drop.
+            const forHarnesses = declaredHarnesses.length > 0
+                ? declaredHarnesses
+                : [selection.adapter.name];
+            for (const w of (0, skill_harness_js_1.skillFrontmatterDropWarnings)(spec, forHarnesses)) {
+                console.log(`⚠ ${w}`);
+            }
+            if (!compileSkillToFile(spec, specPath, dialect))
                 allValid = false;
         }
         else if (spec._specType === "agent") {
-            if (!compileAgentToFile(spec, specPath))
+            if (!compileAgentToFile(spec, specPath, dialect))
                 allValid = false;
         }
         else if (spec._specType === "railway") {
@@ -310,7 +383,7 @@ function verifyHashes(filePaths, silent = false) {
         const fullPath = (0, node_path_1.resolve)(process.cwd(), filePath);
         // If the file doesn't exist at all (typo, deleted), that's an error —
         // not a "no hash" informational message. Without this check, a scoped
-        // audit like `vigiles audit typo.md` would silently exit clean.
+        // lint like `vigiles lint typo.md` would silently exit clean.
         if (!(0, node_fs_1.existsSync)(fullPath)) {
             log(`\n✗ ${filePath} — file not found`);
             if (!silent) {
@@ -387,7 +460,7 @@ function check(filePaths, silent = false) {
         hashErrors: hashes.errorCount,
         // `validateSpecs` only returns a boolean today, so we collapse
         // failures to 1 until it starts reporting counts. Kept in its own
-        // counter so audit's "stale hash — run vigiles compile" remediation
+        // counter so lint's "stale hash — run vigiles compile" remediation
         // doesn't misreport a require-spec / other validation failure.
         validationErrors: specsValid ? 0 : 1,
     };
@@ -403,7 +476,7 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
             console.log(msg);
     };
     const allSpecs = findSpecs();
-    // If audit was invoked with explicit file arguments, only scan the specs
+    // If lint was invoked with explicit file arguments, only scan the specs
     // for those files — otherwise an unrelated duplicate elsewhere in the
     // repo would fail a targeted CI check (e.g. `vigiles lint path/foo.md`).
     //
@@ -551,7 +624,7 @@ async function verifyMarkdownMcpRefs(files, silent) {
     return errors;
 }
 /** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
-function auditExitCode(report) {
+function lintExitCode(report) {
     if (report.hashErrors > 0 ||
         report.validationErrors > 0 ||
         report.inlineErrors > 0 ||
@@ -718,7 +791,7 @@ function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
  *
  * 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
+ * markdown (or an example in a spec-managed file) must not trip lint. 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
@@ -768,14 +841,14 @@ function verifyMarkdownModeRules(files, silent, config) {
     return totals;
 }
 /**
- * Unified audit command: verify hashes, report coverage gaps, detect duplicates,
+ * Unified lint command: verify hashes, report coverage gaps, detect duplicates,
  * suggest improvements.
  *
  * Flags:
  *   --summary   Print a single-line summary (for SessionStart hooks)
  *   --json      Print structured JSON report (for CI integration)
  */
-async function audit(restArgs, flags, config) {
+async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
@@ -801,7 +874,7 @@ async function audit(restArgs, flags, config) {
         console.log("\nLinter rule coverage:\n");
     const coverage = discover(silent);
     // 3. Duplicate rule detection (NCD). Scope to the requested files when
-    // audit was invoked with explicit paths, so targeted CI checks don't
+    // lint was invoked with explicit paths, so targeted CI checks don't
     // fail on unrelated duplicates elsewhere in the repo.
     if (!silent)
         console.log("\nDuplicate rule detection:\n");
@@ -878,15 +951,15 @@ async function audit(restArgs, flags, config) {
         files,
     };
     if (summary) {
-        printAuditSummary(report);
+        printLintSummary(report);
     }
     else if (json) {
         console.log(JSON.stringify(report, null, 2));
     }
     return report;
 }
-/** Single-line audit summary for SessionStart hooks — minimal token cost. */
-function printAuditSummary(report) {
+/** Single-line lint summary for SessionStart hooks — minimal token cost. */
+function printLintSummary(report) {
     const parts = [];
     if (report.hashErrors > 0)
         parts.push(`${String(report.hashErrors)} stale`);
@@ -1036,7 +1109,14 @@ function init(args) {
     // `.ruler/AGENTS.md.spec.ts` source slot → target "AGENTS.md").
     const targetName = (0, node_path_1.basename)(target);
     const targetLine = targetName !== "CLAUDE.md" ? `\n  target: "${targetName}",` : "";
-    const template = `import { claude, enforce, guidance } from "vigiles/spec";
+    // Import ONLY what the scaffold uses (`claude`) — a strict ESLint with
+    // \`no-unused-vars\` + \`--max-warnings=0\` (common in CI) would otherwise fail
+    // the moment this is committed, because the enforce()/guidance() examples
+    // below are commented out. The commented import shows what to add when you
+    // write a real rule.
+    const template = `import { claude } from "vigiles/spec";
+// When you add rules below, import the builders you use, e.g.:
+// import { claude, enforce, guidance } from "vigiles/spec";
 
 export default claude({${targetLine}
   sections: {
@@ -1124,7 +1204,7 @@ ${harness}`;
 /**
  * Detect a workflow that drives vigiles through an OLD API — a bare `npx vigiles`
  * (a no-op help screen in v2+) rather than the `zernie/vigiles@` Action or a real
- * subcommand (`audit`/`test`/…). Upgrading users whose workflow predates the
+ * subcommand (`lint`/`test`/…). Upgrading users whose workflow predates the
  * subcommand split silently lose CI validation, so we flag it loudly.
  */
 function workflowUsesStaleApi(content) {
@@ -1135,24 +1215,69 @@ function workflowUsesStaleApi(content) {
     const hasModernCmd = /vigiles\s+(lint|test|eval|compile|scan|generate-types|generate-schema|init)\b/.test(content);
     return !hasModernCmd;
 }
+/**
+ * Subcommands removed/renamed across majors → the replacement to suggest. A
+ * workflow that still calls one is a silently-broken CI step (the removed
+ * subcommand exits non-zero / no-ops), and this stays true even when the file
+ * ALSO uses the Action or a modern command — so it is checked independently of
+ * the bare-API heuristic above, which an Action reference short-circuits.
+ */
+const REMOVED_SUBCOMMANDS = {
+    audit: "lint", // v3 → v4 rename
+};
+/** The first removed/renamed `vigiles <sub>` a workflow still calls, if any. */
+function workflowRemovedSubcommand(content) {
+    for (const [sub, replacement] of Object.entries(REMOVED_SUBCOMMANDS)) {
+        if (new RegExp(`vigiles\\s+${sub}\\b`).test(content))
+            return { sub, replacement };
+    }
+    return null;
+}
+/** Rewrite removed/renamed `vigiles <sub>` invocations in place (audit → lint).
+ * Surgical — preserves the rest of the user's workflow. */
+function rewriteRemovedSubcommands(content) {
+    let out = content;
+    for (const [sub, replacement] of Object.entries(REMOVED_SUBCOMMANDS)) {
+        out = out.replace(new RegExp(`(vigiles\\s+)${sub}\\b`, "g"), `$1${replacement}`);
+    }
+    return out;
+}
 /** Create `.github/workflows/vigiles.yml`. Returns the files it wrote (for the
- * commit hint). An existing workflow is never clobbered, but a STALE one (old
- * bare-`npx vigiles` API) is reported loudly instead of silently skipped. */
+ * commit hint). An existing workflow is never clobbered unless `--force`, but a
+ * STALE one (old bare-`npx vigiles` API, or a removed subcommand) is reported
+ * loudly instead of silently skipped — and rewritten in place with `--force`. */
 function wireGha(plan) {
     const dir = (0, node_path_1.resolve)(process.cwd(), ".github", "workflows");
     const path = (0, node_path_1.resolve)(dir, "vigiles.yml");
+    const rel = ".github/workflows/vigiles.yml";
     if ((0, node_fs_1.existsSync)(path)) {
         const content = (0, node_fs_1.readFileSync)(path, "utf-8");
-        if (workflowUsesStaleApi(content)) {
-            console.log("⚠ .github/workflows/vigiles.yml is STALE — it runs a bare `npx vigiles`,\n" +
-                "  which is a no-op help screen now. Replace its run step with the Action +\n" +
-                "  the test job (CI is otherwise silently not validating anything):\n" +
-                "    - uses: zernie/vigiles@v1   # lint pillar — verify references\n" +
-                "    - run: npx vigiles test     # pillar 2 — harness tests\n" +
-                "  Or delete the file and re-run `vigiles init` to regenerate it.");
+        const removed = workflowRemovedSubcommand(content);
+        if (removed) {
+            if (plan.force) {
+                (0, node_fs_1.writeFileSync)(path, rewriteRemovedSubcommands(content));
+                console.log(`✓ Rewrote ${rel} (vigiles ${removed.sub} → ${removed.replacement})`);
+                return [rel];
+            }
+            console.log(`⚠ ${rel} is STALE — it runs \`vigiles ${removed.sub}\`,\n` +
+                `  which was removed/renamed (now \`vigiles ${removed.replacement}\`). That CI\n` +
+                "  step is silently broken. Fix it:\n" +
+                `    - re-run \`vigiles init --force\` to rewrite it in place (vigiles ${removed.sub} → ${removed.replacement}), or\n` +
+                "    - switch the run step to `uses: zernie/vigiles@v1` (the composite Action).");
+        }
+        else if (workflowUsesStaleApi(content)) {
+            if (plan.force) {
+                (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan));
+                console.log(`✓ Regenerated ${rel} (was a stale bare \`npx vigiles\`)`);
+                return [rel];
+            }
+            console.log(`⚠ ${rel} is STALE — it runs a bare \`npx vigiles\`,\n` +
+                "  which is a no-op help screen now. CI is silently not validating anything. Fix it:\n" +
+                "    - re-run `vigiles init --force` to regenerate the workflow, or\n" +
+                "    - replace its run step with `uses: zernie/vigiles@v1` + `run: npx vigiles test`.");
         }
         else {
-            console.log("✓ .github/workflows/vigiles.yml already exists (up to date)");
+            console.log(`✓ ${rel} already exists (up to date)`);
         }
         return [];
     }
@@ -1461,6 +1586,51 @@ function harnessBinaryPresent(bin) {
         return false;
     }
 }
+/** Run a plan's auto-install commands; classify the result. */
+function runInstall(plan, exec) {
+    if (plan.commands.length === 0)
+        return "no-cli";
+    try {
+        for (const cmd of plan.commands) {
+            exec(cmd, { stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
+        }
+        return "ok";
+    }
+    catch {
+        return "failed";
+    }
+}
+/**
+ * Report a plan's outcome. On anything but success, be LOUD — when an AGENT runs
+ * `init` (no human at the TTY), a quiet "Install vigiles:" hint followed by
+ * `/plugin` slash commands is a trap: the agent can't run a TUI slash command,
+ * so the plugin silently never installs. Surface the failure as a warning AND
+ * lead with the shell-runnable CLI form (which an agent CAN run), keeping the
+ * slash commands clearly labelled as the in-TUI alternative for a human.
+ */
+function reportInstall(plan, outcome) {
+    if (outcome === "ok") {
+        console.log(plan.successMessage);
+        for (const note of plan.notes)
+            console.log(`  ${note}`);
+        return;
+    }
+    console.log(outcome === "failed"
+        ? `⚠ vigiles plugin auto-install for ${plan.harness} FAILED — the plugin (hooks + skills) is NOT installed.`
+        : `⚠ vigiles plugin for ${plan.harness} was NOT installed (the ${plan.harness} CLI isn't on PATH here).`);
+    if (plan.commands.length > 0) {
+        console.log("  Finish from a shell (an agent can run these):");
+        for (const cmd of plan.commands)
+            console.log(`    ${cmd}`);
+    }
+    if (plan.manualSteps.length > 0) {
+        console.log("  Or inside the Claude Code TUI (a human, not an agent):");
+        for (const step of plan.manualSteps)
+            console.log(`    ${step}`);
+    }
+    for (const note of plan.notes)
+        console.log(`  ${note}`);
+}
 /**
  * Install vigiles's skills/hooks for the chosen harness(es) via the per-harness
  * `planPluginInstall` decision — Claude Code through the GLOBAL plugin
@@ -1474,26 +1644,7 @@ function installPlugins(harnesses) {
     });
     for (const plan of plans) {
         console.log("");
-        let installed = false;
-        if (plan.commands.length > 0) {
-            try {
-                for (const cmd of plan.commands) {
-                    exec(cmd, { stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
-                }
-                console.log(plan.successMessage);
-                installed = true;
-            }
-            catch {
-                // Fall through to the manual instructions below.
-            }
-        }
-        if (!installed) {
-            console.log(`Install vigiles for ${plan.harness}:`);
-            for (const step of plan.manualSteps)
-                console.log(`    ${step}`);
-        }
-        for (const note of plan.notes)
-            console.log(`  ${note}`);
+        reportInstall(plan, runInstall(plan, exec));
     }
 }
 /** Add/upgrade `vigiles` in the project's `devDependencies` (and move it out of
@@ -1657,16 +1808,44 @@ async function setup(args) {
         console.log("\n  Non-markdown agent configs detected. Use a sync tool to convert:");
         console.log("    npm install -D rule-porter");
     }
-    // Strict config.
-    if (strict) {
-        const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
-        if (!(0, node_fs_1.existsSync)(configPath)) {
-            (0, node_fs_1.writeFileSync)(configPath, JSON.stringify({ rules: { "require-spec": "error", "require-skill-spec": "error" } }, null, 2) + "\n");
-            console.log("✓ Created .vigilesrc.json with strict rules");
-            written.push(".vigilesrc.json");
+    // Project config — record the harness(es) so compile/lint select the dialect
+    // deterministically (no cwd sniffing), plus strict rule severities on --strict.
+    writeProjectConfig({ harnesses, strict, written });
+    printSetupSummary({ plan, strict, targets, needsMigration, written });
+}
+/** Canonical, de-duplicated harness list → a config value (string when one). */
+function harnessConfigValue(harnesses) {
+    const canon = [...new Set(harnesses.map(adapter_registry_js_1.normalizeHarnessName))];
+    return canon.length === 1 ? canon[0] : canon;
+}
+/**
+ * Merge the resolved harness(es) (and strict rule severities) into
+ * `.vigilesrc.json` without clobbering existing keys — an existing `harness`
+ * stays, a missing one is added, a malformed file is left untouched.
+ */
+function writeProjectConfig(opts) {
+    const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
+    const existed = (0, node_fs_1.existsSync)(configPath);
+    let existing = {};
+    if (existed) {
+        try {
+            existing = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+        }
+        catch {
+            return; // user-owned malformed config — never clobber it
         }
     }
-    printSetupSummary({ plan, strict, targets, needsMigration, written });
+    const merged = (0, setup_plan_js_1.mergeProjectConfig)(existing, {
+        harness: harnessConfigValue(opts.harnesses),
+        strict: opts.strict,
+    });
+    if (!merged)
+        return;
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(merged, null, 2) + "\n");
+    console.log(`✓ ${existed ? "Updated" : "Created"} .vigilesrc.json`);
+    if (!opts.written.includes(".vigilesrc.json")) {
+        opts.written.push(".vigilesrc.json");
+    }
 }
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
@@ -1725,7 +1904,7 @@ function checkUntestedSurfaces(config, silent) {
 }
 /**
  * Apply the configured coverage thresholds. Returns the number of failing
- * thresholds (so the audit can fail CI when severity is "error").
+ * thresholds (so the lint 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
@@ -1934,7 +2113,7 @@ function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
     console.log("Commands:");
-    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha)");
+    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha, --force)");
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
@@ -1960,11 +2139,11 @@ function printUsage(command) {
 // Main
 // ---------------------------------------------------------------------------
 /**
- * Emit GitHub Actions annotations for an audit report. Skipped when --json or
+ * Emit GitHub Actions annotations for an lint 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) {
+function annotateLintForGitHub(report, flags) {
     const structuredOutput = flags.includes("--json") || flags.includes("--summary");
     if (!isGitHubActions() || structuredOutput)
         return;
@@ -1972,7 +2151,7 @@ function annotateAuditForGitHub(report, flags) {
         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`);
+        ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see lint output`);
     }
     if (report.duplicatePairs > 0) {
         ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
@@ -2289,7 +2468,10 @@ async function main() {
                 console.log("Run `vigiles init` to create one.");
                 process.exit(0);
             }
-            const valid = await compile(specs, config);
+            const harnessFlag = args
+                .find((a) => a.startsWith("--harness="))
+                ?.slice("--harness=".length);
+            const valid = await compile(specs, config, { harnessFlag });
             console.log("");
             if (valid) {
                 console.log("Compilation complete.");
@@ -2303,9 +2485,9 @@ async function main() {
         case "lint": {
             // lint = verify references + 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);
+            const report = await runLint(restArgs, flags, config);
+            annotateLintForGitHub(report, flags);
+            const exitCode = lintExitCode(report);
             if (exitCode !== 0) {
                 process.exit(exitCode);
             }

package/dist/core/compile.d.ts

@@ -92,7 +92,7 @@ export interface CompileAgentResult {
 /**
  * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.
  * Verifies the tool contract and the body's references; the marks the body
- * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
+ * carries (`vigiles:symbol`, file/cmd refs) are the same ones `lint` re-checks.
  */
 export declare function compileAgent(spec: AgentSpec, options: {
     basePath?: string;

package/dist/core/compile.js

@@ -802,7 +802,7 @@ function renderAgentRules(rules) {
 /**
  * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.
  * Verifies the tool contract and the body's references; the marks the body
- * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
+ * carries (`vigiles:symbol`, file/cmd refs) are the same ones `lint` re-checks.
  */
 function compileAgent(spec, options) {
     const basePath = options.basePath ?? process.cwd();

package/dist/core/compose.d.ts

@@ -13,7 +13,7 @@
  * This detector is pure filesystem inspection — the same deterministic-detector
  * shape as `orphans.ts` / `test-coverage.ts`. It reports which tools are present
  * and any target that collides with a file the tool regenerates, so `vigiles
- * audit` can warn before the integrity guarantee is lost.
+ * lint` can warn before the integrity guarantee is lost.
  */
 /** A rule-sync tool vigiles should compose with rather than reimplement. */
 export type SyncToolName = "ruler" | "rulesync";

package/dist/core/compose.js

@@ -14,7 +14,7 @@
  * This detector is pure filesystem inspection — the same deterministic-detector
  * shape as `orphans.ts` / `test-coverage.ts`. It reports which tools are present
  * and any target that collides with a file the tool regenerates, so `vigiles
- * audit` can warn before the integrity guarantee is lost.
+ * lint` can warn before the integrity guarantee is lost.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectSyncTools = detectSyncTools;

package/dist/core/generate-schema.d.ts

@@ -20,7 +20,7 @@ export interface GenerateSchemaOptions {
     basePath?: string;
     /**
      * Custom linters from `.vigilesrc.json` (`rulesDir`-backed). These aren't
-     * auto-discovered by `generate-types`, but `vigiles audit` resolves their
+     * auto-discovered by `generate-types`, but `vigiles lint` resolves their
      * rules via `checkLinterRule`, so the schema enum must include them too —
      * otherwise the YAML LSP false-flags a rule that CI accepts.
      */

package/dist/core/generate-schema.js

@@ -26,7 +26,7 @@ const generate_types_js_1 = require("./generate-types.js");
 /**
  * Rule references for config-declared custom linters. Mirrors
  * `checkLinterRule`'s rulesDir lookup (any file `<rule>.*` is a rule) so the
- * enum matches what `vigiles audit` accepts for these linters.
+ * enum matches what `vigiles lint` accepts for these linters.
  */
 function customRuleRefs(basePath, linters) {
     const refs = [];
@@ -84,7 +84,7 @@ function generateSchema(options = {}) {
                 properties: {
                     enforce: {
                         type: "array",
-                        description: "Linter rules to enforce, verified by `vigiles audit`.",
+                        description: "Linter rules to enforce, verified by `vigiles lint`.",
                         items: {
                             type: "object",
                             additionalProperties: false,
@@ -103,12 +103,12 @@ function generateSchema(options = {}) {
                     },
                     files: {
                         type: "array",
-                        description: "File paths referenced by this instruction file, verified to exist by `vigiles audit`.",
+                        description: "File paths referenced by this instruction file, verified to exist by `vigiles lint`.",
                         items: { type: "string" },
                     },
                     commands: {
                         type: "array",
-                        description: "Commands (npm scripts / script-runner invocations) referenced here, verified by `vigiles audit`.",
+                        description: "Commands (npm scripts / script-runner invocations) referenced here, verified by `vigiles lint`.",
                         items: { type: "string" },
                     },
                 },