vigiles 2.6.0 → 3.0.0

package/dist/core/compose.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Sync-tool compatibility detector — keep vigiles composable with the rule-sync
+ * tools (Ruler, rulesync) instead of fighting them for the same files.
+ *
+ * Both vigiles and a sync tool want to *write* CLAUDE.md / AGENTS.md. That
+ * collision is the whole compatibility problem: vigiles stamps a SHA-256
+ * integrity header on line 1 (see `integrity.ts`), but Ruler concatenates its
+ * source files into CLAUDE.md (prepending `<!-- Source: … -->`) and rulesync
+ * regenerates it — either way the hash silently goes stale. The clean topology
+ * is "vigiles upstream": compile into the tool's *source slot* and let the tool
+ * distribute (see `research/sync-tool-compatibility.md`).
+ *
+ * This detector is pure filesystem inspection — the same deterministic-detector
+ * shape as `orphans.ts` / `test-coverage.ts`. It reports which tools are present
+ * and any target that collides with a file the tool regenerates, so `vigiles
+ * audit` can warn before the integrity guarantee is lost.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSyncTools = detectSyncTools;
+exports.detectInstructionMirror = detectInstructionMirror;
+exports.composeCollisions = composeCollisions;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+/** True when `rel` under `root` exists and is a directory. */
+function hasDir(root, rel) {
+    const p = (0, node_path_1.join)(root, rel);
+    return (0, node_fs_1.existsSync)(p) && (0, node_fs_1.statSync)(p).isDirectory();
+}
+/** True when `rel` under `root` exists as a file. */
+function hasFile(root, rel) {
+    const p = (0, node_path_1.join)(root, rel);
+    return (0, node_fs_1.existsSync)(p) && (0, node_fs_1.statSync)(p).isFile();
+}
+/**
+ * Detect the rule-sync tools configured in the repo at `root`. Ruler is keyed
+ * on its `.ruler/` source dir or a `ruler.toml`; rulesync on its `.rulesync/`
+ * dir. Returns each tool's recommended source slot and the files it owns as
+ * distribution output (used to find collisions).
+ */
+function detectSyncTools(root) {
+    const base = (0, node_path_1.resolve)(root);
+    const tools = [];
+    if (hasDir(base, ".ruler") || hasFile(base, "ruler.toml")) {
+        tools.push({
+            name: "ruler",
+            sourceSlot: (0, node_path_1.join)(".ruler", "AGENTS.md"),
+            // Ruler's default agent outputs that overlap vigiles instruction targets.
+            distributes: ["CLAUDE.md", "AGENTS.md"],
+        });
+    }
+    if (hasDir(base, ".rulesync")) {
+        tools.push({
+            name: "rulesync",
+            sourceSlot: (0, node_path_1.join)(".rulesync", "rules", "vigiles.md"),
+            distributes: ["CLAUDE.md", "AGENTS.md"],
+        });
+    }
+    return tools;
+}
+// ---------------------------------------------------------------------------
+// Collision analysis
+// ---------------------------------------------------------------------------
+/** Normalize a target to its bare filename for comparison (handles paths). */
+function targetName(target) {
+    const parts = target.split(/[\\/]/);
+    return parts[parts.length - 1];
+}
+/**
+ * Detect whether `CLAUDE.md` and `AGENTS.md` at `root` are ONE artifact, not two
+ * — a symlink in either direction (`ln -s CLAUDE.md AGENTS.md`) or byte-identical
+ * content (a sync tool keeping them in lockstep). Claude Code reads CLAUDE.md
+ * only ([anthropics/claude-code#34235]); users bridge to the AGENTS.md tools this
+ * way (see `research/sync-tool-compatibility.md` requirement 7). When mirrored,
+ * vigiles must treat them as the same file — hash + `require-spec` run once on the
+ * real one, and the mirror is never flagged as a second, spec-less instruction
+ * file. Returns null when one is absent, or both exist but genuinely differ.
+ */
+function detectInstructionMirror(root) {
+    const claude = (0, node_path_1.join)(root, "CLAUDE.md");
+    const agents = (0, node_path_1.join)(root, "AGENTS.md");
+    if (!(0, node_fs_1.existsSync)(claude) || !(0, node_fs_1.existsSync)(agents))
+        return null;
+    // Symlink either direction (or both → a third file) resolves to one realpath.
+    try {
+        if ((0, node_fs_1.realpathSync)(claude) === (0, node_fs_1.realpathSync)(agents)) {
+            const claudeIsLink = (0, node_fs_1.lstatSync)(claude).isSymbolicLink();
+            const link = claudeIsLink ? "CLAUDE.md" : "AGENTS.md";
+            const realTarget = claudeIsLink ? "AGENTS.md" : "CLAUDE.md";
+            return {
+                files: ["CLAUDE.md", "AGENTS.md"],
+                kind: "symlink",
+                link,
+                realTarget,
+                reason: `${link} is a symlink resolving to the same file as ${realTarget} — one instruction artifact bridged to the AGENTS.md tools; verify and hash the real file once, never flag the mirror as spec-less.`,
+            };
+        }
+    }
+    catch {
+        /* realpath failed (race / broken link) → fall through to content compare */
+    }
+    // Byte-identical content: kept in sync by rulesync/Ruler rather than symlinked.
+    try {
+        if ((0, node_fs_1.readFileSync)(claude).equals((0, node_fs_1.readFileSync)(agents))) {
+            return {
+                files: ["CLAUDE.md", "AGENTS.md"],
+                kind: "identical-content",
+                reason: `CLAUDE.md and AGENTS.md are byte-identical — kept in sync (rulesync/Ruler); treat as one artifact and stamp the integrity hash only on the compile source slot.`,
+            };
+        }
+    }
+    catch {
+        /* unreadable → not a detectable mirror */
+    }
+    return null;
+}
+/**
+ * Given the repo `root` and the spec's compile `targets`, report every case
+ * where a target is also a file a detected sync tool regenerates. Each
+ * collision carries the source slot to compile into instead — the actionable
+ * fix that preserves the integrity hash (the tool distributes from there).
+ *
+ * No detected tool, or no overlapping target, yields an empty list.
+ */
+function composeCollisions(root, targets) {
+    const tools = detectSyncTools(root);
+    const collisions = [];
+    for (const tool of tools) {
+        for (const target of targets) {
+            if (!tool.distributes.includes(targetName(target)))
+                continue;
+            collisions.push({
+                tool: tool.name,
+                target,
+                redirectTo: tool.sourceSlot,
+                reason: `${tool.name} regenerates ${targetName(target)}, which would overwrite vigiles output and stale its integrity hash — compile into ${tool.sourceSlot} and let ${tool.name} distribute.`,
+            });
+        }
+    }
+    return collisions;
+}
+//# sourceMappingURL=compose.js.map

