vigiles 19.0.1 → 21.0.0

package/dist/core/hook-program.js

@@ -6,7 +6,7 @@ exports.invalidToolPatterns = invalidToolPatterns;
 exports.gateAction = gateAction;
 exports.trimTrailingSeparators = trimTrailingSeparators;
 exports.commandView = commandView;
-exports.defineHook = defineHook;
+exports.experimental_defineHook = experimental_defineHook;
 exports.decideProgram = decideProgram;
 exports.decisionExitCode = decisionExitCode;
 exports.checkHookImports = checkHookImports;
@@ -20,17 +20,17 @@ exports.verifyHookStamp = verifyHookStamp;
 exports.pathView = pathView;
 exports.projectRootOf = projectRootOf;
 exports.undecidablePathWarning = undecidablePathWarning;
-exports.defineFileGate = defineFileGate;
+exports.experimental_defineFileGate = experimental_defineFileGate;
 exports.decideFileGate = decideFileGate;
-exports.definePromptGate = definePromptGate;
+exports.experimental_definePromptGate = experimental_definePromptGate;
 exports.decidePromptGate = decidePromptGate;
-exports.defineStopGate = defineStopGate;
+exports.experimental_defineStopGate = experimental_defineStopGate;
 exports.decideStopGate = decideStopGate;
-exports.defineInject = defineInject;
+exports.experimental_defineInject = experimental_defineInject;
 exports.runInject = runInject;
 exports.injectionOf = injectionOf;
 exports.responseView = responseView;
-exports.defineReact = defineReact;
+exports.experimental_defineReact = experimental_defineReact;
 exports.runReact = runReact;
 exports.outcomeWrites = outcomeWrites;
 exports.rememberHookSource = rememberHookSource;
