vigiles 15.4.1 → 16.0.1

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

@@ -51,8 +51,31 @@ export interface ClaudeCodeToolVocabulary extends ToolVocabulary {
 export declare function 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 `skill()` at
- * runtime; the typed `tools` constraint is the only difference.
+ * against the Claude Code tool catalog. Identical to the core
+ * `experimental_skill()` at runtime; the typed `tools` constraint is the only
+ * difference.
+ *
+ * Carries the same `.input` / `.step` helpers as the core builder, and it must:
+ * those two stopped being standalone exports when the helper vocabulary moved
+ * onto the skill builder, so an author who picked this door would otherwise have
+ * no way to reach them. Before the move they came from `vigiles/spec` — a second
+ * import for one skill, which is the asymmetry this closes rather than a cost it
+ * introduces.
+ *
+ * @experimental
+ */
+declare function skillSpec<const P extends AuthoredPurity | undefined = undefined>(spec: SkillSpecInput<P, ClaudeCodeToolVocabulary>): SkillSpec;
+/**
+ * @experimental
  */
-export declare function experimental_skill<const P extends AuthoredPurity | undefined = undefined>(spec: SkillSpecInput<P, ClaudeCodeToolVocabulary>): SkillSpec;
+export declare const experimental_skill: typeof skillSpec & {
+    input: (name: string, hint: string, opts?: {
+        required?: boolean;
+    }) => import("../../core/spec.js").SkillInput;
+    step: (instr: string | import("../../core/spec.js").InstructionFragment[], opts?: {
+        gate?: import("../../core/spec.js").Gate;
+        retry?: number;
+    }) => import("../../core/spec.js").SkillStep;
+};
+export {};
 //# sourceMappingURL=typed-spec.d.ts.map

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.experimental_skill = void 0;
 exports.agent = agent;
-exports.experimental_skill = experimental_skill;
 /**
  * Typed Claude Code authoring surface — the compile-time half of the purity
  * contract, bound to the Claude Code tool vocabulary.
@@ -46,10 +46,27 @@ function agent(spec) {
 }
 /**
  * Define a Claude Code skill with the purity floor enforced AT COMPILE TIME
- * against the Claude Code tool catalog. Identical to the core `skill()` at
- * runtime; the typed `tools` constraint is the only difference.
+ * against the Claude Code tool catalog. Identical to the core
+ * `experimental_skill()` at runtime; the typed `tools` constraint is the only
+ * difference.
+ *
+ * Carries the same `.input` / `.step` helpers as the core builder, and it must:
+ * those two stopped being standalone exports when the helper vocabulary moved
+ * onto the skill builder, so an author who picked this door would otherwise have
+ * no way to reach them. Before the move they came from `vigiles/spec` — a second
+ * import for one skill, which is the asymmetry this closes rather than a cost it
+ * introduces.
+ *
+ * @experimental
  */
-function experimental_skill(spec) {
+function skillSpec(spec) {
     return (0, spec_js_1.experimental_skill)(spec);
 }
+/**
+ * @experimental
+ */
+exports.experimental_skill = Object.assign(skillSpec, {
+    input: spec_js_1.experimental_skill.input,
+    step: spec_js_1.experimental_skill.step,
+});
 //# sourceMappingURL=typed-spec.js.map

package/dist/cli.js

@@ -1356,12 +1356,16 @@ function vigilesDepSpec() {
     const major = parseInt(getVersion(), 10);
     return Number.isFinite(major) && major > 0 ? `^${String(major)}` : "latest";
 }
-/** True when the file's first line carries a vigiles integrity hash (i.e. it
- * is a compiled artifact we own, safe to overwrite — not hand-written prose). */
+/** True when the file carries a vigiles integrity hash (i.e. it is a compiled artifact we own,
+ * safe to overwrite — not hand-written prose).
+ *
+ * 🔴 This used to read the FIRST LINE only. A compiled SKILL.md carries the header after its
+ * frontmatter, so the first line is `---` and this returned false — vigiles would have treated
+ * its own compiled skill as hand-written prose and refused to overwrite it. The whole-file read
+ * is the cost of not encoding the header's position in a fourth place. */
 function targetHasHash(absPath) {
     try {
-        const first = (0, node_fs_1.readFileSync)(absPath, "utf-8").split("\n", 1)[0];
-        return first.includes("vigiles:sha256");
+        return (0, integrity_js_1.findIntegrityHeader)((0, node_fs_1.readFileSync)(absPath, "utf-8")) !== null;
     }
     catch {
         return false;

package/dist/core/adopt.js

@@ -205,11 +205,18 @@ function adoptMarkdown(markdown, target) {
 // frontmatter-read.ts but matches past the closing fence.
 const FRONTMATTER_CONSUME_RE = /^\uFEFF?(?:<!--[\s\S]*?-->\s*)?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/;
 function splitFrontmatterBody(markdown) {
-    const fm = (0, frontmatter_read_js_1.readFrontmatter)(markdown);
+    // Strip the integrity header FIRST, wherever it sits. FRONTMATTER_CONSUME_RE above knows
+    // only the pre-2026-08-17 placement (a comment BEFORE the frontmatter); once the header
+    // moved below the frontmatter it landed inside what this function calls "the body", so a
+    // round-trip adopt \u2192 compile \u2192 re-adopt grew a stamp into the spec's body on every pass.
+    // Delegating keeps ONE site that knows where the header can be \u2014 which is the entire point
+    // of findIntegrityHeader, and this caller is the one the move missed.
+    const source = (0, integrity_js_1.findIntegrityHeader)(markdown)?.withoutHeader ?? markdown;
+    const fm = (0, frontmatter_read_js_1.readFrontmatter)(source);
     if (fm.block === null)
-        return { fm, body: markdown.replace(/^\uFEFF/, "") };
-    const m = FRONTMATTER_CONSUME_RE.exec(markdown);
-    return { fm, body: m ? markdown.slice(m[0].length) : markdown };
+        return { fm, body: source.replace(/^\uFEFF/, "") };
+    const m = FRONTMATTER_CONSUME_RE.exec(source);
+    return { fm, body: m ? source.slice(m[0].length) : source };
 }
 /** The first non-empty, non-heading paragraph — the CC fallback for a skill's
  * description when its frontmatter omits one (name←dir, description←first ¶). */

package/dist/core/compile.js

@@ -27,6 +27,7 @@ const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
 const node_path_1 = require("node:path");
 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 linters_js_1 = require("./linters.js");
@@ -39,27 +40,42 @@ const DEFAULT_TARGET = "CLAUDE.md";
 // ---------------------------------------------------------------------------
 // Hash utilities
 // ---------------------------------------------------------------------------
-const HASH_RE = /^<!-- vigiles:sha256:([a-f0-9]+) compiled from (.+) -->\r?\n\r?\n?/;
+// The header's position and format now live in ONE place — `./integrity.js`. The local
+// `HASH_RE` that used to sit here was one of four independent copies of "the header is the first
+// line", and that duplication is what let the placement invariant drift unnoticed (see the block
+// comment on FRONTMATTER_RE in integrity.ts).
 /** @internal Compute SHA-256 hash of content (excluding any existing hash line). */
 function computeHash(content) {
-    const body = content.replace(HASH_RE, "");
-    return (0, hash_js_1.sha256short)(body);
+    return (0, hash_js_1.sha256short)((0, integrity_js_1.findIntegrityHeader)(content)?.withoutHeader ?? content);
 }
 /** @internal Prepend a hash comment to compiled content. */
 function addHash(content, specFile) {
-    const hash = computeHash(content);
-    return `<!-- vigiles:sha256:${hash} compiled from ${specFile} -->\n\n${content}`;
+    // 🔴 THE LAST GATE BEFORE A COMPILED FILE IS WRITTEN. Every compile path returns through here
+    // (four call sites), which makes it the one place a whole class of defect can be stopped.
+    //
+    // `[object Object]` in output means a spec passed an object where the API takes a string, and
+    // JS stringified it instead of complaining — types cannot stop this for a user's spec, because
+    // `vigiles compile` runs `.spec.ts` through tsx: transpiled, types erased, never checked.
+    // Observed 2026-08-17 from `input({ name, description })`, which shipped
+    // `argument-hint: <[object Object]>` into a SKILL.md with no error anywhere.
+    //
+    // Hard error, not a warning: the string never appears legitimately (measured — zero
+    // occurrences across every `.md` in this repository), and a file carrying it is broken in a
+    // way its author cannot see by reading the spec.
+    if (content.includes("[object Object]")) {
+        throw new Error(`Compiled output for ${specFile} contains "[object Object]" — a spec value was an object ` +
+            `where a string was expected, and JavaScript stringified it. Check the arguments to ` +
+            `input()/file()/cmd() and friends: they take strings, not option objects.`);
+    }
+    return (0, integrity_js_1.placeIntegrityHeader)(content, computeHash(content), specFile);
 }
 /** @internal Check if a file's hash matches its content. Returns null if no hash found. */
 function verifyHash(content) {
-    const match = content.match(HASH_RE);
-    if (!match)
+    const found = (0, integrity_js_1.findIntegrityHeader)(content);
+    if (!found)
         return null;
-    const expectedHash = match[1];
-    const specFile = match[2];
-    const body = content.replace(HASH_RE, "");
-    const actualHash = (0, hash_js_1.sha256short)(body);
-    return { valid: actualHash === expectedHash, specFile };
+    const actualHash = (0, hash_js_1.sha256short)(found.withoutHeader);
+    return { valid: actualHash === found.hash, specFile: found.specFile };
 }
 // ---------------------------------------------------------------------------
 // Token estimation
@@ -1077,10 +1093,11 @@ function adoptDiff(filePath, spec, basePath, dialect) {
         compiledContent = markdown;
     }
     // Simple line-based diff
-    const currentLines = currentContent.replace(HASH_RE, "").split("\n");
-    const compiledLines = (compiledContent ?? "")
-        .replace(HASH_RE, "")
-        .split("\n");
+    const currentLines = ((0, integrity_js_1.findIntegrityHeader)(currentContent)?.withoutHeader ?? currentContent).split("\n");
+    const compiledLines = (() => {
+        const c = compiledContent ?? "";
+        return ((0, integrity_js_1.findIntegrityHeader)(c)?.withoutHeader ?? c).split("\n");
+    })();
     const currentSet = new Set(currentLines);
     const compiledSet = new Set(compiledLines);
     const addedLines = currentLines.filter((l) => l.trim() && !compiledSet.has(l));

package/dist/core/coverage.js

@@ -17,6 +17,7 @@ exports.computeLinterRuleCoverage = computeLinterRuleCoverage;
 exports.checkCoverage = checkCoverage;
 exports.formatCoverageReport = formatCoverageReport;
 const node_fs_1 = require("node:fs");
+const integrity_js_1 = require("./integrity.js");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
 const compile_js_1 = require("./compile.js");
@@ -57,11 +58,13 @@ function collectDocumentedCommands(basePath, specs) {
         const fullPath = (0, node_path_1.resolve)(basePath, mdFile);
         try {
             const content = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
-            const specMatch = content.match(/^<!-- vigiles:sha256:[a-f0-9]+ compiled from (.+) -->/);
-            if (!specMatch)
+            // Ask integrity.ts where the header is — a compiled SKILL.md carries it AFTER its
+            // frontmatter, so an `^`-anchored match here silently skipped every skill.
+            const found = (0, integrity_js_1.findIntegrityHeader)(content);
+            if (!found)
                 continue;
             // Try to load the spec's compiled JS from dist/
-            const specFile = specMatch[1];
+            const specFile = found.specFile;
             const jsPath = (0, node_path_1.resolve)(basePath, "dist", specFile.replace(/\.ts$/, ".js"));
             if ((0, node_fs_1.existsSync)(jsPath)) {
                 try {

package/dist/core/frontmatter-read.js

@@ -24,8 +24,12 @@ const js_yaml_1 = require("js-yaml");
 // Frontmatter is the very first thing in the file. Anchoring at the start — not
 // `(?:^|\n)` — means a `---` horizontal rule in the BODY is never mistaken for
 // frontmatter (which matters for the malformed-YAML verdict). A leading BOM is
-// stripped first; an optional leading HTML comment is allowed too — vigiles
-// stamps a compiled file with `<!-- vigiles:sha256:… -->` before the `---`.
+// stripped first; an optional leading HTML comment is allowed too, which is what
+// lets this reader still parse files compiled BEFORE 2026-08-17, when vigiles put
+// the `<!-- vigiles:sha256:… -->` stamp above the `---` and thereby hid the
+// frontmatter from every stricter reader. Since then the stamp goes BELOW the
+// frontmatter (placeIntegrityHeader), so this branch is backward compatibility,
+// not a description of what the compiler emits today.
 const BLOCK_RE = /^\uFEFF?(?:<!--[\s\S]*?-->\s*)?---\r?\n([\s\S]*?)\r?\n---/;
 /** A YAML block-scalar indicator: `>`/`|` with optional chomp (`+`/`-`) + indent digit. */
 const BLOCK_SCALAR_RE = /^[|>][+-]?\d*$/;

package/dist/core/integrity.d.ts

@@ -17,6 +17,30 @@
  * - "Are committed compiled files actually fresh?"
  *   → CI runs `vigiles compile` then `git diff --exit-code`
  */
+/**
+ * Split off a leading frontmatter block. `head` is `""` when the file has none, so a caller can
+ * concatenate `head + body` unconditionally and get the original content back.
+ */
+export declare function splitFrontmatter(content: string): {
+    head: string;
+    body: string;
+};
+/**
+ * Locate the integrity header wherever it legitimately sits — before the frontmatter (files
+ * compiled before 2026-08-17) or after it (files compiled since). Returns the hash, the spec
+ * path, and the content with the header removed and everything else intact.
+ *
+ * This is the ONLY place that knows where the header can be. Matching `/^<!-- vigiles:sha256/`
+ * by hand elsewhere is the bug this function exists to make unnecessary.
+ */
+export declare function findIntegrityHeader(content: string): {
+    hash: string;
+    specFile: string;
+    /** `content` minus the header, frontmatter still in place. */
+    withoutHeader: string;
+} | null;
+/** Render the header in its correct position for this content. */
+export declare function placeIntegrityHeader(content: string, hash: string, specFile: string): string;
 export interface IntegrityResult {
     intact: boolean;
     reason?: string;

package/dist/core/integrity.js

@@ -20,22 +20,93 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = void 0;
+exports.splitFrontmatter = splitFrontmatter;
+exports.findIntegrityHeader = findIntegrityHeader;
+exports.placeIntegrityHeader = placeIntegrityHeader;
 exports.checkIntegrity = checkIntegrity;
 exports.parseIntegrityHeader = parseIntegrityHeader;
 exports.ejectMarkdown = ejectMarkdown;
 const hash_js_1 = require("./hash.js");
 const HASH_LINE_RE = /^<!-- vigiles:sha256:([a-f0-9]+) compiled from (.+) -->\r?\n\r?\n?/;
+/**
+ * A YAML frontmatter block at the very start of a file: `---\n … \n---\n`.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE INVARIANT WAS STATED IN THIS FILE AND VIOLATED IN ANOTHER.
+ * `ejectMarkdown` (bottom of this module) has documented since it was written that a compiled
+ * SKILL.md begins with frontmatter which MUST stay in first position, or "the harness would lose
+ * the skill's name/description/tools". `addHash` in compile.ts prepended the integrity header to
+ * every compiled file unconditionally — including those same skills.
+ *
+ * Measured 2026-08-17 on five real skills: after compiling, a reader anchored to `^---` finds NO
+ * frontmatter at all. The header was the ENTIRE delta — body byte-identical, section order
+ * untouched — so one misplaced line was the whole reason a compiled skill could not be adopted.
+ *
+ * The header now goes AFTER the frontmatter when there is one. Readers must ask this module where
+ * the header is rather than anchoring their own regex at `^`: four call sites had independently
+ * encoded "first line", and that duplication is what let the invariant drift unnoticed.
+ */
+const FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n/;
+/** Same header, matched where it sits below a frontmatter block (blank line allowed). */
+const HASH_LINE_IN_BODY_RE = /^\s*<!-- vigiles:sha256:([a-f0-9]+) compiled from (.+) -->\r?\n\r?\n?/;
+/**
+ * Split off a leading frontmatter block. `head` is `""` when the file has none, so a caller can
+ * concatenate `head + body` unconditionally and get the original content back.
+ */
+function splitFrontmatter(content) {
+    const m = FRONTMATTER_RE.exec(content);
+    return m
+        ? { head: m[0], body: content.slice(m[0].length) }
+        : { head: "", body: content };
+}
+/**
+ * Locate the integrity header wherever it legitimately sits — before the frontmatter (files
+ * compiled before 2026-08-17) or after it (files compiled since). Returns the hash, the spec
+ * path, and the content with the header removed and everything else intact.
+ *
+ * This is the ONLY place that knows where the header can be. Matching `/^<!-- vigiles:sha256/`
+ * by hand elsewhere is the bug this function exists to make unnecessary.
+ */
+function findIntegrityHeader(content) {
+    const { head, body } = splitFrontmatter(content);
+    // After the frontmatter — the current placement. The leading `\s*` is load-bearing: the header
+    // is written one blank line below the closing `---` for readability, so an anchor at position 0
+    // of the body misses it. A test caught exactly that before it shipped.
+    const inBody = body.match(HASH_LINE_IN_BODY_RE);
+    if (inBody) {
+        return {
+            hash: inBody[1],
+            specFile: inBody[2],
+            withoutHeader: head + body.replace(HASH_LINE_IN_BODY_RE, ""),
+        };
+    }
+    // Or at the very top, which is what a file compiled before the fix looks like. Such a file has
+    // no leading frontmatter by definition — the header displaced it — so `head` is empty here.
+    const atTop = content.match(HASH_LINE_RE);
+    if (!atTop)
+        return null;
+    return {
+        hash: atTop[1],
+        specFile: atTop[2],
+        withoutHeader: content.replace(HASH_LINE_RE, ""),
+    };
+}
+/** Render the header in its correct position for this content. */
+function placeIntegrityHeader(content, hash, specFile) {
+    const stamp = `<!-- vigiles:sha256:${hash} compiled from ${specFile} -->`;
+    const { head, body } = splitFrontmatter(content);
+    return head ? `${head}\n${stamp}\n\n${body}` : `${stamp}\n\n${body}`;
+}
 /**
  * Check whether the compiled markdown's SHA-256 hash matches its body.
  * Files without a hash header are treated as hand-written (intact).
  */
 function checkIntegrity(content) {
-    const match = content.match(HASH_LINE_RE);
-    if (!match) {
+    const found = findIntegrityHeader(content);
+    if (!found) {
         return { intact: true, reason: "No hash header (hand-written file)" };
     }
-    const expectedHash = match[1];
-    const body = content.replace(HASH_LINE_RE, "");
+    const expectedHash = found.hash;
+    const body = found.withoutHeader;
     if ((0, hash_js_1.sha256short)(body) !== expectedHash) {
         return {
             intact: false,
@@ -53,10 +124,10 @@ exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = "<!-- vigiles-disable require-instru
  * header; `null` when the file is plain markdown (no header).
  */
 function parseIntegrityHeader(content) {
-    const match = content.match(HASH_LINE_RE);
-    if (!match)
+    const found = findIntegrityHeader(content);
+    if (!found)
         return null;
-    return { specFile: match[2], body: content.replace(HASH_LINE_RE, "") };
+    return { specFile: found.specFile, body: found.withoutHeader };
 }
 /**
  * "Eject" a compiled instruction file to plain, hand-owned markdown: strip the

package/dist/core/spec.d.ts

@@ -399,12 +399,21 @@ export interface SkillStep {
     /** Max attempts to satisfy the gate before the step fails (default 1). */
     readonly retry?: number;
 }
-/** Declare a skill input (compiles to argument-hint + an Arguments entry). */
-export declare function input(name: string, hint: string, opts?: {
+/**
+ * Declare a skill input (compiles to argument-hint + an Arguments entry).
+ *
+ * Deliberately NOT a standalone export — reached as `experimental_skill.input`.
+ * The reason is on `experimental_skill` below.
+ */
+declare function input(name: string, hint: string, opts?: {
     required?: boolean;
 }): SkillInput;
-/** Declare a gated pipeline step. */
-export declare function step(instr: string | InstructionFragment[], opts?: {
+/**
+ * Declare a gated pipeline step.
+ *
+ * Deliberately NOT a standalone export — reached as `experimental_skill.step`.
+ */
+declare function step(instr: string | InstructionFragment[], opts?: {
     gate?: Gate;
     retry?: number;
 }): SkillStep;
@@ -504,9 +513,32 @@ export type SkillSpecInput<P extends AuthoredPurity | undefined, V extends ToolV
  * DIFFERENT function — a `Check<Trace>` taking an id string, asking whether a
  * skill fired. This one authors a skill; that one observes one.
  *
+ * Its helper vocabulary hangs off it — `experimental_skill.input(…)` and
+ * `experimental_skill.step(…)` — rather than being exported beside it. Both are
+ * used ONLY by skill specs (measured: zero uses in agent/claude specs, against
+ * `cmd`/`file`/`ref`/`result`, which are shared and therefore stay top-level).
+ * Hanging them here makes the experimental marking STRUCTURAL for the whole
+ * family: you cannot reach `input()` without naming `experimental_skill` first.
+ * The prefix convention alone could not do that — it is a habit, and it had
+ * already leaked once when `skill()` shipped stable-named against its own docs.
+ *
+ * Honest limit: `const { input } = experimental_skill` strips the marker again
+ * inside one file. What the shape actually guarantees is narrower and still
+ * worth having — an unmarked name never crosses the package boundary.
+ *
+ * `Object.assign` rather than `export namespace`: the latter is banned by this
+ * repo's own lint (`no-namespace: error`, inherited from strict-type-checked).
+ *
+ * @experimental
+ */
+declare function skillSpec<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary>(spec: SkillSpecInput<P, V>): SkillSpec;
+/**
  * @experimental
  */
-export declare function experimental_skill<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary>(spec: SkillSpecInput<P, V>): SkillSpec;
+export declare const experimental_skill: typeof skillSpec & {
+    input: typeof input;
+    step: typeof step;
+};
 /**
  * A subagent definition (compiles to `agents/<name>.md`). Unlike a skill —
  * reference material the model reads on activation — a subagent is a *delegated

package/dist/core/spec.js

@@ -10,7 +10,7 @@
  *   guidance() — prose only, no mechanical enforcement
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUILTIN_LINTERS = void 0;
+exports.experimental_skill = exports.BUILTIN_LINTERS = void 0;
 exports.enforce = enforce;
 exports.guidance = guidance;
 exports.guard = guard;
@@ -24,9 +24,6 @@ exports.instructions = instructions;
 exports.experimental_effect = experimental_effect;
 exports.claude = claude;
 exports.project = project;
-exports.input = input;
-exports.step = step;
-exports.experimental_skill = experimental_skill;
 exports.agent = agent;
 exports.result = result;
 exports.delegate = delegate;
@@ -222,11 +219,39 @@ function claude(spec) {
 function project(role) {
     return { _ref: "role", role };
 }
-/** Declare a skill input (compiles to argument-hint + an Arguments entry). */
+/**
+ * Declare a skill input (compiles to argument-hint + an Arguments entry).
+ *
+ * Deliberately NOT a standalone export — reached as `experimental_skill.input`.
+ * The reason is on `experimental_skill` below.
+ */
 function input(name, hint, opts = {}) {
+    // 🔴 The types say `string`, and for a USER's spec nothing enforces that: `vigiles compile`
+    // loads `.spec.ts` through tsx, which transpiles and erases types without checking them.
+    // (vigiles's OWN specs are cross-checked by a separate `tsc --noEmit` over a generated
+    // registry — that safety net does not travel to the people compiling their own specs.)
+    //
+    // Measured 2026-08-17: calling `input({ name, description })` — the object form a reader
+    // reasonably guesses — compiled with NO error and wrote this into the shipped SKILL.md:
+    //
+    //     argument-hint: <[object Object]>
+    //     - `$1` **[object Object]** — undefined
+    //
+    // A wrong call became a wrong file, silently. Refusing here makes the mistake loud at the
+    // moment it is made, and the message carries the real signature because "expected string"
+    // alone does not tell the caller what to write instead.
+    const bad = (v) => typeof v !== "string" || v.trim() === "";
+    if (bad(name) || bad(hint)) {
+        throw new TypeError(`input() takes two strings: input(name, hint, opts?) — e.g. input("pattern", "regex to search for").\n` +
+            `  got name=${JSON.stringify(name)}, hint=${JSON.stringify(hint)}`);
+    }
     return { name, hint, required: opts.required };
 }
-/** Declare a gated pipeline step. */
+/**
+ * Declare a gated pipeline step.
+ *
+ * Deliberately NOT a standalone export — reached as `experimental_skill.step`.
+ */
 function step(instr, opts = {}) {
     return { do: instr, gate: opts.gate, retry: opts.retry };
 }
@@ -245,11 +270,31 @@ function step(instr, opts = {}) {
  * DIFFERENT function — a `Check<Trace>` taking an id string, asking whether a
  * skill fired. This one authors a skill; that one observes one.
  *
+ * Its helper vocabulary hangs off it — `experimental_skill.input(…)` and
+ * `experimental_skill.step(…)` — rather than being exported beside it. Both are
+ * used ONLY by skill specs (measured: zero uses in agent/claude specs, against
+ * `cmd`/`file`/`ref`/`result`, which are shared and therefore stay top-level).
+ * Hanging them here makes the experimental marking STRUCTURAL for the whole
+ * family: you cannot reach `input()` without naming `experimental_skill` first.
+ * The prefix convention alone could not do that — it is a habit, and it had
+ * already leaked once when `skill()` shipped stable-named against its own docs.
+ *
+ * Honest limit: `const { input } = experimental_skill` strips the marker again
+ * inside one file. What the shape actually guarantees is narrower and still
+ * worth having — an unmarked name never crosses the package boundary.
+ *
+ * `Object.assign` rather than `export namespace`: the latter is banned by this
+ * repo's own lint (`no-namespace: error`, inherited from strict-type-checked).
+ *
  * @experimental
  */
-function experimental_skill(spec) {
+function skillSpec(spec) {
     return { _specType: "skill", ...spec };
 }
+/**
+ * @experimental
+ */
+exports.experimental_skill = Object.assign(skillSpec, { input, step });
 /**
  * Define a subagent specification (compiles to `agents/<name>.md`).
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "15.4.1",
+  "version": "16.0.1",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",
@@ -89,6 +89,7 @@
     "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json",
     "api:report": "npm run build && node scripts/api-extractor.mjs --local",
     "api:check": "npm run build && node scripts/api-extractor.mjs",
+    "check": "node scripts/check.mjs",
     "docs:check": "npm run build && node scripts/check-doc-imports.mjs . docs README.md",
     "exports:check": "npm run build && node scripts/check-export-prefixes.mjs .",
     "experimental:check": "npm run api:check && node scripts/check-experimental-naming.mjs",
@@ -98,6 +99,7 @@
     "@eslint/js": "^10.0.1",
     "@jackchuka/mdschema": "^0.12.8",
     "@microsoft/api-extractor": "^7.58.9",
+    "@semantic-release/commit-analyzer": "^13.0.1",
     "@types/js-yaml": "^4.0.9",
     "@types/markdown-it": "^14.1.2",
     "@types/minimatch": "^5.1.2",
@@ -105,6 +107,7 @@
     "@typescript-eslint/eslint-plugin": "^8.58.0",
     "@typescript-eslint/parser": "^8.58.0",
     "@vitest/coverage-v8": "^4.1.8",
+    "conventional-changelog-conventionalcommits": "^10.3.0",
     "eslint": "^10.1.0",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-boundaries": "^6.0.2",