vigiles 19.0.1 → 21.0.0

package/dist/core/spec.js

@@ -10,7 +10,7 @@
  *   guidance() — prose only, no mechanical enforcement
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.experimental_skill = exports.BUILTIN_LINTERS = void 0;
+exports.agent = exports.experimental_agent = exports.instructions = exports.claude = exports.experimental_skill = exports.BUILTIN_LINTERS = void 0;
 exports.enforce = enforce;
 exports.guidance = guidance;
 exports.guard = guard;
@@ -20,23 +20,15 @@ exports.symbol = symbol;
 exports.ref = ref;
 exports.dir = dir;
 exports.glob = glob;
-exports.instructions = instructions;
+exports.prose = prose;
 exports.experimental_effect = experimental_effect;
-exports.claude = claude;
+exports.instructionFile = instructionFile;
 exports.project = project;
-exports.agent = agent;
-exports.result = result;
-exports.delegate = delegate;
-exports.railway = railway;
-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
 // ---------------------------------------------------------------------------
+const skill_normalize_js_1 = require("./skill-normalize.js");
 /** Linters and policy catalogs vigiles can cross-reference. */
 /**
  * The built-in linter / policy catalogs vigiles cross-references — the SINGLE
@@ -156,13 +148,13 @@ function glob(pattern) {
 /**
  * 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.
  *   `
  */