package/dist/core/dialect.d.ts

@@ -0,0 +1,51 @@
+/**
+ * HarnessDialect — the format/dialect PORT (see
+ * `research/code-adapter-architecture.md`, the format axis).
+ *
+ * The compiler needs a handful of harness-specific facts to verify and render an
+ * instruction file: the built-in tool catalog a subagent may declare, the tools
+ * the platform never exposes, the shape of an MCP tool reference, the hook
+ * events the harness fires, the instruction-file targets it reads, and the env
+ * token expanded to the plugin root. Those used to be hard-coded literals inside
+ * `compile.ts`; here they are a single named value behind an interface.
+ *
+ * Claude Code is the reference dialect today (`claudeCodeDialect`, defined in its
+ * adapter at `src/adapters/claude-code/dialect.ts`). A second harness (Codex
+ * likely next) is added by defining a sibling `HarnessDialect` — e.g.
+ * `src/adapters/codex/dialect.ts` exporting `codexDialect` — and injecting it
+ * (`compileAgent(spec, { dialect })`). The compiler reads these from the injected
+ * dialect, so the core never hard-codes — nor even defines — one harness's
+ * vocabulary: the concrete dialects live in the adapters, only this interface
+ * lives in the core. That is the format axis of the hexagonal boundary.
+ */
+/**
+ * Which SKILL.md frontmatter keys a harness understands — see
+ * `HarnessDialect.skillFrontmatter`.
+ */
+export type SkillFrontmatterProfile = "claude-code" | "minimal";
+export interface HarnessDialect {
+    /** Stable identifier, e.g. "claude-code". */
+    readonly name: string;
+    /** Built-in tools a subagent may list in its `tools:` contract. */
+    readonly builtinAgentTools: readonly string[];
+    /** Tools the platform never exposes to a subagent (a listed one is dead). */
+    readonly neverAvailableTools: readonly string[];
+    /** Matches an MCP tool reference, e.g. `mcp__server__tool`. */
+    readonly mcpToolPattern: RegExp;
+    /** Hook event names the harness fires. */
+    readonly hookEvents: readonly string[];
+    /** Instruction-file targets the harness reads (also the h1 heading). */
+    readonly instructionTargets: readonly string[];
+    /** The env token expanded to the plugin root in hook commands. */
+    readonly pluginRootToken: string;
+    /**
+     * Which SKILL.md frontmatter keys this harness understands — the profile the
+     * compiler renders under:
+     * - `"claude-code"` — the full Claude Code set (name, description, plus the
+     *   CC-only keys: disable-model-invocation, argument-hint, …).
+     * - `"minimal"` — name + description ONLY (the cross-tool SKILL.md shape Codex
+     *   and OpenCode read; CC-only keys are omitted because they'd be inert noise).
+     */
+    readonly skillFrontmatter: SkillFrontmatterProfile;
+}
+//# sourceMappingURL=dialect.d.ts.map

