vigiles 15.3.0 → 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.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
@@ -11,7 +18,6 @@
  * `research/adapter-api-design.md`.
  */
 export { recordCheck } from "./check-count.js";
-export { runMutations, formatMutationReport, type MutationCase, type MutationEdit, type MutationOutcome, type MutationReport, type MutationVerdict, type RunMutationsOptions, } from "./mutations.js";
 export { runScript } from "./run-script.js";
 export type { RunScriptOptions, ScriptRunResult } from "./run-script.js";
 export { runHook, propertyHook, fileToolEvents } from "./run-hook.js";

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
@@ -30,7 +37,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.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.runHarness = exports.runHarnessTest = exports.judge = exports.hookFired = exports.loadHook = exports.stubSkillBody = exports.parseClaudeRun = exports.claudeEvalDriver = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.measureTriggerRate = exports.measureArms = exports.measure = exports.runEval = exports.fileToolEvents = exports.propertyHook = exports.runHook = exports.runScript = exports.formatMutationReport = exports.runMutations = exports.recordCheck = void 0;
+exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.runHarness = exports.runHarnessTest = exports.judge = exports.hookFired = exports.loadHook = exports.stubSkillBody = exports.parseClaudeRun = exports.claudeEvalDriver = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.measureTriggerRate = exports.measureArms = exports.measure = exports.runEval = exports.fileToolEvents = exports.propertyHook = exports.runHook = exports.runScript = exports.recordCheck = void 0;
 // --- reporting: how much did this script actually do? ---
 // `vigiles test` can otherwise see only an exit code, so a file that runs NOTHING
 // prints the same `✓` as one that ran and passed (measured 2026-08-08 on a file
@@ -39,14 +46,6 @@ exports.formatContainment = exports.compareContainment = exports.skillContract =
 // vitest's `expect` — so those are visible to the runner too. See check-count.ts.
 var check_count_js_1 = require("./check-count.js");
 Object.defineProperty(exports, "recordCheck", { enumerable: true, get: function () { return check_count_js_1.recordCheck; } });
