vigiles 38.2.0 → 39.1.0

package/dist/core/CLAUDE.md.spec.js

@@ -13,10 +13,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const spec_js_1 = require("./spec.js");
 exports.default = (0, spec_js_1.instructionFile)({
     sections: {
-        scope: `Working in \`src/core/\`? This is the harness-AGNOSTIC domain (spec, compile, linters, the lint/audit detectors). The root \`CLAUDE.md\` holds the full positioning + rule set — read it first. Two invariants live closest to this code: the core must not import an adapter (\`core ⊄ adapter\`, eslint-enforced) and must not hard-code a Claude Code literal (read it from the injected layout/dialect). This file adds the rule for ADDING or CHANGING a detector.`,
+        scope: `Working in \`src/core/\`? This is the harness-AGNOSTIC domain (spec, compile, linters, the lint/audit detectors). The root \`CLAUDE.md\` holds the full positioning + rule set — read it first. Two invariants live closest to this code: the core must not import an adapter (\`core ⊄ adapter\`, eslint-enforced) and must not hard-code a Claude Code literal (read it from the injected layout/dialect). This file adds the rule for ADDING or CHANGING a detector, and where the rule around it lives.`,
     },
     rules: {
-        "detector-meta": (0, spec_js_1.guidance)("A deterministic DETECTOR here is one half of a RULE — and a rule is not done until it is DECLARED. Three things move together (sibling of one-detector-no-drift + rules-docs-in-sync): (1) the pure detector function (shared by `lint` AND `audit`, never reimplemented per surface; read the layout/dialect, never a CC literal); (2) its entry in `src/core/rule-meta.ts` — the `Record<RuleName, RuleMeta>` won't typecheck without it — declaring its DECIDABILITY BUCKET (structural-closed = a type could prevent it / external-decidable = needs the world, error-capable / heuristic-behavioral = warn-or-measure-only), surface, defaultSeverity, the detector name, and any upstreamPrevention; (3) its `docs/rules/<name>.md` (the coverage test binds the registry to the docs by an EXACT set match, so a missing meta or doc fails CI). The bucket is the CEILING, not a preference — a heuristic proxy may NEVER default to `error` (it cries wolf); a structural/external fact MAY, once proven FP-safe. Before writing a new detector, CLASSIFY the defect into a bucket — that decides whether it can ever gate. The full model + the prose behind the buckets is the root `lint-rule-calibration` rule and `research/enforcement-model.md`."),
+        "detector-meta": (0, spec_js_1.guidance)("A deterministic DETECTOR here is a domain capability — a pure function shared by `lint` AND `audit`, never reimplemented per surface, reading the injected layout/dialect and never a Claude Code literal. The RULE around it — id, group, default, decidability bucket, cure, how a finding reads — is POLICY and lives in the outer rule layer: a module `src/rules/<id>.ts` (or, until it migrates in #390, its row in `src/rules/index.ts`), plus its `docs/rules/<id>.md`; `src/rules/index.test.ts` binds the set to the docs by an exact set match. Core declares the port (`./rule.ts`) and receives the set as a parameter (`configFor`, `applyRules`): never import `../rules`, never spell a rule id, never name a group — `boundaries`, `local/no-rule-ids` and `local/no-group-names` refuse each. The bucket is the CEILING, not a preference — a heuristic proxy (heuristic-behavioral) may NEVER default to `error` (it cries wolf); a structural-closed or external-decidable fact MAY, once proven FP-safe. Before writing a new detector, CLASSIFY the defect into a bucket — that decides whether it can ever gate. The model behind the buckets is the root `lint-rule-calibration` rule."),
     },
 });
 //# sourceMappingURL=CLAUDE.md.spec.js.map

