vigiles 16.1.2 → 17.0.0

package/dist/core/vocabulary.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classify = classify;
+exports.suggest = suggest;
+exports.termIssue = termIssue;
+exports.scoredIssues = scoredIssues;
+exports.advisoryIssues = advisoryIssues;
+exports.authoringIssues = authoringIssues;
+exports.vocabularyFromLists = vocabularyFromLists;
+/**
+ * HarnessVocabulary — the platform's own words, with a STATUS per word.
+ *
+ * The three vocabulary checks (`hook-events`, `subagent-tool-contract`, and the
+ * `disallowedTools:` mirror) used to model a harness's vocabulary as two
+ * hand-kept arrays — "these names are fine", "these names are dead" — and then
+ * decide what to SAY about a name in neither by its EDIT DISTANCE to the first
+ * array. That is the defect this module exists to remove, and it failed in both
+ * directions at once (measured against the vendor docs, 2026-08-17):
+ *
+ *  - FALSE ACCUSATION. `Setup` is a documented Claude Code hook event. It was
+ *    reported as "a hook here never fires … Did you mean Stop?" — and the
+ *    suggested repair rewires a one-shot setup hook onto every turn's Stop.
+ *    It was caught for one reason only: `setup` happens to sit at edit distance
+ *    2 from `stop`.
+ *  - SILENCE. Of the 31 events the vendor documents, the old catalog held 9.
+ *    The other 22 were not "accepted" — they were unrecognised and >2 away from
+ *    any known name, so nothing was said. `SubagentStart` and `PostCompact` sat
+ *    at distance 3: one character from becoming the next `Setup`.
+ *
+ * So which of the two a valid name got — an accusation or silence — was decided
+ * by spelling luck. Neither is a verdict, and a tool whose pitch is precision
+ * cannot ship either as its answer to "I don't know this word".
+ *
+ * The fix is not a longer array. It is to stop asking "is this string in my
+ * list?" (a boolean, which has no room for "I don't know") and start asking
+ * "what does my catalog SAY about this string?" — a {@link TermVerdict}, which
+ * has four answers because the vendor's own documentation distinguishes four:
+ *
+ *  - `available`     — the platform provides it.
+ *  - `withheld`      — the platform removes it, unconditionally. A real defect.
+ *  - `conditional`   — the platform removes it only under a STATED condition
+ *                      (`Agent` at the depth limit; `ExitPlanMode` unless
+ *                      `permissionMode: plan`; every non-background built-in when
+ *                      the subagent runs in the background). vigiles cannot see
+ *                      the condition, so it must not assert — it reports the
+ *                      condition and stops.
+ *  - `unrecognised`  — not in the catalog. This is a statement about VIGILES,
+ *                      not about the repo being audited, and the message says so.
+ *
+ * THE THIRD OPTION. `unrecognised` is why this module exists. Silence reads as
+ * approval and hides our own staleness; an error blames the user for our gap.
+ * The honest third answer is an ADVISORY that names vigiles as the possibly-stale
+ * party and prints the capture the catalog came from. It is surfaced and it is
+ * never scored, so a name newer than our capture can never cost anyone a grade.
+ *
+ * WHY THE DISTANCE IS NOT ON THE VERDICT. {@link TermVerdict}'s `unrecognised`
+ * branch carries no near-match. A caller therefore CANNOT write
+ * `if (nearest) report()` — the shape that produced both bugs — because at the
+ * point where the report/skip decision is made, no distance is in scope.
+ * {@link suggest} exists solely to decorate a message that is already being
+ * emitted, and is called from the message builder, not from a branch.
+ *
+ * FAILING LOUDLY. `classify` is total: every name returns one of four cases, so
+ * a `switch` that forgets one is a `tsc` error via the `never` exhaustiveness
+ * check in {@link termIssue}. There is no `null`/`undefined` return to ignore.
+ *
+ * GOING STALE. It will. `capturedFrom` records the exact vendor artifact and
+ * version each catalog was read from, and every name we do not hold prints it.
+ * That is the difference from an ordinary allowlist: this one reports its own
+ * age at the moment it is out of date, rather than silently approving the word
+ * it has never heard of.
+ */
+const edit_distance_js_1 = require("./edit-distance.js");
+/** Look the name up. Total: always one of the four verdicts, never null. */
+function classify(vocab, name) {
+    const term = vocab.terms.find((t) => t.name === name);
+    if (term === undefined)
+        return { kind: "unrecognised", name };
+    switch (term.status) {
+        case "available":
+            return { kind: "available", term };
+        case "withheld":
+            return { kind: "withheld", term };
+        case "conditional":
+            return { kind: "conditional", term };
+    }
+}
+/**
+ * Closest catalog name within edit distance 2, else null — a MESSAGE decoration
+ * only. Never call this to decide whether to report something; the verdict has
+ * already decided that. The ≤2 bound stays tight for the reason it always was:
+ * a loose bound mis-suggests (`TaskGet → Task?` is a different real tool, not a
+ * typo). Only `available` terms are offered — suggesting a name the platform
+ * withholds would trade one dead reference for another.
+ */
+function suggest(vocab, name) {
+    const near = nearest(vocab, name);
+    return near !== null && near.distance <= SUGGEST_MAX ? near.name : null;
+}
+/** How far a hint may reach. Beyond this a "did you mean" mis-suggests. */
+const SUGGEST_MAX = 2;
+/**
+ * How close an unrecognised name must be to a real one before vigiles will call
+ * it a TYPO and put it in the grade, rather than treating it as a name it simply
+ * does not know.
+ *
+ * MEASURED, not assumed — and the measurement is the whole reason the old check
+ * failed. Over every pair of distinct names in the two shipped Claude Code
+ * vocabularies (465 hook-event pairs, 741 subagent-tool pairs):
+ *
+ *   distance 1 : 0 pairs of the 1,206
+ *   distance 2 : exactly 1 pair in each — `Setup`/`Stop` and `Bash`/`Task`
+ *
+ * So the vendor does not ship two real names one edit apart, which makes
+ * distance 1 strong evidence of a mistyped name. Distance 2, on the other hand,
+ * is exactly where two genuinely different real names DO collide — and the one
+ * event-pair that collides there is the bug itself: the old code used ≤2 as its
+ * threshold and therefore accused `Setup`, a real event, of being a typo of
+ * `Stop`. The old bound was not merely too loose, it was set precisely at the
+ * width of the collision.
+ *
+ * Hence: distance 1 is scored, distance 2 still earns a did-you-mean but stays
+ * advisory. RESIDUAL RISK, stated plainly: if the vendor ever ships a name one
+ * edit from an existing one, it will be scored as a typo until the catalog is
+ * updated. Zero of 1,206 current pairs are that close, and `dialect-drift` plus
+ * the conformance invariants are what surface the catalog falling behind.
+ */
+const TYPO_MAX = 1;
+/** Closest catalog name and its distance, or null when the vocabulary is empty. */
+function nearest(vocab, name) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const t of vocab.terms) {
+        if (t.status === "withheld")
+            continue;
+        const d = (0, edit_distance_js_1.editDistance)(name.toLowerCase(), t.name.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = t.name;
+        }
+    }
+    return best === null ? null : { name: best, distance: bestDistance };
+}
+/**
+ * Turn a verdict into the finding to report, or null when there is nothing to
+ * say. The severity is decided HERE, once, from the verdict — callers never
+ * invent their own policy, which is what let `scan` and `lint` drift apart from
+ * `compileAgent` before.
+ *
+ * `noun` names the thing in the message ("hook event" / "tool"); `subject`
+ * describes what listing it does, e.g. "a hook here never fires".
+ */
+function termIssue(vocab, verdict, noun, deadConsequence) {
+    switch (verdict.kind) {
+        case "available":
+            return null;
+        case "conditional": {
+            const alias = verdict.term.aliasOf !== undefined
+                ? ` "${verdict.term.name}" is a still-supported deprecated alias of "${verdict.term.aliasOf}".`
+                : "";
+            return {
+                verdict: "conditional",
+                severity: "advisory",
+                suggestion: null,
+                condition: verdict.term.condition,
+                message: `${noun} "${verdict.term.name}" is available to a subagent, but the platform ` +
+                    `removes it ${verdict.term.condition ?? "under a documented condition"}. ` +
+                    `vigiles cannot see that condition from the file, so this is a note, not a defect.${alias}`,
+            };
+        }
+        case "withheld":
+            return {
+                verdict: "withheld",
+                severity: "scored",
+                suggestion: null,
+                message: `${noun} "${verdict.term.name}" is never available to a subagent — remove it from the tools list.`,
+            };
+        case "unrecognised": {
+            const near = nearest(vocab, verdict.name);
+            const suggestion = near !== null && near.distance <= SUGGEST_MAX ? near.name : null;
+            // One edit from a real name, and no two real names are that close (see
+            // TYPO_MAX): this is a mistyped name, and it is dead in the repo now.
+            if (near !== null && near.distance <= TYPO_MAX)
+                return {
+                    verdict: "unrecognised",
+                    severity: "scored",
+                    suggestion,
+                    message: `${noun} "${verdict.name}" matches no known name — ${deadConsequence}. ` +
+                        `Did you mean "${near.name}"?`,
+                };
+            const hint = suggestion !== null ? ` Did you mean "${suggestion}"?` : "";
+            return {
+                verdict: "unrecognised",
+                severity: "advisory",
+                suggestion,
+                message: `${noun} "${verdict.name}" is not in vigiles's ${vocab.kind} catalog ` +
+                    `(captured from ${vocab.capturedFrom}). If it is newer than that capture, or ` +
+                    `custom to your harness, vigiles is out of date — not your config. ` +
+                    `If it is a typo, ${deadConsequence}.${hint}`,
+            };
+        }
+        default: {
+            // Exhaustiveness: a new verdict kind with no branch is a tsc error here,
+            // so a future status cannot be silently dropped on the floor.
+            const never = verdict;
+            return never;
+        }
+    }
+}
+/**
+ * The issues that count toward a grade. Replaces the per-check
+ * `confidentToolIssues` / `confidentHookEventIssues` helpers, which asked "is
+ * there a near match?" — a question about spelling, answered by a helper each
+ * caller had to remember to apply and which `compileAgent` did not, so `scan`,
+ * `lint` and authoring could disagree about which issues were real. Severity now
+ * travels ON the issue, decided once in {@link termIssue}, so the split is the
+ * same wherever it is taken.
+ */
+function scoredIssues(issues) {
+    return issues.filter((i) => i.severity === "scored");
+}
+/**
+ * The issues that are surfaced but never scored — `conditional` tools and any
+ * name newer than our capture. Kept out of the grade on purpose: vigiles's own
+ * staleness must not cost someone a letter.
+ */
+function advisoryIssues(issues) {
+    return issues.filter((i) => i.severity === "advisory");
+}
+/**
+ * The issues an AUTHORING path treats as errors — everything except
+ * `conditional`. Authoring is a CLOSED world: you are writing this spec now,
+ * against the vigiles you have, so an unrecognised name is a typo worth stopping
+ * for. Auditing is an OPEN world: someone else wrote the file, possibly against
+ * a newer platform, so there the same verdict is only an advisory.
+ *
+ * `conditional` is an error in NEITHER. The tool is real and declaring it is
+ * correct; erroring on it is exactly what told delegating subagents to drop
+ * `Agent`, and what made `tools: Agent, Read, Bash` — a worked example in the
+ * vendor's own docs — fail to compile.
+ */
+function authoringIssues(issues) {
+    return issues.filter((i) => i.verdict !== "conditional");
+}
+/**
+ * Build a vocabulary from a dialect that predates this module — `available` from
+ * its built-in catalog, `withheld` from its never-available list. A dialect on
+ * the legacy shape keeps working and its unknowns become `unrecognised`
+ * ADVISORIES rather than silence, which is the honest reading: a catalog with no
+ * recorded capture cannot claim a name is invalid.
+ */
+function vocabularyFromLists(kind, capturedFrom, available, withheld = []) {
+    return {
+        kind,
+        capturedFrom,
+        terms: [
+            ...available.map((name) => ({ name, status: "available" })),
+            ...withheld.map((name) => ({ name, status: "withheld" })),
+        ],
+    };
+}
+//# sourceMappingURL=vocabulary.js.map

