vigiles 15.2.1 → 15.4.0

package/dist/adapters/claude-code/skill-driver.d.ts

@@ -1,6 +1,9 @@
 /**
  * vigiles — Skill driver: the generator (durable-imperative) form of a skill.
  *
+ * PARKED (2026-08-16) — see the header of `src/core/compile-generator.ts`.
+ * Exported from no package subpath; absent from `docs/skills.md` on purpose.
+ *
  * The declarative `skill({ steps })` form compiles to a *static* SKILL.md — it
  * can't express branching/looping, because that control flow depends on runtime
  * values. The generator form does: a skill is a generator that `yield`s

package/dist/adapters/claude-code/skill-driver.js

@@ -2,6 +2,9 @@
 /**
  * vigiles — Skill driver: the generator (durable-imperative) form of a skill.
  *
+ * PARKED (2026-08-16) — see the header of `src/core/compile-generator.ts`.
+ * Exported from no package subpath; absent from `docs/skills.md` on purpose.
+ *
  * The declarative `skill({ steps })` form compiles to a *static* SKILL.md — it
  * can't express branching/looping, because that control flow depends on runtime
  * values. The generator form does: a skill is a generator that `yield`s

package/dist/adapters/claude-code/typed-spec.d.ts

@@ -54,5 +54,5 @@ export declare function agent<const P extends AuthoredPurity | undefined = undef
  * against the Claude Code tool catalog. Identical to the core `skill()` at
  * runtime; the typed `tools` constraint is the only difference.
  */
-export declare function skill<const P extends AuthoredPurity | undefined = undefined>(spec: SkillSpecInput<P, ClaudeCodeToolVocabulary>): SkillSpec;
+export declare function experimental_skill<const P extends AuthoredPurity | undefined = undefined>(spec: SkillSpecInput<P, ClaudeCodeToolVocabulary>): SkillSpec;
 //# sourceMappingURL=typed-spec.d.ts.map

package/dist/adapters/claude-code/typed-spec.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.agent = agent;
-exports.skill = skill;
+exports.experimental_skill = experimental_skill;
 /**
  * Typed Claude Code authoring surface — the compile-time half of the purity
  * contract, bound to the Claude Code tool vocabulary.
@@ -49,7 +49,7 @@ function agent(spec) {
  * against the Claude Code tool catalog. Identical to the core `skill()` at
  * runtime; the typed `tools` constraint is the only difference.
  */
