vigiles 18.0.0 → 18.1.1

package/dist/adapters/claude-code/agent-result.js

@@ -39,8 +39,17 @@ function fieldMatches(value, type) {
             return typeof value === "boolean";
         case "string[]":
             return Array.isArray(value) && value.every((v) => typeof v === "string");
+        default:
+            // An enum, declared as a readonly tuple of the permitted literals.
+            return typeof value === "string" && type.includes(value);
     }
 }
+/** How a field type reads in a message to a human: `string`, or `"CUT" | "MERGE"`. */
+function typeName(type) {
+    return typeof type === "string"
+        ? type
+        : type.map((v) => JSON.stringify(v)).join(" | ");
+}
 /**
  * Validate a parsed object against a contract track; null when it conforms.
  *
@@ -54,7 +63,9 @@ function shapeError(obj, shape) {
         if (!(field in obj))
             return `missing field "${field}"`;
         if (!fieldMatches(obj[field], type)) {
-            return `field "${field}" should be ${type}`;
+            // `typeName`, not `type`: an enum interpolated raw renders as `CUT,MERGE,KEEP`,
+            // which reads like a value rather than a choice among values.
+            return `field "${field}" should be ${typeName(type)}`;
         }
     }
     return null;

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -93,6 +93,11 @@ export declare function interpreterArgs(file: string, caps: NodeCaps, entry?: st
 export declare function discoverScripts(patterns: readonly string[], defaultGlob: string, cwd: string): string[];
 /** Extra wiring for {@link runScripts}. */
 export interface RunScriptsOptions {
+    /**
+     * How many scripts may run at once. Omitted → decided from `entry`: `test`
+     * fans out across the cores, `eval` stays at 1. See {@link runScripts}.
+     */
+    readonly concurrency?: number;
     /**
      * A program to run INSTEAD of each script, with the script's path as its one
      * argument. `vigiles eval` passes `dist/eval-entry.js`; `vigiles test` passes
@@ -116,7 +121,7 @@ export interface RunScriptsOptions {
  * record them (`.vigiles/coverage.json`) and coverage can answer "tested?" from
  * execution rather than from a matching file name.
  */
-export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv, opts?: RunScriptsOptions): ScriptRunResult[];
+export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv, opts?: RunScriptsOptions): Promise<ScriptRunResult[]>;
 /**
  * Whether any script FAILED. Neither a skip nor a vacuous run counts: the first
  * declined to run, the second ran and verified nothing, and neither is evidence

package/dist/adapters/claude-code/run-scripts.js

@@ -22,9 +22,10 @@ exports.formatScriptSummary = formatScriptSummary;
  * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
  */
 const node_child_process_1 = require("node:child_process");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
+const node_os_2 = require("node:os");
 const glob_1 = require("glob");
 const check_count_js_1 = require("../../check-count.js");
 /**
@@ -178,42 +179,95 @@ function readCheckReport(path) {
  * record them (`.vigiles/coverage.json`) and coverage can answer "tested?" from
  * execution rather than from a matching file name.
  */