package/dist/core/dialect.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=dialect.js.map

package/dist/core/harness-driver.d.ts

@@ -0,0 +1,134 @@
+/**
+ * HarnessTestDriver — the seam that makes the pillar-2 deterministic runner
+ * (`runHarnessTest`) adapter-driven instead of hard-wired to Claude Code.
+ *
+ * Each harness (Claude Code, Codex, …) brings a driver that knows how to: build
+ * the non-interactive argv for its binary, start its scripted mock model, and
+ * parse its stdout into the unified `Trace` fields. The runner stays
+ * harness-agnostic — it spawns `driver.runtime.agentBinary`, points it at the
+ * mock via `driver.runtime.wireMock(url)`, and assembles the result through
+ * `driver.parseRun`. A `HarnessAdapter` carries its driver as
+ * `harnessTestDriver`, so the runner never imports a sibling adapter.
+ *
+ * The shared trace shapes (`ModelTurn`/`ModelRequest`/`ToolCall`/`HookFire`)
+ * live here in core so BOTH the adapters and the runner can reference them
+ * without a cross-adapter import. `vigiles/claude-code` re-exports
+ * `ModelTurn`/`ModelRequest` for back-compat.
+ */
+import type { HarnessRuntime } from "./runtime.js";
+/**
+ * One scripted assistant turn: a final text answer, or a tool call. The common
+ * shape both harness mocks consume — the Anthropic Messages mock
+ * (`src/adapters/claude-code/mock-model.ts`) and the OpenAI Responses mock
+ * (`src/adapters/codex/mock-model.ts`, which uses only `text`).
+ */
+export interface ModelTurn {
+    /** Final text answer (stops the turn). */
+    readonly text?: string;
+    /** A tool to invoke, e.g. "Bash" | "Write" | "Edit". */
+    readonly tool?: string;
+    /** The tool input, e.g. `{ file_path, content }` or `{ command }`. */
+    readonly input?: Record<string, unknown>;
+}
+/**
+ * One model request the scripted mock received, flattened to text for
+ * assertions — the seam that lets a harness test prove what reached the model
+ * (a SessionStart hook's injected context, a slash command's expansion), not
+ * just that a hook fired.
+ */
+export interface ModelRequest {
+    /** The system prompt, flattened to text (string or text-block array). */
+    readonly system: string;
+    /** The conversation messages, each flattened to `{ role, text }`. */
+    readonly messages: readonly {
+        readonly role: string;
+        readonly text: string;
+    }[];
+}
+/** A tool the agent invoked, paired with its result (transcript mode only). */
+export interface ToolCall {
+    readonly name: string;
+    readonly input: unknown;
+    /** The tool_result text ("" if none / not captured). */
+    readonly resultText: string;
+    /** Whether the tool_result came back flagged as an error. */
+    readonly isError: boolean;
+}
+/**
+ * A hook invocation observed during the run, recorded (not inferred) from the
+ * harness's stream events — so a test can assert which hook fired and whether
+ * it blocked.
+ */
+export interface HookFire {
+    /** The hook label, e.g. `"PreToolUse:Edit"` (`Event:Matcher`). */
+    readonly name: string;
+    /** The hook event, e.g. `"PreToolUse"`, `"PostToolUse"`, `"Stop"`. */
+    readonly event: string;
+    /** The hook process exit code (2 = block), or undefined if not reported. */
+    readonly exitCode: number | undefined;
+    /** Whether the hook blocked / errored (exit ≠ 0 or outcome "error"). */
+    readonly blocked: boolean;
+    /** What the hook printed (its block reason / diagnostic), or "". */
+    readonly output: string;
+}
+/** A running scripted mock model: the URL to point the binary at + the record. */
+export interface HarnessMockHandle {
+    /** Base URL the spawned binary is pointed at. */
+    readonly url: string;
+    /** Every request the mock received, flattened for assertions, in order. */
+    readonly requests: readonly ModelRequest[];
+    /** Number of model turns served so far. */
+    readonly count: number;
+    /** Stop the mock server. */
+    close(): void | Promise<void>;
+}
+/** The facts a driver needs to build the non-interactive argv for one run. */
+export interface HarnessDriverContext {
+    /** The user prompt. */
+    readonly prompt: string;
+    /** The temp working dir the binary runs in. */
+    readonly cwd: string;
+    /** Whether a settings file was written (CC: pass `--settings`). */
+    readonly hasSettings: boolean;
+    /** Tools the agent may use. */
+    readonly tools: readonly string[];
+    /** Capture the full event transcript instead of just the final result. */
+    readonly transcript: boolean;
+    /** Path to a plugin dir to install natively, if any. */
+    readonly pluginDir?: string;
+    /**
+     * The mock-wiring args from `runtime.wireMock(url).args` — the flags that
+     * point the binary at the mock model. The DRIVER inserts them at the correct
+     * argv position (for Codex they MUST follow `exec`; for env-only harnesses
+     * like Claude Code this is empty). Passed in (not prepended by the runner)
+     * because only the driver knows its argv structure.
+     */
+    readonly mockArgs: readonly string[];
+}
+/** A harness's stdout parsed into the unified `Trace` fields. */
+export interface ParsedRun {
+    /** Number of model turns, if the stdout reports it (else taken from the mock). */
+    readonly turns?: number;
+    readonly toolCalls: readonly ToolCall[];
+    readonly hooks: readonly HookFire[];
+    /** The agent's final answer text, or "". */
+    readonly output: string;
+}
+/**
+ * What a harness brings so `runHarnessTest` can drive it. Implemented in each
+ * adapter (`claudeCodeDriver`, `codexDriver`) and carried on the
+ * `HarnessAdapter` as `harnessTestDriver`.
+ */
+export interface HarnessTestDriver {
+    /** The transport (binary to spawn + how to reach the mock via `wireMock`). */
+    readonly runtime: HarnessRuntime;
+    /** The non-interactive argv for one run. Pure, so it's unit-tested. */
+    buildArgs(ctx: HarnessDriverContext): readonly string[];
+    /** Start this harness's scripted mock for the given turn script. */
+    startMock(script: readonly ModelTurn[]): Promise<HarnessMockHandle>;
+    /** Parse the harness's stdout into the unified trace fields. */
+    parseRun(stdout: string): ParsedRun;
+    /** Whether the agent binary is available on PATH. */
+    available(): boolean;
+}
+//# sourceMappingURL=harness-driver.d.ts.map

