vigiles 15.3.0 → 15.4.1

package/dist/audit-score.js

@@ -28,7 +28,7 @@ exports.formatAuditScore = formatAuditScore;
  * design). NB the EXECUTING
  * "do your hooks actually block?" disaster-battery is STILL not an `audit` ring:
  * running arbitrary hooks safely needs cross-platform confinement that isn't
- * shipped yet, so the battery lives in the `vigiles/testing` API via
+ * shipped yet, so the battery lives in the `vigiles` testing API via
  * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.
  *
  * TESTED vs EVALUATED are two rings, not one, because a harness and an eval differ
@@ -49,7 +49,7 @@ const score_core_js_1 = require("./score-core.js");
 const W_UNTESTED = 3;
 /** The command that answers the firing question — named, not alluded to. */
 const MEASURE_FIRING_COMMAND = "run `npx vigiles audit` interactively to measure, or add a `*.eval.mjs` " +
-    "(`measureTriggerRate`, vigiles/testing)";
+    "(`paid_measureTriggerRate`, vigiles/eval)";
 /** Resolve the terse "thing(s)" plural placeholder against a count:
  * n===1 drops the "(s)" ("1 tool"); otherwise it becomes "s" ("3 tools"). */
 function pluralizeLabel(n, label) {

package/dist/check-count.js

@@ -46,7 +46,7 @@ exports.armCheckReport = armCheckReport;
  * tool avoids.
  *
  * WHAT A MISSING COUNT MEANS: nothing at all. A script that never imports
- * `vigiles/testing` cannot report, so the runner sees no file and treats it
+ * `vigiles` cannot report, so the runner sees no file and treats it
  * exactly as before — a plain pass. Silence is the legacy branch, never a
  * verdict; only a count of literally zero is a finding. (The alternative —
  * force-loading this module into every child with `node --import` so silence

package/dist/claude-code.d.ts

@@ -2,14 +2,14 @@
  * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
  * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
  * layouts) and the scriptable Anthropic Messages mock. Split from
- * `vigiles/testing` on purpose — the test API above is the stable surface; this
+ * the `vigiles` root on purpose — the test API above is the stable surface; this
  * is the adapter, so a future `vigiles/<other-harness>` can sit beside it.
  */
 export * from "./adapters/claude-code/plugin-loader.js";
 export * from "./mock-model.js";
 export { claudeCodeDriver, buildClaudeArgs, parseClaudeRun, claudeAvailable, } from "./harness-test.js";
 export * from "./adapters/claude-code/dialect.js";
-export { agent, skill, type ClaudeCodeToolVocabulary, } from "./adapters/claude-code/typed-spec.js";
+export { agent, experimental_skill, type ClaudeCodeToolVocabulary, } from "./adapters/claude-code/typed-spec.js";
 export { measureSelectionMatrix, assertNoCollision, formatSelectionReport, } from "./scan-behavioral.js";
 export type { SelectionReport, SkillSelectionStat, SelectionOptions, SelectionMatrixOptions, } from "./scan-behavioral.js";
 export * from "./adapters/claude-code/layout.js";

package/dist/claude-code.js

@@ -14,12 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatSelectionReport = exports.assertNoCollision = exports.measureSelectionMatrix = exports.skill = exports.agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
+exports.formatSelectionReport = exports.assertNoCollision = exports.measureSelectionMatrix = exports.experimental_skill = exports.agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
 /**
  * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
  * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
  * layouts) and the scriptable Anthropic Messages mock. Split from
- * `vigiles/testing` on purpose — the test API above is the stable surface; this
+ * the `vigiles` root on purpose — the test API above is the stable surface; this
  * is the adapter, so a future `vigiles/<other-harness>` can sit beside it.
  */
 __exportStar(require("./adapters/claude-code/plugin-loader.js"), exports);
@@ -28,23 +28,29 @@ __exportStar(require("./mock-model.js"), exports);
 // helpers + the `claude` capability probe. Agnostic users never need these
 // (`runHarnessTest` defaults to the CC driver), but they're exposed here — beside
 // the Codex driver in `vigiles/codex` — for CC-specific tests/tooling. They are
-// deliberately NOT on the agnostic `vigiles/testing` surface.
+// deliberately NOT on the agnostic `vigiles` surface.
 var harness_test_js_1 = require("./harness-test.js");
 Object.defineProperty(exports, "claudeCodeDriver", { enumerable: true, get: function () { return harness_test_js_1.claudeCodeDriver; } });
 Object.defineProperty(exports, "buildClaudeArgs", { enumerable: true, get: function () { return harness_test_js_1.buildClaudeArgs; } });
 Object.defineProperty(exports, "parseClaudeRun", { enumerable: true, get: function () { return harness_test_js_1.parseClaudeRun; } });
 Object.defineProperty(exports, "claudeAvailable", { enumerable: true, get: function () { return harness_test_js_1.claudeAvailable; } });
 __exportStar(require("./adapters/claude-code/dialect.js"), exports);
-// The typed Claude Code authoring surface: `agent` / `skill` with the `purity`
-// floor enforced AT COMPILE TIME against the CC tool catalog (a `tsc` error for
-// e.g. `purity: "pure"` + `"Bash"`). A strict addition to the runtime/compile
-// purity checks; the bare core `agent()`/`skill()` (`vigiles/spec`) stay open.
+// The typed Claude Code authoring surface: `agent` / `experimental_skill` with
+// the `purity` floor enforced AT COMPILE TIME against the CC tool catalog (a
+// `tsc` error for e.g. `purity: "pure"` + `"Bash"`). A strict addition to the
+// runtime/compile purity checks; the bare core `agent()`/`experimental_skill()`
+// (`vigiles/spec`) stay open.
+//
+// NOTE the collision this rename also resolves: `vigiles/testing` exports a
+// `skill()` too, and it is a DIFFERENT function — a `Check<Trace>` asking "did
+// this skill fire?", taking an id string. One word, two concepts, told apart
+// only by which door you imported from. Only the authoring builder is prefixed.
 var typed_spec_js_1 = require("./adapters/claude-code/typed-spec.js");
 Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return typed_spec_js_1.agent; } });