package/dist/core/apply-rules.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ONE ANSWER TO "IS THIS RULE ON?" FOR EVERYTHING A REPORT SHOWS.
+ *
+ * `lint` asked the resolver per rule; `audit` did not ask at all, so a rule the
+ * repo turned off still printed in the audit (`hand-written-hook`, off by
+ * default, listed every hook line vigiles did not write). `applyRules` is the
+ * one place a scan meets the resolved config: it blanks what an OFF rule found
+ * and mints the {@link FilteredScan} brand that every renderer takes — so a
+ * renderer handed a raw scan is a tsc error, not an off rule on screen.
+ *
+ * Generic machinery: it takes the rule set, the groups and the resolver as
+ * parameters (`src/rules/` and `../overrides.ts` stay outside core) and names no
+ * rule and no group. Which scan field a not-yet-migrated rule's findings sit in
+ * is that rule's own declaration (`RuleSpec.legacy.scanField`); a migrated
+ * rule's findings come from its own `findings`.
+ *
+ * UNGRADED GROUPS. A rule in a group with `graded: false` is shown and never
+ * scored: its findings go to `ungraded`, one block per group, headed by the
+ * group's own `label`/`blurb`. A scorer takes a {@link GradedView}, which has no
+ * `ungraded` — so handing one the filtered scan is a tsc error, not a coin
+ * flip moving the grade. (A migrated rule in a GRADED group would need its
+ * findings to reach the scorers; none exists yet, and `src/rules/index.test.ts`
+ * fails the day one does, until vigiles#390 wires it.)
+ *
+ * ⚠️ SCOPE, stated: only fields that are SHOWN and never scored are blanked
+ * today. Blanking a graded field when its rule is off would change a repo's
+ * audit score — a product decision, not a refactor — so a rule whose findings
+ * feed a ring declares no `scanField` yet.
+ */
+import type { Finding, RuleGroups, RuleSpec, ScanInput } from "./rule.js";
+/** The part of a rule resolver this needs: whether a rule can fire anywhere. */
+export interface RuleSwitch {
+    mayFire(rule: string): boolean;
+}
+/** The brand's key — module-private, so only this file can mint the brand. */
+declare const FILTERED: unique symbol;
+/** One rule that is on, and everything it found (possibly nothing). */
+export interface RuleResult {
+    readonly rule: string;
+    readonly findings: readonly Finding[];
+}
+/** An ungraded group's block: its label and the rules of it that are on. */
+export interface UngradedGroup {
+    readonly group: string;
+    readonly label: string;
+    readonly blurb?: string;
+    readonly rules: readonly RuleResult[];
+}
+/**
+ * A scan with the resolved config applied. Minted ONLY by {@link applyRules}
+ * (`local/frame-mint` refuses an `as FilteredScan` anywhere else).
+ */
+export type FilteredScan<S extends object> = S & {
+    readonly [FILTERED]: true;
+    /** Only a renderer reads this (`no-restricted-syntax` in the scorers). */
+    readonly ungraded: readonly UngradedGroup[];
+};
+/** What a scorer takes: a scan that carries no ungraded findings. */
+export type GradedView<S extends object> = S & {
+    readonly ungraded?: never;
+};
+/**
+ * Apply the resolved config to a scan: every rule that cannot fire anywhere
+ * has the scan field it declares emptied, and the ungraded groups' rules that
+ * are on report into `ungraded`. Pure; the scan is not mutated.
+ */
+export declare function applyRules<S extends ScanInput>(rules: readonly RuleSpec[], groups: RuleGroups, resolver: RuleSwitch, scan: S): FilteredScan<S>;
+/** The scan a scorer may read: `ungraded` dropped, everything else as is. */
+export declare function gradedView<S extends ScanInput>(scan: FilteredScan<S>): GradedView<Omit<FilteredScan<S>, "ungraded">>;
+export {};
+//# sourceMappingURL=apply-rules.d.ts.map

package/dist/core/apply-rules.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRules = applyRules;
+exports.gradedView = gradedView;
+/** The brand's key — module-private, so only this file can mint the brand. */
+const FILTERED = Symbol("filtered-scan");
+/** `scan` with `field` emptied, when that field is a list. */
+function blank(scan, field) {
+    return Array.isArray(Reflect.get(scan, field))
+        ? { ...scan, [field]: [] }
+        : scan;
+}
+/** The ungraded groups' blocks: each group that has a rule on, in order. */
+function ungradedOf(rules, groups, scan) {
+    return Object.entries(groups)
+        .filter(([, g]) => !g.graded)
+        .map(([group, g]) => ({
+        group,
+        label: g.label,
+        ...(g.blurb === undefined ? {} : { blurb: g.blurb }),
+        rules: rules
+            .filter((r) => r.group === group)
+            .map((r) => ({ rule: r.id, findings: r.findings?.(scan) ?? [] })),
+    }))
+        .filter((g) => g.rules.length > 0);
+}
+/**
+ * Apply the resolved config to a scan: every rule that cannot fire anywhere
+ * has the scan field it declares emptied, and the ungraded groups' rules that
+ * are on report into `ungraded`. Pure; the scan is not mutated.
+ */
+function applyRules(rules, groups, resolver, scan) {
+    const on = rules.filter((r) => resolver.mayFire(r.id));
+    const blanked = rules
+        .filter((r) => !on.includes(r))
+        .reduce((acc, r) => (r.legacy ? blank(acc, r.legacy.scanField) : acc), scan);
+    return {
+        ...blanked,
+        ungraded: ungradedOf(on, groups, scan),
+        [FILTERED]: true,
+    };
+}
+/** The scan a scorer may read: `ungraded` dropped, everything else as is. */
+function gradedView(scan) {
+    const { ungraded: _shown, ...graded } = scan;
+    return graded;
+}
+//# sourceMappingURL=apply-rules.js.map

package/dist/core/bash-effects.d.ts

@@ -225,61 +225,4 @@ export declare function leafCommandsNormalized(command: string): NormalizedLeaf[
  * Parse failure → `[]`.
  */
 export declare function leafArgvSource(command: string): string[][];
-/**
- * Every word of every simple command in `command` that could name a FILE, with
- * inline PROGRAM TEXT removed — the primitive behind "does this hook's script
- * exist?".
- *
- * 🔴 WHY A FOURTH EXTRACTOR, stated against the three that already exist,
- * because "there is already one that returns words" is exactly the reasoning
- * that produced the bug this replaces.
- *
- *  - `leafCommands` drops every word it cannot reduce to a LITERAL, so
- *    `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` — the standard spelling of a hook path —
- *    disappears entirely. Unusable for a file question.
- *  - `leafCommandsNormalized` basenames the head, so `./hooks/x.sh` becomes
- *    `x.sh` and no resolver can find it.
- *  - `leafArgvSource` keeps the spelling but answers a DIFFERENT question:
- *    "which leaves unconditionally RUN". It drops the right-hand side of `&&`
- *    by design, so `cd "$ROOT" && node hooks/x.mjs` yields no script. For
- *    coverage attribution that abstention is correct; for "must this file
- *    exist?" it is a miss, because a conditionally-run script still has to be
- *    on disk.
- *
- * So this walks EVERY simple command, keeps every word at source level, and
- * subtracts only the words that are provably not paths.
- *
- * 🔴 WHAT IT SUBTRACTS, and the defect that motivated it. The hook scanner used
- * to run a regex over the raw command STRING. Against the standard portable
- * plugin idiom —
- *
- *     node -e "(async()=>{…await import(…join(root,'hooks','always-on.mjs'))…})()"
- *
- * — it grabbed a character run ending at `.mjs` and reported the hook's script
- * as `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`,
- * MISSING. `hooks/always-on.mjs` was 1,766 bytes on disk. Nine such findings
- * across the 32-repo corpus, contributing to two `F/0` grades. Inside a shell
- * parse the argument of `-e` is not a word the shell will ever resolve to a
- * file, so it is not returned.
- *
- * ⚠️ HOW MUCH OF THAT THE FLAG TABLE ACTUALLY DID, measured rather than
- * assumed: none of it, on that corpus. Mutating the `-e`/`-c` subtraction OFF
- * and re-auditing all three affected repos still yields ZERO false hook-script
- * findings, because both real payloads are single words that either contain
- * whitespace or do not end in a script extension, and the caller anchors its
- * match to a whole word. The table is kept because it is the difference
- * between a function whose contract ("words that could name a file") is true
- * and one whose contract is merely true-so-far: without it a JavaScript
- * program is handed to every caller as a candidate filename, and the next
- * caller inherits the bug. Recorded here so nobody reads a corpus number back
- * onto the wrong mechanism.
- *
- * Words beginning with `-` are dropped as flags: a flag is not a path, and the
- * one caller anchors its match to a whole word anyway.
- *
- * Returns `null` — not `[]` — when the text does not parse as shell, so a
- * caller can tell "no file operands" from "no analysis", and cannot silently
- * treat the second as the first.
- */
-export declare function commandWords(command: string): string[] | null;
 //# sourceMappingURL=bash-effects.d.ts.map

package/dist/core/bash-effects.js

@@ -31,7 +31,6 @@ exports.leafCommands = leafCommands;
 exports.stripWrappers = stripWrappers;
 exports.leafCommandsNormalized = leafCommandsNormalized;
 exports.leafArgvSource = leafArgvSource;
-exports.commandWords = commandWords;
 /**
  * The parser is loaded ON FIRST PARSE, not at module load — `sh()` memoizes it.
  *
@@ -1164,150 +1163,4 @@ function normalizeCallExpr(node, redirs) {
         chdir: stripped.chdir,
     };
 }
-// ===========================================================================
-// FILE-OPERAND extraction (the reference question, not the effect question)
-// ===========================================================================
-/**
- * Interpreters, and the flags after which the NEXT word is a PROGRAM rather
- * than a path. `node -e "<js>"`, `python -c "<py>"`, `perl -E "<pl>"`.
- *
- * Keyed by the head's basename, so `/usr/local/bin/node` and `node` behave the
- * same.
- */
-const INLINE_PROGRAM_FLAGS = new Map([
-    ["node", ["-e", "--eval", "-p", "--print"]],
-    ["nodejs", ["-e", "--eval", "-p", "--print"]],
-    ["bun", ["-e", "--eval", "-p", "--print"]],
-    ["deno", ["-e", "--eval", "-p", "--print"]],
-    ["python", ["-c"]],
-    ["python2", ["-c"]],
-    ["python3", ["-c"]],
-    ["ruby", ["-e"]],
-    ["perl", ["-e", "-E"]],
-    ["php", ["-r"]],
-]);
-/**
- * Shells, whose `-c` argument is a nested SHELL program. Not program text to be
- * discarded — program text to be PARSED, so `bash -c 'exec "$ROOT/hooks/x.sh"'`
- * still yields its script.
- */
-const SHELL_HEADS = new Set([
-    "sh",
-    "bash",
-    "zsh",
-    "dash",
-    "ksh",
-    "ash",
-    "busybox",
-]);
-/** Guard against a pathological `sh -c 'sh -c "sh -c …"'` nest. */
-const MAX_SHELL_NESTING = 3;
-/**
- * Every word of every simple command in `command` that could name a FILE, with
- * inline PROGRAM TEXT removed — the primitive behind "does this hook's script
- * exist?".
- *
- * 🔴 WHY A FOURTH EXTRACTOR, stated against the three that already exist,
- * because "there is already one that returns words" is exactly the reasoning
- * that produced the bug this replaces.
- *
- *  - `leafCommands` drops every word it cannot reduce to a LITERAL, so
- *    `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` — the standard spelling of a hook path —
- *    disappears entirely. Unusable for a file question.
- *  - `leafCommandsNormalized` basenames the head, so `./hooks/x.sh` becomes
- *    `x.sh` and no resolver can find it.
- *  - `leafArgvSource` keeps the spelling but answers a DIFFERENT question:
- *    "which leaves unconditionally RUN". It drops the right-hand side of `&&`
- *    by design, so `cd "$ROOT" && node hooks/x.mjs` yields no script. For
- *    coverage attribution that abstention is correct; for "must this file
- *    exist?" it is a miss, because a conditionally-run script still has to be
- *    on disk.
- *
- * So this walks EVERY simple command, keeps every word at source level, and
- * subtracts only the words that are provably not paths.
- *
- * 🔴 WHAT IT SUBTRACTS, and the defect that motivated it. The hook scanner used
- * to run a regex over the raw command STRING. Against the standard portable
- * plugin idiom —
- *
- *     node -e "(async()=>{…await import(…join(root,'hooks','always-on.mjs'))…})()"
- *
- * — it grabbed a character run ending at `.mjs` and reported the hook's script
- * as `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`,
- * MISSING. `hooks/always-on.mjs` was 1,766 bytes on disk. Nine such findings
- * across the 32-repo corpus, contributing to two `F/0` grades. Inside a shell
- * parse the argument of `-e` is not a word the shell will ever resolve to a
- * file, so it is not returned.
- *
- * ⚠️ HOW MUCH OF THAT THE FLAG TABLE ACTUALLY DID, measured rather than
- * assumed: none of it, on that corpus. Mutating the `-e`/`-c` subtraction OFF
- * and re-auditing all three affected repos still yields ZERO false hook-script
- * findings, because both real payloads are single words that either contain
- * whitespace or do not end in a script extension, and the caller anchors its
- * match to a whole word. The table is kept because it is the difference
- * between a function whose contract ("words that could name a file") is true
- * and one whose contract is merely true-so-far: without it a JavaScript
- * program is handed to every caller as a candidate filename, and the next
- * caller inherits the bug. Recorded here so nobody reads a corpus number back
- * onto the wrong mechanism.
- *
- * Words beginning with `-` are dropped as flags: a flag is not a path, and the
- * one caller anchors its match to a whole word anyway.
- *
- * Returns `null` — not `[]` — when the text does not parse as shell, so a
- * caller can tell "no file operands" from "no analysis", and cannot silently
- * treat the second as the first.
- */
-function commandWords(command) {
-    return commandWordsAt(command, 0);
-}
-function commandWordsAt(command, depth) {
-    let file;
-    try {
-        file = sh().syntax.NewParser().Parse(command, "cmd.sh");
-    }
-    catch {
-        return null;
-    }
-    const out = [];
-    sh().syntax.Walk(file, (node) => {
-        if (sh().syntax.NodeType(node) === "CallExpr" && node.Args?.length)
-            fileOperandsOf(node.Args, depth, out);
-        return true;
-    });
-    return out;
-}
-/**
- * The file-operand words of ONE simple command, appended to `out`.
- *
- * Wrappers are resolved through with the same table `leafArgvSource` uses (it
- * keys on the BASENAME head, and wrappers only ever drop words off the FRONT,
- * so a count maps the result back onto the original spellings — not a second
- * copy of the rule). Flags never name a file, so they are dropped; the word
- * AFTER an inline-program flag is dropped with them, and the word after a
- * shell's `-c` is parsed as shell instead.
- */
-function fileOperandsOf(args, depth, out) {
-    const raw = args.map((w) => sourceParts(w.Parts) ?? "");
-    const probe = [normalizeHead(raw[0] ?? ""), ...raw.slice(1)];
-    const argv = raw.slice(probe.length - stripWrappers(probe).argv.length);
-    const head = normalizeHead(argv[0] ?? "");
-    const programFlags = INLINE_PROGRAM_FLAGS.get(head);
-    const nestsShell = SHELL_HEADS.has(head) && depth < MAX_SHELL_NESTING;
-    for (let i = 0; i < argv.length; i++) {
-        const w = argv[i] ?? "";
-        if (w === "")
-            continue;
-        if (!w.startsWith("-")) {
-            out.push(w);
-            continue;
-        }
-        if (nestsShell && w === "-c") {
-            out.push(...(commandWordsAt(argv[++i] ?? "", depth + 1) ?? []));
-        }
-        else if (programFlags?.includes(w)) {
-            i++; // the program text — not a word any shell resolves to a file
-        }
-    }
-}
 //# sourceMappingURL=bash-effects.js.map

package/dist/core/compile-generator.d.ts

@@ -48,16 +48,16 @@ export interface CompileGeneratorSkillResult {
  * function* () { … })` — to a full SKILL.md (frontmatter + body + integrity
  * hash), verifying gate references. This is the CLI entry for generator skills.
  */
-export declare function compileGeneratorSkill(source: string, options?: {
-    basePath?: string;
-    specFile?: string;
+export declare function compileGeneratorSkill(source: string, options: {
+    readonly basePath: string;
+    readonly specFile?: string;
 }): CompileGeneratorSkillResult;
 /**
  * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref
  * errors. `frontmatter` (name/description/…) is prepended verbatim if given.
  */
-export declare function compileGenerator(source: string, options?: {
-    basePath?: string;
-    frontmatter?: string;
+export declare function compileGenerator(source: string, options: {
+    readonly basePath: string;
+    readonly frontmatter?: string;
 }): CompileGeneratorResult;
 //# sourceMappingURL=compile-generator.d.ts.map

package/dist/core/compile-generator.js

@@ -263,8 +263,8 @@ function extractMeta(obj) {
  * function* () { … })` — to a full SKILL.md (frontmatter + body + integrity
  * hash), verifying gate references. This is the CLI entry for generator skills.
  */
-function compileGeneratorSkill(source, options = {}) {
-    const basePath = options.basePath ?? process.cwd();
+function compileGeneratorSkill(source, options) {
+    const basePath = options.basePath;
     const specFile = options.specFile ?? "SKILL.md.spec.ts";
     const sf = typescript_1.default.createSourceFile("s.ts", source, typescript_1.default.ScriptTarget.Latest, true);
     const call = findGenSkillCall(sf);
@@ -309,8 +309,8 @@ function compileGeneratorSkill(source, options = {}) {
  * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref
  * errors. `frontmatter` (name/description/…) is prepended verbatim if given.
  */
-function compileGenerator(source, options = {}) {
-    const basePath = options.basePath ?? process.cwd();
+function compileGenerator(source, options) {
+    const basePath = options.basePath;
     const sf = typescript_1.default.createSourceFile("skill.ts", source, typescript_1.default.ScriptTarget.Latest, true);
     const gen = findGenerator(sf);
     if (!gen?.body) {

package/dist/core/compile.d.ts

@@ -66,6 +66,46 @@ export declare function validateCommandRef(command: string, basePath: string): C
 export declare function validateSymbolRef(file: string, name: string, basePath: string): Promise<CompileError | null>;
 export declare function validateDirRef(dirPath: string, basePath: string): CompileError | null;
 export declare function validateGlobRef(pattern: string, basePath: string): CompileError | null;
+/**
+ * Why an `enforce()` reference was NOT verified. Separate members, not one
+ * "unknown", because the compile output turns each into a different instruction
+ * (make-the-distinction-a-type): a switch someone turned off is fixed by turning
+ * it on, an unset rule by setting it, an unreadable config by fixing the probe.
+ */
+export type UnverifiedReason = 
+/** `enforce(…, { verify: false })` on this rule. */
+"verify-false"
+/** `verifyLinters: false` for the whole compile. */
+ | "verification-off"
+/** `linterModes[<linter>] === false`. */
+ | "linter-off"
+/** catalog-only: the rule exists, the config was not read. */
+ | "config-not-read"
+/** the whole config was read and no block sets the rule. */
+ | "not-configured"
+/** the rule exists; whether the config switches it on could not be read. */
+ | "enabled-unknown"
+/** the rule does not exist (a compile error as well). */
+ | "not-found"
+/** the config switches the rule off (a compile error as well). */
+ | "disabled";
+/** What `compile` established about one `enforce()` reference. */
+export type EnforceVerdict = {
+    readonly kind: "verified";
+} | {
+    readonly kind: "unverified";
+    readonly reason: UnverifiedReason;
+};
+/** One `enforce()` reference and its verdict, in spec order. */
+export interface EnforceVerdictEntry {
+    readonly ref: string;
+    readonly verdict: EnforceVerdict;
+}
+/**
+ * The sentence the compile prints for an unverified reference: what happened
+ * and the one thing that turns it into "Enforced by".
+ */
+export declare function unverifiedAdvice(ref: string, reason: UnverifiedReason): string;
 export interface CompileClaudeResult {
     markdown: string;
     errors: CompileError[];
@@ -86,10 +126,28 @@ export interface CompileClaudeResult {
      */
     budgetFindings: CompileError[];
     linterResults: LinterCheckResult[];
+    /**
+     * One entry per `enforce()` rule, in spec order: rendered "**Enforced by:**"
+     * exactly when `verdict.kind === "verified"`, "**Claimed (unverified):**"
+     * otherwise. The CLI's "N linter-verified" count is the verified entries.
+     */
+    enforceVerdicts: EnforceVerdictEntry[];
     /** Estimated token count of compiled output (~4 chars/token). */
     tokens: number;
     /** All targets from the spec (for multi-target compilation). */
     targets: string[];
+    /**
+     * Each target's file: its repo-relative path (a secondary target is named
+     * from the primary's directory) and its markdown, rendered for THAT path so
+     * every link resolves from where the file sits. The first is the primary,
+     * whose markdown is `markdown`.
+     */
+    outputs: CompiledOutput[];
+}
+/** One file a multi-target compile writes. */
+export interface CompiledOutput {
+    readonly path: string;
+    readonly markdown: string;
 }
 export interface CompileClaudeOptions {
     /**
@@ -107,7 +165,8 @@ export interface CompileClaudeOptions {
     maxSectionChars?: number;
     /** Character budget for the whole rendered Rules section (0 disables). */
     maxRulesChars?: number;
-    basePath?: string;
+    /** The repo root every reference resolves against. Required: no cwd fallback. */
+    readonly basePath: string;
     specFile?: string;
     /** Injected harness dialect; its instructionTargets[0] is the default target. */
     dialect?: HarnessDialect;
@@ -166,13 +225,15 @@ export declare const DEFAULT_MAX_SECTION_CHARS = 15000;
  * budget, which leaves the other half for everything else the file carries.
  */
 export declare const DEFAULT_MAX_RULES_CHARS = 20000;
+/** The compile options that decide how an `enforce()` reference is verified. */
+type LinterVerifyOptions = Pick<CompileClaudeOptions, "verifyLinters" | "linterModes" | "catalogOnly" | "linters">;
 /**
  * Compile a ClaudeSpec into markdown.
  *
  * Returns the compiled markdown, validation errors, and linter check results.
  * The markdown is generated even if there are errors (with warnings).
  */
-export declare function compileClaude(spec: ClaudeSpec, options?: CompileClaudeOptions): Promise<CompileClaudeResult>;
+export declare function compileClaude(spec: ClaudeSpec, options: Readonly<CompileClaudeOptions>): Promise<CompileClaudeResult>;
 export interface CompileSkillResult {
     /**
      * The stamped artifact — present ONLY when `errors` is empty. `null` is what
@@ -187,13 +248,14 @@ export interface CompileSkillResult {
 /**
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
  */
-export declare function compileSkill(spec: SkillSpec, options?: {
-    basePath?: string;
+export declare function compileSkill(spec: SkillSpec, options: Readonly<{
+    /** The repo root every reference resolves against. Required: no cwd fallback. */
+    readonly basePath: string;
     specFile?: string;
     /** The harness dialect — supplies `skillFrontmatterKeys`. Omitting it emits
      *  every key the compiler can render, so existing callers are unchanged. */
     dialect?: HarnessDialect;
-}): Promise<CompileSkillResult>;
+}>): Promise<CompileSkillResult>;
 export interface CompileAgentResult {
     /**
      * The stamped artifact — present ONLY when `errors` is empty. `null` is what
@@ -210,13 +272,14 @@ export interface CompileAgentResult {
  * Verifies the tool contract and the body's references; the marks the body
  * carries (`vigiles:symbol`, file/cmd refs) are the same ones `lint` re-checks.
  */
-export declare function compileAgent(spec: AgentSpec, options: {
-    basePath?: string;
+export declare function compileAgent(spec: AgentSpec, options: Readonly<{
+    /** The repo root every reference resolves against. Required: no cwd fallback. */
+    basePath: string;
     specFile?: string;
     /** The harness dialect to verify the tool contract against (required — the
      *  core defines no default dialect; the adapter/composition root injects it). */
     dialect: HarnessDialect;
-}): Promise<CompileAgentResult>;
+} & LinterVerifyOptions>): Promise<CompileAgentResult>;
 export interface CompileRailwayOptions {
     /** Names of compiled agents, to resolve `delegate` targets. Skipped if omitted. */
     knownAgents?: readonly string[];
@@ -261,4 +324,5 @@ export interface AdoptResult {
  * Returns the diff so users can see what was manually changed.
  */
 export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string, dialect: HarnessDialect): Promise<AdoptResult>;
+export {};
 //# sourceMappingURL=compile.d.ts.map