vigiles 5.0.1 → 5.2.0

package/dist/scan.js

@@ -13,75 +13,257 @@
  * stack on top later; this core stays pure so it runs anywhere in CI for free.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.unexpectedScript = unexpectedScript;
 exports.scanPlugin = scanPlugin;
+exports.inspectMarketplace = inspectMarketplace;
+exports.expandMarketplace = expandMarketplace;
 exports.formatScanReport = formatScanReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
+const layout_js_1 = require("./adapters/claude-code/layout.js");
+const dialect_js_1 = require("./adapters/claude-code/dialect.js");
+const plugin_loader_js_2 = require("./plugin-loader.js");
+const tool_contract_js_1 = require("./core/tool-contract.js");
+const hook_events_js_1 = require("./core/hook-events.js");
+const mcp_config_js_1 = require("./core/mcp-config.js");
+const linters_js_1 = require("./core/linters.js");
+const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
+const description_overlap_js_1 = require("./core/description-overlap.js");
+const mcp_tool_js_1 = require("./core/mcp-tool.js");
+const mcp_hook_js_1 = require("./core/mcp-hook.js");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
 const test_coverage_js_1 = require("./test-coverage.js");
+const effects_js_1 = require("./core/effects.js");
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
 const SCRIPT_RE = /\S+\.(?:sh|mjs|cjs|js|ts|py|rb)\b/g;
+// The scalar fields scan reads from a skill/agent `---` block, via the shared
+// lenient reader (core/frontmatter-read.ts) — a real YAML parse with a regex
+// salvage on malformed input, so block scalars / multi-line quoted values parse
+// for free and a bad block still yields what it can. One reader, no drift.
 function frontmatter(md) {
-    const m = /(?:^|\n)---\r?\n([\s\S]*?)\r?\n---/.exec(md);
-    if (!m)
-        return {};
-    const name = /^name:\s*(.+)$/m.exec(m[1])?.[1]?.trim();
-    const description = /^description:\s*(.+)$/m.exec(m[1])?.[1]?.trim();
-    return { name, description };
-}
-const isSkill = (f) => /skills\/[^/]+\/SKILL\.md$/.test(f);
-const isAgent = (f) => /agents\/[^/]+\.md$/.test(f) && !f.endsWith(".spec.ts");
-const isCommand = (f) => /commands\/.+\.md$/.test(f);
+    const fm = (0, frontmatter_read_js_1.readFrontmatter)(md);
+    return {
+        name: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "name"),
+        description: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "description"),
+        model: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "model"),
+        color: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "color"),
+    };
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function makeClassifier(layout) {
+    // An empty dir means "this harness has no such surface" → never matches.
+    const at = (dir) => dir ? `(?:^|/)${escapeRe(dir)}/` : null;
+    const skill = at(layout.skillDir);
+    const agent = at(layout.agentDir);
+    const command = at(layout.commandDir);
+    const skillRe = skill ? new RegExp(`${skill}[^/]+/SKILL\\.md$`) : null;
+    const agentRe = agent ? new RegExp(`${agent}[^/]+\\.md$`) : null;
+    const commandRe = command ? new RegExp(`${command}.+\\.md$`) : null;
+    return {
+        isSkill: (f) => skillRe?.test(f) ?? false,
+        isAgent: (f) => (agentRe?.test(f) ?? false) && !f.endsWith(".spec.ts"),
+        isCommand: (f) => commandRe?.test(f) ?? false,
+    };
+}
 function skillName(path) {
     return (path
         .replace(/\/SKILL\.md$/, "")
         .split("/")
         .pop() ?? path);
 }
