vigiles 5.2.0 → 7.0.0

package/dist/core/spec.d.ts

@@ -50,6 +50,42 @@ export type StrictLinterRule = [keyof KnownLinterRules] extends [never] ? Linter
  */
 export type StrictFile = [keyof KnownProjectFiles] extends [never] ? string : KnownProjectFiles[keyof KnownProjectFiles] & string;
 export type StrictCmd = [keyof KnownNpmScripts] extends [never] ? string : `npm run ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | `npm ${KnownNpmScripts[keyof KnownNpmScripts] & string}` | (string & {});
+/**
+ * A harness's tool vocabulary, split by the purity floor that admits it. The
+ * read-only/side-effecting split is harness-specific (it comes from the
+ * dialect's `builtinAgentTools` − `sideEffectingTools`), so the concrete unions
+ * are supplied by the adapter; core only describes the SHAPE.
+ *
+ * - `readOnly`: tools a `pure` unit may declare (observation only).
+ * - `bounded`: tools a `bounded` unit may declare — the read-only set PLUS the
+ *   decidable side-effecting tools (Write/Edit/NotebookEdit) AND `Bash` (its
+ *   command is decided at RUNTIME by the gate; the floor admits the tool). Bars
+ *   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()`.
+ */
+export interface ToolVocabulary {
+    /** Union of tool names allowed under `purity: "pure"`. */
+    readonly readOnly: string;
+    /** Union of tool names allowed under `purity: "bounded"`. */
+    readonly bounded: string;
+}
+/** The fully-open default vocabulary — no constraint at any purity level. */
+export interface OpenToolVocabulary extends ToolVocabulary {
+    readonly readOnly: string;
+    readonly bounded: string;
+}
+/**
+ * The tool names ALLOWED at a declared `purity`, given a vocabulary `V`:
+ * - `"pure"`  → only `V["readOnly"]`.
+ * - `"bounded"` → `V["bounded"]` (read-only ∪ decidable side-effecting ∪ `Bash`).
+ * - `"dangerously-unrestricted"` (or no purity) → `string` (anything).
+ *
+ * With the open default vocabulary every branch widens to `string`, so an
+ * 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. */
@@ -430,13 +466,27 @@ export interface SkillSpec {
      */
     readonly maxInlineCodeLines?: number;
 }
+/**
+ * The input to `skill()` — `SkillSpec` minus `_specType`, with `tools`
+ * constrained by the declared `purity` and vocabulary `V` (same mechanism as
+ * `AgentSpecInput`). The open default vocabulary leaves it unconstrained.
+ */
+export type SkillSpecInput<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = Omit<SkillSpec, "_specType" | "tools" | "purity"> & {
+    readonly purity?: P;
+    readonly tools?: readonly AllowedAt<P, V>[];
+};
 /**
  * Define a SKILL.md specification.
  *
  *   // skills/my-skill/SKILL.md.spec.ts
  *   export default skill({ name: "my-skill", description: "...", body: "..." });
+ *
+ * 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.
  */
-export declare function skill(spec: Omit<SkillSpec, "_specType">): SkillSpec;
+export declare function 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
@@ -507,6 +557,46 @@ export interface AgentSpec {
      */
     readonly purity?: AuthoredPurity;
 }
