vigiles 7.0.0 → 8.0.0

package/dist/core/adopt.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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()`
+ * 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
+ * is "review the diff" — for a well-headed file that diff is small (whitespace +
+ * the canonical `# <target>` h1). The agentic path (the `adopt-spec` skill)
+ * handles irregular prose better; this is the zero-model floor.
+ *
+ * WHY IT ALWAYS COMPILES: the compiler only rejects `#`/`##` headers INSIDE a
+ * section body (sections render as `##`), so we split the file on every `#`/`##`
+ * heading — each becomes its own section, and `###`+ subheadings ride along
+ * inside the body untouched. Reserved lowercase keys
+ * (`commands`/`keyFiles`/`rules`) are never produced (`safeKey`). `guidance()`
+ * vs `enforce()` is deliberately NOT guessed here — that cross-referencing is
+ * `strengthen`'s separate, later job; adoption is lossless transcription.
+ */
+export type AdoptTier = "structured" | "raw";
+export interface AdoptResult {
+    /** Generated `.spec.ts` source (compiles back to ~the original file). */
+    source: string;
+    /**
+     * `structured` = a clean `##`-headed file mapped 1:1 to sections (the diff is
+     * just the canonical h1 + whitespace). `raw` = a heading-less or
+     * intro-bearing file we wrapped under a synthesized `Overview` section —
+     * content is preserved verbatim, but the diff adds a heading, so "review the
+     * diff" matters more.
+     */
+    tier: AdoptTier;
+    /** Number of named sections produced (excluding the auto-rendered h1). */
+    sectionCount: number;
+}
+/**
+ * The intermediate adoption result: the `claude()` 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.
+ */
+export interface AdoptedSpec {
+    target: string;
+    /** Heading → verbatim section body, in document order. */
+    sections: Record<string, string>;
+    /** Set only when a faithful section exceeds the compiler's 200-line guard. */
+    maxSectionLines?: number;
+    tier: AdoptTier;
+}
+/**
+ * Parse an instruction file's markdown into the faithful `claude()` 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
+ *   any, is stripped — we adopt the body)
+ * @param target   the bare target filename (`"CLAUDE.md"` / `"AGENTS.md"`),
+ *   which the compiler renders as the h1
+ */
+export declare function adoptToSpec(markdown: string, target: string): AdoptedSpec;
+/**
+ * Convert an instruction file's markdown into a faithful `claude()` spec source
+ * (the deliverable `init` writes).
+ */
+export declare function adoptMarkdown(markdown: string, target: string): AdoptResult;
+//# sourceMappingURL=adopt.d.ts.map

