vigiles 19.0.0 → 20.0.0

package/dist/core/rule-meta.js

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

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

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

package/dist/core/skill-normalize.js

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

package/dist/core/spec.d.ts

@@ -71,7 +71,7 @@ export type StrictCmd = [keyof KnownNpmScripts] extends [never] ? string : `npm
  *   MCP / unknown / wildcard.
  *
  * The default (`string` at both) imposes no constraint — any tool is accepted at
- * every level, the historical behaviour of an untyped `agent()`/`skill()`.
+ * every level, the historical behaviour of an untyped `experimental_agent()`/`skill()`.
  */
 export interface ToolVocabulary {
     /** Union of tool names allowed under `purity: "pure"`. */
@@ -94,8 +94,6 @@ export interface OpenToolVocabulary extends ToolVocabulary {
  * untyped surface accepts any tools.
  */
 export type AllowedAt<P extends AuthoredPurity | undefined, V extends ToolVocabulary> = P extends "pure" ? V["readOnly"] : P extends "bounded" ? V["bounded"] : string;
-export type ClaudeTool = "Read" | "Write" | "Edit" | "Bash" | "Grep" | "Glob" | "Agent" | "TodoWrite" | "WebSearch" | "WebFetch" | "NotebookEdit";
-export type HookEvent = "PreToolUse" | "PostToolUse" | "PreSession" | "PostSession" | "Notification";
 /** A rule delegated to an external tool (linter, ast-grep, dependency-cruiser, etc.) or to a vigiles-internal check. */
 export interface EnforceRule {
     readonly _kind: "enforce";
@@ -257,18 +255,18 @@ export type InstructionFragment = string | Ref | EffectRegion;
 /**
  * Tagged template literal for skill instructions with typed references.
  *
- *   instructions`
+ *   prose`
  *     Check ${file("eslint.config.ts")} for rules.
  *     Run ${cmd("npm test")} to verify.
  *     See ${ref("skills/other/SKILL.md")} for format.
  *   `
  */