package/dist/eval-define.d.ts

@@ -0,0 +1,166 @@
+import type { ArmsCheckReport, EvalDriver, ArmsMeasureSpec, CheckReport, EvalReport, EvalSpec, MeasureSpec, Metrics, TriggerRateReport, TriggerRateSpec } from "./eval.js";
+import type { SelectionMatrixOptions, SelectionReport } from "./scan-behavioral.js";
+/**
+ * Brand marking a value as built by {@link defineEval}. A registered symbol, so
+ * a descriptor still reads as one across two copies of the package on disk —
+ * the shape a monorepo produces routinely.
+ */
+export declare const EVAL_DEFINITION: unique symbol;
+/** `measureSelectionMatrix`'s two arguments as one declarable object. */
+export interface SelectionMatrixSpec extends SelectionMatrixOptions {
+    /** The plugin root whose skills are measured against each other. */
+    readonly pluginDir: string;
+}
+/**
+ * The five measurements an eval file may declare — the runners that already
+ * exist, keyed by their own names, so migrating is renaming a call to a key.
+ * EXACTLY ONE must be present: zero is a file that declares nothing, and two is
+ * a file whose author expected both to run.
+ */
+export interface EvalMeasurements {
+    /** A/B across arms with derived metrics — `paid_runEval`. */
+    readonly runEval?: EvalSpec<Metrics>;
+    /** Checks scored over N trials of one task — `paid_measure`. */
+    readonly measure?: MeasureSpec;
+    /** The same checks per arm — `paid_measureArms`. */
+    readonly measureArms?: ArmsMeasureSpec;
+    /** Does a skill's description actually fire — `paid_measureTriggerRate`. */
+    readonly measureTriggerRate?: TriggerRateSpec;
+    /**
+     * The N×N skill-selection collision matrix — `measureSelectionMatrix` from
+     * `vigiles/claude-code`. Declared here because a description is a description
+     * whatever harness answers it; only `eval-entry.ts` resolves it to a runner.
+     */
+    readonly measureSelectionMatrix?: SelectionMatrixSpec;
+}
+/** The report type produced by each declared measurement. */
+export interface EvalReports {
+    readonly runEval: EvalReport;
+    readonly measure: CheckReport;
+    readonly measureArms: ArmsCheckReport;
+    readonly measureTriggerRate: TriggerRateReport;
+    readonly measureSelectionMatrix: SelectionReport;
+}
+/** The measurement names, as a type. */
+export type EvalKind = keyof EvalMeasurements;
+/** Everything an eval file declares beyond the measurement itself. */
+export interface EvalHooks<K extends EvalKind> {
+    /**
+     * A lazy precondition. Return a reason to SKIP (exit 77, loud — never a silent
+     * green); return nothing to run. Lazy is the point: a probe at the top of the
+     * file would be work at import time, which is the shape being removed.
+     */
+    readonly skipIf?: () => string | false | undefined | null;
+    /**
+     * What the report has to show. Throw to fail. The runner has already printed
+     * the standard report by the time this is called, so this is for the derived
+     * reads — gates, per-arm significance, a verdict line.
+     */
+    readonly assert?: (report: EvalReports[K]) => void | Promise<void>;
+    /**
+     * Drive the measurement with this harness instead of the real `claude` CLI —
+     * the declarative home for the second argument of
+     * `measureTriggerRate(spec, { evalDriver })`, e.g. `codexEvalDriver` from
+     * `vigiles/codex`, or a fake runner in a test.
+     *
+     * ⚠️ `measureTriggerRate` ONLY. That is not a limitation of this shape but of
+     * the product as it stands: `measureTriggerRate` is the one measurement with a
+     * public driver seam, and `runEval(spec)` always drives Claude Code (see
+     * docs/harnesses.md, footnote 2). Declaring it with any other measurement is a
+     * loud error rather than a field that silently does nothing.
+     */
+    readonly evalDriver?: EvalDriver;
+}
+/** One measurement + its hooks: what an eval file default-exports. */
+export type EvalDefinitionInput<K extends EvalKind> = Pick<EvalMeasurements, K> & EvalHooks<K>;
+/** The branded value {@link defineEval} returns. */
+export type EvalDefinition<K extends EvalKind = EvalKind> = EvalDefinitionInput<K> & {
+    readonly [EVAL_DEFINITION]: true;
+};
+/**
+ * What a module's default export declares. Total: every answer the runner has to
+ * distinguish is a case here, so no caller can forget one.
+ */
+export type DeclaredEval = {
+    readonly ok: true;
+    readonly kind: EvalKind;
+    readonly spec: unknown;
+} | {
+    readonly ok: false;
+    readonly why: "not-a-definition";
+} | {
+    readonly ok: false;
+    readonly why: "declares-nothing";
+} | {
+    readonly ok: false;
+    readonly why: "declares-several";
+    readonly kinds: readonly EvalKind[];
+};
+/** The measurement keys, in a fixed order — the one list, read by everything. */
+export declare const EVAL_KINDS: readonly EvalKind[];
+/** Whether a value came from {@link defineEval}. */
+export declare function isEvalDefinition(v: unknown): v is EvalDefinition;
+/**
+ * Read a module's default export as a declaration. Pure — this is the whole
+ * reason the descriptor is data: the runner answers "what does this file
+ * declare?" without executing anything and without spending anything.
+ */
+export declare function declaredEval(def: unknown): DeclaredEval;
+/**
+ * The definition a module namespace carries, through the CJS/ESM interop layer.
+ *
+ * 🔴 THE SECOND `.default` IS NOT DEFENSIVE — it is the only way a TypeScript
+ * eval file works, and it was found by a test, not by reading. Three shapes
+ * reach this function and they are genuinely different objects:
+ *
+ *   x.eval.mjs   real ESM        → `mod.default` IS the definition
+ *   x.eval.cjs   `module.exports = defineEval(…)`
+ *                                → `mod.default` is `module.exports`, the definition
+ *   x.eval.ts    `export default …`, transpiled to CJS by tsx
+ *                                → `mod.default` is `module.exports`, and the
+ *                                  definition sits at `mod.default.default`
+ *
+ * Measured 2026-08-18: without the unwrap a `.eval.ts` file reported
+ * "no `export default defineEval({…})` found" — a correct file, refused, with a
+ * message that sent its author looking in the wrong place.
+ *
+ * Brand-directed rather than shape-directed: it reaches deeper ONLY when the
+ * outer value is not a definition, so a definition that happens to carry a
+ * `default` field of its own is never skipped over.
+ */
+export declare function moduleDefault(mod: unknown): unknown;
+/**
+ * Was node pointed STRAIGHT at an eval file? `argv1` is `process.argv[1]`: the
+ * path node was started with, which no stray configuration can forge.
+ *
+ *   node x.eval.mjs                 → the file            → true
+ *   vigiles eval x.eval.mjs         → dist/eval-entry.js  → false
+ *   node -e 'import("x.eval.mjs")'  → undefined           → false
+ *   npx vitest run                  → …/vitest/…/forks.js → false
+ *
+ * Pure: a fact in, a boolean out.
+ */
+export declare function ranAsEntry(argv1: string | undefined): boolean;
+/** The words shown when someone runs an eval file directly. Asserted by a test:
+ *  a refusal that stops a run without saying what to do instead is a ticket. */
+export declare function ranAsEntryRefusal(argv1: string): string;
+/**
+ * Declare the eval a file describes. Returns a plain, branded value; it starts
+ * nothing, spends nothing, and touches no filesystem.
+ *
+ * ```js
+ * import { defineEval, assertRates } from "vigiles";
+ * import { skill } from "vigiles";
+ *
+ * export default defineEval({
+ *   measure: { pluginDir, task: "…", checks: [skill("my:skill")], trials: 3 },
+ *   assert: (report) => assertRates(report, { min: 0.6 }),
+ * });
+ * ```
+ *
+ * @throws if node was pointed straight at the eval file — see the module doc.
+ *   That is the ONE thing this function does besides build a value, and it is
+ *   here rather than in each file precisely so that no author can forget it.
+ */
+export declare function defineEval<K extends EvalKind>(def: EvalDefinitionInput<K>): EvalDefinition<K>;
+//# sourceMappingURL=eval-define.d.ts.map

