vigiles 38.2.0 → 39.0.0

package/dist/core/hook-delivery.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookOutputDelivery = hookOutputDelivery;
+const event_capability_js_1 = require("./event-capability.js");
+const byteLength = (s) => new TextEncoder().encode(s).length;
+const nonEmpty = (v) => typeof v === "string" && v.trim().length > 0;
+const isRecord = (v) => typeof v === "object" && v !== null;
+function hookSpecific(json) {
+    const h = json?.hookSpecificOutput;
+    return isRecord(h) ? h : {};
+}
+const NONE = { via: [], stranded: [] };
+const reached = (channel) => ({
+    via: [channel],
+    stranded: [],
+});
+const strand = (stream, text, why) => ({ via: [], stranded: [{ stream, bytes: byteLength(text), why }] });
+/** True iff the JSON or the exit code expresses a veto under this protocol. */
+function vetoExpressed(e, f) {
+    const permission = hookSpecific(e.json).permissionDecision;
+    const decision = permission ?? e.json?.decision;
+    const denied = typeof decision === "string" && f.denyDecisionValues.includes(decision);
+    return e.exitCode === f.blockExitCode || denied;
+}
+/** True iff the JSON sets the protocol's halt-the-turn field to false. */
+function haltExpressed(e, f) {
+    return f.haltsTurnField !== undefined && e.json?.[f.haltsTurnField] === false;
+}
+/**
+ * The hook stopped something: a veto on an event that honours one, or a halt
+ * on an event that honours THAT. Two channels, read apart: a halt is not a
+ * veto, and an event can honour either alone (Claude Code's `continue: false`
+ * ends the turn from `PostToolUse`, which vetoes nothing; `PreCompact` vetoes
+ * and discards `continue`).
+ */
+function stopped(e, f, honours) {
+    return ((honours.includes("veto") && vetoExpressed(e, f)) ||
+        (honours.includes("halt") && haltExpressed(e, f)));
+}
+/** Where a non-empty `additionalContext` goes on this event. */
+function contextDelivery(e, honours) {
+    return honours.includes("inject")
+        ? reached("additional-context")
+        : strand("stdout", e.stdout, `\`${e.event}\` does not honour additionalContext — the text is ` +
+            `dropped. Move the hook to an event that injects context.`);
+}
+/** `additionalContext` and a feedback-event `decision` reason, from JSON stdout. */
+function jsonParts(e, f, honours) {
+    if (e.json === null)
+        return [];
+    const context = hookSpecific(e.json).additionalContext;
+    const contextPart = nonEmpty(context) ? contextDelivery(e, honours) : NONE;
+    const decision = e.json.decision;
+    const reasonDelivered = typeof decision === "string" &&
+        f.denyDecisionValues.includes(decision) &&
+        nonEmpty(e.json.reason) &&
+        honours.includes("feedback");
+    return [contextPart, reasonDelivered ? reached("decision-reason") : NONE];
+}
+/** Plain (non-JSON) stdout: context only at exit 0 on a `stdout-context` event. */
+function plainStdoutPart(e, honours) {
+    if (e.json !== null || e.stdout.trim().length === 0)
+        return NONE;
+    if (e.exitCode !== 0) {
+        return strand("stdout", e.stdout, `plain stdout is only ever context at exit 0; this hook exited ` +
+            `${String(e.exitCode)}.`);
+    }
+    return honours.includes("stdout-context")
+        ? reached("plain-stdout")
+        : strand("stdout", e.stdout, `plain stdout on \`${e.event}\` is not added to the model's context ` +
+            `(it goes to the debug log). Emit JSON ` +
+            `\`hookSpecificOutput.additionalContext\` instead.`);
+}
+/** Why stderr reached no channel — an instruction, not a verdict. */
+function stderrWhy(e, f, honours) {
+    const block = String(f.blockExitCode);
+    if (e.exitCode === f.blockExitCode) {
+        return `exit ${block} on \`${e.event}\` neither stops anything nor feeds stderr to the model.`;
+    }
+    if (e.exitCode !== 0) {
+        return `exit ${String(e.exitCode)} is a non-blocking error: at most the first line of stderr is shown to the USER, never to the model.`;
+    }
+    const orExit = honours.includes("feedback")
+        ? `, or exit ${block} (\`${e.event}\` feeds that stderr back to the model)`
+        : "";
+    return `stderr from a hook that exits 0 reaches no channel the model reads. Emit JSON \`hookSpecificOutput.additionalContext\` on stdout${orExit}.`;
+}
+/** stderr: delivered only at the block exit code on a `feedback` event. */
+function stderrPart(e, f, honours) {
+    if (e.stderr.trim().length === 0)
+        return NONE;
+    return e.exitCode === f.blockExitCode && honours.includes("feedback")
+        ? reached("exit-code-feedback")
+        : strand("stderr", e.stderr, stderrWhy(e, f, honours));
+}
+/** The verdict for an event the table has no row for. */
+function unrecordedEvent(e, f) {
+    const legacy = f.table === undefined ? (f.injectableEvents ?? []) : [];
+    if (nonEmpty(hookSpecific(e.json).additionalContext) &&
+        legacy.includes(e.event)) {
+        return { kind: "delivered", via: ["additional-context"], stranded: [] };
+    }
+    const why = e.event === ""
+        ? "the event carries no hook_event_name, so there is no event to judge against"
+        : `the harness's capability table has no row for \`${e.event}\`, so where ` +
+            `its output goes is not recorded — add the row (with its basis) to judge it`;
+    return { kind: "unknown", event: e.event, why };
+}
+/**
+ * Judge one finished hook run. Pure.
+ *
+ * Order matters and is the specification:
+ * 1. nothing printed → `silent` (true on every event, known or not);
+ * 2. no table row → `delivered` only on the one fact the legacy list proves,
+ *    else `unknown`;
+ * 3. a veto on an event that honours one, or a halt on an event that
+ *    honours `halt` → `blocked`;
+ * 4. otherwise collect every channel that carried text, and every stream that
+ *    carried text to no channel; at least one channel → `delivered`. A JSON
+ *    object on stdout is applied on any exit code (the host's exit-code table:
+ *    valid JSON is "Success" at exit 0 and at any other code, and its fields
+ *    are still read at exit 2); plain text is context only at exit 0.
+ */
+function hookOutputDelivery(e, f) {
+    if (e.stdout.trim().length === 0 && e.stderr.trim().length === 0) {
+        return { kind: "silent" };
+    }
+    const verdict = (0, event_capability_js_1.capabilityOf)(f.table, e.event);
+    if (verdict.kind === "unknown")
+        return unrecordedEvent(e, f);
+    const honours = verdict.capability.honours;
+    if (stopped(e, f, honours))
+        return { kind: "blocked", stranded: [] };
+    const parts = [
+        ...jsonParts(e, f, honours),
+        plainStdoutPart(e, honours),
+        stderrPart(e, f, honours),
+    ];
+    const via = parts.flatMap((p) => p.via);
+    const stranded = parts.flatMap((p) => p.stranded);
+    if (via.length > 0)
+        return { kind: "delivered", via, stranded };
+    // Control-only JSON (`permissionDecision: "allow"`, a bare `systemMessage`)
+    // printed something, but nothing addressed to the model — that is silence,
+    // not a stranded nudge.
+    return stranded.length === 0
+        ? { kind: "silent" }
+        : { kind: "undelivered", stranded };
+}
+//# sourceMappingURL=hook-delivery.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * Where compiled hooks and their stamps live — the one owner of these two
+ * paths. A leaf module, so the writer (`compile`), the runtime and the
+ * hook-line plan can all import it without importing each other.
+ */
+/** The directory `compile` reads hook sources from, repo-relative. */
+export declare const HOOKS_DIR = ".vigiles/hooks";
+/**
+ * The stamp sidecar a hook's compile writes, as a repo-relative reference
+ * (`.vigiles/hooks/<basename>.json`). `hookStampPath` resolves it; the hook-line
+ * plan names it.
+ */
+export declare function hookStampRef(hookFile: string): string;
+//# sourceMappingURL=hook-paths.d.ts.map