-function runScripts(files, cwd, env = {}, opts = {}) {
+async function runScripts(files, cwd, env = {}, opts = {}) {
     const caps = (0, ts_runner_caps_js_2.detectNodeCaps)(cwd);
-    const results = [];
-    const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-checks-"));
-    try {
-        files.forEach((file, i) => {
-            let argv;
-            try {
-                argv = interpreterArgs(file, caps, opts.entry);
-            }
-            catch (e) {
-                console.error(`✗ ${file}: ${e.message}`);
-                results.push({ file, code: 1, status: "fail" });
-                return;
-            }
-            const countFile = (0, node_path_1.join)(countDir, `${String(i)}.count`);
-            const res = (0, node_child_process_1.spawnSync)("node", argv, {
-                cwd,
-                stdio: "inherit",
-                env: { ...process.env, ...env, [check_count_js_1.CHECK_COUNT_ENV]: countFile },
-            });
-            const code = res.status ?? 1;
+    const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_2.tmpdir)(), "vigiles-checks-"));
+    // 🔴 THE DEFAULT IS DECIDED BY `entry`, NOT BY A FLAG, because the two commands
+    // that share this runner have OPPOSITE right answers and the caller already
+    // distinguishes them:
+    //
+    //   `test` passes no entry — every script is a `*.harness.*` file, which is free
+    //   and deterministic BY CONSTRUCTION (the harness tier drives the agent CLI
+    //   against a mock model with no API key, and anything that spends money lives
+    //   behind `vigiles/eval` with a `paid_` prefix). Nothing here can bill, so the
+    //   only reason to serialize was that we always had.
+    //
+    //   `eval` passes an entry — every script spends real model quota. Running those
+    //   N-at-a-time multiplies spend and collides with rate limits, so it stays at 1.
+    //
+    // Measured motivation: 48 harness files in one consumer repo took 1m48s in CI as
+    // a strict queue, on a runner with cores sitting idle.
+    const parallel = Math.max(1, opts.concurrency ?? (opts.entry ? 1 : Math.min(8, (0, node_os_1.availableParallelism)())));
+    // Output is BUFFERED per child and printed when that child exits, rather than
+    // inherited. This is the real cost of concurrency and the reason it was not
+    // free: with `stdio: "inherit"` two children write to the same terminal at once
+    // and 48 reports shred into each other. Buffering keeps each report whole and
+    // attributable; what it gives up is live streaming, which only matters when one
+    // script is slow AND alone — i.e. exactly the `eval` case, where parallel is 1
+    // and the buffer is flushed as soon as the single child ends anyway.
+    const runOne = (file, i) => new Promise((resolveRun) => {
+        let argv;
+        try {
+            argv = interpreterArgs(file, caps, opts.entry);
+        }
+        catch (e) {
+            console.error(`✗ ${file}: ${e.message}`);
+            resolveRun({ file, code: 1, status: "fail" });
+            return;
+        }
+        const countFile = (0, node_path_1.join)(countDir, `${String(i)}.count`);
+        const child = (0, node_child_process_1.spawn)("node", argv, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, ...env, [check_count_js_1.CHECK_COUNT_ENV]: countFile },
+        });
+        const chunks = [];
+        child.stdout.on("data", (c) => chunks.push(c));
+        child.stderr.on("data", (c) => chunks.push(c));
+        const finish = (code) => {
+            process.stdout.write(Buffer.concat(chunks));
             const report = readCheckReport(countFile);
-            results.push({
+            resolveRun({
                 file,
                 code,
                 status: statusFor(code, report?.checks),
                 checks: report?.checks,
                 ...(report ? { surfaces: report.surfaces } : {}),
             });
+        };
+        // `error` fires when the process could not be spawned at all; without this
+        // the promise would never settle and the whole run would hang silently —
+        // which is worse than any failure it could report.
+        child.on("error", (e) => {
+            chunks.push(Buffer.from(`✗ ${file}: ${e.message}\n`));
+            finish(1);
+        });
+        child.on("close", (code) => {
+            finish(code ?? 1);
         });
+    });
+    try {
+        // Results are stored BY INDEX so the reported order is the discovery order,
+        // whatever order the children happen to finish in. A run whose output reorders
+        // itself between invocations reads as flaky even when every result is stable.
+        const results = new Array(files.length);
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= files.length)
+                    return;
+                results[i] = await runOne(files[i], i);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(parallel, files.length) }, () => {
+            return worker();
+        }));
+        return results;
     }
     finally {
         (0, node_fs_1.rmSync)(countDir, { recursive: true, force: true });
     }