+/**
+ * The input to `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>[]`:
+ * - `purity: "pure"`   → `tools` may list only `V["readOnly"]` tools.
+ * - `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
+ * `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"> & {
+    readonly purity?: P;
+    readonly tools?: readonly AllowedAt<P, V>[];
+    /** The typed result contract — `result(ok, err)`. Its literal field shapes are
+     *  captured into the returned `TypedAgentSpec` so a typed `pipe` can check them. */
+    readonly output?: OutputContract<Ok, Err>;
+};
+declare const __outcome: unique symbol;
+/** Phantom carrier of an agent's success/error result shapes (type-level only). */
+export interface TypedOutcome<Ok extends Shape, Err extends Shape> {
+    readonly [__outcome]: {
+        readonly ok: Ok;
+        readonly err: Err;
+    };
+}
+/** An `AgentSpec` that REMEMBERS its `result()` ok/err shapes at the type level
+ *  (via a phantom field). Still an `AgentSpec`, so it flows everywhere one does.
+ *  The input to a typed `pipe` / `then`. */
+export type TypedAgentSpec<Ok extends Shape, Err extends Shape> = AgentSpec & TypedOutcome<Ok, Err>;
+/**
+ * Extract a typed agent's success (`result().ok`) SHAPE at the type level. The
+ * phantom `__outcome` symbol is module-private, so this is the exported reader
+ * the whole-harness registry uses: `OkOf<typeof registry["planner"]>` is the
+ * literal `ok` shape `planner` produces, the producer side of a cross-file
+ * `Handoff<>` check. A plain `AgentSpec` (no `result()` contract) carries no
+ * phantom, so `OkOf` widens to the erased `Shape` — a no-op handoff, additive.
+ */
+export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
 /**
  * Define a subagent specification (compiles to `agents/<name>.md`).
  *
@@ -521,21 +611,41 @@ export interface AgentSpec {
  *       "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."),
  *     },
  *   });
+ *
+ * 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.
+ *
+ * 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.
  */
-export declare function agent(spec: Omit<AgentSpec, "_specType">): AgentSpec;
+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>;
 /** The field types a result contract can declare (kept tiny + dependency-free). */
 export type OutputFieldType = "string" | "number" | "boolean" | "string[]";
+/** A field SHAPE — a record of field-name → field-type, kept in the TYPE so a
+ *  typed pipeline can cross-reference one agent's `ok` against the next agent's
+ *  `needs`. The erased runtime form is `Record<string, OutputFieldType>`. */
+export type Shape = Readonly<Record<string, OutputFieldType>>;
 /**
  * A subagent's typed result contract: the shape it must return on success
  * (`ok`) and on failure (`err`). Rich on both tracks — an error is structured
  * detail, not a bare pass/fail bit. Compiles into the worker's system prompt
  * (the `vigiles:ok` / `vigiles:err` block it must emit) and is the schema the
  * `parseAgentResult` parser + the `assertAgentOk/Err` test helpers validate.
+ *
+ * Generic over its `ok`/`err` field shapes so a typed value REMEMBERS them at
+ * the type level (the basis of typed composition — see `pipe`). The default
+ * type parameters widen to the historical erased `Shape`, so an `OutputContract`
+ * named with no arguments behaves exactly as before — backwards-compatible.
  */
-export interface OutputContract {
+export interface OutputContract<Ok extends Shape = Shape, Err extends Shape = Shape> {
     readonly _ref: "output";
-    readonly ok: Readonly<Record<string, OutputFieldType>>;
-    readonly err: Readonly<Record<string, OutputFieldType>>;
+    readonly ok: Ok;
+    readonly err: Err;
 }
 /**
  * Declare a subagent's success/error result contract.
@@ -547,8 +657,14 @@ export interface OutputContract {
  *
  * (Distinct from a skill's `result:` postcondition gate — this types a
  * subagent's *return value*, the success/error tracks of the railway.)
+ *
+ * The literal field shapes are PRESERVED in the return type (`const` inference),
+ * not erased to `Record<string, OutputFieldType>` — this is what lets `pipe`
+ * 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(ok: Record<string, OutputFieldType>, err: Record<string, OutputFieldType>): OutputContract;
+export 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";
@@ -556,9 +672,31 @@ export interface RailwayStep {
     readonly agent: string;
     /** Optional task hint passed to the worker. */
     readonly task?: string;
+    /**
+     * Optional input contract the step reads from its predecessor's `result().ok`.
+     * When present, the whole-harness registry (`generate-harness`) emits a
+     * per-edge `Handoff<>` assertion so a CROSS-FILE handoff mismatch (a missing
+     * field or wrong type vs the prior step's `ok`) is a `tsc` error naming the
+     * field. Absent `needs` = no handoff check (today's behavior, the string-path
+     * backstop). Built by `needs(...)`, the same builder a typed `pipeStep` uses.
+     */
+    readonly needs?: Shape;
 }
