vigiles 16.0.0 → 16.0.1

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.js

@@ -226,6 +226,25 @@ function project(role) {
  * 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 };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "16.0.0",
+  "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",