package/dist/core/harness-driver.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=harness-driver.js.map

package/dist/core/hook-protocol.d.ts

@@ -0,0 +1,28 @@
+/**
+ * HookProtocol — the hook-wire PORT (transport axis). How a harness signals that
+ * a hook blocked/denied a tool call: the block exit code, the decision values
+ * that mean "deny", and the env vars a synthesized event carries. The research
+ * (research/harness-landscape.md) found Claude Code and Codex hooks are nearly
+ * identical at the wire level (both: JSON on stdin, `permissionDecision: "deny"`
+ * / `decision: "block"` / exit 2) — so this descriptor is deliberately thin, and
+ * the fact that a second harness needs almost the same values IS the finding.
+ * What varies more (config format JSON-vs-TOML, the plugin-root token, the event
+ * names) lives in PluginLayout / HarnessDialect, not here.
+ *
+ * The Claude Code implementation is `claudeCodeHookProtocol` in
+ * `src/adapters/claude-code/hook-protocol.ts`.
+ */
+export interface HookProtocol {
+    /** Stable identifier, e.g. "claude-code". */
+    readonly name: string;
+    /** Exit code a hook process uses to block/deny a tool call (Claude Code: 2). */
+    readonly blockExitCode: number;
+    /** decision / permissionDecision values that mean "deny" the tool call. */
+    readonly denyDecisionValues: readonly string[];
+    /**
+     * Env vars a synthesized hook event carries beyond the JSON on stdin (Claude
+     * Code passes the event on stdin only; Codex adds session_id/cwd/PLUGIN_ROOT/…).
+     */
+    readonly eventEnvVars: readonly string[];
+}
+//# sourceMappingURL=hook-protocol.d.ts.map