-// --- the tier above the tiers: is a passing test PROVING anything? ---
-// Every tier below reports that a check passed. None can tell a watched assertion
-// from a vacuous one — both print `✓`. `runMutations` plants a defect, runs the
-// test that owns it, and requires the test to fail with the message that NAMES
-// it, so "green" stops being the strongest claim a suite can make about itself.
-var mutations_js_1 = require("./mutations.js");
-Object.defineProperty(exports, "runMutations", { enumerable: true, get: function () { return mutations_js_1.runMutations; } });
-Object.defineProperty(exports, "formatMutationReport", { enumerable: true, get: function () { return mutations_js_1.formatMutationReport; } });
 // --- unit tier: runScript (the primitive) + runHook (it, plus a decision) ---
 // `runScript` runs any program and reports what it DID (exit, both streams,
 // writes, egress). `runHook` is that plus the hook protocol: event to stdin,

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.3.0",
+  "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": {

package/dist/mutations.d.ts

@@ -1,96 +0,0 @@
-/** One edit: the file, the exact substring to find, and what replaces it. */
-export type MutationEdit = readonly [
-    file: string,
-    find: string,
-    replace: string
-];
-/** One planted defect and the assertion that must catch it. */
-export interface MutationCase {
-    /** Short id, printed in the report. */
-    readonly name: string;
-    /** What the mutation takes away, in words — the column a reader scans. */
-    readonly disables: string;
-    /**
-     * The edits that plant it. A LIST, because some defects are only expressible as more than one:
-     * removing a guard AND the vocabulary check that would otherwise throw for an unrelated reason.
-     * Every edit must match its `find` EXACTLY ONCE, or the case is reported `not-applied`.
-     */
-    readonly edits: readonly MutationEdit[];
-    /** The test file that must go red. Its absence is refused, loudly, before anything is touched. */
-    readonly test: string;
-    /** A substring the test's complaint must contain, so a kill by a NEIGHBOUR is not counted. */
-    readonly expect: string;
-}
-/**
- * - `killed` — the test went red AND printed `expect`. The only outcome that counts as proof.
- * - `wrong-assertion` — red, but not with this case's message: two defects share one assertion and
- *   neither is really watched.
- * - `survived` — the test stayed green. The assertion is vacuous, or absent.
- * - `unjudgeable` — the test was ALREADY red before the run, and `expect` never printed, so "red"
- *   carries no information about this mutation. Not a pass and not a failure of the assertion.
- * - `not-applied` — the edit did not land: `find` matched zero or several times, or the
- *   replacement equalled the original.
- */
-export type MutationVerdict = "killed" | "wrong-assertion" | "survived" | "unjudgeable" | "not-applied";
-/** What one case did. */
-export interface MutationOutcome {
-    readonly name: string;
-    readonly disables: string;
-    readonly verdict: MutationVerdict;
-    /** Human-readable specifics — which file, how many matches, whether a retry was needed. */
-    readonly detail: string;
-}
-/** What a whole run did. */
-export interface MutationReport {
-    readonly outcomes: readonly MutationOutcome[];
-    /** Cases with verdict `killed`. */
-    readonly killed: number;
-    /** Test files that were red BEFORE any mutation, so they can testify about nothing. */
-    readonly alreadyRed: readonly string[];
-    /**
-     * Whether every test that was green before the run is green again after it. `false` means the
-     * restore failed and the working tree is not what it was — the one outcome worth interrupting for.
-     */
-    readonly restored: boolean;
-}
-export interface RunMutationsOptions {
-    /** Working directory for the test runs; every path in `edits` and `test` is absolute. */
-    readonly cwd: string;
-    readonly cases: readonly MutationCase[];
-    /**
-     * Extra environment for each test run, merged over `process.env`.
-     * Use it to hand the test the same variables its normal runner would.
-     */
-    readonly env?: NodeJS.ProcessEnv;
-}
-/**
- * Plant each case's defect, run the test that owns it, restore, and report what happened.
- *
- * ```ts
- * const report = runMutations({
- *   cwd: repoRoot,
- *   cases: [{
- *     name: "year",
- *     disables: "the year comparison",
- *     edits: [[checker, "rec.year !== ourYear", "false"]],
- *     test: harness,
- *     expect: "a wrong year was not reported",
- *   }],
- * });
- * console.log(formatMutationReport(report));
- * process.exit(report.killed === report.outcomes.length && report.restored ? 0 : 1);
- * ```
- *
- * 🔴 THIS REWRITES THE FILES NAMED IN `edits` AND RESTORES THEM. The restore runs in a `finally`
- * AND on SIGINT/SIGTERM, because a run killed midway would otherwise leave a neutered checker on
- * disk — and the next run would then measure an already-broken repo and call it healthy. Commit
- * before running. (Do not reach for `git stash` to clear the tree: the stash is repository-global,
- * so a second agent working in another worktree of the same repo will pop your entries.)
- *
- * @throws if `cases` is empty, or if any named test file does not exist — both BEFORE any file is
- * touched, so the message arrives with a clean working tree.
- */
-export declare function runMutations(o: RunMutationsOptions): MutationReport;
-/** Render a report the way the CLI-style runners in this package render theirs. */
-export declare function formatMutationReport(report: MutationReport): string;
-//# sourceMappingURL=mutations.d.ts.map

package/dist/mutations.js

@@ -1,237 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runMutations = runMutations;
-exports.formatMutationReport = formatMutationReport;
-/**
- * `runMutations` — prove a test can FAIL, by breaking the thing it watches.
- *
- * A green test says the checker passed. It does not say the test would notice if the check were
- * deleted: an assertion can be vacuous, a fixture can be wrong in the same direction as the code,
- * and both look exactly like a pass. The only way to tell is to plant a defect and require the
- * test to go red — with the message that NAMES that defect, not merely with something red.
- *
- * ## Why this is in vigiles rather than in a repo's own scripts
- *
- * It arrived as ten hand-written copies of one driver in a dogfooding repo (1799 lines), and the
- * copies had DRIFTED. Counted against the committed versions on 2026-08-14:
- *
- *   - the NO-OP guard (a replacement equal to the original leaves a green test proving nothing)
- *     was in 4 of 10;
- *   - the RETRY (a non-kill re-run once before it is believed) was in 1 of 10;
- *   - the strict rule — killed by its OWN named assertion, not merely by something going red —
- *     was in 1 of 10.
- *
- * Every one of those was written AFTER it caught something, in whichever copy happened to catch
- * it, and never travelled to the other nine. Two copies also named a test file that a refactor had
- * deleted; the runner they used exits 0 on a path matching nothing, so those cases reported
- * SURVIVED on every run for three days. That is the argument for one engine: not less code, but
- * one place where each of those becomes impossible again.
- *
- * ## What this is NOT
- *
- * Not Stryker/mutmut/PIT. Those GENERATE mutants from operators (flip a `<`, drop a `return`) over
- * production code and score a suite by kill ratio. Here the mutations are HAND-AUTHORED and each
- * one names the assertion that must catch it, because the subject is usually not general-purpose
- * code — it is a checker, a hook, an instruction file — where "flip an operator" produces mostly
- * unreachable nonsense and a kill ratio measures nothing. The generated-operator approach is the
- * better tool when it applies; reach for it there.
- *
- * ## The contract, in one sentence
- *
- * Plant one defect, run the test that owns it, and require the test to fail with the message that
- * names it — anything else is reported as a finding, never as a pass.
- *
- * @module
- */
-const node_fs_1 = require("node:fs");
-const node_child_process_1 = require("node:child_process");
-const node_path_1 = require("node:path");
-const run_scripts_js_1 = require("./adapters/claude-code/run-scripts.js");
-function runTest(file, o) {
-    const argv = (0, run_scripts_js_1.interpreterArgs)(file, (0, run_scripts_js_1.detectNodeCaps)(o.cwd));
-    const r = (0, node_child_process_1.spawnSync)("node", argv, {
-        cwd: o.cwd,
-        encoding: "utf8",
-        env: { ...process.env, ...o.env },
-    });
-    return { failed: r.status !== 0, out: (r.stdout ?? "") + (r.stderr ?? "") };
-}
-/**
- * Plant each case's defect, run the test that owns it, restore, and report what happened.
- *
- * ```ts
- * const report = runMutations({
- *   cwd: repoRoot,
- *   cases: [{
- *     name: "year",
- *     disables: "the year comparison",
- *     edits: [[checker, "rec.year !== ourYear", "false"]],
- *     test: harness,
- *     expect: "a wrong year was not reported",
- *   }],
- * });
- * console.log(formatMutationReport(report));
- * process.exit(report.killed === report.outcomes.length && report.restored ? 0 : 1);
- * ```
- *
- * 🔴 THIS REWRITES THE FILES NAMED IN `edits` AND RESTORES THEM. The restore runs in a `finally`
- * AND on SIGINT/SIGTERM, because a run killed midway would otherwise leave a neutered checker on
- * disk — and the next run would then measure an already-broken repo and call it healthy. Commit
- * before running. (Do not reach for `git stash` to clear the tree: the stash is repository-global,
- * so a second agent working in another worktree of the same repo will pop your entries.)
- *
- * @throws if `cases` is empty, or if any named test file does not exist — both BEFORE any file is
- * touched, so the message arrives with a clean working tree.
- */
-function runMutations(o) {
-    if (o.cases.length === 0) {
-        throw new Error("runMutations: no cases. A mutation run with nothing to run reports success, which is the exact claim this API exists to make impossible.");
-    }
-    const tests = [...new Set(o.cases.map((c) => c.test))];
-    // A test path that resolves to nothing is the defect that hid for three days in the corpus this
-    // came from: the runner exits 0 on "no files matched", so every case naming it reported SURVIVED
-    // and sent the reader hunting for an assertion that was never reached.
-    const missing = tests.filter((t) => !(0, node_fs_1.existsSync)(t));
-    if (missing.length > 0) {
-        throw new Error(`runMutations: test file(s) do not exist, so no case naming them could ever be judged:\n  ${missing.join("\n  ")}`);
-    }
-    // Baselined BEFORE anything is touched. Without this, a test that is red on purpose (an open
-    // finding it is meant to report) makes every run announce "the restore failed" about a working
-    // restore, and makes every case against it look killed.
-    const alreadyRed = tests.filter((t) => runTest(t, o).failed);
-    const redBefore = new Set(alreadyRed);
-    const targets = [...new Set(o.cases.flatMap((c) => c.edits.map(([f]) => f)))];
-    const originals = new Map(targets.map((f) => [f, (0, node_fs_1.readFileSync)(f, "utf8")]));
-    const restore = () => {
-        for (const [f, text] of originals)
-            (0, node_fs_1.writeFileSync)(f, text);
-    };
-    const onSignal = (sig) => {
-        restore();
-        process.exit(sig === "SIGINT" ? 130 : 143);
-    };
-    process.on("SIGINT", onSignal);
-    process.on("SIGTERM", onSignal);
-    const outcomes = [];
-    try {
-        for (const c of o.cases) {
-            const applied = apply(c);
-            if (applied) {
-                outcomes.push({
-                    name: c.name,
-                    disables: c.disables,
-                    verdict: "not-applied",
-                    detail: applied,
-                });
-                restore();
-                continue;
-            }
-            // A non-kill is retried ONCE before it is believed. Observed on a real corpus: a row killed
-            // as named came back as a neighbour's assertion in a later full run and reproduced as a clean
-            // kill when replayed alone. Reporting a flake as a survivor sends the next reader to rewrite
-            // a working assertion, which is worse than one extra run.
-            let judged = judge(c, o, redBefore);
-            if (judged.verdict !== "killed") {
-                const second = judge(c, o, redBefore);
-                if (second.verdict === "killed")
-                    judged = {
-                        verdict: "killed",
-                        detail: "killed on retry (the first run was a flake)",
-                    };
-                else
-                    judged = second;
-            }
-            outcomes.push({ name: c.name, disables: c.disables, ...judged });
-            restore();
-        }
-    }
-    finally {
-        restore();
-        process.off("SIGINT", onSignal);
-        process.off("SIGTERM", onSignal);
-    }
-    // Only a test that was GREEN before can testify about the restore.
-    const restored = tests
-        .filter((t) => !redBefore.has(t))
-        .every((t) => !runTest(t, o).failed);
-    return {
-        outcomes,
-        killed: outcomes.filter((r) => r.verdict === "killed").length,
-        alreadyRed,
-        restored,
-    };
-}
-/** Plants one case's edits. Returns a reason string when it could not be planted, else null. */
-function apply(c) {
-    for (const [file, find, replace] of c.edits) {
-        const src = (0, node_fs_1.readFileSync)(file, "utf8");
-        const n = src.split(find).length - 1;
-        if (n !== 1) {
-            return n === 0
-                ? `"find" matched nothing in ${(0, node_path_1.basename)(file)} — the source moved under the case`
-                : `"find" matched ${String(n)} times in ${(0, node_path_1.basename)(file)}; an edit must be unambiguous`;
-        }
-        const next = src.replace(find, replace);
-        // The mutation-that-does-not-mutate, caught against the BYTES rather than the intent: a
-        // replacement equal to the original leaves a green test that reads exactly like a kill.
-        if (next === src)
-            return `the replacement equals the original in ${(0, node_path_1.basename)(file)}`;
-        (0, node_fs_1.writeFileSync)(file, next);
-    }
-    return null;
-}
-function judge(c, o, redBefore) {
-    const { failed, out } = runTest(c.test, o);
-    if (!failed)
-        return {
-            verdict: "survived",
-            detail: `${(0, node_path_1.basename)(c.test)} stayed green with the defect planted`,
-        };
-    if (out.includes(c.expect))
-        return { verdict: "killed", detail: `named by "${c.expect}"` };
-    // When the test was ALREADY red, "red" carries no information — but the MESSAGE still does,
-    // because a runner that aborts at the first failure never reaches a later assertion. Absent it,
-    // the two causes are indistinguishable, and calling it a wrong assertion would be a guess.
-    return redBefore.has(c.test)
-        ? {
-            verdict: "unjudgeable",
-            detail: `${(0, node_path_1.basename)(c.test)} was red before the run and "${c.expect}" never printed`,
-        }
-        : {
-            verdict: "wrong-assertion",
-            detail: `red, but "${c.expect}" never printed — a neighbour's assertion caught it`,
-        };
-}
-/** Render a report the way the CLI-style runners in this package render theirs. */
-function formatMutationReport(report) {
-    const lines = [];
-    if (report.alreadyRed.length > 0) {
-        lines.push(`ℹ️  already red before any mutation: ${report.alreadyRed.map((t) => (0, node_path_1.basename)(t)).join(", ")} — excluded from the restore check; a case naming one is reported unjudgeable.`, "");
-    }
-    const width = Math.max(...report.outcomes.map((r) => r.name.length));
-    const mark = {
-        killed: "✓ killed",
-        "wrong-assertion": "🔴 wrong assertion",
-        survived: "🔴 SURVIVED",
-        unjudgeable: "🔴 unjudgeable",
-        "not-applied": "🔴 not applied",
-    };
-    for (const r of report.outcomes) {
-        lines.push(`${r.name.padEnd(width)}  ${mark[r.verdict].padEnd(20)} ${r.disables}`);
-        if (r.verdict !== "killed")
-            lines.push(`${" ".repeat(width + 2)}  ${r.detail}`);
-    }
-    lines.push("");
-    lines.push(report.restored
-        ? "restored: every test that was green before the run is green again"
-        : "🔴 RESTORE FAILED — a test that was green before the run is red now. The working tree is not what it was.");
-    const bad = report.outcomes.length - report.killed;
-    lines.push(bad === 0
-        ? `✓ all ${String(report.outcomes.length)} mutations killed, each at its own assertion`
-        : `🔴 ${String(bad)} of ${String(report.outcomes.length)} not killed as named: ${report.outcomes
-            .filter((r) => r.verdict !== "killed")
-            .map((r) => r.name)
-            .join(", ")}`);
-    return lines.join("\n");
-}
-//# sourceMappingURL=mutations.js.map