vigiles 11.0.0 → 12.1.0

package/dist/scan.d.ts

@@ -17,6 +17,7 @@ import { type ToolIssue } from "./core/tool-contract.js";
 import { type HookEventIssue } from "./core/hook-events.js";
 import { type McpIssue } from "./core/mcp-config.js";
 import { type DescriptionOverlap } from "./core/description-overlap.js";
+import { type DescriptionBudgetIssue } from "./core/skill-description-budget.js";
 import { type McpToolIssue } from "./core/mcp-tool.js";
 import { type McpContractToolError } from "./core/mcp.js";
 import { type McpHookIssue } from "./core/mcp-hook.js";
@@ -28,8 +29,6 @@ import { type DelegationTrifectaFinding } from "./core/delegation-trifecta.js";
 import { type HookBlockFinding } from "./core/hook-block-ineffective.js";
 import { type HookMatcherFinding } from "./core/hook-matcher.js";
 import { type PurityLevel, type EffectSurface } from "./core/effects.js";
-/** A named writing system. The label `unexpectedScript` reports + the config's expectation parse into this. */
-export type Script = "Latin" | "Cyrillic" | "Han" | "Japanese" | "Korean" | "Arabic" | "Hebrew" | "Greek" | "Devanagari" | "Thai";
 export interface ScanSkill {
     readonly name: string;
     readonly path: string;
@@ -41,15 +40,6 @@ export interface ScanSkill {
      */
     readonly description?: string;
     readonly userInvoked: boolean;
-    /**
-     * The description's dominant script when it DIFFERS from the expected one
-     * (default `"Latin"`), else null. The model's skill-selection context is
-     * English-centric, so a description in another script carries a cross-language
-     * trigger risk — it may under-fire on English prompts. A RISK flag, not a
-     * defect (a language-matched audience is fine); measure the real gap with the
-     * `audit` trigger tier / `measureTriggerRate`.
-     */
-    readonly descriptionScript: Script | null;
     /**
      * SKILL.md body references to a bundled file (`scripts/`/`references/`/`assets/`
      * or a relative markdown link with an extension) that don't resolve on disk
@@ -221,6 +211,8 @@ export interface ScanReport {
     readonly mcpHookIssues: readonly McpHookIssue[];
     /** Pairs of model-invocable skills whose descriptions are near-identical (precision collision). */
     readonly descriptionOverlaps: readonly DescriptionOverlap[];
+    /** Model-invocable skills whose description is so long the trigger signal is buried. */
+    readonly descriptionBudgetIssues: readonly DescriptionBudgetIssue[];
     /**
      * Lethal-trifecta findings across subagents + model-invocable skills — a unit
      * holding all three legs (read-private + ingest-untrusted + exfiltrate). Each
@@ -299,18 +291,6 @@ export interface SurfaceClassifier {
     readonly isAgent: (f: string) => boolean;
     readonly isCommand: (f: string) => boolean;
 }
-/**
- * The description's dominant alphabetic script when it DIFFERS from `expected`
- * (default `"Latin"`) — the cross-language trigger-risk signal. The model's
- * skill-selection context is English-centric, so a description written mostly in
- * another script may under-fire on English prompts. `expected` is a configurable
- * default, not a value judgement: a Russian-targeted pack sets it to `"Cyrillic"`
- * so its Cyrillic descriptions pass and an English one is flagged instead.
- * Returns null when the dominant script IS the expected one (or there's no
- * alphabetic content). Shared by `scan` and the future lint rule (one detector,
- * 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

package/dist/scan.js

@@ -13,7 +13,6 @@
  * stack on top later; this core stays pure so it runs anywhere in CI for free.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unexpectedScript = unexpectedScript;
 exports.isManagedHookCommand = isManagedHookCommand;
 exports.preferCompiledHooksMessage = preferCompiledHooksMessage;
 exports.scanPlugin = scanPlugin;
@@ -35,6 +34,7 @@ const hook_normalize_js_1 = require("./core/hook-normalize.js");
 const linters_js_1 = require("./core/linters.js");
 const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
 const description_overlap_js_1 = require("./core/description-overlap.js");
+const skill_description_budget_js_1 = require("./core/skill-description-budget.js");
 const mcp_tool_js_1 = require("./core/mcp-tool.js");
 const mcp_js_1 = require("./core/mcp.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
@@ -111,58 +111,6 @@ function skillName(path) {
         .split("/")
         .pop() ?? path);
 }
-// [Unicode \p{Script=…} property value (Node native, no dependency), our Script
-// label]. Japanese kana fold to "Japanese". Latin is the DEFAULT expectation (the
-// selector is English-centric), but it's just a default — a language-matched pack
-// can declare a different expectation, and then the OTHER script is the mismatch.
-const SCRIPTS = [
-    ["Latin", "Latin"],
-    ["Cyrillic", "Cyrillic"],
-    ["Han", "Han"],
-    ["Hiragana", "Japanese"],
-    ["Katakana", "Japanese"],
-    ["Hangul", "Korean"],
-    ["Arabic", "Arabic"],
-    ["Hebrew", "Hebrew"],
-    ["Greek", "Greek"],
-    ["Devanagari", "Devanagari"],
-    ["Thai", "Thai"],
-];
-/** Letter counts per named script label (Japanese kana folded together). */
-function scriptCounts(text) {
-    const counts = new Map();
-    for (const [script, label] of SCRIPTS) {
-        const n = (text.match(new RegExp(`\\p{Script=${script}}`, "gu")) ?? [])
-            .length;
-        if (n > 0)
-            counts.set(label, (counts.get(label) ?? 0) + n);
-    }
-    return counts;
-}
-/**
- * The description's dominant alphabetic script when it DIFFERS from `expected`
- * (default `"Latin"`) — the cross-language trigger-risk signal. The model's
- * skill-selection context is English-centric, so a description written mostly in
- * another script may under-fire on English prompts. `expected` is a configurable
- * default, not a value judgement: a Russian-targeted pack sets it to `"Cyrillic"`
- * so its Cyrillic descriptions pass and an English one is flagged instead.
- * Returns null when the dominant script IS the expected one (or there's no
- * alphabetic content). Shared by `scan` and the future lint rule (one detector,
- * no drift). The ≥20% guard avoids a near-empty string tripping on one letter.
- */
-function unexpectedScript(text, expected = "Latin") {
-    const counts = scriptCounts(text);
-    let total = 0;
-    let dominant = null;
-    for (const [label, count] of counts) {
-        total += count;
-        if (!dominant || count > dominant.count)
-            dominant = { label, count };
-    }
-    if (!dominant || dominant.label === expected)
-        return null;
-    return dominant.count / total >= 0.2 ? dominant.label : null;
-}
 /**
  * The first prose paragraph of a SKILL.md body (after the frontmatter and any
  * leading `#` headings) — Claude Code's FALLBACK skill description when the
@@ -236,7 +184,6 @@ function scanSkills(files, cls, ctx) {
             hasDescription: Boolean(effectiveDesc && effectiveDesc.length >= 20),
             description: effectiveDesc?.trim(),
             userInvoked,
-            descriptionScript: effectiveDesc ? unexpectedScript(effectiveDesc) : null,
             resourceIssues,
             trifecta,
             // A SKILL.md opening with `name:`/`description:` but no `---` fence loads
@@ -254,7 +201,7 @@ function scanSkills(files, cls, ctx) {
  * logic as `scanSkills` (frontmatter `description` ← first body paragraph), then
  * the NCD precision-proxy. See description-overlap.ts.
  */
-function descriptionOverlapsFor(files, cls) {
+function modelInvocableSkillSurfaces(files, cls) {
     const surfaces = [];
     for (const [path, md] of Object.entries(files)) {
         if (!cls.isSkill(path))
@@ -267,7 +214,18 @@ function descriptionOverlapsFor(files, cls) {
             continue;
         surfaces.push({ name: fm.name ?? skillName(path), description });
     }
-    return (0, description_overlap_js_1.findDescriptionOverlaps)(surfaces);
+    return surfaces;
+}
+function descriptionOverlapsFor(files, cls) {
+    return (0, description_overlap_js_1.findDescriptionOverlaps)(modelInvocableSkillSurfaces(files, cls));
+}
+/**
+ * Model-invocable skills whose description is so long the trigger signal is
+ * buried (heuristic proxy; degrades recall + precision). Same surfaces as the
+ * overlap check. See skill-description-budget.ts.
+ */
+function descriptionBudgetFor(files, cls) {
+    return (0, skill_description_budget_js_1.findDescriptionBudgetIssues)(modelInvocableSkillSurfaces(files, cls));
 }
 function scanAgents(files, dialect, declaredServers, cls) {
     const out = [];
@@ -797,6 +755,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         mcpIssues: (0, mcp_config_js_1.verifyMcpServers)(mcpServers),
         mcpHookIssues: (0, mcp_hook_js_1.verifyMcpHookTargets)(loaded.settings.hooks, declaredServers, dialect),
         descriptionOverlaps: descriptionOverlapsFor(loaded.files, cls),
+        descriptionBudgetIssues: descriptionBudgetFor(loaded.files, cls),
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,
         skillFenceIssues: skillFenceFindings,
@@ -923,7 +882,7 @@ function section(title, lines, count = lines.length) {
         return [];
     return [`${title} (${String(count)}):`, ...lines, ""];
 }
-/** One skill's report line: ✓/⚠ + name + notes (no-trigger, user-invoked, language risk). */
+/** One skill's report line: ✓/⚠ + name + notes (no-trigger, user-invoked). */
 function skillLine(s) {
     if (!s.hasDescription) {
         return `  ⚠ ${s.name} (no usable description — no frontmatter description and no body text — can't trigger)`;
@@ -931,11 +890,7 @@ function skillLine(s) {
     const notes = [];
     if (s.userInvoked)
         notes.push("user-invoked");
-    if (s.descriptionScript) {
-        notes.push(`description in ${s.descriptionScript} — cross-language trigger risk`);
-    }
-    const mark = s.descriptionScript ? "⚠" : "✓";
-    return `  ${mark} ${s.name}${notes.length ? ` (${notes.join("; ")})` : ""}`;
+    return `  ✓ ${s.name}${notes.length ? ` (${notes.join("; ")})` : ""}`;
 }
 /** One agent's report block: ✗ (broken contract) / ⚠ (inherits all) / ✓ + issues + purity. */
 function agentLines(a) {
@@ -1002,6 +957,7 @@ function formatScanReport(r) {
     out.push(...section("MCP config", r.mcpIssues.map((i) => `  ✗ ${i.message}`)));
     out.push(...section("MCP hook targets", r.mcpHookIssues.map((i) => `  ✗ ${i.message}`)));
     out.push(...section("Description overlap (precision risk)", r.descriptionOverlaps.map((o) => `  ⚠ ${o.message}`)));
+    out.push(...section("Description budget (trigger-signal risk)", r.descriptionBudgetIssues.map((o) => `  ⚠ ${o.message}`)));
     out.push(...section("Lethal trifecta (prompt-injection exfil risk)", r.trifectaFindings.map((t) => `  ${t.finding.severity === "hard" ? "✗" : "⚠"} ${t.kind} ${t.name} (${t.path}): ${t.finding.message}`)));
     out.push(...section("Skill bundled resources", r.skillResourceIssues.map((s) => `  ✗ ${s.name}: ${s.finding.ref} (line ${String(s.finding.line)}) — bundled resource not found`)));
     out.push(...section("Invisible skills (missing frontmatter fence)", r.skillFenceIssues.map((s) => `  ✗ ${s.name} (${s.path}): opens with \`${s.finding.key}:\` but no \`---\` fence — loads as body, never fires`)));
@@ -1028,13 +984,6 @@ function formatScanReport(r) {
     if (warnings.length > 0) {
         out.push("Warnings:", ...warnings.map((w) => `  - ${w}`), "");
     }
-    // Cross-language trigger risk is a RISK, not a structural defect (a
-    // language-matched audience is fine), so it's reported separately from the
-    // verdict — it points at the behavioral column, it doesn't fail the scan.
-    const mismatched = r.skills.filter((s) => s.descriptionScript);
-    if (mismatched.length > 0) {
-        out.push(`⚠ ${String(mismatched.length)} skill(s) have descriptions in an unexpected script (cross-language trigger risk) — measure with \`vigiles measure\``, "");
-    }
     // Skill-metadata is a RECOMMENDATION, not a structural defect (the skill loads
     // via fallbacks) — reported as a soft note, never counted in the verdict.
     if (r.skillMetaIssues.length > 0) {

package/dist/setup-plan.d.ts

@@ -95,7 +95,7 @@ export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "unt
  * keep their own default severities. Named for the group taxonomy
  * (research/install-enforcement-dx.md).
  */
-export declare const NUDGE_RULES: readonly ["frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher"];
+export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher"];
 export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
     harness: string | string[];
     strict: boolean;
@@ -158,6 +158,43 @@ export interface InstallPlan {
 export declare function planPluginInstall(harnesses: readonly string[], opts: {
     hasClaude: boolean;
 }): InstallPlan[];
+/** One vigiles-managed Codex hook: a `[[hooks.<event>]]` entry. */
+export interface CodexPluginHook {
+    readonly event: string;
+    /** Codex matcher (anchored regex, the dialect convention). */
+    readonly matcher: string;
+    /** The shell command Codex runs (a direct `npx vigiles …`, no plugin root). */
+    readonly command: string;
+    /** A unique command substring → idempotent re-merge (replaces in place). */
+    readonly key: string;
+}
+/**
+ * vigiles's proactive nudges, wired into a Codex repo's `.codex/config.toml`.
+ *
+ * Codex has no global plugin store (unlike Claude Code's marketplace), so its
+ * config is repo-committed — the idiomatic place for these. They run as DIRECT
+ * `npx vigiles hook-runtime …` commands (NOT vendored bash scripts): the runtime
+ * entrypoints read the event JSON on stdin and emit the `hookSpecificOutput.
+ * additionalContext` shape Codex honors on `PostToolUse` (confirmed against the
+ * official hooks docs + encoded in `HookProtocol.injectableEvents`). Safety: only
+ * an INTENTIONAL `exit 2` blocks an edit (the refs nudge, when `unmarked-refs` is
+ * `error`); an npx-resolution failure exits non-2, so a missing dep never blocks.
+ *
+ * Deliberately NOT here (a loud, documented deferral — no-silent-skips): the
+ * SessionStart lint summary (CC delivers it as plain stdout, whose SessionStart
+ * prepend is unconfirmed on Codex — vs the JSON `additionalContext` these use) and
+ * the compile-on-edit / pre-edit-block guards (filename-gated bash with no
+ * harness-neutral `hook-runtime` entrypoint yet). Those stay manual on Codex.
+ */
+export declare function codexPluginHooks(): CodexPluginHook[];
+/**
+ * Idempotently merge {@link codexPluginHooks} into a parsed `.codex/config.toml`
+ * object. Pure — the IO (read/parse/serialize/write) stays in cli.ts's
+ * `wireCodexHooks`. Each vigiles hook is keyed by a unique command substring, so
+ * a re-run REPLACES its own entry in place and leaves the user's own Codex hooks
+ * (and every other config key) untouched. Returns a new object.
+ */
+export declare function applyCodexPluginHooks(existing: Record<string, unknown>): Record<string, unknown>;
 /**
  * Resolve the final plan: defaults, then flags, then interactive answers (each
  * layer overrides the previous only where it has an opinion). `--target` pins a

package/dist/setup-plan.js

@@ -17,6 +17,8 @@ exports.mergeProjectConfig = mergeProjectConfig;
 exports.shouldPrompt = shouldPrompt;
 exports.collectSetupAnswers = collectSetupAnswers;
 exports.planPluginInstall = planPluginInstall;
+exports.codexPluginHooks = codexPluginHooks;
+exports.applyCodexPluginHooks = applyCodexPluginHooks;
 exports.resolvePlan = resolvePlan;
 function flagValue(args, prefix) {
     return args.find((a) => a.startsWith(prefix))?.slice(prefix.length);
@@ -119,6 +121,7 @@ exports.WORKFLOW_RULES = [
  * (research/install-enforcement-dx.md).
  */
 exports.NUDGE_RULES = [
+    "skill-description-budget",
     "frontmatter-valid",
     "skill-frontmatter",
     "prefer-compiled-hooks",
@@ -260,8 +263,10 @@ function planPluginInstall(harnesses, opts) {
         if (harness === "codex") {
             // The cross-agent `skills` CLI with `-g -y` installs to the global store
             // ~/.agents/skills/ (NOT the repo, and NOT ~/.codex/ — verified against
-            // the real CLI). Skills only; Codex hooks (.codex/config.toml [hooks])
-            // are not wired automatically.
+            // the real CLI). Skills install globally; the proactive NUDGE hooks
+            // (eval-lock + refs) are wired into the repo's .codex/config.toml by
+            // `init` (see codexPluginHooks / wireCodexHooks) — Codex config is
+            // repo-committed, so that's the idiomatic place.
             return {
                 harness,
                 commands: ["npx --yes skills add zernie/vigiles -a codex -g -y"],
@@ -269,9 +274,10 @@ function planPluginInstall(harnesses, opts) {
                 manualSteps: ["npx skills add zernie/vigiles -a codex -g -y"],
                 notes: [
                     "Codex reads AGENTS.md directly; the skills install globally to ~/.agents/skills/ (not the repo).",
-                    "Codex hooks (.codex/config.toml [hooks]) are not auto-wired yet — add them manually for compile-on-edit.",
+                    "The eval-lock + refs NUDGE hooks are wired into .codex/config.toml (repo-committed, the Codex norm).",
+                    "Still manual on Codex: the SessionStart lint summary + compile-on-edit/pre-edit guards (no harness-neutral entrypoint yet).",
                 ],
-                vendors: false,
+                vendors: true,
             };
         }
         return {
@@ -284,6 +290,63 @@ function planPluginInstall(harnesses, opts) {
         };
     });
 }
+/**
+ * vigiles's proactive nudges, wired into a Codex repo's `.codex/config.toml`.
+ *
+ * Codex has no global plugin store (unlike Claude Code's marketplace), so its
+ * config is repo-committed — the idiomatic place for these. They run as DIRECT
+ * `npx vigiles hook-runtime …` commands (NOT vendored bash scripts): the runtime
+ * entrypoints read the event JSON on stdin and emit the `hookSpecificOutput.
+ * additionalContext` shape Codex honors on `PostToolUse` (confirmed against the
+ * official hooks docs + encoded in `HookProtocol.injectableEvents`). Safety: only
+ * an INTENTIONAL `exit 2` blocks an edit (the refs nudge, when `unmarked-refs` is
+ * `error`); an npx-resolution failure exits non-2, so a missing dep never blocks.
+ *
+ * Deliberately NOT here (a loud, documented deferral — no-silent-skips): the
+ * SessionStart lint summary (CC delivers it as plain stdout, whose SessionStart
+ * prepend is unconfirmed on Codex — vs the JSON `additionalContext` these use) and
+ * the compile-on-edit / pre-edit-block guards (filename-gated bash with no
+ * harness-neutral `hook-runtime` entrypoint yet). Those stay manual on Codex.
+ */
+function codexPluginHooks() {
+    // Codex's file-edit tool is `apply_patch` (its dialect vocabulary —
+    // src/adapters/codex/dialect.ts), NOT Claude's `Edit`/`Write`. A PostToolUse
+    // matcher keyed on CC tool names would never fire on Codex, so the nudges must
+    // match the Codex tool name. (Both nudge entrypoints also self-gate on the
+    // edited file, so a non-edit event no-ops regardless.)
+    return [
+        {
+            event: "PostToolUse",
+            matcher: "^apply_patch$",
+            command: "npx --no-install vigiles hook-runtime eval-lock-nudge",
+            key: "hook-runtime eval-lock-nudge",
+        },
+        {
+            event: "PostToolUse",
+            matcher: "^apply_patch$",
+            command: "npx --no-install vigiles hook-runtime refs",
+            key: "hook-runtime refs",
+        },
+    ];
+}
+/**
+ * Idempotently merge {@link codexPluginHooks} into a parsed `.codex/config.toml`
+ * object. Pure — the IO (read/parse/serialize/write) stays in cli.ts's
+ * `wireCodexHooks`. Each vigiles hook is keyed by a unique command substring, so
+ * a re-run REPLACES its own entry in place and leaves the user's own Codex hooks
+ * (and every other config key) untouched. Returns a new object.
+ */
+function applyCodexPluginHooks(existing) {
+    const config = existing;
+    const hooks = {
+        ...(config.hooks ?? {}),
+    };
+    for (const h of codexPluginHooks()) {
+        const kept = (hooks[h.event] ?? []).filter((e) => !e.command.includes(h.key));
+        hooks[h.event] = [...kept, { matcher: h.matcher, command: h.command }];
+    }
+    return { ...existing, hooks };
+}
 /**
  * Resolve the final plan: defaults, then flags, then interactive answers (each
  * layer overrides the previous only where it has an opinion). `--target` pins a

package/hooks/eval-lock-nudge.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# PostToolUse hook — after the agent edits an eval input (a SKILL.md trigger
+# surface or an *.eval.* script) and committed eval locks exist, inject a
+# NON-BLOCKING reminder to re-run `vigiles eval --update`. Self-gating: silent
+# until you've committed a lock, so it never fires in a repo that doesn't use
+# evals. Never blocks the edit. Runs as its OWN PostToolUse entry so its stdout
+# stays clean JSON. See docs/harness-testing.md (the eval lock).
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# No npx / not a Node project → nothing to do, never disrupt the edit.
+command -v npx >/dev/null 2>&1 || exit 0
+[ -f package.json ] || exit 0
+
+printf '%s' "$INPUT" | npx vigiles hook-runtime eval-lock-nudge
+
+# Always exit 0 — this hook only nudges, it never blocks (the gate is CI's
+# `vigiles eval --check`). Swallow any tool/setup error so it can't disrupt edits.
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "11.0.0",
+  "version": "12.1.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",

package/skills/adopt-spec/SKILL.md

@@ -7,7 +7,16 @@ argument-hint: <path to CLAUDE.md, defaults to CLAUDE.md>
 
 Start a typed `CLAUDE.md.spec.ts` from an existing hand-written CLAUDE.md (or AGENTS.md). This is the non-destructive adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
 
-> **Faithful by default, and reversible.** Adoption is non-destructive: the goal is a spec that compiles back to the user's existing file as closely as possible — preserve every rule, command, key file, and prose section. Don't upgrade `guidance()` to `enforce()` here; that's a separate, opt-in step (the `strengthen` skill). And it's never a one-way door — `vigiles eject <file>` hands the file back as plain hand-owned markdown anytime. For the lightest touch with no spec at all, inline `<!-- vigiles:enforce ... -->` comments are verified by `vigiles lint` with the same engine.
+## Adoption rules
+
+Adoption is the **safe, faithful on-ramp — never an upgrade in disguise.** These are non-negotiable:
+
+- **Faithful.** Preserve every rule, command, key file, and prose section as-is. Invent nothing — the spec must compile back to ~the user's existing file.
+- **Non-destructive.** Never edit the original `CLAUDE.md` / `AGENTS.md`. Only write the new `.spec.ts`. Never auto-`compile` over the file — switching it to spec-managed is a separate, explicit step the user runs with a diff to review.
+- **Don't escalate enforcement.** Keep `guidance()` as `guidance()`. Upgrading to `enforce()` has a cost (config/plugins, possible false positives) and is a separate opt-in step — the `strengthen` skill. Adoption is **not** turning on strict / `workflow` gating.
+- **Reversible.** `vigiles eject <file>` hands the file back as plain hand-owned markdown anytime — it's never a one-way door. Tell the user this.
+- **Ask before writing.** Present the generated spec and a conversion summary first; write only on the user's yes.
+- **A lighter touch exists.** For no spec at all, inline `<!-- vigiles:enforce ... -->` comments are verified by `vigiles lint` with the same engine.
 
 ## Instructions
 

package/skills/edit-spec/SKILL.md

@@ -136,6 +136,7 @@ If the vigiles plugin is installed (`/plugin marketplace add zernie/vigiles` the
 
 ## Important
 
+- **Do what's asked; don't silently escalate enforcement.** Add the rule the user asked for. If making it an `enforce()` would need a linter-config edit or a plugin install (a cost), or if it could fail a clean CI, **say so and let the user choose** — don't change linter config or flip on strict / `workflow` gating on your own. A pure win (a rule that's already enabled) you can just apply. The `strengthen` skill owns `guidance()` → `enforce()` upgrades.
 - **Never edit CLAUDE.md or AGENTS.md directly** — they have a vigiles hash comment and are build artifacts
 - **The spec is TypeScript** — you get type checking, autocomplete, and verified references
 - **`enforce()` rules are verified** — the compiler checks the rule exists AND is enabled in your linter config

package/skills/strengthen/SKILL.md

@@ -5,6 +5,10 @@ description: Upgrade a vigiles spec's guidance() rules to enforce() — scan the
 
 Scan spec files for `guidance()` rules and suggest `enforce()` replacements backed by real linter rules.
 
+## Principle: auto the free wins, nudge for the costs
+
+The dividing line is **cost, not strictness**. A `guidance()` → `enforce()` swap where the linter rule **already exists and is enabled** is a pure win — free, reversible, no false-positive risk — so apply it (Tier 1 below). Anything that **costs** something — editing linter config, installing a plugin, or a change that could fail a clean CI — is the user's call: **present it with the tradeoff spelled out and let them choose** (Tiers 2–4). Never silently edit config, install a dependency, or escalate the repo into strict gating. This is the `init` enforcement model (structural = on by default, workflow/strict = opt-in) applied at edit time.
+
 ## Instructions
 
 ### Step 0: Choose Mode

package/skills/test-harness/SKILL.md

@@ -190,6 +190,50 @@ job that asserts the capability is present, run **`vigiles test --no-skip`** so
 skipped tier fails — a green-with-skips is untested surface. Keep unit +
 deterministic tests in CI (free); run evals locally or on a schedule with auth.
 
+### After a real-model run: TELL THE USER WHAT IT SPENT
+
+Whenever you run a real-model eval (`runEval` / `measureArms` / `measureTriggerRate`
+/ `measure`), **surface the spend to the user in your reply** — don't let a paid run
+be silent. `runEval` prints a cost block to stderr and every report carries `usage`
+(`report.arms[*].usage`: `totalCostUsd` + token counts). Relay, in plain words:
+
+- **tokens spent** and the **API-equivalent `$`** (`total_cost_usd` — what it _would_
+  cost at metered API rates);
+- **how it was billed** — "on your Claude subscription (**$0 metered**)" if you're
+  logged in, or a **⚠ warning** if `ANTHROPIC_API_KEY` is set (that run was billed
+  **per token** — tell them to unset it and `claude login` to run free).
+
+We do **not** show "% of your subscription" — Anthropic doesn't expose a plan's
+quota, so any percentage would be invented. Tokens + API-equivalent `$` + the
+billed-to line is the honest, complete picture. Keep the user's cost visible, always.
+
+## Step 5 — Lock the eval so CI stays honest (you do this automatically)
+
+Real-model evals run on the user's subscription — locally, never in CI. So **as
+part of writing an eval, you keep its result fresh for them.** Do these two things
+without being asked:
+
+1. **Give every eval a `name`.** That's what the lock keys on.
+2. **After running it, commit the lock:**
+
+   ```bash
+   vigiles eval --update      # records the result → .vigiles/eval-locks/<name>.lock.json
+   ```
+
+   Then commit that file. CI runs `vigiles eval --check` (no model) to verify it
+   still matches the inputs — so a later edit that forgets to re-eval fails loud
+   instead of shipping stale numbers.
+
+**When you later change a skill's description or prompts, re-run `vigiles eval
+--update` and commit the updated lock** — the change altered what the eval
+measures. (vigiles also nudges you: when a lock exists, a `SKILL.md` edit triggers
+a non-blocking reminder.)
+
+Why it's cheap: `--check` only hashes inputs (skill text, prompts, model). A
+**threshold** change in the test re-uses the saved numbers (no model); only an
+**input** change needs a fresh `--update`. Full mechanics:
+[`docs/harness-testing.md`](../../docs/harness-testing.md#keep-eval-results-fresh-in-ci-the-lock).
+
 ## When the user didn't say what to test
 
 Don't ask them to specify — **pick something real and demonstrate.** Scan the