vigiles 38.2.0 → 39.0.0

package/dist/cli-main.js

@@ -32,6 +32,7 @@ const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
 const validate_js_1 = require("./core/validate.js");
+const overrides_js_1 = require("./overrides.js");
 const eval_lock_js_1 = require("./eval-lock.js");
 const eval_entry_js_1 = require("./eval-entry.js");
 const zod_1 = require("zod");
@@ -69,6 +70,7 @@ const instruction_sources_js_1 = require("./instruction-sources.js");
 const rule_catalog_js_1 = require("./core/rule-catalog.js");
 const adoptability_js_1 = require("./adoptability.js");
 const compile_js_1 = require("./core/compile.js");
+const enforce_marker_js_1 = require("./core/enforce-marker.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");
@@ -79,6 +81,7 @@ const action_gate_js_1 = require("./action-gate.js");
 const guards_js_1 = require("./core/guards.js");
 const hook_program_js_1 = require("./core/hook-program.js");
 const hook_install_js_1 = require("./hook-install.js");
+const hook_command_js_1 = require("./core/hook-command.js");
 const hook_check_install_js_1 = require("./hook-check-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
@@ -98,6 +101,7 @@ const harness_test_js_1 = require("./harness-test.js");
 const run_scripts_js_1 = require("./adapters/claude-code/run-scripts.js");
 const coverage_artifact_js_1 = require("./coverage-artifact.js");
 const integrity_js_1 = require("./core/integrity.js");
+const instruction_remedies_js_1 = require("./core/instruction-remedies.js");
 const adopt_js_1 = require("./core/adopt.js");
 const coverage_js_1 = require("./core/coverage.js");
 const orphans_js_1 = require("./core/orphans.js");
@@ -343,6 +347,27 @@ function printErrors(specFile, errors) {
         console.log(`::error file=${specFile}::${err.message}`);
     }
 }