-function instructions(strings, ...values) {
+function prose(strings, ...values) {
     const result = [];
     for (let i = 0; i < strings.length; i++) {
         if (strings[i])
@@ -176,7 +168,7 @@ function instructions(strings, ...values) {
  * 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:
@@ -206,9 +198,9 @@ function experimental_effect(strings, ...values) {
  * Define a CLAUDE.md specification.
  *
  *   // CLAUDE.md.spec.ts
- *   export default claude({ commands: {...}, rules: {...} });
+ *   export default instructionFile({ commands: {...}, rules: {...} });
  */
-function claude(spec) {
+function instructionFile(spec) {
     return { _specType: "claude", ...spec };
 }
 /**
@@ -262,7 +254,7 @@ function step(instr, opts = {}) {
  *   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.
  *
@@ -289,7 +281,11 @@ function step(instr, opts = {}) {
  * @experimental
  */
 function skillSpec(spec) {
-    return { _specType: "skill", ...spec };
+    // The deprecated `result:` is folded into `postcondition:` by the shared
+    // helper — see `skill-normalize.ts` for why it is shared rather than inlined
+    // here (short version: this builder is not the only public entrance, and the
+    // other one silently dropped the gate until a reviewer noticed).
+    return (0, skill_normalize_js_1.foldLegacyPostcondition)({ _specType: "skill", ...spec });
 }
 /**
  * @experimental
@@ -299,12 +295,12 @@ exports.experimental_skill = Object.assign(skillSpec, { input, step });
  * 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."),
  *     },
@@ -313,15 +309,21 @@ exports.experimental_skill = Object.assign(skillSpec, { input, step });
  * 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.
  */
-function agent(spec) {
+function agentSpec(spec) {
     return { _specType: "agent", ...spec };
 }
 /**
@@ -340,6 +342,7 @@ function agent(spec) {
  * 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 };
@@ -357,6 +360,7 @@ function result(ok, err) {
  * 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
@@ -373,6 +377,7 @@ function delegate(agent, task, needsContract) {
  *     onError: delegate("reporter"),
  *     recover: { step: delegate("fixer"), max: 2 },
  *   })
+ 
  */
 function railway(spec) {
     return { _specType: "railway", ...spec };
@@ -386,19 +391,21 @@ function railway(spec) {
  *
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
+ 
  */
 function experimental_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
+ * 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.
+ 
  */
 function experimental_pipeStep(a, needsContract = {}) {
     return { _step: "typed-delegate", agent: a, needs: needsContract };
@@ -410,6 +417,7 @@ function experimental_pipeStep(a, needsContract = {}) {
  *
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
+ 
  */
 function experimental_start(first) {
     const step = "_step" in first
@@ -440,6 +448,7 @@ function experimental_start(first) {
  *
  * @experimental Experimental typed-composition surface — NOT part of the frozen
  * public API (pre-1.0); may change without a major bump.
+ 
  */
 function experimental_andThen(prior, next) {
     const real = next;
@@ -468,4 +477,79 @@ function experimental_pipe(first, ...rest) {
 function defineConfig(config) {
     return config;
 }
+// ─── ОКНО АЛИАСА (один мажор) ──────────────────────────────────────────────────
+// Старые имена остаются рабочими ровно один мажорный релиз, помеченные
+// `@deprecated`, и убираются в следующем.
+//
+// 🔴 ПОЧЕМУ ЭТО НЕ ВЕЖЛИВОСТЬ, А НЕОБХОДИМОСТЬ, замерено 2026-08-21: предыдущее
+// переименование ушло БЕЗ окна — 18.1.1 экспортировал только старые имена,
+// 19.0.0 только новые, пересечения ноль. У потребителя (репа знаний, 12
+// скомпилированных хуков) откат контейнера вернул старый `node_modules` под
+// новые исходники, `PreToolUse` перестал загружаться, а не загрузившийся
+// PreToolUse отбивает ЛЮБУЮ Bash-команду — включая ту, которой это чинится.
+// Репа встала колом на час. Одно окно в один мажор делает этот отказ
+// невыразимым: любая пара (лок, исходники) в пределах мажора совместима.
+//
+// 🔴 «ОДИН МАЖОР» СЧИТАЕТСЯ ОТ ТОГО, КОТОРЫЙ АЛИАСЫ ВВОДИТ, а не до него.
+// Мажор, выпускающий этот PR, — ПЕРВЫЙ, где старые и новые имена сосуществуют;
+// именно он и есть обещанное окно. Убирать алиасы можно в СЛЕДУЮЩЕМ за ним.
+// Формулировка «Removed next major» была двусмысленной ровно здесь (её так и
+// прочитал ревьюер: как «удалить в том же релизе, который их вводит»), и по
+// такому расписанию окна не существовало бы вовсе — то есть отказ выше
+// воспроизвёлся бы дословно, при живом абзаце, который его запрещает.
+/**
+ * @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.
+ */
+exports.claude = 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.
+ */
+exports.instructions = 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
+ */
+exports.experimental_agent = Object.assign(agentSpec, {
+    result,
+    delegate,
+    railway,
+    needs: experimental_needs,
+    pipeStep: experimental_pipeStep,
+    start: experimental_start,
+    andThen: experimental_andThen,
+    pipe: 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.
+ */
+exports.agent = exports.experimental_agent;
 //# sourceMappingURL=spec.js.map

package/dist/eval-surface.d.ts

@@ -13,9 +13,14 @@
  * The import path warns ONCE, at the top of the file. The name warns EVERY time,
  * at the call site. Reading `await judged(trace, "did it refuse?")` on line 140,
  * the import line is long out of view — `await paid_judged(...)` still says what
- * it costs. This is not a new idiom in this package: `vigiles/experimental`
- * already pairs a quarantined subpath with an `experimental_` name prefix for
- * exactly this reason. The same device, applied to a second axis.
+ * it costs. This is not a new idiom in this package: the `experimental_` prefix
+ * says the same kind of thing on a second axis, at the same place.
+ *
+ * That comparison used to read "`vigiles/experimental` already pairs a
+ * quarantined subpath WITH a name prefix". The subpath was deleted 2026-08-21
+ * and the prefix kept, on the argument this paragraph makes: of the two, only
+ * the name is present where the reader is. Which is also why THIS surface has
+ * no `vigiles/paid` subpath and never needed one.
  *
  * ⚠️ **The prefix slightly OVERSTATES the cost, and that is a deliberate trade
  * rather than an oversight.** `paid_judged` takes an injectable judge:

package/dist/eval-surface.js

@@ -14,9 +14,14 @@
  * The import path warns ONCE, at the top of the file. The name warns EVERY time,
  * at the call site. Reading `await judged(trace, "did it refuse?")` on line 140,
  * the import line is long out of view — `await paid_judged(...)` still says what
- * it costs. This is not a new idiom in this package: `vigiles/experimental`
- * already pairs a quarantined subpath with an `experimental_` name prefix for
- * exactly this reason. The same device, applied to a second axis.
+ * it costs. This is not a new idiom in this package: the `experimental_` prefix
+ * says the same kind of thing on a second axis, at the same place.
+ *
+ * That comparison used to read "`vigiles/experimental` already pairs a
+ * quarantined subpath WITH a name prefix". The subpath was deleted 2026-08-21
+ * and the prefix kept, on the argument this paragraph makes: of the two, only
+ * the name is present where the reader is. Which is also why THIS surface has
+ * no `vigiles/paid` subpath and never needed one.
  *
  * ⚠️ **The prefix slightly OVERSTATES the cost, and that is a deliberate trade
  * rather than an oversight.** `paid_judged` takes an injectable judge:

package/dist/harness-assert.js

@@ -176,7 +176,7 @@ function assertHookAllowed(r) {
  * in-process rather than loaded from disk has no file to name, so nothing is
  * recorded and nothing is invented:
  *
- *     const h = defineHook({…}); assertHookDenies(h, e);  → surfacesRecorded() === []
+ *     const h = experimental_defineHook({…}); assertHookDenies(h, e);  → surfacesRecorded() === []
  *
  * …and a direct `runHookProgram(hook, event)` call (the pure evaluator, public
  * via `vigiles/hook`) records nothing either, for the reason above. Both cost a

package/dist/hook.d.ts

@@ -11,15 +11,15 @@
  *
  * The roles, each with its own output type so a category mistake is a `tsc`
  * error, not a silent no-op:
- *   - `defineHook` / `defineFileGate` — a **gate** returns a `Decision`
+ *   - `experimental_defineHook` / `experimental_defineFileGate` — a **gate** returns a `Decision`
  *     (`allow`/`deny`/`ask`); `deny` is the only thing that blocks.
- *   - `definePromptGate` — a **prompt gate** (UserPromptSubmit) sees the prompt
+ *   - `experimental_definePromptGate` — a **prompt gate** (UserPromptSubmit) sees the prompt
  *     TEXT and may `deny` to block it (a security filter).
- *   - `defineStopGate` — a **stop gate** (Stop/SubagentStop) may `deny` to keep
+ *   - `experimental_defineStopGate` — a **stop gate** (Stop/SubagentStop) may `deny` to keep
  *     the agent going (gate-until-tests-pass).
- *   - `defineInject` — an **inject** returns an `Injection` (context text); it
+ *   - `experimental_defineInject` — an **inject** returns an `Injection` (context text); it
  *     has no `deny`, so "block on a SessionStart hook" won't compile.
- *   - `defineReact` — a **react** (PostToolUse) returns a `Reaction`; it sees the
+ *   - `experimental_defineReact` — a **react** (PostToolUse) returns a `Reaction`; it sees the
  *     tool RESPONSE, its `run(cmd)` is effect-classified at construction, and it
  *     can't block (the tool already ran).
  *
@@ -45,7 +45,7 @@
  * tool calls. A gate is a strong default, never an unbypassable wall. See
  * `docs/compiled-hooks.md`.
  */
-export { defineHook as experimental_defineHook, defineFileGate as experimental_defineFileGate, definePromptGate as experimental_definePromptGate, defineStopGate as experimental_defineStopGate, tool, tools, allow, deny, ask, commandView, pathView, gateAction, hookMode, defineInject as experimental_defineInject, inject, defineReact as experimental_defineReact, run, notice, nothing, responseView, decideProgram, decideFileGate, decidePromptGate, decideStopGate, runInject, runReact, runHookProgram, decisionExitCode, dispatchKind, hookRouting, hookNeeds, injectionOf, outcomeWrites, matchesTool, invalidToolPatterns, compileHookProgram, checkHookImports, stampHook, verifyHookStamp, HookCompileError, } from "./core/hook-program.js";
+export { experimental_defineHook, experimental_defineFileGate, experimental_definePromptGate, experimental_defineStopGate, tool, tools, allow, deny, ask, commandView, pathView, gateAction, hookMode, experimental_defineInject, inject, experimental_defineReact, run, notice, nothing, responseView, decideProgram, decideFileGate, decidePromptGate, decideStopGate, runInject, runReact, runHookProgram, decisionExitCode, dispatchKind, hookRouting, hookNeeds, injectionOf, outcomeWrites, matchesTool, invalidToolPatterns, compileHookProgram, checkHookImports, stampHook, verifyHookStamp, HookCompileError, } from "./core/hook-program.js";
 export type { Decision, HookMode, GateAction, CommandView, PathView, ResponseView, BashToolEvent, FileToolEvent, PromptEvent, StopEvent, ReactEvent, SessionEvent, HookProgram, FileGateHook, PromptGateHook, StopGateHook, InjectHook, ReactHook, AnyHook, DispatchKind, Injection, Reaction, RunReaction, CompiledHookProgram, CompileHookOptions, RawHookEvent, HookProgramOutcome, } from "./core/hook-program.js";
 export { provide, dangerously, defineProvider, provider, } from "./core/hook-providers.js";
 export { state, record, stateFact, isValidStateKey, isStateNeed, isStateWrite, admissibleWrites, durationSeconds, HookStateError, } from "./core/hook-state.js";

package/dist/hook.js

@@ -15,15 +15,15 @@ exports.leafCommandsNormalized = exports.HookStateError = exports.durationSecond
  *
  * The roles, each with its own output type so a category mistake is a `tsc`
  * error, not a silent no-op:
- *   - `defineHook` / `defineFileGate` — a **gate** returns a `Decision`
+ *   - `experimental_defineHook` / `experimental_defineFileGate` — a **gate** returns a `Decision`
  *     (`allow`/`deny`/`ask`); `deny` is the only thing that blocks.
- *   - `definePromptGate` — a **prompt gate** (UserPromptSubmit) sees the prompt
+ *   - `experimental_definePromptGate` — a **prompt gate** (UserPromptSubmit) sees the prompt
  *     TEXT and may `deny` to block it (a security filter).
- *   - `defineStopGate` — a **stop gate** (Stop/SubagentStop) may `deny` to keep
+ *   - `experimental_defineStopGate` — a **stop gate** (Stop/SubagentStop) may `deny` to keep
  *     the agent going (gate-until-tests-pass).
- *   - `defineInject` — an **inject** returns an `Injection` (context text); it
+ *   - `experimental_defineInject` — an **inject** returns an `Injection` (context text); it
  *     has no `deny`, so "block on a SessionStart hook" won't compile.
- *   - `defineReact` — a **react** (PostToolUse) returns a `Reaction`; it sees the
+ *   - `experimental_defineReact` — a **react** (PostToolUse) returns a `Reaction`; it sees the
  *     tool RESPONSE, its `run(cmd)` is effect-classified at construction, and it
  *     can't block (the tool already ran).
  *
@@ -57,12 +57,23 @@ var hook_program_js_1 = require("./core/hook-program.js");
 // entry points makes the marking structural for the whole vocabulary. A
 // per-name prefix could not guarantee that; a chokepoint can.
 //
-// Import them aliased, so the word crosses the package boundary exactly once:
-//   import { experimental_defineInject as defineInject, state } from "vigiles/hook";
-Object.defineProperty(exports, "experimental_defineHook", { enumerable: true, get: function () { return hook_program_js_1.defineHook; } });
-Object.defineProperty(exports, "experimental_defineFileGate", { enumerable: true, get: function () { return hook_program_js_1.defineFileGate; } });
-Object.defineProperty(exports, "experimental_definePromptGate", { enumerable: true, get: function () { return hook_program_js_1.definePromptGate; } });
-Object.defineProperty(exports, "experimental_defineStopGate", { enumerable: true, get: function () { return hook_program_js_1.defineStopGate; } });
+// 🔴 DO NOT alias the prefix away at the import. This block used to advise
+// exactly that — "so the word crosses the package boundary exactly once" — and
+// the advice defeated the mechanism it was attached to. 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(...)`
+// and cannot tell it is provisional. A prefix that is stripped on import is a
+// subpath with extra steps; if the guarantee is only boundary-deep, the honest
+// shape is a quarantined subpath, not a name nobody sees. We chose the name,
+// and then deleted the subpath (`vigiles/experimental`, gone 2026-08-21) so
+// there is only the one mechanism left to keep honest.
+// so the name has to be there. The declarations carry it too — there is one
+// spelling of each symbol now, and `local/experimental-name` no longer needs
+// to reason about re-export aliasing to know what crosses the boundary.
+Object.defineProperty(exports, "experimental_defineHook", { enumerable: true, get: function () { return hook_program_js_1.experimental_defineHook; } });
+Object.defineProperty(exports, "experimental_defineFileGate", { enumerable: true, get: function () { return hook_program_js_1.experimental_defineFileGate; } });
+Object.defineProperty(exports, "experimental_definePromptGate", { enumerable: true, get: function () { return hook_program_js_1.experimental_definePromptGate; } });
+Object.defineProperty(exports, "experimental_defineStopGate", { enumerable: true, get: function () { return hook_program_js_1.experimental_defineStopGate; } });
 Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return hook_program_js_1.tool; } });
 Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return hook_program_js_1.tools; } });
 Object.defineProperty(exports, "allow", { enumerable: true, get: function () { return hook_program_js_1.allow; } });
@@ -73,10 +84,10 @@ Object.defineProperty(exports, "pathView", { enumerable: true, get: function ()
 Object.defineProperty(exports, "gateAction", { enumerable: true, get: function () { return hook_program_js_1.gateAction; } });
 Object.defineProperty(exports, "hookMode", { enumerable: true, get: function () { return hook_program_js_1.hookMode; } });
 // inject vocabulary
-Object.defineProperty(exports, "experimental_defineInject", { enumerable: true, get: function () { return hook_program_js_1.defineInject; } });
+Object.defineProperty(exports, "experimental_defineInject", { enumerable: true, get: function () { return hook_program_js_1.experimental_defineInject; } });
 Object.defineProperty(exports, "inject", { enumerable: true, get: function () { return hook_program_js_1.inject; } });
 // react vocabulary
-Object.defineProperty(exports, "experimental_defineReact", { enumerable: true, get: function () { return hook_program_js_1.defineReact; } });
+Object.defineProperty(exports, "experimental_defineReact", { enumerable: true, get: function () { return hook_program_js_1.experimental_defineReact; } });
 Object.defineProperty(exports, "run", { enumerable: true, get: function () { return hook_program_js_1.run; } });
 Object.defineProperty(exports, "notice", { enumerable: true, get: function () { return hook_program_js_1.notice; } });
 Object.defineProperty(exports, "nothing", { enumerable: true, get: function () { return hook_program_js_1.nothing; } });

package/dist/linting.d.ts

@@ -1,14 +1,43 @@
 /**
  * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
- * files. Re-exports the spec builders/types + the public compile entry points
- * under one concern-named import. This is the canonical pillar-1 surface; the
- * spec builders are also at the package root (`vigiles`).
+ * files. The spec builders/types that describe a CLAUDE.md, a SKILL.md or an
+ * agent, plus the public compile entry points, under one concern-named import.
  *
  * Curated (named, not `export *`) so the internal compiler validators, hash
  * helpers, and the linter cross-reference ENGINE stay out of the public surface,
  * the api reports, and the docs site (the CLI imports those from the source).
+ *
+ * 🔴 THAT SENTENCE USED TO BE FALSE, and so did the one after it (fixed
+ * 2026-08-21). The file claimed to be curated while `export * from
+ * "./core/spec.js"` sat one line below it, and it claimed "the spec builders are
+ * also at the package root (`vigiles`)" — measured against `vigiles.api.md`: 191
+ * exports there and zero matches for `claude`, `agent`, `enforce` or `result`.
+ * The builders' second door is `vigiles/spec`, not the root. Both claims read as
+ * documentation of a decision and were descriptions of the opposite one; a
+ * header nobody re-reads is where an `export *` hides best.
+ *
+ * WHAT THE CURATION DROPS (28 symbols, measured — nothing in this repo imported
+ * any of them from here; every in-repo user takes them from `vigiles/spec`, and
+ * the one live consumer of this subpath in the docs takes `compileAgent`): the
+ * typed-COMPOSITION family — `experimental_pipe`/`_pipeStep`/`_start`/
+ * `_andThen`/`_needs`, `Pipeline`, `PipeStep`, `Supplies`, `Handoff`,
+ * `NeedsContract`, `OkOf`, `TypedAgentSpec`, `TypedOutcome`, `Shape`,
+ * `OutputFieldType` and the `result()` builder. Those verify HANDOFFS between
+ * workers; they compile to nothing and lint nothing, so they are not pillar 1.
+ *
+ * ⚠️ The cut is not a clean slice along that line, and pretending otherwise
+ * would strand a signature: the `result()` FUNCTION leaves, but the
+ * `OutputContract` TYPE stays, because `compileAgent`/`compileSkill` name it in
+ * their own types. A consumer who needs to BUILD one imports `vigiles/spec`.
  */
-export * from "./core/spec.js";
+export { instructionFile, prose, experimental_effect, enforce, guidance, guard, file, cmd, symbol, ref, dir, glob, project, experimental_skill, experimental_agent, 
+/** @deprecated Renamed to `instructionFile`. Removed one major AFTER the one that introduces it. */
+claude, 
+/** @deprecated Renamed to `prose`. Removed one major AFTER the one that introduces it. */
+instructions, 
+/** @deprecated Renamed to `experimental_agent`. Removed one major AFTER the one that introduces it. */
+agent, } from "./core/spec.js";
+export { BUILTIN_LINTERS, type BuiltinLinter, type LinterRule, type VigilesRef, type EnforcementRef, type KnownLinterRules, type KnownProjectFiles, type KnownNpmScripts, type KnownAgentName, type StrictLinterRule, type StrictFile, type StrictCmd, type ToolVocabulary, type OpenToolVocabulary, type AllowedAt, type AuthoredPurity, type EnforceRule, type GuidanceRule, type GuardRule, type Rule, type VerifiedPath, type VerifiedCmd, type VerifiedRef, type VerifiedDir, type VerifiedGlob, type FileRef, type CmdRef, type SkillRef, type SymbolRef, type DirRef, type GlobRef, type Ref, type EffectRegion, type InstructionFragment, type InstructionTarget, type ClaudeSpec, type Gate, type RoleGate, type ProjectRole, type SkillInput, type SkillStep, type SkillSpec, type SkillSpecInput, type AgentSpec, type AgentSpecInput, type Railway, type RailwayStep, type OutputContract, } from "./core/spec.js";
 export { compileClaude, compileSkill, compileAgent, compileRailway, CompileError, } from "./core/compile.js";
 export type { CompileClaudeOptions, CompileClaudeResult, CompileSkillResult, CompileAgentResult, CompileRailwayOptions, CompileRailwayResult, } from "./core/compile.js";
 //# sourceMappingURL=linting.d.ts.map

package/dist/linting.js

@@ -1,32 +1,72 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-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.compileRailway = exports.compileAgent = exports.compileSkill = exports.compileClaude = void 0;
 /**
  * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
- * files. Re-exports the spec builders/types + the public compile entry points
- * under one concern-named import. This is the canonical pillar-1 surface; the
- * spec builders are also at the package root (`vigiles`).
+ * files. The spec builders/types that describe a CLAUDE.md, a SKILL.md or an
+ * agent, plus the public compile entry points, under one concern-named import.
  *
  * Curated (named, not `export *`) so the internal compiler validators, hash
  * helpers, and the linter cross-reference ENGINE stay out of the public surface,
  * the api reports, and the docs site (the CLI imports those from the source).
+ *
+ * 🔴 THAT SENTENCE USED TO BE FALSE, and so did the one after it (fixed
+ * 2026-08-21). The file claimed to be curated while `export * from
+ * "./core/spec.js"` sat one line below it, and it claimed "the spec builders are
+ * also at the package root (`vigiles`)" — measured against `vigiles.api.md`: 191
+ * exports there and zero matches for `claude`, `agent`, `enforce` or `result`.
+ * The builders' second door is `vigiles/spec`, not the root. Both claims read as
+ * documentation of a decision and were descriptions of the opposite one; a
+ * header nobody re-reads is where an `export *` hides best.
+ *
+ * WHAT THE CURATION DROPS (28 symbols, measured — nothing in this repo imported
+ * any of them from here; every in-repo user takes them from `vigiles/spec`, and
+ * the one live consumer of this subpath in the docs takes `compileAgent`): the
+ * typed-COMPOSITION family — `experimental_pipe`/`_pipeStep`/`_start`/
+ * `_andThen`/`_needs`, `Pipeline`, `PipeStep`, `Supplies`, `Handoff`,
+ * `NeedsContract`, `OkOf`, `TypedAgentSpec`, `TypedOutcome`, `Shape`,
+ * `OutputFieldType` and the `result()` builder. Those verify HANDOFFS between
+ * workers; they compile to nothing and lint nothing, so they are not pillar 1.
+ *
+ * ⚠️ The cut is not a clean slice along that line, and pretending otherwise
+ * would strand a signature: the `result()` FUNCTION leaves, but the
+ * `OutputContract` TYPE stays, because `compileAgent`/`compileSkill` name it in
+ * their own types. A consumer who needs to BUILD one imports `vigiles/spec`.
  */
-// The spec authoring builders (claude/enforce/guidance/file/cmd/agent/skill/…).
-__exportStar(require("./core/spec.js"), exports);
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileRailway = exports.compileAgent = exports.compileSkill = exports.compileClaude = exports.BUILTIN_LINTERS = exports.agent = exports.instructions = exports.claude = exports.experimental_agent = exports.experimental_skill = exports.project = exports.glob = exports.dir = exports.ref = exports.symbol = exports.cmd = exports.file = exports.guard = exports.guidance = exports.enforce = exports.experimental_effect = exports.prose = exports.instructionFile = void 0;
+// --- the spec authoring builders: rules, refs, prose, and the three spec kinds ---
+var spec_js_1 = require("./core/spec.js");
+// instruction files
+Object.defineProperty(exports, "instructionFile", { enumerable: true, get: function () { return spec_js_1.instructionFile; } });
+Object.defineProperty(exports, "prose", { enumerable: true, get: function () { return spec_js_1.prose; } });
+Object.defineProperty(exports, "experimental_effect", { enumerable: true, get: function () { return spec_js_1.experimental_effect; } });
+// rules
+Object.defineProperty(exports, "enforce", { enumerable: true, get: function () { return spec_js_1.enforce; } });
+Object.defineProperty(exports, "guidance", { enumerable: true, get: function () { return spec_js_1.guidance; } });
+Object.defineProperty(exports, "guard", { enumerable: true, get: function () { return spec_js_1.guard; } });
+// verified references
+Object.defineProperty(exports, "file", { enumerable: true, get: function () { return spec_js_1.file; } });
+Object.defineProperty(exports, "cmd", { enumerable: true, get: function () { return spec_js_1.cmd; } });
+Object.defineProperty(exports, "symbol", { enumerable: true, get: function () { return spec_js_1.symbol; } });
+Object.defineProperty(exports, "ref", { enumerable: true, get: function () { return spec_js_1.ref; } });
+Object.defineProperty(exports, "dir", { enumerable: true, get: function () { return spec_js_1.dir; } });
+Object.defineProperty(exports, "glob", { enumerable: true, get: function () { return spec_js_1.glob; } });
+Object.defineProperty(exports, "project", { enumerable: true, get: function () { return spec_js_1.project; } });
+// the other two spec kinds + how a railway wires them
+Object.defineProperty(exports, "experimental_skill", { enumerable: true, get: function () { return spec_js_1.experimental_skill; } });
+// the subagent ROOT — `railway`/`delegate`/`result`/`pipe`… are its members
+Object.defineProperty(exports, "experimental_agent", { enumerable: true, get: function () { return spec_js_1.experimental_agent; } });
+// ─── ОКНО АЛИАСА (один мажор) — see core/spec.ts for why a window is not
+// politeness here. Kept on THIS door too: a consumer importing `claude` from
+// `vigiles/linting` never saw `vigiles/spec`, so the window over there does
+// not cover them.
+/** @deprecated Renamed to `instructionFile`. Removed one major AFTER the one that introduces it. */
+Object.defineProperty(exports, "claude", { enumerable: true, get: function () { return spec_js_1.claude; } });
+/** @deprecated Renamed to `prose`. Removed one major AFTER the one that introduces it. */
+Object.defineProperty(exports, "instructions", { enumerable: true, get: function () { return spec_js_1.instructions; } });
+/** @deprecated Renamed to `experimental_agent`. Removed one major AFTER the one that introduces it. */
+Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return spec_js_1.agent; } });
+var spec_js_2 = require("./core/spec.js");
+Object.defineProperty(exports, "BUILTIN_LINTERS", { enumerable: true, get: function () { return spec_js_2.BUILTIN_LINTERS; } });
 // Compile: only the public entry points + their option/result types.
 var compile_js_1 = require("./core/compile.js");
 Object.defineProperty(exports, "compileClaude", { enumerable: true, get: function () { return compile_js_1.compileClaude; } });

package/dist/load-hook.js

@@ -56,7 +56,7 @@ async function loadHook(file) {
     const program = mod.default?.default ?? mod.default;
     if (!program || typeof program !== "object") {
         throw new hook_program_js_1.HookCompileError(`${file} has no default-exported hook program ` +
-            `(use \`export default defineHook({…})\`).`);
+            `(use \`export default experimental_defineHook({…})\`).`);
     }
     // Remember WHERE it came from, so the assertion that later EVALUATES it can
     // attribute execution coverage without parsing anything. Remembering is not

package/dist/scaffold-test.js

@@ -151,7 +151,7 @@ function outcomeSection(input, contract) {
         ? `// TODO: assert the VALUES you expect (the shape is already validated above), e.g.:\n//   assert.ok(value.${firstField}, "expected a ${firstField}");`
         : "";
     return `import assert from "node:assert/strict";
-import { result } from "vigiles/spec";
+import { experimental_agent } from "vigiles/spec";\nconst { result } = experimental_agent;
 import { assertAgentOk } from "vigiles";
 
 // Reconstructed from ${input.name}'s ## Output contract (its compiled .md) — the
@@ -180,7 +180,7 @@ function fallbackSection(input) {
     return `import { runHarnessTest, assertToolUsed } from "vigiles";
 
 // ${input.name} has no result() contract, so its outcome can't be asserted
-// deterministically — add one (result() on its agent() spec) for a no-judge
+// deterministically — add one (result() on its experimental_agent() spec) for a no-judge
 // outcome test. For now, assert it reaches for the right tool.
 const r = await runHarnessTest({
   plugin: ".", // TODO: the plugin dir holding this subagent

package/dist/services-docker.js

@@ -9,7 +9,7 @@ exports.parseDockerPort = parseDockerPort;
 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`).
+ * tier (⚠️ EXPERIMENTAL / UNSTABLE — see src/services.ts; served from `vigiles`).
  *
  * This is the v0 backend the R3 build spec (research/r3-disposable-services.md)
  * scopes: `docker run` a throwaway service, wait for it to be ready, run its seed,
@@ -23,7 +23,7 @@ exports.experimental_makeDockerRuntime = experimental_makeDockerRuntime;
  * end-to-end integration test needs a live daemon (it skips when absent).
  *
  * @experimental
- * @module vigiles/experimental (docker backend)
+ * @module vigiles (docker backend)
  */
 const node_child_process_1 = require("node:child_process");
 const node_net_1 = require("node:net");

package/dist/services.d.ts

@@ -2,7 +2,7 @@
  * vigiles — R3 disposable-service tier (⚠️ EXPERIMENTAL / UNSTABLE).
  *
  * ─────────────────────────────────────────────────────────────────────────────
- *   EXPERIMENTAL: this surface is a DRAFT. Import it from `vigiles/experimental`,
+ *   EXPERIMENTAL: this surface is a DRAFT. Import it from `vigiles`,
  *   NOT from a stable subpath. It is NOT covered by the stability guarantee and
  *   may change shape or be removed WITHOUT a major-version bump. Do not build a
  *   production workflow on it yet. See docs/measuring-skills.md § Experimental.
@@ -44,7 +44,7 @@
  * side-effect-free).
  *
  * @experimental
- * @module vigiles/experimental (services)
+ * @module vigiles (services)
  */
 /**
  * How a service signals it is ready to accept work — polled by the