vigiles 36.0.0 → 38.0.0

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

@@ -130,6 +130,15 @@ export declare const vigilesConfigSchema: z.ZodObject<{
         "disallowed-tools-contract": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "description-overlap": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "skill-description-budget": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
+        "compile-budget": z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>, z.ZodTuple<[z.ZodLiteral<"warn">, z.ZodObject<{
+            maxEntryChars: z.ZodOptional<z.ZodNumber>;
+            maxSectionChars: z.ZodOptional<z.ZodNumber>;
+            maxRulesChars: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], null>, z.ZodTuple<[z.ZodLiteral<"error">, z.ZodObject<{
+            maxEntryChars: z.ZodOptional<z.ZodNumber>;
+            maxSectionChars: z.ZodOptional<z.ZodNumber>;
+            maxRulesChars: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], null>]>>;
         "frontmatter-valid": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "mcp-hook-target-resolves": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;
         "lethal-trifecta": z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<"warn">, z.ZodLiteral<"error">, z.ZodLiteral<false>, z.ZodLiteral<"off">, z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<true>]>, z.ZodTransform<false | "error" | "warn", boolean | 0 | 1 | 2 | "error" | "warn" | "off">>>;

package/dist/core/config-schema.js

@@ -122,6 +122,20 @@ const testCoverageConfig = zod_1.z
     testExtension: zod_1.z.string().optional(),
 })
     .strict();
+/**
+ * Thresholds for `compile-budget`, in characters. Each one left out keeps its
+ * built-in default; `0` turns that one budget off.
+ */
+const compileBudgetThresholds = zod_1.z
+    .object({
+    /** One `commands` description. */
+    maxEntryChars: zod_1.z.number().optional(),
+    /** One named prose section. */
+    maxSectionChars: zod_1.z.number().optional(),
+    /** The whole rendered Rules section. */
+    maxRulesChars: zod_1.z.number().optional(),
+})
+    .strict();
 /**
  * Every validation rule, with its shipped default severity.
  *
@@ -156,6 +170,7 @@ const rulesSchema = zod_1.z
     "disallowed-tools-contract": severitySchema.default("warn"),
     "description-overlap": severitySchema.default("warn"),
     "skill-description-budget": severitySchema.default("warn"),
+    "compile-budget": withOptions(compileBudgetThresholds).default("warn"),
     "frontmatter-valid": severitySchema.default("warn"),
     "mcp-hook-target-resolves": severitySchema.default("warn"),
     "lethal-trifecta": severitySchema.default("warn"),

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

@@ -18,6 +18,7 @@
  * runners re-export these names, so every existing import keeps resolving.
  */
 import type { ToolCall, HookFire, ModelRequest } from "./harness-driver.js";