-function skill(spec) {
-    return (0, spec_js_1.skill)(spec);
+function experimental_skill(spec) {
+    return (0, spec_js_1.experimental_skill)(spec);
 }
 //# sourceMappingURL=typed-spec.js.map

package/dist/claude-code.d.ts

@@ -9,7 +9,7 @@ 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,7 +14,7 @@ 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
@@ -35,13 +35,19 @@ Object.defineProperty(exports, "buildClaudeArgs", { enumerable: true, get: funct
 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?"

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/e2e.d.ts

@@ -10,7 +10,9 @@
  * four tiers). Prefer `vigiles/integration`.
  *
  * NOT here: **evals** (`runEval` / `measure` / `measureTriggerRate` / `judge`) —
- * those are non-deterministic measurement (`vigiles/eval`), a different axis.
+ * those are non-deterministic measurement, a different axis. (They live on
+ * `vigiles/testing`; `vigiles/eval` is named here in the original comment and does
+ * not exist as an entry point.)
  */
 export * from "./integration.js";
 //# sourceMappingURL=e2e.d.ts.map

package/dist/e2e.js

@@ -26,7 +26,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * four tiers). Prefer `vigiles/integration`.
  *
  * NOT here: **evals** (`runEval` / `measure` / `measureTriggerRate` / `judge`) —
- * those are non-deterministic measurement (`vigiles/eval`), a different axis.
+ * those are non-deterministic measurement, a different axis. (They live on
+ * `vigiles/testing`; `vigiles/eval` is named here in the original comment and does
+ * not exist as an entry point.)
  */
 __exportStar(require("./integration.js"), exports);
 //# sourceMappingURL=e2e.js.map

package/dist/experimental-emit.js

@@ -71,6 +71,23 @@ function fieldSchema(type) {
             return { type: "boolean" };
         case "string[]":
             return { type: "array", items: { type: "string" } };
+        default:
+            // 🔴 Unreachable from TypeScript, reachable from JavaScript — and the one
+            // shipped example of this API (examples/experimental-emit/run-emit.mjs) is
+            // .mjs, so this is the path a real author takes.
+            //
+            // Without this arm the switch fell through to `undefined`, and every later
+            // step read that as a field: `"actions" in properties` is TRUE for an
+            // undefined value, so nothing noticed; `JSON.stringify` then DROPPED the
+            // key while `required` kept it and `additionalProperties: false` forbade
+            // it. The served schema demanded a property it also banned — unsatisfiable,
+            // silent, and contradicted by `.instruction`, which still asked the model
+            // to send it. Throwing here makes the contradiction impossible to construct
+            // instead of merely unlikely.
+            throw new TypeError(`experimental_emitTool: unsupported field type ${JSON.stringify(type)}. ` +
+                `Supported: "string", "number", "boolean", "string[]". ` +
+                `Nested objects and enums are outside this surface's ceiling — flatten the field, ` +
+                `or use the fenced fork rail if the shape cannot be flattened.`);
     }
 }
 function trackSchema(shape) {

package/dist/experimental.d.ts

@@ -29,6 +29,6 @@
  * @module vigiles/experimental
  */
 export { experimental_startServices, experimental_withServices, type ServiceSpec, type ServiceReady, type ServiceReset, type ServiceHandle, type ServiceSession, type ContainerRuntime, } from "./services.js";
-export { experimental_dockerRuntime, makeDockerRuntime, type DockerExec, type NetProbe, } from "./services-docker.js";
+export { experimental_dockerRuntime, experimental_makeDockerRuntime, type DockerExec, type NetProbe, } from "./services-docker.js";
 export { experimental_emitTool, experimental_parseEmitted, experimental_assertEmittedOk, type EmitFieldSchema, type EmitObjectSchema, type EmitPropertySchema, type EmitTrackSchema, type EmitToolDefinition, type ExperimentalEmitTool, } from "./experimental-emit.js";
 //# sourceMappingURL=experimental.d.ts.map

package/dist/experimental.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = void 0;
+exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = void 0;
 /**
  * `vigiles/experimental` — ⚠️ EXPERIMENTAL, UNSTABLE public surface.
  *
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "experimental_startServices", { enumerable: true,
 Object.defineProperty(exports, "experimental_withServices", { enumerable: true, get: function () { return services_js_1.experimental_withServices; } });
 var services_docker_js_1 = require("./services-docker.js");
 Object.defineProperty(exports, "experimental_dockerRuntime", { enumerable: true, get: function () { return services_docker_js_1.experimental_dockerRuntime; } });
-Object.defineProperty(exports, "makeDockerRuntime", { enumerable: true, get: function () { return services_docker_js_1.makeDockerRuntime; } });
+Object.defineProperty(exports, "experimental_makeDockerRuntime", { enumerable: true, get: function () { return services_docker_js_1.experimental_makeDockerRuntime; } });
 var experimental_emit_js_1 = require("./experimental-emit.js");
 Object.defineProperty(exports, "experimental_emitTool", { enumerable: true, get: function () { return experimental_emit_js_1.experimental_emitTool; } });
 Object.defineProperty(exports, "experimental_parseEmitted", { enumerable: true, get: function () { return experimental_emit_js_1.experimental_parseEmitted; } });

package/dist/harness-assert.d.ts

@@ -309,7 +309,7 @@ interface MatcherOutput {
  * Custom matchers compatible with both vitest and jest. Register once:
  *
  *   import { expect } from "vitest"; // or "@jest/globals"
- *   import { vigilesMatchers } from "vigiles/harness-assert";
+ *   import { vigilesMatchers } from "vigiles/testing";
  *   expect.extend(vigilesMatchers);
  *
  *   expect(result).toHaveCreated("RESULT");

package/dist/harness-assert.js

@@ -69,7 +69,8 @@ const agent_result_js_1 = require("./adapters/claude-code/agent-result.js");
 const stats_js_1 = require("./stats.js");
 const eval_baseline_js_1 = require("./eval-baseline.js");
 // Re-export the significance primitives so the whole eval-analysis surface lives
-// behind `vigiles/harness-assert` (no separate entry point).
+// re-exported from `vigiles/testing` (there is no `vigiles/harness-assert` entry
+// point — it was advertised in this very comment and never existed).
 var stats_js_2 = require("./stats.js");
 Object.defineProperty(exports, "compareArms", { enumerable: true, get: function () { return stats_js_2.compareArms; } });
 var eval_baseline_js_2 = require("./eval-baseline.js");
@@ -689,7 +690,7 @@ function assertTriggerRate(report, opts) {
  * Custom matchers compatible with both vitest and jest. Register once:
  *
  *   import { expect } from "vitest"; // or "@jest/globals"
- *   import { vigilesMatchers } from "vigiles/harness-assert";
+ *   import { vigilesMatchers } from "vigiles/testing";
  *   expect.extend(vigilesMatchers);
  *
  *   expect(result).toHaveCreated("RESULT");

package/dist/services-docker.d.ts

@@ -34,7 +34,7 @@ export declare function parseDockerPort(output: string): number | undefined;
  *
  * @experimental
  */
-export declare function makeDockerRuntime(deps?: {
+export declare function experimental_makeDockerRuntime(deps?: {
     exec?: DockerExec;
     netProbe?: NetProbe;
     sleep?: (ms: number) => Promise<void>;

package/dist/services-docker.js

@@ -6,7 +6,7 @@ exports.dockerRunArgs = dockerRunArgs;
 exports.dockerExecArgs = dockerExecArgs;
 exports.publishedPorts = publishedPorts;
 exports.parseDockerPort = parseDockerPort;
-exports.makeDockerRuntime = makeDockerRuntime;
+exports.experimental_makeDockerRuntime = experimental_makeDockerRuntime;
 /**
  * vigiles — a Docker-backed {@link ContainerRuntime} for the R3 disposable-service
  * tier (⚠️ EXPERIMENTAL / UNSTABLE — see src/services.ts and `vigiles/experimental`).
@@ -166,7 +166,7 @@ function numericNow() {
  *
  * @experimental
  */
-function makeDockerRuntime(deps = {}) {
+function experimental_makeDockerRuntime(deps = {}) {
     const exec = deps.exec ?? realDockerExec;
     const netProbe = deps.netProbe ?? realNetProbe;
     const sleep = deps.sleep ?? delay;
@@ -230,5 +230,5 @@ const containerNames = new WeakMap();
  *
  * @experimental
  */
-exports.experimental_dockerRuntime = makeDockerRuntime();
+exports.experimental_dockerRuntime = experimental_makeDockerRuntime();
 //# sourceMappingURL=services-docker.js.map

package/dist/skill-test.d.ts

@@ -1,6 +1,11 @@
 /**
  * vigiles — Skill testing: deterministic tests for a skill's action sequence.
  *
+ * PARKED (2026-08-16) — this drives the generator form, so it is parked with it;
+ * see the header of `src/core/compile-generator.ts`. `runSkill` is reachable
+ * from no package subpath. `scriptModel` is NOT parked: it is public from
+ * `vigiles/claude-code` and serves the harness testing API independently.
+ *
  * A thin wrapper over the generator driver (`driveSkill`) for use inside an
  * ordinary `node:test` / Vitest `test()` — no custom runner, no DSL. You script
  * the *model* (the non-deterministic part) and assert the deterministic spine:

package/dist/skill-test.js

@@ -2,6 +2,11 @@
 /**
  * vigiles — Skill testing: deterministic tests for a skill's action sequence.
  *
+ * PARKED (2026-08-16) — this drives the generator form, so it is parked with it;
+ * see the header of `src/core/compile-generator.ts`. `runSkill` is reachable
+ * from no package subpath. `scriptModel` is NOT parked: it is public from
+ * `vigiles/claude-code` and serves the harness testing API independently.
+ *
  * A thin wrapper over the generator driver (`driveSkill`) for use inside an
  * ordinary `node:test` / Vitest `test()` — no custom runner, no DSL. You script
  * the *model* (the non-deterministic part) and assert the deterministic spine:

package/dist/testing.d.ts

@@ -3,7 +3,14 @@
  * the three tiers — `runHook` (unit), `runHarnessTest` (deterministic), `runEval`
  * (eval) — plus the runner-agnostic predicates/assertions. Kept deliberately
  * separate from `vigiles/claude-code` so this surface can stay harness-agnostic as
- * more harnesses are added. Granular paths (`vigiles/run-hook`, etc.) still work.
+ * more harnesses are added.
+ *
+ * 🔴 THIS LINE USED TO SAY the granular paths (`vigiles/run-hook`, etc.) «still
+ * work». MEASURED 2026-08-16: they do not. `vigiles/run-hook`, `vigiles/eval`,
+ * `vigiles/harness-test`, `vigiles/harness-assert`, `vigiles/skill` and
+ * `vigiles/skill-test` all raise ERR_PACKAGE_PATH_NOT_EXPORTED — six paths this
+ * package advertised to its own readers and does not serve. A promise that an
+ * import keeps working is exactly the kind a reader has no reason to re-check.
  *
  * It re-exports the composition-root runner modules (which do the Claude-Code
  * default-wiring), never an adapter directly — the `agnostic-surface` eslint

package/dist/testing.js

@@ -4,7 +4,14 @@
  * the three tiers — `runHook` (unit), `runHarnessTest` (deterministic), `runEval`
  * (eval) — plus the runner-agnostic predicates/assertions. Kept deliberately
  * separate from `vigiles/claude-code` so this surface can stay harness-agnostic as
- * more harnesses are added. Granular paths (`vigiles/run-hook`, etc.) still work.
+ * more harnesses are added.
+ *
+ * 🔴 THIS LINE USED TO SAY the granular paths (`vigiles/run-hook`, etc.) «still
+ * work». MEASURED 2026-08-16: they do not. `vigiles/run-hook`, `vigiles/eval`,
+ * `vigiles/harness-test`, `vigiles/harness-assert`, `vigiles/skill` and
+ * `vigiles/skill-test` all raise ERR_PACKAGE_PATH_NOT_EXPORTED — six paths this
+ * package advertised to its own readers and does not serve. A promise that an
+ * import keeps working is exactly the kind a reader has no reason to re-check.
  *
  * It re-exports the composition-root runner modules (which do the Claude-Code
  * default-wiring), never an adapter directly — the `agnostic-surface` eslint

package/dist/unit.d.ts

@@ -1,8 +1,23 @@
 /**
  * `vigiles/unit` — the **no-capability** harness-testing surface.
  *
- * Importing from here is a contract: this test needs **no `claude`, no model, no
- * bubblewrap, no network** — only a process. It is the cheap base of the pyramid:
+ * Importing from here is MOSTLY a contract: this test needs no `claude`, no
+ * bubblewrap and no network — only a process. It is the cheap base of the pyramid:
+ *
+ * 🔴 «NO MODEL» IS NOT TRUE TODAY, AND SAYING SO WAS THE WORST OF THE FOUR
+ * MISSTATEMENTS ON THIS SURFACE, because it reads as a guarantee rather than a
+ * description. `judged` is re-exported here and its default judge is a REAL model
+ * call — `check.ts` resolves `opts.judge ?? ((o) => runJudge(o))`. So a test that
+ * imports only from this barrel can still spend money, and the one line a reader
+ * would rely on to know it cannot is this one.
+ *
+ * The honest fix is to MOVE `judged` off this barrel, not to reword the sentence —
+ * but that changes the public surface, and the surface is being reorganised
+ * separately (the measured proposal splits by COST: everything free on one path,
+ * everything that spends money on another, where this defect becomes unexpressible
+ * rather than merely documented). Until that lands, the claim is corrected here
+ * rather than left standing.
+ *
  * `runHook` (pipe a synthesized event to a hook and read the block/allow
  * decision), the bare `Trace` predicates, the `assert*` helpers, and the pure
  * parsers. A `*.test.ts` should import **only** from here (enforced by lint).

package/dist/unit.js

@@ -18,8 +18,23 @@ exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblocke
 /**
  * `vigiles/unit` — the **no-capability** harness-testing surface.
  *
- * Importing from here is a contract: this test needs **no `claude`, no model, no
- * bubblewrap, no network** — only a process. It is the cheap base of the pyramid:
+ * Importing from here is MOSTLY a contract: this test needs no `claude`, no
+ * bubblewrap and no network — only a process. It is the cheap base of the pyramid:
+ *
+ * 🔴 «NO MODEL» IS NOT TRUE TODAY, AND SAYING SO WAS THE WORST OF THE FOUR
+ * MISSTATEMENTS ON THIS SURFACE, because it reads as a guarantee rather than a
+ * description. `judged` is re-exported here and its default judge is a REAL model
+ * call — `check.ts` resolves `opts.judge ?? ((o) => runJudge(o))`. So a test that
+ * imports only from this barrel can still spend money, and the one line a reader
+ * would rely on to know it cannot is this one.
+ *
+ * The honest fix is to MOVE `judged` off this barrel, not to reword the sentence —
+ * but that changes the public surface, and the surface is being reorganised
+ * separately (the measured proposal splits by COST: everything free on one path,
+ * everything that spends money on another, where this defect becomes unexpressible
+ * rather than merely documented). Until that lands, the claim is corrected here
+ * rather than left standing.
+ *
  * `runHook` (pipe a synthesized event to a hook and read the block/allow
  * decision), the bare `Trace` predicates, the `assert*` helpers, and the pure
  * parsers. A `*.test.ts` should import **only** from here (enforced by lint).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "15.2.1",
+  "version": "15.4.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",
@@ -92,6 +92,8 @@
     "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json",
     "api:report": "npm run build && node scripts/api-extractor.mjs --local",
     "api:check": "npm run build && node scripts/api-extractor.mjs",
+    "docs:check": "npm run build && node scripts/check-doc-imports.mjs . docs README.md",
+    "experimental:check": "npm run api:check && node scripts/check-experimental-naming.mjs",
     "docs:api": "typedoc"
   },
   "devDependencies": {