-Object.defineProperty(exports, "skill", { enumerable: true, get: function () { return typed_spec_js_1.skill; } });
+Object.defineProperty(exports, "experimental_skill", { enumerable: true, get: function () { return typed_spec_js_1.experimental_skill; } });
 // Selection-collision — a Claude-Code-ONLY behavioral measurement (Codex has no
 // skill-selection event to read), so it lives on this surface, not the agnostic
-// `vigiles/testing`. `measureSelectionMatrix` builds the N×N "which skill fired?"
+// `vigiles`. `measureSelectionMatrix` builds the N×N "which skill fired?"
 // matrix (diagonal = recall, off-diagonal = collision); `assertNoCollision` gates it.
 var scan_behavioral_js_1 = require("./scan-behavioral.js");
 Object.defineProperty(exports, "measureSelectionMatrix", { enumerable: true, get: function () { return scan_behavioral_js_1.measureSelectionMatrix; } });

package/dist/cli.js

@@ -1702,7 +1702,7 @@ function formatTriggerNudge(triggerableSkills) {
         return "";
     const n = triggerableSkills;
     return (`ℹ Do your ${String(n)} skill${n === 1 ? "" : "s"} actually fire? The deterministic read can't tell — ` +
-        `run \`audit\` interactively to measure, or test with \`measureTriggerRate\` (vigiles/testing).`);
+        `run \`audit\` interactively to measure, or test with \`paid_measureTriggerRate\` (vigiles/eval).`);
 }
 /** A terminal summary of the rule map: the CONFIDENT lane counts + the POSSIBLE
  * (review) and SKIPPED tiers, with the honest caveat that detection is a
@@ -1973,7 +1973,7 @@ function vigilesWorkflow(plan, harnesses, hasPackageJson) {
 `
         : "";
     // The test pillar's harness job runs `*.harness.mjs` files that
-    // `import "vigiles/testing"`, so it needs vigiles RESOLVABLE — a package.json +
+    // `import "vigiles"`, so it needs vigiles RESOLVABLE — a package.json +
     // install. A repo with no package.json can't run the JS test tier in CI at all
     // (the import won't resolve even though the CLI itself came from npx), so the
     // harness job is emitted ONLY when a package.json exists (Codex review / #111 /
@@ -2136,7 +2136,7 @@ const STARTER_HARNESS = `/**
  *
  * Guide: https://github.com/zernie/vigiles/blob/main/docs/harness-testing.md
  */
-import { runHook } from "vigiles/testing";
+import { runHook } from "vigiles";
 import assert from "node:assert/strict";
 
 // EXAMPLE — replace with one of YOUR hooks. This PreToolUse Bash guard blocks a