package/dist/core/hook-paths.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Where compiled hooks and their stamps live — the one owner of these two
+ * paths. A leaf module, so the writer (`compile`), the runtime and the
+ * hook-line plan can all import it without importing each other.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOKS_DIR = void 0;
+exports.hookStampRef = hookStampRef;
+/** The directory `compile` reads hook sources from, repo-relative. */
+exports.HOOKS_DIR = ".vigiles/hooks";
+/**
+ * The stamp sidecar a hook's compile writes, as a repo-relative reference
+ * (`.vigiles/hooks/<basename>.json`). `hookStampPath` resolves it; the hook-line
+ * plan names it.
+ */
+function hookStampRef(hookFile) {
+    // Either separator: a Windows path names the same sidecar.
+    const base = hookFile.replace(/\\/g, "/").split("/").at(-1) ?? hookFile;
+    return `${exports.HOOKS_DIR}/${base}.json`;
+}
+//# sourceMappingURL=hook-paths.js.map

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

@@ -558,7 +558,7 @@ export interface PathView {
      * True iff the path sits under at least one allowed prefix (e.g. "src/**").
      *
      * A prefix is matched in ITS OWN spelling: a repo-relative prefix (`"src"`,
-     * `"migratsiya/papers/"`) is compared against the path made repo-relative, an
+     * `"drafts/papers/"`) is compared against the path made repo-relative, an
      * absolute prefix (`"/etc"`) against the path made absolute. Which of those is
      * available depends on the project root — see {@link pathView}.
      */