+/**
+ * The rule count line, split by what compile VERIFIED (#351): "linter-verified"
+ * counts only references rendered "**Enforced by:**"; every other `enforce()` was
+ * rendered "**Claimed (unverified):**" and gets one line saying why and what
+ * turns it into "Enforced by". Never changes the exit code.
+ */
+function printRuleSummary(specFile, ruleCount, verdicts) {
+    const unverified = verdicts.flatMap((v) => v.verdict.kind === "unverified"
+        ? [{ ref: v.ref, reason: v.verdict.reason }]
+        : []);
+    const verified = verdicts.length - unverified.length;
+    const claimed = unverified.length > 0
+        ? `, ${String(unverified.length)} claimed unverified`
+        : "";
+    console.log(`  ${String(ruleCount)} rules (${String(verified)} linter-verified${claimed})`);
+    unverified.forEach((u) => {
+        const advice = (0, compile_js_1.unverifiedAdvice)(u.ref, u.reason);
+        console.log(`  ⚠ Claimed (unverified) — ${advice}`);
+        console.log(`::warning file=${specFile}::${advice}`);
+    });
+}
 /** Non-blocking advisories — printed, but never fail the compile. */
 function printWarnings(specFile, warnings) {
     for (const w of warnings) {
@@ -355,10 +380,10 @@ function printWarnings(specFile, warnings) {
 // Commands
 // ---------------------------------------------------------------------------
 /** Compile a generator-skill spec from source → SKILL.md. Returns validity. */
-function compileGeneratorSkillToFile(specPath, source) {
+function compileGeneratorSkillToFile(root, specPath, source) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
     const { artifact, errors } = (0, compile_generator_js_1.compileGeneratorSkill)(source, {
-        basePath: process.cwd(),
+        basePath: root,
         specFile: specPath,
     });
     // Written only when the compile is clean: `artifact` is null otherwise, and
@@ -375,9 +400,9 @@ function compileGeneratorSkillToFile(specPath, source) {
     return false;
 }
 /** Compile a ClaudeSpec → its primary + any additional targets. */
-async function compileClaudeToFile(spec, specPath, config, dialect) {
-    const basePath = process.cwd();
-    const { markdown, errors, warnings, linterResults, targets } = await (0, compile_js_1.compileClaude)(spec, {
+async function compileClaudeToFile(root, spec, specPath, config, dialect) {
+    const basePath = root;
+    const { markdown, errors, warnings, enforceVerdicts, outputs } = await (0, compile_js_1.compileClaude)(spec, {
         basePath,
         specFile: specPath,
         dialect,
@@ -386,7 +411,7 @@ async function compileClaudeToFile(spec, specPath, config, dialect) {
         maxSectionLines: config.maxSectionLines,
         catalogOnly: config.catalogOnly,
         linters: config.linters,
-        ...compileBudgetOptions(config),
+        ...compileBudgetOptions(config, specPath.replace(/\.spec\.ts$/, "")),
     });
     const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
     // Budget findings print BEFORE the pass/fail line and never change the exit
@@ -418,20 +443,12 @@ async function compileClaudeToFile(spec, specPath, config, dialect) {
         console.log(`  → ${primaryOutput} was NOT written; the previous version is left in place.`);
         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(", ")} (${formatArtifactSize(markdown)})`);
-    console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
+    // Each target as compile rendered it for its own path: a secondary in
+    // another directory has its own links, so it is never a re-headed copy.
+    for (const o of outputs)
+        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, o.path), o.markdown);
+    console.log(`\n✓ ${specPath} → ${outputs.map((o) => o.path).join(", ")} (${formatArtifactSize(markdown)})`);
+    printRuleSummary(specPath, Object.keys(spec.rules).length, enforceVerdicts);
     return true;
 }
 /**
@@ -512,10 +529,10 @@ function formatArtifactSize(markdown) {
     return `${size} · ~${String(kTokens)}k tokens est.`;
 }
 /** Compile a declarative SkillSpec → SKILL.md. */
-async function compileSkillToFile(spec, specPath, dialect) {
+async function compileSkillToFile(root, spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
     const { artifact, errors, warnings } = await (0, compile_js_1.compileSkill)(spec, {
-        basePath: process.cwd(),
+        basePath: root,
         specFile: specPath,
         // 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.
@@ -536,12 +553,15 @@ async function compileSkillToFile(spec, specPath, dialect) {
     return false;
 }
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
-async function compileAgentToFile(spec, specPath, dialect) {
+async function compileAgentToFile(root, spec, specPath, config, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    // The same verify options an instruction file gets (`compileClaudeToFile`).
     const { artifact, errors, warnings } = await (0, compile_js_1.compileAgent)(spec, {
-        basePath: process.cwd(),
+        basePath: root,
         specFile: specPath,
         dialect,
+        catalogOnly: config.catalogOnly,
+        linters: config.linters,
     });
     // Written only when the compile is clean: `artifact` is null otherwise, and
     // `writeArtifact` takes nothing else.
@@ -591,6 +611,7 @@ async function collectAgentNames(excludes) {
     return names;
 }
 async function compile(specPaths, config, excludes, opts = {}) {
+    const root = excludes.root;
     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
@@ -598,7 +619,7 @@ async function compile(specPaths, config, excludes, opts = {}) {
     // ambiguous-detection pick.
     const declaredHarnesses = (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses);
     const selection = (0, adapter_registry_js_1.resolveHarnessSelection)({
-        root: process.cwd(),
+        root,
         flag: opts.harnessFlag,
         configHarness: declaredHarnesses,
     });
@@ -610,9 +631,9 @@ async function compile(specPaths, config, excludes, opts = {}) {
     let knownAgents = null;
     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");
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(root, specPath), "utf-8");
         if (/\bgenSkill\s*\(/.test(source)) {
-            if (!compileGeneratorSkillToFile(specPath, source))
+            if (!compileGeneratorSkillToFile(root, specPath, source))
                 allValid = false;
             continue;
         }
@@ -633,7 +654,7 @@ async function compile(specPaths, config, excludes, opts = {}) {
             const specDialect = opts.harnessFlag === undefined
                 ? ((0, adapter_registry_js_1.adapterForInstructionFile)(targetFile)?.dialect ?? dialect)
                 : dialect;
-            if (await compileClaudeToFile(spec, specPath, config, specDialect)) {
+            if (await compileClaudeToFile(root, spec, specPath, config, specDialect)) {
                 writeInstructionMirrors(specPath.replace(/\.spec\.ts$/, ""), declaredHarnesses);
             }
             else {
@@ -649,11 +670,11 @@ async function compile(specPaths, config, excludes, opts = {}) {
             for (const w of (0, skill_harness_js_1.skillFrontmatterDropWarnings)(spec, forHarnesses)) {
                 console.log(`⚠ ${w}`);
             }
-            if (!(await compileSkillToFile(spec, specPath, dialect)))
+            if (!(await compileSkillToFile(root, spec, specPath, dialect)))
                 allValid = false;
         }
         else if (spec._specType === "agent") {
-            if (!(await compileAgentToFile(spec, specPath, dialect)))
+            if (!(await compileAgentToFile(root, spec, specPath, config, dialect)))
                 allValid = false;
         }
         else if (spec._specType === "railway") {
@@ -690,14 +711,14 @@ function ghAnnotate(level, message, file, line) {
     const loc = locParts.length > 0 ? " " + locParts.join(",") : "";
     console.log(`::${level}${loc}::${message}`);
 }
-function verifyHashes(frame, filePaths, silent = false) {
+function verifyHashes(root, frame, filePaths, silent = false) {
     let errorCount = 0;
     const log = (msg) => {
         if (!silent)
             console.log(msg);
     };
     for (const filePath of filePaths) {
-        const fullPath = (0, node_path_1.resolve)(process.cwd(), filePath);
+        const fullPath = (0, node_path_1.resolve)(root, 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
         // lint like `vigiles lint typo.md` would silently exit clean.
@@ -727,14 +748,14 @@ function verifyHashes(frame, filePaths, silent = false) {
     }
     return { valid: errorCount === 0, errorCount };
 }
-function validateSpecs(filePaths, rulesConfig, silent = false) {
+function validateSpecs(root, filePaths, rulesConfig, rules, silent = false) {
     let allValid = true;
     const log = (msg) => {
         if (!silent)
             console.log(msg);
     };
     for (const filePath of filePaths) {
-        const fullPath = (0, node_path_1.resolve)(process.cwd(), filePath);
+        const fullPath = (0, node_path_1.resolve)(root, filePath);
         let content;
         try {
             content = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
@@ -747,16 +768,24 @@ function validateSpecs(filePaths, rulesConfig, silent = false) {
         const hashMatch = content.match(/<!-- vigiles:sha256:[a-f0-9]+ compiled from (.+) -->/);
         if (hashMatch) {
             // Verify the referenced spec still exists
-            const specRef = (0, node_path_1.resolve)(process.cwd(), hashMatch[1]);
+            const specRef = (0, node_path_1.resolve)(root, hashMatch[1]);
             if (!(0, node_fs_1.existsSync)(specRef)) {
                 log(`  ✗ [require-instructions-spec] ${filePath} references "${hashMatch[1]}" but that spec no longer exists.`);
                 allValid = false;
             }
             continue;
         }
+        // The path as discovered (cwd-relative), not `fullPath`: the finding prints
+        // it, and its `exclude` snippet must be a root-relative glob.
         const result = (0, validate_js_1.validate)(content, {
-            filePath: fullPath,
-            rules: rulesConfig,
+            filePath,
+            // The two spec-presence rules resolved at THIS file (`overrides`), the
+            // rest as configured — validate reads only these two per file.
+            rules: {
+                ...rulesConfig,
+                "require-instructions-spec": rules.severityAt("require-instructions-spec", filePath),
+                "require-skill-spec": rules.severityAt("require-skill-spec", filePath),
+            },
         });
         for (const err of result.errors) {
             log(`  ✗ [${err.rule}] ${err.message}`);
@@ -768,10 +797,10 @@ function validateSpecs(filePaths, rulesConfig, silent = false) {
     }
     return allValid;
 }
-function check(frame, filePaths, silent = false) {
-    const hashes = verifyHashes(frame, filePaths, silent);
-    const vConfig = (0, validate_js_1.loadConfig)();
-    const specsValid = validateSpecs(filePaths, vConfig.rules, silent);
+function check(root, frame, filePaths, silent = false) {
+    const hashes = verifyHashes(root, frame, filePaths, silent);
+    const vConfig = (0, validate_js_1.loadConfig)(root);
+    const specsValid = validateSpecs(root, filePaths, vConfig.rules, (0, overrides_js_1.ruleResolver)(vConfig.rules, vConfig.overrides), silent);
     return {
         valid: hashes.valid && specsValid,
         hashErrors: hashes.errorCount,
@@ -787,7 +816,8 @@ function check(frame, filePaths, silent = false) {
  * Catches spec bloat — rules that likely say the same thing in different words.
  * Uses information-theoretic distance (gzip-based) — no LLM, fully deterministic.
  */
-async function findDuplicateRules(excludes, threshold = 0.3, silent = false, scopeFiles) {
+async function findDuplicateRules(excludes, threshold = 0.3, silent = false, scopeFiles, severityAt = () => "warn") {
+    const root = excludes.root;
     const log = (msg) => {
         if (!silent)
             console.log(msg);
@@ -810,28 +840,33 @@ async function findDuplicateRules(excludes, threshold = 0.3, silent = false, sco
             for (const f of scopeFiles) {
                 let resolved;
                 try {
-                    const content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), f), "utf-8");
+                    const content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(root, f), "utf-8");
                     const m = compiledFromRe.exec(content);
                     if (m) {
-                        resolved = (0, node_path_1.resolve)(process.cwd(), m[1].trim());
+                        resolved = (0, node_path_1.resolve)(root, m[1].trim());
                     }
                 }
                 catch {
                     // File unreadable — fall through to the naming convention
                 }
                 if (!resolved) {
-                    resolved = (0, node_path_1.resolve)(process.cwd(), `${f}.spec.ts`);
+                    resolved = (0, node_path_1.resolve)(root, `${f}.spec.ts`);
                 }
                 wanted.add(resolved);
             }
-            return allSpecs.filter((specPath) => wanted.has((0, node_path_1.resolve)(process.cwd(), specPath)));
+            return allSpecs.filter((specPath) => wanted.has((0, node_path_1.resolve)(root, specPath)));
         })()
         : allSpecs;
     if (specs.length === 0)
-        return { valid: true, pairCount: 0 };
+        return { valid: true, pairCount: 0, errorPairs: 0 };
     let totalPairs = 0;
+    let errorPairs = 0;
     let specsWithDuplicates = 0;
     for (const specPath of specs) {
+        // Per spec: an `overrides` entry may turn `duplicate-rules` off for it.
+        const sev = severityAt(specPath);
+        if (sev === false)
+            continue;
         const spec = await loadSpec(specPath);
         if (!spec || spec._specType !== "claude")
             continue;
@@ -847,6 +882,8 @@ async function findDuplicateRules(excludes, threshold = 0.3, silent = false, sco
         }
         specsWithDuplicates++;
         totalPairs += pairs.length;
+        if (sev === "error")
+            errorPairs += pairs.length;
         log(`  ${specPath}`);
         for (const pair of pairs.slice(0, 5)) {
             log(`    ${pair.idA}  ↔  ${pair.idB}  (distance: ${pair.distance.toFixed(3)})`);
@@ -857,10 +894,10 @@ async function findDuplicateRules(excludes, threshold = 0.3, silent = false, sco
     }
     if (totalPairs === 0) {
         log("No near-duplicate rules detected.");
-        return { valid: true, pairCount: 0 };
+        return { valid: true, pairCount: 0, errorPairs: 0 };
     }
     log(`\n  ${String(totalPairs)} duplicate pair(s) in ${String(specsWithDuplicates)} spec(s). Consider merging or rewording.`);
-    return { valid: false, pairCount: totalPairs };
+    return { valid: false, pairCount: totalPairs, errorPairs };
 }
 /**
  * Verify the file-qualified symbol references (`path.ext#symbol`) in instruction
@@ -1005,12 +1042,12 @@ function lintExitCode(report) {
         report.skillFrontmatterErrors > 0 ||
         report.mcpToolErrors > 0 ||
         report.hookScriptErrors > 0 ||
+        report.handWrittenHookErrors > 0 ||
         report.disallowedToolErrors > 0 ||
         report.descriptionOverlapErrors > 0 ||
         report.descriptionBudgetErrors > 0 ||
         report.frontmatterValidErrors > 0 ||
         report.mcpHookErrors > 0 ||
-        report.preferCompiledHookErrors > 0 ||
         report.lethalTrifectaErrors > 0 ||
         report.skillResourceErrors > 0 ||
         report.skillFenceErrors > 0 ||
@@ -1338,6 +1375,31 @@ function discoverNestedBundles(root, excludes) {
     }
     return out.sort();
 }
+/**
+ * Each finding with the severity `rule` has at its path (`overrides`
+ * applied), the ones an override turns off removed. `pathOf` returns
+ * `undefined` for a finding about the repository as a whole, which keeps the
+ * severity `rules` gives it.
+ */
+function graded(rules, rule, found, pathOf) {
+    return found.flatMap((f) => {
+        const sev = rules.severityAt(rule, pathOf(f));
+        return sev === false ? [] : [{ ...f, sev }];
+    });
+}
+/** The `{ issues, errors }` a per-surface check returns, from its graded findings. */
+function tally(found) {
+    return {
+        issues: found.length,
+        errors: found.filter((f) => f.sev === "error").length,
+    };
+}
+/** The terminal mark and annotation level for a severity. */
+function markOf(sev) {
+    return sev === "error"
+        ? { mark: "✗", level: "error" }
+        : { mark: "⚠", level: "warning" };
+}
 /**
  * Run one per-surface check over EVERY bundle and sum its counters.
  *
@@ -1397,13 +1459,13 @@ function overBundles(fn, run, bundles) {
  * Cost is bounded: only specs whose compiled target actually EXISTS are loaded,
  * so a repo with no specs does no extra work at all.
  */
-async function checkSpecRefs(excludes, config, silent, dialect) {
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["spec-refs"]) ?? "error";
-    // `compile-budget` is reported here only at "error": at its default it is a
-    // compile-time warning, and `lint` printed nothing about size before the rule
-    // had a name — the default output does not change.
-    const budgetGate = (0, types_js_1.ruleSeverity)(config?.rules?.["compile-budget"]) === "error";
-    if (!sev && !budgetGate)
+async function checkSpecRefs(excludes, config, rules, silent, dialect) {
+    // Both rules are resolved per compiled target below (`overrides`). The scan
+    // is skipped only when neither can fire anywhere. `compile-budget` is
+    // reported here only at "error": at its default it is a compile-time
+    // warning, and `lint` printed nothing about size before the rule had a name
+    // — the default output does not change.
+    if (!rules.mayFire("spec-refs") && !rules.mayFire("compile-budget"))
         return { issues: 0, errors: 0, budgetErrors: 0 };
     const derived = [];
     let knownAgents;
@@ -1422,7 +1484,12 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
             derived.push({
                 target,
                 specPath,
-                findings: await specCompileErrors(spec, specPath, dialect, config, knownAgents ?? []),
+                findings: await specCompileErrors(spec, specPath, {
+                    root: excludes.root,
+                    dialect,
+                    config,
+                    knownAgents: knownAgents ?? [],
+                }),
             });
         }
         catch {
@@ -1431,50 +1498,32 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
             continue;
         }
     }
-    const messages = (pick) => derived.flatMap((d) => pick(d.findings).map((e) => `${d.target}: ${e.message} (from ${d.specPath})`));
-    const found = sev ? messages((f) => f.errors) : [];
-    const overBudget = messages((f) => f.budget);
+    const messages = (pick) => derived.flatMap((d) => pick(d.findings).map((e) => ({
+        target: d.target,
+        msg: `${d.target}: ${e.message} (from ${d.specPath})`,
+    })));
+    const found = graded(rules, "spec-refs", messages((f) => f.errors), (m) => m.target);
+    const overBudget = graded(rules, "compile-budget", messages((f) => f.budget), (m) => m.target).filter((m) => m.sev === "error");
     if (found.length > 0 && !silent) {
         console.log("\nSpec reference check:\n");
-        for (const msg of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${msg}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", msg);
+        for (const { msg, sev } of found) {
+            console.log(`  ${markOf(sev).mark} ${msg}`);
+            ghAnnotate(markOf(sev).level, msg);
         }
     }
     if (overBudget.length > 0 && !silent) {
         console.log("\nCompile budget check (compile-budget):\n");
-        overBudget.forEach((msg) => {
+        overBudget.forEach(({ msg }) => {
             console.log(`  ✗ ${msg}`);
             ghAnnotate("error", `compile-budget: ${msg}`);
         });
     }
-    return {
-        issues: found.length,
-        errors: sev === "error" ? found.length : 0,
-        budgetErrors: overBudget.length,
-    };
+    return { ...tally(found), budgetErrors: overBudget.length };
 }
-/**
- * The ONE spec-type dispatcher, in the only shape both directions can share:
- * errors, no writing. `compile` reaches its compilers through the
- * `compile*ToFile` wrappers (which write and print); `checkSpecRefs` reaches the
- * SAME compilers through this, because a read must never write.
- *
- * Why it exists (#190): `checkSpecRefs` used to call `compileClaude` directly and
- * skip every other spec type, so a SKILL.md / subagent / railway artifact
- * committed with a since-deleted reference hashed cleanly against its own header
- * forever — `lint` green, `compile` red. Measured on this repo:
- * `examples/SKILL.md.spec.ts` names `skills/enforce-rules-format/SKILL.md`, which
- * does not exist (the skill lives under `.claude/skills/`), and `lint` reported
- * `hash valid`.
- *
- * A switch rather than a per-type "ref accessor": all four compilers already
- * return the same `errors: CompileError[]`, so there is nothing to normalize —
- * only the options differ. Exhaustive over `_specType`, so a FIFTH spec type is
- * a tsc error here instead of a silent skip, which is the failure this closes.
- */
-async function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
-    const basePath = process.cwd();
+async function specCompileErrors(spec, specPath, { root, dialect, config, knownAgents }) {
+    const basePath = root;
+    // The compiled file this spec writes — `overrides` resolve at its path.
+    const target = specPath.replace(/\.spec\.ts$/, "");
     switch (spec._specType) {
         case "claude": {
             const r = await (0, compile_js_1.compileClaude)(spec, {
@@ -1486,7 +1535,7 @@ async function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
                 maxSectionLines: config?.maxSectionLines,
                 catalogOnly: config?.catalogOnly,
                 linters: config?.linters,
-                ...compileBudgetOptions(config),
+                ...compileBudgetOptions(config, target),
             });
             // A size finding is `compile-budget`'s, not a dead reference: split by
             // IDENTITY against the compiler's own list, never by the type's name.
@@ -1502,7 +1551,13 @@ async function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
             };
         case "agent":
             return {
-                errors: (await (0, compile_js_1.compileAgent)(spec, { basePath, specFile: specPath, dialect })).errors,
+                errors: (await (0, compile_js_1.compileAgent)(spec, {
+                    basePath,
+                    specFile: specPath,
+                    dialect,
+                    catalogOnly: config?.catalogOnly,
+                    linters: config?.linters,
+                })).errors,
                 budget: [],
             };
         case "railway":
@@ -1518,17 +1573,18 @@ async function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
     }
 }
 /**
- * The `compile-budget` rule, as `compileClaude` options: its severity and any
- * thresholds the config set. The ONE translation, so `compile` (which writes)
- * and `lint` (which re-derives) can never measure against different numbers.
+ * The `compile-budget` rule, as `compileClaude` options: its severity at the
+ * compiled `target` (`overrides` applied) and any thresholds `rules` set. The
+ * ONE translation, so `compile` (which writes) and `lint` (which re-derives)
+ * can never measure against different numbers.
  */
-function compileBudgetOptions(config) {
+function compileBudgetOptions(config, target) {
     const rule = config?.rules?.["compile-budget"];
     // No config at all (a programmatic caller, a missing file) is the default.
     if (rule === undefined)
         return { budgetSeverity: "warn" };
     return {
-        budgetSeverity: (0, types_js_1.ruleSeverity)(rule),
+        budgetSeverity: (0, overrides_js_1.ruleResolver)(config?.rules ?? validate_js_1.DEFAULT_RULES, config?.overrides).severityAt("compile-budget", target),
         ...(0, types_js_1.ruleOptions)(rule),
     };
 }
@@ -1545,6 +1601,8 @@ function writeArtifact(outputPath, artifact) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), artifact);
 }
 async function runLint(restArgs, flags, excludes, config) {
+    // The project root the CLI resolved once; the excludes are rooted at it.
+    const root = excludes.root;
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
@@ -1561,7 +1619,7 @@ async function runLint(restArgs, flags, excludes, config) {
         (0, node_fs_1.existsSync)(positional[0]) &&
         (0, node_fs_1.lstatSync)(positional[0]).isDirectory()
         ? (0, node_path_1.resolve)(positional[0])
-        : process.cwd();
+        : root;
     // Resolve the active harness ONCE so the harness-specific checks below run
     // against the right adapter's dialect (tool/event catalogs) and surfaces —
     // not a hard-coded Claude Code default. A subagent-surface rule reports n/a
@@ -1595,8 +1653,9 @@ async function runLint(restArgs, flags, excludes, config) {
     // ONE frame for the whole run (#281): every path a check prints or annotates is
     // relative to it, and config globs resolve from it — whichever bundle is being
     // scored. Built here, once, instead of each option re-deriving its own root.
-    const frame = (0, frame_js_1.frameFor)(process.cwd(), scanRoot);
-    const run = { config, silent, adapter, excludes, frame };
+    const frame = (0, frame_js_1.frameFor)(root, scanRoot);
+    const rules = (0, overrides_js_1.ruleResolver)(config?.rules ?? validate_js_1.DEFAULT_RULES, config?.overrides);
+    const run = { config, rules, silent, adapter, excludes, frame };
     if (!silent && nestedBundles.length > 0) {
         const rel = nestedBundles.map((b) => (0, node_path_1.relative)(scanRoot, b) || b);
         console.log(scoreAll
@@ -1622,7 +1681,7 @@ async function runLint(restArgs, flags, excludes, config) {
         }
     }
     const hashResult = files.length > 0
-        ? check(frame, files, silent)
+        ? check(root, frame, files, silent)
         : { valid: true, hashErrors: 0, validationErrors: 0 };
     // 1b. Verify inline + frontmatter rules in instruction files not managed
     // by a spec. See verifyMarkdownModeRules / docs/markdown-mode.md.
@@ -1637,16 +1696,15 @@ async function runLint(restArgs, flags, excludes, config) {
     // fail on unrelated duplicates elsewhere in the repo.
     if (!silent)
         console.log("\nDuplicate rule detection:\n");
-    const dups = await findDuplicateRules(excludes, 0.3, silent, restArgs.length > 0 ? files : undefined);
+    const dups = await findDuplicateRules(excludes, 0.3, silent, restArgs.length > 0 ? files : undefined, (specPath) => rules.severityAt("duplicate-rules", specPath));
     // 4. Guidance rule count (strengthen suggestions moved to /strengthen skill)
     const guidanceCount = await countGuidanceRules(excludes, silent);
     // 5. Integrity check (hand-edit detection via SHA-256 hash)
-    const integritySeverity = config?.rules.integrity ?? "warn";
     let integrityErrors = 0;
-    if (integritySeverity) {
+    if (rules.mayFire("integrity")) {
         if (!silent)
             console.log("\nIntegrity check:\n");
-        integrityErrors = checkIntegrityForFiles(files, integritySeverity, silent);
+        integrityErrors = checkIntegrityForFiles(root, files, rules, silent);
     }
     // 6. Coverage thresholds (gates CI when severity is "error")
     const coverageErrors = await checkCoverageThresholds(excludes, coverage, config, silent);
@@ -1664,8 +1722,7 @@ async function runLint(restArgs, flags, excludes, config) {
     // always-blocking check and deleting the `orphans` block. `warn` now reports
     // without touching the exit code and `false`/`"off"` skips the scan, exactly
     // like every other rule.
-    const orphanSeverity = (0, types_js_1.ruleSeverity)(config?.rules?.["orphan-docs"]) ?? "warn";
-    const orphansCfg = orphanSeverity ? config?.orphans : undefined;
+    const orphansCfg = rules.mayFire("orphan-docs") ? config?.orphans : undefined;
     if (!silent)
         console.log("\nOrphan docs check:\n");
     let orphanReport = {
@@ -1675,12 +1732,10 @@ async function runLint(restArgs, flags, excludes, config) {
         orphans: [],
     };
     if (orphansCfg) {
-        orphanReport = (0, orphans_js_1.findOrphanDocs)({
-            basePath: process.cwd(),
+        const found = (0, orphans_js_1.findOrphanDocs)({
+            basePath: root,
             include: orphansCfg.include,
-            exclude: orphansCfg.exclude,
-            // The repo-wide `exclude` is the FLOOR under the rule's own `exclude`
-            // (union, never override): an excluded corpus is neither an orphan
+            // The repo-wide `exclude`: an excluded corpus is neither an orphan
             // candidate nor a source of references that keep a doc alive (#192).
             repoExclude: excludes.globIgnore,
             // Exempt every registered harness's surface files (instruction file,
@@ -1688,6 +1743,10 @@ async function runLint(restArgs, flags, excludes, config) {
             // core carries no harness literal (see src/core/orphans.ts).
             layouts: adapter_registry_js_1.ADAPTERS.map((a) => a.layout),
         });
+        // Per doc: an `overrides` entry with `orphan-docs` off drops it from the
+        // report (it still counts as a doc that references others).
+        const orphanGraded = graded(rules, "orphan-docs", found.orphans.map((doc) => ({ doc })), (o) => o.doc);
+        orphanReport = { ...found, orphans: orphanGraded.map((o) => o.doc) };
         if (!silent) {
             for (const line of (0, orphans_js_1.formatOrphanReport)(orphanReport).split("\n")) {
                 console.log(`  ${line}`);
@@ -1702,7 +1761,7 @@ async function runLint(restArgs, flags, excludes, config) {
     // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
     // A compiled artifact's refs, re-derived from its spec — the hash says the file
     // is unchanged, not that what it names still exists (#173).
-    const specRefs = await checkSpecRefs(excludes, config, silent, adapter.dialect);
+    const specRefs = await checkSpecRefs(excludes, config, rules, silent, adapter.dialect);
     const untested = overBundles(checkUntestedSurfaces, run, lintRoots);
     // 7c. Subagent tool-contract check — cross-reference each subagent's `tools:`
     // rail against the harness catalog (the moat). n/a on a harness with no
@@ -1728,6 +1787,8 @@ async function runLint(restArgs, flags, excludes, config) {
     // validate`"; measured false on 2026-09-08 (Claude Code 2.1.263) — see
     // docs/rules/hook-script-exists.md and tools/measure-validate-overlap.mjs.
     const hookScripts = overBundles(checkHookScriptExists, run, lintRoots);
+    // 7i². Hand-written hooks — every hook line vigiles did not write, by name.
+    const handWrittenHooks = overBundles(checkHandWrittenHooks, run, lintRoots);
     // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
     // (the deny-side mirror of subagent-tool-contract; close-typo only).
     const disallowedTools = overBundles(checkDisallowedTools, run, lintRoots);
@@ -1744,9 +1805,6 @@ async function runLint(restArgs, flags, excludes, config) {
     // 7m. MCP hook-target — a `type: mcp_tool` hook action that's incomplete or
     // targets an undeclared server (the moat applied to the hook surface).
     const mcpHookTargets = overBundles(checkMcpHookTargets, run, lintRoots);
-    // 7n. Prefer-compiled-hooks — ONE discovery nudge (not per-hook) toward
-    // compiled `vigiles/hook` artifacts when hand-written hooks ship. Recommendation.
-    const preferCompiledHooks = overBundles(checkPreferCompiledHooks, run, lintRoots);
     // 7o. Lethal-trifecta — a unit (subagent / model-invocable skill) whose tools
     // hold all three legs (read-private + ingest-untrusted + exfiltrate) is a
     // prompt-injection exfil path (Rule of Two). Capability SET-intersection.
@@ -1792,11 +1850,12 @@ async function runLint(restArgs, flags, excludes, config) {
     // over the repository, like the ratchet: a nested bundle's spec would
     // otherwise be reported again by every bundle that encloses it.
     const deprecatedKeyFiles = (0, deprecated_key_files_js_1.checkDeprecatedKeyFiles)({
-        severity: (0, types_js_1.ruleSeverity)(config?.rules?.["deprecated-key-files"]),
-        find: () => specsUsingKeyFiles(process.cwd(), excludes.globIgnore),
+        severity: rules.mayFire("deprecated-key-files") ? "warn" : false,
+        severityAt: (path) => rules.severityAt("deprecated-key-files", path),
+        find: () => specsUsingKeyFiles(root, excludes.globIgnore),
         silent,
         annotate: (level, message, path) => {
-            ghAnnotate(level, message, frame.repo((0, node_path_1.resolve)(process.cwd(), path)));
+            ghAnnotate(level, message, frame.repo((0, node_path_1.resolve)(root, path)));
         },
     });
     // 8. Validate vigiles builder calls inside markdown code blocks — the
@@ -1819,7 +1878,7 @@ async function runLint(restArgs, flags, excludes, config) {
     // globs without `dot`, so `.claude/**` — where real skills and agents live —
     // has never been scanned. The rule has never once looked at a deployed
     // instruction file; every ref it has ever judged was in prose.
-    const docRefSeverity = (0, types_js_1.ruleSeverity)(config?.rules?.["doc-refs"]);
+    const docRefSeverity = rules.mayFire("doc-refs");
     if (!silent && docRefSeverity)
         console.log("\nMarkdown code block refs:\n");
     // 🔴 `config.exclude` REACHES THIS PASS. It did not, and that single omission is
@@ -1835,8 +1894,8 @@ async function runLint(restArgs, flags, excludes, config) {
     // With no way to reach 0 the step was made `continue-on-error: true`, and a lint
     // whose exit code is discarded gates nothing — after which hand-written CI steps
     // grew to do the gating instead. One unpassed argument, that whole chain.
-    const docRefReport = docRefSeverity
-        ? (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd(), ignore: excludes.globIgnore })
+    const docRefFound = docRefSeverity
+        ? (0, doc_refs_js_1.findDocRefs)({ basePath: root, ignore: excludes.globIgnore })
         : {
             filesScanned: 0,
             filesIgnored: 0,
@@ -1846,10 +1905,24 @@ async function runLint(restArgs, flags, excludes, config) {
             unverified: 0,
             placeholders: 0,
         };
+    // Per file: an `overrides` entry may turn `doc-refs` off, or set its
+    // severity, for a folder. Printed once per severity present, so a `✗` never
+    // stands next to a finding that does not gate.
+    const docRefErrors = graded(rules, "doc-refs", docRefFound.errors, (e) => e.file);
+    const docRefReport = { ...docRefFound, errors: docRefErrors };
     if (!silent && docRefSeverity) {
-        const rendered = (0, doc_refs_js_1.formatDocRefReport)(docRefReport, docRefSeverity === "error" ? "error" : "warn");
-        for (const line of rendered.split("\n")) {
-            console.log(`  ${line}`);
+        const groups = ["error", "warn"]
+            .map((sev) => ({
+            sev,
+            errors: docRefErrors.filter((e) => e.sev === sev),
+        }))
+            .filter((g, i, all) => g.errors.length > 0 ||
+            (i === 0 && all.every((x) => x.errors.length === 0)));
+        for (const g of groups) {
+            const rendered = (0, doc_refs_js_1.formatDocRefReport)({ ...docRefFound, errors: g.errors }, g.sev);
+            for (const line of rendered.split("\n")) {
+                console.log(`  ${line}`);
+            }
         }
     }
     // Per-line GitHub annotations for each broken doc ref — each carries file+line,
@@ -1859,7 +1932,7 @@ async function runLint(restArgs, flags, excludes, config) {
     // on the PR. CI-only (isGitHubActions); skipped under --json/--summary.
     if (isGitHubActions() && !silent && docRefSeverity) {
         for (const e of docRefReport.errors) {
-            ghAnnotate(docRefSeverity === "error" ? "error" : "warning", `${e.kind}("${e.value}") — ${e.message}`, frame.repo((0, node_path_1.resolve)(process.cwd(), e.file)), e.line);
+            ghAnnotate(markOf(e.sev).level, `${e.kind}("${e.value}") — ${e.message}`, frame.repo((0, node_path_1.resolve)(root, e.file)), e.line);
         }
     }
     // 9. Verify code-shaped symbol references live (see src/refs.ts).
@@ -1878,14 +1951,16 @@ async function runLint(restArgs, flags, excludes, config) {
         specRefErrors: specRefs.errors,
         compileBudgetErrors: specRefs.budgetErrors,
         duplicatePairs: dups.pairCount,
-        duplicateSeverity: (0, types_js_1.ruleSeverity)(config?.rules?.["duplicate-rules"]) ?? "warn",
+        duplicateSeverity: dups.errorPairs > 0 ? "error" : "warn",
         coverageEnabled: coverage.enabled,
         coverageDocumented: coverage.documented,
         strengthenSuggestions: guidanceCount,
         integrityErrors,
         coverageErrors,
         orphanCount: orphanReport.orphans.length,
-        orphanSeverity: orphanSeverity,
+        orphanSeverity: orphanReport.orphans.some((doc) => rules.severityAt("orphan-docs", doc) === "error")
+            ? "error"
+            : "warn",
         untestedSurfaces: untested.untested,
         untestedErrors: untested.errors,
         toolContractIssues: toolContract.issues,
@@ -1902,6 +1977,8 @@ async function runLint(restArgs, flags, excludes, config) {
         mcpToolErrors: mcpToolResolves.errors,
         hookScriptIssues: hookScripts.issues,
         hookScriptErrors: hookScripts.errors,
+        handWrittenHookIssues: handWrittenHooks.issues,
+        handWrittenHookErrors: handWrittenHooks.errors,
         disallowedToolIssues: disallowedTools.issues,
         disallowedToolErrors: disallowedTools.errors,
         descriptionOverlapIssues: descriptionOverlap.issues,
@@ -1912,8 +1989,6 @@ async function runLint(restArgs, flags, excludes, config) {
         frontmatterValidErrors: frontmatterValid.errors,
         mcpHookIssues: mcpHookTargets.issues,
         mcpHookErrors: mcpHookTargets.errors,
-        preferCompiledHookIssues: preferCompiledHooks.issues,
-        preferCompiledHookErrors: preferCompiledHooks.errors,
         lethalTrifectaIssues: lethalTrifecta.issues,
         lethalTrifectaErrors: lethalTrifecta.errors,
         skillResourceIssues: skillResources.issues,
@@ -1935,7 +2010,7 @@ async function runLint(restArgs, flags, excludes, config) {
         // Only the "error" tier gates. At "warn" the findings are printed and
         // annotated, and the exit code is untouched — same contract as every other
         // opt-in rule here.
-        docRefErrors: docRefSeverity === "error" ? docRefReport.errors.length : 0,
+        docRefErrors: docRefErrors.filter((e) => e.sev === "error").length,
         symbolRefErrors,
         mcpRefErrors,
         files,
@@ -2021,10 +2096,9 @@ function collectDocumentedRules(excludes) {
     });
     for (const mdFile of mdFiles) {
         const content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), mdFile), "utf-8");
-        const enforcedRe = /\*\*Enforced by:\*\*\s*`([^`]+)`/g;
-        let m;
-        while ((m = enforcedRe.exec(content)) !== null) {
-            documented.add(m[1]);
+        // Both compiled spellings (#351): an unverified claim is still documented.
+        for (const m of content.matchAll(new RegExp(enforce_marker_js_1.RULE_MARKER_SOURCE, "g"))) {
+            documented.add(m[2]);
         }
     }
     return documented;
@@ -2079,10 +2153,12 @@ function discover(excludes, silent = false) {
     }
     const totalPct = totalEnabled > 0 ? Math.round((totalDocumented / totalEnabled) * 100) : 0;
     log(`Coverage: ${String(totalDocumented)}/${String(totalEnabled)} rules documented (${String(totalPct)}%)`);
-    if (totalDocumented < totalEnabled) {
-        log(`\nConsider adding enforce() rules for frequently-triggered undocumented rules.`);
-        log(`The agent encounters these rules but has no context about WHY.`);
-    }
+    const advice = (0, coverage_js_1.undocumentedRulesAdvice)({
+        enabled: totalEnabled,
+        documented: totalDocumented,
+    });
+    if (advice.length > 0)
+        log(["", ...advice].join("\n"));
     return { enabled: totalEnabled, documented: totalDocumented };
 }
 /** This package's own version (from the installed package.json). */
@@ -2178,21 +2254,40 @@ function discoverAdoptableSurfaces(cwd) {
     }
     return out;
 }
-/** The full adoptable-surface list `audit` reports: the instruction file (when it
- * exists hand-written, no spec) PLUS every skill/subagent surface without a spec.
- * Same notion `init` adopts; surfaced in the AuditReport + the terminal nudge so
- * the report's "Create spec" / "Create all specs" affordances have their paths.
- * Composition-root only — CC paths are intentional here (like discoverAdoptableSurfaces). */
-function discoverAdoptableForAudit(root, instructionFile) {
-    const out = [];
-    const instrAbs = (0, node_path_1.resolve)(root, instructionFile);
-    if ((0, node_fs_1.existsSync)(instrAbs) &&
-        !targetHasHash(instrAbs) &&
-        !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, `${instructionFile}.spec.ts`))) {
-        out.push(instructionFile);
-    }
-    out.push(...discoverAdoptableSurfaces(root));
-    return out;
+/** Every hand-written instruction file under `root` — root AND nested
+ * `CLAUDE.md` / `AGENTS.md`, the same files `gatherInstructionFiles` reads —
+ * by the one predicate `lint`'s `require-instructions-spec` asks
+ * (`instructionSpecState`). Measured on a repo with six hand-written files
+ * (root + five nested): `audit` counted 1 (root only) while `lint` warned about
+ * all six. A spec-managed or opted-out file is not listed. */
+function handWrittenInstructionFiles(root, instructionFile, excludes, rules) {
+    return (gatherInstructionFiles(root, instructionFile, excludes)
+        .filter((f) => (0, integrity_js_1.instructionSpecState)(f.text, (0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, `${f.path}.spec.ts`))) === "hand-written")
+        // A folder an `overrides` entry turned the rule off for keeps its files
+        // hand-written on purpose: that decline is remembered, not re-offered.
+        .filter((f) => rules.severityAt("require-instructions-spec", f.path) !== false)
+        .map((f) => f.path));
+}
+/** The hand-written instruction files BELOW the root — the ones `init`'s
+ * root-level `determineTargets` does not see. Bare `init` adopts them too, so a
+ * repo it sets up passes `require-instructions-spec` (in `vigiles:recommended`)
+ * on its first `lint`. Read with the repo's own `exclude`. */
+function nestedHandWrittenInstructionFiles(cwd) {
+    const config = (0, validate_js_1.loadConfig)();
+    return handWrittenInstructionFiles(cwd, adapter_registry_js_1.defaultAdapter.layout.instructionFile, (0, exclude_js_1.excludeSet)(cwd, config.exclude), (0, overrides_js_1.ruleResolver)(config.rules, config.overrides)).filter((p) => p.includes("/"));
+}
+/** The full adoptable-surface list `audit` reports: every hand-written
+ * instruction file (nested included) PLUS every skill/subagent surface without
+ * a spec. Same notion `init` adopts; surfaced in the AuditReport + the terminal
+ * nudge so the report's "Create spec" / "Create all specs" affordances have
+ * their paths. Composition-root only — CC paths are intentional here (like
+ * discoverAdoptableSurfaces). */
+function discoverAdoptableForAudit(root, { instructionFile, excludes, config, }) {
+    const rules = (0, overrides_js_1.ruleResolver)(config.rules, config.overrides);
+    return [
+        ...handWrittenInstructionFiles(root, instructionFile, excludes, rules),
+        ...discoverAdoptableSurfaces(root),
+    ].filter((p) => !(0, exclude_js_1.excludedBy)(excludes)((0, node_path_1.resolve)(root, p)));
 }
 /** Lint-config file BASENAMES whose CONTENTS (textual, NEVER executed) reveal
  * which rules a repo has configured — read best-effort for the rule-inventory
@@ -2425,32 +2520,47 @@ function computeRuleRouting(root, instructionFile, excludes) {
         return undefined;
     }
 }
-/** The terminal "adoptable surfaces" nudge — N un-spec'd surfaces + the create-all
- * command and up to ~5 per-surface commands (then "+K more"). "" when nothing to
+/** The terminal "adoptable surfaces" nudge. Instruction files are listed in
+ * full (up to {@link NUDGE_LIST_CAP}) with the shared adoption remedy — they
+ * have two adopters, `init --target` and the `adopt-spec` skill; skills and
+ * subagents keep the per-surface `init --target` command. "" when nothing to
  * adopt (a fully spec-managed repo says nothing). */
 function formatAdoptableNudge(surfaces) {
     if (surfaces.length === 0)
         return "";
+    const instructions = surfaces.filter((s) => surfaceKind(s) === "instruction");
+    const others = surfaces.filter((s) => surfaceKind(s) !== "instruction");
     const n = surfaces.length;
+    const capped = (items, line) => {
+        const shown = items.slice(0, NUDGE_LIST_CAP).map(line);
+        const more = items.length - shown.length;
+        return more > 0
+            ? [...shown, `    • +${String(more)} more (all in --json)`]
+            : shown;
+    };
     // Lead with the VALUE, not the chore: a spec is the pull up from the gate to
     // the richer layer, so say what it BUYS (drift-proof references + testable),
     // not just "create one". The invitation is where richer-feature adoption is
     // won — keep it compelling, never a bare to-do (research/adoption-design.md §1).
     const lines = [
         `ℹ ${String(n)} surface${n === 1 ? "" : "s"} could be spec-managed — a spec re-verifies its references on every change (a hand-edit can't silently break them) and makes it testable.`,
-        `  Adopt now, or one at a time with \`npx vigiles init --target=<path>\`:`,
     ];
-    const shown = surfaces.slice(0, 5);
-    for (const s of shown)
-        lines.push(`    • npx vigiles init --target=${s}`);
-    const more = n - shown.length;
-    if (more > 0)
-        lines.push(`    • +${String(more)} more`);
+    if (instructions.length > 0) {
+        const k = instructions.length;
+        lines.push(`  ${String(k)} hand-written instruction file${k === 1 ? "" : "s"}:`, ...capped(instructions, (s) => `    • ${s}`), ...(0, instruction_remedies_js_1.adoptInstructionFileRemedy)("<path>")
+            .split("\n")
+            .map((l) => `  ${l}`));
+    }
+    if (others.length > 0) {
+        lines.push(`  Skills and subagents, one at a time with \`npx vigiles init --target=<path>\`:`, ...capped(others, (s) => `    • npx vigiles init --target=${s}`));
+    }
     // The remembered-decline affordance (non-evil contract): one keystroke to
     // silence, stated where it's shown so it's never a surprise nag.
     lines.push(`  (set "nudge": "dismissed" in .vigilesrc.json to hide this)`);
     return lines.join("\n");
 }
+/** How many paths one group of the adoption nudge prints before "+N more". */
+const NUDGE_LIST_CAP = 10;
 /** A small, terse behavioral nudge — the deterministic read can't tell whether a
  * skill actually FIRES. "" when there are no model-invocable skills. */
 function formatTriggerNudge(triggerableSkills) {
@@ -3168,7 +3278,11 @@ async function setupPillar1(detected, targetValue, harnesses) {
     // file. An explicit --target stays scoped to that one surface.
     const targets = targetValue
         ? instructionTargets
-        : [...instructionTargets, ...discoverAdoptableSurfaces(cwd)];
+        : [
+            ...instructionTargets,
+            ...nestedHandWrittenInstructionFiles(cwd).filter((p) => !instructionTargets.includes(p)),
+            ...discoverAdoptableSurfaces(cwd),
+        ];
     // Create specs. An existing hand-written target is faithfully ADOPTED into a
     // spec (scaffoldSpec() does the convert), not clobbered with a blank one — so the
     // compile below reproduces it (the user reviews the diff). A greenfield target
@@ -3199,6 +3313,7 @@ async function setupPillar1(detected, targetValue, harnesses) {
     for (const l of typesResult.linters) {
         console.log(`  ${l.linter}: ${String(l.rules.length)} rules`);
     }
+    printUnreadableLinters(typesResult.unreadable);
     if (typesResult.scripts.length > 0) {
         console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
     }
@@ -3811,6 +3926,7 @@ async function setup(args) {
         strict,
         reportOnly: parsed.reportOnly,
         lint: plan.lint,
+        specs: plan.scaffoldSpecs,
         written,
     });
     printSetupSummary({
@@ -3930,6 +4046,7 @@ function fullSetupGap(plan, detected, harnesses) {
     const unspecced = pillar1
         ? [
             ...determineTargets(detected, undefined, [...harnesses]),
+            ...nestedHandWrittenInstructionFiles(cwd),
             ...discoverAdoptableSurfaces(cwd),
         ].filter((t, i, all) => all.indexOf(t) === i && !has(`${t}.spec.ts`))
         : [];
@@ -4010,6 +4127,7 @@ function writeProjectConfig(opts) {
         strict: opts.strict,
         reportOnly: opts.reportOnly,
         lint: opts.lint,
+        specs: opts.specs,
     });
     if (!merged)
         return;
@@ -4022,31 +4140,34 @@ function writeProjectConfig(opts) {
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
 // ---------------------------------------------------------------------------
-function checkIntegrityForFiles(files, severity, silent) {
+function checkIntegrityForFiles(root, files, rules, silent) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
     };
-    let errorCount = 0;
-    const basePath = process.cwd();
-    for (const filePath of files) {
+    const basePath = root;
+    // Per file: an `overrides` entry may turn `integrity` off for a folder.
+    const checked = files.flatMap((filePath) => {
+        const severity = rules.severityAt("integrity", filePath);
         const abs = (0, node_path_1.resolve)(basePath, filePath);
-        if (!(0, node_fs_1.existsSync)(abs))
-            continue;
+        if (severity === false || !(0, node_fs_1.existsSync)(abs))
+            return [];
         const result = (0, integrity_js_1.checkIntegrity)((0, node_fs_1.readFileSync)(abs, "utf-8"));
+        return [{ filePath, severity, result }];
+    });
+    for (const { filePath, severity, result } of checked) {
         if (!result.intact) {
-            errorCount++;
-            const marker = severity === "error" ? "✗" : "⚠";
-            log(`  ${marker} ${filePath} — ${result.reason ?? "tampered"}`);
+            log(`  ${markOf(severity).mark} ${filePath} — ${result.reason ?? "tampered"}`);
         }
         else if (!silent) {
             log(`  ✓ ${filePath}`);
         }
     }
-    if (errorCount === 0) {
+    const broken = checked.filter((c) => !c.result.intact);
+    if (broken.length === 0) {
         log("  All compiled files intact.");
     }
-    return severity === "error" ? errorCount : 0;
+    return broken.filter((c) => c.severity === "error").length;
 }
 /**
  * The layout of the harness this repo actually targets — `--harness=`/config/
@@ -4093,7 +4214,7 @@ const UNTESTED_RULE = {
 /**
  * The `untested-*` rules AS THE DETECTOR TAKES THEM: which kinds this repo
  * enabled, and the discovery options merged from whichever of the three rules
- * carries them (`include` / `exclude` / `testExtension` are shared).
+ * carries them (`include` / `testExtension` are shared).
  *
  * 🔴 ONE READER, BECAUSE THE SECOND ONE DRIFTED. `vigiles lint` read the config
  * here; the PostToolUse nudge (`evalLockNudgeHookCommand`) called the same
@@ -4104,25 +4225,24 @@ const UNTESTED_RULE = {
  * while the nudge said "no test or eval covers it". A nudge contradicting the
  * linter of the same repo, in the same second, teaches people to ignore both.
  */
-function untestedRules(config) {
-    const rules = config?.rules;
-    const severity = (kind) => (0, types_js_1.ruleSeverity)(rules?.[UNTESTED_RULE[kind]]);
+function untestedRules(config, rules) {
     const names = Object.values(UNTESTED_RULE);
     const opts = names.reduce((acc, rule) => ({
         ...acc,
-        ...(0, types_js_1.ruleOptions)(rules?.[rule]),
+        ...(0, types_js_1.ruleOptions)(config?.rules?.[rule]),
     }), {});
-    const on = (kind) => severity(kind) !== false;
+    // A kind is SCANNED when its rule can fire anywhere — an override may turn
+    // it on for one folder while `rules` has it off.
+    const on = (kind) => rules.mayFire(UNTESTED_RULE[kind]);
     return {
-        severity,
-        anyEnabled: names.some((rule) => (0, types_js_1.ruleSeverity)(rules?.[rule]) !== false),
+        severity: (kind, path) => rules.severityAt(UNTESTED_RULE[kind], path),
+        anyEnabled: names.some((rule) => rules.mayFire(rule)),
         options: {
             skills: on("skill"),
             agents: on("agent"),
             hooks: on("hook"),
             outputStyles: on("output-style"),
             include: opts.include,
-            exclude: opts.exclude,
             // Without this the `testExtension` documented on TestCoverageOptions was a
             // config key nothing read: a TypeScript-shaped repo got `.ts` suggestions
             // however the author configured it. Prose isn't policy, in our own CLI.
@@ -4139,33 +4259,37 @@ function untestedRules(config) {
  */
 function checkUntestedSurfaces(ctx) {
     const { config, silent, adapter, frame, bundle } = ctx;
-    const { severity: sevFor, anyEnabled, options } = untestedRules(config);
+    const { severity: sevFor, anyEnabled, options, } = untestedRules(config, ctx.rules);
     if (!anyEnabled)
         return { untested: 0, errors: 0 };
-    const report = (0, test_coverage_js_1.findUntestedSurfaces)({
+    const scanned = (0, test_coverage_js_1.findUntestedSurfaces)({
         ...options,
         basePath: bundle.abs,
-        // #281: `include`/`exclude` and every reported path are relative to the
+        // #281: `include` and every reported path are relative to the
         // frame root (where `.vigilesrc.json` lives), not to the bundle being scored.
         root: frame.root,
         layout: adapter.layout,
-        // The rule's own `exclude` NARROWS; the repo-wide one is the floor under
-        // it. Union, never override — a rule option must not re-admit a vendored
-        // corpus the repo excluded (#192). Passed WHOLE so it carries its own root.
+        // The repo-wide `exclude` — passed WHOLE so it carries its own root (#192).
         excludes: ctx.excludes,
     });
+    // Per surface: an `overrides` entry may turn its kind's rule off for a folder.
+    const untested = scanned.untested.flatMap((s) => {
+        const sev = sevFor(s.kind, s.path);
+        return sev === false ? [] : [{ ...s, sev }];
+    });
+    const report = { ...scanned, untested };
     if (!silent) {
         console.log("\nUntested surfaces:\n");
         for (const line of (0, test_coverage_js_1.formatUntestedReport)(report).split("\n")) {
             console.log(`  ${line}`);
         }
         for (const s of report.untested) {
-            ctx.annotate(sevFor(s.kind) === "error" ? "error" : "warning", `${s.kind} ${s.path} ships without a test or eval`, frame.repo((0, node_path_1.join)(frame.root, s.path)));
+            ctx.annotate(markOf(s.sev).level, `${s.kind} ${s.path} ships without a test or eval`, frame.repo((0, node_path_1.join)(frame.root, s.path)));
         }
     }
     return {
         untested: report.untested.length,
-        errors: report.untested.filter((s) => sevFor(s.kind) === "error").length,
+        errors: untested.filter((s) => s.sev === "error").length,
     };
 }
 /**
@@ -4190,9 +4314,8 @@ function reportNotApplicable(check, surface, adapter, silent) {
  * `subagent-tool-contract: "error"` to gate CI. Returns the issue + error counts.
  */
 function checkSubagentToolContracts(ctx) {
-    const { config, silent, adapter } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-tool-contract"]);
-    if (!sev)
+    const { silent, adapter } = ctx;
+    if (!ctx.rules.mayFire("subagent-tool-contract"))
         return { issues: 0, errors: 0 };
     if (!adapter.subagents) {
         reportNotApplicable("Subagent tool-contract check", "subagents", adapter, silent);
@@ -4208,24 +4331,16 @@ function checkSubagentToolContracts(ctx) {
     catch {
         return { issues: 0, errors: 0 };
     }
-    let issues = 0;
-    let printedHeader = false;
-    for (const agent of agents) {
-        if (agent.toolIssues.length === 0)
-            continue;
-        issues += agent.toolIssues.length;
-        if (!silent) {
-            if (!printedHeader) {
-                console.log("\nSubagent tool-contract check:\n");
-                printedHeader = true;
-            }
-            for (const issue of agent.toolIssues) {
-                console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(agent.path)}: ${issue.message}`);
-                ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(agent.path));
-            }
+    const found = graded(ctx.rules, "subagent-tool-contract", agents.flatMap((a) => a.toolIssues.map((i) => ({ path: a.path, message: i.message }))), (f) => ctx.bundle.scanned(f.path));
+    if (found.length > 0 && !silent) {
+        console.log("\nSubagent tool-contract check:\n");
+        for (const issue of found) {
+            const at = ctx.bundle.scanned(issue.path);
+            console.log(`  ${markOf(issue.sev).mark} ${at}: ${issue.message}`);
+            ctx.annotate(markOf(issue.sev).level, issue.message, at);
         }
     }
-    return { issues, errors: sev === "error" ? issues : 0 };
+    return tally(found);
 }
 /**
  * Apply the `hook-events` rule: flag a hook registered under an event name the
@@ -4266,30 +4381,30 @@ function checkHookEvents(ctx) {
  * `frontmatterIssues` + `frontmatterValueIssues`. Warning by default; "error" gates CI.
  */
 function checkFrontmatterSchema(ctx) {
-    const { config, silent, adapter } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-frontmatter"]);
-    if (!sev)
+    const { silent, adapter } = ctx;
+    if (!ctx.rules.mayFire("subagent-frontmatter"))
         return { issues: 0, errors: 0 };
     if (!adapter.subagents) {
         reportNotApplicable("Subagent-frontmatter check", "subagents", adapter, silent);
         return { issues: 0, errors: 0 };
     }
-    let found;
+    let raw;
     try {
         const r = ctx.scan();
-        found = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
+        raw = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "subagent-frontmatter", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nFrontmatter-schema check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
+            console.log(`  ${markOf(issue.sev).mark} ${ctx.label(issue.message)}`);
+            ctx.annotate(markOf(issue.sev).level, issue.message, ctx.bundle.scanned(issue.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `skill-frontmatter` rule: RECOMMEND (not require) that a SKILL.md
@@ -4300,54 +4415,25 @@ function checkFrontmatterSchema(ctx) {
  * `skillMetaIssues`.
  */
 function checkSkillFrontmatter(ctx) {
-    const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-frontmatter"]);
-    if (!sev)
+    const { silent } = ctx;
+    if (!ctx.rules.mayFire("skill-frontmatter"))
         return { issues: 0, errors: 0 };
-    let found;
+    let raw;
     try {
-        found = ctx.scan().skillMetaIssues;
+        raw = ctx.scan().skillMetaIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "skill-frontmatter", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nSkill-frontmatter check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
+            console.log(`  ${markOf(issue.sev).mark} ${ctx.label(issue.message)}`);
+            ctx.annotate(markOf(issue.sev).level, issue.message, ctx.bundle.scanned(issue.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
-}
-/**
- * Apply the `prefer-compiled-hooks` rule: a SINGLE repo-level recommendation
- * (one finding regardless of hook count) nudging hand-written hooks toward
- * compiled `vigiles/hook` artifacts. A discovery nudge, not a defect — the shell
- * lane stays first-class — so it fires once and the message links the guide.
- * Reuses `scanPlugin`'s `manualHookCount` (one-detector-no-drift).
- */
-function checkPreferCompiledHooks(ctx) {
-    const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["prefer-compiled-hooks"]);
-    if (!sev)
-        return { issues: 0, errors: 0 };
-    let count;
-    try {
-        count = ctx.scan().manualHookCount;
-    }
-    catch {
-        return { issues: 0, errors: 0 };
-    }
-    if (count === 0)
-        return { issues: 0, errors: 0 };
-    const message = (0, scan_js_1.preferCompiledHooksMessage)(count);
-    if (!silent) {
-        console.log("\nCompiled-hooks check:\n");
-        console.log(`  ${sev === "error" ? "✗" : "ℹ"} ${ctx.label(message)}`);
-        ctx.annotate(sev === "error" ? "error" : "warning", message);
-    }
-    return { issues: 1, errors: sev === "error" ? 1 : 0 };
+    return tally(found);
 }
 /**
  * Apply the `mcp-config` rule: a declared MCP server with neither a `command`
@@ -4383,17 +4469,16 @@ function checkMcpConfig(ctx) {
  * "error" gates CI.
  */
 function checkDisallowedTools(ctx) {
-    const { config, silent, adapter } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["disallowed-tools-contract"]);
-    if (!sev)
+    const { silent, adapter } = ctx;
+    if (!ctx.rules.mayFire("disallowed-tools-contract"))
         return { issues: 0, errors: 0 };
     if (!adapter.subagents) {
         reportNotApplicable("Disallowed-tools check", "subagents", adapter, silent);
         return { issues: 0, errors: 0 };
     }
-    let found;
+    let raw;
     try {
-        found = ctx.scan().agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({
+        raw = ctx.scan().agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({
             message: i.message,
             path: a.path,
         })));
@@ -4401,14 +4486,15 @@ function checkDisallowedTools(ctx) {
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "disallowed-tools-contract", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nDisallowed-tools check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(issue.path)}: ${issue.message}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
+            console.log(`  ${markOf(issue.sev).mark} ${ctx.bundle.scanned(issue.path)}: ${issue.message}`);
+            ctx.annotate(markOf(issue.sev).level, issue.message, ctx.bundle.scanned(issue.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `frontmatter-valid` rule: a skill/agent `---` block that EXISTS but
@@ -4419,25 +4505,25 @@ function checkDisallowedTools(ctx) {
  * (verify before setting "error").
  */
 function checkFrontmatterValid(ctx) {
-    const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["frontmatter-valid"]);
-    if (!sev)
+    const { silent } = ctx;
+    if (!ctx.rules.mayFire("frontmatter-valid"))
         return { issues: 0, errors: 0 };
-    let found;
+    let raw;
     try {
-        found = ctx.scan().malformedFrontmatter;
+        raw = ctx.scan().malformedFrontmatter;
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "frontmatter-valid", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nFrontmatter-validity check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
+            console.log(`  ${markOf(issue.sev).mark} ${ctx.label(issue.message)}`);
+            ctx.annotate(markOf(issue.sev).level, issue.message, ctx.bundle.scanned(issue.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `description-overlap` rule: two model-invocable skills with
@@ -4512,38 +4598,40 @@ function checkDescriptionBudget(ctx) {
  * unaffected by the collapse.
  */
 function checkLethalTrifecta(ctx) {
-    const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["lethal-trifecta"]);
-    if (!sev)
+    const { silent } = ctx;
+    if (!ctx.rules.mayFire("lethal-trifecta"))
         return { issues: 0, errors: 0 };
-    let found;
+    let raw;
     try {
-        found = ctx.scan().trifectaFindings;
+        raw = ctx.scan().trifectaFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "lethal-trifecta", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
-        const mark = sev === "error" ? "✗" : "⚠";
-        const level = sev === "error" ? "error" : "warning";
         console.log("\nLethal-trifecta check:\n");
         const unfenced = found.filter((t) => t.kind === "skill" && t.finding.fence === "none");
         for (const t of found) {
             if (unfenced.includes(t))
                 continue;
             const msg = `${t.kind} ${t.name}: ${t.finding.message}`;
-            console.log(`  ${mark} ${ctx.bundle.scanned(t.path)}: ${msg}`);
-            ctx.annotate(level, msg, ctx.bundle.scanned(t.path));
+            console.log(`  ${markOf(t.sev).mark} ${ctx.bundle.scanned(t.path)}: ${msg}`);
+            ctx.annotate(markOf(t.sev).level, msg, ctx.bundle.scanned(t.path));
         }
         if (unfenced.length > 0) {
-            console.log(`  ${mark} ${String(unfenced.length)} skill(s) declare no \`disallowed-tools:\` fence, so each ` +
+            // One line for the group, at the worst severity any of its skills has.
+            const groupSev = unfenced.some((t) => t.sev === "error")
+                ? "error"
+                : "warn";
+            console.log(`  ${markOf(groupSev).mark} ${String(unfenced.length)} skill(s) declare no \`disallowed-tools:\` fence, so each ` +
                 `inherits every tool the session grants and holds all three legs. ` +
                 `\`allowed-tools:\` pre-approves, it does not restrict. ` +
                 `Add one \`disallowed-tools:\` line per skill to drop a leg: ` +
                 unfenced.map((t) => t.name).join(", "));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `skill-resource-resolves` rule: a SKILL.md body referencing a bundled
@@ -4554,12 +4642,11 @@ function checkLethalTrifecta(ctx) {
  */
 function checkSkillResourceResolves(ctx) {
     const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-resource-resolves"]);
-    if (!sev)
+    if (!ctx.rules.mayFire("skill-resource-resolves"))
         return { issues: 0, errors: 0 };
-    let found;
+    let raw;
     try {
-        found = ctx.scan({
+        raw = ctx.scan({
             sharedDirs: config?.sharedDirs,
             // sharedDirs live at the frame root — the repo that OWNS the scan target:
             // cwd for a scoped subdir or a nested bundle, the target for a foreign lint.
@@ -4569,6 +4656,7 @@ function checkSkillResourceResolves(ctx) {
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "skill-resource-resolves", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nSkill-resource check:\n");
         for (const s of found) {
@@ -4578,11 +4666,11 @@ function checkSkillResourceResolves(ctx) {
                 // it was documented only in docs/skills-monorepo.md, so a CI log gave no
                 // hint and the rule read as broken rather than misconfigured.
                 ` If it resolves from the repo root instead, add its directory to \`sharedDirs\` in .vigilesrc.json.`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(s.path)}: ${msg}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", msg, ctx.bundle.scanned(s.path));
+            console.log(`  ${markOf(s.sev).mark} ${ctx.bundle.scanned(s.path)}: ${msg}`);
+            ctx.annotate(markOf(s.sev).level, msg, ctx.bundle.scanned(s.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `skill-missing-fence` rule: a SKILL.md that opens with
@@ -4592,26 +4680,26 @@ function checkSkillResourceResolves(ctx) {
  * default; "error" gates CI.
  */
 function checkSkillMissingFence(ctx) {
-    const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-missing-fence"]);
-    if (!sev)
+    const { silent } = ctx;
+    if (!ctx.rules.mayFire("skill-missing-fence"))
         return { issues: 0, errors: 0 };
-    let found;
+    let raw;
     try {
-        found = ctx.scan().skillFenceIssues;
+        raw = ctx.scan().skillFenceIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "skill-missing-fence", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nSkill-missing-fence check:\n");
         for (const s of found) {
             const msg = `${s.name}: ${s.finding.message}`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(s.path)}: ${msg}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", msg, ctx.bundle.scanned(s.path));
+            console.log(`  ${markOf(s.sev).mark} ${ctx.bundle.scanned(s.path)}: ${msg}`);
+            ctx.annotate(markOf(s.sev).level, msg, ctx.bundle.scanned(s.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `plugin-dir-layout` rule: functional surface dirs (skills/agents/
@@ -4621,25 +4709,25 @@ function checkSkillMissingFence(ctx) {
  * gates CI.
  */
 function checkPluginDirLayout(ctx) {
-    const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["plugin-dir-layout"]);
-    if (!sev)
+    const { silent } = ctx;
+    if (!ctx.rules.mayFire("plugin-dir-layout"))
         return { issues: 0, errors: 0 };
-    let found;
+    let raw;
     try {
-        found = ctx.scan().pluginLayoutIssues;
+        raw = ctx.scan().pluginLayoutIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "plugin-dir-layout", raw, (f) => ctx.bundle.scanned(f.dir));
     if (found.length > 0 && !silent) {
         console.log("\nPlugin-dir-layout check:\n");
         for (const p of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(p.message)}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", p.message);
+            console.log(`  ${markOf(p.sev).mark} ${ctx.label(p.message)}`);
+            ctx.annotate(markOf(p.sev).level, p.message);
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `delegation-trifecta` rule: a lethal trifecta that EMERGES across a
@@ -4650,26 +4738,26 @@ function checkPluginDirLayout(ctx) {
  * capability the way a surface-specific rule is.
  */
 function checkDelegationTrifecta(ctx) {
-    const { config, silent } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["delegation-trifecta"]);
-    if (!sev)
+    const { silent } = ctx;
+    if (!ctx.rules.mayFire("delegation-trifecta"))
         return { issues: 0, errors: 0 };
-    let found;
+    let raw;
     try {
-        found = ctx.scan().delegationTrifecta;
+        raw = ctx.scan().delegationTrifecta;
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "delegation-trifecta", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nDelegation-trifecta check:\n");
         for (const d of found) {
             const msg = `${d.finding.name}: ${d.finding.message}`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(d.path)}: ${msg}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", msg, ctx.bundle.scanned(d.path));
+            console.log(`  ${markOf(d.sev).mark} ${ctx.bundle.scanned(d.path)}: ${msg}`);
+            ctx.annotate(markOf(d.sev).level, msg, ctx.bundle.scanned(d.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the `hook-block-ineffective` rule: a hook that LOOKS like it blocks but
@@ -4787,43 +4875,57 @@ function checkMcpHookTargets(ctx) {
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
 /**
- * Apply the `hook-script-exists` rule: a hook command references a script file
- * that doesn't exist on disk (with `${CLAUDE_PLUGIN_ROOT}` resolved) → the hook
- * silently never runs. Reuses `scanPlugin`'s `hooks` (status "missing"); the
- * shared resolver already excludes the FP-prone cases (unresolved vars,
- * existence-guarded one-liners, inline commands). Matches Anthropic's own
- * `claude plugin validate`. Warning by default; "error" gates CI.
+ * Apply the `hook-script-exists` rule: a file a COMPILED hook line needs is
+ * missing — the runtime, the program or its stamp — so the hook cannot run.
+ * The files come from the hook-line plan (`hookLinePlan`), never from reading a
+ * line: a line is compiled only by identity with what `compile` writes.
  */
 function checkHookScriptExists(ctx) {
+    return reportHookLines(ctx, "hook-script-exists", "Hook-script existence check", (scan) => [
+        ...scan.hooks
+            .filter((h) => h.status === "missing")
+            // `script` is absolute (the root variable resolved) — printed as-is it
+            // was a machine path (#281); `scanned` makes it the bundle's own.
+            .map((h) => (0, scan_js_1.hookScriptMissingMessage)(ctx.bundle.scanned(h.script))),
+        // A line vigiles wrote that is now wrong: its own wiring, so here.
+        ...scan.staleHooks.map(scan_js_1.staleHookMessage),
+    ]);
+}
+/**
+ * Apply the `hand-written-hook` rule: one finding per hook line vigiles did not
+ * write (or wrote and someone edited). vigiles never parses such a line, so it
+ * cannot say what it runs; the finding names it and points at compiled hooks.
+ */
+function checkHandWrittenHooks(ctx) {
+    return reportHookLines(ctx, "hand-written-hook", "Hand-written hooks", (scan) => scan.handWrittenHooks.map(scan_js_1.handWrittenHookMessage));
+}
+/** Print and count one hook-line rule's messages at its configured severity. */
+function reportHookLines(ctx, rule, heading, messagesOf) {
     const { config, silent, adapter } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-script-exists"]);
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.[rule]);
     if (!sev)
         return { issues: 0, errors: 0 };
     if (!adapter.shellHooks) {
-        reportNotApplicable("Hook-script existence check", "shell hooks", adapter, silent);
+        reportNotApplicable(heading, "shell hooks", adapter, silent);
         return { issues: 0, errors: 0 };
     }
-    let missing;
+    let messages;
     try {
-        missing = ctx.scan().hooks.filter((h) => h.status === "missing");
+        messages = messagesOf(ctx.scan());
     }
     catch {
         return { issues: 0, errors: 0 };
     }
-    if (missing.length > 0 && !silent) {
-        console.log("\nHook-script existence check:\n");
-        for (const h of missing) {
-            // `script` arrives with the plugin-root token EXPANDED, i.e. absolute —
-            // printed as-is it was a machine path (#281). A relative one is the
-            // bundle's own, which is what `scanned` assumes.
-            const msg = `hook script "${ctx.bundle.scanned(h.script)}" is referenced but missing — the hook never runs.`;
+    if (messages.length > 0 && !silent) {
+        console.log(`\n${heading}:\n`);
+        for (const msg of messages) {
             console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(msg)}`);
             ctx.annotate(sev === "error" ? "error" : "warning", msg);
         }
     }
     return {
-        issues: missing.length,
-        errors: sev === "error" ? missing.length : 0,
+        issues: messages.length,
+        errors: sev === "error" ? messages.length : 0,
     };
 }
 /**
@@ -4834,31 +4936,31 @@ function checkHookScriptExists(ctx) {
  * plugin-namespaced form skipped). Warning by default; "error" gates CI.
  */
 function checkMcpToolResolves(ctx) {
-    const { config, silent, adapter } = ctx;
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-tool-resolves"]);
-    if (!sev)
+    const { silent, adapter } = ctx;
+    if (!ctx.rules.mayFire("mcp-tool-resolves"))
         return { issues: 0, errors: 0 };
     if (!adapter.subagents) {
         reportNotApplicable("MCP tool-resolution check", "subagents", adapter, silent);
         return { issues: 0, errors: 0 };
     }
-    let found;
+    let raw;
     try {
-        found = ctx
+        raw = ctx
             .scan()
             .agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
     }
     catch {
         return { issues: 0, errors: 0 };
     }
+    const found = graded(ctx.rules, "mcp-tool-resolves", raw, (f) => ctx.bundle.scanned(f.path));
     if (found.length > 0 && !silent) {
         console.log("\nMCP tool-resolution check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(issue.path)}: ${issue.message}`);
-            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
+            console.log(`  ${markOf(issue.sev).mark} ${ctx.bundle.scanned(issue.path)}: ${issue.message}`);
+            ctx.annotate(markOf(issue.sev).level, issue.message, ctx.bundle.scanned(issue.path));
         }
     }
-    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+    return tally(found);
 }
 /**
  * Apply the configured coverage thresholds. Returns the number of failing
@@ -5082,6 +5184,17 @@ async function handleGenerate(restArgs, args) {
             process.exit(2);
     }
 }
+/**
+ * A linter whose config could not be read is missing from the generated types;
+ * say so on stderr (and as a CI annotation) instead of a silent short list.
+ */
+function printUnreadableLinters(unreadable) {
+    unreadable.forEach(({ linter, reason }) => {
+        const msg = `could not read the ${linter} config: ${reason} (its rules are not listed)`;
+        console.error(`  ⚠ ${msg}`);
+        console.error(`::warning::${msg}`);
+    });
+}
 function handleGenerateTypes(args, restArgs) {
     const checkOnly = args.includes("--check");
     const outPath = restArgs[0] ?? ".vigiles/generated.d.ts";
@@ -5097,6 +5210,7 @@ function handleGenerateTypes(args, restArgs) {
     for (const l of result.linters) {
         console.log(`  ${l.linter}: ${String(l.rules.length)} enabled rules (via ${l.via})`);
     }
+    printUnreadableLinters(result.unreadable);
     if (result.scripts.length > 0) {
         console.log(`  npm scripts: ${String(result.scripts.length)}`);
     }
@@ -6382,7 +6496,8 @@ function evalLockNudgeHookCommand() {
     // into a failed edit: the nudge not firing is the cheaper failure. The verbs
     // throw on the same config; what is CHECKED is identical.
     const config = (0, validate_js_1.loadConfig)(cwd, { onInvalid: "warn" });
-    const { options } = untestedRules(config);
+    const nudgeRules = (0, overrides_js_1.ruleResolver)(config.rules, config.overrides);
+    const { options } = untestedRules(config, nudgeRules);
     // 🔴 THE SAME LAYOUT `vigiles lint` RESOLVES, for the same reason as the config
     // above. This used to pass `basePath` alone, so the detector fell back to the
     // Claude Code layout: in a Codex repo whose surfaces live at
@@ -6397,9 +6512,8 @@ function evalLockNudgeHookCommand() {
     // heard nothing at all, while a repo that already tests got reminded. That is
     // backwards, and `untested-skill` already stated the missing half correctly;
     // it just lived in `vigiles lint`, which someone has to run by hand.
-    // Same union `vigiles lint` applies: the rule's exclude narrows, the
-    // repo-wide exclude is the floor (#192) — the nudge must not report a
-    // vendored skill the linter would never list.
+    // The repo-wide exclude `vigiles lint` applies (#192) — the nudge must not
+    // report a vendored skill the linter would never list.
     const excludes = (0, exclude_js_1.excludeSet)(cwd, config.exclude);
     // 🔴 THE BUNDLE THAT HOLDS THE EDIT, found the way `lint` finds it (#281, D6).
     // The nudge scanned the root bundle only and matched by SUFFIX, so an edit to
@@ -6416,13 +6530,18 @@ function evalLockNudgeHookCommand() {
             return r !== "" && !r.startsWith("..") && !(0, node_path_1.isAbsolute)(r);
         })
         : undefined) ?? cwd;
-    const msg = (0, test_coverage_js_1.skillTestNudge)(frame.repo(edited), {
-        ...options,
-        basePath: home,
-        root: cwd,
-        layout,
-        excludes,
-    }) ?? (0, eval_lock_js_1.evalLockNudge)(target, (0, node_path_1.resolve)(cwd, eval_lock_js_1.DEFAULT_LOCK_DIR));
+    // The same per-path answer `lint` gives: no untested nudge for a skill whose
+    // folder an `overrides` entry turned `untested-skill` off for.
+    const untestedHere = nudgeRules.severityAt("untested-skill", frame.repo(edited)) !== false;
+    const msg = (untestedHere
+        ? (0, test_coverage_js_1.skillTestNudge)(frame.repo(edited), {
+            ...options,
+            basePath: home,
+            root: cwd,
+            layout,
+            excludes,
+        })
+        : undefined) ?? (0, eval_lock_js_1.evalLockNudge)(target, (0, node_path_1.resolve)(cwd, eval_lock_js_1.DEFAULT_LOCK_DIR));
     if (!msg)
         return;
     process.stdout.write(JSON.stringify({
@@ -6462,7 +6581,10 @@ async function refsHookCommand() {
     // from the process's directory is how a disabled rule comes back to life.
     const cwd = runtimeRoot(eventRoot(raw));
     // A hook rail — see `evalLockNudgeHookCommand` for why it warns, not throws.
-    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)(cwd, { onInvalid: "warn" }).rules["unmarked-refs"]);
+    // Resolved at the edited file's own path, so an `overrides` entry that turns
+    // `unmarked-refs` off for a folder is honoured at edit time too.
+    const refsConfig = (0, validate_js_1.loadConfig)(cwd, { onInvalid: "warn" });
+    const severity = (0, overrides_js_1.ruleResolver)(refsConfig.rules, refsConfig.overrides).severityAt("unmarked-refs", (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)));
     if (severity === false)
         return;
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
@@ -6542,7 +6664,7 @@ async function compileProviders() {
  * the string the user typed — `x.hook.ts` and `./x.hook.ts` are the same wiring),
  * so recompiling updates in place and never clobbers the user's own hooks.
  */
-async function installHookFile(file, adapter, registeredProviders = []) {
+async function installHookFile(file, adapter, registeredProviders, runtime) {
     const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
     const program = await (0, hook_runtime_js_1.loadHookProgram)(file);
     // Emit the CANONICAL path so two spellings of the same file produce the same
@@ -6561,16 +6683,17 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         // cache, thirteen times, on every tool call. The `|| exit N` ending is what
         // the shell does when that file cannot start at all. `compileHookProgram`
         // adds it (see `hookRuntimeMissingExit`), so it is not written here.
-        gateCommand: `${(0, hook_install_js_1.hookRuntimeRef)(adapter.layout.projectRootTokens)} hook-runtime run-program ` +
-            (0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens),
+        gateCommand: (0, hook_command_js_1.runProgramCommand)((0, hook_command_js_1.hookRuntimeRef)(adapter.layout.projectRootTokens, runtime), (0, hook_command_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)),
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settings: adapter.layout.settings,
         registeredProviders,
     });
-    // Tamper-evident stamp beside the source (one dir → basename is unique).
+    // Tamper-evident stamp beside the source (one dir → basename is unique). The
+    // role is recorded with it: `lint` rebuilds the exact line compile writes
+    // from it (`hookLinePlan`), so a wired line is read by identity, not parsed.
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)((0, hook_runtime_js_1.hookStampPath)(file)), { recursive: true });
-    (0, node_fs_1.writeFileSync)((0, hook_runtime_js_1.hookStampPath)(file), JSON.stringify({ file, stamp: compiled.stamp }, null, 2) + "\n");
+    (0, node_fs_1.writeFileSync)((0, hook_runtime_js_1.hookStampPath)(file), JSON.stringify({ file, stamp: compiled.stamp, role: (0, hook_program_js_1.dispatchKind)(program) }, null, 2) + "\n");
     // Merge into the harness's native config, idempotently.
     //
     // 🔴 THREE FORMAT BRANCHES BECAME ZERO, and they were three because the ONE
@@ -6646,7 +6769,14 @@ async function installHookFile(file, adapter, registeredProviders = []) {
                     `yet automatic).`;
         }
     }
-    return { role, settingsPath: adapter.layout.settingsPath, warning };
+    // 🔴 `compiled.warnings` WAS COMPUTED AND NEVER PRINTED until 2026-10-11
+    // (#356): a degraded role/event fit reached the author's terminal by no
+    // path at all — a nudge with no delivery, inside the check for exactly that.
+    return {
+        role,
+        settingsPath: adapter.layout.settingsPath,
+        warnings: [...(compiled.warnings ?? []), ...(warning ? [warning] : [])],
+    };
 }
 /**
  * Compile + install every hook (explicit paths, else discovered under
@@ -6680,15 +6810,29 @@ async function installHooks(hookFiles, harnessFlag, configHarness, validateProvi
     }
     if (hookFiles.length === 0)
         return true; // providers validated; nothing to wire
+    // WHICH runtime the wiring starts — the installed package for a consumer, the
+    // package's own built bin when this IS vigiles (see `hookRuntimeFor`).
+    const runtime = (0, hook_install_js_1.readHookRuntime)(process.cwd());
+    // 🔴 SAY IT NOW, because nothing will later. A nudge whose runtime cannot
+    // start ends in `|| exit 0` by design, so from then on it is indistinguishable
+    // from a nudge with nothing to say. Measured 2026-10-11 on this repository:
+    // dead for three weeks, every gate green. Not an error — the file may arrive
+    // with the next install or build — but never silent.
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), runtime.path))) {
+        console.warn(`⚠ the hook runtime ${runtime.path} is not on disk — every hook compiled ` +
+            `here fails to load until it is: a reminder is skipped without a word, a ` +
+            `gate refuses every command. Run ${runtime.cure}.`);
+    }
     let ok = true;
     for (const file of hookFiles) {
         try {
             // Fan out: the same compiled hook lands in each enabled harness's config.
             for (const adapter of adapters) {
-                const r = await installHookFile(file, adapter, registeredProviders);
+                const r = await installHookFile(file, adapter, registeredProviders, runtime);
                 console.log(`✓ ${file} → ${r.settingsPath} (role: ${r.role}, harness: ${adapter.name})`);
-                if (r.warning)
-                    console.warn(`⚠ ${r.warning}`);
+                r.warnings.forEach((w) => {
+                    console.warn(`⚠ ${w}`);
+                });
             }
         }
         catch (e) {
@@ -7091,6 +7235,30 @@ async function askOnce(q) {
         rl.close();
     }
 }
+/**
+ * 🔴 THE PROJECT ROOT, resolved ONCE (#371) — the only place the CLI asks where
+ * it was started. Every command then runs from the root, so `vigiles lint` in
+ * `src/` reads the root's `.vigilesrc.json`, its overrides and its compiled
+ * files exactly as it does at the root, and passes the root on explicitly. A
+ * path the user typed means "from where I typed it", so path arguments are
+ * re-expressed from the root first (`PATH_ARGUMENTS` says which arguments are
+ * paths). `hook-runtime` is exempt: its cwd and argv come from the harness.
+ */
+function enterProjectRoot() {
+    const typed = process.argv.slice(2);
+    const [command = "", ...rest] = typed;
+    const invocationDir = process.cwd();
+    if (!(0, cli_flag_check_js_1.runsFromProjectRoot)(command))
+        return { command, projectRoot: invocationDir, args: typed };
+    const projectRoot = (0, frame_js_1.findProjectRoot)(invocationDir, node_fs_1.existsSync);
+    const args = [
+        command,
+        ...(0, cli_flag_check_js_1.rebasePathArgs)(command, rest, (p) => (0, frame_js_1.rebaseArg)(p, invocationDir, projectRoot)),
+    ];
+    if (projectRoot !== invocationDir)
+        process.chdir(projectRoot);
+    return { command, projectRoot, args };
+}
 /**
  * Persist the audit consent (`audit.measure`) into `.vigilesrc.json` without
  * clobbering existing keys — the "ask once, remember" sticky choice. Best-effort:
@@ -7120,8 +7288,7 @@ function rememberAuditMeasure(value) {
     }
 }
 async function main() {
-    const args = process.argv.slice(2);
-    const command = args[0];
+    const { command, projectRoot, args } = enterProjectRoot();
     // `--version` / `-v` / `version` prints the version number, not the help
     // banner — so `npx vigiles --version` reports e.g. `3.0.0`.
     if (command === "--version" || command === "-v" || command === "version") {
@@ -7156,11 +7323,11 @@ async function main() {
     const restArgs = args.slice(1).filter((a) => !a.startsWith("--"));
     // Shared flags (--max-rules, --catalog-only) override the loaded config so
     // every GitHub Action input maps to a real CLI flag. See src/cli-flags.ts.
-    const config = (0, cli_flags_js_1.applyConfigFlags)((0, validate_js_1.loadConfig)(), args);
+    const config = (0, cli_flags_js_1.applyConfigFlags)((0, validate_js_1.loadConfig)(projectRoot), args);
     // `.vigilesrc.json#exclude`, parsed ONCE here and threaded to every walk that
     // polices the repo (src/exclude.ts). Built where the config is loaded so a
     // command cannot re-derive it differently — the drift #192 measured.
-    const excludes = (0, exclude_js_1.excludeSet)(process.cwd(), config.exclude);
+    const excludes = (0, exclude_js_1.excludeSet)(projectRoot, config.exclude);
     switch (command) {
         // --- Primary commands ---
         case "init": {
@@ -7193,7 +7360,7 @@ async function main() {
             // is refused below, out loud, with the command that fixes it.
             const found = restArgs.length > 0
                 ? (0, hook_install_js_1.partitionHookArgs)(restArgs.filter((f) => !f.endsWith(".spec.ts")))
-                : (0, hook_install_js_1.discoveredHookArgs)(process.cwd());
+                : (0, hook_install_js_1.discoveredHookArgs)(projectRoot);
             const hooks = [...found.hooks];
             const unclaimed = found.unclaimed;
             if (specs.length === 0 &&
@@ -7228,8 +7395,8 @@ async function main() {
             // committed baseline — shown at the moment of change. Report-only:
             // `lint` is the gate (rule `instruction-weight`).
             if (specs.length > 0) {
-                const weightLine = (0, instruction_weight_ratchet_js_1.compileWeightLine)(process.cwd(), (0, scan_js_1.measureInstructionWeight)(process.cwd(), (0, adapter_registry_js_1.resolveHarnessSelection)({
-                    root: process.cwd(),
+                const weightLine = (0, instruction_weight_ratchet_js_1.compileWeightLine)(projectRoot, (0, scan_js_1.measureInstructionWeight)(projectRoot, (0, adapter_registry_js_1.resolveHarnessSelection)({
+                    root: projectRoot,
                     flag: harnessFlag,
                     configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses),
                 }).adapter));
@@ -7432,7 +7599,7 @@ async function main() {
                 }
                 // The same single owner of "relative to which directory" `lint` uses
                 // (#281): cwd, unless the audited dir is somebody else's repository.
-                const frame = (0, frame_js_1.frameFor)(process.cwd(), root);
+                const frame = (0, frame_js_1.frameFor)(projectRoot, root);
                 const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
                     deprecatedKeyFiles: specsUsingKeyFiles(root, excludes.globIgnore),
                     sharedDirs: config.sharedDirs,
@@ -7478,9 +7645,11 @@ async function main() {
                 // --target=skills/x/SKILL.md` named a file that does not exist from where
                 // you run it, and offered to adopt a skill `exclude` had removed.
                 const auditedBundle = frame.bundle(root);
-                const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile)
-                    .filter((p) => !(0, exclude_js_1.excludedBy)(excludes)((0, node_path_1.resolve)(root, p)))
-                    .map((p) => auditedBundle.scanned(p));
+                const adoptableSurfaces = discoverAdoptableForAudit(root, {
+                    instructionFile: adapter.layout.instructionFile,
+                    excludes,
+                    config,
+                }).map((p) => auditedBundle.scanned(p));
                 // Read the local flight recorder ONCE — feeds both the JSON report
                 // (structured summary, the product boundary) and the terminal render.
                 const ledgerRecords = (0, observe_js_1.readObservations)(root);
@@ -7488,7 +7657,7 @@ async function main() {
                 // report is built (it's a pure read off the scan) because the report's
                 // `Evaluated` ring needs to know whether this run will ever ask the
                 // skill-firing question — see `firingMeasured` below.
-                const isForeign = root !== process.cwd();
+                const isForeign = root !== projectRoot;
                 // ONE read of "can we reach a model, and on whose bill", from the driving
                 // adapter. It replaces a name check OR-ed with one harness's env vars at
                 // four sites below, and the two hard-coded "authenticate the `claude` CLI"
@@ -7758,8 +7927,8 @@ async function main() {
                 // CI upload / a custom location). The dir is created if missing.
                 const outFlag = args.find((a) => a.startsWith("--out="));
                 const outDir = outFlag
-                    ? (0, node_path_1.resolve)(process.cwd(), outFlag.slice("--out=".length))
-                    : process.cwd();
+                    ? (0, node_path_1.resolve)(projectRoot, outFlag.slice("--out=".length))
+                    : projectRoot;
                 const openReport = !args.includes("--no-open");
                 const wroteReports = [];
                 // The versioned JSON artifact — the upload/CI boundary (a hosted dashboard
@@ -7805,14 +7974,14 @@ async function main() {
                     // `--out` pointing elsewhere yields nothing to write rather than a
                     // dead `../../..` entry.
                     const rel = wroteReports
-                        .map((f) => (0, repo_path_js_1.repoRelative)(process.cwd(), (0, node_path_1.resolve)(outDir, f), {
+                        .map((f) => (0, repo_path_js_1.repoRelative)(projectRoot, (0, node_path_1.resolve)(outDir, f), {
                         relative: node_path_1.relative,
                         resolve: node_path_1.resolve,
                         isAbsolute: node_path_1.isAbsolute,
                         sep: node_path_1.sep,
                     }))
                         .filter((p) => p !== null);
-                    ensureReportGitignored(process.cwd(), rel);
+                    ensureReportGitignored(projectRoot, rel);
                 }
                 // A shareable deep-link for a public GitHub repo: the in-browser demo
                 // re-runs the audit LIVE for whoever opens it, so a local result is