-function scanSkills(files) {
+// [Unicode \p{Script=…} property value (Node native, no dependency), our Script
+// label]. Japanese kana fold to "Japanese". Latin is the DEFAULT expectation (the
+// selector is English-centric), but it's just a default — a language-matched pack
+// can declare a different expectation, and then the OTHER script is the mismatch.
+const SCRIPTS = [
+    ["Latin", "Latin"],
+    ["Cyrillic", "Cyrillic"],
+    ["Han", "Han"],
+    ["Hiragana", "Japanese"],
+    ["Katakana", "Japanese"],
+    ["Hangul", "Korean"],
+    ["Arabic", "Arabic"],
+    ["Hebrew", "Hebrew"],
+    ["Greek", "Greek"],
+    ["Devanagari", "Devanagari"],
+    ["Thai", "Thai"],
+];
+/** Letter counts per named script label (Japanese kana folded together). */
+function scriptCounts(text) {
+    const counts = new Map();
+    for (const [script, label] of SCRIPTS) {
+        const n = (text.match(new RegExp(`\\p{Script=${script}}`, "gu")) ?? [])
+            .length;
+        if (n > 0)
+            counts.set(label, (counts.get(label) ?? 0) + n);
+    }
+    return counts;
+}
+/**
+ * The description's dominant alphabetic script when it DIFFERS from `expected`
+ * (default `"Latin"`) — the cross-language trigger-risk signal. The model's
+ * skill-selection context is English-centric, so a description written mostly in
+ * another script may under-fire on English prompts. `expected` is a configurable
+ * default, not a value judgement: a Russian-targeted pack sets it to `"Cyrillic"`
+ * so its Cyrillic descriptions pass and an English one is flagged instead.
+ * Returns null when the dominant script IS the expected one (or there's no
+ * alphabetic content). Shared by `scan` and the future lint rule (one detector,
+ * no drift). The ≥20% guard avoids a near-empty string tripping on one letter.
+ */
+function unexpectedScript(text, expected = "Latin") {
+    const counts = scriptCounts(text);
+    let total = 0;
+    let dominant = null;
+    for (const [label, count] of counts) {
+        total += count;
+        if (!dominant || count > dominant.count)
+            dominant = { label, count };
+    }
+    if (!dominant || dominant.label === expected)
+        return null;
+    return dominant.count / total >= 0.2 ? dominant.label : null;
+}
+/**
+ * The first prose paragraph of a SKILL.md body (after the frontmatter and any
+ * leading `#` headings) — Claude Code's FALLBACK skill description when the
+ * frontmatter omits `description`. Used so the trigger-surface check doesn't
+ * overclaim "can't trigger" for a skill that has a usable body paragraph.
+ */
+function firstBodyParagraph(md) {
+    const body = md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+    const para = [];
+    for (const line of body.split(/\r?\n/)) {
+        const t = line.trim();
+        if (t === "" || t.startsWith("#")) {
+            if (para.length > 0)
+                break; // end of the first paragraph
+            continue; // skip leading blanks / headings
+        }
+        para.push(t);
+    }
+    return para.join(" ").trim() || undefined;
+}
+function scanSkills(files, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isSkill(path))
+        if (!cls.isSkill(path))
             continue;
         const fm = frontmatter(md);
+        // A skill's trigger surface is its frontmatter `description` OR — when that's
+        // absent — Claude Code's fallback to the first body paragraph. Only when
+        // NEITHER exists is the skill genuinely undescribed (can't be selected). The
+        // explicit-frontmatter best-practice is the separate `skill-frontmatter` rule.
+        const effectiveDesc = fm.description ?? firstBodyParagraph(md);
         out.push({
             name: fm.name ?? skillName(path),
             path,
-            hasDescription: Boolean(fm.description && fm.description.length >= 20),
+            hasDescription: Boolean(effectiveDesc && effectiveDesc.length >= 20),
             userInvoked: /^\s*disable-model-invocation:\s*true\s*$/m.test(md),
+            descriptionScript: effectiveDesc ? unexpectedScript(effectiveDesc) : null,
         });
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
-function scanAgents(files) {
+/**
+ * Near-duplicate description pairs among the MODEL-INVOCABLE skills — the ones
+ * that actually compete for auto-selection (a user-invoked skill is picked by
+ * explicit command, so it can't collide). Uses the same effective-description
+ * logic as `scanSkills` (frontmatter `description` ← first body paragraph), then
+ * the NCD precision-proxy. See description-overlap.ts.
+ */
+function descriptionOverlapsFor(files, cls) {
+    const surfaces = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!cls.isSkill(path))
+            continue;
+        if (/^\s*disable-model-invocation:\s*true\s*$/m.test(md))
+            continue;
+        const fm = frontmatter(md);
+        const description = fm.description ?? firstBodyParagraph(md);
+        if (!description || description.length < 20)
+            continue;
+        surfaces.push({ name: fm.name ?? skillName(path), description });
+    }
+    return (0, description_overlap_js_1.findDescriptionOverlaps)(surfaces);
+}
+function scanAgents(files, dialect, declaredServers, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isAgent(path))
+        if (!cls.isAgent(path))
             continue;