+import type { StubCall } from "./stub-rules.js";
 /** Per-run resource use, parsed from the terminal `result` event (0 when absent). */
 export interface EvalUsage {
     /** `total_cost_usd` reported by the harness binary. */
@@ -99,6 +100,13 @@ export interface Trace {
      * Empty unless the stream was captured / the harness emits subagent events.
      */
     readonly subagents?: readonly SubagentTrace[];
+    /**
+     * Every invocation of a tool stub during the run, in order — including calls a
+     * script the agent ran made itself (`execFile(gh, …)`), which never appear as
+     * a tool call. Each says which rule answered it, or that none did. Absent when
+     * the run had no stubs (eval tier: `stubs` on the spec).
+     */
+    readonly stubCalls?: readonly StubCall[];
     /** Final contents of a file under the working dir, or null if absent. */
     file(path: string): string | null;
 }
@@ -137,7 +145,7 @@ export interface AgentRunArgs {
      * When true, `env` is the COMPLETE spawn environment (an ephemeral run env from
      * `ephemeralRunEnv`) — the runner does NOT prepend `process.env`, so the
      * real `$HOME` / secrets are scrubbed. Default false: `env` is an overlay over
-     * `process.env` (the byte-identical-to-today path). Set only by `ephemeralEnv`.
+     * `process.env` (the byte-identical-to-today path). Set only by an ephemeral `env`.
      */
     readonly replaceEnv?: boolean;
 }

package/dist/core/eval-spec-parse.d.ts

@@ -0,0 +1,14 @@
+import { type ToolStub } from "./stub-rules.js";
+import { type RunEnv } from "./run-env.js";
+/**
+ * Parse an eval spec's `stubs`. Absent → `[]`. Throws, naming the field, on the
+ * old shape, a malformed rule, a stateful RegExp, or two stubs of one name.
+ */
+export declare function parseToolStubs(raw: unknown, caller: string): readonly ToolStub[];
+/**
+ * Parse an eval spec's `env`, including its seeded HOME: every seed path is
+ * HOME-relative, stays inside HOME, and does not overwrite one of the harness's
+ * own auth files (`keepHomeFiles`). Throws before any trial on a bad value.
+ */
+export declare function parseRunEnv(raw: unknown, caller: string, keepHomeFiles: readonly string[]): RunEnv;
+//# sourceMappingURL=eval-spec-parse.d.ts.map

package/dist/core/eval-spec-parse.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseToolStubs = parseToolStubs;
+exports.parseRunEnv = parseRunEnv;
+/**
+ * The eval spec boundary for `stubs` and `env` — parsed ONCE, before anything is
+ * packaged or spent, into the plain data the runner then trusts.
+ *
+ * An eval file is often plain JavaScript, so no type checks its literal. A shape
+ * the runner would silently mis-read must fail here, naming the field and the
+ * rewrite. Two such shapes are the reason this module exists:
+ *
+ * - the old argv-blind stub `{ name, stdout }`, which printed one answer for
+ *   every invocation (a fabricated observation for every command nobody
+ *   anticipated);
+ * - a spec with no `env`, which used to inherit your HOME and environment by
+ *   default — so a comparison measured the author's machine.
+ *
+ * zod lives HERE and not in `stub-rules.ts`: the stub process reads its rules
+ * once per `gh` call and must not pay for a schema library; the rules file it
+ * reads is this parse's output, written by vigiles.
+ */
+const zod_1 = require("zod");
+const stub_rules_js_1 = require("./stub-rules.js");
+const run_env_js_1 = require("./run-env.js");
+/** `stubs[0].rules[1].argv` from a zod issue path. */
+function pathText(root, path) {
+    return path.reduce((acc, k) => typeof k === "number" ? `${acc}[${String(k)}]` : `${acc}.${String(k)}`, root);
+}
+function refuse(caller, root, error) {
+    const lines = error.issues.map((i) => `${caller}: ${pathText(root, i.path)}: ${i.message}`);
+    throw new Error(lines.join("\n"));
+}
+// --- stubs ---------------------------------------------------------------------
+const regexToken = zod_1.z.instanceof(RegExp).refine((r) => !r.global && !r.sticky, {
+    message: "a RegExp token may not carry the flags g and y — test() would carry lastIndex from one call to the next",
+});
+const token = zod_1.z.union([zod_1.z.string(), regexToken]);
+const restToken = zod_1.z
+    .strictObject({ kind: zod_1.z.literal("rest") })
+    .transform(() => stub_rules_js_1.ARGV_REST);
+/** A plain object (not an array, not a RegExp), readable by key. */
+const isObj = (v) => typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    !(v instanceof RegExp);
+const isRestToken = (t) => isObj(t) && t.kind === "rest";
+const argvPattern = zod_1.z
+    .array(zod_1.z.union([token, restToken]))
+    .refine((p) => p.slice(0, -1).every((t) => !isRestToken(t)), {
+    message: "experimental_stub.rest may appear only as the last token",
+});
+const answerFields = {
+    stdout: zod_1.z.string().optional(),
+    stderr: zod_1.z.string().optional(),
+    exitCode: zod_1.z.number().int().min(0).max(255).optional(),
+};
+const reply = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z.strictObject({ kind: zod_1.z.literal("always"), ...answerFields }),
+    zod_1.z.strictObject({
+        kind: zod_1.z.literal("inOrder"),
+        answers: zod_1.z
+            .array(zod_1.z.strictObject(answerFields))
+            .min(1, { message: "an inOrder reply needs at least one answer" }),
+    }),
+]);
+const rule = zod_1.z
+    .strictObject({
+    argv: argvPattern,
+    contains: zod_1.z.array(token).optional(),
+    reply,
+})
+    .refine((r) => r.contains === undefined || isRestToken(r.argv.at(-1)), {
+    message: "`contains` matches tokens after the positional prefix, so it needs a trailing experimental_stub.rest in `argv`",
+    path: ["contains"],
+});
+const stub = zod_1.z.strictObject({
+    name: zod_1.z
+        .string()
+        .min(1)
+        .refine((n) => !/[/\\]/.test(n) && n !== "." && n !== "..", {
+        message: "a bare binary name, as it is looked up on PATH (no path separator)",
+    }),
+    rules: zod_1.z.array(rule).min(1, {
+        message: "a stub needs at least one rule — one per command the agent runs",
+    }),
+});
+/** Is this the removed `{ name, stdout?, stderr?, exitCode? }` shape? */
+const isOldShape = (s) => isObj(s) &&
+    !("rules" in s) &&
+    ["stdout", "stderr", "exitCode"].some((k) => k in s);
+function oldShapeMessage(caller, i, s) {
+    const name = typeof s.name === "string" ? s.name : "<tool>";
+    const stdout = typeof s.stdout === "string" ? JSON.stringify(s.stdout) : '"…"';
+    return (`${caller}: stubs[${String(i)}] (${JSON.stringify(name)}) is the old shape \`{ name, stdout }\`, which printed one answer for EVERY invocation — ` +
+        `a command nobody scripted got that answer as if the tool had said it. A stub is now a list of rules, one per command the agent runs:\n` +
+        `    experimental_stub(${JSON.stringify(name)}, [\n` +
+        `      { argv: ["<command>", experimental_stub.rest], reply: { kind: "always", stdout: ${stdout} } },\n` +
+        `      // one rule per further command; an invocation no rule answers fails the run\n` +
+        `    ])\n` +
+        `  The argv a run used is printed when it goes unanswered, so the first run tells you which rules to add.`);
+}
+/**
+ * Parse an eval spec's `stubs`. Absent → `[]`. Throws, naming the field, on the
+ * old shape, a malformed rule, a stateful RegExp, or two stubs of one name.
+ */
+function parseToolStubs(raw, caller) {
+    if (raw === undefined)
+        return [];
+    const items = Array.isArray(raw) ? raw : [];
+    const old = items.findIndex(isOldShape);
+    const oldItem = items[old];
+    if (isOldShape(oldItem))
+        throw new Error(oldShapeMessage(caller, old, oldItem));
+    const parsed = zod_1.z.array(stub).safeParse(raw);
+    if (!parsed.success)
+        refuse(caller, "stubs", parsed.error);
+    const names = parsed.data.map((s) => s.name);
+    const dup = names.find((n, i) => names.indexOf(n) !== i);
+    if (dup !== undefined)
+        throw new Error(`${caller}: two stubs named ${JSON.stringify(dup)} — one binary has one stub; put both rule lists in it.`);
+    // The zod output has the shape; `toToolStub` gives it the type, without a cast.
+    return parsed.data.map(stub_rules_js_1.toToolStub);
+}
+// --- env -----------------------------------------------------------------------
+const homeSeed = zod_1.z.strictObject({
+    kind: zod_1.z.literal("files"),
+    files: zod_1.z.record(zod_1.z.string(), zod_1.z.string()),
+});
+const runEnv = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z.strictObject({ kind: zod_1.z.literal("ephemeral"), home: homeSeed.optional() }),
+    zod_1.z.strictObject({
+        kind: zod_1.z.literal("inherit"),
+        reason: zod_1.z.string().refine((r) => r.trim() !== "", {
+            message: "say why this run must see your real HOME and environment",
+        }),
+    }),
+]);
+function envRequiredMessage(caller) {
+    return (`${caller}: \`env\` is required — say where each trial runs:\n` +
+        `    env: { kind: "ephemeral" }               a throwaway HOME and a scrubbed environment; only the harness's own auth passes\n` +
+        `    env: { kind: "inherit", reason: "…" }    your real HOME and environment; the reason is printed with the report\n` +
+        `  There is no default. Inheriting measures your machine (your config, your tokens), and an ephemeral run\n` +
+        `  fails on its first trial if your auth is not where the harness expects it — so the choice is yours to make.`);
+}
+/**
+ * Parse an eval spec's `env`, including its seeded HOME: every seed path is
+ * HOME-relative, stays inside HOME, and does not overwrite one of the harness's
+ * own auth files (`keepHomeFiles`). Throws before any trial on a bad value.
+ */
+function parseRunEnv(raw, caller, keepHomeFiles) {
+    if (raw === undefined)
+        throw new Error(envRequiredMessage(caller));
+    if (isObj(raw) && raw.kind === "inherit" && "home" in raw)
+        throw new Error(`${caller}: env.home: \`home\` exists only on an ephemeral env: seeding would write into your real HOME. ` +
+            `Use env: { kind: "ephemeral", home: … }.`);
+    const parsed = runEnv.safeParse(raw);
+    if (!parsed.success)
+        refuse(caller, "env", parsed.error);
+    const env = parsed.data;
+    if (env.kind === "ephemeral" && env.home !== undefined) {
+        const plan = (0, run_env_js_1.planHome)(env.home, keepHomeFiles);
+        if (plan.kind === "refused")
+            throw new Error(`${caller}: env.home.files: ${plan.reason}`);
+    }
+    return env;
+}
+//# sourceMappingURL=eval-spec-parse.js.map

