vigiles 7.0.0 → 8.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[];
     /**

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/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/scan-trigger-suggest.d.ts

@@ -0,0 +1,54 @@
+/**
+ * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
+ * real model is reachable, surface the (real-model) `scan --trigger` tier that
+ * measures whether those skills actually FIRE (recall + precision). Pure
+ * decision + helpers; the IO (prompt / scaffold write / running the measure)
+ * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
+ * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ */
+/** Only the env vars that signal a reachable model (parse, don't validate). */
+export interface ModelEnv {
+    readonly ANTHROPIC_API_KEY?: string;
+    readonly CLAUDECODE?: string;
+    readonly CLAUDE_CODE_ENTRYPOINT?: string;
+}
+/**
+ * Is a real model reachable for the eval / trigger tier? Either a metered API
+ * key (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session
+ * (`CLAUDECODE=1` / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter
+ * drives the `claude` CLI on the user's subscription, no key needed. Keeping
+ * this a tiny, env-only predicate (not a live probe) means it never spends a
+ * token just to decide whether to suggest spending one.
+ */
+export declare function hasModelAccess(env: ModelEnv): boolean;
+export type TriggerSuggestion = "prompt" | "hint" | "none";
+export interface SuggestOpts {
+    /** A real model is reachable (`hasModelAccess`). */
+    readonly modelAccess: boolean;
+    /** stdout is an interactive terminal (a human is watching). */
+    readonly isTTY: boolean;
+    /** Count of model-invocable, described skills worth measuring. */
+    readonly triggerableSkills: number;
+    /** `--json` — machine output; never decorate or prompt. */
+    readonly json: boolean;
+    /** `--no-interactive` — explicit agent/CI mode; hint, never prompt. */
+    readonly noInteractive: boolean;
+}
+/**
+ * Decide how `scan` surfaces the trigger tier after its report:
+ * - `"none"`   — no model-invocable skills, no model access, or `--json`.
+ * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
+ *                / `--no-interactive`): a one-line, non-blocking hint.
+ * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ */
+export declare function decideTriggerSuggestion(o: SuggestOpts): TriggerSuggestion;
+/** The one-line, non-blocking hint (the agent/CI surface). */
+export declare function formatTriggerHint(dir: string, triggerableSkills: number): string;
+/**
+ * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
+ * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
+ * placeholders the user replaces with real requests. Deterministic; written
+ * only on an explicit human "yes" so a plain `scan` never spends a token.
+ */
+export declare function scaffoldTriggerPrompts(skillNames: readonly string[]): string;
+//# sourceMappingURL=scan-trigger-suggest.d.ts.map

package/dist/scan-trigger-suggest.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
+ * real model is reachable, surface the (real-model) `scan --trigger` tier that
+ * measures whether those skills actually FIRE (recall + precision). Pure
+ * decision + helpers; the IO (prompt / scaffold write / running the measure)
+ * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
+ * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasModelAccess = hasModelAccess;
+exports.decideTriggerSuggestion = decideTriggerSuggestion;
+exports.formatTriggerHint = formatTriggerHint;
+exports.scaffoldTriggerPrompts = scaffoldTriggerPrompts;
+/**
+ * Is a real model reachable for the eval / trigger tier? Either a metered API
+ * key (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session
+ * (`CLAUDECODE=1` / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter
+ * drives the `claude` CLI on the user's subscription, no key needed. Keeping
+ * this a tiny, env-only predicate (not a live probe) means it never spends a
+ * token just to decide whether to suggest spending one.
+ */
+function hasModelAccess(env) {
+    return Boolean(env.ANTHROPIC_API_KEY ||
+        env.CLAUDECODE === "1" ||
+        env.CLAUDE_CODE_ENTRYPOINT);
+}
+/**
+ * Decide how `scan` surfaces the trigger tier after its report:
+ * - `"none"`   — no model-invocable skills, no model access, or `--json`.
+ * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
+ *                / `--no-interactive`): a one-line, non-blocking hint.
+ * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ */
+function decideTriggerSuggestion(o) {
+    if (o.json || o.triggerableSkills < 1 || !o.modelAccess)
+        return "none";
+    if (o.noInteractive || !o.isTTY)
+        return "hint";
+    return "prompt";
+}
+/** The one-line, non-blocking hint (the agent/CI surface). */
+function formatTriggerHint(dir, triggerableSkills) {
+    const n = triggerableSkills;
+    return (`ℹ ${String(n)} model-invocable skill${n === 1 ? "" : "s"} + model access detected — ` +
+        `measure whether they actually FIRE (recall + precision) with:\n` +
+        `    vigiles scan ${dir} --trigger --prompts=trigger-prompts.json`);
+}
+/**
+ * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
+ * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
+ * placeholders the user replaces with real requests. Deterministic; written
+ * only on an explicit human "yes" so a plain `scan` never spends a token.
+ */
+function scaffoldTriggerPrompts(skillNames) {
+    const obj = {};
+    for (const name of skillNames) {
+        obj[name] = {
+            prompts: [
+                `TODO: a request that SHOULD trigger "${name}"`,
+                `TODO: a differently-phrased request that should also trigger it`,
+            ],
+            irrelevant: [
+                `TODO: an unrelated request that should NOT trigger "${name}"`,
+            ],
+        };
+    }
+    return JSON.stringify(obj, null, 2) + "\n";
+}
+//# sourceMappingURL=scan-trigger-suggest.js.map

package/dist/scan.d.ts

