vigiles 19.0.0 → 20.0.0

package/README.md

@@ -260,6 +260,12 @@ Targets Claude Code and Codex out of the box, or [your own harness](docs/authori
 - **Reference** — [CLI](docs/cli.md) · [rules matrix](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix) · [testing API](docs/testing-api.md) · [full API](https://zernie.github.io/vigiles/api/)
 - **Explanation** — [what it catches](docs/what-vigiles-catches.md) · [how it compares](docs/comparison.md) · [FAQ](docs/faq.md)
 
+> **A name starting with `experimental_` is not covered by semver.** It may change
+> shape or disappear in a patch release. Everything so named has a stable
+> alternative, given in that feature's own docs page — and the prefix is the only
+> signal you need to look for, since it is on every call site rather than on an
+> import line you scrolled past. See [Stability](STABILITY.md).
+
 **Project** — [Stability](STABILITY.md) · [Related tools](docs/comparison.md#what-vigiles-composes-with) · ships as an [Agent Plugins](https://agent-plugins.org) 1.0.0 plugin ([how to do the same](docs/for-plugin-authors.md#6-ship-it-in-the-portable-agent-plugins-format))
 
 <!-- The "companion to [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need)"

package/dist/adapter-conformance.js

@@ -109,7 +109,7 @@ function checkAdapterConformance(adapter) {
     // pass the subagent tool-contract check under this dialect.
     const tool = adapter.dialect.builtinAgentTools[0];
     if (tool) {
-        const spec = (0, spec_js_1.agent)({
+        const spec = (0, spec_js_1.experimental_agent)({
             name: "conformance",
             description: "conformance probe",
             tools: [tool],

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

@@ -2,23 +2,23 @@
  * Typed Claude Code authoring surface — the compile-time half of the purity
  * contract, bound to the Claude Code tool vocabulary.
  *
- * The core `agent()` / `skill()` builders (`vigiles/spec`) are generic over a
+ * The core `experimental_agent()` / `skill()` builders (`vigiles/spec`) are generic over a
  * tool `ToolVocabulary` that DEFAULTS to fully-open (`string` at every purity
  * level), so they accept any tools — backwards-compatible, harness-agnostic.
  * This module re-binds them to the CONCRETE Claude Code vocabulary derived from
  * `claudeCodeDialect`, so authoring a spec with an invalid `purity`×`tools`
  * combination is a `tsc` error at EDIT TIME, before any vigiles command runs:
  *
- *   import { agent } from "vigiles/claude-code";
+ *   import { experimental_agent } from "vigiles/claude-code";
  *
- *   agent({ purity: "pure", tools: ["Read", "Bash"] });
+ *   experimental_agent({ purity: "pure", tools: ["Read", "Bash"] });
  *   //                                       ^^^^^^ tsc error — Bash side-effecting
  *
- *   agent({ purity: "bounded", tools: ["Read", "Bash", "Write"] }); // OK
- *   agent({ purity: "bounded", tools: ["mcp__x__y"] });
+ *   experimental_agent({ purity: "bounded", tools: ["Read", "Bash", "Write"] }); // OK
+ *   experimental_agent({ purity: "bounded", tools: ["mcp__x__y"] });
  *   //                                  ^^^^^^^^^^^ tsc error — MCP not decidable
  *
- *   agent({ tools: ["anything", "mcp__x__y"] }); // no purity → open, OK
+ *   experimental_agent({ tools: ["anything", "mcp__x__y"] }); // no purity → open, OK
  *
  * This is a STRICT ADDITION to the runtime/compile checks: `purityViolations`
  * (`vigiles compile`) and `decidePurityGate` (the PreToolUse gate) are unchanged
@@ -44,11 +44,11 @@ export interface ClaudeCodeToolVocabulary extends ToolVocabulary {
 }
 /**
  * Define a Claude Code subagent with the purity floor enforced AT COMPILE TIME
- * against the Claude Code tool catalog. Identical to the core `agent()` at
+ * against the Claude Code tool catalog. Identical to the core `experimental_agent()` at
  * runtime (it IS the core builder); the only difference is the typed `tools`
  * constraint. `P` is inferred from the literal `purity` field.
  */
-export declare function agent<const P extends AuthoredPurity | undefined = undefined>(spec: AgentSpecInput<P, ClaudeCodeToolVocabulary>): AgentSpec;
+export declare function experimental_agent<const P extends AuthoredPurity | undefined = undefined>(spec: AgentSpecInput<P, ClaudeCodeToolVocabulary>): AgentSpec;
 /**
  * Define a Claude Code skill with the purity floor enforced AT COMPILE TIME
  * against the Claude Code tool catalog. Identical to the core

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

@@ -1,28 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.experimental_skill = void 0;
-exports.agent = agent;
+exports.experimental_agent = experimental_agent;
 /**
  * Typed Claude Code authoring surface — the compile-time half of the purity
  * contract, bound to the Claude Code tool vocabulary.
  *
- * The core `agent()` / `skill()` builders (`vigiles/spec`) are generic over a
+ * The core `experimental_agent()` / `skill()` builders (`vigiles/spec`) are generic over a
  * tool `ToolVocabulary` that DEFAULTS to fully-open (`string` at every purity
  * level), so they accept any tools — backwards-compatible, harness-agnostic.
  * This module re-binds them to the CONCRETE Claude Code vocabulary derived from
  * `claudeCodeDialect`, so authoring a spec with an invalid `purity`×`tools`
  * combination is a `tsc` error at EDIT TIME, before any vigiles command runs:
  *
- *   import { agent } from "vigiles/claude-code";
+ *   import { experimental_agent } from "vigiles/claude-code";
  *
- *   agent({ purity: "pure", tools: ["Read", "Bash"] });
+ *   experimental_agent({ purity: "pure", tools: ["Read", "Bash"] });
  *   //                                       ^^^^^^ tsc error — Bash side-effecting
  *
- *   agent({ purity: "bounded", tools: ["Read", "Bash", "Write"] }); // OK
- *   agent({ purity: "bounded", tools: ["mcp__x__y"] });
+ *   experimental_agent({ purity: "bounded", tools: ["Read", "Bash", "Write"] }); // OK
+ *   experimental_agent({ purity: "bounded", tools: ["mcp__x__y"] });
  *   //                                  ^^^^^^^^^^^ tsc error — MCP not decidable
  *
- *   agent({ tools: ["anything", "mcp__x__y"] }); // no purity → open, OK
+ *   experimental_agent({ tools: ["anything", "mcp__x__y"] }); // no purity → open, OK
  *
  * This is a STRICT ADDITION to the runtime/compile checks: `purityViolations`
  * (`vigiles compile`) and `decidePurityGate` (the PreToolUse gate) are unchanged
@@ -37,12 +37,12 @@ exports.agent = agent;
 const spec_js_1 = require("../../core/spec.js");
 /**
  * Define a Claude Code subagent with the purity floor enforced AT COMPILE TIME
- * against the Claude Code tool catalog. Identical to the core `agent()` at
+ * against the Claude Code tool catalog. Identical to the core `experimental_agent()` at
  * runtime (it IS the core builder); the only difference is the typed `tools`
  * constraint. `P` is inferred from the literal `purity` field.
  */
-function agent(spec) {
-    return (0, spec_js_1.agent)(spec);
+function experimental_agent(spec) {
+    return (0, spec_js_1.experimental_agent)(spec);
 }
 /**
  * Define a Claude Code skill with the purity floor enforced AT COMPILE TIME

package/dist/claude-code.d.ts

@@ -9,7 +9,13 @@ export * from "./adapters/claude-code/plugin-loader.js";
 export * from "./mock-model.js";
 export { claudeCodeDriver, buildClaudeArgs, parseClaudeRun, claudeAvailable, } from "./harness-test.js";
 export * from "./adapters/claude-code/dialect.js";
-export { agent, experimental_skill, type ClaudeCodeToolVocabulary, } from "./adapters/claude-code/typed-spec.js";
+export { experimental_agent, experimental_skill, type ClaudeCodeToolVocabulary, } from "./adapters/claude-code/typed-spec.js";
+export { 
+/**
+ * @deprecated Renamed to `experimental_agent` — the shape is not settled.
+ * Removed one major AFTER the one that introduces it.
+ */
+experimental_agent as agent, } from "./adapters/claude-code/typed-spec.js";
 export { measureSelectionMatrix, assertNoCollision, formatSelectionReport, } from "./scan-behavioral.js";
 export type { SelectionReport, SkillSelectionStat, SelectionOptions, SelectionMatrixOptions, } from "./scan-behavioral.js";
 export * from "./adapters/claude-code/layout.js";

package/dist/claude-code.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatSelectionReport = exports.assertNoCollision = exports.measureSelectionMatrix = exports.experimental_skill = exports.agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
+exports.formatSelectionReport = exports.assertNoCollision = exports.measureSelectionMatrix = exports.agent = exports.experimental_skill = exports.experimental_agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
 /**
  * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
  * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
@@ -35,10 +35,10 @@ Object.defineProperty(exports, "buildClaudeArgs", { enumerable: true, get: funct
 Object.defineProperty(exports, "parseClaudeRun", { enumerable: true, get: function () { return harness_test_js_1.parseClaudeRun; } });
 Object.defineProperty(exports, "claudeAvailable", { enumerable: true, get: function () { return harness_test_js_1.claudeAvailable; } });
 __exportStar(require("./adapters/claude-code/dialect.js"), exports);
-// The typed Claude Code authoring surface: `agent` / `experimental_skill` with
+// The typed Claude Code authoring surface: `experimental_agent` / `experimental_skill` with
 // the `purity` floor enforced AT COMPILE TIME against the CC tool catalog (a
 // `tsc` error for e.g. `purity: "pure"` + `"Bash"`). A strict addition to the
-// runtime/compile purity checks; the bare core `agent()`/`experimental_skill()`
+// runtime/compile purity checks; the bare core `experimental_agent()`/`experimental_skill()`
 // (`vigiles/spec`) stay open.
 //
 // NOTE the collision this rename also resolves: `vigiles/testing` exports a
@@ -46,8 +46,19 @@ __exportStar(require("./adapters/claude-code/dialect.js"), exports);
 // this skill fire?", taking an id string. One word, two concepts, told apart
 // only by which door you imported from. Only the authoring builder is prefixed.
 var typed_spec_js_1 = require("./adapters/claude-code/typed-spec.js");
-Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return typed_spec_js_1.agent; } });
+Object.defineProperty(exports, "experimental_agent", { enumerable: true, get: function () { return typed_spec_js_1.experimental_agent; } });
 Object.defineProperty(exports, "experimental_skill", { enumerable: true, get: function () { return typed_spec_js_1.experimental_skill; } });
+// ─── ОКНО АЛИАСА (один мажор) ──────────────────────────────────────────────────
+// Та же политика, что в `core/spec.ts`: старое имя живёт ровно один мажор. Эта
+// дверь обязана иметь окно ОТДЕЛЬНО — потребитель, импортировавший `agent` из
+// `vigiles/claude-code`, никогда не видел `vigiles/spec`, и окно на той стороне
+// его не спасает.
+var typed_spec_js_2 = require("./adapters/claude-code/typed-spec.js");
+/**
+ * @deprecated Renamed to `experimental_agent` — the shape is not settled.
+ * Removed one major AFTER the one that introduces it.
+ */
+Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return typed_spec_js_2.experimental_agent; } });
 // Selection-collision — a Claude-Code-ONLY behavioral measurement (Codex has no
 // skill-selection event to read), so it lives on this surface, not the agnostic
 // `vigiles`. `measureSelectionMatrix` builds the N×N "which skill fired?"

package/dist/cli.js

@@ -1431,7 +1431,7 @@ function targetHasHash(absPath) {
 /** Classify an adoption target by its path: a `SKILL.md` is a skill, a file under
  * an `agents/` dir is a subagent, everything else is an instruction file. Used to
  * pick the right adopt function so `init --target=skills/x/SKILL.md` (the
- * per-surface path the audit report points at) makes a `skill()`/`agent()` spec. */
+ * per-surface path the audit report points at) makes a `skill()`/`experimental_agent()` spec. */
 function surfaceKind(target) {
     if (/^SKILL\.md$/i.test((0, node_path_1.basename)(target)))
         return "skill";
@@ -1835,11 +1835,11 @@ function scaffoldSpec(args) {
     // the moment this is committed, because the enforce()/guidance() examples
     // below are commented out. The commented import shows what to add when you
     // write a real rule.
-    const template = `import { claude } from "vigiles/spec";
+    const template = `import { instructionFile } from "vigiles/spec";
 // When you add rules below, import the builders you use, e.g.:
-// import { claude, enforce, guidance } from "vigiles/spec";
+// import { instructionFile, enforce, guidance } from "vigiles/spec";
 
-export default claude({${targetLine}
+export default instructionFile({${targetLine}
   sections: {
     // Prose sections become ## headings in the compiled output.
     // Do not add # or ## headers inside sections.

package/dist/core/CLAUDE.md.spec.js

@@ -11,7 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * compiled build artifact (`vigiles compile`).
  */
 const spec_js_1 = require("./spec.js");
-exports.default = (0, spec_js_1.claude)({
+exports.default = (0, spec_js_1.instructionFile)({
     sections: {
         scope: `Working in \`src/core/\`? This is the harness-AGNOSTIC domain (spec, compile, linters, the lint/audit detectors). The root \`CLAUDE.md\` holds the full positioning + rule set — read it first. Two invariants live closest to this code: the core must not import an adapter (\`core ⊄ adapter\`, eslint-enforced) and must not hard-code a Claude Code literal (read it from the injected layout/dialect). This file adds the rule for ADDING or CHANGING a detector.`,
     },

package/dist/core/adopt.d.ts

@@ -2,7 +2,7 @@
  * Faithful markdown → typed-spec adoption — the deterministic half of `init`
  * auto-adopt (research/install-enforcement-dx.md).
  *
- * Turns an existing instruction file (CLAUDE.md / AGENTS.md) into a `claude()`
+ * Turns an existing instruction file (CLAUDE.md / AGENTS.md) into a `instructionFile()`
  * spec source that compiles back to ~the same file, so adopting a rich,
  * hand-tuned instruction file is SAFE: every heading becomes a prose section
  * (verbatim), no rule is invented, nothing is dropped. The contract to the user
@@ -35,7 +35,7 @@ export interface AdoptResult {
     sectionCount: number;
 }
 /**
- * The intermediate adoption result: the `claude()` spec FIELDS (before
+ * The intermediate adoption result: the `instructionFile()` spec FIELDS (before
  * rendering to source). Exposed so the renderer and the round-trip tests share
  * one parse — the test can feed `sections` straight into `compileClaude` and
  * assert the file is reproduced, without evaluating generated TS source.
@@ -49,7 +49,7 @@ export interface AdoptedSpec {
     tier: AdoptTier;
 }
 /**
- * Parse an instruction file's markdown into the faithful `claude()` spec FIELDS.
+ * Parse an instruction file's markdown into the faithful `instructionFile()` spec FIELDS.
  * The shared core of {@link adoptMarkdown} and the round-trip tests.
  *
  * @param markdown the file's current content (an existing integrity header, if
@@ -59,7 +59,7 @@ export interface AdoptedSpec {
  */
 export declare function adoptToSpec(markdown: string, target: string): AdoptedSpec;
 /**
- * Convert an instruction file's markdown into a faithful `claude()` spec source
+ * Convert an instruction file's markdown into a faithful `instructionFile()` spec source
  * (the deliverable `init` writes).
  */
 export declare function adoptMarkdown(markdown: string, target: string): AdoptResult;

package/dist/core/adopt.js

@@ -3,7 +3,7 @@
  * Faithful markdown → typed-spec adoption — the deterministic half of `init`
  * auto-adopt (research/install-enforcement-dx.md).
  *
- * Turns an existing instruction file (CLAUDE.md / AGENTS.md) into a `claude()`
+ * Turns an existing instruction file (CLAUDE.md / AGENTS.md) into a `instructionFile()`
  * spec source that compiles back to ~the same file, so adopting a rich,
  * hand-tuned instruction file is SAFE: every heading becomes a prose section
  * (verbatim), no rule is invented, nothing is dropped. The contract to the user
@@ -123,15 +123,15 @@ function renderSpecSource(spec) {
     return `// Adopted from ${spec.target} by \`vigiles init\` — faithful by default.
 // Each heading became a prose section; no rules were inferred. Run the
 // \`/strengthen\` skill to upgrade prose to verified enforce()/guard() rules.
-import { claude } from "vigiles/spec";
+import { instructionFile } from "vigiles/spec";
 
-export default claude({${targetLine}${maxLine}${sectionsBlock}
+export default instructionFile({${targetLine}${maxLine}${sectionsBlock}
   rules: {},
 });
 `;
 }
 /**
- * Parse an instruction file's markdown into the faithful `claude()` spec FIELDS.
+ * Parse an instruction file's markdown into the faithful `instructionFile()` spec FIELDS.
  * The shared core of {@link adoptMarkdown} and the round-trip tests.
  *
  * @param markdown the file's current content (an existing integrity header, if
@@ -189,7 +189,7 @@ function adoptToSpec(markdown, target) {
     };
 }
 /**
- * Convert an instruction file's markdown into a faithful `claude()` spec source
+ * Convert an instruction file's markdown into a faithful `instructionFile()` spec source
  * (the deliverable `init` writes).
  */
 function adoptMarkdown(markdown, target) {
@@ -348,7 +348,7 @@ function adoptSkill(markdown, dirName) {
     return { source, kind: "skill", spec, unmappedKeys };
 }
 /**
- * Adopt an existing subagent (`agents/<name>.md`) into an `agent()` spec. Unlike
+ * Adopt an existing subagent (`agents/<name>.md`) into an `experimental_agent()` spec. Unlike
  * a skill, an agent's `sections` reject `##` headers, so the body is split: the
  * lead preamble becomes `body` and each `##`/`#` heading becomes a named section
  * (reusing the instruction-file splitter). The tool contract is carried as-is —
@@ -378,7 +378,7 @@ function splitAgentBody(body) {
     }
     return { lead, sectionEntries };
 }
-/** Render the `agent({…})` source lines from the extracted fields. */
+/** Render the `experimental_agent({…})` source lines from the extracted fields. */
 function buildAgentLines(f) {
     const lines = [
         `  name: ${JSON.stringify(f.name)},`,
@@ -419,7 +419,7 @@ function adoptAgent(markdown, fileBase) {
     const sections = {};
     for (const { key, content } of f.sectionEntries)
         sections[key] = content;
-    const spec = (0, spec_js_1.agent)({
+    const spec = (0, spec_js_1.experimental_agent)({
         name: f.name,
         description: f.description,
         ...(f.model ? { model: f.model } : {}),
@@ -433,8 +433,8 @@ function adoptAgent(markdown, fileBase) {
     });
     const source = SURFACE_HEADER(`${fileBase}.md`) +
         unmappedNote("agent", unmappedKeys) +
-        `import { agent } from "vigiles/spec";\n\n` +
-        `export default agent({\n${buildAgentLines(f).join("\n")}\n});\n`;
+        `import { experimental_agent } from "vigiles/spec";\n\n` +
+        `export default experimental_agent({\n${buildAgentLines(f).join("\n")}\n});\n`;
     return { source, kind: "agent", spec, unmappedKeys };
 }
 //# sourceMappingURL=adopt.js.map

package/dist/core/compile.js

@@ -34,6 +34,7 @@ const hash_js_1 = require("./hash.js");
 const integrity_js_1 = require("./integrity.js");
 const markdown_js_1 = require("./markdown.js");
 const symbols_js_1 = require("./symbols.js");
+const skill_normalize_js_1 = require("./skill-normalize.js");
 const linters_js_1 = require("./linters.js");
 const tool_contract_js_1 = require("./tool-contract.js");
 const effects_js_1 = require("./effects.js");
@@ -301,7 +302,7 @@ function compileRule(id, rule) {
 // chars; TS #52243 unresolved), so a helper's content is guarded at COMPILE time
 // instead — the ESLint-max-len / Prettier-printWidth precedent. Deliberately
 // generous (don't-cry-wolf): real prose sections are short, so this only trips on
-// an egregious dump (a whole essay pasted into one section / instructions``).
+// an egregious dump (a whole essay pasted into one section / prose``).
 // Override per spec with `maxSectionLines`; `maxTokens` is the global backstop.
 const DEFAULT_MAX_SECTION_LINES = 200;
 function validateSectionContent(name, text, maxSectionLines) {
@@ -619,8 +620,8 @@ function collectSkillRefs(spec) {
         if (s.gate && s.gate._ref !== "role")
             refs.push(s.gate);
     }
-    if (spec.result && spec.result._ref !== "role")
-        refs.push(spec.result);
+    if (spec.postcondition && spec.postcondition._ref !== "role")
+        refs.push(spec.postcondition);
     return refs;
 }
 /**
@@ -725,8 +726,8 @@ function renderSkillSections(spec) {
     if (spec.steps && spec.steps.length > 0) {
         sections.push(renderSteps(spec.steps));
     }
-    if (spec.result)
-        sections.push(renderResult(spec.result));
+    if (spec.postcondition)
+        sections.push(renderResult(spec.postcondition));
     // A forked skill (context: fork) runs as a subagent, so it may carry the SAME
     // typed Result outcome — reuse the subagent renderer (one-renderer-no-drift).
     if (spec.output)
@@ -774,6 +775,14 @@ function checkInlineCode(markdown, max) {
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
  */
 function compileSkill(spec, options = {}) {
+    // 🔴 NORMALISE FIRST, before anything reads the spec. `compileSkill` accepts a
+    // `SkillSpec` STRUCTURALLY, so a caller can hand us `{ _specType: "skill", …,
+    // result: cmd(…) }` without ever touching `experimental_skill()`. Both readers
+    // below (`collectSkillRefs`, `renderSkillSections`) look only at
+    // `postcondition`, so without this line such a spec loses its `## Result`
+    // section AND its reference verification, silently. Doing it here rather than
+    // in the readers means a reader added later cannot reintroduce the gap.
+    spec = (0, skill_normalize_js_1.foldLegacyPostcondition)(spec);
     const basePath = options.basePath ?? process.cwd();
     const specFile = options.specFile ?? "SKILL.md.spec.ts";
     const profile = options.dialect?.skillFrontmatter ?? "claude-code";
@@ -859,13 +868,13 @@ function compileSkill(spec, options = {}) {
 // harness's format-axis vocabulary — it lives in the HarnessDialect port
 // (src/core/dialect.ts), injected here, never hard-coded for one harness.
 //
-// SCOPE: compileAgent renders vigiles's agent() — a VERIFIED TOOL CONTRACT — to
+// SCOPE: compileAgent renders vigiles's experimental_agent() — a VERIFIED TOOL CONTRACT — to
 // a Claude-Code-shaped subagent markdown file. Compiling that to Codex is a
 // deliberate NON-GOAL, not a missing renderer: a Codex "subagent" is an
 // [agents.<name>] TOML concurrency table (max_threads / max_depth), which is a
 // runtime-orchestration knob, NOT a tool contract. The two models don't map, so
 // vigiles does not emit a TOML [agents] block. The Codex dialect still verifies
-// an agent()'s tool contract (its built-in catalog) — only the OUTPUT renderer
+// an experimental_agent()'s tool contract (its built-in catalog) — only the OUTPUT renderer
 // is CC-only here. See research/codex-prototype-findings.md (gaps).
 /** Verify a subagent's allowed-tools contract — the rails are real tools. The
  * detection lives in the shared `verifyToolContract` detector (one-detector-no-

package/dist/core/hook-program.d.ts

@@ -263,10 +263,13 @@ export declare const tool: (name: string) => {
     tool: string;
 };
 /**
- * @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.
  */
-export declare function defineHook<const N extends readonly NeedSpec[] = readonly []>(p: HookProgram<N>): HookProgram<N>;
+export declare function experimental_defineHook<const N extends readonly NeedSpec[] = readonly []>(p: HookProgram<N>): HookProgram<N>;
 /**
  * Build the typed event from a raw PreToolUse event, then decide.
  *
@@ -511,10 +514,13 @@ export declare const tools: (...names: string[]) => {
     tools: string[];
 };
 /**
- * @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.
  */
-export declare function defineFileGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<FileGateHook<N>, "role">): FileGateHook<N>;
+export declare function experimental_defineFileGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<FileGateHook<N>, "role">): FileGateHook<N>;
 /**
  * Run a file-tool gate against a raw PreToolUse event (reads `file_path`).
  *
@@ -551,10 +557,13 @@ export interface PromptGateHook<N extends readonly NeedSpec[] = readonly Provide
     readonly decide: (e: PromptEvent<N>) => Decision;
 }
 /**
- * @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.
  */
-export declare function definePromptGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<PromptGateHook<N>, "role">): PromptGateHook<N>;
+export declare function experimental_definePromptGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<PromptGateHook<N>, "role">): PromptGateHook<N>;
 /** Run a prompt gate against a raw UserPromptSubmit event (reads `prompt`). */
 export declare function decidePromptGate<N extends readonly NeedSpec[]>(hook: PromptGateHook<N>, raw: {
     prompt?: unknown;
@@ -586,10 +595,13 @@ export interface StopGateHook<N extends readonly NeedSpec[] = readonly ProviderN
     readonly decide: (e: StopEvent<N>) => Decision;
 }
 /**
- * @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.
  */
-export declare function defineStopGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<StopGateHook<N>, "role">): StopGateHook<N>;
+export declare function experimental_defineStopGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<StopGateHook<N>, "role">): StopGateHook<N>;
 /** Run a Stop gate against a raw Stop/SubagentStop event (reads `stop_hook_active`). */
 export declare function decideStopGate<N extends readonly NeedSpec[]>(hook: StopGateHook<N>, raw: {
     stop_hook_active?: unknown;
@@ -635,10 +647,13 @@ export interface InjectHook<N extends readonly NeedSpec[] = readonly ProviderNam
     readonly produce: (e: SessionEvent<N>) => Injection;
 }
 /**
- * @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.
  */
-export declare function defineInject<const N extends readonly NeedSpec[] = readonly []>(p: Omit<InjectHook<N>, "role">): InjectHook<N>;
+export declare function experimental_defineInject<const N extends readonly NeedSpec[] = readonly []>(p: Omit<InjectHook<N>, "role">): InjectHook<N>;
 /**
  * Run an inject hook → the CC JSON the author never hand-writes. The compiler
  * targets `additionalContext` (the RIGHT field for this event), so the
@@ -740,10 +755,13 @@ export interface ReactHook<N extends readonly NeedSpec[] = readonly ProviderName
     readonly react: (e: ReactEvent<N>) => Reaction;
 }
 /**
- * @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.
  */
-export declare function defineReact<const N extends readonly NeedSpec[] = readonly []>(p: Omit<ReactHook<N>, "role">): ReactHook<N>;
+export declare function experimental_defineReact<const N extends readonly NeedSpec[] = readonly []>(p: Omit<ReactHook<N>, "role">): ReactHook<N>;
 /**
  * Run a react hook against a raw PostToolUse event → the (classified) Reaction.
  *

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 };
 }
 /**