vigiles 5.1.0 → 5.2.0

package/dist/core/compile.js

@@ -14,6 +14,8 @@ exports.validateFileRef = validateFileRef;
 exports.readPackageScripts = readPackageScripts;
 exports.validateCommandRef = validateCommandRef;
 exports.validateSymbolRef = validateSymbolRef;
+exports.validateDirRef = validateDirRef;
+exports.validateGlobRef = validateGlobRef;
 exports.compileClaude = compileClaude;
 exports.compileSkill = compileSkill;
 exports.compileAgent = compileAgent;
@@ -22,11 +24,13 @@ exports.compileRailway = compileRailway;
 exports.checkFileHash = checkFileHash;
 exports.adoptDiff = adoptDiff;
 const node_fs_1 = require("node:fs");
+const glob_1 = require("glob");
 const node_path_1 = require("node:path");
 const hash_js_1 = require("./hash.js");
 const symbols_js_1 = require("./symbols.js");
 const linters_js_1 = require("./linters.js");
 const tool_contract_js_1 = require("./tool-contract.js");
+const effects_js_1 = require("./effects.js");
 // vigiles's default compile target when a spec names none and no dialect is
 // injected — a product convention (vigiles emits CLAUDE.md by default), not a
 // harness dialect. When a dialect IS injected its instructionTargets win.
@@ -147,45 +151,73 @@ function validateSymbolRef(file, name, basePath) {
     }
     return null;
 }
+function validateDirRef(dirPath, basePath) {
+    const resolved = (0, node_path_1.resolve)(basePath, dirPath);
+    if (!(0, node_fs_1.existsSync)(resolved)) {
+        return {
+            type: "stale-file",
+            message: `Directory not found: "${dirPath}"`,
+            path: dirPath,
+        };
+    }
+    if (!(0, node_fs_1.statSync)(resolved).isDirectory()) {
+        return {
+            type: "stale-ref",
+            message: `Not a directory: "${dirPath}"`,
+            path: dirPath,
+        };
+    }
+    return null;
+}
+function validateGlobRef(pattern, basePath) {
+    // ≥1 match = the pattern resolves to something real. `dot` so a dotfile path
+    // (e.g. `.claude/**`) isn't silently a no-match.
+    const matches = (0, glob_1.globSync)(pattern, { cwd: basePath, dot: true });
+    if (matches.length === 0) {
+        return {
+            type: "stale-ref",
+            message: `Glob matched no files: "${pattern}"`,
+            path: pattern,
+        };
+    }
+    return null;
+}
 function validateRefs(fragments, basePath) {
     const errors = [];
     for (const fragment of fragments) {
-        if (typeof fragment === "string")
-            continue;
-        const r = fragment;
-        switch (r._ref) {
-            case "file": {
-                const err = validateFileRef(r.path, basePath);
-                if (err)
-                    errors.push(err);
-                break;
-            }
-            case "cmd": {
-                const err = validateCommandRef(r.command, basePath);
-                if (err)
-                    errors.push(err);
-                break;
-            }
-            case "skill": {
-                const err = validateFileRef(r.path, basePath);
-                if (err) {
-                    errors.push({
+        if (typeof fragment !== "string") {
+            errors.push(...validateOneRef(fragment, basePath));
+        }
+    }
+    return errors;
+}
+const wrap = (e) => (e ? [e] : []);
+/** Validate a single non-string fragment (a `Ref` or `EffectRegion`). */
+function validateOneRef(r, basePath) {
+    switch (r._ref) {
+        case "file":
+            return wrap(validateFileRef(r.path, basePath));
+        case "cmd":
+            return wrap(validateCommandRef(r.command, basePath));
+        case "skill":
+            return validateFileRef(r.path, basePath)
+                ? [
+                    {
                         type: "stale-ref",
                         message: `Skill not found: "${r.path}"`,
                         path: r.path,
-                    });
-                }
-                break;
-            }
-            case "symbol": {
-                const err = validateSymbolRef(r.file, r.symbol, basePath);
-                if (err)
-                    errors.push(err);
-                break;
-            }
-        }
+                    },
+                ]
+                : [];
+        case "symbol":
+            return wrap(validateSymbolRef(r.file, r.symbol, basePath));
+        case "dir":
+            return wrap(validateDirRef(r.path, basePath));
+        case "glob":
+            return wrap(validateGlobRef(r.pattern, basePath));
+        case "effect":
+            return validateRefs(r.body, basePath);
     }
-    return errors;
 }
 function renderFragment(fragment) {
     if (typeof fragment === "string")
@@ -199,6 +231,14 @@ function renderFragment(fragment) {
             return `[${(0, node_path_1.basename)((0, node_path_1.dirname)(fragment.path))}](${fragment.path})`;
         case "symbol":
             return `\`vigiles:symbol ${fragment.file}#${fragment.symbol}\``;
+        case "dir":
+            return `\`${fragment.path}\``;
+        case "glob":
+            return `\`${fragment.pattern}\``;
+        case "effect": {
+            const inner = fragment.body.map(renderFragment).join("").trim();
+            return `\n<!-- vigiles:effect -->\n\n${inner}\n\n<!-- /vigiles:effect -->\n`;
+        }
         default:
             return (0, hash_js_1.assertNever)(fragment);
     }
@@ -235,6 +275,14 @@ function compileRule(id, rule) {
             return (0, hash_js_1.assertNever)(rule);
     }
 }
