vigiles 7.0.0 → 9.0.0

package/dist/core/spec.d.ts

@@ -135,7 +135,7 @@ export declare function guidance(text: string): GuidanceRule;
  * Declare a reactive guard: runs a command when watched files change.
  *
  *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
- *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate types" }, "Regen types")
  */
 export declare function guard(options: {
     watch: string | readonly string[];
@@ -237,6 +237,9 @@ export declare function glob(pattern: string): GlobRef;
  * the region the unit is treated as read-only (the `"pure"` effective floor),
  * inside it the declared purity floor applies. The position-aware companion to
  * the per-call `purity` floor. See `research/effect-boundary-design.md`.
+ *
+ * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * may change or be removed without a major bump pre-1.0.
  */
 export interface EffectRegion {
     readonly _ref: "effect";
@@ -269,6 +272,9 @@ export declare function instructions(strings: TemplateStringsArray, ...values: I
  * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
  * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
  * surface — it does not block on it.
+ *
+ * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * may change or be removed without a major bump pre-1.0.
  */
 export declare function effect(strings: TemplateStringsArray, ...values: InstructionFragment[]): EffectRegion;
 /**
@@ -732,6 +738,9 @@ export declare function railway(spec: Omit<Railway, "_specType">): Railway;
  * Declared via `needs(...)` and threaded into the typed agent so `pipe` can
  * cross-reference it. Independent of `result()` (the output) — an agent both
  * `needs` an input shape and produces an `ok`/`err` output shape.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type NeedsContract<N extends Shape> = N;
 /**
@@ -740,12 +749,18 @@ export type NeedsContract<N extends Shape> = N;
  * step with no upstream requirement — valid as the FIRST step of a pipeline.
  *
  *   needs({ plan: "string", files: "string[]" })
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function needs<const N extends Shape>(shape: N): NeedsContract<N>;
 /**
  * A typed pipeline step: a `TypedAgentSpec` paired with the input `needs` it
  * reads from the prior step's `ok`. `step()` builds one; `pipe` checks that the
  * prior step's `ok` shape supplies this step's `needs`.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape> {
     readonly _step: "typed-delegate";
@@ -758,6 +773,9 @@ export interface PipeStep<Needs extends Shape, Ok extends Shape, Err extends Sha
  * second is the `needs(...)` input contract.
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function pipeStep<Needs extends Shape, Ok extends Shape, Err extends Shape>(a: TypedAgentSpec<Ok, Err>, needsContract?: Needs): PipeStep<Needs, Ok, Err>;
 /**
@@ -766,6 +784,9 @@ export declare function pipeStep<Needs extends Shape, Ok extends Shape, Err exte
  * descriptive error object naming the offending field (`__missing` /
  * `__mismatch`), which surfaces at the mismatched call. Shallow (a per-field
  * mapped type, not a recursion) to avoid TS2589.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type Supplies<Producer extends Shape, Consumer extends Shape> = {
     [K in keyof Consumer]: K extends keyof Producer ? Producer[K] extends Consumer[K] ? true : {
@@ -788,12 +809,17 @@ export type Supplies<Producer extends Shape, Consumer extends Shape> = {
  * assigning `true` to it is a `tsc` error at edit time. Shallow (one wrap over
  * the per-field `Supplies` mapped type, no recursion); the generator emits one
  * assertion per consecutive step pair (O(N)), keeping clear of TS2589.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type Handoff<Producer extends Shape, Consumer extends Shape> = Supplies<Producer, Consumer> extends true ? true : {
     readonly __handoff_error: Supplies<Producer, Consumer>;
 };
 /** A typed pipeline value — carries the LAST step's `ok` and the UNION of every
- *  step's `err` (any step can short-circuit to the error track). */
+ *  step's `err` (any step can short-circuit to the error track).
+ *  @internal Experimental typed-composition surface — NOT part of the frozen
+ *  public API (pre-1.0); may change without a major bump. */
 export interface Pipeline<Ok extends Shape, Err extends Shape> {
     readonly _specType: "pipeline";
     /** Ordered agent names — the resolved compose order. */
@@ -809,6 +835,9 @@ export interface Pipeline<Ok extends Shape, Err extends Shape> {
  * Begin a typed pipeline from its first step. The first step has no upstream, so
  * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
  * carrying that step's `ok`/`err` forward.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function start<Ok extends Shape, Err extends Shape>(first: PipeStep<Record<string, never>, Ok, Err> | TypedAgentSpec<Ok, Err>): Pipeline<Ok, Err>;
 /**
@@ -821,6 +850,9 @@ export declare function start<Ok extends Shape, Err extends Shape>(first: PipeSt
  * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
  * exporting a function called `then` becomes a thenable, so `await import()` of
  * any barrel re-exporting it would invoke it — a footgun the rename avoids.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function andThen<PriorOk extends Shape, PriorErr extends Shape, Needs extends Shape, Ok extends Shape, Err extends Shape>(prior: Pipeline<PriorOk, PriorErr>, next: Supplies<PriorOk, Needs> extends true ? PipeStep<Needs, Ok, Err> : {
     readonly __HANDOFF_ERROR: Supplies<PriorOk, Needs>;
@@ -841,6 +873,9 @@ export declare function andThen<PriorOk extends Shape, PriorErr extends Shape, N
  *     pipeStep(implementer, needs({ plan: "string", files: "string[]" })),
  *     pipeStep(reviewer, needs({ diff: "string" })),
  *   ) // ← won't compile if a handoff doesn't line up
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export declare function pipe<A extends Shape, AE extends Shape>(a: TypedAgentSpec<A, AE>): Pipeline<A, AE>;
 export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape, B extends Shape, BE extends Shape>(a: TypedAgentSpec<A, AE>, b: Supplies<A, BN> extends true ? PipeStep<BN, B, BE> : {
@@ -866,6 +901,9 @@ export declare function pipe<A extends Shape, AE extends Shape, BN extends Shape
  * object naming the dangling target + the railway it came from — so assigning
  * `true` to it is a `tsc` error at edit time. Shallow (one conditional, no
  * recursion); the generator emits one assertion per edge (O(N)).
+ *
+ * @internal Experimental whole-harness-codegen surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 export type KnownAgentName<Target extends string, Names extends string, From extends string = string> = [Target] extends [Names] ? true : {
     readonly __dangling_delegate: Target;

package/dist/core/spec.js

@@ -73,7 +73,7 @@ function guidance(text) {
  * Declare a reactive guard: runs a command when watched files change.
  *
  *   guard({ watch: "*.spec.ts", run: "npx vigiles compile" }, "Recompile on spec change")
- *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" }, "Regen types")
+ *   guard({ watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate types" }, "Regen types")
  */
 function guard(options, description) {
     return {
@@ -166,6 +166,9 @@ function instructions(strings, ...values) {
  * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
  * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
  * surface — it does not block on it.
+ *
+ * @internal Experimental (parked P3) — NOT part of the frozen public surface;
+ * may change or be removed without a major bump pre-1.0.
  */
 function effect(strings, ...values) {
     const body = [];
@@ -304,6 +307,9 @@ function railway(spec) {
  * step with no upstream requirement — valid as the FIRST step of a pipeline.
  *
  *   needs({ plan: "string", files: "string[]" })
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function needs(shape) {
     return shape;
@@ -314,6 +320,9 @@ function needs(shape) {
  * second is the `needs(...)` input contract.
  *
  *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function pipeStep(a, needsContract = {}) {
     return { _step: "typed-delegate", agent: a, needs: needsContract };
@@ -322,6 +331,9 @@ function pipeStep(a, needsContract = {}) {
  * Begin a typed pipeline from its first step. The first step has no upstream, so
  * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
  * carrying that step's `ok`/`err` forward.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function start(first) {
     const step = "_step" in first ? first : pipeStep(first, {});
@@ -347,6 +359,9 @@ function start(first) {
  * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
  * exporting a function called `then` becomes a thenable, so `await import()` of
  * any barrel re-exporting it would invoke it — a footgun the rename avoids.
+ *
+ * @internal Experimental typed-composition surface — NOT part of the frozen
+ * public API (pre-1.0); may change without a major bump.
  */
 function andThen(prior, next) {
     const real = next;

package/dist/core/types.d.ts

@@ -82,12 +82,23 @@ export interface TestCoverageConfig {
     exclude?: readonly string[];
 }
 export interface RulesConfig {
-    /** Require .spec.ts for CLAUDE.md / AGENTS.md. Default: "warn". */
-    "require-spec"?: RuleSeverity;
     /**
-     * @deprecated Skills are legitimately hand-written; use `untested-skill`
-     * ("every skill ships with a test/eval") instead. Default: false (off). The
-     * check still runs if you set this explicitly.
+     * Require a `.spec.ts` behind each instruction file (CLAUDE.md / AGENTS.md) —
+     * the file must be compiled from a typed spec, not hand-written. NARROW: only a
+     * `.spec.ts` sibling (or an explicit `<!-- vigiles-disable
+     * require-instructions-spec -->` marker) satisfies it; inline
+     * `<!-- vigiles:enforce -->` comments do NOT (the rule name says "spec"). Default:
+     * "warn". `vigiles init` auto-adopts every instruction file into a spec, so this
+     * is GREEN by construction after setup — a safety net for a NEW hand-added file,
+     * not a nag. The workflow-tier opt-in (gated under `--strict`).
+     */
+    "require-instructions-spec"?: RuleSeverity;
+    /**
+     * Require a `.spec.ts` behind each SKILL.md — the consistent
+     * `require-<surface>-spec` parallel to `require-instructions-spec`. Default:
+     * false (OFF): skills are legitimately hand-written, and the coverage that
+     * matters ("every skill ships with a test/eval") is the `untested-skill` rule.
+     * Set it explicitly if your team wants every skill spec-managed.
      */
     "require-skill-spec"?: RuleSeverity;
     /** Detect hand-edits to compiled markdown via SHA-256 hash. Default: "warn". */
@@ -161,6 +172,18 @@ export interface RulesConfig {
      * "warn"; "error" gates CI. Same detector as `scan` (hooks status "missing").
      */
     "hook-script-exists"?: RuleSeverity;
+    /**
+     * A single repo-level RECOMMENDATION (one finding regardless of hook count):
+     * when a plugin/repo ships hand-written hook commands that aren't compiled
+     * `vigiles/hook` artifacts, nudge toward compiled hooks — they make whole hook
+     * bug classes (exit-1-not-2, wrong decision field, matcher bypass) UNREPRESENTABLE
+     * at authoring time, and `guardrail-check` proves an existing one blocks. A
+     * discovery nudge, not a defect: the hand-written shell lane stays first-class,
+     * so it's opt-out and fires ONCE (never per-hook). The message links
+     * `docs/compiled-hooks.md`. Default "warn"; set "off" to silence or "error" to
+     * enforce. Same detector as `scan` (manualHookCount).
+     */
+    "prefer-compiled-hooks"?: RuleSeverity;
     /**
      * Cross-reference a subagent's `disallowedTools:` block-list against the
      * catalog — the deny-side mirror of `subagent-tool-contract`. A close typo there
@@ -226,7 +249,8 @@ export interface VigilesConfig {
      * (tsconfig-style, relative to the repo root). Use it for vendored or
      * benchmark fixtures the repo's own lint shouldn't police — e.g.
      * `["bench/**"]` so a third-party `CLAUDE.md` injected verbatim as a benchmark
-     * arm isn't held to `require-spec`. `node_modules`/`dist` are always excluded.
+     * arm isn't held to `require-instructions-spec`. `node_modules`/`dist` are always
+     * excluded.
      */
     exclude?: readonly string[];
     /**
@@ -239,6 +263,18 @@ export interface VigilesConfig {
      * `"claude-code"`. See research/multi-harness-compile.md.
      */
     harness?: string | string[];
+    /**
+     * `vigiles audit` preferences. `measure` is the sticky remembered answer to the
+     * "run the executing checks against your harness?" prompt — at a TTY `audit`
+     * asks once, then records the choice here so it never asks again. `true` runs
+     * the executing checks (safety battery · live MCP · skill firing) on every
+     * interactive run, `false` keeps them off (edit this key to change). Written by
+     * the audit consent prompt, not `init`. Headless runs never execute regardless
+     * (audit is a local report, not a CI step — there is no execution flag).
+     */
+    audit?: {
+        measure?: boolean;
+    };
 }
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";

package/dist/core/validate.js

@@ -11,8 +11,6 @@ const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
 const node_path_1 = require("node:path");
 const cosmiconfig_1 = require("cosmiconfig");
-const inline_js_1 = require("./inline.js");
-const frontmatter_js_1 = require("./frontmatter.js");
 // ---------------------------------------------------------------------------
 // Constants & regex
 // ---------------------------------------------------------------------------
@@ -31,13 +29,13 @@ const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
 const DEFAULT_RULES = {
-    "require-spec": "warn",
-    // DEPRECATED — default OFF. Skills are legitimately hand-written (Level 0/1),
-    // so requiring a .spec.ts per SKILL.md was the wrong constraint and only added
-    // noise (it also nagged about vendored/fixture/bench skills). Use the
-    // `untested-*` rules instead — "every skill/agent/hook ships with a test or
-    // eval" is the coverage that matters. The implementation is kept: setting
-    // `require-skill-spec` explicitly still works for anyone who wants it.
+    "require-instructions-spec": "warn",
+    // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
+    // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong
+    // default (it would nag about vendored/fixture/bench skills); the coverage that
+    // matters is the `untested-*` rules ("every skill/agent/hook ships with a test
+    // or eval"). Set `require-skill-spec` explicitly if your team wants every skill
+    // spec-managed.
     "require-skill-spec": false,
     integrity: "warn",
     coverage: false,
@@ -60,6 +58,10 @@ const DEFAULT_RULES = {
     "mcp-tool-resolves": "warn",
     // A hook script referenced but missing never runs — on by default at warn.
     "hook-script-exists": "warn",
+    // Discovery nudge toward compiled hooks (one finding) — default OFF: it's a
+    // recommendation, not a defect (the hand-written shell lane stays first-class),
+    // so it shouldn't fire unasked. Set "warn"/"error" to opt in.
+    "prefer-compiled-hooks": false,
     // High-precision (close-typo only) deny-list mirror of subagent-tool-contract.
     "disallowed-tools-contract": "warn",
     // Deterministic NCD precision proxy (near-identical skill descriptions) — warn.
@@ -176,26 +178,25 @@ function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect
     const missingCount = parsedRules.filter((r) => r.enforcement === "missing").length;
     const errors = [];
     const warnings = [];
-    const disableComment = /<!--\s*vigiles-disable\s+require-spec\s*-->/;
+    const disableComment = /<!--\s*vigiles-disable\s+require-instructions-spec\s*-->/;
     if (filePath) {
         const basename = (0, node_path_1.basename)(filePath);
         const recognized = dialect?.instructionTargets ?? INSTRUCTION_FILES;
         const isInstruction = recognized.includes(basename);
         const isSkill = basename === "SKILL.md";
-        // --- require-spec (CLAUDE.md / AGENTS.md) ---
-        const specSeverity = activeRules["require-spec"];
+        // --- require-instructions-spec (CLAUDE.md / AGENTS.md) ---
+        // NARROW: only a `.spec.ts` sibling satisfies it. The rule name says "spec",
+        // so inline `<!-- vigiles:enforce -->` / `vigiles:` frontmatter do NOT count
+        // (a user on inline mode keeps this rule off — it's a workflow-tier opt-in).
+        // `vigiles init` auto-adopts every instruction file into a spec, so this is
+        // green by construction after setup.
+        const specSeverity = activeRules["require-instructions-spec"];
         if (specSeverity && isInstruction && !disableComment.test(content)) {
             const specPath = filePath + ".spec.ts";
-            // Inline mode counts as a spec — any parseable
-            // `<!-- vigiles:enforce ... -->` comment means the file is
-            // verified on `vigiles lint` even without a .spec.ts sibling.
-            // Delegate to the real parser so a malformed marker can't
-            // satisfy require-spec with a rule that lint can't verify.
-            const hasInline = (0, inline_js_1.hasInlineRules)(content) || (0, frontmatter_js_1.hasFrontmatterRules)(content);
-            if (!(0, node_fs_1.existsSync)(specPath) && !hasInline) {
+            if (!(0, node_fs_1.existsSync)(specPath)) {
                 const msg = {
-                    rule: "require-spec",
-                    message: `No spec file found for "${filePath}". Expected "${specPath}". Run \`npx vigiles init --target=${filePath}\` to create one, add inline \`<!-- vigiles:enforce ... -->\` comments or a \`vigiles:\` frontmatter block, or disable with <!-- vigiles-disable require-spec -->.`,
+                    rule: "require-instructions-spec",
+                    message: `No spec file found for "${filePath}". Expected "${specPath}". Run \`npx vigiles init --target=${filePath}\` to adopt it into a spec, or disable with <!-- vigiles-disable require-instructions-spec -->.`,
                     line: 1,
                 };
                 if (specSeverity === "error") {
@@ -206,9 +207,8 @@ function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect
                 }
             }
         }
-        // --- require-skill-spec (SKILL.md) — DEPRECATED but still honored when a
-        // user sets it explicitly, so reading the deprecated key here is intentional.
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        // --- require-skill-spec (SKILL.md) — the consistent require-<surface>-spec
+        // parallel, off by default; honored when a user sets it explicitly.
         const skillSeverity = activeRules["require-skill-spec"];
         if (skillSeverity && isSkill && !disableComment.test(content)) {
             const specPath = filePath + ".spec.ts";
@@ -302,7 +302,7 @@ function validatePaths(paths, { followSymlinks = false, ruleMarkers, rules: rule
     let allValid = true;
     // Maps a real (symlink-resolved) path → the first path validated for it, so a
     // symlinked/synced CLAUDE.md⇄AGENTS.md mirror is validated ONCE on the real
-    // file instead of double-firing require-spec on the mirror's name (sync-tool-
+    // file instead of double-firing require-instructions-spec on the mirror's name (sync-tool-
     // compatibility.md req 7). Recorded only on a successful validation, so a
     // symlink seen first (and skipped) never shadows its real target.
     const seenReal = new Map();
@@ -338,7 +338,7 @@ function validatePaths(paths, { followSymlinks = false, ruleMarkers, rules: rule
                 allValid = false;
             continue;
         }
-        // Attribute require-spec/integrity to the REAL file when this path is a
+        // Attribute require-instructions-spec/integrity to the REAL file when this path is a
         // symlink, so a symlinked AGENTS.md resolves to CLAUDE.md's spec rather than
         // a nonexistent AGENTS.md.spec.ts. Non-symlinks keep the original path
         // verbatim (behaviour-preserving).

package/dist/dialect-drift.js

@@ -40,7 +40,7 @@ exports.formatDialectDrift = formatDialectDrift;
  *
  * Pure parsers (testable with fixtures) + a local-install locator. TWO consumers:
  * the gated CI test in `dialect-drift.test.ts` (fails loud on tool/event drift), and
- * `vigiles scan` at runtime via `checkDialectDrift`/`formatDialectDrift` (a best-effort,
+ * `vigiles audit` at runtime via `checkDialectDrift`/`formatDialectDrift` (a best-effort,
  * read-local freshness WARN when the installed CC's tool surface drifts from ours).
  */
 const node_fs_1 = require("node:fs");

package/dist/eval.d.ts

@@ -251,7 +251,7 @@ export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
  */
 export declare function resolveSpawnEnv(a: Pick<AgentRunArgs, "env" | "replaceEnv">, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. `scan --trigger`) bind the same runner. */
+ *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
 export declare function spawnAgent(a: AgentRunArgs): Promise<RunOut>;
 /**
  * Run the eval: every arm × every trial against the real `claude` CLI, with the

package/dist/eval.js

@@ -96,7 +96,7 @@ function resolveSpawnEnv(a, base = process.env) {
 }
 /* v8 ignore start -- real claude subprocess; exercised by bench/, not the unit gate */
 /** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. `scan --trigger`) bind the same runner. */
+ *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
 function spawnAgent(a) {
     return new Promise((resolvePromise) => {
         const args = [

package/dist/guardrail-check.d.ts

@@ -75,7 +75,7 @@ export declare function unblockedDisasters(results: readonly GuardrailResult[]):
  */
 export declare function assertBlocksDisasters(hookCommand: string, opts?: VerifyGuardrailOptions): void;
 /**
- * Render a coverage report (Level 0 — informational, NEUTRAL). It reports what the
+ * Render a coverage report (informational, NEUTRAL). It reports what the
  * hook blocks WITHOUT judging it: a hook that allows these may simply not be a
  * bash-safety guard (our own pre-edit.sh blocks .md edits, not `rm -rf`). The
  * "false confidence" verdict only applies once intent is DECLARED — see

package/dist/guardrail-check.js

@@ -131,7 +131,7 @@ function assertBlocksDisasters(hookCommand, opts = {}) {
     throw new Error(`Guardrail \`${hookCommand}\` did NOT block ${misses.length} dangerous action(s):\n${lines.join("\n")}\nA hook that doesn't block these is false confidence — fix it (PreToolUse + exit 2).`);
 }
 /**
- * Render a coverage report (Level 0 — informational, NEUTRAL). It reports what the
+ * Render a coverage report (informational, NEUTRAL). It reports what the
  * hook blocks WITHOUT judging it: a hook that allows these may simply not be a
  * bash-safety guard (our own pre-edit.sh blocks .md edits, not `rm -rf`). The
  * "false confidence" verdict only applies once intent is DECLARED — see

package/dist/optimize.d.ts

@@ -1,9 +1,9 @@
 /**
- * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
- * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
- * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
- * a separate command, so it's folded into scan as one more view on the same
- * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ * The per-repo harness optimizer's DETERMINISTIC spine — folded INLINE into the
+ * default `vigiles audit` report (each finding carries its fix; NOT its own
+ * `optimize` verb, and no longer a `--fix-plan` flag: until the measured A/B half
+ * lands, an "optimizer" that only re-prints audit's findings doesn't earn a
+ * separate surface; see research/roadmap.md §P2 "reconsider an `optimize` verb").
  *
  * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
  * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
@@ -69,6 +69,13 @@ export interface OptimizeReport {
  * before `possible` proxies, via explainScore's own ordering). Pure over the report.
  */
 export declare function optimize(report: ScanReport): OptimizeReport;
+/**
+ * Just the deterministic fix list (no score header) — folded into the default
+ * `vigiles audit` report so every finding carries its fix inline (replaces the
+ * former `--fix-plan`/`--explain` flags). Empty string when there's nothing to
+ * fix (or no loadable surface), so the caller can skip the section entirely.
+ */
+export declare function formatRecommendations(rep: OptimizeReport): string;
 /** Render an optimization plan for the CLI. */
 export declare function formatOptimize(rep: OptimizeReport): string;
 //# sourceMappingURL=optimize.d.ts.map

package/dist/optimize.js

@@ -1,13 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.optimize = optimize;
+exports.formatRecommendations = formatRecommendations;
 exports.formatOptimize = formatOptimize;
 /**
- * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
- * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
- * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
- * a separate command, so it's folded into scan as one more view on the same
- * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ * The per-repo harness optimizer's DETERMINISTIC spine — folded INLINE into the
+ * default `vigiles audit` report (each finding carries its fix; NOT its own
+ * `optimize` verb, and no longer a `--fix-plan` flag: until the measured A/B half
+ * lands, an "optimizer" that only re-prints audit's findings doesn't earn a
+ * separate surface; see research/roadmap.md §P2 "reconsider an `optimize` verb").
  *
  * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
  * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
@@ -67,6 +68,27 @@ const ACTION_LABEL = {
     differentiate: "DIFFERENTIATE",
 };
 const measureHint = (dir) => `\`vigiles measure ${dir} --prompts=<file>\` — real-model, runs on your subscription`;
+/**
+ * Just the deterministic fix list (no score header) — folded into the default
+ * `vigiles audit` report so every finding carries its fix inline (replaces the
+ * former `--fix-plan`/`--explain` flags). Empty string when there's nothing to
+ * fix (or no loadable surface), so the caller can skip the section entirely.
+ */
+function formatRecommendations(rep) {
+    if (rep.empty || rep.recommendations.length === 0)
+        return "";
+    const lines = [
+        `${String(rep.recommendations.length)} deterministic fix(es) — free, no model:`,
+        "",
+    ];
+    for (const r of rep.recommendations) {
+        const mark = r.confidence === "likely" ? "✗" : "⚠";
+        lines.push(`${mark} [${ACTION_LABEL[r.action]}] ${r.surface}`);
+        lines.push(`    why: ${r.rationale}  [${r.detector}]`);
+        lines.push(`    →    ${r.fix}`);
+    }
+    return lines.join("\n");
+}
 /** Render an optimization plan for the CLI. */
 function formatOptimize(rep) {
     const head = `Harness health: ${String(rep.score)}/100 (${rep.grade}) — ${rep.dir}`;

package/dist/scan-behavioral.d.ts

@@ -1,8 +1,8 @@
 /**
- * `vigiles scan --trigger` — the BEHAVIORAL column of the scan report.
+ * `vigiles audit` model trigger tier — the BEHAVIORAL column of the audit report.
  *
  * Structural `scan`/`scanPlugin` is deterministic, no-model, CI-free — and stays
- * that way. This is the opt-in, model-gated column that stacks on top: for each
+ * that way. This is the model-gated column that stacks on top: for each
  * model-invocable skill in a plugin, it measures how reliably the description
  * actually FIRES (recall, + precision when irrelevant prompts are supplied),
  * reusing `measureTriggerRate`. It degrades honestly when the `claude` CLI / auth
@@ -12,6 +12,8 @@
  * path in prose is undecidable, and the deterministic-input discipline is what
  * makes the column trustworthy. See `research/plugin-behavioral-findings.md`.
  */
+import type { PluginLayout } from "./core/layout.js";
+import type { HarnessDialect } from "./core/dialect.js";
 import { type EvalDriver } from "./eval.js";
 import { type Trace } from "./harness-test.js";
 /** Which harness drives the behavioral column (default Claude Code). */
@@ -46,6 +48,10 @@ export interface ProbeOptions {
     readonly minDistance?: number;
     /** Which harness to drive (default `"claude-code"`). */
     readonly harness?: ProbeHarness;
+    /** Layout + dialect for candidate discovery — so a Codex repo's skills (under
+     *  the Codex layout) are found, not silently missed by the default CC layout. */
+    readonly layout?: PluginLayout;
+    readonly dialect?: HarnessDialect;
 }
 /**
  * Per-harness probe wiring: the eval driver (runner+parse), how to build the

package/dist/scan-behavioral.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * `vigiles scan --trigger` — the BEHAVIORAL column of the scan report.
+ * `vigiles audit` model trigger tier — the BEHAVIORAL column of the audit report.
  *
  * Structural `scan`/`scanPlugin` is deterministic, no-model, CI-free — and stays
- * that way. This is the opt-in, model-gated column that stacks on top: for each
+ * that way. This is the model-gated column that stacks on top: for each
  * model-invocable skill in a plugin, it measures how reliably the description
  * actually FIRES (recall, + precision when irrelevant prompts are supplied),
  * reusing `measureTriggerRate`. It degrades honestly when the `claude` CLI / auth
@@ -131,8 +131,10 @@ async function probeSkill(ctx, name, ps) {
 async function probePluginTriggersWith(dir, promptSet, probe, opts = {}) {
     const ctx = { dir, opts, probe };
     // Only model-invocable, describable skills can auto-trigger; user-invoked and
-    // description-less ones can't, so they're not behavioral candidates.
-    const candidates = (0, scan_js_1.scanPlugin)(dir).skills.filter((s) => !s.userInvoked && s.hasDescription);
+    // description-less ones can't, so they're not behavioral candidates. Discover
+    // them with the resolved layout/dialect (default CC) so a Codex repo's skills
+    // aren't missed by the wrong layout.
+    const candidates = (0, scan_js_1.scanPlugin)(dir, opts.layout, opts.dialect).skills.filter((s) => !s.userInvoked && s.hasDescription);
     const results = [];
     for (const s of candidates) {
         const ps = promptSet[s.name];