package/dist/core/adopt.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * 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()`
+ * 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
+ * is "review the diff" — for a well-headed file that diff is small (whitespace +
+ * the canonical `# <target>` h1). The agentic path (the `adopt-spec` skill)
+ * handles irregular prose better; this is the zero-model floor.
+ *
+ * WHY IT ALWAYS COMPILES: the compiler only rejects `#`/`##` headers INSIDE a
+ * section body (sections render as `##`), so we split the file on every `#`/`##`
+ * heading — each becomes its own section, and `###`+ subheadings ride along
+ * inside the body untouched. Reserved lowercase keys
+ * (`commands`/`keyFiles`/`rules`) are never produced (`safeKey`). `guidance()`
+ * vs `enforce()` is deliberately NOT guessed here — that cross-referencing is
+ * `strengthen`'s separate, later job; adoption is lossless transcription.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adoptToSpec = adoptToSpec;
+exports.adoptMarkdown = adoptMarkdown;
+const integrity_js_1 = require("./integrity.js");
+// A top-level heading is `#` or `##` (the levels the compiler reserves for
+// document/section structure). `###`+ stay inside a section body.
+const HEADING_RE = /^ {0,3}(#{1,2})\s+(.*)$/;
+const FENCE_RE = /^ {0,3}(?:`{3,}|~{3,})/;
+// Mirrors compile.ts RESERVED_SECTION_KEYS — keys that clash with the structured
+// `commands`/`keyFiles`/`rules` fields and would be a compile error as a section.
+const RESERVED_SECTION_KEYS = new Set([
+    "commands",
+    "keyFiles",
+    "key-files",
+    "key_files",
+    "rules",
+]);
+/**
+ * Split a markdown body into a leading preamble block plus one block per
+ * top-level (`#`/`##`) heading. Fence-aware, so a `## ` inside a fenced code
+ * block is not a split point (matching the compiler's own section validator).
+ */
+function splitIntoBlocks(body) {
+    const blocks = [];
+    let current = { heading: null, level: null, lines: [] };
+    let inFence = false;
+    for (const line of body.split("\n")) {
+        if (FENCE_RE.test(line)) {
+            inFence = !inFence;
+            current.lines.push(line);
+            continue;
+        }
+        const m = inFence ? null : line.match(HEADING_RE);
+        if (m) {
+            blocks.push(current);
+            current = {
+                heading: m[2].trim(),
+                level: m[1].length,
+                lines: [],
+            };
+        }
+        else {
+            current.lines.push(line);
+        }
+    }
+    blocks.push(current);
+    return blocks;
+}
+/**
+ * Avoid a reserved lowercase section key (`commands`/`rules`/…) by capitalizing
+ * the first letter — which is exactly the heading the compiler renders anyway,
+ * so there's no visible diff.
+ */
+function safeKey(heading) {
+    return RESERVED_SECTION_KEYS.has(heading)
+        ? heading.charAt(0).toUpperCase() + heading.slice(1)
+        : heading;
+}
+/**
+ * Allocate a unique section key, disambiguating a duplicate with ` (2)`, ` (3)`,
+ * … and recording it in `used`. Shared by the real-heading loop and the
+ * synthesized `Overview`, so no two sections collide on one object key (which
+ * would silently drop the earlier one's content).
+ */
+function allocKey(base, used) {
+    let key = base;
+    for (let n = 2; used.has(key); n++)
+        key = `${base} (${n})`;
+    used.add(key);
+    return key;
+}
+/**
+ * Emit a readable multi-line TS template literal for arbitrary section content,
+ * escaping the three sequences that would break it: backslash, backtick, and the
+ * `${` interpolation opener. TS un-escapes them back to the original string, so
+ * the round-trip is exact.
+ */
+function tsTemplate(s) {
+    const esc = s
+        .replace(/\\/g, "\\\\")
+        .replace(/`/g, "\\`")
+        .replace(/\$\{/g, "\\${");
+    return "`" + esc + "`";
+}
+function renderSpecSource(spec) {
+    const targetLine = spec.target !== "CLAUDE.md"
+        ? `\n  target: ${JSON.stringify(spec.target)},`
+        : "";
+    const maxLine = spec.maxSectionLines !== undefined
+        ? `\n  maxSectionLines: ${String(spec.maxSectionLines)},`
+        : "";
+    const entries = Object.entries(spec.sections)
+        .map(([key, content]) => `    ${JSON.stringify(key)}: ${tsTemplate(content)},`)
+        .join("\n");
+    const sectionsBlock = entries
+        ? `\n  sections: {\n${entries}\n  },`
+        : `\n  sections: {},`;
+    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";
+
+export default claude({${targetLine}${maxLine}${sectionsBlock}
+  rules: {},
+});
+`;
+}
+/**
+ * Parse an instruction file's markdown into the faithful `claude()` 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
+ *   any, is stripped — we adopt the body)
+ * @param target   the bare target filename (`"CLAUDE.md"` / `"AGENTS.md"`),
+ *   which the compiler renders as the h1
+ */
+function adoptToSpec(markdown, target) {
+    const header = (0, integrity_js_1.parseIntegrityHeader)(markdown);
+    const body = header ? header.body : markdown;
+    const blocks = splitIntoBlocks(body);
+    const overviewLines = [];
+    const ordered = [];
+    const usedKeys = new Set();
+    let titleConsumed = false;
+    let synthesizedHeading = false;
+    for (const block of blocks) {
+        if (block.level === null) {
+            // Preamble before any heading — has no structural home, so it goes to a
+            // synthesized Overview section.
+            overviewLines.push(...block.lines);
+            continue;
+        }
+        if (!titleConsumed && block.level === 1) {
+            // The document title — the compiler re-renders `# <target>` from the
+            // filename, so drop the heading line; its body (intro prose under the h1)
+            // also has no slot, so it joins Overview.
+            titleConsumed = true;
+            overviewLines.push(...block.lines);
+            continue;
+        }
+        const key = allocKey(safeKey(block.heading ?? ""), usedKeys);
+        ordered.push({ key, content: block.lines.join("\n").trim() });
+    }
+    const overview = overviewLines.join("\n").trim();
+    if (overview) {
+        synthesizedHeading = true;
+        // Allocate the synthesized key with the SAME dedup as real headings, so a
+        // file that already has a literal `## Overview` doesn't collide and silently
+        // drop the intro when the sections object is built (it becomes "Overview (2)").
+        ordered.unshift({ key: allocKey("Overview", usedKeys), content: overview });
+    }
+    const sections = {};
+    for (const { key, content } of ordered)
+        sections[key] = content;
+    // A faithful section can legitimately be long; lift the 200-line guard above
+    // the longest one so adoption never trips it (only when actually needed, so a
+    // normal spec stays free of the override).
+    const longest = ordered.reduce((n, s) => Math.max(n, s.content.split("\n").length), 0);
+    return {
+        target,
+        sections,
+        maxSectionLines: longest > 190 ? longest + 50 : undefined,
+        tier: synthesizedHeading || ordered.length === 0 ? "raw" : "structured",
+    };
+}
+/**
+ * Convert an instruction file's markdown into a faithful `claude()` spec source
+ * (the deliverable `init` writes).
+ */
+function adoptMarkdown(markdown, target) {
+    const spec = adoptToSpec(markdown, target);
+    return {
+        source: renderSpecSource(spec),
+        tier: spec.tier,
+        sectionCount: Object.keys(spec.sections).length,
+    };
+}
+//# sourceMappingURL=adopt.js.map

package/dist/core/compose.d.ts

@@ -62,7 +62,7 @@ export declare function detectSyncTools(root: string): DetectedSyncTool[];
  * content (a sync tool keeping them in lockstep). Claude Code reads CLAUDE.md
  * only ([anthropics/claude-code#34235]); users bridge to the AGENTS.md tools this
  * way (see `research/sync-tool-compatibility.md` requirement 7). When mirrored,
- * vigiles must treat them as the same file — hash + `require-spec` run once on the
+ * vigiles must treat them as the same file — hash + `require-instructions-spec` run once on the
  * real one, and the mirror is never flagged as a second, spec-less instruction
  * file. Returns null when one is absent, or both exist but genuinely differ.
  */

package/dist/core/compose.js

@@ -75,7 +75,7 @@ function targetName(target) {
  * content (a sync tool keeping them in lockstep). Claude Code reads CLAUDE.md
  * only ([anthropics/claude-code#34235]); users bridge to the AGENTS.md tools this
  * way (see `research/sync-tool-compatibility.md` requirement 7). When mirrored,
- * vigiles must treat them as the same file — hash + `require-spec` run once on the
+ * vigiles must treat them as the same file — hash + `require-instructions-spec` run once on the
  * real one, and the mirror is never flagged as a second, spec-less instruction
  * file. Returns null when one is absent, or both exist but genuinely differ.
  */

package/dist/core/evolve.d.ts

@@ -1,6 +1,10 @@
 /**
  * vigiles — Evolution engine for self-evolving specifications.
  *
+ * @internal Research-stage / experimental — NOT exported from any public entry
+ * point and NOT part of the frozen public surface (pre-1.0). Kept for the
+ * self-evolving-specs line; `proofs.ts` (used by ncd / covering-array) stays.
+ *
  * AI agents propose mutations. The engine applies them, runs the proof suite,
  * and only accepts mutations that pass all proofs AND improve fitness.
  *

package/dist/core/evolve.js

@@ -2,6 +2,10 @@
 /**
  * vigiles — Evolution engine for self-evolving specifications.
  *
+ * @internal Research-stage / experimental — NOT exported from any public entry
+ * point and NOT part of the frozen public surface (pre-1.0). Kept for the
+ * self-evolving-specs line; `proofs.ts` (used by ncd / covering-array) stays.
+ *
  * AI agents propose mutations. The engine applies them, runs the proof suite,
  * and only accepts mutations that pass all proofs AND improve fitness.
  *

package/dist/core/frontmatter.d.ts

@@ -1,11 +1,11 @@
 /**
- * vigiles — YAML frontmatter rule mode (Level 1 adoption).
+ * vigiles — YAML frontmatter rule mode.
  *
  * Parses a `vigiles.enforce` block out of a markdown file's YAML
  * frontmatter, so a project can declare enforce rules in structured YAML
- * instead of `<!-- vigiles:enforce ... -->` HTML comments (Level 0) or a
- * typed `.spec.ts` (Level 2). Every frontmatter rule goes through the same
- * `checkLinterRule` verification as inline and spec rules.
+ * instead of `<!-- vigiles:enforce ... -->` inline HTML comments or a typed
+ * `.spec.ts`. Every frontmatter rule goes through the same `checkLinterRule`
+ * verification as inline and spec rules.
  *
  * Shape (verbose — chosen so a JSON Schema can give `rule` an enum that
  * YAML LSP autocompletes and squiggles on typo):
@@ -67,9 +67,10 @@ export interface FrontmatterParseResult {
 export declare function parseFrontmatterRules(content: string): FrontmatterParseResult;
 /**
  * True if the content has at least one parseable `vigiles` reference in its
- * frontmatter — an `enforce` rule, a `files` entry, or a `commands` entry.
- * Used by `require-spec` validation to treat frontmatter mode as
- * spec-equivalent, mirroring `hasInlineRules`.
+ * frontmatter — an `enforce` rule, a `files` entry, or a `commands` entry. A
+ * utility for detecting frontmatter (Level-1) mode, mirroring `hasInlineRules`.
+ * (Note `require-instructions-spec` is narrow — only a `.spec.ts` satisfies it —
+ * so this no longer feeds that rule.)
  */
 export declare function hasFrontmatterRules(content: string): boolean;
 //# sourceMappingURL=frontmatter.d.ts.map

package/dist/core/frontmatter.js

@@ -1,12 +1,12 @@
 "use strict";
 /**
- * vigiles — YAML frontmatter rule mode (Level 1 adoption).
+ * vigiles — YAML frontmatter rule mode.
  *
  * Parses a `vigiles.enforce` block out of a markdown file's YAML
  * frontmatter, so a project can declare enforce rules in structured YAML
- * instead of `<!-- vigiles:enforce ... -->` HTML comments (Level 0) or a
- * typed `.spec.ts` (Level 2). Every frontmatter rule goes through the same
- * `checkLinterRule` verification as inline and spec rules.
+ * instead of `<!-- vigiles:enforce ... -->` inline HTML comments or a typed
+ * `.spec.ts`. Every frontmatter rule goes through the same `checkLinterRule`
+ * verification as inline and spec rules.
  *
  * Shape (verbose — chosen so a JSON Schema can give `rule` an enum that
  * YAML LSP autocompletes and squiggles on typo):
@@ -252,9 +252,10 @@ function parseFrontmatterRules(content) {
 }
 /**
  * True if the content has at least one parseable `vigiles` reference in its
- * frontmatter — an `enforce` rule, a `files` entry, or a `commands` entry.
- * Used by `require-spec` validation to treat frontmatter mode as
- * spec-equivalent, mirroring `hasInlineRules`.
+ * frontmatter — an `enforce` rule, a `files` entry, or a `commands` entry. A
+ * utility for detecting frontmatter (Level-1) mode, mirroring `hasInlineRules`.
+ * (Note `require-instructions-spec` is narrow — only a `.spec.ts` satisfies it —
+ * so this no longer feeds that rule.)
  */
 function hasFrontmatterRules(content) {
     const r = parseFrontmatterRules(content);

package/dist/core/generate-harness.d.ts

@@ -1,5 +1,5 @@
 /**
- * vigiles generate-harness — emit ONE typed registry over the whole harness.
+ * vigiles generate harness — emit ONE typed registry over the whole harness.
  *
  * The third generated artifact beside `generate-types` (`.d.ts`) and
  * `generate-schema` (JSON Schema): a `harness.gen.ts` that imports every

package/dist/core/generate-harness.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * vigiles generate-harness — emit ONE typed registry over the whole harness.
+ * vigiles generate harness — emit ONE typed registry over the whole harness.
  *
  * The third generated artifact beside `generate-types` (`.d.ts`) and
  * `generate-schema` (JSON Schema): a `harness.gen.ts` that imports every
@@ -178,10 +178,10 @@ function generateHarness(model, options) {
         import: relImport(outDir, a.file),
     }));
     const L = [];
-    L.push("// AUTO-GENERATED by `vigiles generate-harness` — DO NOT EDIT.");
+    L.push("// AUTO-GENERATED by `vigiles generate harness` — DO NOT EDIT.");
     L.push("// One typed registry over every *.spec.ts in the harness, so a single");
     L.push("// `tsc --noEmit` cross-checks the WHOLE harness as one program.");
-    L.push("// Regenerate with `vigiles generate-harness` (wired to a spec guard).");
+    L.push("// Regenerate with `vigiles generate harness` (wired to a spec guard).");
     L.push("");
     const handoffs = model.handoffs ?? [];
     const specTypeImports = handoffs.length > 0 ? "KnownAgentName, Handoff, OkOf" : "KnownAgentName";

package/dist/core/generate-schema.js

@@ -75,7 +75,7 @@ function generateSchema(options = {}) {
         $schema: "http://json-schema.org/draft-07/schema#",
         $id: "https://vigiles.dev/frontmatter.schema.json",
         title: "vigiles frontmatter",
-        description: "vigiles enforce rules declared in markdown YAML frontmatter (Level 1).",
+        description: "vigiles enforce rules declared in markdown YAML frontmatter.",
         type: "object",
         properties: {
             vigiles: {

package/dist/core/inline.d.ts

@@ -64,13 +64,13 @@ export declare function parseInlineRules(content: string): InlineParseResult;
 /**
  * True if the content contains at least one parseable vigiles inline marker —
  * an `enforce` rule, a `file` reference, or a `cmd` reference (ignoring fenced
- * code blocks and malformed markers). Used by `require-spec` validation to
- * treat inline mode as spec-equivalent: a file that pins even a single path is
- * meaningfully managed.
+ * code blocks and malformed markers). A utility for detecting whether a file is
+ * inline-managed (Level-0 mode). Deliberately delegates to `parseInlineRules` so
+ * a loose prefix regex can't report a malformed marker that produces no real
+ * reference.
  *
- * Deliberately delegates to `parseInlineRules` so a loose prefix regex
- * can't satisfy require-spec with a malformed marker that produces no
- * real reference.
+ * NB `require-instructions-spec` is NARROW — it is satisfied only by a `.spec.ts`,
+ * not by inline markers — so this no longer feeds that rule.
  */
 export declare function hasInlineRules(content: string): boolean;
 //# sourceMappingURL=inline.d.ts.map

package/dist/core/inline.js

@@ -174,13 +174,13 @@ function parseInlineRules(content) {
 /**
  * True if the content contains at least one parseable vigiles inline marker —
  * an `enforce` rule, a `file` reference, or a `cmd` reference (ignoring fenced
- * code blocks and malformed markers). Used by `require-spec` validation to
- * treat inline mode as spec-equivalent: a file that pins even a single path is
- * meaningfully managed.
+ * code blocks and malformed markers). A utility for detecting whether a file is
+ * inline-managed (Level-0 mode). Deliberately delegates to `parseInlineRules` so
+ * a loose prefix regex can't report a malformed marker that produces no real
+ * reference.
  *
- * Deliberately delegates to `parseInlineRules` so a loose prefix regex
- * can't satisfy require-spec with a malformed marker that produces no
- * real reference.
+ * NB `require-instructions-spec` is NARROW — it is satisfied only by a `.spec.ts`,
+ * not by inline markers — so this no longer feeds that rule.
  */
 function hasInlineRules(content) {
     const r = parseInlineRules(content);

package/dist/core/integrity.d.ts

@@ -26,4 +26,35 @@ export interface IntegrityResult {
  * Files without a hash header are treated as hand-written (intact).
  */
 export declare function checkIntegrity(content: string): IntegrityResult;
+/** The marker that tells `require-instructions-spec` a file is intentionally
+ * hand-owned (no `.spec.ts` expected). */
+export declare const REQUIRE_INSTRUCTIONS_SPEC_DISABLE = "<!-- vigiles-disable require-instructions-spec -->";
+/**
+ * Parse the `vigiles:sha256 … compiled from <spec>` integrity header, if the
+ * file carries one. Returns the referenced spec path and the body below the
+ * header; `null` when the file is plain markdown (no header).
+ */
+export declare function parseIntegrityHeader(content: string): {
+    specFile: string;
+    body: string;
+} | null;
+/**
+ * "Eject" a compiled instruction file to plain, hand-owned markdown: strip the
+ * integrity header so the file is no longer spec-managed, and prepend a
+ * `require-instructions-spec` disable marker so `vigiles lint` won't ask for a
+ * spec back. Pure — the caller writes the file and removes the spec. Returns
+ * `null` when there is no header to strip (nothing to eject). Idempotent: a body
+ * that already carries the marker is not double-marked.
+ *
+ * The disable marker is added ONLY for instruction-file bodies. A compiled
+ * SKILL.md / subagent body begins with YAML frontmatter (`---`) that MUST stay in
+ * first position — prepending an HTML comment there would push the frontmatter
+ * out of the lead block and the harness would lose the skill's name/description/
+ * tools. The marker is also meaningless for those surfaces (require-instructions-
+ * spec doesn't apply to them), so a frontmatter-led body is ejected as-is.
+ */
+export declare function ejectMarkdown(content: string): {
+    markdown: string;
+    specFile: string;
+} | null;
 //# sourceMappingURL=integrity.d.ts.map

package/dist/core/integrity.js

@@ -19,7 +19,10 @@
  *   → CI runs `vigiles compile` then `git diff --exit-code`
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = void 0;
 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?/;
 /**
@@ -41,4 +44,46 @@ function checkIntegrity(content) {
     }
     return { intact: true };
 }
+/** The marker that tells `require-instructions-spec` a file is intentionally
+ * hand-owned (no `.spec.ts` expected). */
+exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = "<!-- vigiles-disable require-instructions-spec -->";
+/**
+ * Parse the `vigiles:sha256 … compiled from <spec>` integrity header, if the
+ * file carries one. Returns the referenced spec path and the body below the
+ * header; `null` when the file is plain markdown (no header).
+ */
+function parseIntegrityHeader(content) {
+    const match = content.match(HASH_LINE_RE);
+    if (!match)
+        return null;
+    return { specFile: match[2], body: content.replace(HASH_LINE_RE, "") };
+}
+/**
+ * "Eject" a compiled instruction file to plain, hand-owned markdown: strip the
+ * integrity header so the file is no longer spec-managed, and prepend a
+ * `require-instructions-spec` disable marker so `vigiles lint` won't ask for a
+ * spec back. Pure — the caller writes the file and removes the spec. Returns
+ * `null` when there is no header to strip (nothing to eject). Idempotent: a body
+ * that already carries the marker is not double-marked.
+ *
+ * The disable marker is added ONLY for instruction-file bodies. A compiled
+ * SKILL.md / subagent body begins with YAML frontmatter (`---`) that MUST stay in
+ * first position — prepending an HTML comment there would push the frontmatter
+ * out of the lead block and the harness would lose the skill's name/description/
+ * tools. The marker is also meaningless for those surfaces (require-instructions-
+ * spec doesn't apply to them), so a frontmatter-led body is ejected as-is.
+ */
+function ejectMarkdown(content) {
+    const parsed = parseIntegrityHeader(content);
+    if (!parsed)
+        return null;
+    // A frontmatter-led body is a skill/agent — strip the header, add nothing.
+    if (/^---\r?\n/.test(parsed.body)) {
+        return { markdown: parsed.body, specFile: parsed.specFile };
+    }
+    const markdown = parsed.body.startsWith(exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE)
+        ? parsed.body
+        : `${exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE}\n\n${parsed.body}`;
+    return { markdown, specFile: parsed.specFile };
+}
 //# sourceMappingURL=integrity.js.map

package/dist/core/orphans.js

@@ -30,7 +30,7 @@ const DEFAULT_IGNORE = [
 ];
 /**
  * A doc carrying this marker opts out of orphan detection — the inline escape
- * hatch, mirroring `vigiles-disable require-spec` and `vigiles:ignore-test`.
+ * hatch, mirroring `vigiles-disable require-instructions-spec` and `vigiles:ignore-test`.
  * Use it for an intentionally-unreferenced doc (a changelog, a top-level index)
  * that nothing else links to but is not rot.
  */