@@ -578,9 +578,9 @@ export interface PathView {
  * 🔴 `root` IS NOT OPTIONAL IN PRACTICE — WITHOUT IT THIS IS DEAD FOR EVERY REAL
  * EVENT. Claude Code's Edit/Write/MultiEdit tools always send an ABSOLUTE
  * `file_path`, and every hook in the wild writes repo-relative prefixes
- * (`under(["migratsiya/papers/"])`). Before the root existed, the two could
- * never meet: the comparison ran `"/home/u/repo/migratsiya/papers/x.tex"`
- * against `"migratsiya/papers"` and returned `false` for all input, forever.
+ * (`under(["drafts/papers/"])`). Before the root existed, the two could
+ * never meet: the comparison ran `"/home/u/repo/drafts/papers/x.tex"`
+ * against `"drafts/papers"` and returned `false` for all input, forever.
  * MEASURED 2026-08-12 on the live runtime with one compiled react hook and two
  * spellings of the same file — the relative one printed its checklist, the
  * absolute one exited 0 in silence. Three shipped hooks in a consumer repo were

package/dist/core/hook-program.js

@@ -87,6 +87,7 @@ const tool_contract_js_1 = require("./tool-contract.js");
 const merge_conflict_js_1 = require("./merge-conflict.js");
 const hook_providers_js_1 = require("./hook-providers.js");
 const hook_state_js_1 = require("./hook-state.js");
+const hook_paths_js_1 = require("./hook-paths.js");
 /**
  * Does `name` match a hook's declared tool list, under the SAME semantics as the
  * matcher the compiler emits for it?
@@ -324,8 +325,8 @@ const isAtOrUnder = (rawCandidate, rawBase, insensitive = false) => {
  * Could this path be under this prefix under SOME root or working directory?
  *
  * The tractable stand-in for "unprovable": the prefix's segments occur as a whole
- * contiguous run somewhere in the path. `/home/u/mine/migratsiya/papers/x.tex`
- * could be `migratsiya/papers/x.tex` in a repo rooted at `/home/u/mine`; the
+ * contiguous run somewhere in the path. `/home/u/project/drafts/papers/x.tex`
+ * could be `drafts/papers/x.tex` in a repo rooted at `/home/u/project`; the
  * leading directories are exactly what we cannot rule out without a root.
  *
  * A leading `/` is stripped from the prefix first, so an ABSOLUTE prefix can
@@ -335,8 +336,8 @@ const isAtOrUnder = (rawCandidate, rawBase, insensitive = false) => {
  * ⚠️ WHAT THIS STILL MISSES, stated rather than implied — in both cases the
  * verdict is `"outside"`, so the denylist misses too:
  *
- * 1. The segments must be PRESENT. `cd migratsiya && sed -i s/a/b/ papers/x.tex`
- *    names only `papers/x.tex`, so a prefix of `migratsiya/papers` finds nothing.
+ * 1. The segments must be PRESENT. `cd drafts && sed -i s/a/b/ papers/x.tex`
+ *    names only `papers/x.tex`, so a prefix of `drafts/papers` finds nothing.
  *    Resolving a leaf's argument against a preceding `cd` is a parser change, not
  *    a matcher one; it is the blind spot both shipped guards already document.
  * 2. An ABSOLUTE prefix against a RELATIVE token with NO root — `touches(["/r/
@@ -373,7 +374,7 @@ const mightBeUnder = (path, base, insensitive = false) => {
  *
  * Note what does NOT happen: a placed path that is not under the prefix comes
  * back `"under"`-less but is still offered to `mightBeUnder`, so a denylist
- * over-blocks a sibling checkout's `…/migratsiya/papers/…` rather than silently
+ * over-blocks a sibling checkout's `…/drafts/papers/…` rather than silently
  * allowing it. That over-block is the chosen error direction, not an oversight —
  * `under` never sees it, because `under` accepts `"under"` only.
  */
@@ -466,7 +467,7 @@ function writeTargetsOf(leaf) {
 }
 /**
  * A write target as it lands on disk, given the chdir wrapper the leaf ran under
- * (`env -C migratsiya sed -i s/a/b/ papers/x.tex` writes `migratsiya/papers/x.tex`).
+ * (`env -C drafts sed -i s/a/b/ papers/x.tex` writes `drafts/papers/x.tex`).
  *
  * Absolute targets and `~`-rooted ones already name their directory and are
  * returned untouched. The join itself is {@link resolveRef} rather than a fresh
@@ -562,8 +563,8 @@ function commandView(raw, root) {
         // REAL BYPASS. `leafCommands` keeps a word exactly as written, quotes and
         // all, so a token arrived as `"papers/x.tex"` — with the quote characters —
         // and matched no prefix at all. MEASURED end-to-end on a shipped guard:
-        // `sed -i s/a/b/ migratsiya/papers/x/paper.tex` exited 2 (blocked) while
-        // `sed -i s/a/b/ "migratsiya/papers/x/paper.tex"` exited 0. Quoting a path
+        // `sed -i s/a/b/ drafts/papers/x/paper.tex` exited 2 (blocked) while
+        // `sed -i s/a/b/ "drafts/papers/x/paper.tex"` exited 0. Quoting a path
         // is not an exotic evasion — it is what anyone writes for a path with a
         // space in it, so every denylist built on `touches` was one quote from open.
         // `writesTo` was already correct precisely because it reads `normalized`;
@@ -1020,9 +1021,9 @@ function verifyHookStamp(source, stamp) {
  * 🔴 `root` IS NOT OPTIONAL IN PRACTICE — WITHOUT IT THIS IS DEAD FOR EVERY REAL
  * EVENT. Claude Code's Edit/Write/MultiEdit tools always send an ABSOLUTE
  * `file_path`, and every hook in the wild writes repo-relative prefixes
- * (`under(["migratsiya/papers/"])`). Before the root existed, the two could
- * never meet: the comparison ran `"/home/u/repo/migratsiya/papers/x.tex"`
- * against `"migratsiya/papers"` and returned `false` for all input, forever.
+ * (`under(["drafts/papers/"])`). Before the root existed, the two could
+ * never meet: the comparison ran `"/home/u/repo/drafts/papers/x.tex"`
+ * against `"drafts/papers"` and returned `false` for all input, forever.
  * MEASURED 2026-08-12 on the live runtime with one compiled react hook and two
  * spellings of the same file — the relative one printed its checklist, the
  * absolute one exited 0 in silence. Three shipped hooks in a consumer repo were
@@ -1632,11 +1633,6 @@ function resolveRef(root, ref) {
     const leader = unc ? "//" : joined.startsWith("/") ? "/" : "";
     return leader + out.join("/");
 }
-/** The basename of a path token — the sidecar is keyed by the hook's basename. */
-function basenameOf(token) {
-    const parts = token.replace(/\\/g, "/").split("/");
-    return parts[parts.length - 1] ?? token;
-}
 /**
  * The tool names a repair may arrive under: the ones MEASURED to write a file
  * and carry `file_path`. Everything else is refused, including a name this list
@@ -1702,14 +1698,6 @@ function repairTargetOf(event) {
     const filePath = event.tool_input?.file_path;
     return typeof filePath === "string" ? filePath : null;
 }
-/**
- * The stamp sidecar a hook's compile writes, as a repo-relative reference.
- * Mirrors `hookStampPath` in cli.ts (`.vigiles/hooks/<basename>.json`); kept as a
- * string here because core takes no `node:path`.
- */
-function stampSidecarRef(hookFile) {
-    return `.vigiles/hooks/${basenameOf(hookFile)}.json`;
-}
 /**
  * True when this event IS the author repairing the hook — a FILE WRITE, and only
  * a file write.
@@ -1770,7 +1758,7 @@ function isStampRepairEvent(event, hookFile, repoRoot) {
         return false;
     const target = resolveRef(repoRoot, filePath);
     return (target === resolveRef(repoRoot, hookFile) ||
-        target === resolveRef(repoRoot, stampSidecarRef(hookFile)));
+        target === resolveRef(repoRoot, (0, hook_paths_js_1.hookStampRef)(hookFile)));
 }
 /**
  * True when this event is a load-path REPAIR — a file write, and only a file

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

@@ -13,7 +13,7 @@
  *
  * ## The hole it fills, measured
  *
- * `prefer-compiled-hooks` says a hook should be a typed program the compiler can
+ * `hook-script-exists` says a hook should be a typed program the compiler can
  * check. In the knowledge base this repo dogfoods on, ALL SEVEN advisory hooks
  * were still hand-written shell (measured 2026-08-12), and the reason was uniform:
  * every one of them both READS and WRITES a stamp file.

package/dist/core/hook-state.js

@@ -14,7 +14,7 @@
  *
  * ## The hole it fills, measured
  *
- * `prefer-compiled-hooks` says a hook should be a typed program the compiler can
+ * `hook-script-exists` says a hook should be a typed program the compiler can
  * check. In the knowledge base this repo dogfoods on, ALL SEVEN advisory hooks
  * were still hand-written shell (measured 2026-08-12), and the reason was uniform:
  * every one of them both READS and WRITES a stamp file.

package/dist/core/instruction-remedies.d.ts

@@ -1,4 +1,7 @@
 /**
+ * What a finding about an instruction file tells the reader to DO — the one
+ * owner of that wording, so lint, audit and compile cannot drift apart.
+ *
  * Where always-loaded text can go instead of being deleted.
  *
  * Every finding that says "too much is loaded on every request" — the weight
@@ -10,4 +13,36 @@
  * still fires at the right moment first, deletion last.
  */
 export declare const MOVE_OUT_OF_ALWAYS_LOADED: string;
+/**
+ * The two ways to put a hand-written instruction file under a spec, each said
+ * for what it does. They are not interchangeable: `init --target` is the
+ * deterministic floor (`adoptMarkdown` — every heading becomes a verbatim prose
+ * section, only backticked paths that resolve become checked `file()` refs, no
+ * rule is inferred), while the `adopt-spec` skill is an agent reading the file
+ * and mapping rules, commands and paths to typed calls. The skill is
+ * user-invoked (`disable-model-invocation`), so it has to be asked for.
+ * Neither edits the markdown: switching it to spec-managed is a `compile` the
+ * user runs after reviewing.
+ */
+export declare function adoptInstructionFileRemedy(path: string): string;
+/**
+ * For a file the repository does not own — vendored, a corpus, a fixture: drop
+ * its folder from what vigiles reads. `exclude` is top-level in
+ * `.vigilesrc.json`, and its globs are relative to the repository root.
+ */
+export declare function excludeFolderRemedy(path: string): string;
+/**
+ * For instruction files kept hand-written on purpose (a notes or
+ * knowledge-base folder): turn the rule off for those folders with an
+ * `overrides` entry — the rule keeps guarding every other folder. Off for the
+ * whole repository is the last resort, named last.
+ */
+export declare function keepHandWrittenRemedy(path: string): string;
+/**
+ * Everything a `require-instructions-spec` finding says to do, in the order to
+ * try it: adopt, else exclude what is not yours, else turn the rule off for the
+ * folders that stay hand-written. It is the first finding a new adopter sees,
+ * so it names commands and config, not concepts.
+ */
+export declare function handWrittenInstructionRemedy(path: string): string;
 //# sourceMappingURL=instruction-remedies.d.ts.map

package/dist/core/instruction-remedies.js

@@ -1,7 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MOVE_OUT_OF_ALWAYS_LOADED = void 0;
+exports.adoptInstructionFileRemedy = adoptInstructionFileRemedy;
+exports.excludeFolderRemedy = excludeFolderRemedy;
+exports.keepHandWrittenRemedy = keepHandWrittenRemedy;
+exports.handWrittenInstructionRemedy = handWrittenInstructionRemedy;
 /**
+ * What a finding about an instruction file tells the reader to DO — the one
+ * owner of that wording, so lint, audit and compile cannot drift apart.
+ *
  * Where always-loaded text can go instead of being deleted.
  *
  * Every finding that says "too much is loaded on every request" — the weight
@@ -18,7 +25,69 @@ exports.MOVE_OUT_OF_ALWAYS_LOADED = [
     "  - a step tied to one action → a hook",
     "  - a procedure for one kind of task → a skill",
     "  - a fact a machine can check → a lint rule or a test, then delete the prose",
-    "  - measurements and history → docs, linked, not loaded",
+    "  - history → git: link the commit, do not copy its text",
+    "  - a measurement → next to the check that measures it",
     "  - text another file already says → delete it",
 ].join("\n");
+/**
+ * The two ways to put a hand-written instruction file under a spec, each said
+ * for what it does. They are not interchangeable: `init --target` is the
+ * deterministic floor (`adoptMarkdown` — every heading becomes a verbatim prose
+ * section, only backticked paths that resolve become checked `file()` refs, no
+ * rule is inferred), while the `adopt-spec` skill is an agent reading the file
+ * and mapping rules, commands and paths to typed calls. The skill is
+ * user-invoked (`disable-model-invocation`), so it has to be asked for.
+ * Neither edits the markdown: switching it to spec-managed is a `compile` the
+ * user runs after reviewing.
+ */
+function adoptInstructionFileRemedy(path) {
+    return [
+        `Adopt it into a spec, one of two ways:`,
+        `  - the \`adopt-spec\` skill — ask your agent to run it on ${path} (it never fires by itself): the agent maps rules to guidance()/enforce(), commands to cmd() and paths to file(), and shows you the spec before writing it`,
+        `  - \`npx vigiles init --target=${path}\` — no agent, immediate: copies every section verbatim as prose; only paths that resolve become checked file() refs, rules stay prose`,
+        `  Neither edits ${path}. Review the spec, then run \`npx vigiles compile\`.`,
+    ].join("\n");
+}
+/** The folder of a repository-relative path, as a root-relative glob. */
+function folderGlob(path) {
+    const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+    return dir === "" ? "<folder>/**" : `${dir}/**`;
+}
+/**
+ * For a file the repository does not own — vendored, a corpus, a fixture: drop
+ * its folder from what vigiles reads. `exclude` is top-level in
+ * `.vigilesrc.json`, and its globs are relative to the repository root.
+ */
+function excludeFolderRemedy(path) {
+    return [
+        `Not your file (vendored, a corpus, a fixture)? Exclude its folder in .vigilesrc.json:`,
+        `    { "exclude": ["${folderGlob(path)}"] }`,
+    ].join("\n");
+}
+/**
+ * For instruction files kept hand-written on purpose (a notes or
+ * knowledge-base folder): turn the rule off for those folders with an
+ * `overrides` entry — the rule keeps guarding every other folder. Off for the
+ * whole repository is the last resort, named last.
+ */
+function keepHandWrittenRemedy(path) {
+    return [
+        `Keeping instruction files hand-written on purpose (a notes or knowledge-base folder)? Turn the rule off for those folders in .vigilesrc.json:`,
+        `    { "overrides": [{ "files": ["${folderGlob(path)}"], "rules": { "require-instructions-spec": "off" } }] }`,
+        `  Only if no instruction file in the repository should have a spec: { "rules": { "require-instructions-spec": "off" } }`,
+    ].join("\n");
+}
+/**
+ * Everything a `require-instructions-spec` finding says to do, in the order to
+ * try it: adopt, else exclude what is not yours, else turn the rule off for the
+ * folders that stay hand-written. It is the first finding a new adopter sees,
+ * so it names commands and config, not concepts.
+ */
+function handWrittenInstructionRemedy(path) {
+    return [
+        `1. ${adoptInstructionFileRemedy(path)}`,
+        `2. ${excludeFolderRemedy(path)}`,
+        `3. ${keepHandWrittenRemedy(path)}`,
+    ].join("\n");
+}
 //# sourceMappingURL=instruction-remedies.js.map

package/dist/core/integrity-header.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Where the vigiles integrity header sits in a file, and whether an
+ * instruction file is under a spec — the node-free half of `integrity.ts`.
+ *
+ * Split out (like `assert-never.ts` from `hash.ts`) so the browser scan twin
+ * can read these facts without `node:crypto`; `integrity.ts` re-exports all of
+ * it, so callers import from there as before.
+ */
+/**
+ * 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): Readonly<{
+    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): Readonly<{
+    hash: string;
+    specFile: string;
+    /** `content` minus the header, frontmatter still in place. */
+    withoutHeader: string;
+}> | null;
+/** 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 -->";
+/**
+ * Whether an instruction file is under a spec, opted out of one, or neither.
+ *
+ * 🔴 THE ONE ANSWER to "is this instruction file hand-written?". `lint`'s
+ * `require-instructions-spec`, `audit`'s adoption list and the scan's
+ * `Instructions:` line each used to decide it with their own test — a sibling
+ * spec only, a spec or a compiled header, with or without the marker — so the
+ * same repo could be one hand-written file to `audit` and six to `lint`.
+ *
+ * - `spec-managed`: a sibling `<file>.spec.ts`, or a compiled integrity header
+ *   (a multi-target file such as `AGENTS.md` compiled from `CLAUDE.md.spec.ts`
+ *   has no sibling spec and is still compiled);
+ * - `opted-out`: the {@link REQUIRE_INSTRUCTIONS_SPEC_DISABLE} marker — kept
+ *   hand-written on purpose, and that decision is remembered;
+ * - `hand-written`: neither.
+ *
+ * Pure: the caller says whether the sibling spec exists.
+ */
+export type InstructionSpecState = "spec-managed" | "opted-out" | "hand-written";
+export declare function instructionSpecState(content: string, siblingSpecExists: boolean): InstructionSpecState;
+//# sourceMappingURL=integrity-header.d.ts.map

