vigiles 5.1.0 → 5.2.0

package/dist/core/effects.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyToolEffect = classifyToolEffect;
+exports.effectSurface = effectSurface;
+exports.purityViolations = purityViolations;
+exports.pureContractViolations = pureContractViolations;
+exports.decidePurityGate = decidePurityGate;
+const hash_js_1 = require("./hash.js");
+const bash_effects_js_1 = require("./bash-effects.js");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Strips a `Tool(restriction)` suffix and returns the base tool name. */
+function baseTool(raw) {
+    return raw.split("(")[0].trim();
+}
+/** Returns true for the wildcard sentinels that mean "inherits-all". */
+function isWildcard(tool) {
+    return tool === "" || tool === "*";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Classify the effect of ONE tool name against a dialect's known catalogs.
+ *
+ * A `Tool(restriction)` suffix (e.g. `Bash(git:*)`) is stripped first — the
+ * restriction narrows what the tool can DO but doesn't change its effect class
+ * (Bash with any restriction is still conservatively side-effecting).
+ *
+ * Classification rules (in priority order):
+ *  1. In `dialect.sideEffectingTools`  → `"side-effecting"`
+ *  2. In `dialect.builtinAgentTools` (and NOT side-effecting) → `"read-only"`
+ *  3. Matches `dialect.mcpToolPattern` → `"unknown"` (MCP tools are not
+ *     classifiable from the name alone — treated as unknown-effect)
+ *  4. Otherwise → `"unknown"` (unrecognized tool; may be a plugin tool or a typo)
+ */
+function classifyToolEffect(tool, dialect) {
+    const base = baseTool(tool);
+    const sideEffecting = dialect.sideEffectingTools ?? [];
+    if (sideEffecting.includes(base))
+        return "side-effecting";
+    if (dialect.builtinAgentTools.includes(base))
+        return "read-only";
+    if (dialect.mcpToolPattern.test(base))
+        return "unknown";
+    return "unknown";
+}
+/**
+ * Compute the static effect surface of a declared `tools:` contract.
+ *
+ * `"*"` / `""` (inherits-all) entries make purity `"unrestricted"` because the
+ * contract grants access to all tools including every side-effecting one — the
+ * full surface is unknowable statically. They are NOT listed in any bucket
+ * (they represent a wildcard, not a named tool).
+ *
+ * De-duplication: a tool name that appears more than once in `tools` is counted
+ * once in its bucket (base tool after restriction stripping).
+ */
+function effectSurface(tools, dialect) {
+    const readOnly = new Set();
+    const sideEffecting = new Set();
+    const unknown = new Set();
+    let hasWildcard = false;
+    let hasBash = false;
+    for (const raw of tools) {
+        const base = baseTool(raw);
+        if (isWildcard(base)) {
+            hasWildcard = true;
+            continue; // wildcards don't go into any named bucket
+        }
+        const effect = classifyToolEffect(raw, dialect);
+        switch (effect) {
+            case "read-only":
+                readOnly.add(base);
+                break;
+            case "side-effecting":
+                sideEffecting.add(base);
+                if (base === "Bash")
+                    hasBash = true;
+                break;
+            case "unknown":
+                unknown.add(base);
+                break;
+            default:
+                (0, hash_js_1.assertNever)(effect);
+        }
+    }
+    const purity = hasWildcard || hasBash || unknown.size > 0
+        ? "unrestricted"
+        : sideEffecting.size > 0
+            ? "bounded"
+            : "pure";
+    return {
+        readOnly: [...readOnly],
+        sideEffecting: [...sideEffecting],
+        unknown: [...unknown],
+        purity,
+    };
+}
+/**
+ * Returns the violations of a DECLARED purity floor — the tools that make the
+ * actual effect surface LOOSER than the declared level. Empty ⇒ the contract
+ * honours the declared level. The `message` on each is actionable (names the
+ * tool, the effect class, and what to do).
+ *
+ * What counts as a violation depends on `declared`:
+ * - `"pure"`:         every side-effecting tool (incl. `Bash`), every
+ *                     unknown-effect tool, and any wildcard (a pure unit may
+ *                     only observe — no `Bash`, no effects, fully static).
+ * - `"bounded"`:      only the truly UNBOUNDED tools — unknown-effect (MCP /
+ *                     unrecognized) and wildcards. Every decidable side-effecting
+ *                     tool is ALLOWED: Write/Edit confine to the boundary, and
+ *                     `Bash` is admitted because the RUNTIME gate
+ *                     (`decidePurityGate`) refines it by command (read-only Bash
+ *                     is an observation; a mutating command is denied).
+ * - `"unrestricted"`: never a violation (the rung carries no constraint).
+ *
+ * A wildcard (`"*"` / `""`) contract is a violation at every constrained level:
+ * "inherits-all" grants every tool, so neither `pure` nor `bounded` can hold.
+ */
+function purityViolations(tools, dialect, declared) {
+    if (declared === "unrestricted")
+        return []; // no constraint to violate
+    const violations = [];
+    const seen = new Set();
+    for (const raw of tools) {
+        const base = baseTool(raw);
+        if (isWildcard(base)) {
+            const key = base === "" ? '""' : '"*"';
+            if (!seen.has(key)) {
+                seen.add(key);
+                violations.push({
+                    tool: base,
+                    effect: "side-effecting",
+                    message: `${key} (inherits-all) is not allowed in a ${declared} contract — it grants access to every tool, including side-effecting ones. Declare explicit tools instead.`,
+                });
+            }
+            continue;
+        }
+        if (seen.has(base))
+            continue;
+        const effect = classifyToolEffect(raw, dialect);
+        switch (effect) {
+            case "read-only":
+                break; // allowed at every level
+            case "unknown":
+                seen.add(base);
+                violations.push({
+                    tool: base,
+                    effect,
+                    message: `"${base}" has unknown effect class (MCP or unrecognized tool); a ${declared} contract cannot declare it — its effects are unbounded from static analysis. Remove it or declare the unit dangerously-unrestricted.`,
+                });
+                break;
+            case "side-effecting":
+                // In a BOUNDED unit every decidable side-effecting tool is allowed:
+                // Write/Edit confine to the boundary, and `Bash` is admitted because the
+                // RUNTIME gate (`decidePurityGate`) refines it by command — a read-only
+                // Bash is an observation, a mutating command is denied. Only `pure` bars
+                // them (a pure unit may only observe; no `Bash`, no effects).
+                if (declared === "bounded")
+                    break;
+                seen.add(base);
+                violations.push({
+                    tool: base,
+                    effect,
+                    message: base === "Bash"
+                        ? `"Bash" is undecidable at the tool-name level; a pure unit cannot declare it. A read-only Bash belongs in a bounded unit (the runtime gate confines it by command) — declare the unit bounded or dangerously-unrestricted.`
+                        : `"${base}" is side-effecting; a pure unit cannot declare it. Remove it or declare the unit bounded.`,
+                });
+                break;
+            default:
+                (0, hash_js_1.assertNever)(effect);
+        }
+    }
+    return violations;
+}
+/**
+ * The violations of a `purity: "pure"` contract — every side-effecting,
+ * unknown-effect, or wildcard tool. A thin alias for `purityViolations(…,
+ * "pure")` kept for the common pure case.
+ */
+function pureContractViolations(tools, dialect) {
+    return purityViolations(tools, dialect, "pure");
+}
+/**
+ * The RUNTIME half of the purity contract: decide whether a single LIVE tool
+ * call is allowed under the active unit's declared purity floor.
+ *
+ * Unlike `purityViolations` (which checks the DECLARED tools contract
+ * statically), this sees the ACTUAL call — including the `Bash` command string —
+ * so it refines `Bash` by effect via `isReadOnlyBash`. That command is the whole
+ * reason the gate's home is the runtime hook: only here is the concrete command
+ * visible (the static surface sees a tool name + a `Bash(git:*)` pattern, never
+ * the command).
+ *
+ * Rules (the ladder, command-refined):
+ * - `unrestricted` → always allow (no constraint).
+ * - read-only tool → allow at every level.
+ * - `Bash` → allow iff the command is provably read-only (an observation);
+ *   otherwise deny — a mutating/undecidable command's effect must move to a
+ *   marked boundary. Same at `pure` and `bounded`.
+ * - other side-effecting tool (Write, Edit, …) → allow under `bounded`
+ *   (a decidable, boundary-confined effect), deny under `pure` (observe-only).
+ * - unknown-effect (MCP / unrecognized) → deny under `pure`/`bounded`
+ *   (unbounded from static analysis).
+ *
+ * Dialect injected (core ⊄ adapter). Reuses `classifyToolEffect` +
+ * `isReadOnlyBash` — one-detector-no-drift with compile + scan.
+ */
+function decidePurityGate(declared, tool, command, dialect) {
+    if (declared === "unrestricted")
+        return { allow: true, message: "" };
+    const base = baseTool(tool);
+    const effect = classifyToolEffect(tool, dialect);
+    if (effect === "read-only")
+        return { allow: true, message: "" };
+    if (base === "Bash") {
+        if (command !== undefined && (0, bash_effects_js_1.isReadOnlyBash)(command)) {
+            return { allow: true, message: "" };
+        }
+        const shown = command ? `"${command}" ` : "";
+        return {
+            allow: false,
+            message: `Bash command ${shown}is not provably read-only; a ${declared} unit may run only read-only Bash ` +
+                `(observation). Move the side effect into a marked boundary, or declare the unit dangerously-unrestricted.`,
+        };
+    }
+    if (effect === "side-effecting") {
+        if (declared === "bounded")
+            return { allow: true, message: "" };
+        return {
+            allow: false,
+            message: `"${base}" is side-effecting; a pure unit may only observe. ` +
+                `Declare the unit bounded (or dangerously-unrestricted) to use it.`,
+        };
+    }
+    // unknown — MCP / unrecognized tool
+    return {
+        allow: false,
+        message: `"${base}" has unknown effect class; a ${declared} unit cannot use it — its effects are unbounded. ` +
+            `Declare the unit dangerously-unrestricted to allow it.`,
+    };
+}
+//# sourceMappingURL=effects.js.map

package/dist/core/layout.d.ts

@@ -29,6 +29,12 @@ export interface PluginLayout {
     readonly instructionFile: string;
     /** Surface dirs materialized into the sandbox, e.g. skills/agents/commands. */
     readonly surfaceDirs: readonly string[];
+    /** Skills dir, holding the nested `<dir>/<name>/SKILL.md`, e.g. `skills`. */
+    readonly skillDir: string;
+    /** Subagents dir, holding flat `<dir>/<name>.md`, e.g. `agents` (`""` = none). */
+    readonly agentDir: string;
+    /** Slash-commands dir, holding flat `<dir>/<name>.md`, e.g. `commands`. */
+    readonly commandDir: 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. */

package/dist/core/mcp-tool.d.ts

@@ -4,7 +4,7 @@
  * names a server `linear`; if the plugin declares its own MCP servers (a
  * `.mcp.json` / manifest `mcpServers` block) and `linear` isn't among them, the
  * tool can't resolve — a dead contract entry. This completes the tool moat:
- * `agent-tool-contract` (tool-contract.ts) verifies BUILT-IN tools but passes
+ * `subagent-tool-contract` (tool-contract.ts) verifies BUILT-IN tools but passes
  * ANY `mcp__*` token unchecked; this verifies the MCP half.
  *
  * Calibrated HIGH-PRECISION — three guards, each learned from a real plugin in

package/dist/core/orphans.js

@@ -35,6 +35,25 @@ const DEFAULT_IGNORE = [
  * that nothing else links to but is not rot.
  */
 const DISABLE_RE = /<!--\s*vigiles-disable\s+orphan-docs\s*-->/;
+/**
+ * Files the HARNESS loads directly — an instruction file (`CLAUDE.md` /
+ * `AGENTS.md`), a skill (`SKILL.md`), a subagent (`agents/*.md`), or a slash
+ * command (`commands/*.md`) — are load-bearing by their NAME/LOCATION, not
+ * because another `.md` links to them. They are categorically NOT docs, so they
+ * are never orphans, even if a project broadens `orphans.include` to scan the
+ * whole repo. (They are still scanned as REFERENCERS, so a real doc that only
+ * a CLAUDE.md links to is still credited — this exemption only removes them from
+ * the orphan-CANDIDATE set.)
+ */
+function isHarnessLoadedFile(path) {
+    const norm = normalizePath(path);
+    const base = norm.slice(norm.lastIndexOf("/") + 1);
+    if (base === "CLAUDE.md" || base === "AGENTS.md" || base === "SKILL.md") {
+        return true;
+    }
+    // Subagent / slash-command surfaces the harness enumerates by directory.
+    return /(^|\/)(agents|commands)\//.test(norm);
+}
 // Match markdown links ](path.md) or ](path.md#anchor)
 const LINK_RE = /\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
 // Match backtick code spans wrapping a path ending in .md
@@ -56,6 +75,8 @@ function collectDocs(basePath, include, ignore) {
     const docs = new Set();
     for (const pattern of include) {
         for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
+            if (isHarnessLoadedFile(p))
+                continue; // instruction files are never orphans
             if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
                 continue;
             docs.add(normalizePath(p));

package/dist/core/spec.d.ts

@@ -120,6 +120,12 @@ export type VerifiedCmd = string & {
 export type VerifiedRef = string & {
     readonly [__brand]: "VerifiedRef";
 };
+export type VerifiedDir = string & {
+    readonly [__brand]: "VerifiedDir";
+};
+export type VerifiedGlob = string & {
+    readonly [__brand]: "VerifiedGlob";
+};
 /** A typed file reference — verified at compile time. */
 export interface FileRef {
     readonly _ref: "file";
@@ -141,7 +147,17 @@ export interface SymbolRef {
     readonly file: VerifiedPath;
     readonly symbol: string;
 }
-export type Ref = FileRef | CmdRef | SkillRef | SymbolRef;
+/** A typed directory reference — verified to exist AND be a directory. */
+export interface DirRef {
+    readonly _ref: "dir";
+    readonly path: VerifiedDir;
+}
+/** A typed glob reference — verified to match at least one path. */
+export interface GlobRef {
+    readonly _ref: "glob";
+    readonly pattern: VerifiedGlob;
+}
+export type Ref = FileRef | CmdRef | SkillRef | SymbolRef | DirRef | GlobRef;
 /**
  * Reference a file path — verified to exist at compile time.
  * When generated types are present, narrowed to known project files.
@@ -164,7 +180,33 @@ export declare function symbol(file: NoInfer<StrictFile>, name: string): SymbolR
  * Compiles to a markdown link: [skill name](path)
  */
 export declare function ref(path: string): SkillRef;
-export type InstructionFragment = string | Ref;
+/**
+ * Reference a directory — verified at compile time to exist AND be a directory
+ * (not a file). The "architecture floats free" fix: a spec that names `src/core/`
+ * proves the directory is really there, where a plain string in prose rots
+ * silently. Compiles to the inline form `` `path` ``.
+ */
+export declare function dir(path: string): DirRef;
+/**
+ * Reference a glob pattern — verified at compile time to match at least one path,
+ * so `glob("src/*.test.ts")` proves tests actually exist where the instructions
+ * claim (the pattern supports the usual `*` / `**` syntax). Compiles to the
+ * inline form `` `pattern` ``.
+ */
+export declare function glob(pattern: string): GlobRef;
+/**
+ * A marked side-effect BOUNDARY inside a skill/agent body — "side effects are
+ * allowed ONLY inside this block." Compiles to `<!-- vigiles:effect -->` …
+ * `<!-- /vigiles:effect -->` markers the runtime PreToolUse gate keys on: outside
+ * the region the unit is treated as read-only (the `"pure"` effective floor),
+ * inside it the declared purity floor applies. The position-aware companion to
+ * the per-call `purity` floor. See `research/effect-boundary-design.md`.
+ */
+export interface EffectRegion {
+    readonly _ref: "effect";
+    readonly body: InstructionFragment[];
+}
+export type InstructionFragment = string | Ref | EffectRegion;
 /**
  * Tagged template literal for skill instructions with typed references.
  *
@@ -175,6 +217,39 @@ export type InstructionFragment = string | Ref;
  *   `
  */
 export declare function instructions(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];
+/**
+ * Tagged template literal marking a side-effect boundary — usable as an
+ * interpolated fragment inside a body / `instructions\`\``:
+ *
+ *   instructions`
+ *     ## Apply
+ *     ${effect`
+ *       Side effects are allowed ONLY here:
+ *       - write ${file("CHANGELOG.md")}
+ *       - ${cmd("npm publish")}
+ *     `}
+ *   `
+ *
+ * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
+ * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
+ * surface — it does not block on it.
+ */
+export declare function effect(strings: TemplateStringsArray, ...values: InstructionFragment[]): EffectRegion;
+/**
+ * The purity an author DECLARES for a skill/agent — the floor `compile`
+ * enforces against the tool contract (see `purityViolations` in
+ * `core/effects.ts`). Mirrors the analysis `PurityLevel` for the two meaningful
+ * rungs, so what you DECLARE and what `scan` REPORTS share one vocabulary:
+ * - `"pure"`:    only read-only tools — no side effects at all.
+ * - `"bounded"`: decidable side-effecting tools (Write, Edit, …) are allowed,
+ *   but not `Bash` / unknown-effect / inherits-all (the unbounded cells).
+ * - `"dangerously-unrestricted"`: the explicit escape hatch — no enforcement.
+ *   Deliberately loud (cf. React's `dangerouslySetInnerHTML`) so opting OUT of
+ *   the guardrail stands out in review. Omitting `purity` is the same
+ *   (unenforced) default WITHOUT typing the loud word — you write it only when
+ *   you mean to override a stricter level.
+ */
+export type AuthoredPurity = "pure" | "bounded" | "dangerously-unrestricted";
 /** Known markdown instruction file targets. */
 export type InstructionTarget = "CLAUDE.md" | "AGENTS.md" | (string & {});
 export interface ClaudeSpec {
@@ -190,7 +265,12 @@ export interface ClaudeSpec {
     readonly keyFiles?: Record<string, string>;
     /** Named prose sections — plain strings or tagged templates with file()/cmd()/ref(). */
     readonly sections?: Record<string, string | InstructionFragment[]>;
-    /** Maximum lines per prose section (per-spec override). */
+    /**
+     * Maximum lines for a single named prose section. Overrides the generous
+     * compile-time default (200 lines) that guards every section + agent section
+     * against an egregious content dump — set a tighter number to enforce your own
+     * house limit, or a larger one for an intentionally long section.
+     */
     readonly maxSectionLines?: number;
     /**
      * Maximum estimated tokens for the compiled output (~4 chars per token).
@@ -293,6 +373,31 @@ export interface SkillSpec {
     readonly inputs?: readonly SkillInput[];
     /** Whether to disable model invocation (frontmatter flag). */
     readonly disableModelInvocation?: boolean;
+    /**
+     * Execution context. `"fork"` runs the skill's body as the task inside a
+     * forked SUBAGENT (its own context window) instead of inline in the main
+     * conversation (Anthropic's `context: fork` frontmatter). This is the ONLY
+     * setting under which a skill gains a real call→return boundary — so it's the
+     * prerequisite for declaring an `output` Result contract (see `output`). Omit
+     * for the default inline execution.
+     */
+    readonly context?: "fork";
+    /**
+     * The allowed-tools contract for this skill. Each entry must be a known
+     * built-in tool or an MCP tool (`mcp__server__tool`). Omit to inherit all
+     * tools. When `purity` is `"pure"`/`"bounded"`, the declared tools are checked
+     * against that floor — compile rejects a tool looser than the declared level.
+     */
+    readonly tools?: readonly string[];
+    /**
+     * Declare this skill's purity floor — compile rejects a tool contract looser
+     * than it. `"pure"` allows only read-only tools; `"bounded"` also allows
+     * decidable side-effecting tools (Write, Edit, …) but bars `Bash` /
+     * unknown-effect / inherits-all; `"dangerously-unrestricted"` (or omitting it)
+     * enforces nothing. NOTE: `"pure"`/`"bounded"` require an explicit read-only
+     * `tools` list — an absent list inherits ALL tools and is a violation.
+     */
+    readonly purity?: AuthoredPurity;
     /**
      * Gated pipeline steps. When set, the skill compiles to a `## Steps`
      * checklist with a deterministic gate per step. Use this OR `body`.
@@ -303,6 +408,18 @@ export interface SkillSpec {
      * Compiles to a `## Result` section + a `vigiles:result` marker.
      */
     readonly result?: Gate;
+    /**
+     * The skill's typed railway outcome — the SAME `Result<ok, err>` contract a
+     * subagent declares with `result(okShape, errShape)`. Valid ONLY with
+     * `context: "fork"`: a forked skill runs as a subagent, so it has the
+     * call→return boundary a typed outcome needs (compile errors if `output` is set
+     * without `context: "fork"`). When valid, compiles to a `## Output contract`
+     * with a `vigiles:ok` / `vigiles:err` block — parseable (`parseAgentResult`) and
+     * testable (`assertAgentOk`) via the existing subagent rail. An INLINE skill has
+     * no return, so a typed outcome there is a category error — hence the gate. See
+     * `research/spec-syntax-and-railway-scope.md`.
+     */
+    readonly output?: OutputContract;
     /** Freeform instruction body (linear/unstructured skills). Use this OR `steps`. */
     readonly body?: string | InstructionFragment[];
     /**
@@ -338,6 +455,8 @@ export interface AgentSpec {
     readonly description: string;
     /** Model alias (e.g. "sonnet", "opus", "haiku", "inherit"). Optional. */
     readonly model?: string;
+    /** Subagent UI colour (Claude Code frontmatter, e.g. "pink", "blue"). Optional. */
+    readonly color?: string;
     /**
      * The allowed-tools contract — the rails the worker runs on. Each entry must be
      * a known built-in tool (Read/Write/Edit/Bash/Grep/Glob/WebSearch/WebFetch/
@@ -345,6 +464,17 @@ export interface AgentSpec {
      * Omit to inherit all tools. Verified at compile time.
      */
     readonly tools?: readonly string[];
+    /**
+     * The DENY-side contract — tools the worker may NOT use. Use this INSTEAD OF
+     * `tools`, not with it: `tools` is an allowlist (only these), so a tool not
+     * listed is already unavailable and a `disallowedTools` entry would be
+     * redundant. `disallowedTools` earns its place only when there's NO allowlist
+     * (the agent inherits ALL tools) and you want to subtract a few — e.g.
+     * `disallowedTools: ["Bash"]` on an otherwise-unrestricted worker. Rendered to
+     * the `disallowedTools:` frontmatter; close-typos are flagged (a typo'd entry
+     * blocks nothing). For a read-only floor prefer a tight `tools` list + `purity`.
+     */
+    readonly disallowedTools?: readonly string[];
     /**
      * The lead/intro prose of the system prompt (the "You are…" opener), before any
      * sections. Carries verified `file()`/`cmd()`/`symbol()`/`ref()` marks. No
@@ -367,6 +497,15 @@ export interface AgentSpec {
      * and testable (see `result()`, `parseAgentResult`, `assertAgentOk`).
      */
     readonly output?: OutputContract;
+    /**
+     * Declare this agent's purity floor — compile rejects a tool contract looser
+     * than it. `"pure"` allows only read-only tools; `"bounded"` also allows
+     * decidable side-effecting tools (Write, Edit, …) but bars `Bash` /
+     * unknown-effect / inherits-all; `"dangerously-unrestricted"` (or omitting it)
+     * enforces nothing. `"pure"`/`"bounded"` require an explicit `tools` list — a
+     * wildcard or absent-tools (inherits-all) is always a violation.
+     */
+    readonly purity?: AuthoredPurity;
 }
 /**
  * Define a subagent specification (compiles to `agents/<name>.md`).

package/dist/core/spec.js

@@ -17,7 +17,10 @@ exports.file = file;
 exports.cmd = cmd;
 exports.symbol = symbol;
 exports.ref = ref;
+exports.dir = dir;
+exports.glob = glob;
 exports.instructions = instructions;
+exports.effect = effect;
 exports.claude = claude;
 exports.project = project;
 exports.input = input;
@@ -105,6 +108,24 @@ function symbol(file, name) {
 function ref(path) {
     return { _ref: "skill", path: path };
 }
+/**
+ * Reference a directory — verified at compile time to exist AND be a directory
+ * (not a file). The "architecture floats free" fix: a spec that names `src/core/`
+ * proves the directory is really there, where a plain string in prose rots
+ * silently. Compiles to the inline form `` `path` ``.
+ */
+function dir(path) {
+    return { _ref: "dir", path: path };
+}
+/**
+ * Reference a glob pattern — verified at compile time to match at least one path,
+ * so `glob("src/*.test.ts")` proves tests actually exist where the instructions
+ * claim (the pattern supports the usual `*` / `**` syntax). Compiles to the
+ * inline form `` `pattern` ``.
+ */
+function glob(pattern) {
+    return { _ref: "glob", pattern: pattern };
+}
 /**
  * Tagged template literal for skill instructions with typed references.
  *
@@ -124,6 +145,33 @@ function instructions(strings, ...values) {
     }
     return result;
 }
+/**
+ * Tagged template literal marking a side-effect boundary — usable as an
+ * interpolated fragment inside a body / `instructions\`\``:
+ *
+ *   instructions`
+ *     ## Apply
+ *     ${effect`
+ *       Side effects are allowed ONLY here:
+ *       - write ${file("CHANGELOG.md")}
+ *       - ${cmd("npm publish")}
+ *     `}
+ *   `
+ *
+ * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
+ * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
+ * surface — it does not block on it.
+ */
+function effect(strings, ...values) {
+    const body = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i])
+            body.push(strings[i]);
+        if (i < values.length)
+            body.push(values[i]);
+    }
+    return { _ref: "effect", body };
+}
 /**
  * Define a CLAUDE.md specification.
  *

package/dist/core/tool-contract.d.ts

@@ -7,7 +7,7 @@
  *
  * ONE pure detector (`one-detector-no-drift`), reused by THREE callers so they
  * can't disagree: `compileAgent` (spec authoring), `scan` (read-only audit of a
- * shipped plugin), and the `agent-tool-contract` lint rule (the severity-gated
+ * shipped plugin), and the `subagent-tool-contract` lint rule (the severity-gated
  * commit gate). The dialect is injected (core ⊄ adapter) — the composition root
  * passes `claudeCodeDialect` / `codexDialect`.
  *

package/dist/core/types.d.ts

@@ -71,7 +71,7 @@ export interface OrphansConfig {
 }
 /**
  * Shared options for the per-kind untested-* rules (`untested-skill` /
- * `untested-agent` / `untested-hook`). Which kinds are scanned is controlled by
+ * `untested-subagent` / `untested-hook`). Which kinds are scanned is controlled by
  * each rule's severity (set a rule to `false` to skip that kind), so only the
  * test-discovery knobs live here.
  */
@@ -97,7 +97,7 @@ export interface RulesConfig {
     /** Flag a skill (SKILL.md) that ships with no test or eval. Default: "warn". */
     "untested-skill"?: RuleWithOptions<TestCoverageConfig>;
     /** Flag a subagent (agents/*.md) that ships with no test or eval. Default: "warn". */
-    "untested-agent"?: RuleWithOptions<TestCoverageConfig>;
+    "untested-subagent"?: RuleWithOptions<TestCoverageConfig>;
     /** Flag a hook script that ships with no test or eval. Default: "warn". */
     "untested-hook"?: RuleWithOptions<TestCoverageConfig>;
     /**
@@ -115,7 +115,7 @@ export interface RulesConfig {
      * plugin/MCP-provided, never flagged). Off unless set; "warn" surfaces,
      * "error" gates CI. Same detector as `scan` + `compileAgent`.
      */
-    "agent-tool-contract"?: RuleSeverity;
+    "subagent-tool-contract"?: RuleSeverity;
     /**
      * Flag a hook registered under an event name the harness doesn't define (a
      * typo → the hook never fires). High-precision: close typos only, never a
@@ -128,7 +128,7 @@ export interface RulesConfig {
      * `name` (to load), an agent needs `name` + `description`. A broken surface
      * that won't register. Default "warn"; "error" gates CI. Same detector as `scan`.
      */
-    "agent-frontmatter"?: RuleSeverity;
+    "subagent-frontmatter"?: RuleSeverity;
     /**
      * Flag a declared MCP server that can't start — neither a `command` (stdio)
      * nor a `url` (http/sse). Default "warn"; "error" gates CI. Same detector as
@@ -146,7 +146,7 @@ export interface RulesConfig {
     /**
      * Cross-reference an `mcp__server__tool` in a subagent's contract against the
      * plugin's declared `mcpServers` — flag a server the plugin doesn't declare
-     * (the MCP half of the tool moat; `agent-tool-contract` checks the built-in
+     * (the MCP half of the tool moat; `subagent-tool-contract` checks the built-in
      * half). High-precision: only flags when the plugin SHIPS a declared set,
      * allowlists harness built-ins (`ide`), and skips the plugin-namespaced
      * `mcp__plugin_…` form. Default "warn"; "error" gates CI. Same detector as
@@ -163,7 +163,7 @@ export interface RulesConfig {
     "hook-script-exists"?: RuleSeverity;
     /**
      * Cross-reference a subagent's `disallowedTools:` block-list against the
-     * catalog — the deny-side mirror of `agent-tool-contract`. A close typo there
+     * catalog — the deny-side mirror of `subagent-tool-contract`. A close typo there
      * blocks NOTHING (you meant to deny `Bash`, wrote `Bsh`), leaving the tool
      * available. High-precision: close-typo only (a never-available tool is
      * harmless to list, a bare unknown is likely a plugin tool). Default "warn";