vigiles 5.1.0 → 6.0.0

package/dist/core/spec.js

@@ -17,7 +17,10 @@ exports.file = file;
 exports.cmd = cmd;
 exports.symbol = symbol;
 exports.ref = ref;
+exports.dir = dir;
+exports.glob = glob;
 exports.instructions = instructions;
+exports.effect = effect;
 exports.claude = claude;
 exports.project = project;
 exports.input = input;
@@ -27,6 +30,11 @@ exports.agent = agent;
 exports.result = result;
 exports.delegate = delegate;
 exports.railway = railway;
+exports.needs = needs;
+exports.pipeStep = pipeStep;
+exports.start = start;
+exports.andThen = andThen;
+exports.pipe = pipe;
 exports.defineConfig = defineConfig;
 // ---------------------------------------------------------------------------
 // Builder functions
@@ -105,6 +113,24 @@ function symbol(file, name) {
 function ref(path) {
     return { _ref: "skill", path: path };
 }
+/**
+ * Reference a directory — verified at compile time to exist AND be a directory
+ * (not a file). The "architecture floats free" fix: a spec that names `src/core/`
+ * proves the directory is really there, where a plain string in prose rots
+ * silently. Compiles to the inline form `` `path` ``.
+ */
+function dir(path) {
+    return { _ref: "dir", path: path };
+}
+/**
+ * Reference a glob pattern — verified at compile time to match at least one path,
+ * so `glob("src/*.test.ts")` proves tests actually exist where the instructions
+ * claim (the pattern supports the usual `*` / `**` syntax). Compiles to the
+ * inline form `` `pattern` ``.
+ */
+function glob(pattern) {
+    return { _ref: "glob", pattern: pattern };
+}
 /**
  * Tagged template literal for skill instructions with typed references.
  *
@@ -124,6 +150,33 @@ function instructions(strings, ...values) {
     }
     return result;
 }
+/**
+ * Tagged template literal marking a side-effect boundary — usable as an
+ * interpolated fragment inside a body / `instructions\`\``:
+ *
+ *   instructions`
+ *     ## Apply
+ *     ${effect`
+ *       Side effects are allowed ONLY here:
+ *       - write ${file("CHANGELOG.md")}
+ *       - ${cmd("npm publish")}
+ *     `}
+ *   `
+ *
+ * Returns an `EffectRegion` fragment; `compile` wraps its rendered body in
+ * `<!-- vigiles:effect -->` markers. Independent of the `doc()` authoring
+ * surface — it does not block on it.
+ */
+function effect(strings, ...values) {
+    const body = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i])
+            body.push(strings[i]);
+        if (i < values.length)
+            body.push(values[i]);
+    }
+    return { _ref: "effect", body };
+}
 /**
  * Define a CLAUDE.md specification.
  *
@@ -154,6 +207,11 @@ function step(instr, opts = {}) {
  *
  *   // skills/my-skill/SKILL.md.spec.ts
  *   export default skill({ name: "my-skill", description: "...", body: "..." });
+ *
+ * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
+ * constraint), exactly like `agent()`: a vocabulary-bound `skill` (e.g.
+ * `vigiles/claude-code`) makes `purity: "pure"` + a side-effecting tool a `tsc`
+ * error; the bare core `skill()` accepts any tools, as before.
  */
 function skill(spec) {
     return { _specType: "skill", ...spec };
@@ -172,6 +230,17 @@ function skill(spec) {
  *       "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."),
  *     },
  *   });