package/dist/core/hook-protocol.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=hook-protocol.js.map

package/dist/core/layout.d.ts

@@ -0,0 +1,43 @@
+/**
+ * PluginLayout — the plugin/repo LAYOUT port (hexagonal format axis, the
+ * filesystem half). A harness's plugin layout is where its instruction file,
+ * skills, subagents, commands, hooks and settings live on disk, plus the env
+ * token expanded to the plugin root. The loader (`loadPlugin`) reads those from
+ * this descriptor instead of hard-coding Claude Code's `.claude-plugin/` /
+ * `.claude/` conventions, so a second harness (Codex) supplies its own
+ * `PluginLayout` and reuses the same loader.
+ *
+ * Paths are repo-relative (POSIX-style, `join`-friendly). The Claude Code
+ * implementation is `claudeCodeLayout` in `src/adapters/claude-code/layout.ts`.
+ */
+export interface PluginLayout {
+    /** Stable identifier, e.g. "claude-code". */
+    readonly name: string;
+    /** Plugin manifest, e.g. `.claude-plugin/plugin.json`. */
+    readonly manifestPath: string;
+    /** Convention path for a standalone hooks file, e.g. `hooks/hooks.json`. */
+    readonly hooksConventionPath: string;
+    /** Repo settings carrying hooks, e.g. `.claude/settings.json` or `.codex/config.toml`. */
+    readonly settingsPath: string;
+    /**
+     * How the settings file is encoded — `"json"` (Claude Code's settings.json) or
+     * `"toml"` (Codex's `config.toml` `[hooks]`). The loader dispatches a parser on
+     * it, so a TOML-configured harness's hooks aren't silently read as zero.
+     */
+    readonly settingsFormat: "json" | "toml";
+    /** Top-level instruction file, e.g. `CLAUDE.md`. */
+    readonly instructionFile: string;
+    /** Surface dirs materialized into the sandbox, e.g. skills/agents/commands. */
+    readonly surfaceDirs: readonly string[];
+    /** Dir the surfaces are materialized under, e.g. `.claude`. */
+    readonly materializeRoot: string;
+    /** Env token expanded to the plugin's absolute root in hook commands. */
+    readonly pluginRootToken: string;
+    /** Standalone MCP config file, e.g. `.mcp.json`. */
+    readonly mcpConfigFile: string;
+    /** Manifest key declaring MCP servers, e.g. `mcpServers`. */
+    readonly mcpManifestKey: string;
+    /** Dirs scanned for dangling intra-plugin file references. */
+    readonly intraRefDirs: readonly string[];
+}
+//# sourceMappingURL=layout.d.ts.map