-        out.push({ name: (0, node_path_1.basename)(path, ".md"), path, tools: (0, agent_runtime_js_1.parseAgentTools)(md) });
+        const tools = (0, agent_runtime_js_1.parseAgentTools)(md);
+        // An inherits-all agent (no `tools:` line) grants access to every tool
+        // including every side-effecting one — pass the wildcard sentinel so
+        // effectSurface correctly classifies it as `"unrestricted"`.
+        const surface = (0, effects_js_1.effectSurface)(tools ?? ["*"], dialect);
+        out.push({
+            name: (0, node_path_1.basename)(path, ".md"),
+            path,
+            tools,
+            // Cross-reference the declared rail against the dialect catalog — the moat.
+            // Auditing third-party plugins → only the HIGH-CONFIDENCE issues (never-
+            // available + close typos); a bare unrecognized tool is likely plugin/MCP-
+            // provided, not a defect (the TaskCreate/TaskGet lesson). See tool-contract.ts.
+            toolIssues: tools
+                ? (0, tool_contract_js_1.confidentToolIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect))
+                : [],
+            // The MCP half of the moat: an `mcp__server__tool` whose server isn't in the
+            // plugin's declared set can't resolve. High-precision (gated on a declared
+            // set, built-ins allowlisted, plugin-namespaced form skipped). See mcp-tool.ts.
+            mcpToolIssues: tools
+                ? (0, mcp_tool_js_1.verifyMcpToolServers)(tools, declaredServers, dialect)
+                : [],
+            // The block-list mirror: a `disallowedTools:` entry that's a typo of a real
+            // tool blocks nothing (close-typo only — high-precision). See tool-contract.ts.
+            disallowedToolIssues: (0, tool_contract_js_1.disallowedToolIssues)((0, agent_runtime_js_1.parseAgentToolList)(md, "disallowedTools") ?? [], dialect),
+            purity: surface.purity,
+            effectBuckets: {
+                readOnly: surface.readOnly,
+                sideEffecting: surface.sideEffecting,
+                unknown: surface.unknown,
+            },
+        });
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
  * Resolve a hook script token to a checkable path. `loadPlugin` expands the
- * braced `${CLAUDE_PLUGIN_ROOT}`; the unbraced shell form `$CLAUDE_PLUGIN_ROOT`
- * survives, so resolve it against the plugin root here and strip shell quotes.
- * A token that still carries any `$VAR` after that is genuinely uncheckable.
+ * braced plugin-root token (`${CLAUDE_PLUGIN_ROOT}`, Codex `${PLUGIN_ROOT}`, …);
+ * the unbraced shell form survives, so resolve BOTH forms of the HARNESS's token
+ * (from the layout, not hard-coded) against the plugin root and strip shell
+ * quotes. A token that still carries any `$VAR` after that is genuinely
+ * uncheckable.
  */