+ *
+ * Generic over a tool `Vocabulary` (default `OpenToolVocabulary` — no
+ * constraint). A harness adapter re-exports a vocabulary-bound `agent` (e.g.
+ * `vigiles/claude-code`) so `purity: "pure"` + a side-effecting tool is a `tsc`
+ * error at edit time; the bare core `agent()` accepts any tools, as before.
+ *
+ * Also generic over the result's `Ok`/`Err` shapes, inferred from `output:
+ * result(...)`. The returned value is a `TypedAgentSpec<Ok, Err>` — an
+ * `AgentSpec` that carries those shapes at the type level, so a typed `pipe`
+ * can cross-reference the handoff. With no `output` the shapes default to the
+ * erased `Shape`, and the value is still a plain `AgentSpec` — backwards-compatible.
  */
 function agent(spec) {
     return { _specType: "agent", ...spec };
@@ -186,15 +255,35 @@ function agent(spec) {
  *
  * (Distinct from a skill's `result:` postcondition gate — this types a
  * subagent's *return value*, the success/error tracks of the railway.)
+ *
+ * The literal field shapes are PRESERVED in the return type (`const` inference),
+ * not erased to `Record<string, OutputFieldType>` — this is what lets `pipe`
+ * cross-reference one agent's `ok` against the next agent's needs at `tsc` time.
+ * The return is still an `OutputContract`, so every existing consumer (the
+ * `output:` field, `renderOutputContract`, `parseAgentResult`) is unchanged.
  */
 function result(ok, err) {
     return { _ref: "output", ok, err };
 }
-/** Build a railway step that dispatches `agent` (optionally with a task hint). */
-function delegate(agent, task) {
-    return task === undefined
+/**
+ * Build a railway step that dispatches `agent`.
+ *
+ *   delegate("planner")                                  // no task, no handoff
+ *   delegate("implementer", "implement the plan")        // task hint only
+ *   delegate("reviewer", undefined, needs({ diff: "string" }))  // + handoff check
+ *
+ * The optional 3rd argument carries the step's input `needs` (built by
+ * `needs(...)`). When present, the whole-harness registry asserts that the
+ * PREVIOUS success-track step's `result().ok` SUPPLIES it — a cross-file
+ * handoff that doesn't line up is a `tsc` error naming the offending field.
+ * Omitting it (the historical 1-/2-arg call) keeps the exact string-path
+ * behavior — fully backwards-compatible.
+ */
+function delegate(agent, task, needsContract) {
+    const base = task === undefined
         ? { _step: "delegate", agent }
         : { _step: "delegate", agent, task };
+    return needsContract === undefined ? base : { ...base, needs: needsContract };
 }
 /**
  * Compose flat subagents into a railway (compiles to an orchestrator command).
@@ -209,6 +298,80 @@ function delegate(agent, task) {
 function railway(spec) {
     return { _specType: "railway", ...spec };
 }
+/**
+ * Declare the input fields a step reads from its predecessor's success payload.
+ * Pass it as `needs:` on a typed pipeline step. `needs({})` (the default) is a
+ * step with no upstream requirement — valid as the FIRST step of a pipeline.
+ *
+ *   needs({ plan: "string", files: "string[]" })
+ */
+function needs(shape) {
+    return shape;
+}
+/**
+ * Pair a typed agent with the input it `needs` from the previous step. The first
+ * argument is an `agent()` VALUE (which carries its `result()` shape); the
+ * second is the `needs(...)` input contract.
+ *
+ *   pipeStep(implementer, needs({ plan: "string", files: "string[]" }))
+ */
+function pipeStep(a, needsContract = {}) {
+    return { _step: "typed-delegate", agent: a, needs: needsContract };
+}
+/**
+ * Begin a typed pipeline from its first step. The first step has no upstream, so
+ * its `needs` must be empty (`needs({})` or omitted). Returns a `Pipeline`
+ * carrying that step's `ok`/`err` forward.
+ */
+function start(first) {
+    const step = "_step" in first ? first : pipeStep(first, {});
+    const out = step.agent.output;
+    return {
+        _specType: "pipeline",
+        agents: [step.agent.name],
+        ok: (out ? out.ok : {}),
+        err: (out ? out.err : {}),
+        railway: railway({
+            name: step.agent.name,
+            steps: [delegate(step.agent.name)],
+        }),
+    };
+}
+/**
+ * Append a step to a typed pipeline. The handoff is CHECKED: the constraint
+ * `Supplies<PriorOk, Needs>` must be `true`, else the `next` parameter's type
+ * collapses to a `__HANDOFF_ERROR` object and `tsc` rejects the call, naming the
+ * missing/mismatched field. Carries the new step's `ok` forward and accumulates
+ * the error track. Shallow per-call check — no recursive chain type.
+ *
+ * Named `andThen` (Wlaschin's railway `bind`/`andThen`), NOT `then`: a module
+ * exporting a function called `then` becomes a thenable, so `await import()` of
+ * any barrel re-exporting it would invoke it — a footgun the rename avoids.
+ */
+function andThen(prior, next) {
+    const real = next;
+    const out = real.agent.output;
+    const rw = railway({
+        name: prior.railway.name,
+        steps: [...prior.railway.steps, delegate(real.agent.name)],
+    });
+    return {
+        _specType: "pipeline",
+        agents: [...prior.agents, real.agent.name],
+        ok: (out ? out.ok : {}),
+        err: (out ? out.err : {}),
+        railway: rw,
+    };
+}
+function pipe(first, ...rest) {
+    // The overloads above enforce each handoff at the type level; the runtime body
+    // is the same left fold of start/andThen, untyped (the checks already happened).
+    let pipeline = start(first);
+    for (const s of rest) {
+        pipeline = andThen(pipeline, s);
+    }
+    return pipeline;
+}
 function defineConfig(config) {
     return config;
 }

package/dist/core/tool-contract.d.ts

@@ -7,7 +7,7 @@
  *
  * ONE pure detector (`one-detector-no-drift`), reused by THREE callers so they
  * can't disagree: `compileAgent` (spec authoring), `scan` (read-only audit of a
- * shipped plugin), and the `agent-tool-contract` lint rule (the severity-gated
+ * shipped plugin), and the `subagent-tool-contract` lint rule (the severity-gated
  * commit gate). The dialect is injected (core ⊄ adapter) — the composition root
  * passes `claudeCodeDialect` / `codexDialect`.
  *

package/dist/core/types.d.ts

@@ -71,7 +71,7 @@ export interface OrphansConfig {
 }
 /**
  * Shared options for the per-kind untested-* rules (`untested-skill` /
- * `untested-agent` / `untested-hook`). Which kinds are scanned is controlled by
+ * `untested-subagent` / `untested-hook`). Which kinds are scanned is controlled by
  * each rule's severity (set a rule to `false` to skip that kind), so only the
  * test-discovery knobs live here.
  */
@@ -97,7 +97,7 @@ export interface RulesConfig {
     /** Flag a skill (SKILL.md) that ships with no test or eval. Default: "warn". */
     "untested-skill"?: RuleWithOptions<TestCoverageConfig>;
     /** Flag a subagent (agents/*.md) that ships with no test or eval. Default: "warn". */
-    "untested-agent"?: RuleWithOptions<TestCoverageConfig>;
+    "untested-subagent"?: RuleWithOptions<TestCoverageConfig>;
     /** Flag a hook script that ships with no test or eval. Default: "warn". */
     "untested-hook"?: RuleWithOptions<TestCoverageConfig>;
     /**
@@ -115,7 +115,7 @@ export interface RulesConfig {
      * plugin/MCP-provided, never flagged). Off unless set; "warn" surfaces,
      * "error" gates CI. Same detector as `scan` + `compileAgent`.
      */
-    "agent-tool-contract"?: RuleSeverity;
+    "subagent-tool-contract"?: RuleSeverity;
     /**
      * Flag a hook registered under an event name the harness doesn't define (a
      * typo → the hook never fires). High-precision: close typos only, never a
@@ -128,7 +128,7 @@ export interface RulesConfig {
      * `name` (to load), an agent needs `name` + `description`. A broken surface
      * that won't register. Default "warn"; "error" gates CI. Same detector as `scan`.
      */
-    "agent-frontmatter"?: RuleSeverity;
+    "subagent-frontmatter"?: RuleSeverity;
     /**
      * Flag a declared MCP server that can't start — neither a `command` (stdio)
      * nor a `url` (http/sse). Default "warn"; "error" gates CI. Same detector as
@@ -146,7 +146,7 @@ export interface RulesConfig {
     /**
      * Cross-reference an `mcp__server__tool` in a subagent's contract against the
      * plugin's declared `mcpServers` — flag a server the plugin doesn't declare
-     * (the MCP half of the tool moat; `agent-tool-contract` checks the built-in
+     * (the MCP half of the tool moat; `subagent-tool-contract` checks the built-in
      * half). High-precision: only flags when the plugin SHIPS a declared set,
      * allowlists harness built-ins (`ide`), and skips the plugin-namespaced
      * `mcp__plugin_…` form. Default "warn"; "error" gates CI. Same detector as
@@ -163,7 +163,7 @@ export interface RulesConfig {
     "hook-script-exists"?: RuleSeverity;
     /**
      * Cross-reference a subagent's `disallowedTools:` block-list against the
-     * catalog — the deny-side mirror of `agent-tool-contract`. A close typo there
+     * catalog — the deny-side mirror of `subagent-tool-contract`. A close typo there
      * blocks NOTHING (you meant to deny `Bash`, wrote `Bsh`), leaving the tool
      * available. High-precision: close-typo only (a never-available tool is
      * harmless to list, a bare unknown is likely a plugin tool). Default "warn";

package/dist/core/validate.js

@@ -43,15 +43,15 @@ const DEFAULT_RULES = {
     coverage: false,
     // Per-kind surface-coverage: a skill/agent/hook must ship with a test or eval.
     "untested-skill": "warn",
-    "untested-agent": "warn",
+    "untested-subagent": "warn",
     "untested-hook": "warn",
     "unmarked-refs": "warn",
     // High-precision (never-available + close typos only), so on by default at warn.
-    "agent-tool-contract": "warn",
+    "subagent-tool-contract": "warn",
     // High-precision (close typos only), on by default at warn.
     "hook-events": "warn",
     // Missing required frontmatter (name/description) — on by default at warn.
-    "agent-frontmatter": "warn",
+    "subagent-frontmatter": "warn",
     // A declared MCP server with no command/url can't start — on by default at warn.
     "mcp-config": "warn",
     // Best-practice nudge (skills load without frontmatter) — warn, not error.
@@ -60,7 +60,7 @@ const DEFAULT_RULES = {
     "mcp-tool-resolves": "warn",
     // A hook script referenced but missing never runs — on by default at warn.
     "hook-script-exists": "warn",
-    // High-precision (close-typo only) deny-list mirror of agent-tool-contract.
+    // High-precision (close-typo only) deny-list mirror of subagent-tool-contract.
     "disallowed-tools-contract": "warn",
     // Deterministic NCD precision proxy (near-identical skill descriptions) — warn.
     "description-overlap": "warn",

package/dist/harness-test.d.ts

@@ -110,6 +110,13 @@ export interface SubagentTrace {
     readonly name: string;
     /** The tools the subagent invoked (events tagged with the Task's id). */
     readonly toolCalls: readonly ToolCall[];
+    /**
+     * The subagent's RETURNED text — the dispatch tool_result the orchestrator
+     * receives back. This is where a `result()` contract's `vigiles:ok`/`vigiles:err`
+     * block lands, so `subagent(name, [output(/vigiles:ok/)])` can assert the typed
+     * outcome. "" if not captured.
+     */
+    readonly output: string;
 }
 export interface HarnessTestResult extends Trace {
     readonly exitCode: number;

package/dist/harness-test.js

@@ -130,6 +130,7 @@ function parseToolCalls(streamJson) {
  */
 function parseSubagents(streamJson) {
     const tasks = new Map(); // dispatch id → subagent name
+    const dispatchOutput = new Map(); // dispatch id → returned text
     const byParent = new Map();
     const groupFor = (parent) => {
         let g = byParent.get(parent);
@@ -162,7 +163,10 @@ function parseSubagents(streamJson) {
                     // A subagent dispatch is any top-level tool_use whose input carries a
                     // `subagent_type` — the dispatch tool is named "Agent" on the live CLI
                     // (older docs say "Task"), so match the input field, NOT the tool name,
-                    // to survive the rename. Confirmed against real claude output.
+                    // to survive the rename. Confirmed against real claude output. CC NOTE:
+                    // under `--plugin-dir` the value is NAMESPACED `plugin:agent` (captured
+                    // "reviewer-spec:code-reviewer"); the bare agent name is matched in the
+                    // `subagent()` check (src/check.ts), so the full id is preserved here.
                     const sub = b.input?.subagent_type;
                     if (typeof sub === "string")
                         tasks.set(id, sub);
@@ -170,12 +174,20 @@ function parseSubagents(streamJson) {
                 if (parent)
                     groupFor(parent).uses.push({ id, name: b.name, input: b.input });
             }
-            else if (b.type === "tool_result" && parent) {
+            else if (b.type === "tool_result") {
                 const id = typeof b.tool_use_id === "string" ? b.tool_use_id : "";
-                groupFor(parent).results.set(id, {
-                    text: contentText(b.content),
-                    isError: b.is_error === true,
-                });
+                if (parent) {
+                    groupFor(parent).results.set(id, {
+                        text: contentText(b.content),
+                        isError: b.is_error === true,
+                    });
+                }
+                else if (id) {
+                    // A top-level tool_result whose id is a subagent dispatch is the SUB's
+                    // RETURN to the orchestrator (where a result() vigiles:ok/err block
+                    // lands). Record it; matched to its dispatch by id below.
+                    dispatchOutput.set(id, contentText(b.content));
+                }
             }
         }
     }
@@ -188,7 +200,7 @@ function parseSubagents(streamJson) {
             resultText: g?.results.get(u.id)?.text ?? "",
             isError: g?.results.get(u.id)?.isError ?? false,
         }));
-        out.push({ name, toolCalls });
+        out.push({ name, toolCalls, output: dispatchOutput.get(taskId) ?? "" });
     }
     return out;
 }

package/dist/leaderboard.d.ts

@@ -21,6 +21,8 @@ export interface PluginScore {
     readonly issues: readonly string[];
     readonly report: ScanReport;
 }
+/** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
+export declare function gradeFor(score: number): PluginScore["grade"];
 /** Deterministic structural-health score for one scanned plugin. */
 export declare function scoreReport(r: ScanReport): {
     score: number;

package/dist/leaderboard.js

@@ -12,6 +12,7 @@
  * model and stack on top later; this part runs anywhere in CI for free.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.gradeFor = gradeFor;
 exports.scoreReport = scoreReport;
 exports.rankPlugins = rankPlugins;
 exports.formatLeaderboard = formatLeaderboard;
@@ -23,6 +24,7 @@ const W_NO_DESCRIPTION = 10; // a skill with no usable description → can't tri
 const W_DANGLING_REF = 8; // a referenced intra-plugin file that's missing → broken path
 const W_NO_CONTRACT = 5; // an agent with no `tools:` line → inherits everything
 const W_UNTESTED = 3; // a surface with no test/eval → warning-tier
+/** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
 function gradeFor(score) {
     if (score >= 90)
         return "A";

package/dist/optimize.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
+ * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
+ * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
+ * a separate command, so it's folded into scan as one more view on the same
+ * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ *
+ * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
+ * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
+ * delta. The measured delta is the real-model layer (gated on the Pro/Max
+ * subscription, costs tokens); this v0 ships the deterministic HALF — the free
+ * pre-filter that runs on every commit with no model.
+ *
+ * It answers "what should I fix in my harness, and why" using only the cross-ref
+ * findings the linter already computes: it reuses `scoreReport` for the headline
+ * structural-health score and `explainScore` for the per-surface cause + one-line
+ * fix (one-detector-no-drift — it never re-detects). The result is a prioritized,
+ * typed action list — the spine the measured A/B (the behavioral delta) stacks on.
+ *
+ * This is the "linting as a free pre-filter to measurement" thesis made a command:
+ * clear the structural dead-ends a model can't help with FIRST (free, certain),
+ * THEN spend tokens measuring whether the structurally-clean skills earn their keep.
+ *
+ * Distinct from `vigiles explain` (which diagnoses ONE underperforming surface a
+ * measurement flagged): `optimize` is the whole-repo adoption view — health score +
+ * the ranked fix list + the hand-off to the measured layer. Same findings, the
+ * optimization framing. See research/measurement-authority.md (A2) + roadmap §P1.
+ */
+import { type PluginScore } from "./leaderboard.js";
+import { type ExplanationConfidence } from "./score-explainer.js";
+import type { ScanReport } from "./scan.js";
+/**
+ * The action a recommendation asks for. The deterministic detectors yield two:
+ * `"differentiate"` (a description-overlap PAIR — make the two distinct so the
+ * selector can disambiguate) and `"fix"` (every other structural dead-end —
+ * correct/add/remove the offending bit). The richer add/drop/swap vocabulary
+ * belongs to the MEASURED layer, once a behavioral delta ranks the alternatives.
+ */
+export type OptimizeAction = "fix" | "differentiate";
+export interface Recommendation {
+    /** The affected surface (a skill/agent/hook name or path, or an `a ↔ b` pair). */
+    readonly surface: string;
+    readonly action: OptimizeAction;
+    /** The deterministic cause (the detector's own message — no drift). */
+    readonly rationale: string;
+    /** A single, actionable fix. */
+    readonly fix: string;
+    /** The lint rule that found it (open `docs/rules/<detector>.md`). */
+    readonly detector: string;
+    readonly confidence: ExplanationConfidence;
+}
+export interface OptimizeReport {
+    readonly dir: string;
+    /** Structural-health score 0–100 (the same `scoreReport` the leaderboard uses). */
+    readonly score: number;
+    readonly grade: PluginScore["grade"];
+    /** The free deterministic fixes, `likely` dead-ends first (explainScore's order). */
+    readonly recommendations: readonly Recommendation[];
+    /**
+     * No loadable surface at all (not a plugin, or a broken load) — distinct from a
+     * clean-and-loaded harness with zero findings, so the formatter doesn't call an
+     * EMPTY machine "clean". Mirrors `scoreReport`'s empty-machine case.
+     */
+    readonly empty: boolean;
+}
+/**
+ * Turn a scan report into a prioritized optimization plan: the structural-health
+ * score + a typed recommendation per deterministic finding (`likely` dead-ends
+ * before `possible` proxies, via explainScore's own ordering). Pure over the report.
+ */
+export declare function optimize(report: ScanReport): OptimizeReport;
+/** Render an optimization plan for the CLI. */
+export declare function formatOptimize(rep: OptimizeReport): string;
+//# sourceMappingURL=optimize.d.ts.map

package/dist/optimize.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optimize = optimize;
+exports.formatOptimize = formatOptimize;
+/**
+ * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
+ * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
+ * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
+ * a separate command, so it's folded into scan as one more view on the same
+ * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ *
+ * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
+ * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
+ * delta. The measured delta is the real-model layer (gated on the Pro/Max
+ * subscription, costs tokens); this v0 ships the deterministic HALF — the free
+ * pre-filter that runs on every commit with no model.
+ *
+ * It answers "what should I fix in my harness, and why" using only the cross-ref
+ * findings the linter already computes: it reuses `scoreReport` for the headline
+ * structural-health score and `explainScore` for the per-surface cause + one-line
+ * fix (one-detector-no-drift — it never re-detects). The result is a prioritized,
+ * typed action list — the spine the measured A/B (the behavioral delta) stacks on.
+ *
+ * This is the "linting as a free pre-filter to measurement" thesis made a command:
+ * clear the structural dead-ends a model can't help with FIRST (free, certain),
+ * THEN spend tokens measuring whether the structurally-clean skills earn their keep.
+ *
+ * Distinct from `vigiles explain` (which diagnoses ONE underperforming surface a
+ * measurement flagged): `optimize` is the whole-repo adoption view — health score +
+ * the ranked fix list + the hand-off to the measured layer. Same findings, the
+ * optimization framing. See research/measurement-authority.md (A2) + roadmap §P1.
+ */
+const leaderboard_js_1 = require("./leaderboard.js");
+const score_explainer_js_1 = require("./score-explainer.js");
+function actionFor(e) {
+    return e.symptom === "wrong-skill-fires" ? "differentiate" : "fix";
+}
+function isEmptyMachine(r) {
+    const surfaces = r.skills.length + r.agents.length + r.hooks.length + r.commands;
+    return surfaces === 0 && !r.mcp;
+}
+/**
+ * Turn a scan report into a prioritized optimization plan: the structural-health
+ * score + a typed recommendation per deterministic finding (`likely` dead-ends
+ * before `possible` proxies, via explainScore's own ordering). Pure over the report.
+ */
+function optimize(report) {
+    const { score } = (0, leaderboard_js_1.scoreReport)(report);
+    const recommendations = (0, score_explainer_js_1.explainScore)(report).map((e) => ({
+        surface: e.surface,
+        action: actionFor(e),
+        rationale: e.cause,
+        fix: e.fix,
+        detector: e.detector,
+        confidence: e.confidence,
+    }));
+    return {
+        dir: report.dir,
+        score,
+        grade: (0, leaderboard_js_1.gradeFor)(score),
+        recommendations,
+        empty: isEmptyMachine(report),
+    };
+}
+const ACTION_LABEL = {
+    fix: "FIX",
+    differentiate: "DIFFERENTIATE",
+};
+const measureHint = (dir) => `\`vigiles scan ${dir} --trigger\` — real-model, runs on your subscription`;
+/** Render an optimization plan for the CLI. */
+function formatOptimize(rep) {
+    const head = `Harness health: ${String(rep.score)}/100 (${rep.grade}) — ${rep.dir}`;
+    if (rep.empty) {
+        return `${head}\n\nNothing loaded — this isn't a plugin/harness, or the load failed. Point optimize at a dir with a CLAUDE.md/AGENTS.md, skills, agents, or hooks.`;
+    }
+    if (rep.recommendations.length === 0) {
+        return `${head}\n\nNo deterministic fixes found — the structure is clean. Whether your skills actually help is a BEHAVIORAL question; measure it with ${measureHint(rep.dir)}.`;
+    }
+    const lines = [
+        head,
+        "",
+        `${String(rep.recommendations.length)} deterministic fix(es) — free, no model. Apply these before measuring:`,
+        "",
+    ];
+    for (const r of rep.recommendations) {
+        const mark = r.confidence === "likely" ? "✗" : "⚠";
+        lines.push(`${mark} [${ACTION_LABEL[r.action]}] ${r.surface}`);
+        lines.push(`    why: ${r.rationale}  [${r.detector}]`);
+        lines.push(`    →    ${r.fix}`);
+    }
+    lines.push("", `Then measure the behavioral delta of what's left (does each skill earn its keep?) with ${measureHint(rep.dir)}.`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=optimize.js.map

package/dist/scaffold-test.d.ts

@@ -0,0 +1,58 @@
+export type SurfaceKind = "skill" | "agent" | "hook";
+/** The cheapest meaningful tier for a surface kind (mirrors the test-harness skill). */
+export type TestTier = "unit" | "harness" | "eval";
+/** One field of a subagent's `result()` contract, parsed from its compiled `.md`. */
+export interface ContractField {
+    readonly name: string;
+    /** The `OutputFieldType` literal: `"string" | "number" | "boolean" | "string[]"`. */
+    readonly type: string;
+}
+/**
+ * A subagent's typed `result(ok, err)` outcome contract — the typed-spec payoff
+ * the generator turns into a real `assertAgentOk` test (no LLM judge). Parsed from
+ * the `vigiles:ok` / `vigiles:err` blocks the compiler emits into the agent `.md`.
+ */
+export interface ResultContract {
+    readonly ok: readonly ContractField[];
+    readonly err: readonly ContractField[];
+}
+/** What the generator needs to know about a surface to scaffold its test. */
+export interface ScaffoldInput {
+    readonly kind: SurfaceKind;
+    /** Skill dir name / agent name / hook-script basename. */
+    readonly name: string;
+    /** Repo-relative path to the surface (SKILL.md / agent .md / hook script). */
+    readonly path: string;
+    /** Plugin name for the namespaced skill id; a placeholder TODO when unknown. */
+    readonly pluginName?: string;
+    /** A user-invoked skill — trigger-rate is for model-invocable skills, so note it. */
+    readonly userInvoked?: boolean;
+    /** A subagent's declared tool contract (drives the assertion hint); null = inherits all. */
+    readonly tools?: readonly string[] | null;
+    /**
+     * The side-effecting tools in the contract (`effectSurface(tools).sideEffecting`,
+     * computed by the CLI with the resolved dialect — kept harness-agnostic here). A
+     * non-empty list drives a generated SAFETY check: the agent's "hole" is mocked/denied
+     * and asserted to stay in its lane — the typed `tools` contract writing its own test.
+     */
+    readonly sideEffectingTools?: readonly string[];
+    /**
+     * The subagent's `result()` contract parsed from its compiled `.md`. Present →
+     * the generator emits a deterministic `assertAgentOk` outcome test (no LLM judge);
+     * the single most-concrete "the typed spec wrote your test" payoff.
+     */
+    readonly resultContract?: ResultContract | null;
+    /** How the CLI invokes the hook (e.g. `bash hooks/pre-edit.sh`); a TODO when unknown. */
+    readonly hookCommand?: string;
+}
+export interface Scaffold {
+    readonly path: string;
+    readonly content: string;
+    readonly kind: SurfaceKind;
+    readonly tier: TestTier;
+}
+/** Scaffold a starter test for one surface. Pure: path + content, no I/O. */
+export declare function scaffoldTest(input: ScaffoldInput): Scaffold;
+/** Render a set of scaffolds for the CLI (what was generated, where, which tier). */
+export declare function formatScaffolds(scaffolds: readonly Scaffold[]): string;
+//# sourceMappingURL=scaffold-test.d.ts.map