package/dist/core/markdown.d.ts

@@ -118,4 +118,21 @@ export interface MarkdownRef {
  * which is not recovered — the regexes this replaces did not recover it either.
  */
 export declare function markdownRefs(src: string): MarkdownRef[];
+/**
+ * The fragment ids a markdown file defines — what `file.md#<id>` can land on.
+ *
+ * Two sources, because both are how real files are linked into:
+ *
+ * - every HEADING, slugged the way GitHub slugs it (lowercase; drop everything
+ *   that is not a letter, number, space, `-` or `_`; spaces to `-`; a repeated
+ *   slug gets `-1`, `-2`, …), with the heading's text taken from the parser's
+ *   inline token, so emphasis and code spans do not leak their markers in;
+ * - every explicit `id="…"` / `name="…"` on raw HTML (`<a id="why"></a>`), which
+ *   is how a file in a non-Latin language gives its sections stable ASCII ids.
+ *
+ * Other renderers slug differently (GitLab, mkdocs). A link that resolves on
+ * GitHub and nowhere else is still a link this accepts; one that resolves
+ * NOWHERE — a renamed heading — is what it exists to catch.
+ */
+export declare function markdownAnchors(src: string): ReadonlySet<string>;
 //# sourceMappingURL=markdown.d.ts.map

package/dist/core/markdown.js

@@ -4,6 +4,7 @@ exports.fencedLineFlags = fencedLineFlags;
 exports.proseLines = proseLines;
 exports.fencedCodeBlocks = fencedCodeBlocks;
 exports.markdownRefs = markdownRefs;
+exports.markdownAnchors = markdownAnchors;
 const MarkdownIt = () => require("markdown-it");
 // One reusable parser; parse() is stateless across calls.
 let mdCached = null;
@@ -233,4 +234,60 @@ function refsInInline(children, line, out) {
             out.push({ kind: "code", value: child.content, line });
     }
 }