@@ -4384,7 +4384,7 @@ const COMMAND_HELP = {
         usage: "  vigiles audit [dir...]          Lighthouse for your harness — a LOCAL report: rings + what's broken + fixes (a deterministic read; 2+ dirs → leaderboard)",
         detail: [
             "                                 writes vigiles-report.html + .json (auto-gitignored; --out=<dir> · --no-html/--no-json · --no-open · --json for machine output). NOT a CI step — use `vigiles lint` in CI.",
-            "                                 the executing checks (run your hooks · live MCP · do skills fire?) run only interactively — `audit` asks once (remembered); automation uses the vigiles/testing API",
+            "                                 the executing checks (run your hooks · live MCP · do skills fire?) run only interactively — `audit` asks once (remembered); automation uses the vigiles testing API",
             "                                 --serve opens a LIVE local report whose buttons create specs in one click (own repo only; loopback + token-guarded) · --no-serve to skip the prompt",
         ],
     },
@@ -4970,7 +4970,7 @@ function refsHookCommand() {
 // ---------------------------------------------------------------------------
 /**
  * Load a compiled-hook program's default export — the SHARED loader, also the
- * public `vigiles/testing` `loadHook` a `.harness.mjs` test uses, so a hook that
+ * public `vigiles` `loadHook` a `.harness.mjs` test uses, so a hook that
  * loads in a test loads identically here (one loader, no drift).
  */
 const loadHookProgram = load_hook_js_1.loadHook;
@@ -6135,7 +6135,7 @@ async function main() {
             // uses `vigiles lint`). The executing checks (safety battery + live MCP +
             // skill firing) run only on consent: at a TTY `audit` asks once (remembered
             // in `.vigilesrc.json`), headless it stays a read + a one-line nudge. There
-            // is NO execution flag — automation tests the harness via the vigiles/testing
+            // is NO execution flag — automation tests the harness via the vigiles testing
             // API + skills, not the report verb. See the `audit-side-effect-free` rule.
             const dirs = restArgs.length > 0 ? restArgs : ["."];
             const json = args.includes("--json");
@@ -6337,10 +6337,10 @@ async function main() {
                 // linter also executes it). A plain `audit` is a deterministic READ;
                 // these run only on consent — ASK once at a TTY (remembered); headless
                 // stays a read + a nudge (no execution flag — automation uses the
-                // vigiles/testing API). Resolved AFTER the report (so the read leads) but
+                // vigiles testing API). Resolved AFTER the report (so the read leads) but
                 // BEFORE the rule map is routed, so a first-time "yes" enriches THIS run.
                 // (The safety battery is NOT here — it needs cross-platform confinement
-                // that isn't shipped, so it lives in the vigiles/testing API.)
+                // that isn't shipped, so it lives in the vigiles testing API.)
                 // `surfaces` + `execDecision` were resolved above (the ring needed them);
                 // this only turns an `ask` into a prompt and remembers the answer.
                 const { execute, note: execNote } = await resolveExecution(surfaces, execDecision, json, adapter.name);

package/dist/codex.d.ts

@@ -1,6 +1,6 @@
 /**
  * `vigiles/codex` — the OpenAI Codex harness adapter. Sits beside
- * `vigiles/claude-code`: same harness-agnostic `vigiles/testing` core, a
+ * `vigiles/claude-code`: same harness-agnostic `vigiles` testing core, a
  * different transport (the `codex` binary + the OpenAI **Responses** SSE mock).
  *
  * Pillar 2 (harness testing) is proven here — `startCodexMock` serves the

package/dist/codex.js

@@ -16,7 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * `vigiles/codex` — the OpenAI Codex harness adapter. Sits beside
- * `vigiles/claude-code`: same harness-agnostic `vigiles/testing` core, a
+ * `vigiles/claude-code`: same harness-agnostic `vigiles` testing core, a
  * different transport (the `codex` binary + the OpenAI **Responses** SSE mock).
  *
  * Pillar 2 (harness testing) is proven here — `startCodexMock` serves the

package/dist/core/adopt.d.ts

@@ -80,7 +80,7 @@ export interface AdoptSurfaceResult {
     unmappedKeys: string[];
 }
 /**
- * Adopt an existing SKILL.md into a `skill()` spec. The body is carried verbatim
+ * Adopt an existing SKILL.md into an `experimental_skill()` spec. The body is carried verbatim
  * (skills are freeform markdown — `##` headings stay in the body), so a clean
  * skill round-trips below the integrity header.
  *

package/dist/core/adopt.js

@@ -289,7 +289,7 @@ function unmappedNote(kind, keys) {
 const SURFACE_HEADER = (from) => `// Adopted from ${from} by \`vigiles init\` — body verbatim, standard\n` +
     `// frontmatter mapped; no rules inferred. Review the diff, then \`compile\`.\n`;
 /**
- * Adopt an existing SKILL.md into a `skill()` spec. The body is carried verbatim
+ * Adopt an existing SKILL.md into an `experimental_skill()` spec. The body is carried verbatim
  * (skills are freeform markdown — `##` headings stay in the body), so a clean
  * skill round-trips below the integrity header.
  *
@@ -325,7 +325,7 @@ function adoptSkill(markdown, dirName) {
     const trimmedBody = body.trim();
     if (trimmedBody)
         lines.push(`  body: ${tsTemplate(trimmedBody)},`);
-    const spec = (0, spec_js_1.skill)({
+    const spec = (0, spec_js_1.experimental_skill)({
         name,
         description,
         ...(argumentHint ? { argumentHint } : {}),
@@ -336,8 +336,8 @@ function adoptSkill(markdown, dirName) {
     });
     const source = SURFACE_HEADER(`${dirName}/SKILL.md`) +
         unmappedNote("skill", unmappedKeys) +
-        `import { skill } from "vigiles/spec";\n\n` +
-        `export default skill({\n${lines.join("\n")}\n});\n`;
+        `import { experimental_skill } from "vigiles/spec";\n\n` +
+        `export default experimental_skill({\n${lines.join("\n")}\n});\n`;
     return { source, kind: "skill", spec, unmappedKeys };
 }
 /**

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

@@ -1,6 +1,15 @@
 /**
  * vigiles — Generator → SKILL.md compiler.
  *
+ * PARKED (2026-08-16). Not part of the public API and not in `docs/skills.md`.
+ * It works — `vigiles compile` detects `genSkill(` and routes here (`cli.ts`),
+ * verified end-to-end — but `genSkill` / `act` / `checkpoint` / `finish` /
+ * `runSkill` are reachable from NO package subpath, so nobody outside this repo
+ * can author one. Parked rather than deleted because the code is sound and its
+ * tests pass; there is simply nothing to evaluate its usefulness against.
+ * Do not re-document it or give it an entry point without settling that first —
+ * see `docs/skills.md` §Status and the adoption-ladder work.
+ *
  * A generator skill (`function* () { … yield act/gate/result … }`) has dynamic
  * control flow, so it can't be rendered by *executing* it. Instead we parse its
  * SOURCE with the TypeScript compiler API and render the structure to markdown:

package/dist/core/compile-generator.js

@@ -2,6 +2,15 @@
 /**
  * vigiles — Generator → SKILL.md compiler.
  *
+ * PARKED (2026-08-16). Not part of the public API and not in `docs/skills.md`.
+ * It works — `vigiles compile` detects `genSkill(` and routes here (`cli.ts`),
+ * verified end-to-end — but `genSkill` / `act` / `checkpoint` / `finish` /
+ * `runSkill` are reachable from NO package subpath, so nobody outside this repo
+ * can author one. Parked rather than deleted because the code is sound and its
+ * tests pass; there is simply nothing to evaluate its usefulness against.
+ * Do not re-document it or give it an entry point without settling that first —
+ * see `docs/skills.md` §Status and the adoption-ladder work.
+ *
  * A generator skill (`function* () { … yield act/gate/result … }`) has dynamic
  * control flow, so it can't be rendered by *executing* it. Instead we parse its
  * SOURCE with the TypeScript compiler API and render the structure to markdown:

package/dist/core/spec.d.ts

@@ -281,10 +281,10 @@ export declare function instructions(strings: TemplateStringsArray, ...values: I
  * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
  * surface — it does not block on it.
  *
- * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * @experimental Experimental (parked P3) — NOT part of the frozen public surface;
  * may change or be removed without a major bump pre-1.0.
  */
-export declare function effect(strings: TemplateStringsArray, ...values: InstructionFragment[]): EffectRegion;
+export declare function experimental_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
@@ -493,14 +493,20 @@ export type SkillSpecInput<P extends AuthoredPurity | undefined, V extends ToolV
  * Define a SKILL.md specification.
  *
  *   // skills/my-skill/SKILL.md.spec.ts
- *   export default skill({ name: "my-skill", description: "...", body: "..." });
+ *   export default experimental_skill({ name: "my-skill", description: "…" });
  *
  * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
- * constraint), exactly like `agent()`: a vocabulary-bound `skill` (e.g.
- * `vigiles/claude-code`) makes `purity: "pure"` + a side-effecting tool a `tsc`
- * error; the bare core `skill()` accepts any tools, as before.
+ * constraint), exactly like `agent()`: a vocabulary-bound `experimental_skill`
+ * (e.g. `vigiles/claude-code`) makes `purity: "pure"` + a side-effecting tool a
+ * `tsc` error; the bare core one accepts any tools, as before.
+ *
+ * The name also disambiguates: `vigiles/testing` exports a `skill()` that is a
+ * DIFFERENT function — a `Check<Trace>` taking an id string, asking whether a
+ * skill fired. This one authors a skill; that one observes one.
+ *
+ * @experimental
  */
-export declare function skill<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary>(spec: SkillSpecInput<P, V>): SkillSpec;
+export declare function experimental_skill<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary>(spec: SkillSpecInput<P, V>): SkillSpec;
 /**
  * A subagent definition (compiles to `agents/<name>.md`). Unlike a skill —
  * reference material the model reads on activation — a subagent is a *delegated
@@ -758,10 +764,10 @@ export type NeedsContract<N extends Shape> = N;
  *
  *   needs({ plan: "string", files: "string[]" })
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-export declare function needs<const N extends Shape>(shape: N): NeedsContract<N>;
+export declare function experimental_needs<const N extends Shape>(shape: N): NeedsContract<N>;
 /**
  * A typed pipeline step: a `TypedAgentSpec` paired with the input `needs` it
  * reads from the prior step's `ok`. `step()` builds one; `pipe` checks that the
@@ -782,10 +788,10 @@ export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Sha
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-export declare function pipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape>(a: TypedAgentSpec<Ok, Err>, needsContract?: Needs): PipeStep<Needs, Ok, Err>;
+export declare function experimental_pipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape>(a: TypedAgentSpec<Ok, Err>, needsContract?: Needs): PipeStep<Needs, Ok, Err>;
 /**
  * True iff `Producer` provides EVERY field `Consumer` needs, with matching
  * field types. When satisfiable it is `true`; otherwise it collapses to a
@@ -844,10 +850,10 @@ export interface Pipeline<Ok extends Shape, Err extends Shape> {
  * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
  * carrying that step's `ok`/`err` forward.
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-export declare function start<Ok extends Shape, Err extends Shape>(first: PipeStep<Record<string, never>, Ok, Err> | TypedAgentSpec<Ok, Err>): Pipeline<Ok, Err>;
+export declare function experimental_start<Ok extends Shape, Err extends Shape>(first: PipeStep<Record<string, never>, Ok, Err> | TypedAgentSpec<Ok, Err>): Pipeline<Ok, Err>;
 /**
  * Append a step to a typed pipeline. The handoff is CHECKED: the constraint
  * `Supplies<PriorOk, Needs>` must be `true`, else the `next` parameter's type
@@ -859,10 +865,10 @@ export declare function start<Ok extends Shape, Err extends Shape>(first: PipeSt
  * exporting a function called `then` becomes a thenable, so `await import()` of
  * any barrel re-exporting it would invoke it — a footgun the rename avoids.
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-export declare function andThen<PriorOk extends Shape, PriorErr extends Shape, Needs extends Shape, Ok extends Shape, Err extends Shape>(prior: Pipeline<PriorOk, PriorErr>, next: Supplies<PriorOk, Needs> extends true ? PipeStep<Needs, Ok, Err> : {
+export declare function experimental_andThen<PriorOk extends Shape, PriorErr extends Shape, Needs extends Shape, Ok extends Shape, Err extends Shape>(prior: Pipeline<PriorOk, PriorErr>, next: Supplies<PriorOk, Needs> extends true ? PipeStep<Needs, Ok, Err> : {
     readonly __HANDOFF_ERROR: Supplies<PriorOk, Needs>;
 }): Pipeline<Ok, PriorErr | Err>;
 /**
@@ -882,19 +888,19 @@ export declare function andThen<PriorOk extends Shape, PriorErr extends Shape, N
  *     pipeStep(reviewer, needs({ diff: "string" })),
  *   ) // ← won't compile if a handoff doesn't line up
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-export declare function pipe<A extends Shape, AE extends Shape>(a: TypedAgentSpec<A, AE>): Pipeline<A, AE>;
-export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
+export declare function experimental_pipe<A extends Shape, AE extends Shape>(a: TypedAgentSpec<A, AE>): Pipeline<A, AE>;
+export declare function experimental_pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
     readonly __HANDOFF_ERROR: Supplies<A, BN>;
 }): Pipeline<B, AE | BE>;
-export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape, CN extends Shape, C extends Shape, CE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
+export declare function experimental_pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape, CN extends Shape, C extends Shape, CE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
     readonly __HANDOFF_ERROR: Supplies<A, BN>;
 }, c: Supplies<B, CN> extends true ? PipeStep<CN, C, CE> : {
     readonly __HANDOFF_ERROR: Supplies<B, CN>;
 }): Pipeline<C, AE | BE | CE>;
-export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape, CN extends Shape, C extends Shape, CE extends Shape, DN extends Shape, D extends Shape, DE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
+export declare function experimental_pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape, CN extends Shape, C extends Shape, CE extends Shape, DN extends Shape, D extends Shape, DE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
     readonly __HANDOFF_ERROR: Supplies<A, BN>;
 }, c: Supplies<B, CN> extends true ? PipeStep<CN, C, CE> : {
     readonly __HANDOFF_ERROR: Supplies<B, CN>;

package/dist/core/spec.js

@@ -21,21 +21,21 @@ exports.ref = ref;
 exports.dir = dir;
 exports.glob = glob;
 exports.instructions = instructions;
-exports.effect = effect;
+exports.experimental_effect = experimental_effect;
 exports.claude = claude;
 exports.project = project;
 exports.input = input;
 exports.step = step;
-exports.skill = skill;
+exports.experimental_skill = experimental_skill;
 exports.agent = agent;
 exports.result = result;
 exports.delegate = delegate;
 exports.railway = railway;
-exports.needs = needs;
-exports.pipeStep = pipeStep;
-exports.start = start;
-exports.andThen = andThen;
-exports.pipe = pipe;
+exports.experimental_needs = experimental_needs;
+exports.experimental_pipeStep = experimental_pipeStep;
+exports.experimental_start = experimental_start;
+exports.experimental_andThen = experimental_andThen;
+exports.experimental_pipe = experimental_pipe;
 exports.defineConfig = defineConfig;
 // ---------------------------------------------------------------------------
 // Template literal types for type-safe linter references
@@ -192,10 +192,10 @@ function instructions(strings, ...values) {
  * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
  * surface — it does not block on it.
  *
- * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * @experimental Experimental (parked P3) — NOT part of the frozen public surface;
  * may change or be removed without a major bump pre-1.0.
  */
-function effect(strings, ...values) {
+function experimental_effect(strings, ...values) {
     const body = [];
     for (let i = 0; i < strings.length; i++) {
         if (strings[i])
@@ -234,14 +234,20 @@ function step(instr, opts = {}) {
  * Define a SKILL.md specification.
  *
  *   // skills/my-skill/SKILL.md.spec.ts
- *   export default skill({ name: "my-skill", description: "...", body: "..." });
+ *   export default experimental_skill({ name: "my-skill", description: "…" });
  *
  * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
- * constraint), exactly like `agent()`: a vocabulary-bound `skill` (e.g.
- * `vigiles/claude-code`) makes `purity: "pure"` + a side-effecting tool a `tsc`
- * error; the bare core `skill()` accepts any tools, as before.
+ * constraint), exactly like `agent()`: a vocabulary-bound `experimental_skill`
+ * (e.g. `vigiles/claude-code`) makes `purity: "pure"` + a side-effecting tool a
+ * `tsc` error; the bare core one accepts any tools, as before.
+ *
+ * The name also disambiguates: `vigiles/testing` exports a `skill()` that is a
+ * DIFFERENT function — a `Check<Trace>` taking an id string, asking whether a
+ * skill fired. This one authors a skill; that one observes one.
+ *
+ * @experimental
  */
-function skill(spec) {
+function experimental_skill(spec) {
     return { _specType: "skill", ...spec };
 }
 /**
@@ -333,10 +339,10 @@ function railway(spec) {
  *
  *   needs({ plan: "string", files: "string[]" })
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-function needs(shape) {
+function experimental_needs(shape) {
     return shape;
 }
 /**
@@ -346,10 +352,10 @@ function needs(shape) {
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-function pipeStep(a, needsContract = {}) {
+function experimental_pipeStep(a, needsContract = {}) {
     return { _step: "typed-delegate", agent: a, needs: needsContract };
 }
 /**
@@ -357,11 +363,13 @@ function pipeStep(a, needsContract = {}) {
  * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
  * carrying that step's `ok`/`err` forward.
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-function start(first) {
-    const step = "_step" in first ? first : pipeStep(first, {});
+function experimental_start(first) {
+    const step = "_step" in first
+        ? first
+        : experimental_pipeStep(first, {});
     const out = step.agent.output;
     return {
         _specType: "pipeline",
@@ -385,10 +393,10 @@ function start(first) {
  * exporting a function called `then` becomes a thenable, so `await import()` of
  * any barrel re-exporting it would invoke it — a footgun the rename avoids.
  *
- * @internal Experimental typed-composition surface — NOT part of the frozen
+ * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-function andThen(prior, next) {
+function experimental_andThen(prior, next) {
     const real = next;
     const out = real.agent.output;
     const rw = railway({
@@ -403,12 +411,12 @@ function andThen(prior, next) {
         railway: rw,
     };
 }
-function pipe(first, ...rest) {
+function experimental_pipe(first, ...rest) {
     // The overloads above enforce each handoff at the type level; the runtime body
     // is the same left fold of start/andThen, untyped (the checks already happened).
-    let pipeline = start(first);
+    let pipeline = experimental_start(first);
     for (const s of rest) {
-        pipeline = andThen(pipeline, s);
+        pipeline = experimental_andThen(pipeline, s);
     }
     return pipeline;
 }

package/dist/eval-surface.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `vigiles/eval` — the **paid** surface: every runtime export here can call a
+ * model, and therefore can spend money.
+ *
+ * That single property is the whole reason this subpath exists. The package used
+ * to split its testing API by TEST TIER (`vigiles/unit`, `vigiles/integration`,
+ * `vigiles/e2e`, `vigiles/testing`); it now splits on COST. Everything free is on
+ * the package root, [`vigiles`](./test.ts). Everything that bills is here. The
+ * name rhymes with the `vigiles eval` CLI verb.
+ *
+ * ## Why every runtime export is also named `paid_`
+ *
+ * The import path warns ONCE, at the top of the file. The name warns EVERY time,
+ * at the call site. Reading `await judged(trace, "did it refuse?")` on line 140,
+ * the import line is long out of view — `await paid_judged(...)` still says what
+ * it costs. This is not a new idiom in this package: `vigiles/experimental`
+ * already pairs a quarantined subpath with an `experimental_` name prefix for
+ * exactly this reason. The same device, applied to a second axis.
+ *
+ * ⚠️ **The prefix slightly OVERSTATES the cost, and that is a deliberate trade
+ * rather than an oversight.** `paid_judged` takes an injectable judge:
+ * `paid_judged(rubric, { judge: myFn })` calls no model and spends nothing — only
+ * the DEFAULT judge bills. `paid_measureTriggerRate` and friends likewise accept
+ * an injected `evalDriver`. The strictly accurate prefix would be `metered_`, but
+ * it reads a beat slower, and a warning that is not absorbed at a glance is not a
+ * warning. Clarity wins; the imprecision is recorded here and on each symbol
+ * rather than left for a reader to discover.
+ *
+ * ## Why the split had to be cost, not tier
+ *
+ * The old `vigiles/unit` docstring promised "no `claude`, no model, no
+ * bubblewrap, no network" — and re-exported `judged`, whose default judge is a
+ * real model call (`check.ts` resolves `opts.judge ?? ((o) => runJudge(o))`). A
+ * test importing only from that barrel could still spend money, and the one line
+ * a reader would have relied on to know otherwise was the false one. `judged`
+ * moved HERE and became `paid_judged`, which makes that class of defect
+ * unrepresentable rather than apologised for: on this path, billing is the
+ * advertised property, in the subpath and in every name.
+ *
+ * ## What is NOT here, and why
+ *
+ * The ~two dozen helpers that read an eval RESULT — `assertImproves`,
+ * `assertNoRegression`, `assertReliable`, `assertSignificant`, `assertTriggerRate`,
+ * `reliable`, `improvement`, `significantlyBeats`, `compareArms`, `diffReports`,
+ * `diffToJUnit`, `formatBaselineDiff`, `parseBaselineFile`, `readBaseline`,
+ * `toBaselineFile`, `writeBaseline`, `cost`, `latency`, `tokens`, `inputTokens`,
+ * `outputTokens`, `cacheTokens`, `formatEvalReport`, `formatCheckReport`,
+ * `formatTriggerRateReport`, `checkReportToJUnit`, `assertRates` — spend nothing,
+ * so they live on the free root barrel, unprefixed, even though their subject
+ * matter is evals.
+ *
+ * That is the one seam the split cannot make clean: the free helpers are typed
+ * over report shapes DEFINED here. The coupling is real and irreducible, so both
+ * barrels re-export the same report types. **The types are NOT prefixed** — the
+ * prefix is a warning about calling something, and a type is never called;
+ * `paid_EvalReport` would be noise on a symbol that cannot bill. Importing
+ * `vigiles/eval` for a type alone should never be necessary; importing it for a
+ * FUNCTION means you accepted a bill.
+ *
+ * Harness-specific eval drivers are not here either — `codexEvalDriver` /
+ * `codexEvalRunner` / `codexEvalAgentRunner` live on `vigiles/codex`, and
+ * `measureSelectionMatrix` / `assertNoCollision` on `vigiles/claude-code`, because
+ * those surfaces are chosen by harness, not by cost.
+ */
+/**
+ * Run an A/B eval across arms with a real model. Spends money.
+ *
+ * ⚠️ The `paid_` prefix overstates slightly: pass your own `evalDriver` and no
+ * model of ours is called. The DEFAULT path bills.
+ */
+export { runEval as paid_runEval } from "./eval.js";
+/**
+ * Score checks over N trials of one task with a real model. Spends money.
+ *
+ * ⚠️ `paid_` overstates slightly: with an injected `evalDriver` this drives
+ * whatever you supply. The DEFAULT path bills.
+ */
+export { measure as paid_measure } from "./eval.js";
+/**
+ * Score the same checks per arm (a hook/skill/rule on vs off) with a real model.
+ * Spends money.
+ *
+ * ⚠️ `paid_` overstates slightly: an injected `evalDriver` replaces the billed
+ * path. The DEFAULT path bills.
+ */
+export { measureArms as paid_measureArms } from "./eval.js";
+/**
+ * Measure whether a skill's description actually FIRES (recall + precision) by
+ * running real prompts against a real model. Spends money.
+ *
+ * ⚠️ `paid_` overstates slightly: an injected `evalDriver` replaces the billed
+ * path, and `stubSkillBodies` makes the default path much cheaper without making
+ * it free. The DEFAULT path bills.
+ */
+export { measureTriggerRate as paid_measureTriggerRate } from "./eval.js";
+/**
+ * The model-graded judge (harness-agnostic — grades text against a rubric).
+ * Shells out to the `claude` CLI synchronously; needs model auth. Spends money.
+ *
+ * ⚠️ Unlike the others this one has no injection seam — it always calls a model,
+ * so here `paid_` is exact.
+ */
+export { judge as paid_judge } from "./judge.js";
+/**
+ * The one member of the declarative check vocabulary that bills: its default
+ * judge is a real model call. Every other `Check` is deterministic and lives
+ * unprefixed on the free root barrel.
+ *
+ * ⚠️ The `paid_` prefix overstates slightly, and this is the symbol it overstates
+ * most: `paid_judged(rubric, { judge: myFn })` calls YOUR function and spends
+ * nothing. Only `paid_judged(rubric)` — the default — bills.
+ */
+export { judged as paid_judged } from "./check.js";
+/**
+ * The Claude-Code eval driver: the transport `paid_runEval` and friends use by
+ * default. Naming it here is how you pass it explicitly; using it spends money.
+ */
+export { claudeEvalDriver as paid_claudeEvalDriver } from "./eval.js";
+export type { Check, CheckResult, JudgeFn } from "./check.js";
+export type { Trace } from "./harness-test.js";
+export type { EvalArm, EvalDriver, EvalSpec, EvalReport, EvalUsage, MeasureSpec, ArmsMeasureSpec, ArmReport, ArmUsage, ArmsCheckReport, CheckRate, CheckReport, MetricStat, Metrics, ModelOutputParser, ParsedModelRun, PromptDiversityIssue, PromptTriggerStat, RunContext, RunOut, SelectionTrialResult, TriggerRateReport, TriggerRateSpec, AgentRunArgs, AgentRunner, } from "./eval.js";
+//# sourceMappingURL=eval-surface.d.ts.map