vigiles 14.7.0 → 14.8.0

package/dist/scan-core.js

@@ -0,0 +1,690 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeClassifier = makeClassifier;
+exports.scanSkills = scanSkills;
+exports.descriptionOverlapsFor = descriptionOverlapsFor;
+exports.descriptionBudgetFor = descriptionBudgetFor;
+exports.scanAgents = scanAgents;
+exports.isManagedHookCommand = isManagedHookCommand;
+exports.preferCompiledHooksMessage = preferCompiledHooksMessage;
+exports.scanHooks = scanHooks;
+exports.frontmatterIssuesFor = frontmatterIssuesFor;
+exports.frontmatterValueIssuesFor = frontmatterValueIssuesFor;
+exports.malformedFrontmatterFor = malformedFrontmatterFor;
+exports.skillMetaIssuesFor = skillMetaIssuesFor;
+exports.collectSurfaceFindings = collectSurfaceFindings;
+exports.collectDelegationTrifecta = collectDelegationTrifecta;
+exports.collectHookBlockEntries = collectHookBlockEntries;
+exports.collectHookMatchers = collectHookMatchers;
+exports.summarizePurity = summarizePurity;
+/**
+ * scan-core — the PURE, NODE-FREE detector runtime behind `vigiles audit`.
+ *
+ * These are the deterministic surface detectors `scanPlugin` (disk, src/scan.ts)
+ * and `scanFiles` (browser, src/scan-files.ts) BOTH run — one detector, no drift.
+ * They were split out of `scan.ts` so the in-browser audit engine can import them
+ * WITHOUT dragging `scan.ts`'s node-only runtime deps (plugin-loader/crypto,
+ * core/mcp/child_process, test-coverage/glob, node:fs) into the bundle: every
+ * import below is node-free (path ops from the node-free `./posix-path.js`; all
+ * filesystem IO is INJECTED by the caller, never imported here). `scan.ts`
+ * re-exports everything here (`export *`) so its public surface is unchanged.
+ *
+ * The only edge back to `scan.ts` is TYPE-ONLY (the report shapes), elided at
+ * build, so there is no runtime cycle — `scan.ts` requires `scan-core.js`, never
+ * the reverse.
+ */
+const posix_path_js_1 = require("./posix-path.js");
+const tool_contract_js_1 = require("./core/tool-contract.js");
+const edit_distance_js_1 = require("./core/edit-distance.js");
+const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
+const description_overlap_js_1 = require("./core/description-overlap.js");
+const skill_description_budget_js_1 = require("./core/skill-description-budget.js");
+const mcp_tool_js_1 = require("./core/mcp-tool.js");
+const lethal_trifecta_js_1 = require("./core/lethal-trifecta.js");
+const skill_resources_js_1 = require("./core/skill-resources.js");
+const skill_missing_fence_js_1 = require("./core/skill-missing-fence.js");
+const delegation_trifecta_js_1 = require("./core/delegation-trifecta.js");
+const effects_js_1 = require("./core/effects.js");
+const agent_tools_js_1 = require("./adapters/claude-code/agent-tools.js");
+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 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;
+    // A subagent lives at the plugin's TOP-LEVEL `agents/` dir (e.g. `agents/foo.md`
+    // or `.claude/agents/foo.md`), never recursively under ANOTHER surface dir. Two
+    // real-world nesting traps are excluded as false positives:
+    //   - `skills/<x>/agents/…` — skill-internal worker docs (Anthropic's skill-creator)
+    //   - `commands/agents/…`   — a COMMAND namespaced `/agents:…` (ruvnet/claude-flow),
+    //     incl. a `README.md`; these are commands, not dispatchable subagents.
+    // Flagging either as a subagent missing frontmatter is a false positive (it
+    // mis-graded a real plugin F). A genuine top-level `agents/foo.md` still
+    // matches. Both excluded dirs are read from the layout (adapter-agnostic). See
+    // scan.test.ts for the regressions.
+    const nestedUnder = [
+        layout.skillDir &&
+            `${escapeRe(layout.skillDir)}/.+/${escapeRe(layout.agentDir)}/`,
+        layout.commandDir &&
+            `${escapeRe(layout.commandDir)}/(?:.+/)?${escapeRe(layout.agentDir)}/`,
+    ].filter((x) => Boolean(x));
+    const nestedAgentRe = layout.agentDir && nestedUnder.length
+        ? new RegExp(`(?:^|/)(?:${nestedUnder.join("|")})`)
+        : null;
+    const isAgent = (f) => (agentRe?.test(f) ?? false) &&
+        !f.endsWith(".spec.ts") &&
+        !(nestedAgentRe?.test(f) ?? false);
+    return {
+        isSkill: (f) => skillRe?.test(f) ?? false,
+        isAgent,
+        isCommand: (f) => commandRe?.test(f) ?? false,
+    };
+}
+function skillName(path) {
+    return (path
+        .replace(/\/SKILL\.md$/, "")
+        .split("/")
+        .pop() ?? path);
+}
+/**
+ * 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;
+}
+/** The body of a SKILL.md with the leading `---` frontmatter block stripped. */
+function skillBody(md) {
+    return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+}
+/**
+ * The on-disk path for a materialized file key. `loadPlugin` prefixes each
+ * surface file with the layout's `materializeRoot` (e.g. `.claude/`), but the file
+ * lives on disk WITHOUT that prefix (under the real surface dir), so a
+ * bundled-resource existence check must strip it back off. Mirrors how
+ * `resolveScript` resolves a hook path against the real plugin root.
+ */
+function onDiskPath(materializedKey, materializeRoot) {
+    if (!materializeRoot)
+        return materializedKey;
+    const prefix = `${materializeRoot}/`;
+    return materializedKey.startsWith(prefix)
+        ? materializedKey.slice(prefix.length)
+        : materializedKey;
+}
+function scanSkills(files, cls, ctx) {
+    const { root, materializeRoot, dialect, sharedDirs } = ctx;
+    // `sharedDirs` are declared relative to the REPO root (config location), which
+    // is `root` for a whole-repo scan but a PARENT when the scan is scoped to a
+    // subdir. Resolve them against that, not the scoped subdir.
+    const sharedDirsRoot = ctx.sharedDirsRoot ?? root;
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!cls.isSkill(path))
+            continue;
+        // Prefer the real on-disk dir (a `.claude/skills/…` skill materializes under
+        // the same canonical key as a repo-root one, but lives elsewhere on disk).
+        const onDiskDir = ctx.sources?.[path];
+        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);
+        const userInvoked = /^\s*disable-model-invocation:\s*true\s*$/m.test(md);
+        // Bundled-resource refs resolve against the skill's OWN dir (resources ship
+        // beside the SKILL.md), built from the plugin root + the file's ON-DISK dir
+        // (the materialize-root prefix the loader added is stripped back off).
+        const skillDir = onDiskDir
+            ? (0, posix_path_js_1.dirname)(onDiskDir)
+            : (0, posix_path_js_1.resolve)(root, (0, posix_path_js_1.dirname)(onDiskPath(path, materializeRoot)));
+        // Bundled refs resolve against the skill's OWN dir. A repo that shares a
+        // top-level tree across skills (`sharedDirs` in .vigilesrc.json) ALSO resolves
+        // a ref under one of those declared dirs against the repo root — OPT-IN, so a
+        // repo that doesn't set it is byte-identical to before (no masking of a real
+        // missing bundled resource). See feedback P1-4.
+        const resourceIssues = (0, skill_resources_js_1.skillResourceIssues)(skillBody(md), skillDir, {
+            repoRoot: sharedDirsRoot,
+            sharedDirs,
+            existsSync: ctx.existsSync,
+        });
+        // The lethal trifecta is a property of what a unit CAN do, which for a skill is
+        // its declared `allowed-tools` (the CC skill tool contract). Only a model-
+        // invocable skill can be hijacked by attacker content, so a user-invoked one is
+        // excluded. A skill with no `allowed-tools` line inherits all → advisory.
+        const skillTools = (0, agent_tools_js_1.parseAgentToolList)(md, "allowed-tools");
+        // No `allowed-tools:` line (null) → inherits all → wildcard sentinel; an
+        // EXPLICIT empty `[]` means zero tools → no trifecta (don't collapse them).
+        const trifecta = userInvoked
+            ? null
+            : (0, lethal_trifecta_js_1.lethalTrifectaIssues)(skillTools ?? ["*"], dialect);
+        out.push({
+            name: fm.name ?? skillName(path),
+            path,
+            hasDescription: Boolean(effectiveDesc && effectiveDesc.length >= 20),
+            description: effectiveDesc?.trim(),
+            userInvoked,
+            resourceIssues,
+            trifecta,
+            // A SKILL.md opening with `name:`/`description:` but no `---` fence loads
+            // as plain body → the skill is invisible. Inspect the RAW md (not the
+            // frontmatter-stripped body) so the unfenced keys are visible.
+            fenceIssue: (0, skill_missing_fence_js_1.skillMissingFence)(md),
+        });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * 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 modelInvocableSkillSurfaces(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 surfaces;
+}
+function descriptionOverlapsFor(files, cls) {
+    return (0, description_overlap_js_1.findDescriptionOverlaps)(modelInvocableSkillSurfaces(files, cls));
+}
+/**
+ * Model-invocable skills whose description is so long the trigger signal is
+ * buried (heuristic proxy; degrades recall + precision). Same surfaces as the
+ * overlap check. See skill-description-budget.ts.
+ */
+function descriptionBudgetFor(files, cls) {
+    return (0, skill_description_budget_js_1.findDescriptionBudgetIssues)(modelInvocableSkillSurfaces(files, cls));
+}
+function scanAgents(files, dialect, declaredServers, cls) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!cls.isAgent(path))
+            continue;
+        const tools = (0, agent_tools_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, posix_path_js_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_tools_js_1.parseAgentToolList)(md, "disallowedTools") ?? [], dialect),
+            purity: surface.purity,
+            effectBuckets: {
+                readOnly: surface.readOnly,
+                sideEffecting: surface.sideEffecting,
+                unknown: surface.unknown,
+            },
+            // The lethal trifecta: a subagent whose contract grants all three legs. An
+            // inherits-all agent (no `tools:` line → tools === null) is the advisory
+            // case — pass the wildcard sentinel so it's distinguished from an EXPLICIT
+            // empty `tools: []` (zero tools → no trifecta). One detector, no drift.
+            trifecta: (0, lethal_trifecta_js_1.lethalTrifectaIssues)(tools ?? ["*"], dialect),
+        });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve a hook script token to a checkable path. `loadPlugin` expands the
+ * 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, pluginRootToken, fullCommand, exists) {
+    // "${CLAUDE_PLUGIN_ROOT}" → unbraced "$CLAUDE_PLUGIN_ROOT".
+    const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
+    const cleaned = token
+        .replace(/["']/g, "")
+        .replaceAll(pluginRootToken, root)
+        .replaceAll(unbraced, root);
+    if (cleaned.includes("$"))
+        return { command: fullCommand, script: token, status: "unresolved" };
+    // 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, posix_path_js_1.isAbsolute)(cleaned) ? cleaned : (0, posix_path_js_1.resolve)(root, cleaned);
+    // Resolve the full command the same way we resolve the script token (expand
+    // plugin-root, strip outer quotes) so the CLI can pass it to verifyGuardrail.
+    const resolvedCommand = fullCommand
+        .replaceAll(pluginRootToken, root)
+        .replaceAll(unbraced, root);
+    return {
+        command: resolvedCommand,
+        script: cleaned,
+        status: exists(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)/;
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+function isManagedHookCommand(command) {
+    return /\bhook-runtime\b/.test(command);
+}
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+function preferCompiledHooksMessage(count) {
+    return (`${String(count)} hand-written hook command(s) — if any gate the agent ` +
+        `(a block/deny decision), compiled hooks (\`vigiles/hook\`) make whole hook ` +
+        `bug classes unrepresentable at authoring time, and \`guardrail-check\` proves ` +
+        `an existing one blocks. See docs/compiled-hooks.md.`);
+}
+/** Pull script-file hook commands out of the resolved settings; count inline ones. */
+/**
+ * Best-effort map of each script token → the hook EVENT it's registered under,
+ * by walking the canonical object-keyed-by-event settings shape
+ * (`{ PreToolUse: [{ hooks: [{ command }] }], … }`). Lets the safety battery
+ * scope itself to `PreToolUse` (the only event that can block a tool call), so a
+ * `SessionStart`/`PostToolUse`/`Stop` hook isn't tested against the disaster
+ * catalog. Returns an empty map for a non-object/array config (event → unknown).
+ */
+function eventsByScript(regs) {
+    const map = new Map();
+    for (const reg of regs) {
+        for (const tok of reg.command.match(SCRIPT_RE) ?? []) {
+            if (!map.has(tok))
+                map.set(tok, reg.event);
+        }
+    }
+    return map;
+}
+function scanHooks(regs, root, pluginRootToken, exists) {
+    const commands = regs.map((r) => r.command);
+    const evMap = eventsByScript(regs);
+    // A hand-written hook is any non-empty command that isn't a vigiles-managed
+    // (compiled) hook-runtime invocation — the basis for the prefer-compiled-hooks nudge.
+    const manual = commands.filter((c) => {
+        const u = c.trim();
+        return u !== "" && !isManagedHookCommand(u);
+    }).length;
+    const byScript = new Map();
+    let inline = 0;
+    for (const cmd of commands) {
+        const found = cmd.match(SCRIPT_RE);
+        if (!found || found.length === 0) {
+            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(cmd)) {
+            inline++;
+            continue;
+        }
+        for (const tok of found) {
+            const hook = resolveScript(tok, root, pluginRootToken, cmd, exists);
+            const event = evMap.get(tok);
+            byScript.set(hook.script, event ? { ...hook, event } : hook);
+        }
+    }
+    const hooks = [...byScript.values()].sort((a, b) => a.script.localeCompare(b.script));
+    return { hooks, inline, manual };
+}
+// ---------------------------------------------------------------------------
+// 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, edit_distance_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));
+}
+/**
+ * Flatten the per-surface lethal-trifecta + skill-resource findings into the
+ * path-tagged report lists the `audit` report AND the `lethal-trifecta` /
+ * `skill-resource-resolves` lint rules both consume (one detector, no drift).
+ */
+function collectSurfaceFindings(agents, skills) {
+    const trifectaFindings = [];
+    for (const a of agents) {
+        if (a.trifecta) {
+            trifectaFindings.push({
+                path: a.path,
+                kind: "subagent",
+                name: a.name,
+                finding: a.trifecta,
+            });
+        }
+    }
+    for (const s of skills) {
+        if (s.trifecta) {
+            trifectaFindings.push({
+                path: s.path,
+                kind: "skill",
+                name: s.name,
+                finding: s.trifecta,
+            });
+        }
+    }
+    const skillResourceFindings = skills.flatMap((s) => s.resourceIssues.map((finding) => ({
+        path: s.path,
+        name: s.name,
+        finding,
+    })));
+    const skillFenceFindings = skills.flatMap((s) => s.fenceIssue ? [{ path: s.path, name: s.name, finding: s.fenceIssue }] : []);
+    return { trifectaFindings, skillResourceFindings, skillFenceFindings };
+}
+/**
+ * Build the subagent delegation graph and flag a lethal trifecta that EMERGES
+ * across an edge (own ∪ delegated-to capability) though no single unit trips it.
+ *
+ * Edge source (deterministic, audit-available): a subagent that lists the `Task`
+ * tool can dispatch any sibling subagent, so it `delegatesTo` every OTHER agent.
+ * An inherits-all agent (`tools === null`) carries the wildcard, which the
+ * detector's FP-safe guard skips (that maximal-blast case is the per-unit
+ * advisory's job). One detector, no drift. (Richer edge sources — a typed
+ * railway's `delegate()` chain, a Flue subagent inheritance tree — plug in here.)
+ */
+function collectDelegationTrifecta(agents, dialect) {
+    const allNames = agents.map((a) => a.name);
+    const nodes = agents.map((a) => {
+        const canDispatch = a.tools === null ||
+            a.tools.some((t) => t === "Task" || t.startsWith("Task("));
+        return {
+            name: a.name,
+            kind: "agent",
+            tools: a.tools ?? ["*"],
+            delegatesTo: canDispatch ? allNames.filter((n) => n !== a.name) : [],
+        };
+    });
+    const pathByName = new Map(agents.map((a) => [a.name, a.path]));
+    return (0, delegation_trifecta_js_1.delegationTrifectaIssues)(nodes, dialect).map((finding) => ({
+        path: pathByName.get(finding.name) ?? "",
+        finding,
+    }));
+}
+/**
+ * Build `hookBlockIssues` entries by walking the canonical object-keyed-by-event
+ * settings shape PER REGISTRATION — so a script registered under several events
+ * is inspected under EACH (no de-dup by script path), inline one-liners are
+ * included (script token → null, inspect the command), and a script token is
+ * resolved to its ABSOLUTE on-disk path against the plugin root (not the caller's
+ * cwd). Addresses the gaps a de-duplicated `ScanHook[]` would miss.
+ */
+function collectHookBlockEntries(regs, root, pluginRootToken, exists) {
+    const out = [];
+    for (const { event, command: cmd } of regs) {
+        // A wrapper command runs MORE than one script (`node run.cjs guard.mjs`),
+        // so resolve EVERY candidate and inspect each — reading only the first
+        // (the wrapper) would miss the guard's block logic. Candidates: extensioned
+        // script tokens (SCRIPT_RE) PLUS path-like words with NO extension
+        // (`bash hooks/guard`, `${ROOT}/hooks/session-start`) that resolve to a file.
+        const candidates = new Set(cmd.match(SCRIPT_RE) ?? []);
+        for (const word of cmd.split(/\s+/)) {
+            const w = word.replace(/^["']+|["']+$/g, "");
+            if (w.startsWith("-"))
+                continue; // a flag, not a path
+            if (w.includes("/") || w.includes(pluginRootToken))
+                candidates.add(w);
+        }
+        const resolvedPaths = [];
+        for (const tok of candidates) {
+            const r = resolveScript(tok, root, pluginRootToken, cmd, exists);
+            if (r.status === "ok") {
+                const abs = (0, posix_path_js_1.isAbsolute)(r.script) ? r.script : (0, posix_path_js_1.resolve)(root, r.script);
+                if (!resolvedPaths.includes(abs))
+                    resolvedPaths.push(abs);
+            }
+        }
+        if (resolvedPaths.length > 0) {
+            // One entry per resolvable script (each is inspected on its own).
+            for (const sp of resolvedPaths) {
+                out.push({ event, command: cmd, scriptPath: sp });
+            }
+        }
+        else {
+            // No script file resolved → inline one-liner; inspect the command text.
+            out.push({ event, command: cmd, scriptPath: null });
+        }
+    }
+    return out;
+}
+/** Extract (event, matcher) pairs from the normalized hook registrations. */
+function collectHookMatchers(regs) {
+    const seen = new Set();
+    const out = [];
+    for (const { event, matcher } of regs) {
+        if (matcher === null)
+            continue;
+        const key = `${event}${matcher}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ event, matcher });
+    }
+    return out;
+}
+/** Tally how many scanned agents fall into each purity rung (effectSurface). */
+function summarizePurity(agents) {
+    return agents.reduce((acc, a) => {
+        acc[a.purity]++;
+        return acc;
+    }, { pure: 0, bounded: 0, unrestricted: 0 });
+}
+//# sourceMappingURL=scan-core.js.map