@@ -94,7 +94,7 @@ export interface ScanHook {
  * Every cc/codex repo has one even when it ships no plugin surface, so `scan`
  * reports it — otherwise a plain instruction-only repo looks empty. `hasSpec` is
  * the deterministic fact that a `<file>.spec.ts` sits beside it (spec-managed vs
- * hand-written); it is informational, NOT the `require-spec` gate (that's lint).
+ * hand-written); it is informational, NOT the `require-instructions-spec` gate (that's lint).
  */
 export interface ScanInstructions {
     readonly file: string;
@@ -109,6 +109,13 @@ export interface ScanReport {
     readonly hooks: readonly ScanHook[];
     /** Hook entries with no script file (inline shell one-liners) — can't be path-checked. */
     readonly inlineHooks: number;
+    /**
+     * Hand-written hook commands that are NOT compiled `vigiles/hook` artifacts (a
+     * compiled hook's command invokes `vigiles hook-runtime run-program`). The basis
+     * for the `prefer-compiled-hooks` recommendation — a single nudge regardless of
+     * count. Zero when there are no hooks or every hook is vigiles-managed.
+     */
+    readonly manualHookCount: number;
     readonly commands: number;
     readonly mcp: boolean;
     /**
@@ -175,6 +182,15 @@ export interface SurfaceClassifier {
  * no drift). The ≥20% guard avoids a near-empty string tripping on one letter.
  */
 export declare function unexpectedScript(text: string, expected?: Script): Script | null;
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+export declare function isManagedHookCommand(command: string): boolean;
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+export declare function preferCompiledHooksMessage(count: number): string;
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect): ScanReport;
 /**

package/dist/scan.js

@@ -14,6 +14,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unexpectedScript = unexpectedScript;
+exports.isManagedHookCommand = isManagedHookCommand;
+exports.preferCompiledHooksMessage = preferCompiledHooksMessage;
 exports.scanPlugin = scanPlugin;
 exports.verifyLiveMcpTools = verifyLiveMcpTools;
 exports.formatMcpContractReport = formatMcpContractReport;
@@ -265,10 +267,32 @@ function resolveScript(token, root, pluginRootToken) {
 // target is INTENTIONAL, not a broken reference. Don't flag scripts in such a
 // command as MISSING (a false positive caught on gmickel/flow-next's ralph-guard).
 const EXISTENCE_GUARD = /(?:\[\[?\s*!?\s*-[efsx]\s)|(?:\btest\s+!?\s*-[efsx]\s)/;
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+function isManagedHookCommand(command) {
+    return /\bhook-runtime\b/.test(command);
+}
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+function preferCompiledHooksMessage(count) {
+    return (`${String(count)} hand-written hook command(s) — if any gate the agent ` +
+        `(a block/deny decision), compiled hooks (\`vigiles/hook\`) make whole hook ` +
+        `bug classes unrepresentable at authoring time, and \`guardrail-check\` proves ` +
+        `an existing one blocks. See docs/compiled-hooks.md.`);
+}
 /** Pull script-file hook commands out of the resolved settings; count inline ones. */
 function scanHooks(settings, root, pluginRootToken) {
     const text = JSON.stringify(settings.hooks ?? {});
     const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
+    // A hand-written hook is any non-empty command that isn't a vigiles-managed
+    // (compiled) hook-runtime invocation — the basis for the prefer-compiled-hooks nudge.
+    const manual = commands.filter((c) => {
+        const u = c.replace(/\\(.)/g, "$1").trim();
+        return u !== "" && !isManagedHookCommand(u);
+    }).length;
     const byScript = new Map();
     let inline = 0;
     for (const cmd of commands) {
@@ -290,7 +314,7 @@ function scanHooks(settings, root, pluginRootToken) {
         }
     }
     const hooks = [...byScript.values()].sort((a, b) => a.script.localeCompare(b.script));
-    return { hooks, inline };
+    return { hooks, inline, manual };
 }
 // ---------------------------------------------------------------------------
 // Public API
@@ -487,7 +511,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
     const lay = layout ?? layout_js_1.claudeCodeLayout;
     const cls = makeClassifier(lay);
     const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
-    const { hooks, inline } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
+    const { hooks, inline, manual } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
     // Hook-event keys are a CLOSED platform set — an unrecognized one is a dead
     // registration (the hook never fires), so flag every unknown (not just typos).
     // ONLY for the canonical object-keyed-by-event shape: a plugin shipping a
@@ -521,6 +545,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         agents,
         hooks,
         inlineHooks: inline,
+        manualHookCount: manual,
         commands: Object.keys(loaded.files).filter(cls.isCommand).length,
         mcp: loaded.warnings.some((w) => w.includes("MCP server")),
         danglingRefs: (0, plugin_loader_js_2.danglingRefs)((0, node_path_1.resolve)(dir), lay),
@@ -749,6 +774,11 @@ function formatScanReport(r) {
     if (r.skillMetaIssues.length > 0) {
         out.push(`ℹ ${String(r.skillMetaIssues.length)} skill(s) lack an explicit frontmatter name/description (recommended for a reliable trigger surface) — they still load via fallback`, "");
     }
+    // One discovery nudge toward compiled hooks (never per-hook); the hand-written
+    // shell lane stays first-class, so this is a recommendation, not a defect.
+    if (r.manualHookCount > 0) {
+        out.push(`ℹ ${preferCompiledHooksMessage(r.manualHookCount)}`, "");
+    }
     // Malformed-YAML frontmatter is INFORMATIONAL, not a structural defect: js-yaml
     // is stricter than some loaders (a colon/quote/<example> in a one-line
     // description trips it though the file may still load), and the other fields are