+// A generous default cap on a single named prose section. TypeScript types
+// cannot bound a string's length (template-literal-type recursion caps out ~463
+// chars; TS #52243 unresolved), so a helper's content is guarded at COMPILE time
+// instead — the ESLint-max-len / Prettier-printWidth precedent. Deliberately
+// generous (don't-cry-wolf): real prose sections are short, so this only trips on
+// an egregious dump (a whole essay pasted into one section / instructions``).
+// Override per spec with `maxSectionLines`; `maxTokens` is the global backstop.
+const DEFAULT_MAX_SECTION_LINES = 200;
 function validateSectionContent(name, text, maxSectionLines) {
     const errors = [];
     const contentLines = text.split("\n");
@@ -257,10 +305,11 @@ function validateSectionContent(name, text, maxSectionLines) {
             break;
         }
     }
-    if (maxSectionLines && contentLines.length > maxSectionLines) {
+    const max = maxSectionLines ?? DEFAULT_MAX_SECTION_LINES;
+    if (contentLines.length > max) {
         errors.push({
             type: "section-too-long",
-            message: `Section "${name}" is ${String(contentLines.length)} lines (max ${String(maxSectionLines)}). Split into smaller named sections.`,
+            message: `Section "${name}" is ${String(contentLines.length)} lines (max ${String(max)}). Split into smaller named sections, move detail into a file() reference, or raise maxSectionLines if it's intentional.`,
         });
     }
     return errors;
@@ -561,8 +610,8 @@ function collectSkillRefs(spec) {
  * Build the SKILL.md YAML frontmatter block under the harness's frontmatter
  * profile. The `"minimal"` profile (Codex/OpenCode) emits ONLY name +
  * description; `"claude-code"` adds the CC-only keys (disable-model-invocation,
- * argument-hint). Default is `"claude-code"` so callers that pass no dialect get
- * byte-identical output to before.
+ * argument-hint, tools). Default is `"claude-code"` so callers that pass no
+ * dialect get byte-identical output to before.
  */
 function renderSkillFrontmatter(spec, profile = "claude-code") {
     const fm = [
@@ -577,11 +626,16 @@ function renderSkillFrontmatter(spec, profile = "claude-code") {
         if (spec.disableModelInvocation !== undefined) {
             fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
         }
+        if (spec.context !== undefined)
+            fm.push(`context: ${spec.context}`);
         const argHint = spec.inputs && spec.inputs.length > 0
             ? renderArgumentHint(spec.inputs)
             : spec.argumentHint;
         if (argHint)
             fm.push(`argument-hint: ${argHint}`);
+        if (spec.tools && spec.tools.length > 0) {
+            fm.push(`tools: ${spec.tools.join(", ")}`);
+        }
     }
     fm.push("", "---");
     return fm.join("\n");
@@ -603,6 +657,10 @@ function renderSkillSections(spec) {
     }
     if (spec.result)
         sections.push(renderResult(spec.result));
+    // A forked skill (context: fork) runs as a subagent, so it may carry the SAME
+    // typed Result outcome — reuse the subagent renderer (one-renderer-no-drift).
+    if (spec.output)
+        sections.push(renderOutputContract(spec.output));
     return sections.join("\n\n");
 }
 const DEFAULT_MAX_INLINE_CODE_LINES = 20;
@@ -661,9 +719,36 @@ function compileSkill(spec, options = {}) {
         }
     }
     errors.push(...validateRefs(collectSkillRefs(spec), basePath));
+    // A typed `output` Result contract is valid ONLY for a forked skill: an inline
+    // skill has no call→return boundary, so a typed outcome there is a category
+    // error (see research/spec-syntax-and-railway-scope.md). Enforce it at compile.
+    if (spec.output && spec.context !== "fork") {
+        errors.push({
+            type: "output-without-fork",
+            message: 'A skill `output` (result() contract) requires `context: "fork"` — an ' +
+                "inline skill has no return value to type. Add context:'fork' to run it " +
+                "as a subagent, or drop `output`.",
+        });
+    }
+    // purity floor check — the dialect is optional (callers that don't pass one
+    // skip the check rather than crash; the CLI always passes it). An absent
+    // tools list inherits ALL tools, so it's checked as the "*" wildcard (a
+    // violation at the pure/bounded floors), never as the empty set.
+    if (spec.purity &&
+        spec.purity !== "dangerously-unrestricted" &&
+        options.dialect) {
+        for (const v of (0, effects_js_1.purityViolations)(spec.tools ?? ["*"], options.dialect, spec.purity)) {
+            errors.push({ type: "purity-violation", message: v.message });
+        }
+    }
     const sections = renderSkillSections(spec);
     errors.push(...checkInlineCode(sections, spec.maxInlineCodeLines ?? DEFAULT_MAX_INLINE_CODE_LINES));
-    const content = renderSkillFrontmatter(spec, profile) + "\n\n" + sections.trim() + "\n";
+    const marker = purityMarker(spec.purity);
+    const content = renderSkillFrontmatter(spec, profile) +
+        "\n\n" +
+        (marker ? marker + "\n\n" : "") +
+        sections.trim() +
+        "\n";
     return { markdown: addHash(content, specFile), errors };
 }
 // ---------------------------------------------------------------------------