package/dist/eval-define.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVAL_KINDS = exports.EVAL_DEFINITION = void 0;
+exports.isEvalDefinition = isEvalDefinition;
+exports.declaredEval = declaredEval;
+exports.moduleDefault = moduleDefault;
+exports.ranAsEntry = ranAsEntry;
+exports.ranAsEntryRefusal = ranAsEntryRefusal;
+exports.defineEval = defineEval;
+/**
+ * `defineEval` — an eval file DESCRIBES its eval; `vigiles eval` runs it.
+ *
+ * ## The defect this shape removes
+ *
+ * Eval files used to do their work in the module body:
+ *
+ *   const report = await measureTriggerRate({ … });    // ← top level
+ *   console.log(formatTriggerRateReport(report));
+ *   assertTriggerRate(report, { min: 0.6 });
+ *
+ * In ESM, `import` IS execution. So the cheapest imaginable question — "does
+ * this file even parse?" — answered with `import()` launched a real, paid run
+ * against a real model. That happened, and was paid for, on 2026-08-12.
+ *
+ * The fix is not a better warning. It is that the file no longer HOLDS a runner:
+ *
+ *   export default defineEval({
+ *     measureTriggerRate: { … },                       // ← data
+ *     assert: (r) => assertTriggerRate(r, { min: 0.6 }),
+ *   });
+ *
+ * `defineEval` builds a plain value. There is nothing in it to run, so importing
+ * it starts nothing — not "is discouraged from starting"; there is no call. The
+ * five paid runners are reached only by `eval-entry.ts`, the module `vigiles
+ * eval` spawns. After the migration, ZERO of this repo's 19 eval files import a
+ * runner at all: the paid subpath is no longer part of an eval file's vocabulary.
+ * (18 were already named `*.eval.*`; `from-promptfoo.mjs` was renamed in, because
+ * it ran a paid runner at the top level while sitting outside the runner's glob —
+ * the same defect in a file nothing would have caught.)
+ *
+ * ## Why data and not a callback
+ *
+ * `defineEval({ run: async ({ measure }) => … })` would also make importing
+ * inert, and it was rejected on a measurable difference: with a callback the
+ * runner cannot know WHAT a file declares without executing it, so "this file
+ * declares no eval" becomes undecidable, and the loud report on an unmigrated
+ * file — the whole discovery path — becomes impossible. With data it is a
+ * property of the value, decided before a cent is spent. (See
+ * `eval-define.test.ts`, which asserts exactly that on a fixture.)
+ *
+ * ## Running the file directly is a LOUD failure, not a no-op
+ *
+ * Every old eval file was documented as `node path/to/x.eval.mjs`, and that
+ * habit outlives the migration. A pure description run that way would print
+ * nothing and exit 0 — a silent no-op, the same class of defect in a new place.
+ * So `defineEval` refuses when node was pointed straight at an eval file (a
+ * POSITIVE identification from `process.argv[1]`, the same fact and the same
+ * reasoning `foreign-runner.ts` uses; it cannot be forged by configuration).
+ * `node --check <file>` — the free syntax check people should be reaching for —
+ * never executes, so it is untouched.
+ */
+const node_path_1 = require("node:path");
+/**
+ * Brand marking a value as built by {@link defineEval}. A registered symbol, so
+ * a descriptor still reads as one across two copies of the package on disk —
+ * the shape a monorepo produces routinely.
+ */
+exports.EVAL_DEFINITION = Symbol.for("vigiles.eval.definition");
+/** The measurement keys, in a fixed order — the one list, read by everything. */
+exports.EVAL_KINDS = [
+    "runEval",
+    "measure",
+    "measureArms",
+    "measureTriggerRate",
+    "measureSelectionMatrix",
+];
+/** Whether a value came from {@link defineEval}. */
+function isEvalDefinition(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        v[exports.EVAL_DEFINITION] === true);
+}
+/**
+ * Read a module's default export as a declaration. Pure — this is the whole
+ * reason the descriptor is data: the runner answers "what does this file
+ * declare?" without executing anything and without spending anything.
+ */
+function declaredEval(def) {
+    if (!isEvalDefinition(def))
+        return { ok: false, why: "not-a-definition" };
+    const rec = def;
+    const present = exports.EVAL_KINDS.filter((k) => rec[k] !== undefined);
+    if (present.length === 0)
+        return { ok: false, why: "declares-nothing" };
+    if (present.length > 1)
+        return { ok: false, why: "declares-several", kinds: present };
+    const kind = present[0];
+    if (kind === undefined)
+        return { ok: false, why: "declares-nothing" };
+    return { ok: true, kind, spec: rec[kind] };
+}
+/**
+ * The definition a module namespace carries, through the CJS/ESM interop layer.
+ *
+ * 🔴 THE SECOND `.default` IS NOT DEFENSIVE — it is the only way a TypeScript
+ * eval file works, and it was found by a test, not by reading. Three shapes
+ * reach this function and they are genuinely different objects:
+ *
+ *   x.eval.mjs   real ESM        → `mod.default` IS the definition
+ *   x.eval.cjs   `module.exports = defineEval(…)`
+ *                                → `mod.default` is `module.exports`, the definition
+ *   x.eval.ts    `export default …`, transpiled to CJS by tsx
+ *                                → `mod.default` is `module.exports`, and the
+ *                                  definition sits at `mod.default.default`
+ *
+ * Measured 2026-08-18: without the unwrap a `.eval.ts` file reported
+ * "no `export default defineEval({…})` found" — a correct file, refused, with a
+ * message that sent its author looking in the wrong place.
+ *
+ * Brand-directed rather than shape-directed: it reaches deeper ONLY when the
+ * outer value is not a definition, so a definition that happens to carry a
+ * `default` field of its own is never skipped over.
+ */
+function moduleDefault(mod) {
+    const outer = mod?.default;
+    if (isEvalDefinition(outer))
+        return outer;
+    const inner = outer?.default;
+    return isEvalDefinition(inner) ? inner : outer;
+}
+/** Filenames vigiles runs as evals — the runner's own glob, as a pattern. */
+const EVAL_FILE = /\.eval\.(?:m|c)?[jt]s$/;
+/**
+ * Was node pointed STRAIGHT at an eval file? `argv1` is `process.argv[1]`: the
+ * path node was started with, which no stray configuration can forge.
+ *
+ *   node x.eval.mjs                 → the file            → true
+ *   vigiles eval x.eval.mjs         → dist/eval-entry.js  → false
+ *   node -e 'import("x.eval.mjs")'  → undefined           → false
+ *   npx vitest run                  → …/vitest/…/forks.js → false
+ *
+ * Pure: a fact in, a boolean out.
+ */
+function ranAsEntry(argv1) {
+    return argv1 !== undefined && EVAL_FILE.test(argv1.replaceAll("\\", "/"));
+}
+/** The words shown when someone runs an eval file directly. Asserted by a test:
+ *  a refusal that stops a run without saying what to do instead is a ticket. */
+function ranAsEntryRefusal(argv1) {
+    const f = (0, node_path_1.basename)(argv1);
+    return (`\`node ${f}\` no longer runs this eval — the file DESCRIBES one.\n` +
+        `  An eval file that ran itself spent real money on a plain import, so the work moved\n` +
+        `  into \`vigiles eval\`, which is the only thing that runs a description.\n` +
+        `  → run it:      npx vigiles eval ${argv1}\n` +
+        `  → check syntax without running anything: node --check ${argv1}`);
+}
+/**
+ * Declare the eval a file describes. Returns a plain, branded value; it starts
+ * nothing, spends nothing, and touches no filesystem.
+ *
+ * ```js
+ * import { defineEval, assertRates } from "vigiles";
+ * import { skill } from "vigiles";
+ *
+ * export default defineEval({
+ *   measure: { pluginDir, task: "…", checks: [skill("my:skill")], trials: 3 },
+ *   assert: (report) => assertRates(report, { min: 0.6 }),
+ * });
+ * ```
+ *
+ * @throws if node was pointed straight at the eval file — see the module doc.
+ *   That is the ONE thing this function does besides build a value, and it is
+ *   here rather than in each file precisely so that no author can forget it.
+ */
+function defineEval(def) {
+    /* v8 ignore next 3 -- the entry-point branch is exercised through a child process (eval-define.test.ts) */
+    const argv1 = process.argv[1];
+    if (argv1 !== undefined && ranAsEntry(argv1))
+        throw new Error(ranAsEntryRefusal(argv1));
+    return { ...def, [exports.EVAL_DEFINITION]: true };
+}
+//# sourceMappingURL=eval-define.js.map