+/**
+ * The fragment ids a markdown file defines — what `file.md#<id>` can land on.
+ *
+ * Two sources, because both are how real files are linked into:
+ *
+ * - every HEADING, slugged the way GitHub slugs it (lowercase; drop everything
+ *   that is not a letter, number, space, `-` or `_`; spaces to `-`; a repeated
+ *   slug gets `-1`, `-2`, …), with the heading's text taken from the parser's
+ *   inline token, so emphasis and code spans do not leak their markers in;
+ * - every explicit `id="…"` / `name="…"` on raw HTML (`<a id="why"></a>`), which
+ *   is how a file in a non-Latin language gives its sections stable ASCII ids.
+ *
+ * Other renderers slug differently (GitLab, mkdocs). A link that resolves on
+ * GitHub and nowhere else is still a link this accepts; one that resolves
+ * NOWHERE — a renamed heading — is what it exists to catch.
+ */
+function markdownAnchors(src) {
+    // The html-enabled parser: with the shared one, `<a id="x">` is paragraph
+    // text and its id would be invisible.
+    const tokens = mdProse().parse(src, {});
+    const headings = tokens.flatMap((t, i) => t.type === "heading_open" ? [headingSlug(tokens[i + 1])] : []);
+    const explicit = tokens
+        .flatMap(htmlOf)
+        .flatMap((h) => [...h.matchAll(HTML_ID)].map((m) => m[1]));
+    return new Set([...numberRepeats(headings), ...explicit]);
+}
+/** An explicit `id="…"` / `name="…"` on raw HTML. */
+const HTML_ID = /\b(?:id|name)\s*=\s*["']([^"']+)["']/g;
+/** A heading's GitHub slug before repeats are numbered, from its inline token. */
+function headingSlug(inline) {
+    return (inline?.children ?? [])
+        .filter((c) => c.type === "text" || c.type === "code_inline")
+        .map((c) => c.content)
+        .join("")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .trim()
+        .replace(/\s/g, "-");
+}
+/** GitHub's numbering of a repeated slug: `x`, `x-1`, `x-2`, … */
+function numberRepeats(bases) {
+    return bases.map((base, i) => {
+        const k = bases.slice(0, i).filter((b) => b === base).length;
+        return k === 0 ? base : `${base}-${String(k)}`;
+    });
+}
+/** The raw HTML a token carries: a block, an inline, or an inline run's HTML. */
+function htmlOf(t) {
+    if (t.type === "html_block" || t.type === "html_inline")
+        return [t.content];
+    if (t.type !== "inline")
+        return [];
+    return (t.children ?? [])
+        .filter((c) => c.type === "html_inline")
+        .map((c) => c.content);
+}
 //# sourceMappingURL=markdown.js.map