package/dist/core/layout.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=layout.js.map

package/dist/core/model-mock.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ModelMock — the model-mock PORT (transport axis). A harness test tier runs the
+ * real agent against a fake, scripted model server so it needs no API key and is
+ * deterministic. This descriptor captures what the mock's WIRE FORMAT is: the API
+ * dialect it speaks, the endpoint that consumes a scripted turn, and the optional
+ * token-count endpoint a client probes. The research (research/harness-landscape.md)
+ * found the two concrete formats differ sharply — Claude Code speaks Anthropic
+ * **Messages** SSE at `/v1/messages`; Codex speaks OpenAI **Responses** SSE at
+ * `/v1/responses` — which is exactly the second implementation that makes this
+ * port designable.
+ *
+ * The HTTP server + per-event flush mechanics live in the harness's mock module
+ * (`startMock` for Claude Code); a second harness implements the same contract
+ * with its own renderer. The Claude Code descriptor is `claudeCodeModelMock` in
+ * `src/adapters/claude-code/model-mock.ts`.
+ */
+export interface ModelMock {
+    /** Stable identifier, e.g. "claude-code". */
+    readonly name: string;
+    /** The model API wire format, e.g. "anthropic-messages" or "openai-responses". */
+    readonly wireApi: string;
+    /** URL substring identifying a turn-consuming model request (e.g. "/v1/messages"). */
+    readonly modelEndpoint: string;
+    /** Token-count endpoint substring a client probes (e.g. "count_tokens"); omit if none. */
+    readonly countTokensEndpoint?: string;
+}
+//# sourceMappingURL=model-mock.d.ts.map

package/dist/core/model-mock.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=model-mock.js.map

package/dist/core/refs.d.ts