-/** Build a railway step that dispatches `agent` (optionally with a task hint). */
-export declare function delegate(agent: string, task?: string): RailwayStep;
+/**
+ * Build a railway step that dispatches `agent`.
+ *
+ *   delegate("planner")                                  // no task, no handoff
+ *   delegate("implementer", "implement the plan")        // task hint only
+ *   delegate("reviewer", undefined, needs({ diff: "string" }))  // + handoff check
+ *
+ * The optional 3rd argument carries the step's input `needs` (built by
+ * `needs(...)`). When present, the whole-harness registry asserts that the
+ * PREVIOUS success-track step's `result().ok` SUPPLIES it — a cross-file
+ * 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;
 /**
  * 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`
@@ -589,6 +727,150 @@ export interface Railway {
  *   })
  */
 export 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
+ * cross-reference it. Independent of `result()` (the output) — an agent both
+ * `needs` an input shape and produces an `ok`/`err` output shape.
+ */
+export type NeedsContract<N extends Shape> = N;
+/**
+ * Declare the input fields a step reads from its predecessor's success payload.
+ * Pass it as `needs:` on a typed pipeline step. `needs({})` (the default) is a
+ * step with no upstream requirement — valid as the FIRST step of a pipeline.
+ *
+ *   needs({ plan: "string", files: "string[]" })
+ */
+export declare function 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
+ * prior step's `ok` shape supplies this step's `needs`.
+ */
+export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape> {
+    readonly _step: "typed-delegate";
+    readonly agent: TypedAgentSpec<Ok, Err>;
+    readonly needs: Needs;
+}
+/**
+ * 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
+ * second is the `needs(...)` input contract.
+ *
+ *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ */
+export declare function 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
+ * descriptive error object naming the offending field (`__missing` /
+ * `__mismatch`), which surfaces at the mismatched call. Shallow (a per-field
+ * mapped type, not a recursion) to avoid TS2589.
+ */
+export type Supplies<Producer extends Shape, Consumer extends Shape> = {
+    [K in keyof Consumer]: K extends keyof Producer ? Producer[K] extends Consumer[K] ? true : {
+        readonly __mismatch: K;
+        readonly expected: Consumer[K];
+        readonly got: Producer[K];
+    } : {
+        readonly __missing: K;
+        readonly required: Consumer[K];
+    };
+}[keyof Consumer];
+/**
+ * Per-edge CROSS-FILE handoff check — the registry-scale form of `Supplies<>`,
+ * mirroring `KnownAgentName` (the dangling-delegate per-edge check). `Producer`
+ * is the prior success-track step's `result().ok` shape (read off the registry
+ * via `OkOf`); `Consumer` is THIS step's `needs(...)` input contract. Collapses
+ * to `true` when the producer supplies every field the consumer needs (matching
+ * types), else to a descriptive error object naming the offending field
+ * (`__handoff_error` wrapping `Supplies`'s `__missing`/`__mismatch`), so
+ * assigning `true` to it is a `tsc` error at edit time. Shallow (one wrap over
+ * the per-field `Supplies` mapped type, no recursion); the generator emits one
+ * assertion per consecutive step pair (O(N)), keeping clear of TS2589.
+ */
+export type Handoff<Producer extends Shape, Consumer extends Shape> = Supplies<Producer, Consumer> extends true ? true : {
+    readonly __handoff_error: Supplies<Producer, Consumer>;
+};
+/** A typed pipeline value — carries the LAST step's `ok` and the UNION of every
+ *  step's `err` (any step can short-circuit to the error track). */
+export interface Pipeline<Ok extends Shape, Err extends Shape> {
+    readonly _specType: "pipeline";
+    /** Ordered agent names — the resolved compose order. */
+    readonly agents: readonly string[];
+    /** The final step's success shape. */
+    readonly ok: Ok;
+    /** The union of every step's error shape. */
+    readonly err: Err;
+    /** The underlying string-path railway, for `compileRailway` reuse. */
+    readonly railway: Railway;
+}
+/**
+ * Begin a typed pipeline from its first step. The first step has no upstream, so
+ * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
+ * carrying that step's `ok`/`err` forward.
+ */
+export declare function 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
+ * collapses to a `__HANDOFF_ERROR` object and `tsc` rejects the call, naming the
+ * missing/mismatched field. Carries the new step's `ok` forward and accumulates
+ * the error track. Shallow per-call check — no recursive chain type.
+ *
+ * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
+ * 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.
+ */
+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> : {
+    readonly __HANDOFF_ERROR: Supplies<PriorOk, Needs>;
+}): Pipeline<Ok, PriorErr | Err>;
+/**
+ * Compose a typed pipeline in one call — the ergonomic form of
+ * `andThen(andThen(start(a), b), c)`. Each adjacent handoff is checked
+ * left-to-right: the FIRST step is the producer, the rest are
+ * `pipeStep(agent, needs(...))` consumers, and the compiler rejects the whole
+ * expression if ANY handoff's producer `ok` does not supply the consumer's
+ * `needs` (variadic chains hit TS2589 quickly, so `pipe` is a fixed set of
+ * overloads over the shallow `start`/`andThen` fold rather than a recursive
+ * variadic type — keep chains to a handful of steps; for longer ones, fold
+ * `andThen` explicitly).
+ *
+ *   pipe(
+ *     planner,                                              // produces ok
+ *     pipeStep(implementer, needs({ plan: "string", files: "string[]" })),
+ *     pipeStep(reviewer, needs({ diff: "string" })),
+ *   ) // ← won't compile if a handoff doesn't line up
+ */
+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> : {
+    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> : {
+    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> : {
+    readonly __HANDOFF_ERROR: Supplies<A, BN>;
+}, c: Supplies<B, CN> extends true ? PipeStep<CN, C, CE> : {
+    readonly __HANDOFF_ERROR: Supplies<B, CN>;
+}, d: Supplies<C, DN> extends true ? PipeStep<DN, D, DE> : {
+    readonly __HANDOFF_ERROR: Supplies<C, DN>;
+}): Pipeline<D, AE | BE | CE | DE>;
+/**
+ * Per-edge dangling-`delegate` check. `Target` is a delegate target NAME (a
+ * string literal the generator reads off a `railway()` value); `Names` is the
+ * literal union of every agent name in the harness (emitted by the generator).
+ * Collapses to `true` when the target resolves, else to a descriptive error
+ * object naming the dangling target + the railway it came from — so assigning
+ * `true` to it is a `tsc` error at edit time. Shallow (one conditional, no
+ * recursion); the generator emits one assertion per edge (O(N)).
+ */
+export type KnownAgentName<Target extends string, Names extends string, From extends string = string> = [Target] extends [Names] ? true : {
+    readonly __dangling_delegate: Target;
+    readonly from: From;
+};
 /** Derive the spec filename from an output filename. */
 export type SpecPath<Output extends `${string}.md`> = `${Output}.spec.ts`;
 /** Extract the output filename from a spec filename. */

package/dist/core/spec.js

@@ -30,6 +30,11 @@ 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.defineConfig = defineConfig;
 // ---------------------------------------------------------------------------
 // Builder functions
@@ -202,6 +207,11 @@ function step(instr, opts = {}) {
  *
  *   // skills/my-skill/SKILL.md.spec.ts
  *   export default skill({ name: "my-skill", description: "...", body: "..." });
+ *
+ * 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.
  */
 function skill(spec) {
     return { _specType: "skill", ...spec };
@@ -220,6 +230,17 @@ function skill(spec) {
  *       "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."),
  *     },
  *   });