-export declare function instructions(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];
+export declare function prose(strings: TemplateStringsArray, ...values: InstructionFragment[]): InstructionFragment[];
 /**
  * Tagged template literal marking a side-effect boundary — usable as an
  * interpolated fragment inside a body / `instructions\`\``:
  *
- *   instructions`
+ *   prose`
  *     ## Apply
  *     ${effect`
  *       Side effects are allowed ONLY here:
@@ -332,7 +330,7 @@ export interface ClaudeSpec {
     readonly rules: Record<string, Rule>;
 }
 /**
- * Input type for claude() — maxSectionLines is only valid when sections are provided.
+ * Input type for instructionFile() — maxSectionLines is only valid when sections are provided.
  * TypeScript errors if you set maxSectionLines without defining sections.
  */
 type ClaudeSpecBase = {
@@ -354,9 +352,9 @@ type ClaudeSpecInput = ClaudeSpecBase & ClaudeSpecSections;
  * Define a CLAUDE.md specification.
  *
  *   // CLAUDE.md.spec.ts
- *   export default claude({ commands: {...}, rules: {...} });
+ *   export default instructionFile({ commands: {...}, rules: {...} });
  */
-export declare function claude(spec: ClaudeSpecInput): ClaudeSpec;
+export declare function instructionFile(spec: ClaudeSpecInput): ClaudeSpec;
 /**
  * A deterministic gate on a skill step or its final result. A gate is one of:
  * a command (exit 0), a file (must exist), or a *project role* that resolves to
@@ -484,6 +482,25 @@ export interface SkillSpec {
     /**
      * Terminal postcondition — the skill is "done" only when this gate passes.
      * Compiles to a `## Result` section + a `vigiles:result` marker.
+     *
+     * 🔴 NAMED `postcondition`, NOT `result`, because `result` already means
+     * something else one screen down: {@link result} builds a subagent's typed
+     * ok/err CONTRACT (and reaches a skill through `output:`). Two concepts under
+     * one word, told apart only by whether you wrote `result:` or `output:
+     * result(...)` — the doc comment on {@link result} had to spend a line saying
+     * "distinct from a skill's `result:` postcondition gate", which is the tell.
+     * A name that needs a disambiguating sentence is the wrong name.
+     *
+     * The compiled MARKER stays `vigiles:result` deliberately: it is the wire
+     * format between the compiler and {@link parseSkillGates}, and every already
+     * compiled SKILL.md on disk carries it. Renaming the authoring field is a
+     * source-level change; renaming the marker would invalidate stamps.
+     */
+    readonly postcondition?: Gate;
+    /**
+     * @deprecated Renamed to {@link SkillSpec.postcondition}. Removed next
+     * major. Measured 2026-08-21: 0 of 46 specs in the consuming knowledge base
+     * set this field, so the window costs nothing and closes the collision above.
      */
     readonly result?: Gate;
     /**
@@ -524,7 +541,7 @@ export type SkillSpecInput<P extends AuthoredPurity | undefined, V extends ToolV
  *   export default experimental_skill({ name: "my-skill", description: "…" });
  *
  * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
- * constraint), exactly like `agent()`: a vocabulary-bound `experimental_skill`
+ * constraint), exactly like `experimental_agent()`: a vocabulary-bound `experimental_skill`
  * (e.g. `vigiles/claude-code`) makes `purity: "pure"` + a side-effecting tool a
  * `tsc` error; the bare core one accepts any tools, as before.
  *
@@ -629,7 +646,7 @@ export interface AgentSpec {
     readonly purity?: AuthoredPurity;
 }
 /**
- * The input to `agent()` — `AgentSpec` minus the internal `_specType`, with the
+ * The input to `experimental_agent()` — `AgentSpec` minus the internal `_specType`, with the
  * `tools` list constrained by the declared `purity` and the tool vocabulary `V`.
  * `P` is inferred from the literal `purity` field (`const` inference), and
  * `tools` is then typed `AllowedAt<P, V>[]`:
@@ -637,7 +654,7 @@ export interface AgentSpec {
  * - `purity: "bounded"`→ `tools` may list `V["bounded"]` tools (admits `Bash`).
  * - no `purity` / `"dangerously-unrestricted"` → `tools` is `string[]` (open).
  *
- * With the open default vocabulary (core `agent()`) every level widens to
+ * With the open default vocabulary (core `experimental_agent()`) every level widens to
  * `string`, so any tools compile — backwards-compatible.
  */
 export type AgentSpecInput<P extends AuthoredPurity | undefined, V extends ToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape> = Omit<AgentSpec, "_specType" | "tools" | "purity" | "output"> & {
@@ -672,12 +689,12 @@ export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
  * Define a subagent specification (compiles to `agents/<name>.md`).
  *
  *   // agents/reviewer.md.spec.ts
- *   export default agent({
+ *   export default experimental_agent({
  *     name: "reviewer",
  *     description: "Review a diff for correctness. Dispatch PROACTIVELY after edits.",
  *     model: "sonnet",
  *     tools: ["Read", "Grep", "Bash"],
- *     body: instructions`Review the diff. Run ${cmd("npm test")} first.`,
+ *     body: prose`Review the diff. Run ${cmd("npm test")} first.`,
  *     rules: {
  *       "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."),
  *     },
@@ -686,15 +703,21 @@ export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
  * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
  * constraint). A harness adapter re-exports a vocabulary-bound `agent` (e.g.
  * `vigiles/claude-code`) so `purity: "pure"` + a side-effecting tool is a `tsc`
- * error at edit time; the bare core `agent()` accepts any tools, as before.
+ * error at edit time; the bare core `experimental_agent()` accepts any tools, as before.
  *
  * Also generic over the result's `Ok`/`Err` shapes, inferred from `output:
  * result(...)`. The returned value is a `TypedAgentSpec<Ok, Err>` — an
  * `AgentSpec` that carries those shapes at the type level, so a typed `pipe`
  * can cross-reference the handoff. With no `output` the shapes default to the
  * erased `Shape`, and the value is still a plain `AgentSpec` — backwards-compatible.
+ *
+ * @experimental The SHAPE is not settled — the author is unsure of the design,
+ * which is exactly what this marker promises: the form may change. It is NOT a
+ * claim that the surface is unproven. Measured 2026-06-20: real Claude Code
+ * loaded a compiled `agents/code-reviewer.md`, dispatched to it and read it,
+ * 100% of trials — stronger end-to-end evidence than `experimental_skill` has.
  */
-export declare function agent<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape>(spec: AgentSpecInput<P, V, Ok, Err>): TypedAgentSpec<Ok, Err>;
+export declare function experimental_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).
  *
@@ -848,7 +871,7 @@ export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Sha
 }
 /**
  * Pair a typed agent with the input it `needs` from the previous step. The first
- * argument is an `agent()` VALUE (which carries its `result()` shape); the
+ * argument is an `experimental_agent()` VALUE (which carries its `result()` shape); the
  * second is the `needs(...)` input contract.
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
@@ -1028,5 +1051,28 @@ export interface VigilesV2Config {
     readonly linters?: Record<string, LinterMode>;
 }
 export declare function defineConfig(config: VigilesV2Config): VigilesV2Config;
+/**
+ * @deprecated Renamed to {@link instructionFile}. The builder compiles to
+ * `CLAUDE.md` **and** `AGENTS.md` (see `InstructionTarget`), so a name taken from
+ * one of the two harnesses was never right. Removed one major AFTER the one that introduces it.
+ */
+export declare const claude: typeof instructionFile;
+/**
+ * @deprecated Renamed to {@link prose}. It builds a prose FRAGMENT with typed
+ * refs; the plural read as "the instruction file", which is what
+ * {@link instructionFile} builds. Removed one major AFTER the one that introduces it.
+ */
+export declare const instructions: typeof prose;
+/**
+ * @deprecated Renamed to {@link experimental_agent} — the shape is not settled.
+ * Removed one major AFTER the one that introduces it.
+ *
+ * @experimental
+ * vigiles:experimental-name-ok this IS the old spelling — prefixing a deprecated
+ * alias would defeat the alias, which exists precisely so code written against
+ * the unprefixed name keeps compiling for one major. It carries the tag because
+ * it is the same function, and the tag is what the deprecation notice points at.
+ */
+export declare const agent: typeof experimental_agent;
 export {};
 //# sourceMappingURL=spec.d.ts.map

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.instructions = exports.claude = exports.experimental_skill = exports.BUILTIN_LINTERS = void 0;
 exports.enforce = enforce;
 exports.guidance = guidance;
 exports.guard = guard;
@@ -20,11 +20,11 @@ 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.experimental_agent = experimental_agent;
 exports.result = result;
 exports.delegate = delegate;
 exports.railway = railway;
@@ -37,6 +37,7 @@ 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 +157,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 +177,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 +207,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 +263,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 +290,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 +304,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 +318,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 experimental_agent(spec) {
     return { _specType: "agent", ...spec };
 }
 /**
@@ -392,7 +403,7 @@ function experimental_needs(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[]" }))
@@ -468,4 +479,47 @@ 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;
+/**
+ * @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 = 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-install.js

@@ -83,9 +83,41 @@ function normalizeHookRef(hookPath, cwd = process.cwd()) {
  */
 function managesHook(entry, hookPath) {
     const ref = normalizeHookRef(hookPath);
-    return entry.hooks.some((h) => h.command
-        .split(/\s+/)
-        .some((token) => token !== "" && normalizeHookRef(token) === ref));
+    return entry.hooks.some((h) => h.command.split(/\s+/).some((token) => {
+        const bare = bareToken(token);
+        return bare !== "" && normalizeHookRef(bare) === ref;
+    }));
+}
+/**
+ * A command token reduced to the PATH it names, so two spellings of the same
+ * hook file compare equal.
+ *
+ * 🔴 BOTH STRIPS ARE REGRESSIONS, MEASURED IN A CONSUMER REPO 2026-08-21, and
+ * they compound: a settings.json wired the Claude-Code-recommended way carries
+ * BOTH a quote and the project-dir variable, so `managesHook` saw
+ * `"$CLAUDE_PROJECT_DIR/.claude/hooks/x.hook.ts"`, canonicalized it to
+ * something under the cwd that resembles nothing, and reported "not managed by
+ * this hook". Recompiling then APPENDED its own block beside the existing one.
+ * Twelve hooks, twelve duplicates, and the duplicate is the WORSE of the two:
+ * it spells the path relative to the cwd, so it dies with exit 2 the moment the
+ * agent runs from a subdirectory — while the healthy copy beside it keeps
+ * working, which is why this survived a full day unnoticed.
+ *
+ * - QUOTES. A path with a space MUST be quoted, so the quoted form is not an
+ *   exotic spelling — it is the correct one. Comparing it raw could never match.
+ * - `$CLAUDE_PROJECT_DIR`. It is defined as the project root, which is exactly
+ *   what `normalizeHookRef` resolves relative paths against, so stripping the
+ *   prefix makes the two spellings the same path by definition rather than by
+ *   guess. `${CLAUDE_PROJECT_DIR}` is the same variable in brace syntax.
+ *
+ * Nothing else is stripped. A token this function does not recognise is left
+ * alone and simply fails to match, which is the pre-existing behaviour: the
+ * cost of a miss here is a duplicate block, and the cost of an over-match is
+ * deleting a hook the user wrote themselves.
+ */
+function bareToken(token) {
+    const unquoted = token.replace(/^["']/, "").replace(/["']$/, "");
+    return unquoted.replace(/^\$\{?CLAUDE_PROJECT_DIR\}?[/\\]/, "");
 }
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`

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";