@@ -683,7 +768,7 @@ function compileSkill(spec, options = {}) {
 // is CC-only here. See research/codex-prototype-findings.md (gaps).
 /** Verify a subagent's allowed-tools contract — the rails are real tools. The
  * detection lives in the shared `verifyToolContract` detector (one-detector-no-
- * drift: compile + scan + the agent-tool-contract lint rule call the same code). */
+ * drift: compile + scan + the subagent-tool-contract lint rule call the same code). */
 function validateAgentTools(tools, dialect) {
     return (0, tool_contract_js_1.verifyToolContract)(tools, dialect).map((issue) => ({
         type: "unknown-tool",
@@ -700,12 +785,30 @@ function renderAgentFrontmatter(spec) {
     ];
     if (spec.model !== undefined)
         fm.push(`model: ${spec.model}`);
+    if (spec.color !== undefined)
+        fm.push(`color: ${spec.color}`);
     if (spec.tools && spec.tools.length > 0) {
         fm.push(`tools: ${spec.tools.join(", ")}`);
     }
+    if (spec.disallowedTools && spec.disallowedTools.length > 0) {
+        fm.push(`disallowedTools: ${spec.disallowedTools.join(", ")}`);
+    }
     fm.push("", "---");
     return fm.join("\n");
 }
+/**
+ * The `<!-- vigiles:purity:LEVEL -->` marker the runtime PreToolUse gate reads to
+ * enforce a unit's declared purity floor against live tool calls (see
+ * `decidePurityGate` / `parseAgentPurity`). Returns "" when no purity is
+ * declared. The loud authoring word `dangerously-unrestricted` maps to the
+ * neutral report/runtime level `unrestricted` (no constraint to enforce).
+ */
+function purityMarker(purity) {
+    if (!purity)
+        return "";
+    const level = purity === "dangerously-unrestricted" ? "unrestricted" : purity;
+    return `<!-- vigiles:purity:${level} -->`;
+}
 /** Render the subagent's named `##` system-prompt sections (verified like CLAUDE.md). */
 function renderAgentSections(sections, basePath) {
     const lines = [];
@@ -795,6 +898,21 @@ function compileAgent(spec, options) {
     }
     if (spec.tools)
         errors.push(...validateAgentTools(spec.tools, dialect));
+    if (spec.disallowedTools) {
+        // A disallowedTools entry that's a close typo of a real tool blocks NOTHING —
+        // the same high-precision detector scan + the disallowed-tools-contract rule use.
+        for (const issue of (0, tool_contract_js_1.disallowedToolIssues)(spec.disallowedTools, dialect)) {
+            errors.push({ type: "unknown-tool", message: issue.message });
+        }
+    }
+    if (spec.purity && spec.purity !== "dangerously-unrestricted") {
+        // Enforce the declared purity floor against the tool contract. An absent
+        // tools list inherits ALL tools, so it's checked as the "*" wildcard (a
+        // violation at the pure/bounded floors), never as the empty set.
+        for (const v of (0, effects_js_1.purityViolations)(spec.tools ?? ["*"], dialect, spec.purity)) {
+            errors.push({ type: "purity-violation", message: v.message });
+        }
+    }
     if (Array.isArray(spec.body)) {
         errors.push(...validateRefs(spec.body, basePath));
     }
@@ -813,7 +931,12 @@ function compileAgent(spec, options) {
         sections.push(renderOutputContract(spec.output));
     const body = sections.join("\n\n");
     errors.push(...checkInlineCode(body, DEFAULT_MAX_INLINE_CODE_LINES));
-    const content = renderAgentFrontmatter(spec) + "\n\n" + body.trim() + "\n";
+    const marker = purityMarker(spec.purity);
+    const content = renderAgentFrontmatter(spec) +
+        "\n\n" +
+        (marker ? marker + "\n\n" : "") +
+        body.trim() +
+        "\n";
     return { markdown: addHash(content, specFile), errors };
 }
 /** Verify a railway: non-empty, bounded recovery, every delegate target real. */

package/dist/core/dialect.d.ts

@@ -55,5 +55,15 @@ export interface HarnessDialect {
      *   and OpenCode read; CC-only keys are omitted because they'd be inert noise).
      */
     readonly skillFrontmatter: SkillFrontmatterProfile;
+    /**
+     * Tools that PRODUCE side effects (write, exec, network, spawn) — the
+     * complement of read-only within `builtinAgentTools`. The basis for
+     * effect-surface analysis and the `pure:` contract: a tool here is denied to a
+     * pure skill and counts toward a harness's side-effect surface. `Bash` is
+     * listed (undecidable at the tool-name level → conservatively side-effecting);
+     * an MCP tool not classifiable from the name is treated as unknown-effect.
+     * Optional (additive, non-breaking) — absent ⇒ no tool is known-side-effecting.
+     */
+    readonly sideEffectingTools?: readonly string[];
 }
 //# sourceMappingURL=dialect.d.ts.map

package/dist/core/effects.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Static effect-surface analysis — the `pure:` contract and the purity ladder.
+ *
+ * An agent's side effects ARE its tool calls. The read-only vs side-effecting
+ * split is a PUBLISHED catalog (`dialect.sideEffectingTools`), so this analysis
+ * is fully deterministic — no model needed. The result answers "how constrained
+ * is this skill/agent's declared tool contract?" at three rungs:
+ *
+ *   **pure**       — no side-effecting tools; the skill can only observe, not
+ *                    mutate. Deterministically testable with no mocks.
+ *   **bounded**    — has decidable side-effecting tools (Edit, Write, …) but
+ *                    none that are undecidable (`Bash`) or unknown-effect (MCP).
+ *                    The side-effect surface is finite and enumerable.
+ *   **unrestricted** — has `Bash` (undecidable) or an unknown-effect tool (MCP
+ *                    or unclassified), or declares `"*"` / inherits-all. The
+ *                    actual effect surface is unbounded from static analysis
+ *                    alone; "unrestricted" is the honest report.
+ *
+ * SURFACE vs FLOOR — two related but distinct questions, intentionally. The
+ * `effectSurface` above is the STATIC surface: it can't see a `Bash` command, so
+ * any `Bash` makes the surface `unrestricted` (honest — statically unbounded).
+ * The purity FLOOR (`purityViolations` / `decidePurityGate`) is what's
+ * ENFORCED, and `bounded` admits `Bash` because the runtime gate refines it by
+ * command (`isReadOnlyBash`). So a `bounded`-declared unit with `Bash` reports an
+ * `unrestricted` surface yet enforces a `bounded` floor — the runtime gate is
+ * exactly what closes that gap.
+ *
+ * ONE pure detector (`one-detector-no-drift`), dialect injected (core ⊄
+ * adapter). The composition root passes `claudeCodeDialect` / `codexDialect`.
+ *
+ * See `research/side-effect-separation.md` for the full design rationale.
+ */
+import type { HarnessDialect } from "./dialect.js";
+/** The effect class of a single tool from a declared `tools:` contract. */
+export type ToolEffect = "read-only" | "side-effecting" | "unknown";
+/**
+ * The three rungs of the purity ladder. See module-level JSDoc for semantics.
+ *
+ * - `"pure"`:         no side-effecting tools, no unknown-effect tools, no wildcard.
+ * - `"bounded"`:      has side-effecting tools, none of which are `Bash` or unknown.
+ * - `"unrestricted"`: has `Bash`, any unknown-effect tool, or a wildcard (`"*"` /
+ *                     inherits-all) that can reach effects.
+ */
+export type PurityLevel = "pure" | "bounded" | "unrestricted";
+/**
+ * The aggregated effect surface of a declared `tools:` contract.
+ *
+ * Fields are de-duplicated: a tool listed twice appears at most once per bucket.
+ */
+export interface EffectSurface {
+    /** Built-in read-only tools in the contract (Read, Grep, Glob, …). */
+    readonly readOnly: readonly string[];
+    /** Built-in tools that produce side effects (Bash, Write, Edit, …). */
+    readonly sideEffecting: readonly string[];
+    /**
+     * Tools whose effect class cannot be determined statically: MCP tools
+     * (`mcp__server__tool`) and any tool name the dialect does not recognize.
+     * These make purity `"unrestricted"` because the surface is unknown.
+     */
+    readonly unknown: readonly string[];
+    /**
+     * The overall purity of the contract:
+     * - `"pure"`:         `sideEffecting` and `unknown` are both empty, no wildcard.
+     * - `"bounded"`:      `sideEffecting` is non-empty, `unknown` is empty, no `Bash`.
+     * - `"unrestricted"`: `Bash` present, OR `unknown` is non-empty, OR the contract
+     *                     is `"*"` / inherits-all (can reach any tool, including effects).
+     *
+     * A wildcard (`"*"` or `""`) contract is always `"unrestricted"` — it grants
+     * access to all tools including every side-effecting one.
+     */
+    readonly purity: PurityLevel;
+}
+/**
+ * A violation record for `pureContractViolations` — a single tool in a
+ * declared `pure:` contract that is side-effecting or unknown-effect.
+ */
+export interface PureViolation {
+    /** The base tool name (restriction suffix already stripped). */
+    readonly tool: string;
+    /** Why this tool violates a pure contract. */
+    readonly effect: ToolEffect;
+    /** A ready-to-show, actionable message. */
+    readonly message: string;
+}
+/**
+ * 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)
+ */
+export declare function classifyToolEffect(tool: string, dialect: HarnessDialect): ToolEffect;
+/**
+ * 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).
+ */
+export declare function effectSurface(tools: readonly string[], dialect: HarnessDialect): EffectSurface;
+/**
+ * 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.
+ */
+export declare function purityViolations(tools: readonly string[], dialect: HarnessDialect, declared: PurityLevel): PureViolation[];
+/**
+ * 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.
+ */
+export declare function pureContractViolations(tools: readonly string[], dialect: HarnessDialect): PureViolation[];
+/** A runtime allow/deny decision for the PreToolUse purity gate. */
+export interface PurityGateDecision {
+    readonly allow: boolean;
+    /** Reason fed back to the model on a deny; empty on allow. */
+    readonly message: string;
+}
+/**
+ * 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.
+ */
+export declare function decidePurityGate(declared: PurityLevel, tool: string, command: string | undefined, dialect: HarnessDialect): PurityGateDecision;
+//# sourceMappingURL=effects.d.ts.map