package/dist/core/integrity-header.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Where the vigiles integrity header sits in a file, and whether an
+ * instruction file is under a spec — the node-free half of `integrity.ts`.
+ *
+ * Split out (like `assert-never.ts` from `hash.ts`) so the browser scan twin
+ * can read these facts without `node:crypto`; `integrity.ts` re-exports all of
+ * it, so callers import from there as before.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRE_INSTRUCTIONS_SPEC_DISABLE = void 0;
+exports.splitFrontmatter = splitFrontmatter;
+exports.findIntegrityHeader = findIntegrityHeader;
+exports.instructionSpecState = instructionSpecState;
+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, ""),
+    };
+}
+/** 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 -->";
+/** The disable marker as written by hand: whitespace inside the comment varies. */
+const REQUIRE_INSTRUCTIONS_SPEC_DISABLE_RE = /<!--\s*vigiles-disable\s+require-instructions-spec\s*-->/;
+function instructionSpecState(content, siblingSpecExists) {
+    if (siblingSpecExists || findIntegrityHeader(content) !== null)
+        return "spec-managed";
+    if (REQUIRE_INSTRUCTIONS_SPEC_DISABLE_RE.test(content))
+        return "opted-out";
+    return "hand-written";
+}
+//# sourceMappingURL=integrity-header.js.map

package/dist/core/integrity.d.ts

@@ -17,28 +17,7 @@
  * - "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;
+export { splitFrontmatter, findIntegrityHeader, REQUIRE_INSTRUCTIONS_SPEC_DISABLE, instructionSpecState, type InstructionSpecState, } from "./integrity-header.js";
 /** Render the header in its correct position for this content. */
 export declare function placeIntegrityHeader(content: string, hash: string, specFile: string): string;
 export interface IntegrityResult {
@@ -50,9 +29,6 @@ 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