package/dist/core/presets.d.ts

@@ -30,7 +30,7 @@ import type { RulesConfig } from "./types.js";
  * `untested-*`): a clean repo fails those until the work is done, so they stay
  * an explicit opt-in (`init --strict`).
  */
-export declare const RECOMMENDED_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap"];
+export declare const RECOMMENDED_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap", "compile-budget"];
 /** The preset names `extends` accepts. One today; the tuple is the enum. */
 export declare const PRESET_NAMES: readonly ["vigiles:recommended"];
 /** A preset name `extends` accepts. */

package/dist/core/presets.js

@@ -24,6 +24,7 @@ exports.RECOMMENDED_RULES = [
     "mcp-hook-target-resolves",
     "disallowed-tools-contract",
     "description-overlap",
+    "compile-budget",
 ];
 /** The preset names `extends` accepts. One today; the tuple is the enum. */
 exports.PRESET_NAMES = ["vigiles:recommended"];

package/dist/core/rule-meta.js

@@ -226,6 +226,18 @@ exports.RULE_META = {
         summary: "The always-loaded instruction weight did not move off its committed baseline.",
         detector: "compareToBaseline",
     },
+    "compile-budget": {
+        id: "compile-budget",
+        // Exact once a threshold is chosen: a length or a count read off the spec
+        // and its rendered output. The threshold is the judgment: the default stays
+        // `warn`, and `vigiles:recommended` sets `error`.
+        bucket: "structural-closed",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "A compiled instruction file stays within its size budgets (command entries, sections, the Rules total).",
+        detector: "checkContentBudgets",
+        upstreamPrevention: "compile measures the spec before writing; a render policy (enforce render, guidance details) meets a budget without deleting a rule",
+    },
     "skill-description-budget": {
         id: "skill-description-budget",
         bucket: "heuristic-behavioral",

package/dist/core/run-env.d.ts

@@ -6,7 +6,7 @@
  *
  * - SCRUBBED (`scrubbedRunEnv`): a throwaway HOME/TMPDIR, the OS essentials, the
  *   harness's declared auth, and the caller's own named extras. Everything else
- *   is dropped. The eval tier's `ephemeralEnv` and the harness-tier preflight of
+ *   is dropped. The eval tier's `env: { kind: "ephemeral" }` and the harness-tier preflight of
  *   `experimental_outputStyleArms` use it.
  * - INHERITED (`withoutSessionIdentity`): the caller's env as-is, minus the
  *   harness's declared session identity. The default spawn of both tiers.
@@ -46,5 +46,50 @@ export declare function scrubbedRunEnv(base: EnvLike, opts: {
  * a plain spawn env. Without a policy nothing is removed.
  */
 export declare function withoutSessionIdentity(base: EnvLike, policy?: RunEnvPolicy): Readonly<Record<string, string>>;
+/** Files to write under a throwaway HOME: HOME-relative POSIX path → contents. */
+export type HomeFiles = Readonly<Record<string, string>>;
+/**
+ * Where a throwaway HOME's starting contents come from. A FILE map, so an empty
+ * directory cannot be expressed — Claude Code's startup housekeeping removes
+ * empty task directories, and a seed that could hold one would lose it.
+ */
+export interface HomeSeed {
+    readonly kind: "files";
+    readonly files: HomeFiles;
+}
+/**
+ * Where a run executes. Two cases, and `home` exists only on `ephemeral`: there
+ * is no way to write "seed my real HOME".
+ *
+ * - `ephemeral` — a throwaway HOME (seeded from `home`, then given the
+ *   harness's own auth files) and a scrubbed environment.
+ * - `inherit` — your real HOME and environment, minus the parent session's
+ *   identity. `reason` says why, and is printed with the report.
+ */
+export type RunEnv = {
+    readonly kind: "ephemeral";
+    readonly home?: HomeSeed;
+} | {
+    readonly kind: "inherit";
+    readonly reason: string;
+};
+/** One file a seed writes, HOME-relative. */
+export interface HomeFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** The files a seed writes, sorted by path — or why the seed is refused. */
+export type HomePlan = {
+    readonly kind: "ok";
+    readonly files: readonly HomeFile[];
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+};
+/**
+ * Validate a seed and list the files it writes. Pure. `keepHomeFiles` are the
+ * harness's auth files (`RunEnvPolicy.keepHomeFiles`), copied in after the seed.
+ */
+export declare function planHome(seed: HomeSeed | undefined, keepHomeFiles: readonly string[]): HomePlan;
 export {};
 //# sourceMappingURL=run-env.d.ts.map

package/dist/core/run-env.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OS_ESSENTIAL_ENV = void 0;
 exports.scrubbedRunEnv = scrubbedRunEnv;
 exports.withoutSessionIdentity = withoutSessionIdentity;
+exports.planHome = planHome;
 /**
  * What ANY spawned process needs to function, whatever the harness: resolve
  * binaries (`PATH`) and keep the locale and terminal (`LANG`, `LC_*`, `TERM`).
@@ -48,4 +49,62 @@ function withoutSessionIdentity(base, policy) {
 function defined(base, keep) {
     return Object.fromEntries(Object.entries(base).filter((e) => e[1] !== undefined && keep(e[0])));
 }
+/** Why `path` cannot be a HOME-relative seed path, or undefined when it can. */
+function seedPathProblem(path, keepHomeFiles) {
+    if (path === "")
+        return "an empty path";
+    if (path.startsWith("/") || path.includes("\\"))
+        return `${JSON.stringify(path)} is not a HOME-relative POSIX path`;
+    const parts = path.split("/");
+    if (parts.some((p) => p === "" || p === "." || p === ".."))
+        return `${JSON.stringify(path)} must stay inside HOME and be spelled plainly (no "", ".", or ".." segments)`;
+    if (keepHomeFiles.includes(path))
+        return `${JSON.stringify(path)} is the harness's own auth file, which the run copies in itself; a seed may not replace it`;
+    return undefined;
+}
+/**
+ * The pairs that cannot both exist: one path written as a FILE while another
+ * needs it to be a DIRECTORY (`a` and `a/b`). Over the seed's paths and the
+ * harness's auth files, as a seed file standing on an auth file's parent
+ * (`.claude`) would fail the same way. Auth files among themselves are the
+ * harness's own business. Without this the run fails mid-trial with a raw
+ * `EEXIST`/`ENOTDIR`, after the trial's directories were built.
+ */
+function seedConflicts(paths, keepHomeFiles) {
+    const isSeed = (p) => paths.includes(p);
+    const label = (p) => isSeed(p)
+        ? JSON.stringify(p)
+        : `${JSON.stringify(p)} (the harness's own auth file)`;
+    const all = [...paths, ...keepHomeFiles];
+    return all.flatMap((file) => all
+        .filter((under) => under.startsWith(`${file}/`))
+        .filter((under) => isSeed(file) || isSeed(under))
+        .map((under) => `${label(file)} is written as a file but ${label(under)} needs it to be a directory`));
+}
+/**
+ * Validate a seed and list the files it writes. Pure. `keepHomeFiles` are the
+ * harness's auth files (`RunEnvPolicy.keepHomeFiles`), copied in after the seed.
+ */
+function planHome(seed, keepHomeFiles) {
+    if (seed === undefined)
+        return { kind: "ok", files: [] };
+    const paths = Object.keys(seed.files).sort();
+    if (paths.length === 0)
+        return {
+            kind: "refused",
+            reason: "a files seed with no files — omit `home` for an empty HOME",
+        };
+    const problems = paths.flatMap((p) => {
+        const why = seedPathProblem(p, keepHomeFiles);
+        return why === undefined ? [] : [why];
+    });
+    // Conflicts are read over well-formed paths only: a "" or "/x" would pair with everything.
+    const refusals = problems.length > 0 ? problems : seedConflicts(paths, keepHomeFiles);
+    if (refusals.length > 0)
+        return { kind: "refused", reason: refusals.join("; ") };
+    return {
+        kind: "ok",
+        files: paths.map((path) => ({ path, contents: seed.files[path] ?? "" })),
+    };
+}
 //# sourceMappingURL=run-env.js.map

package/dist/core/spec.d.ts

@@ -94,6 +94,30 @@ export interface OpenToolVocabulary extends ToolVocabulary {
  * untyped surface accepts any tools.
  */
 export type AllowedAt<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = P extends "pure" ? V["readOnly"] : P extends "bounded" ? V["bounded"] : string;
+/**
+ * Where a rule's long text lives when the compiled file carries a short form —
+ * a `file()` reference (verified to exist, like every other one) and an
+ * optional anchor inside it (verified to be a heading or an explicit
+ * `<a id="…">` in that file). Rendered as a `[Details](path#anchor)` link.
+ */
+export interface RuleDetails {
+    readonly file: FileRef;
+    readonly anchor?: string;
+}
+/**
+ * How much of an `enforce()` rule the compiled file carries (#355).
+ *
+ * - `"full"` (default) — the rule id and the whole `why`, as always.
+ * - `"line"` — the rule id and the first sentence of `why`.
+ * - `"id"` — the rule id only: the linter already holds the rule, so the prose
+ *   is a second copy that costs tokens on every request and can drift.
+ *
+ * Whatever is rendered, the rule stays whole in the SPEC — lint, coverage, the
+ * audit rule map and `enforce-rules-format` read the spec, not the markdown —
+ * and the integrity hash is taken over the RENDERED file, so it stays a
+ * function of what the model actually sees.
+ */
+export type RuleRender = "full" | "line" | "id";
 /** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.) or to a vigiles-internal check. */
 export interface EnforceRule {
     readonly _kind: "enforce";
@@ -101,12 +125,29 @@ export interface EnforceRule {
     readonly why: string;
     /** Skip verification for this rule. Default: true (verify). */
     readonly verify: boolean;
+    /** How much of the rule the compiled file carries. Default `"full"`. */
+    readonly render?: RuleRender;
+    /** Where the long text lives; rendered as a verified link. */
+    readonly details?: RuleDetails;
 }
 /** A guidance-only rule (prose, no enforcement). */
 export interface GuidanceRule {
     readonly _kind: "guidance";
     readonly text: string;
+    /** Where the long text lives; rendered as a verified link after `text`. */
+    readonly details?: RuleDetails;
 }
+/**
+ * The `details` half of a rule's options. An `anchor` is only meaningful
+ * inside a `details` file, so the type refuses one without the other.
+ */
+export type RuleDetailsOptions = {
+    readonly details: FileRef;
+    readonly anchor?: string;
+} | {
+    readonly details?: undefined;
+    readonly anchor?: never;
+};
 /** A reactive rule: runs a command when watched files change. */
 export interface GuardRule {
     readonly _kind: "guard";
@@ -130,13 +171,15 @@ export type Rule = EnforceRule | GuidanceRule | GuardRule;
  */
 export declare function enforce(ref: NoInfer<StrictLinterRule> | VigilesRef, why: string, options?: {
     verify?: boolean;
-}): EnforceRule;
+    render?: RuleRender;
+} & RuleDetailsOptions): EnforceRule;
 /**
  * Declare a guidance-only rule.
  *
  *   guidance("Google unfamiliar APIs before implementing.")
+ *   guidance("Short statement.", { details: file("docs/rules/x.md"), anchor: "why" })
  */
-export declare function guidance(text: string): GuidanceRule;
+export declare function guidance(text: string, options?: RuleDetailsOptions): GuidanceRule;
 /**
  * Declare a reactive guard: runs a command when watched files change.
  *

package/dist/core/spec.js

@@ -55,6 +55,13 @@ exports.BUILTIN_LINTERS = [
     "golangci-lint",
     "cedar",
 ];
+const detailsOf = (o) => {
+    if (!o?.details)
+        return undefined;
+    return o.anchor === undefined
+        ? { file: o.details }
+        : { file: o.details, anchor: o.anchor };
+};
 // ---------------------------------------------------------------------------
 // Builder functions
 // ---------------------------------------------------------------------------
@@ -72,21 +79,28 @@ exports.BUILTIN_LINTERS = [
  *   enforce("vigiles/orphan-docs", "No docs without spec references.")
  */
 function enforce(ref, why, options) {
+    const details = detailsOf(options);
     return {
         _kind: "enforce",
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         linterRule: ref,
         why,
         verify: options?.verify ?? true,
+        ...(options?.render === undefined ? {} : { render: options.render }),
+        ...(details ? { details } : {}),
     };
 }
 /**
  * Declare a guidance-only rule.
  *
  *   guidance("Google unfamiliar APIs before implementing.")
+ *   guidance("Short statement.", { details: file("docs/rules/x.md"), anchor: "why" })
  */
-function guidance(text) {
-    return { _kind: "guidance", text };
+function guidance(text, options) {
+    const details = detailsOf(options);
+    return details
+        ? { _kind: "guidance", text, details }
+        : { _kind: "guidance", text };
 }
 /**
  * Declare a reactive guard: runs a command when watched files change.