@@ -536,10 +536,13 @@ function commandView(raw, root) {
 const tool = (name) => ({ tool: name });
 exports.tool = tool;
 /**
- * @experimental Compiled hooks are provisional — see docs/experimental.md.
- * Imported as `experimental_defineHook`; alias it at the import site.
+ * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
+ * Imported and CALLED as `experimental_defineHook` — do not alias the prefix away at
+ * the import. Measured 2026-08-21: with the alias in place the marker survived
+ * at 0 of 5 call sites in the only user-facing example, because a reader 200
+ * lines down sees `defineHook` without it and cannot tell it is provisional.
  */
-function defineHook(p) {
+function experimental_defineHook(p) {
     return p;
 }
 // ---------------------------------------------------------------------------
@@ -918,10 +921,13 @@ const tools = (...names) => ({
 });
 exports.tools = tools;
 /**
- * @experimental Compiled hooks are provisional — see docs/experimental.md.
- * Imported as `experimental_defineFileGate`; alias it at the import site.
+ * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
+ * Imported and CALLED as `experimental_defineFileGate` — do not alias the prefix away at
+ * the import. Measured 2026-08-21: with the alias in place the marker survived
+ * at 0 of 5 call sites in the only user-facing example, because a reader 200
+ * lines down sees `defineFileGate` without it and cannot tell it is provisional.
  */
-function defineFileGate(p) {
+function experimental_defineFileGate(p) {
     return { role: "gate", ...p };
 }
 /**
@@ -949,10 +955,13 @@ function decideFileGate(hook, raw, ctx = {}, root = typeof raw.cwd === "string"
     });
 }
 /**
- * @experimental Compiled hooks are provisional — see docs/experimental.md.
- * Imported as `experimental_definePromptGate`; alias it at the import site.
+ * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
+ * Imported and CALLED as `experimental_definePromptGate` — do not alias the prefix away at
+ * the import. Measured 2026-08-21: with the alias in place the marker survived
+ * at 0 of 5 call sites in the only user-facing example, because a reader 200
+ * lines down sees `definePromptGate` without it and cannot tell it is provisional.
  */
-function definePromptGate(p) {
+function experimental_definePromptGate(p) {
     return { role: "prompt-gate", ...p };
 }
 /** Run a prompt gate against a raw UserPromptSubmit event (reads `prompt`). */
@@ -965,10 +974,13 @@ function decidePromptGate(hook, raw, ctx = {}) {
     });
 }
 /**
- * @experimental Compiled hooks are provisional — see docs/experimental.md.
- * Imported as `experimental_defineStopGate`; alias it at the import site.
+ * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
+ * Imported and CALLED as `experimental_defineStopGate` — do not alias the prefix away at
+ * the import. Measured 2026-08-21: with the alias in place the marker survived
+ * at 0 of 5 call sites in the only user-facing example, because a reader 200
+ * lines down sees `defineStopGate` without it and cannot tell it is provisional.
  */
-function defineStopGate(p) {
+function experimental_defineStopGate(p) {
     return { role: "stop-gate", ...p };
 }
 /** Run a Stop gate against a raw Stop/SubagentStop event (reads `stop_hook_active`). */
@@ -994,10 +1006,13 @@ const inject = (context, ...records) => ({
 });
 exports.inject = inject;
 /**
- * @experimental Compiled hooks are provisional — see docs/experimental.md.
- * Imported as `experimental_defineInject`; alias it at the import site.
+ * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
+ * Imported and CALLED as `experimental_defineInject` — do not alias the prefix away at
+ * the import. Measured 2026-08-21: with the alias in place the marker survived
+ * at 0 of 5 call sites in the only user-facing example, because a reader 200
+ * lines down sees `defineInject` without it and cannot tell it is provisional.
  */
-function defineInject(p) {
+function experimental_defineInject(p) {
     return { role: "inject", ...p };
 }
 /**
@@ -1076,10 +1091,13 @@ const nothing = (...records) => ({
 });
 exports.nothing = nothing;
 /**
- * @experimental Compiled hooks are provisional — see docs/experimental.md.
- * Imported as `experimental_defineReact`; alias it at the import site.
+ * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
+ * Imported and CALLED as `experimental_defineReact` — do not alias the prefix away at
+ * the import. Measured 2026-08-21: with the alias in place the marker survived
+ * at 0 of 5 call sites in the only user-facing example, because a reader 200
+ * lines down sees `defineReact` without it and cannot tell it is provisional.
  */
-function defineReact(p) {
+function experimental_defineReact(p) {
     return { role: "react", ...p };
 }
 /**

package/dist/core/rule-meta.js

@@ -86,7 +86,7 @@ exports.RULE_META = {
         defaultSeverity: "warn",
         summary: "A subagent's tools: are all real (no never-available / typo).",
         detector: "verifyToolContract / scoredIssues",
-        upstreamPrevention: "typed agent() vocabulary + compileAgent — an unknown tool is a tsc/compile error",
+        upstreamPrevention: "typed experimental_agent() vocabulary + compileAgent — an unknown tool is a tsc/compile error",
     },
     "disallowed-tools-contract": {
         id: "disallowed-tools-contract",
@@ -95,7 +95,7 @@ exports.RULE_META = {
         defaultSeverity: "warn",
         summary: "A disallowedTools: entry isn't a typo that blocks nothing.",
         detector: "disallowedToolIssues",
-        upstreamPrevention: "typed agent() vocabulary (a typo is a tsc error)",
+        upstreamPrevention: "typed experimental_agent() vocabulary (a typo is a tsc error)",
     },
     "subagent-frontmatter": {
         id: "subagent-frontmatter",

package/dist/core/skill-normalize.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one implementation of "fold the deprecated `result:` into `postcondition:`".
+ *
+ * 🔴 WHY THIS IS ITS OWN MODULE, and the mistake that produced it. The fold
+ * originally lived inside `experimental_skill()` alone, with a comment arguing
+ * that normalising "at the door" beats normalising at each reader — because a
+ * reader added later would silently read only the new field and drop every spec
+ * still on the old one. The argument was right. The identification of the door
+ * was wrong: `experimental_skill()` is not the only entrance.
+ *
+ * `compileSkill()` is public, and it accepts a `SkillSpec` STRUCTURALLY. That
+ * interface still advertises `result?: Gate`, so this compiles and is legal:
+ *
+ *   compileSkill({ _specType: "skill", name, description, body, result: cmd("npm test") })
+ *
+ * Such a caller never touches the builder, so before this module the `## Result`
+ * section and its reference verification were both silently dropped — the exact
+ * defect the original comment predicted, arriving through the entrance it did not
+ * count. Found by a reviewer, not by me.
+ *
+ * So: one function, called at BOTH doors. That is not two sources of truth — it
+ * is one, used twice. Putting it in spec.ts would have meant either exporting it
+ * from `vigiles/spec` (public surface for an internal concern) or duplicating it
+ * in compile.ts (the thing being avoided). This module is imported by both and
+ * re-exported by neither, so it stays off every api report.
+ *
+ * ⚠️ IT IMPORTS NOTHING, including from spec.ts, and that is deliberate.
+ * `core/spec.ts` is the dependency ROOT of this package — it has zero imports of
+ * its own — and spec.ts has to call this. Naming `Gate` here would put a back
+ * edge into the root; a type-only import erases at runtime, but the graph would
+ * still read as a cycle to anyone (or any lint rule) looking at it. The fold does
+ * not care what a gate IS, only which of two properties holds one, so the shape
+ * is described structurally and the dependency stays one-directional.
+ */
+/** Anything carrying the two spellings of a skill's terminal gate. */
+interface HasPostcondition<G> {
+    readonly postcondition?: G;
+    /** @deprecated the old spelling; folded away by {@link foldLegacyPostcondition}. */
+    readonly result?: G;
+}
+/**
+ * Return `spec` with `result:` folded into `postcondition:` and `result` removed.
+ *
+ * Throws when both are set: they are the same field under two names, so which
+ * gate runs would otherwise be decided by which branch of the fold ran last —
+ * a coin flip in a place where the answer is a gate.
+ */
+export declare function foldLegacyPostcondition<G, T extends HasPostcondition<G>>(spec: T): T;
+export {};
+//# sourceMappingURL=skill-normalize.d.ts.map

package/dist/core/skill-normalize.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * The one implementation of "fold the deprecated `result:` into `postcondition:`".
+ *
+ * 🔴 WHY THIS IS ITS OWN MODULE, and the mistake that produced it. The fold
+ * originally lived inside `experimental_skill()` alone, with a comment arguing
+ * that normalising "at the door" beats normalising at each reader — because a
+ * reader added later would silently read only the new field and drop every spec
+ * still on the old one. The argument was right. The identification of the door
+ * was wrong: `experimental_skill()` is not the only entrance.
+ *
+ * `compileSkill()` is public, and it accepts a `SkillSpec` STRUCTURALLY. That
+ * interface still advertises `result?: Gate`, so this compiles and is legal:
+ *
+ *   compileSkill({ _specType: "skill", name, description, body, result: cmd("npm test") })
+ *
+ * Such a caller never touches the builder, so before this module the `## Result`
+ * section and its reference verification were both silently dropped — the exact
+ * defect the original comment predicted, arriving through the entrance it did not
+ * count. Found by a reviewer, not by me.
+ *
+ * So: one function, called at BOTH doors. That is not two sources of truth — it
+ * is one, used twice. Putting it in spec.ts would have meant either exporting it
+ * from `vigiles/spec` (public surface for an internal concern) or duplicating it
+ * in compile.ts (the thing being avoided). This module is imported by both and
+ * re-exported by neither, so it stays off every api report.
+ *
+ * ⚠️ IT IMPORTS NOTHING, including from spec.ts, and that is deliberate.
+ * `core/spec.ts` is the dependency ROOT of this package — it has zero imports of
+ * its own — and spec.ts has to call this. Naming `Gate` here would put a back
+ * edge into the root; a type-only import erases at runtime, but the graph would
+ * still read as a cycle to anyone (or any lint rule) looking at it. The fold does
+ * not care what a gate IS, only which of two properties holds one, so the shape
+ * is described structurally and the dependency stays one-directional.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.foldLegacyPostcondition = foldLegacyPostcondition;
+/**
+ * Return `spec` with `result:` folded into `postcondition:` and `result` removed.
+ *
+ * Throws when both are set: they are the same field under two names, so which
+ * gate runs would otherwise be decided by which branch of the fold ran last —
+ * a coin flip in a place where the answer is a gate.
+ */
+function foldLegacyPostcondition(spec) {
+    // This IS the one place the deprecated field may be read — the fold is what
+    // makes the old spelling work at all, so a lint that forbade it everywhere
+    // would forbid the alias window itself.
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- see above
+    const { result: legacy, ...rest } = spec;
+    if (!legacy)
+        return spec;
+    if (rest.postcondition) {
+        throw new Error("skill spec sets BOTH `postcondition:` and the deprecated `result:` — " +
+            "they are the same field under two names, so which gate runs is a " +
+            "coin flip. Keep `postcondition:` and delete `result:`.");
+    }
+    return { ...rest, postcondition: legacy };
+}
+//# sourceMappingURL=skill-normalize.js.map

package/dist/core/spec.d.ts

@@ -71,7 +71,7 @@ export type StrictCmd = [keyof KnownNpmScripts] extends [never] ? string : `npm
  *   MCP / unknown / wildcard.
  *
  * The default (`string` at both) imposes no constraint — any tool is accepted at
- * every level, the historical behaviour of an untyped `agent()`/`skill()`.
+ * every level, the historical behaviour of an untyped `experimental_agent()`/`skill()`.
  */
 export interface ToolVocabulary {
     /** Union of tool names allowed under `purity: "pure"`. */
@@ -94,8 +94,6 @@ export interface OpenToolVocabulary extends ToolVocabulary {
  * untyped surface accepts any tools.
  */
 export type AllowedAt<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = P extends "pure" ? V["readOnly"] : P extends "bounded" ? V["bounded"] : string;
-export type ClaudeTool = "Read" | "Write" | "Edit" | "Bash" | "Grep" | "Glob" | "Agent" | "TodoWrite" | "WebSearch" | "WebFetch" | "NotebookEdit";
-export type HookEvent = "PreToolUse" | "PostToolUse" | "PreSession" | "PostSession" | "Notification";
 /** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.) or to a vigiles-internal check. */
 export interface EnforceRule {
     readonly _kind: "enforce";
@@ -257,18 +255,18 @@ export type InstructionFragment = string | Ref | EffectRegion;
 /**
  * Tagged template literal for skill instructions with typed references.
  *
- *   instructions`
+ *   prose`
  *     Check ${file("eslint.config.ts")} for rules.
  *     Run ${cmd("npm test")} to verify.
  *     See ${ref("skills/other/SKILL.md")} for format.
  *   `
  */
-export declare function instructions(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];
+export declare function prose(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];
 /**
  * Tagged template literal marking a side-effect boundary — usable as an
  * interpolated fragment inside a body / `instructions\`\``:
  *
- *   instructions`
+ *   prose`
  *     ## Apply
  *     ${effect`
  *       Side effects are allowed ONLY here:
@@ -332,7 +330,7 @@ export interface ClaudeSpec {
     readonly rules: Record<string, Rule>;
 }
 /**
- * Input type for claude() — maxSectionLines is only valid when sections are provided.
+ * Input type for instructionFile() — maxSectionLines is only valid when sections are provided.
  * TypeScript errors if you set maxSectionLines without defining sections.
  */
 type ClaudeSpecBase = {
@@ -354,9 +352,9 @@ type ClaudeSpecInput = ClaudeSpecBase & ClaudeSpecSections;
  * Define a CLAUDE.md specification.
  *
  *   // CLAUDE.md.spec.ts
- *   export default claude({ commands: {...}, rules: {...} });
+ *   export default instructionFile({ commands: {...}, rules: {...} });
  */
-export declare function claude(spec: ClaudeSpecInput): ClaudeSpec;
+export declare function instructionFile(spec: ClaudeSpecInput): ClaudeSpec;
 /**
  * A deterministic gate on a skill step or its final result. A gate is one of:
  * a command (exit 0), a file (must exist), or a *project role* that resolves to
@@ -484,6 +482,25 @@ export interface SkillSpec {
     /**
      * Terminal postcondition — the skill is "done" only when this gate passes.
      * Compiles to a `## Result` section + a `vigiles:result` marker.
+     *
+     * 🔴 NAMED `postcondition`, NOT `result`, because `result` already means
+     * something else one screen down: {@link result} builds a subagent's typed
+     * ok/err CONTRACT (and reaches a skill through `output:`). Two concepts under
+     * one word, told apart only by whether you wrote `result:` or `output:
+     * result(...)` — the doc comment on {@link result} had to spend a line saying
+     * "distinct from a skill's `result:` postcondition gate", which is the tell.
+     * A name that needs a disambiguating sentence is the wrong name.
+     *
+     * The compiled MARKER stays `vigiles:result` deliberately: it is the wire
+     * format between the compiler and {@link parseSkillGates}, and every already
+     * compiled SKILL.md on disk carries it. Renaming the authoring field is a
+     * source-level change; renaming the marker would invalidate stamps.
+     */
+    readonly postcondition?: Gate;
+    /**
+     * @deprecated Renamed to {@link SkillSpec.postcondition}. Removed next
+     * major. Measured 2026-08-21: 0 of 46 specs in the consuming knowledge base
+     * set this field, so the window costs nothing and closes the collision above.
      */
     readonly result?: Gate;
     /**
@@ -524,7 +541,7 @@ export type SkillSpecInput<P extends AuthoredPurity | undefined, V extends ToolV
  *   export default experimental_skill({ name: "my-skill", description: "…" });
  *
  * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
- * constraint), exactly like `agent()`: a vocabulary-bound `experimental_skill`
+ * constraint), exactly like `experimental_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.
  *
@@ -629,7 +646,7 @@ export interface AgentSpec {
     readonly purity?: AuthoredPurity;
 }
 /**
- * The input to `agent()` — `AgentSpec` minus the internal `_specType`, with the
+ * The input to `experimental_agent()` — `AgentSpec` minus the internal `_specType`, with the
  * `tools` list constrained by the declared `purity` and the tool vocabulary `V`.
  * `P` is inferred from the literal `purity` field (`const` inference), and
  * `tools` is then typed `AllowedAt<P, V>[]`:
@@ -637,7 +654,7 @@ export interface AgentSpec {
  * - `purity: "bounded"`→ `tools` may list `V["bounded"]` tools (admits `Bash`).
  * - no `purity` / `"dangerously-unrestricted"` → `tools` is `string[]` (open).
  *
- * With the open default vocabulary (core `agent()`) every level widens to
+ * With the open default vocabulary (core `experimental_agent()`) every level widens to
  * `string`, so any tools compile — backwards-compatible.
  */
 export type AgentSpecInput<P extends AuthoredPurity | undefined, V extends ToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape> = Omit<AgentSpec, "_specType" | "tools" | "purity" | "output"> & {
@@ -672,12 +689,12 @@ export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
  * Define a subagent specification (compiles to `agents/<name>.md`).
  *
  *   // agents/reviewer.md.spec.ts
- *   export default agent({
+ *   export default experimental_agent({
  *     name: "reviewer",
  *     description: "Review a diff for correctness. Dispatch PROACTIVELY after edits.",
  *     model: "sonnet",
  *     tools: ["Read", "Grep", "Bash"],
- *     body: instructions`Review the diff. Run ${cmd("npm test")} first.`,
+ *     body: prose`Review the diff. Run ${cmd("npm test")} first.`,
  *     rules: {
  *       "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."),
  *     },
@@ -686,15 +703,21 @@ export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
  * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
  * constraint). A harness adapter re-exports a vocabulary-bound `agent` (e.g.
  * `vigiles/claude-code`) so `purity: "pure"` + a side-effecting tool is a `tsc`
- * error at edit time; the bare core `agent()` accepts any tools, as before.
+ * error at edit time; the bare core `experimental_agent()` accepts any tools, as before.
  *
  * Also generic over the result's `Ok`/`Err` shapes, inferred from `output:
  * result(...)`. The returned value is a `TypedAgentSpec<Ok, Err>` — an
  * `AgentSpec` that carries those shapes at the type level, so a typed `pipe`
  * can cross-reference the handoff. With no `output` the shapes default to the
  * erased `Shape`, and the value is still a plain `AgentSpec` — backwards-compatible.
+ *
+ * @experimental The SHAPE is not settled — the author is unsure of the design,
+ * which is exactly what this marker promises: the form may change. It is NOT a
+ * claim that the surface is unproven. Measured 2026-06-20: real Claude Code
+ * loaded a compiled `agents/code-reviewer.md`, dispatched to it and read it,
+ * 100% of trials — stronger end-to-end evidence than `experimental_skill` has.
  */
-export declare function agent<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape>(spec: AgentSpecInput<P, V, Ok, Err>): TypedAgentSpec<Ok, Err>;
+declare function agentSpec<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape>(spec: AgentSpecInput<P, V, Ok, Err>): TypedAgentSpec<Ok, Err>;
 /**
  * The field types a result contract can declare (kept tiny + dependency-free).
  *
@@ -748,8 +771,9 @@ export interface OutputContract<Ok extends Shape = Shape, Err extends Shape = Sh
  * cross-reference one agent's `ok` against the next agent's needs at `tsc` time.
  * The return is still an `OutputContract`, so every existing consumer (the
  * `output:` field, `renderOutputContract`, `parseAgentResult`) is unchanged.
+ 
  */
-export declare function result<const Ok extends Shape, const Err extends Shape>(ok: Ok, err: Err): OutputContract<Ok, Err>;
+declare function result<const Ok extends Shape, const Err extends Shape>(ok: Ok, err: Err): OutputContract<Ok, Err>;
 /** One step on a railway: dispatch a flat subagent (the "activity"). */
 export interface RailwayStep {
     readonly _step: "delegate";
@@ -780,8 +804,9 @@ export interface RailwayStep {
  * handoff that doesn't line up is a `tsc` error naming the offending field.
  * Omitting it (the historical 1-/2-arg call) keeps the exact string-path
  * behavior — fully backwards-compatible.
+ 
  */
-export declare function delegate(agent: string, task?: string, needsContract?: Shape): RailwayStep;
+declare function delegate(agent: string, task?: string, needsContract?: Shape): RailwayStep;
 /**
  * A railway over flat subagents. `steps` run in order on the success track; the
  * first step that returns an error short-circuits to `onError`. `recover`
@@ -810,8 +835,9 @@ export interface Railway {
  *     onError: delegate("reporter"),
  *     recover: { step: delegate("fixer"), max: 2 },
  *   })
+ 
  */
-export declare function railway(spec: Omit<Railway, "_specType">): Railway;
+declare function railway(spec: Omit<Railway, "_specType">): Railway;
 /**
  * A subagent's INPUT contract — the fields it reads from the prior step's `ok`.
  * Declared via `needs(...)` and threaded into the typed agent so `pipe` can
@@ -831,8 +857,9 @@ export type NeedsContract<N extends Shape> = N;
  *
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
+ 
  */
-export declare function experimental_needs<const N extends Shape>(shape: N): NeedsContract<N>;
+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
@@ -848,15 +875,16 @@ export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Sha
 }
 /**
  * Pair a typed agent with the input it `needs` from the previous step. The first
- * argument is an `agent()` VALUE (which carries its `result()` shape); the
+ * argument is an `experimental_agent()` VALUE (which carries its `result()` shape); the
  * second is the `needs(...)` input contract.
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
  *
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
+ 
  */
-export declare function experimental_pipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape>(a: TypedAgentSpec<Ok, Err>, needsContract?: Needs): PipeStep<Needs, Ok, Err>;
+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
@@ -917,8 +945,9 @@ export interface Pipeline<Ok extends Shape, Err extends Shape> {
  *
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
+ 
  */
-export declare function experimental_start<Ok extends Shape, Err extends Shape>(first: PipeStep<Record<string, never>, Ok, Err> | TypedAgentSpec<Ok, Err>): Pipeline<Ok, Err>;
+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
@@ -932,8 +961,9 @@ export declare function experimental_start<Ok extends Shape, Err extends Shape>(
  *
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
+ 
  */
-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> : {
+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>;
 /**
@@ -956,16 +986,16 @@ export declare function experimental_andThen<PriorOk extends Shape, PriorErr ext
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
  */
-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> : {
+declare function experimental_pipe<A extends Shape, AE extends Shape>(a: TypedAgentSpec<A, AE>): Pipeline<A, AE>;
+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 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> : {
+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 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> : {
+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>;
@@ -1028,5 +1058,69 @@ export interface VigilesV2Config {
     readonly linters?: Record<string, LinterMode>;
 }
 export declare function defineConfig(config: VigilesV2Config): VigilesV2Config;
+/**
+ * @deprecated Renamed to {@link instructionFile}. The builder compiles to
+ * `CLAUDE.md` **and** `AGENTS.md` (see `InstructionTarget`), so a name taken from
+ * one of the two harnesses was never right. Removed one major AFTER the one that introduces it.
+ */
+export declare const claude: typeof instructionFile;
+/**
+ * @deprecated Renamed to {@link prose}. It builds a prose FRAGMENT with typed
+ * refs; the plural read as "the instruction file", which is what
+ * {@link instructionFile} builds. Removed one major AFTER the one that introduces it.
+ */
+export declare const instructions: typeof prose;
+/**
+ * Define a subagent — and the ROOT of the subagent vocabulary.
+ *
+ * Everything that only makes sense for subagents hangs off this one symbol:
+ * `experimental_agent.result()` (the outcome contract), `.railway()` / `.delegate()`
+ * (the flat orchestrator), and `.pipe()` / `.start()` / `.andThen()` / `.pipeStep()` /
+ * `.needs()` (the typed pipeline). Same chokepoint as `experimental_skill.input()`.
+ *
+ * WHY a root and not a prefix on each name: `railway()` and `delegate()` are
+ * meaningless without a subagent, yet they shipped under STABLE names while the
+ * builder they depend on is experimental — a stable name resting on an unstable
+ * one. Prefixing each would carry the warning but multiply the vocabulary; a
+ * namespace OBJECT was rejected for the reason the `vigiles/experimental` subpath
+ * was retired in #169 — it marks the import line, out of view by the time anyone
+ * reads the call. A member reached through the marked root cannot be destructured
+ * free of its warning without renaming it, so the warning rides every call site.
+ *
+ * The rule this establishes: ONE experimental root per feature, everything else a
+ * member of it, TYPES excluded (a type annotation is not a call site).
+ *
+ * @experimental
+ */
+export declare const experimental_agent: typeof agentSpec & {
+    result: typeof result;
+    delegate: typeof delegate;
+    railway: typeof railway;
+    needs: typeof experimental_needs;
+    pipeStep: typeof experimental_pipeStep;
+    start: typeof experimental_start;
+    andThen: typeof experimental_andThen;
+    pipe: typeof experimental_pipe;
+};
+/**
+ * @deprecated Renamed to {@link experimental_agent} — the shape is not settled.
+ * Removed one major AFTER the one that introduces it.
+ *
+ * @experimental
+ * vigiles:experimental-name-ok this IS the old spelling — prefixing a deprecated
+ * alias would defeat the alias, which exists precisely so code written against
+ * the unprefixed name keeps compiling for one major. It carries the tag because
+ * it is the same function, and the tag is what the deprecation notice points at.
+ */
+export declare const agent: typeof agentSpec & {
+    result: typeof result;
+    delegate: typeof delegate;
+    railway: typeof railway;
+    needs: typeof experimental_needs;
+    pipeStep: typeof experimental_pipeStep;
+    start: typeof experimental_start;
+    andThen: typeof experimental_andThen;
+    pipe: typeof experimental_pipe;
+};
 export {};
 //# sourceMappingURL=spec.d.ts.map