+ *
+ * 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.
+ *
+ * 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.
  */
 function agent(spec) {
     return { _specType: "agent", ...spec };
@@ -234,15 +255,35 @@ function agent(spec) {
  *
  * (Distinct from a skill's `result:` postcondition gate — this types a
  * subagent's *return value*, the success/error tracks of the railway.)
+ *
+ * The literal field shapes are PRESERVED in the return type (`const` inference),
+ * not erased to `Record<string, OutputFieldType>` — this is what lets `pipe`
+ * 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.
  */
 function result(ok, err) {
     return { _ref: "output", ok, err };
 }
-/** Build a railway step that dispatches `agent` (optionally with a task hint). */
-function delegate(agent, task) {
-    return task === undefined
+/**
+ * Build a railway step that dispatches `agent`.
+ *
+ *   delegate("planner")                                  // no task, no handoff
+ *   delegate("implementer", "implement the plan")        // task hint only
+ *   delegate("reviewer", undefined, needs({ diff: "string" }))  // + handoff check
+ *
+ * The optional 3rd argument carries the step's input `needs` (built by
+ * `needs(...)`). When present, the whole-harness registry asserts that the
+ * PREVIOUS success-track step's `result().ok` SUPPLIES it — a cross-file
+ * 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.
+ */
+function delegate(agent, task, needsContract) {
+    const base = task === undefined
         ? { _step: "delegate", agent }
         : { _step: "delegate", agent, task };
+    return needsContract === undefined ? base : { ...base, needs: needsContract };
 }
 /**
  * Compose flat subagents into a railway (compiles to an orchestrator command).
@@ -257,6 +298,80 @@ function delegate(agent, task) {
 function railway(spec) {
     return { _specType: "railway", ...spec };
 }
+/**
+ * Declare the input fields a step reads from its predecessor's success payload.
+ * Pass it as `needs:` on a typed pipeline step. `needs({})` (the default) is a
+ * step with no upstream requirement — valid as the FIRST step of a pipeline.
+ *
+ *   needs({ plan: "string", files: "string[]" })
+ */
+function needs(shape) {
+    return shape;
+}
+/**
+ * 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
+ * second is the `needs(...)` input contract.
+ *
+ *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ */
+function pipeStep(a, needsContract = {}) {
+    return { _step: "typed-delegate", agent: a, needs: needsContract };
+}
+/**
+ * Begin a typed pipeline from its first step. The first step has no upstream, so
+ * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
+ * carrying that step's `ok`/`err` forward.
+ */
+function start(first) {
+    const step = "_step" in first ? first : pipeStep(first, {});
+    const out = step.agent.output;
+    return {
+        _specType: "pipeline",
+        agents: [step.agent.name],
+        ok: (out ? out.ok : {}),
+        err: (out ? out.err : {}),
+        railway: railway({
+            name: step.agent.name,
+            steps: [delegate(step.agent.name)],
+        }),
+    };
+}
+/**
+ * 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
+ * collapses to a `__HANDOFF_ERROR` object and `tsc` rejects the call, naming the
+ * missing/mismatched field. Carries the new step's `ok` forward and accumulates
+ * the error track. Shallow per-call check — no recursive chain type.
+ *
+ * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
+ * 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.
+ */
+function andThen(prior, next) {
+    const real = next;
+    const out = real.agent.output;
+    const rw = railway({
+        name: prior.railway.name,
+        steps: [...prior.railway.steps, delegate(real.agent.name)],
+    });
+    return {
+        _specType: "pipeline",
+        agents: [...prior.agents, real.agent.name],
+        ok: (out ? out.ok : {}),
+        err: (out ? out.err : {}),
+        railway: rw,
+    };
+}
+function 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);
+    for (const s of rest) {
+        pipeline = andThen(pipeline, s);
+    }
+    return pipeline;
+}
 function defineConfig(config) {
     return config;
 }

package/dist/core/types.d.ts

@@ -221,6 +221,14 @@ export interface VigilesConfig {
     }>;
     /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
     orphans?: OrphansConfig;
+    /**
+     * Glob patterns of instruction/skill files to EXCLUDE from `lint` discovery
+     * (tsconfig-style, relative to the repo root). Use it for vendored or
+     * benchmark fixtures the repo's own lint shouldn't police — e.g.
+     * `["bench/**"]` so a third-party `CLAUDE.md` injected verbatim as a benchmark
+     * arm isn't held to `require-spec`. `node_modules`/`dist` are always excluded.
+     */
+    exclude?: readonly string[];
     /**
      * The harness(es) this repo targets — selects the compile dialect / skill
      * frontmatter profile / instruction-file shape, instead of sniffing the cwd.

package/dist/dialect-drift.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The Claude Code version `ACKNOWLEDGED_TOOL_INPUT_TYPES` + the dialect were last
+ * validated against. SINGLE SOURCE OF TRUTH for the pin: CI installs
+ * `@anthropic-ai/claude-code@<this>` (grepped from this line) in every job that
+ * drives the real binary, so the dialect-drift alarm fires only on a DELIBERATE
+ * bump — not on every unpinned CC release landing on an unrelated PR — and the
+ * real-`claude` harness/eval tests stay reproducible. Bump this together with
+ * `ACKNOWLEDGED_TOOL_INPUT_TYPES` (the gated test cross-checks them).
+ */
+export declare const VALIDATED_CC_VERSION = "2.1.187";
+/**
+ * The `<X>Input` interface names we've ACKNOWLEDGED from `sdk-tools.d.ts` (Claude
+ * Code 2.1.187). The drift test fails when the installed set differs — a loud nudge
+ * to re-check `claudeCodeDialect` (and update this set) when CC adds/removes a tool.
+ * NOT a redistribution of their file: a list of bare identifiers (facts), authored here.
+ *
+ * 2.1.187 added the agent-PLATFORM surface (cron/scheduling/worktrees/web-app):
+ * Artifact, Cron{Create,Delete,List}, Enter/ExitWorktree, EnterPlanMode, Monitor,
+ * Projects, PushNotification, REPL, ReadMcpResourceDir, RemoteTrigger,
+ * ScheduleWakeup, ShowOnboardingRolePicker, Task{Create,Get,List,Update}, Workflow;
+ * and removed Config. These are HOST/platform tools, NOT subagent-grantable, so
+ * `claudeCodeDialect.builtinAgentTools` (the `tools:` frontmatter catalog) is
+ * intentionally unchanged — they're acknowledged here as facts, nothing more.
+ */
+export declare const ACKNOWLEDGED_TOOL_INPUT_TYPES: readonly string[];
+/** Parse `export interface <X>Input {` names from sdk-tools.d.ts → sorted [<X>]. Pure. */
+export declare function parseToolInputTypes(dts: string): string[];
+/**
+ * Locate a READABLE JavaScript bundle inside the installed CC package, or null.
+ * Older CC shipped `cli.js` — a readable JS bundle whose hook-event names appear as
+ * string literals, greppable by `eventsMissingFromBundle`. CC ≥ ~2.1.18x switched to
+ * a NATIVE-BINARY distribution (`bin/claude.exe` copied from a platform
+ * `optionalDependencies` package) with NO readable JS bundle, so there is nothing to
+ * text-scan. Returns the bundle path when present, else null — callers then SKIP the
+ * event-drift check loudly rather than crash on a missing `cli.js`.
+ */
+export declare function findClaudeCodeBundle(pkg: string): string | null;
+/** Which of `events` do NOT appear as a whole-word literal in the bundle. Pure. */
+export declare function eventsMissingFromBundle(bundle: string, events: readonly string[]): string[];
+/**
+ * Locate the user's installed `@anthropic-ai/claude-code` package dir, or null.
+ * Tries the global npm root, then the `claude` binary's real path. Read-only —
+ * we only read files the user already installed under their own CC license.
+ */
+export declare function findClaudeCodePackage(): string | null;
+/** A runtime drift report: how the INSTALLED CC's tool surface compares to ours. */
+export interface DialectDriftReport {
+    readonly installedVersion: string;
+    readonly validatedVersion: string;
+    /** Tool-input types present in the install but not in ACKNOWLEDGED (CC added). */
+    readonly newToolTypes: string[];
+    /** Acknowledged types absent from the install (CC removed/renamed). */
+    readonly removedToolTypes: string[];
+}
+/**
+ * Best-effort, read-local drift check for `scan` (and other runtime callers). Reads
+ * only the small `sdk-tools.d.ts` (fast — no `cli.js` bundle scan; events are the
+ * CI test's job). Returns null when CC isn't installed or anything is unreadable —
+ * NEVER throws, so it can't break the command. ToS-clean: reads the user's own
+ * install, ships nothing.
+ */
+export declare function checkDialectDrift(): DialectDriftReport | null;
+/** A one-line freshness warning if the dialect drifted from the install, else null. */
+export declare function formatDialectDrift(r: DialectDriftReport | null): string | null;
+//# sourceMappingURL=dialect-drift.d.ts.map