-function resolveScript(token, root) {
-    const path = token
+function resolveScript(token, root, pluginRootToken) {
+    // "${CLAUDE_PLUGIN_ROOT}" → unbraced "$CLAUDE_PLUGIN_ROOT".
+    const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
+    const cleaned = token
         .replace(/["']/g, "")
-        .replaceAll("${CLAUDE_PLUGIN_ROOT}", root)
-        .replaceAll("$CLAUDE_PLUGIN_ROOT", root);
-    if (path.includes("$"))
+        .replaceAll(pluginRootToken, root)
+        .replaceAll(unbraced, root);
+    if (cleaned.includes("$"))
         return { script: token, status: "unresolved" };
-    return { script: path, status: (0, node_fs_1.existsSync)(path) ? "ok" : "missing" };
+    // A relative hook path (`./hooks/x.sh`, `scripts/x.py`) is the plugin's own —
+    // resolve it against the PLUGIN ROOT, not the scanner's cwd. Without this, a
+    // plugin that references `./hooks/x.sh` (the file IS present) was reported
+    // MISSING because existsSync() checked cwd-relative (a false positive caught on
+    // ananddtyagi/cc-marketplace). The displayed `script` stays as the author wrote it.
+    const abs = (0, node_path_1.isAbsolute)(cleaned) ? cleaned : (0, node_path_1.resolve)(root, cleaned);
+    return { script: cleaned, status: (0, node_fs_1.existsSync)(abs) ? "ok" : "missing" };
 }
+// A shell existence guard around a command — `[ ! -f x ] || x`, `[ -f x ] && x`,
+// `test -f x && …`. Authors use it to make a hook OPTIONAL (run the script only
+// if present; a no-op otherwise — e.g. a runtime-generated guard), so a missing
+// target is INTENTIONAL, not a broken reference. Don't flag scripts in such a
+// command as MISSING (a false positive caught on gmickel/flow-next's ralph-guard).
+const EXISTENCE_GUARD = /(?:\[\[?\s*!?\s*-[efsx]\s)|(?:\btest\s+!?\s*-[efsx]\s)/;
 /** Pull script-file hook commands out of the resolved settings; count inline ones. */
-function scanHooks(settings, root) {
+function scanHooks(settings, root, pluginRootToken) {
     const text = JSON.stringify(settings.hooks ?? {});
     const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
     const byScript = new Map();
@@ -93,8 +275,14 @@ function scanHooks(settings, root) {
             inline++;
             continue;
         }
+        // A guarded command runs its script only if it exists — an optional hook, not
+        // a broken one. Treat it as a conditional one-liner (inline), don't path-check.
+        if (EXISTENCE_GUARD.test(unescaped)) {
+            inline++;
+            continue;
+        }
         for (const tok of found) {
-            const hook = resolveScript(tok, root);
+            const hook = resolveScript(tok, root, pluginRootToken);
             byScript.set(hook.script, hook);
         }
     }
@@ -104,45 +292,376 @@ function scanHooks(settings, root) {
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/**
+ * Frontmatter-schema check — **subagents only**. Per the Claude Code docs, a
+ * subagent (`agents/*.md`) REQUIRES `name` + `description` (no fallback) or it
+ * won't register. A SKILL.md requires NOTHING: `name` falls back to the directory
+ * name and `description` to the first body paragraph, so a frontmatter-less skill
+ * still loads — flagging it would be a false positive (skill description QUALITY
+ * is a separate, behavioral concern). See https://code.claude.com/docs/en/skills
+ * and …/sub-agents.
+ */
+function frontmatterIssuesFor(files, cls) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!cls.isAgent(path))
+            continue; // skills require no frontmatter (dir/body fallbacks)
+        const fm = frontmatter(md);
+        const missing = [];
+        if (!fm.name)
+            missing.push("name");
+        if (!fm.description)
+            missing.push("description");
+        if (missing.length === 0)
+            continue;
+        out.push({
+            path,
+            kind: "agent",
+            missing,
+            message: `agent ${path} is missing required frontmatter: ${missing.join(", ")} — it won't register.`,
+        });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+// The canonical subagent `model:` aliases and `color:` enum (Claude Code). The
+// model check skips a full/dated id (`claude-sonnet-4-5`) — that's a valid
+// explicit form, not a typo — so only an alias misspelling is caught.
+const MODEL_ALIASES = ["inherit", "sonnet", "opus", "haiku"];
+const AGENT_COLORS = [
+    "red",
+    "blue",
+    "green",
+    "yellow",
+    "purple",
+    "orange",
+    "pink",
+    "cyan",
+];
+/**
+ * Closest candidate by edit distance, ONLY when it's a high-confidence typo: the
+ * value isn't already a candidate, and the nearest is within 2 edits. Returns
+ * null otherwise — a far-off value is more likely an unknown-we-don't-know than a
+ * typo (the high-precision discipline), so it's suppressed, not flagged.
+ */
+function closeCandidate(value, candidates) {
+    const v = value.toLowerCase();
+    if (candidates.includes(v))
+        return null;
+    let best = null;
+    let bestDistance = Infinity;
+    for (const c of candidates) {
+        const dist = (0, linters_js_1.editDistance)(v, c);
+        if (dist < bestDistance) {
+            bestDistance = dist;
+            best = c;
+        }
+    }
+    return bestDistance > 0 && bestDistance <= 2 ? best : null;
+}
+/**
+ * Agent frontmatter VALUE validity — a `model:` or `color:` that's a close typo
+ * of a real one. A bad `model:` silently falls back; a bad `color:` is ignored.
+ * High-precision (close-typo only); a full/dated model id is left alone. Folded
+ * into the `subagent-frontmatter` rule. Agents only (skills have no model/color).
+ */
+function frontmatterValueIssuesFor(files, cls) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!cls.isAgent(path))
+            continue;
+        const fm = frontmatter(md);
+        // A model id with a digit/hyphen is an explicit form, not an alias typo.
+        if (fm.model && !/[0-9-]/.test(fm.model)) {
+            const near = closeCandidate(fm.model, MODEL_ALIASES);
+            if (near) {
+                out.push({
+                    path,
+                    field: "model",
+                    value: fm.model,
+                    suggestion: near,
+                    message: `agent ${path} has model "${fm.model}", not a known alias — it silently falls back. Did you mean "${near}"?`,
+                });
+            }
+        }
+        if (fm.color) {
+            const near = closeCandidate(fm.color, AGENT_COLORS);
+            if (near) {
+                out.push({
+                    path,
+                    field: "color",
+                    value: fm.color,
+                    suggestion: near,
+                    message: `agent ${path} has color "${fm.color}", not a valid color — it's ignored. Did you mean "${near}"?`,
+                });
+            }
+        }
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Frontmatter that EXISTS but isn't valid YAML — the `frontmatter-valid` signal.
+ * Reported for skills + agents via the shared reader's `malformed` flag. Honest
+ * caveat (see docs/rules/frontmatter-valid.md): js-yaml is stricter than some
+ * loaders, so a one-line `description:` containing a `: ` colon or an `<example>`
+ * block is flagged even though it may still load — which is why scan surfaces it
+ * as an informational note (NOT a structural defect) and the lint rule is a
+ * warn, not an error. The file's other fields are still salvaged.
+ */
+function malformedFrontmatterFor(files, cls) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!cls.isSkill(path) && !cls.isAgent(path))
+            continue;
+        if (!(0, frontmatter_read_js_1.readFrontmatter)(md).malformed)
+            continue;
+        out.push({
+            path,
+            message: `${path}: frontmatter is not valid YAML — fields may not parse as intended (a colon, quote, or bracket likely needs escaping/quoting).`,
+        });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Skill-metadata RECOMMENDATION (not a correctness check): a `SKILL.md` loads
+ * fine without frontmatter (`name` ← dir, `description` ← first body paragraph),
+ * but relying on those fallbacks is fragile — the dir name may be unclear and the
+ * first paragraph is often a heading or boilerplate, making a weak trigger
+ * surface. Best practice is an EXPLICIT `name` + `description`. Flags skills
+ * missing either; surfaced as a soft note in scan (NOT a structural defect, NOT
+ * scored) and gated by the `skill-frontmatter` lint rule (warn by default).
+ */
+function skillMetaIssuesFor(files, cls) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!cls.isSkill(path))
+            continue;
+        const fm = frontmatter(md);
+        const missing = [];
+        if (!fm.name)
+            missing.push("name");
+        if (!fm.description)
+            missing.push("description");
+        if (missing.length === 0)
+            continue;
+        out.push({
+            path,
+            kind: "skill",
+            missing,
+            message: `skill ${path} has no explicit frontmatter ${missing.join(" / ")} — recommended for a reliable trigger surface (it still loads via the dir-name / first-paragraph fallback).`,
+        });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Collect declared MCP servers from the JSON sources (`.mcp.json` + the plugin
+ * manifest's `mcpServers`). Codex's TOML `[mcp_servers]` isn't parsed here (a
+ * documented gap); the JSON CC shape is the common case. Merged so a server
+ * defined in both sources appears once. Shared by the `mcp-config` check (does
+ * each server start?) and `mcp-tool-resolves` (is each referenced server here?).
+ */
+function collectMcpServers(root, layout) {
+    const servers = {};
+    const collect = (file) => {
+        const p = (0, node_path_1.join)(root, file);
+        if (!(0, node_fs_1.existsSync)(p))
+            return;
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+            if (parsed.mcpServers !== null && typeof parsed.mcpServers === "object") {
+                Object.assign(servers, parsed.mcpServers);
+            }
+        }
+        catch {
+            /* malformed JSON is the loader's concern, not this check's */
+        }
+    };
+    collect(".mcp.json");
+    collect(layout.manifestPath);
+    return servers;
+}
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
-function scanPlugin(dir, layout) {
-    const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, layout);
-    const { hooks, inline } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir));
+function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
+    const lay = layout ?? layout_js_1.claudeCodeLayout;
+    const cls = makeClassifier(lay);
+    const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
+    const { hooks, inline } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
+    // Hook-event keys are a CLOSED platform set — an unrecognized one is a dead
+    // registration (the hook never fires), so flag every unknown (not just typos).
+    // ONLY for the canonical object-keyed-by-event shape: a plugin shipping a
+    // hooks ARRAY uses a non-CC/custom format whose events live INSIDE each entry
+    // (e.g. ananddtyagi/sugar's `[{event:"tool-use",…}]`) — Object.keys would read
+    // array INDICES, a false positive. We don't interpret a format we don't own.
+    const hooksObj = loaded.settings.hooks;
+    const eventNames = hooksObj !== null &&
+        typeof hooksObj === "object" &&
+        !Array.isArray(hooksObj)
+        ? Object.keys(hooksObj)
+        : [];
+    const hookEventIssues = (0, hook_events_js_1.confidentHookEventIssues)((0, hook_events_js_1.verifyHookEvents)(eventNames, dialect));
+    const instructions = loaded.files[lay.instructionFile] !== undefined
+        ? {
+            file: lay.instructionFile,
+            hasSpec: (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.resolve)(dir), `${lay.instructionFile}.spec.ts`)),
+        }
+        : null;
+    const mcpServers = collectMcpServers((0, node_path_1.resolve)(dir), lay);
+    const declaredServers = Object.keys(mcpServers);
+    const agents = scanAgents(loaded.files, dialect, declaredServers, cls);
+    const puritySummary = agents.reduce((acc, a) => {
+        acc[a.purity]++;
+        return acc;
+    }, { pure: 0, bounded: 0, unrestricted: 0 });
     return {
         dir,
-        skills: scanSkills(loaded.files),
-        agents: scanAgents(loaded.files),
+        instructions,
+        skills: scanSkills(loaded.files, cls),
+        agents,
         hooks,
         inlineHooks: inline,
-        commands: Object.keys(loaded.files).filter(isCommand).length,
+        commands: Object.keys(loaded.files).filter(cls.isCommand).length,
         mcp: loaded.warnings.some((w) => w.includes("MCP server")),
+        danglingRefs: (0, plugin_loader_js_2.danglingRefs)((0, node_path_1.resolve)(dir), lay),
+        hookEventIssues,
+        frontmatterIssues: frontmatterIssuesFor(loaded.files, cls),
+        frontmatterValueIssues: frontmatterValueIssuesFor(loaded.files, cls),
+        skillMetaIssues: skillMetaIssuesFor(loaded.files, cls),
+        mcpIssues: (0, mcp_config_js_1.verifyMcpServers)(mcpServers),
+        mcpHookIssues: (0, mcp_hook_js_1.verifyMcpHookTargets)(loaded.settings.hooks, declaredServers, dialect),
+        descriptionOverlaps: descriptionOverlapsFor(loaded.files, cls),
+        malformedFrontmatter: malformedFrontmatterFor(loaded.files, cls),
         warnings: loaded.warnings,
-        untested: (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir }).untested.length,
+        untested: (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir, layout: lay }).untested
+            .length,
+        puritySummary,
+    };
+}
+/**
+ * Read a `marketplace.json` beside the layout's plugin manifest and classify its
+ * members into on-disk vs external. Returns `null` when `dir` is not a
+ * marketplace. The source of truth behind {@link expandMarketplace} and the
+ * curated-marketplace report in `vigiles scan`.
+ */
+function inspectMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
+    const mpPath = (0, node_path_1.join)(dir, (0, node_path_1.dirname)(layout.manifestPath), "marketplace.json");
+    if (!(0, node_fs_1.existsSync)(mpPath))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(mpPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    const plugins = parsed.plugins;
+    if (!Array.isArray(plugins))
+        return null;
+    const name = parsed.name;
+    // Dedupe by resolved path: a marketplace may map several named entries to the
+    // SAME plugin dir (TheBushidoCollective/han aliases 338 names onto 159 dirs).
+    // Scanning a dir twice is pure noise, so each on-disk member counts once.
+    const onDisk = [];
+    const seen = new Set();
+    let external = 0;
+    for (const entry of plugins) {
+        const source = entry.source;
+        if (typeof source !== "string") {
+            external++; // external plugin (url/git/github object), not on disk
+            continue;
+        }
+        const abs = (0, node_path_1.resolve)(dir, source);
+        if ((0, node_fs_1.existsSync)(abs) && (0, node_fs_1.statSync)(abs).isDirectory()) {
+            if (!seen.has(abs)) {
+                seen.add(abs);
+                onDisk.push(abs);
+            }
+        }
+        else {
+            external++; // a string source that doesn't resolve on disk
+        }
+    }
+    return {
+        name: typeof name === "string" ? name : (0, node_path_1.basename)(dir),
+        onDisk,
+        external,
+        total: plugins.length,
     };
 }