-    return results;
 }
 /**
  * Whether any script FAILED. Neither a skip nor a vacuous run counts: the first

package/dist/cli.js

@@ -1141,7 +1141,23 @@ async function runLint(restArgs, flags, config) {
     // `<!-- vigiles:ignore-file -->` (whole file). Same engine as spec.ts.
     if (!silent)
         console.log("\nMarkdown code block refs:\n");
-    const docRefReport = (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd() });
+    // 🔴 `config.exclude` REACHES THIS PASS. It did not, and that single omission is
+    // why `lint` could not exit 0 on a repository that vendors other people's
+    // markdown: this walker globs `**/*.md` from the repo root, so a third-party
+    // `CLAUDE.md` captured verbatim as benchmark data was held to the same ref
+    // validation as the repo's own docs — and the one config field documented to
+    // stop exactly that ("vendored or benchmark fixtures the repo's own lint
+    // shouldn't police") was never handed over.
+    //
+    // Measured on a consumer repo 2026-08-19: 9 broken refs, 8 of them inside a
+    // directory the user had explicitly listed in `exclude`, all 9 still reported.
+    // With no way to reach 0 the step was made `continue-on-error: true`, and a lint
+    // whose exit code is discarded gates nothing — after which hand-written CI steps
+    // grew to do the gating instead. One unpassed argument, that whole chain.
+    const docRefReport = (0, doc_refs_js_1.findDocRefs)({
+        basePath: process.cwd(),
+        ignore: config?.exclude,
+    });
     if (!silent) {
         for (const line of (0, doc_refs_js_1.formatDocRefReport)(docRefReport).split("\n")) {
             console.log(`  ${line}`);
@@ -4366,7 +4382,7 @@ async function handleRunScripts(kind, args, restArgs) {
     // An eval file DESCRIBES its eval; `dist/eval-entry.js` is what imports the
     // description and runs what it declares. A harness script is still its own
     // program (it is free, so "import spends money" never applied to it).
-    const results = (0, run_scripts_js_1.runScripts)(files, cwd, env, {
+    const results = await (0, run_scripts_js_1.runScripts)(files, cwd, env, {
         ...(kind === "eval" ? { entry: (0, node_path_1.resolve)(__dirname, "eval-entry.js") } : {}),
     });
     // Write down WHAT the run exercised, so `lint`/`audit` can answer "tested?"

package/dist/core/compile.js

@@ -5,6 +5,9 @@
  * Reads .spec.ts files, validates references, and produces
  * markdown instruction files with integrity hashes.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeHash = computeHash;
 exports.addHash = addHash;
@@ -25,6 +28,7 @@ exports.checkFileHash = checkFileHash;
 exports.adoptDiff = adoptDiff;
 const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const node_path_1 = require("node:path");
 const hash_js_1 = require("./hash.js");
 const integrity_js_1 = require("./integrity.js");
@@ -626,12 +630,52 @@ function collectSkillRefs(spec) {
  * argument-hint, tools). Default is `"claude-code"` so callers that pass no
  * dialect get byte-identical output to before.
  */
+/**
+ * A frontmatter scalar, quoted only when leaving it bare would not survive YAML.
+ *
+ * 🔴 WHY THIS EXISTS. `description: ${spec.description}` interpolated the value
+ * raw, so a description containing a colon-space — `"…измеряет, где замер врёт:
+ * неаналоги в выборке"` — emitted frontmatter that is not valid YAML. Measured
+ * 2026-08-19 on two real skills: right after `vigiles compile`, `skillContract()`
+ * reported `malformed: true` and `declared: []`. The file LOOKS like it declares
+ * `allowed-tools`; a strict parser reads nothing, so the skill silently inherits
+ * every tool the session grants.
+ *
+ * That is the exact defect `frontmatter-valid` exists to report — i.e. the
+ * blessed path produced the thing the product hunts for. Worse, it PUNISHED the
+ * fix: a human who quoted the value by hand got a hash mismatch on the next lint
+ * ("manually edited after compilation"), and recompiling silently reverted them.
+ *
+ * The test is a ROUND TRIP rather than a list of dangerous characters: emit it,
+ * read it back with the same loader the linter uses, and quote only if what comes
+ * back is not the string that went in. Consequences of that choice:
+ *   - a value that was already safe is emitted byte-identically, so no existing
+ *     compiled file churns and no integrity hash moves;
+ *   - the set of "dangerous" inputs never has to be enumerated or maintained —
+ *     YAML itself decides, so `#`, `[`, `&`, `*`, leading/trailing space, `yes`,
+ *     `null` and everything else are covered without being listed.
+ */
+function yamlScalar(value) {
+    try {
+        const parsed = js_yaml_1.default.load(`v: ${value}`);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            parsed.v === value) {
+            return value;
+        }
+    }
+    catch {
+        // Did not parse at all — definitively needs quoting.
+    }
+    // A JSON string IS a YAML double-quoted scalar, escaping included.
+    return JSON.stringify(value);
+}
 function renderSkillFrontmatter(spec, profile = "claude-code") {
     const fm = [
         "---",
         "",
-        `name: ${spec.name}`,
-        `description: ${spec.description}`,
+        `name: ${yamlScalar(spec.name)}`,
+        `description: ${yamlScalar(spec.description)}`,
     ];
     // The CC-only keys below are inert in a minimal (Codex/OpenCode) SKILL.md, so
     // they're omitted entirely under that profile.
@@ -645,7 +689,7 @@ function renderSkillFrontmatter(spec, profile = "claude-code") {
             ? renderArgumentHint(spec.inputs)
             : spec.argumentHint;
         if (argHint)
-            fm.push(`argument-hint: ${argHint}`);
+            fm.push(`argument-hint: ${yamlScalar(argHint)}`);
         if (spec.tools && spec.tools.length > 0) {
             // A Claude Code SKILL declares its tool contract under `allowed-tools`
             // (NOT `tools:` — that's the SUBAGENT key), as a real YAML sequence. Flow
@@ -839,11 +883,14 @@ function validateAgentTools(tools, dialect) {
 }
 /** Build the subagent YAML frontmatter (name / description / model / tools). */
 function renderAgentFrontmatter(spec) {
+    // Same round-trip quoting as the skill renderer — a subagent description is
+    // written just as freely and breaks its frontmatter the same way. See
+    // {@link yamlScalar}.
     const fm = [
         "---",
         "",
-        `name: ${spec.name}`,
-        `description: ${spec.description}`,
+        `name: ${yamlScalar(spec.name)}`,
+        `description: ${yamlScalar(spec.description)}`,
     ];
     if (spec.model !== undefined)
         fm.push(`model: ${spec.model}`);
@@ -899,7 +946,9 @@ function renderAgentSections(sections, basePath) {
 /** Render a result-contract track shape as a compact `{ "f": type, … }` line. */
 function renderShape(shape) {
     const fields = Object.entries(shape)
-        .map(([k, t]) => `"${k}": ${t}`)
+        // An enum renders as the choice itself — `"verdict": "CUT" | "MERGE" | "KEEP"` — so
+        // the fenced rail shows a worker the same permitted values the tool schema shows.
+        .map(([k, t]) => `"${k}": ${typeof t === "string" ? t : t.map((v) => JSON.stringify(v)).join(" | ")}`)
         .join(", ");
     return fields ? `{ ${fields} }` : "{}";
 }

package/dist/core/description-overlap.d.ts

@@ -2,9 +2,21 @@
 export interface DescribedSurface {
     readonly name: string;
     readonly description: string;
+    /**
+     * Repo-relative path to report the surface at. Optional for callers that have
+     * no path, but REQUIRED in practice to keep the message actionable: since the
+     * loader started reading BOTH discovery levels, a repo that keeps a copy of a
+     * skill in `skills/` and `.claude/skills/` yields two surfaces with the SAME
+     * name, and "skills \"dup\" and \"dup\" have near-identical descriptions" names
+     * neither file. Measured on `nyldn/claude-octopus`: 50 such pairs. The path is
+     * the only thing that distinguishes them.
+     */
+    readonly where?: string;
 }
 export interface DescriptionOverlap {
+    /** Display label for the first skill — `"name"`, or `"name" (path)`. */
     readonly a: string;
+    /** Display label for the second skill — `"name"`, or `"name" (path)`. */
     readonly b: string;
     /** 0–1, higher = more alike (1 − NCD), rounded to 2 dp. */
     readonly similarity: number;
@@ -17,11 +29,5 @@ export interface DescriptionOverlap {
  * the calibrated value.
  */
 export declare const OVERLAP_NCD_CUTOFF = 0.2;
-/**
- * Find near-duplicate description pairs among `surfaces`. Returns one
- * {@link DescriptionOverlap} per pair whose NCD is below `cutoff`, most-similar
- * first. Pure; pass only the surfaces that actually compete for auto-selection
- * (model-invocable, described) so a user-invoked pair isn't a false alarm.
- */
 export declare function findDescriptionOverlaps(surfaces: readonly DescribedSurface[], cutoff?: number): DescriptionOverlap[];
 //# sourceMappingURL=description-overlap.d.ts.map

package/dist/core/description-overlap.js

@@ -31,6 +31,10 @@ exports.OVERLAP_NCD_CUTOFF = 0.2;
  * first. Pure; pass only the surfaces that actually compete for auto-selection
  * (model-invocable, described) so a user-invoked pair isn't a false alarm.
  */
+/** `"name"`, or `"name" (path)` when the caller supplied one. */
+function label(s) {
+    return s.where === undefined ? `"${s.name}"` : `"${s.name}" (${s.where})`;
+}
 function findDescriptionOverlaps(surfaces, cutoff = exports.OVERLAP_NCD_CUTOFF) {
     const overlaps = [];
     for (let i = 0; i < surfaces.length; i++) {
@@ -38,13 +42,13 @@ function findDescriptionOverlaps(surfaces, cutoff = exports.OVERLAP_NCD_CUTOFF)
             const d = (0, ncd_js_1.ncd)(surfaces[i].description, surfaces[j].description);
             if (d >= cutoff)
                 continue;
-            const a = surfaces[i].name;
-            const b = surfaces[j].name;
+            const a = label(surfaces[i]);
+            const b = label(surfaces[j]);
             overlaps.push({
                 a,
                 b,
                 similarity: Math.round((1 - d) * 100) / 100,
-                message: `skills "${a}" and "${b}" have near-identical descriptions (${String(Math.round((1 - d) * 100))}% alike) — the model can't reliably tell them apart, so the wrong one may fire. Differentiate their descriptions.`,
+                message: `skills ${a} and ${b} have near-identical descriptions (${String(Math.round((1 - d) * 100))}% alike) — the model can't reliably tell them apart, so the wrong one may fire. Differentiate their descriptions.`,
             });
         }
     }

package/dist/core/doc-refs.js

@@ -18,11 +18,15 @@
  * in markdown is explicitly out of scope — use eslint-plugin-markdown or
  * twoslash for that.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractDocRefs = extractDocRefs;
 exports.findDocRefs = findDocRefs;
 exports.formatDocRefReport = formatDocRefReport;
 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 linters_js_1 = require("./linters.js");
@@ -44,7 +48,7 @@ const TS_LANGS = new Set(["ts", "typescript", "js", "javascript"]);
 // doesn't accidentally disable validation.
 const IGNORE_BLOCK_RE = /^\s{0,3}<!--\s*vigiles:ignore\s*-->\s*$/;
 const IGNORE_FILE_RE = /^\s{0,3}<!--\s*vigiles:ignore-file\s*-->\s*$/m;
-const CALL_RE = /\b(enforce|file|cmd|ref)\(\s*["']([^"'\n]+)["']/g;
+const KINDS = new Set(["enforce", "file", "cmd", "ref"]);
 const PLACEHOLDER_RE = /[<>]/;
 /**
  * Error-message patterns that mean "tool not available in this env" rather
@@ -57,6 +61,66 @@ const UNVERIFIABLE_PATTERNS = [
     /not found on PATH/i,
     /No Cedar policies found/i,
 ];
+/**
+ * The builder calls in one fenced block, found by PARSING it rather than by
+ * matching text.
+ *
+ * 🔴 WHY THIS IS NOT A REGEX ANY MORE. The previous form was
+ * `/\b(enforce|file|cmd|ref)\(\s*["']([^"'\n]+)["']/g`, and four of these six
+ * inputs were classified wrongly (measured 2026-08-19):
+ *
+ *   ctx.file("OUT")          → matched, though it is a method on some other
+ *                              object. A live instance of this sat in a real
+ *                              repository's notes and was reported as a broken
+ *                              ref for weeks.
+ *   obj.cmd("npm test")      → matched, same reason
+ *   // cmd("npm test")       → matched, though it is a comment
+ *   const s = 'cmd("x")'     → matched, though it is a string
+ *   myFile("x")              → correctly skipped
+ *   cmd("npm test")          → correctly matched
+ *
+ * `\b` sits happily after a `.`, so every member call read as a builder call,
+ * and a regex has no notion of comments or string literals at all. Parsing makes
+ * all four INEXPRESSIBLE rather than individually patched: the AST only offers a
+ * call whose callee is a bare identifier, and comments and string bodies are not
+ * call expressions in the first place.
+ *
+ * `typescript` is already a runtime dependency of this package, so this costs no
+ * new install — the parser was in the box the whole time.
+ */
+function callsIn(blockLines, file) {
+    if (blockLines.length === 0)
+        return [];
+    const src = blockLines.map((b) => b.text).join("\n");
+    const firstLine = blockLines[0].lineNo;
+    const sf = typescript_1.default.createSourceFile("block.ts", src, typescript_1.default.ScriptTarget.Latest, 
+    /* setParentNodes */ true, typescript_1.default.ScriptKind.TS);
+    const out = [];
+    const visit = (node) => {
+        if (typescript_1.default.isCallExpression(node) && typescript_1.default.isIdentifier(node.expression)) {
+            const kind = node.expression.text;
+            if (KINDS.has(kind)) {
+                const arg = node.arguments[0];
+                // Only a plain string literal is a ref we can resolve. A template with
+                // substitutions, a variable, or a computed value is not something this
+                // pass can check, and guessing at it is how false reports start.
+                if (arg &&
+                    (typescript_1.default.isStringLiteral(arg) || typescript_1.default.isNoSubstitutionTemplateLiteral(arg))) {
+                    const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                    out.push({
+                        file,
+                        line: firstLine + line,
+                        kind: kind,
+                        value: arg.text,
+                    });
+                }
+            }
+        }
+        typescript_1.default.forEachChild(node, visit);
+    };
+    visit(sf);
+    return out;
+}
 /** @internal */ function extractDocRefs(content, file) {
     const lines = content.split("\n");
     const refs = [];
@@ -88,16 +152,7 @@ const UNVERIFIABLE_PATTERNS = [
                         blocksIgnored++;
                     }
                     else {
-                        for (const { lineNo, text } of blockLines) {
-                            for (const m of text.matchAll(CALL_RE)) {
-                                refs.push({
-                                    file,
-                                    line: lineNo,
-                                    kind: m[1],
-                                    value: m[2],
-                                });
-                            }
-                        }
+                        refs.push(...callsIn(blockLines, file));
                     }
                 }
                 fenceChar = null;

package/dist/core/spec.d.ts

@@ -695,8 +695,22 @@ export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
  * erased `Shape`, and the value is still a plain `AgentSpec` — backwards-compatible.
  */
 export declare function agent<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape>(spec: AgentSpecInput<P, V, Ok, Err>): TypedAgentSpec<Ok, Err>;
-/** The field types a result contract can declare (kept tiny + dependency-free). */
-export type OutputFieldType = "string" | "number" | "boolean" | "string[]";
+/**
+ * The field types a result contract can declare (kept tiny + dependency-free).
+ *
+ * The literal-array member is an ENUM: `["CUT", "MERGE", "KEEP"] as const` declares a
+ * field whose value must be one of those strings. It is the ONLY extension to this union,
+ * and it was added because a measured failure had no other cure: across 14 real payloads
+ * a `verdict: "string"` field held 3 mutually incomparable invented categories over 3
+ * runs, and vocabulary compliance was 3/19 — 16%. `string` cannot express "one of these",
+ * so nothing downstream could notice.
+ *
+ * Nothing RELATIONAL follows it — no `object[]`, no tuples, no per-element enums.
+ * Declaring one throws rather than rendering an unsatisfiable schema, because the body of
+ * a result is prose by decision: on those same 14 payloads, 23 scalar values carried
+ * every assertion anyone made while 80,981 characters of prose carried none.
+ */
+export type OutputFieldType = "string" | "number" | "boolean" | "string[]" | readonly [string, ...string[]];
 /** A field SHAPE — a record of field-name → field-type, kept in the TYPE so a
  *  typed pipeline can cross-reference one agent's `ok` against the next agent's
  *  `needs`. The erased runtime form is `Record<string, OutputFieldType>`. */

package/dist/core/surface-scopes.d.ts

@@ -0,0 +1,110 @@
+/**
+ * WHERE a repo's model surfaces (skills/agents/commands) live — and the key each
+ * one is materialized under.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE LOADER USED TO CHOOSE. It read the repo-root
+ * `skills/` **or** the project-level `.claude/skills/` — never both — and
+ * materialized whichever it picked under the SAME canonical
+ * `<materializeRoot>/<surface>/…` key. Two real files, one key: the loser was
+ * never read, and the winner's content sat under the loser's name. Measured
+ * 2026-08-18 on `nyldn/claude-octopus` (pinned corpus): **50 skill names exist in
+ * both `skills/` and `.claude/skills/`, and all 50 pairs differ** — the `.claude/`
+ * copies carry multi-line unquoted `description:` blocks that a strict YAML
+ * loader rejects. vigiles reported those fifty skills as clean without ever
+ * having opened the files it named.
+ *
+ * The vendor settles it — Claude Code loads BOTH, in two namespaces:
+ *
+ * > Plugin skills use a `plugin-name:skill-name` namespace, so they can't
+ * > conflict with other levels.
+ * > For example, `my-plugin/skills/deploy/SKILL.md` becomes `/my-plugin:deploy`
+ * > and loads alongside a `deploy` skill in your project's `.claude/skills/`.
+ * > — https://code.claude.com/docs/en/skills § "Where skills live"
+ *
+ * So "pick one" was never a tie-break to get right; it was a question that has no
+ * answer, asked because the key shape forced one. The fix removes the question:
+ * every scope present is read, and **a scope's key prefix is derived from the
+ * scope, not from a winner**, so two files can no longer claim one key.
+ *
+ * Node-free and IO-free on purpose: the disk loader (`src/plugin-loader.ts`) and
+ * the browser file-map twin (`src/scan-files.ts`) each probe their own storage
+ * and call THIS for the decision, so the pair that this repo has repeatedly been
+ * bitten by fixing on one side only cannot disagree about scoping.
+ */
+import type { PluginLayout } from "./layout.js";
+/**
+ * One discovery level, and the prefix its files are materialized under.
+ *
+ * `base` is the repo-relative dir the surfaces really live under (`""` = the repo
+ * root, the published-plugin shape; `.claude` = the plain-user project shape).
+ * `materializeUnder` is the prefix prepended to `<surface>/<rel>` to form the
+ * `LoadedPlugin.files` key.
+ */
+export interface SurfaceScope {
+    /** Repo-relative dir holding `<surface>/…`; `""` for the repo root. */
+    readonly base: string;
+    /** Key prefix for this scope's files; `""` for none. */
+    readonly materializeUnder: string;
+    /** Human label for warnings — `plugin` (root) or `project` (`.claude/`). */
+    readonly label: string;
+}
+/** Which shape the audited target is, and every scope to read from it. */
+export type SurfaceSource = {
+    readonly kind: "single-skill";
+    readonly skillName: string;
+} | {
+    readonly kind: "scopes";
+    readonly scopes: readonly SurfaceScope[];
+};
+/** What the caller must probe on its own storage for {@link surfaceSource}. */
+export interface SurfaceProbe {
+    /** A `<root>/SKILL.md` exists — the target IS one skill dir. */
+    readonly hasRootSkillFile: boolean;
+    /** Name to give that single skill (the target dir's basename). */
+    readonly skillName: string;
+    /** Some `<root>/<surface>/` holds a loadable file. */
+    readonly rootHasLoadable: boolean;
+    /** A plugin manifest or the hooks convention path exists. */
+    readonly isPluginShaped: boolean;
+    /** Some `<root>/<userSurfaceRoot>/<surface>/` holds a loadable file. */
+    readonly userHasLoadable: boolean;
+}
+/**
+ * Classify the target and list every scope to read, HIGHEST-PRECEDENCE FIRST.
+ *
+ * Precedence decides only one thing: which scope keeps the canonical
+ * `<materializeRoot>/…` key. The project scope takes it, because that key IS
+ * where a project skill lives — `.claude/skills/deploy/SKILL.md` is loaded from
+ * exactly that path and answers to `/deploy`. A plugin scope keeps its own real
+ * location (`skills/deploy/SKILL.md`), which is likewise where the harness reads
+ * it from, under `/plugin:deploy`. Nothing is relocated on top of something else.
+ *
+ * 🔴 THE COLLISION IS STRUCTURAL, NOT CHECKED. Only the FIRST scope is relocated;
+ * every later one keeps `base` as its prefix. Since the first scope is the only
+ * one that can produce a `<materializeRoot>/…` key, and every other prefix is a
+ * distinct real directory, two scopes cannot mint the same key — there is no
+ * ordering, no "if already taken", and no last-write-wins to get wrong.
+ * {@link assertDistinctScopeKeys} is the LOUD backstop for a future
+ * `PluginLayout` that breaks the premise (e.g. one naming `.claude` as BOTH its
+ * `materializeRoot` and a second scope's base).
+ */
+export declare function surfaceSource(layout: PluginLayout, probe: SurfaceProbe): SurfaceSource;
+/** The `LoadedPlugin.files` key for one file under one scope. */
+export declare function scopeKey(scope: SurfaceScope, surface: string, rel: string): string;
+/**
+ * Throw when two scopes would mint the same key prefix. Unreachable for every
+ * shipped layout (see {@link surfaceSource}) — it exists so a NEW layout that
+ * breaks the premise fails loudly at load, rather than silently dropping a
+ * surface file the way the shadowing bug did for a year.
+ */
+export declare function assertDistinctScopeKeys(scopes: readonly SurfaceScope[], layoutName: string): void;
+/**
+ * The warning to emit when more than one scope is present. Both scopes load in a
+ * real session under DIFFERENT names, but the deterministic sandbox is a project
+ * dir — it registers the project scope only, so a plugin-scope skill sitting at
+ * `skills/…` in the fixture never activates there (the footgun
+ * `unregisteredSkillFiles` already warns about for inline arm files). Say so,
+ * rather than quietly relocating one on top of the other.
+ */
+export declare function multiScopeWarning(scopes: readonly SurfaceScope[], counts: Record<string, number>): string | undefined;
+//# sourceMappingURL=surface-scopes.d.ts.map