@@ -0,0 +1,62 @@
+import type { RuleSeverity } from "./types.js";
+/** An inline code span with its 1-based source line. */
+export interface Span {
+    readonly text: string;
+    readonly line: number;
+}
+/**
+ * Extract inline code spans, skipping fenced code blocks (R1). Returns each
+ * span's trimmed text and 1-based line.
+ */
+export declare function inlineSpans(markdown: string): Span[];
+/** A parsed file-qualified reference. */
+export interface SymbolRef {
+    readonly file: string;
+    readonly symbol: string;
+    readonly line: number;
+}
+/** A reference that failed verification. */
+export interface SymbolRefError extends SymbolRef {
+    readonly reason: string;
+}
+/** Extract the `vigiles:symbol` references from a markdown file. */
+export declare function symbolRefs(markdown: string): SymbolRef[];
+/**
+ * Verify the file-qualified symbol references in a markdown file: the named
+ * file must exist and define the named symbol. `basePath` is the directory the
+ * paths resolve against (the instruction file's own directory).
+ */
+export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
+/**
+ * Whether a span is a **linter-rule reference** that ought to be marked
+ * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the audit can verify the
+ * rule exists AND is enabled. High-signal only: a slash-scoped name with no file
+ * extension. A function-call form `` `foo(args)` `` is reduced to its callee.
+ *
+ * Deliberately NOT flagged (too noisy / undecidable): bare identifiers
+ * (`runHook`, `MAX_RETRIES` — usually API prose, mark opt-in via an explicit
+ * `vigiles:symbol`) and file paths (`src/x.ts`, `docs/y.md` — file refs).
+ */
+export declare function isCodeShaped(text: string): boolean;
+/**
+ * Unmarked linter-rule references — the spans the refs-hook nudges the agent to
+ * mark with `enforce()` / `<!-- vigiles:enforce ... -->` (or opt out of with
+ * `<!-- vigiles:ignore -->` / `<!-- vigiles:ignore-file -->`).
+ */
+export declare function unmarkedCodeRefs(markdown: string): Span[];
+/**
+ * The reference issues in an instruction file, as one human-readable line each:
+ * a `vigiles:symbol` mark whose symbol is missing, plus every unmarked
+ * code-shaped span that ought to be a mark. The shared detector behind both the
+ * `vigiles refs` CLI and the PostToolUse refs-hook.
+ */
+export declare function collectRefIssues(markdown: string, basePath: string): string[];
+/** What the refs-hook should do given the issue count and configured severity. */
+export type RefsHookAction = "ok" | "nudge" | "block";
+/**
+ * Map detected issues + the `unmarked-refs` rule severity to a hook action:
+ * no issues or `false` → ok, `"error"` → block (exit 2), anything else
+ * (`"warn"`, the default) → a non-blocking nudge.
+ */
+export declare function refsHookAction(issueCount: number, severity: RuleSeverity): RefsHookAction;
+//# sourceMappingURL=refs.d.ts.map

package/dist/{refs.js → core/refs.js}

@@ -5,6 +5,8 @@ exports.symbolRefs = symbolRefs;
 exports.verifySymbolRefs = verifySymbolRefs;
 exports.isCodeShaped = isCodeShaped;
 exports.unmarkedCodeRefs = unmarkedCodeRefs;
+exports.collectRefIssues = collectRefIssues;
+exports.refsHookAction = refsHookAction;
 /**
  * vigiles — file-qualified symbol reference verification (variant A).
  *
@@ -97,35 +99,32 @@ function verifySymbolRefs(markdown, basePath) {
 // ---------------------------------------------------------------------------
 // Enforcement: force code references to carry the file-qualified mark
 // ---------------------------------------------------------------------------
-const PATH_LIKE = /[/\\]|\.[A-Za-z0-9]+$/; // a path or a bare filename
-const PLAIN_ID = /^[A-Za-z_]\w*$/;
-const SCOPED = /^[A-Za-z_]\w*(?:#|::)[\w?!]+$/;
+const HAS_EXT = /\.[A-Za-z0-9]+$/; // a file extension → a path/filename, not a rule
+// A linter-rule reference: a slash-scoped `linter/rule` (optionally `@scoped`)
+// with NO file extension — `eslint/no-console`, `@typescript-eslint/no-x`,
+// `boundaries/dependencies`. Deliberately NOT a path (`src/x.ts`) or a bare
+// identifier (`runHook`): those are excluded.
+const RULE_SHAPED = /^@?[a-z][\w-]*(?:\/[\w-]+)+$/;
 const IGNORE_FILE = /<!--\s*vigiles:ignore-file\s*-->/;
 const IGNORE_LINE = /<!--\s*vigiles:ignore\s*-->/;
 /**
- * Whether a span looks like a *code reference* that ought to carry a
- * file-qualified mark — a scoped name, or an identifier that isn't a bare
- * lowercase prose word. A function-call form `` `foo(args)` `` is treated as a
- * reference to its callee `foo`. Paths/filenames are excluded (they are `file`
- * refs).
+ * Whether a span is a **linter-rule reference** that ought to be marked
+ * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the audit can verify the
+ * rule exists AND is enabled. High-signal only: a slash-scoped name with no file
+ * extension. A function-call form `` `foo(args)` `` is reduced to its callee.
+ *
+ * Deliberately NOT flagged (too noisy / undecidable): bare identifiers
+ * (`runHook`, `MAX_RETRIES` — usually API prose, mark opt-in via an explicit
+ * `vigiles:symbol`) and file paths (`src/x.ts`, `docs/y.md` — file refs).
  */
 function isCodeShaped(text) {
     const callee = text.replace(/\s*\([^)]*\)\s*$/, ""); // `foo(args)` → `foo`
