vigiles 31.0.0 → 32.0.0

package/dist/core/coverage.d.ts

@@ -8,6 +8,7 @@
  * Configurable thresholds in .vigilesrc.json trigger warnings or errors when
  * coverage drops below the minimum.
  */
+import { type GlobIgnore } from "./glob-ignore.js";
 import type { CoverageThresholds } from "./types.js";
 import type { ClaudeSpec } from "./spec.js";
 export interface CoverageMetric {
@@ -35,11 +36,11 @@ export declare function readNpmScripts(basePath: string): string[];
  * Collect commands documented in specs by loading spec source files directly.
  * Reads the structured `commands` field — no markdown parsing.
  */
-export declare function collectDocumentedCommands(basePath: string, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): Set<string>;
+export declare function collectDocumentedCommands(basePath: string, specs: ClaudeSpec[] | undefined, ignore: GlobIgnore): Set<string>;
 /**
  * Compute script coverage: what % of npm scripts are documented in specs.
  */
-export declare function computeScriptCoverage(basePath: string, threshold: number | undefined, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): CoverageMetric;
+export declare function computeScriptCoverage(basePath: string, threshold: number | undefined, specs: ClaudeSpec[] | undefined, ignore: GlobIgnore): CoverageMetric;
 /**
  * Compute linter rule coverage from pre-computed totals.
  * The actual linter scanning is done by the existing discover() in cli.ts.
@@ -48,7 +49,7 @@ export declare function computeLinterRuleCoverage(enabled: number, documented: n
 /**
  * Check all coverage metrics against thresholds.
  */
-export declare function checkCoverage(basePath: string, thresholds: CoverageThresholds, linterEnabled: number, linterDocumented: number, specs: ClaudeSpec[] | undefined, ignore: readonly string[]): CoverageReport;
+export declare function checkCoverage(basePath: string, thresholds: CoverageThresholds, linterEnabled: number, linterDocumented: number, specs: ClaudeSpec[] | undefined, ignore: GlobIgnore): CoverageReport;
 /**
  * Format coverage report as human-readable text.
  */

package/dist/core/coverage.js

@@ -20,6 +20,7 @@ const node_fs_1 = require("node:fs");
 const integrity_js_1 = require("./integrity.js");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./glob-ignore.js");
 const compile_js_1 = require("./compile.js");
 // ---------------------------------------------------------------------------
 // Script coverage
@@ -50,12 +51,12 @@ function collectDocumentedCommands(basePath, specs, ignore) {
     // Fallback: scan compiled markdown for spec file references, then
     // load the compiled JS spec from dist/. If that fails, try to
     // extract commands from the compiled output (last resort).
-    // `ignore` is the repo's ExcludeSet string face (src/exclude.ts): the floor
-    // plus `.vigilesrc.json#exclude`, required so this fallback cannot walk a
+    // `ignore` is the repo's `ExcludeSet.globIgnore` (src/exclude.ts, correct
+    // from any cwd) or patterns relative to `basePath`, required so this fallback cannot walk a
     // vendored corpus the repo excluded (#192). The CLI always passes `specs`,
     // so this branch is reached by the library path and tests only.
     const mdFiles = (0, glob_1.globSync)("**/*.md", {
-        ignore: [...ignore],
+        ignore: (0, glob_ignore_js_1.withIgnored)([], ignore),
         cwd: basePath,
     });
     for (const mdFile of mdFiles) {

package/dist/core/doc-refs.d.ts

@@ -17,6 +17,7 @@
  * in markdown is explicitly out of scope — use eslint-plugin-markdown or
  * twoslash for that.
  */
+import { type GlobIgnore } from "./glob-ignore.js";
 export type DocRefKind = "enforce" | "file" | "cmd" | "ref";
 export interface DocRef {
     readonly file: string;
@@ -40,7 +41,8 @@ export interface DocRefReport {
 }
 export interface FindDocRefsOptions {
     readonly basePath?: string;
-    readonly ignore?: readonly string[];
+    /** The repo exclude (`ExcludeSet.globIgnore`), or patterns relative to `basePath`. */
+    readonly ignore?: GlobIgnore;
 }
 interface ExtractResult {
     refs: DocRef[];

package/dist/core/doc-refs.js

@@ -29,6 +29,7 @@ const node_fs_1 = require("node:fs");
 const typescript_1 = __importDefault(require("typescript"));
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./glob-ignore.js");
 const linters_js_1 = require("./linters.js");
 const compile_js_1 = require("./compile.js");
 // ---------------------------------------------------------------------------
@@ -239,7 +240,7 @@ function validateRefs(refs, basePath) {
  */
 function findDocRefs(options = {}) {
     const basePath = options.basePath ?? process.cwd();
-    const ignore = [...DEFAULT_IGNORE, ...(options.ignore ?? [])];
+    const ignore = (0, glob_ignore_js_1.withIgnored)(DEFAULT_IGNORE, options.ignore);
     const files = (0, glob_1.globSync)("**/*.md", { cwd: basePath, ignore });
     const allRefs = [];
     let filesIgnored = 0;

package/dist/core/frame.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The frame of a path — WHICH DIRECTORY it is relative to — named by its TYPE
+ * rather than by a comment (#281).
+ *
+ * 🔴 WHY THIS EXISTS. Every path the CLI handled was a bare `string`, so a path
+ * relative to a nested bundle, one relative to the repository and an absolute one
+ * were the same type, and nothing stopped a caller from printing the wrong one.
+ * `overBundles` handed each check ONE `root: string` that had to be the discovery
+ * base, the base of the config's globs AND the frame of every printed path at
+ * once. Under `bundles: "all"` that root was the nested bundle, so `include`
+ * resolved from the wrong directory and `::warning file=skills/x/SKILL.md` named a
+ * file that did not exist from where the command ran — while a root-bundle skill
+ * of the same name made the annotation land on the WRONG real file, which looks
+ * like success.
+ *
+ * Three frames, two of them branded:
+ *   - {@link RepoPath} — relative to {@link Frame.root}, the directory whose
+ *     `.vigilesrc.json` governs the run. Every printed or annotated path.
+ *   - {@link BundlePath} — relative to one {@link Bundle}'s own directory. What a
+ *     per-bundle scan reports.
+ *   - an absolute path — a plain `string`, the only thing the filesystem takes.
+ *
+ * The brand is `Opaque` from `ts-essentials` (a `unique symbol` key, so no object
+ * literal can forge it), imported as a TYPE ONLY: nothing of it survives the
+ * build. It must not reach a public `.d.ts` either — this module is internal and
+ * the API report (`api-surface/*.api.md`) is the gate that would show a leak.
+ *
+ * 🔴 THE ONE CONVERSION POINT. A `RepoPath` is minted here and nowhere else:
+ * {@link Frame.repo} from an absolute path, {@link Bundle.path} from a
+ * `BundlePath`. A cast to `RepoPath` outside this file is refused by ESLint
+ * (`no-restricted-syntax` in `eslint.config.mjs`), so "where did this path get its
+ * frame" always has the answer "in frame.ts".
+ *
+ * WHAT IS UNREPRESENTABLE AND WHAT IS ONLY DETECTABLE. The CLI's output boundary
+ * (`ghAnnotate`, the per-bundle check context) takes `RepoPath`, so handing it a
+ * bundle-relative or absolute string is a tsc error. Upstream of that, scan-core
+ * keeps reporting plain bundle-relative strings, because its browser twin
+ * (`scan-files.ts`) shares those shapes and has no filesystem to have a frame
+ * over. {@link Bundle.scanned} is the seam where such a string gets its frame;
+ * a relative string that is secretly repo-relative still passes it, and that
+ * residue is caught by tests, not by the compiler.
+ *
+ * NODE-FREE: path ops come from `../posix-path.js`, and the caller supplies the
+ * working directory, so this module has no process state of its own.
+ */
+import type { Opaque } from "ts-essentials";
+/** A `/`-separated path relative to {@link Frame.root}. `.` is the root itself. */
+export type RepoPath = Opaque<string, "RepoPath">;
+/** A `/`-separated path relative to one {@link Bundle}'s own directory. */
+export type BundlePath = Opaque<string, "BundlePath">;
+/** One scored directory: the lint target itself, or a nested plugin bundle. */
+export interface Bundle {
+    /** Absolute directory of the bundle. */
+    readonly abs: string;
+    /** Where the bundle sits, from the frame root (`.` when it IS the root). */
+    readonly at: RepoPath;
+    /** A path this bundle's scan reported, re-expressed from the frame root. */
+    path(p: BundlePath): RepoPath;
+    /**
+     * The seam for scan-core's plain strings, which are bundle-relative by
+     * contract (see the header). An ABSOLUTE string is accepted too and converted
+     * directly — `hook-block-ineffective` reports its script that way.
+     */
+    scanned(p: string): RepoPath;
+}
+/** The single owner of "relative to which directory", built once per command. */
+export interface Frame {
+    /** Absolute directory every {@link RepoPath} is relative to. */
+    readonly root: string;
+    /** The one conversion from an absolute path. Throws on a relative input. */
+    repo(abs: string): RepoPath;
+    /** Describe the bundle at an absolute directory, in this frame. */
+    bundle(abs: string): Bundle;
+}
+/**
+ * The frame for a command run from `cwd` against `target` (absolute).
+ *
+ * The root is `cwd` — where `loadConfig()` read `.vigilesrc.json` (it does not
+ * walk up; measured 2026-09-23) — UNLESS the target lies outside it. A foreign
+ * target (`vigiles lint ../other`) is somebody else's repository, and its paths
+ * mean something from ITS root; relative to `cwd` they would all start with
+ * `../`, and a foreign lint must never let the caller's own files satisfy the
+ * target's `sharedDirs` references. That exception was `sharedDirsRootFor` in
+ * the CLI, applied to `sharedDirs` alone; it is owned here now, so `include`,
+ * `exclude`, `sharedDirs` and every printed path agree on one root.
+ */
+export declare function frameFor(cwd: string, target: string): Frame;
+/** The frame rooted at an absolute directory. */
+export declare function frameAt(root: string): Frame;
+//# sourceMappingURL=frame.d.ts.map

package/dist/core/frame.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.frameFor = frameFor;
+exports.frameAt = frameAt;
+const posix_path_js_1 = require("../posix-path.js");
+/**
+ * Node on Windows hands out `C:\\repo`, and `../posix-path.js` recognises only a leading `/`
+ * as absolute. The frame works in `/`-separated form, so every path entering it passes here:
+ * backslashes become `/`, and a drive-letter path (`C:/…`) counts as absolute.
+ */
+function slashed(p) {
+    return p.replaceAll("\\", "/");
+}
+function isAbs(p) {
+    return (0, posix_path_js_1.isAbsolute)(p) || /^[A-Za-z]:\//.test(p);
+}
+/** `rel` is `abs`'s position below `root` when it does not climb out. */
+function isBelow(rel) {
+    return rel === "" || (rel !== ".." && !rel.startsWith("../"));
+}
+/**
+ * The frame for a command run from `cwd` against `target` (absolute).
+ *
+ * The root is `cwd` — where `loadConfig()` read `.vigilesrc.json` (it does not
+ * walk up; measured 2026-09-23) — UNLESS the target lies outside it. A foreign
+ * target (`vigiles lint ../other`) is somebody else's repository, and its paths
+ * mean something from ITS root; relative to `cwd` they would all start with
+ * `../`, and a foreign lint must never let the caller's own files satisfy the
+ * target's `sharedDirs` references. That exception was `sharedDirsRootFor` in
+ * the CLI, applied to `sharedDirs` alone; it is owned here now, so `include`,
+ * `exclude`, `sharedDirs` and every printed path agree on one root.
+ */
+function frameFor(cwd, target) {
+    return frameAt(isBelow((0, posix_path_js_1.relative)(slashed(cwd), slashed(target))) ? cwd : target);
+}
+/** The frame rooted at an absolute directory. */
+function frameAt(root) {
+    const base = (0, posix_path_js_1.normalize)(slashed(root));
+    const repo = (raw) => {
+        const abs = slashed(raw);
+        if (!isAbs(abs))
+            throw new Error(`frame.repo() takes an absolute path, got "${raw}" — a relative string has no frame to convert from`);
+        return ((0, posix_path_js_1.relative)(base, abs) || ".");
+    };
+    const bundle = (raw) => {
+        const dir = (0, posix_path_js_1.normalize)(slashed(raw));
+        const path = (p) => repo((0, posix_path_js_1.join)(dir, p));
+        return {
+            abs: dir,
+            at: repo(dir),
+            path,
+            // The ONE place a plain string is taken to be bundle-relative.
+            scanned: (p) => (isAbs(slashed(p)) ? repo(p) : path(p)),
+        };
+    };
+    return { root: base, repo, bundle };
+}
+//# sourceMappingURL=frame.js.map

package/dist/core/glob-ignore.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One `ignore` for `globSync` out of a detector's own string floor plus the
+ * repository's exclude — glob takes EITHER a pattern list OR one `IgnoreLike`,
+ * never both, so a detector that has both needs this union.
+ *
+ * 🔴 WHY THE REPO EXCLUDE ARRIVES AS AN `IgnoreLike` AND NOT AS STRINGS (#281).
+ * `ExcludeSet` used to hand detectors a string list whose patterns were relative
+ * to the repository root, with the precondition "only correct for a glob rooted
+ * AT that root" written in a comment. Two callers globbed from a nested bundle
+ * and broke it silently: a root-relative `skills/lonely` dropped
+ * `plugins/p/skills/lonely`, and the real exclusion never reached the bundle.
+ * `ExcludeSet.globIgnore` computes each candidate's position from the repo root
+ * itself, so it is correct from ANY glob `cwd`; the string face was retired.
+ *
+ * A plain string list is still accepted — for a direct library caller whose
+ * patterns are, by that caller's own contract, relative to the `cwd` it globs
+ * from. That is the one frame a string can safely carry.
+ */
+import { type IgnoreLike } from "glob";
+/** What a detector takes for "also skip these". */
+export type GlobIgnore = readonly string[] | IgnoreLike;
+/**
+ * `floor` (patterns relative to the glob's `cwd`) plus `extra`, in the form
+ * `globSync`'s `ignore` option accepts. Stays a plain list when both halves are
+ * lists, so a string-only caller sees exactly the glob behaviour it always had.
+ */
+export declare function withIgnored(floor: readonly string[], extra: GlobIgnore | undefined): string[] | IgnoreLike;
+//# sourceMappingURL=glob-ignore.d.ts.map

package/dist/core/glob-ignore.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withIgnored = withIgnored;
+/**
+ * One `ignore` for `globSync` out of a detector's own string floor plus the
+ * repository's exclude — glob takes EITHER a pattern list OR one `IgnoreLike`,
+ * never both, so a detector that has both needs this union.
+ *
+ * 🔴 WHY THE REPO EXCLUDE ARRIVES AS AN `IgnoreLike` AND NOT AS STRINGS (#281).
+ * `ExcludeSet` used to hand detectors a string list whose patterns were relative
+ * to the repository root, with the precondition "only correct for a glob rooted
+ * AT that root" written in a comment. Two callers globbed from a nested bundle
+ * and broke it silently: a root-relative `skills/lonely` dropped
+ * `plugins/p/skills/lonely`, and the real exclusion never reached the bundle.
+ * `ExcludeSet.globIgnore` computes each candidate's position from the repo root
+ * itself, so it is correct from ANY glob `cwd`; the string face was retired.
+ *
+ * A plain string list is still accepted — for a direct library caller whose
+ * patterns are, by that caller's own contract, relative to the `cwd` it globs
+ * from. That is the one frame a string can safely carry.
+ */
+const glob_1 = require("glob");
+function isPatternList(x) {
+    return Array.isArray(x);
+}
+/**
+ * `floor` (patterns relative to the glob's `cwd`) plus `extra`, in the form
+ * `globSync`'s `ignore` option accepts. Stays a plain list when both halves are
+ * lists, so a string-only caller sees exactly the glob behaviour it always had.
+ */
+function withIgnored(floor, extra) {
+    if (extra === undefined)
+        return [...floor];
+    if (isPatternList(extra))
+        return [...floor, ...extra];
+    const own = new glob_1.Ignore([...floor], {});
+    return {
+        ignored: (p) => own.ignored(p) || extra.ignored?.(p) === true,
+        childrenIgnored: (p) => own.childrenIgnored(p) || extra.childrenIgnored?.(p) === true,
+    };
+}
+//# sourceMappingURL=glob-ignore.js.map

package/dist/core/orphans.d.ts

@@ -11,6 +11,7 @@
  * references (markdown links and backtick paths). Works against source
  * README plus compiled CLAUDE.md — no spec loading required.
  */
+import { type GlobIgnore } from "./glob-ignore.js";
 import type { PluginLayout } from "./layout.js";
 export interface OrphanReport {
     /** Include globs that were scanned. */
@@ -35,12 +36,13 @@ export interface FindOrphansOptions {
     /** Glob patterns to exclude within the include scope (orphan CANDIDACY only). */
     readonly exclude?: readonly string[];
     /**
-     * The repo-wide `.vigilesrc.json#exclude` (the ExcludeSet string face,
-     * src/exclude.ts). Applied to BOTH walks — candidates AND the reference scan —
+     * The repo-wide `.vigilesrc.json#exclude` (`ExcludeSet.globIgnore`,
+     * src/exclude.ts — correct from any glob cwd; a plain list is relative to
+     * `basePath`). Applied to BOTH walks — candidates AND the reference scan —
      * so an excluded corpus can neither be an orphan nor keep one alive (#192).
      * The CLI always passes it; a direct library caller may omit it.
      */
-    readonly repoExclude?: readonly string[];
+    readonly repoExclude?: GlobIgnore;
     /**
      * Harnesses whose surface files (instruction file, `SKILL.md`, subagents,
      * commands) are load-bearing by location and thus never orphan CANDIDATES

package/dist/core/orphans.js

@@ -18,6 +18,7 @@ exports.formatOrphanReport = formatOrphanReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const glob_ignore_js_1 = require("./glob-ignore.js");
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
@@ -100,7 +101,7 @@ function isOrphanExempt(absPath) {
 function collectDocs(basePath, include, ignore, layouts) {
     const docs = new Set();
     for (const pattern of include) {
-        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
+        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore })) {
             if (isHarnessLoadedFile(p, layouts))
                 continue; // harness files are never orphans
             if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
@@ -160,13 +161,13 @@ function findOrphanDocs(options = {}) {
     // CANDIDATE nor a SOURCE of references (a link from inside it must not keep a
     // doc alive). The rule's own `exclude` only narrows candidacy: a doc kept out
     // of the orphan list can still reference others. Union, never override.
-    const repoExclude = options.repoExclude ?? [];
-    const ignore = [...DEFAULT_IGNORE, ...repoExclude, ...userExclude];
+    const repoExclude = options.repoExclude;
+    const ignore = (0, glob_ignore_js_1.withIgnored)([...DEFAULT_IGNORE, ...userExclude], repoExclude);
     const layouts = options.layouts ?? [];
     const allDocs = collectDocs(basePath, include, ignore, layouts);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
-        ignore: [...DEFAULT_IGNORE, ...repoExclude],
+        ignore: (0, glob_ignore_js_1.withIgnored)(DEFAULT_IGNORE, repoExclude),
     });
     const referencedBy = new Map();
     for (const mdPath of allMarkdown) {

package/dist/eval.d.ts

@@ -25,9 +25,21 @@ export interface EvalArm {
      * arm, so its skills/commands/agents activate the real way — the real model
      * can trigger a skill by its description (vs. `plugin`, which materializes a
      * file subset that does not register skills). Point at a COMPLETE plugin. Lets
-     * an arm be "skill installed" vs "off" to measure real activation.
+     * an arm be "skill installed" vs "off" to measure real activation. Provide this
+     * OR {@link skillsDir}, not both.
      */
     readonly pluginDir?: string;
+    /**
+     * A directory of LOOSE skills (`<skillsDir>/<name>/SKILL.md`, e.g. a repo's
+     * `.claude/skills`) to install for this arm. vigiles packages them into a
+     * throwaway `--plugin-dir` (manifest + `skills/<name>/`, each skill dir copied
+     * whole) for the run and removes it afterward — the one-liner for repo-local
+     * skills that aren't a published plugin. The skills install under the
+     * namespace `vigiles-loose-skills`, so a `skill()` check / `skillResolved`
+     * matches `vigiles-loose-skills:<name>` (the report's `namespace` says so).
+     * Provide this OR {@link pluginDir}, not both.
+     */
+    readonly skillsDir?: string;
     /**
      * Tools to intercept for this arm (the tool-call spy). Each
      * {@link ToolIntercept} is denied its real execution by an auto-wired PreToolUse
@@ -83,6 +95,15 @@ export interface EvalSpec<M extends Metrics> {
     readonly fixture?: Record<string, string>;
     /** The arms to compare, by name. */
     readonly arms: Record<string, EvalArm>;
+    /**
+     * Stub each arm's skill BODIES (frontmatter kept) before the run — for firing
+     * comparisons (does the skill get SELECTED?), where a selected skill should
+     * stop at selection instead of running its (often expensive) procedure. Every
+     * arm with a `pluginDir` / `skillsDir` is repackaged with bodies stripped; arms
+     * without one are untouched. Don't combine with quality metrics: the body is
+     * gone, so there is nothing to grade. See {@link stubSkillBody}.
+     */
+    readonly stubSkillBodies?: boolean;
     /** The task prompt given to the agent. */
     readonly task: string;
     /** Compute this run's metrics from its outcome. */
@@ -328,15 +349,24 @@ export interface MeasureSpec {
     readonly settings?: unknown;
     /** A real plugin/repo to load (materialized) — see `EvalArm.plugin`. */
     readonly plugin?: string;
-    /** A complete plugin dir to install natively (`--plugin-dir`) so skills activate. */
+    /**
+     * A complete plugin dir to install natively (`--plugin-dir`) so skills activate
+     * — see {@link EvalArm.pluginDir}. Provide this OR `skillsDir`, not both.
+     */
     readonly pluginDir?: string;
     /**
-     * Stub each skill BODY in `pluginDir` (frontmatter/trigger surface kept) before
-     * the run — for checks about whether a skill FIRES (`skill()`), not what it
-     * produces. A selected skill stops at selection instead of running its (often
-     * expensive) procedure, so a description/firing run costs a fraction of the
-     * tokens. Do NOT combine with `judged`/quality checks: the body is gone, so
-     * there's nothing to grade. Requires `pluginDir`. See {@link stubSkillBody}.
+     * A loose `<skillsDir>/<name>/SKILL.md` directory (e.g. a repo's `.claude/skills`)
+     * to install, auto-packaged into a throwaway plugin — see {@link EvalArm.skillsDir}.
+     * Installs under `vigiles-loose-skills`, so `skill("vigiles-loose-skills:<name>")`.
+     */
+    readonly skillsDir?: string;
+    /**
+     * Stub each skill BODY (frontmatter/trigger surface kept) before the run — for
+     * checks about whether a skill FIRES (`skill()`), not what it produces. A
+     * selected skill stops at selection instead of running its (often expensive)
+     * procedure, so a description/firing run costs a fraction of the tokens. Do NOT
+     * combine with `judged`/quality checks: the body is gone, so there's nothing to
+     * grade. Requires `pluginDir` or `skillsDir`. See {@link stubSkillBody}.
      */
     readonly stubSkillBodies?: boolean;
     /** Tools to intercept (the tool-call spy) — see {@link EvalArm.interceptTools}. */
@@ -385,6 +415,15 @@ export interface CheckReport {
     readonly perCheck: readonly CheckRate[];
     /** Cost / latency / token totals for the run (the same source as `runEval`). */
     readonly usage: ArmUsage;
+    /**
+     * The plugin namespace the skills actually installed under — the `<plugin>`
+     * half of the `<plugin>:<skill>` id a `skill()` check matches. Undefined when
+     * the run installed nothing (no `pluginDir` / `skillsDir`). Reported because
+     * with `skillsDir` the name is chosen by the packager, not the caller, so the
+     * most common cause of a 0% `skill()` rate was a value the caller never saw.
+     * Mirrors {@link TriggerRateReport.namespace}.
+     */
+    readonly namespace?: string;
 }
 /**
  * Score a check vocabulary across trials — the scored counterpart to
@@ -407,8 +446,8 @@ export interface ArmsMeasureSpec {
      * Stub each arm's skill BODIES (frontmatter kept) before the run — the A/B
      * counterpart to {@link MeasureSpec.stubSkillBodies}. For firing comparisons
      * (does description variant A fire more than B?), every arm that sets
-     * `pluginDir` is repackaged with bodies stripped so each run stops at
-     * selection — a fraction of the tokens. Arms without a `pluginDir` are left
+     * `pluginDir` / `skillsDir` is repackaged with bodies stripped so each run
+     * stops at selection — a fraction of the tokens. Arms without one are left
      * untouched. Don't combine with `judged`/quality checks. See {@link stubSkillBody}.
      */
     readonly stubSkillBodies?: boolean;
@@ -593,7 +632,7 @@ export declare function seedEphemeralHome(throwawayHome: string, realHome: strin
 export declare function isRateLimited(out: RunOut): boolean;
 /** Map `worker` over `items` with at most `concurrency` in flight, order preserved. */
 export declare function runPool<T, R>(items: readonly T[], concurrency: number, worker: (item: T) => Promise<R>): Promise<R[]>;
-export declare function runEvalWith<M extends Metrics>(spec: EvalSpec<M>, runner: AgentRunner): Promise<EvalReport>;
+export declare function runEvalWith<M extends Metrics>(input: EvalSpec<M>, runner: AgentRunner): Promise<EvalReport>;
 /** Format an eval report as a compact table for the console (mean ± se, pass^k). */
 export declare function formatEvalReport(report: EvalReport): string;
 /**