package/dist/eval-entry.d.ts

@@ -0,0 +1,41 @@
+import { type EvalKind } from "./eval-define.js";
+import { type ArmsCheckReport, type CheckReport, type EvalReport, type TriggerRateReport } from "./eval.js";
+import { type SelectionReport } from "./scan-behavioral.js";
+/** Every report this entry can produce. */
+type AnyReport = EvalReport | CheckReport | ArmsCheckReport | TriggerRateReport | SelectionReport;
+/**
+ * How many trials this run should use, or `undefined` to leave the spec alone.
+ * `vigiles eval --trials=N` arrives as `VIGILES_TRIALS`; a spec's own `trials` is
+ * the default. Pure — exported for the tests.
+ *
+ * A non-numeric or non-positive value is IGNORED rather than treated as zero: a
+ * typo'd `--trials=` must not silently turn a measurement into a no-op.
+ */
+export declare function trialsOverride(raw: string | undefined): number | undefined;
+/**
+ * How many runs a report is built from, or `undefined` when the shape carries no
+ * such count. Pure. Every measurement has one, but under two different names and
+ * at two different depths, which is exactly why each eval file used to
+ * hand-write its own `report.n === 0` check (and why several forgot to).
+ */
+export declare function runsIn(report: AnyReport): number | undefined;
+/**
+ * `evalDriver` is only wired on `measureTriggerRate` — the only measurement with
+ * a public driver seam. Naming it beside any other measurement is a mistake the
+ * runner REFUSES rather than ignores: a field that silently does nothing would
+ * send a Codex user's eval to Claude Code and report the number as theirs.
+ */
+export declare function driverMisplaced(kind: EvalKind, hasDriver: boolean): string | undefined;
+/**
+ * The message for a file that is not a description. Separate from the flow so a
+ * test can assert the WORDS — this is the ONLY thing an author sees when their
+ * pre-migration eval file stops working, so it has to teach the new shape.
+ */
+export declare function notADescriptionMessage(file: string, why: string): string;
+/** The `why` line for each way a default export can fail to be a declaration. */
+export declare function declarationProblem(d: {
+    why: "not-a-definition" | "declares-nothing" | "declares-several";
+    kinds?: readonly EvalKind[];
+}): string;
+export {};
+//# sourceMappingURL=eval-entry.d.ts.map