-    if (SCOPED.test(callee))
-        return true;
-    if (!PLAIN_ID.test(callee))
-        return false;
-    const hasUnderscore = callee.includes("_");
-    const hasCamel = /[a-z][A-Z]/.test(callee);
-    const isPascal = /^[A-Z][a-z]/.test(callee);
-    const isScreaming = /^[A-Z][A-Z0-9_]+$/.test(callee);
-    return hasUnderscore || hasCamel || isPascal || isScreaming;
+    return RULE_SHAPED.test(callee) && !HAS_EXT.test(callee);
 }
 /**
- * Code-shaped inline references that are NOT yet marked — the spans the
- * enforcement hook makes the agent mark as `` `vigiles:symbol path.ext#symbol` ``
- * or opt out of with `<!-- vigiles:ignore -->` (or `<!-- vigiles:ignore-file -->`
- * for the whole file).
+ * Unmarked linter-rule references — the spans the refs-hook nudges the agent to
+ * mark with `enforce()` / `<!-- vigiles:enforce ... -->` (or opt out of with
+ * `<!-- vigiles:ignore -->` / `<!-- vigiles:ignore-file -->`).
  */
 function unmarkedCodeRefs(markdown) {
     if (IGNORE_FILE.test(markdown))
@@ -136,9 +135,36 @@ function unmarkedCodeRefs(markdown) {
             return false;
         if (SYMBOL_MARK.test(span.text))
             return false; // already a vigiles:symbol mark
-        if (PATH_LIKE.test(span.text))
-            return false; // a path/filename → file ref
         return isCodeShaped(span.text);
     });
 }
+/**
+ * The reference issues in an instruction file, as one human-readable line each:
+ * a `vigiles:symbol` mark whose symbol is missing, plus every unmarked
+ * code-shaped span that ought to be a mark. The shared detector behind both the
+ * `vigiles refs` CLI and the PostToolUse refs-hook.
+ */
+function collectRefIssues(markdown, basePath) {
+    const out = [];
+    for (const b of verifySymbolRefs(markdown, basePath)) {
+        out.push(`line ${String(b.line)}: ${b.reason}`);
+    }
+    for (const u of unmarkedCodeRefs(markdown)) {
+        out.push(`line ${String(u.line)}: \`${u.text}\` is an unmarked linter-rule ` +
+            `reference — mark it as \`enforce("${u.text}")\` (typed spec) or ` +
+            `\`<!-- vigiles:enforce ${u.text} -->\` (markdown) so audit can verify ` +
+            `it exists and is enabled, or add <!-- vigiles:ignore --> if it is prose`);
+    }
+    return out;
+}
+/**
+ * Map detected issues + the `unmarked-refs` rule severity to a hook action:
+ * no issues or `false` → ok, `"error"` → block (exit 2), anything else
+ * (`"warn"`, the default) → a non-blocking nudge.
+ */
+function refsHookAction(issueCount, severity) {
+    if (issueCount === 0 || severity === false)
+        return "ok";
+    return severity === "error" ? "block" : "nudge";
+}
 //# sourceMappingURL=refs.js.map