-function section(title, lines) {
+/**
+ * If `dir` is a plugin MARKETPLACE (a `marketplace.json` beside the layout's
+ * plugin manifest, e.g. `.claude-plugin/marketplace.json`), expand it into the
+ * absolute dirs of its member plugins. Returns `null` when there's no
+ * marketplace, `[]` when it's a marketplace whose members are all external (not
+ * on disk). Used by `vigiles scan` to rank a whole marketplace — wshobson/agents
+ * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
+ */
+function expandMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
+    const mp = inspectMarketplace(dir, layout);
+    return mp ? [...mp.onDisk] : null;
+}
+// `count` defaults to the number of lines, but a section whose entries span
+// multiple lines (Agents: a header + indented issue lines; Hooks: file hooks +
+// an inline-summary line) passes the real entity count so the header isn't
+// inflated by sub-lines.
+function section(title, lines, count = lines.length) {
     if (lines.length === 0)
         return [];
-    return [`${title} (${String(lines.length)}):`, ...lines, ""];
+    return [`${title} (${String(count)}):`, ...lines, ""];
+}
+/** One skill's report line: ✓/⚠ + name + notes (no-trigger, user-invoked, language risk). */
+function skillLine(s) {
+    if (!s.hasDescription) {
+        return `  ⚠ ${s.name} (no usable description — no frontmatter description and no body text — can't trigger)`;
+    }
+    const notes = [];
+    if (s.userInvoked)
+        notes.push("user-invoked");
+    if (s.descriptionScript) {
+        notes.push(`description in ${s.descriptionScript} — cross-language trigger risk`);
+    }
+    const mark = s.descriptionScript ? "⚠" : "✓";
+    return `  ${mark} ${s.name}${notes.length ? ` (${notes.join("; ")})` : ""}`;
+}
+/** One agent's report block: ✗ (broken contract) / ⚠ (inherits all) / ✓ + issues + purity. */
+function agentLines(a) {
+    const tools = a.tools === null
+        ? "tools: (inherits all — no contract)"
+        : `tools: ${a.tools.join(", ") || "(none)"}`;
+    const broken = a.toolIssues.length +
+        a.mcpToolIssues.length +
+        a.disallowedToolIssues.length;
+    let mark = "✓";
+    if (broken > 0)
+        mark = "✗";
+    else if (a.tools === null)
+        mark = "⚠";
+    // Purity is an informational health signal (not a structural defect); mark it
+    // clearly so a reader knows which rung this agent is on.
+    const PURITY_TAGS = {
+        pure: "pure",
+        bounded: "bounded",
+        unrestricted: "unrestricted",
+    };
+    const purityTag = PURITY_TAGS[a.purity] ?? "unrestricted";
+    const lines = [`  ${mark} ${a.name} — ${tools} [${purityTag}]`];
+    for (const issue of a.toolIssues)
+        lines.push(`      ✗ ${issue.message}`);
+    for (const issue of a.mcpToolIssues)
+        lines.push(`      ✗ ${issue.message}`);
+    for (const issue of a.disallowedToolIssues)
+        lines.push(`      ✗ ${issue.message}`);
+    return lines;
 }
 /** Format a scan report as human-readable text. */
 function formatScanReport(r) {
     const out = [`Scan: ${r.dir}`, ""];
-    out.push(...section("Skills", r.skills.map((s) => {
-        const mark = s.hasDescription ? "✓" : "⚠";
-        const note = s.hasDescription
-            ? s.userInvoked
-                ? "(user-invoked)"
-                : ""
-            : "(missing/short description — can't trigger)";
-        return `  ${mark} ${s.name} ${note}`.trimEnd();
-    })));
-    out.push(...section("Agents", r.agents.map((a) => {
-        const tools = a.tools === null
-            ? "tools: (inherits all — no contract)"
-            : `tools: ${a.tools.join(", ") || "(none)"}`;
-        return `  ${a.tools === null ? "⚠" : "✓"} ${a.name} — ${tools}`;
-    })));
+    if (r.instructions) {
+        const tag = r.instructions.hasSpec
+            ? "spec-managed"
+            : "hand-written, no spec";
+        out.push(`Instructions: ${r.instructions.file} (${tag})`, "");
+    }
+    out.push(...section("Skills", r.skills.map(skillLine)));
+    out.push(...section("Agents", r.agents.flatMap(agentLines), r.agents.length));
     const hookMark = {
         ok: "✓",
         missing: "✗",
@@ -157,18 +676,66 @@ function formatScanReport(r) {
     if (r.inlineHooks > 0) {
         hookLines.push(`  · ${String(r.inlineHooks)} inline hook(s) (no script file)`);
     }
-    out.push(...section("Hooks", hookLines));
+    out.push(...section("Hooks", hookLines, r.hooks.length + r.inlineHooks));
+    out.push(...section("Broken references", r.danglingRefs.map((ref) => `  ✗ ${ref} (referenced but MISSING)`)));
+    out.push(...section("Hook events", r.hookEventIssues.map((i) => `  ✗ ${i.message}`)));
+    out.push(...section("Frontmatter", [
+        ...r.frontmatterIssues.map((i) => `  ✗ ${i.message}`),
+        ...r.frontmatterValueIssues.map((i) => `  ✗ ${i.message}`),
+    ]));
+    out.push(...section("MCP config", r.mcpIssues.map((i) => `  ✗ ${i.message}`)));
+    out.push(...section("MCP hook targets", r.mcpHookIssues.map((i) => `  ✗ ${i.message}`)));
+    out.push(...section("Description overlap (precision risk)", r.descriptionOverlaps.map((o) => `  ⚠ ${o.message}`)));
     const facts = [];
     if (r.commands > 0)
         facts.push(`Commands: ${String(r.commands)}`);
     facts.push(`MCP servers: ${r.mcp ? "yes" : "no"}`);
     facts.push(`Untested surfaces: ${String(r.untested)}`);
+    // Effect surface: harness-level purity summary across all scanned agents.
+    // Informational (higher pure% = more constrained, cheaper to test); shown
+    // only when there are agents to summarize (no agents → no summary line).
+    if (r.agents.length > 0) {
+        const { pure, bounded, unrestricted } = r.puritySummary;
+        facts.push(`Effect surface: ${String(pure)} pure · ${String(bounded)} bounded · ${String(unrestricted)} unrestricted`);
+    }
     out.push(...facts, "");
-    if (r.warnings.length > 0) {
-        out.push("Warnings:", ...r.warnings.map((w) => `  - ${w}`), "");
+    // The dangling-ref warning is now shown as a first-class ✗ section above, so
+    // drop it from the free-text list to avoid saying the same thing twice.
+    const warnings = r.warnings.filter((w) => !w.includes("intra-plugin file(s) that don't exist"));
+    if (warnings.length > 0) {
+        out.push("Warnings:", ...warnings.map((w) => `  - ${w}`), "");
+    }
+    // Cross-language trigger risk is a RISK, not a structural defect (a
+    // language-matched audience is fine), so it's reported separately from the
+    // verdict — it points at the behavioral column, it doesn't fail the scan.
+    const mismatched = r.skills.filter((s) => s.descriptionScript);
+    if (mismatched.length > 0) {
+        out.push(`⚠ ${String(mismatched.length)} skill(s) have descriptions in an unexpected script (cross-language trigger risk) — measure with \`scan --trigger\``, "");
+    }
+    // Skill-metadata is a RECOMMENDATION, not a structural defect (the skill loads
+    // via fallbacks) — reported as a soft note, never counted in the verdict.
+    if (r.skillMetaIssues.length > 0) {
+        out.push(`ℹ ${String(r.skillMetaIssues.length)} skill(s) lack an explicit frontmatter name/description (recommended for a reliable trigger surface) — they still load via fallback`, "");
+    }
+    // Malformed-YAML frontmatter is INFORMATIONAL, not a structural defect: js-yaml
+    // is stricter than some loaders (a colon/quote/<example> in a one-line
+    // description trips it though the file may still load), and the other fields are
+    // salvaged. Surfaced as a note; the frontmatter-valid lint rule warns on it.
+    if (r.malformedFrontmatter.length > 0) {
+        out.push(`ℹ ${String(r.malformedFrontmatter.length)} file(s) have frontmatter that isn't valid YAML — fields may not parse as intended (verify before enforcing \`frontmatter-valid\`)`, "");
     }
     const broken = r.hooks.filter((h) => h.status === "missing").length +
-        r.skills.filter((s) => !s.hasDescription).length;
+        r.skills.filter((s) => !s.hasDescription).length +
+        r.agents.reduce((n, a) => n +
+            a.toolIssues.length +
+            a.mcpToolIssues.length +
+            a.disallowedToolIssues.length, 0) +
+        r.danglingRefs.length +
+        r.hookEventIssues.length +
+        r.frontmatterIssues.length +
+        r.frontmatterValueIssues.length +
+        r.mcpIssues.length +
+        r.mcpHookIssues.length;
     out.push(broken === 0
         ? "✓ no structural issues found"
         : `⚠ ${String(broken)} structural issue(s) — see ✗/⚠ above`);