skills-doctor 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,7 +6,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
-*No changes yet.*
+## [0.4.0] - 2026-06-18
+
+### Added
+
+- Exposed the rule catalog as structured public API metadata.
+- Added opt-in `--fail-on` and `--min-score` scan quality gates for automation.
+- Included the agent-facing `skills/skills-doctor` wrapper in the npm package.
+- Added injectable resource and eval existence checks for `validateQualityRules`.
+- Added a public API and `schemaVersion: 1` report schema reference.
+- Tested the declared Node runtime floor in CI and aligned the package engine range to Node 22.13+.
+
+### Changed
+
+- Made non-interactive scans fail on ambiguous local/global or Claude/Codex root choices instead of scanning all detected roots.
+- Added bounded concurrent `SKILL.md` reads while preserving deterministic scan order.
+- Reused shared grouped-finding indexes for report summaries and grouped output.
+- Made the manual release checklist version-aware and aligned with tag-derived release notes.
+- Replaced the stale reusable CLI spec with a Skills Doctor-specific architecture map.
+
+### Fixed
+
+- Restored the documented `missing-skill` and `invalid-frontmatter` rule behavior so the structured rule catalog matches scanner findings.
+- Stopped trailing sentence punctuation from creating false missing-resource warnings for valid skill resource references.
+- Wrote repair handoff reports and prompts before stopping when no local `claude` or `codex` agent is available.
+- Recognized normal `--help` mentions when checking script help guidance.
+- Prevented long per-skill handoff report filenames from colliding after truncation.
+- Returned JSON error reports for parse-level CLI failures when `--json` is set.
+- Made the local `bun run dev` script execute the same CLI bin path used by packaged runs.
+- Rejected symlinked skill resource references that resolve outside the skill directory.
+- Preserved custom-root discovery diagnostics in scan reports when interactive scans add a missing custom skills path.
+- Reflected blocking diagnostic failures in scan scores so diagnostic-only failures no longer report a perfect score.
+- Reported unreadable direct-child `SKILL.md` entries as blocking diagnostics while continuing to scan other skills.
+- Kept repair handoff prompts available inline when writing `handoff-prompt.md` fails after report-directory creation.
+- Kept the release workflow on token-backed `bun publish` until npm trusted publishing is configured for the package.
+
+### Tests
+
+- Tightened rule-catalog synchronization coverage so docs-only, catalog-only, and emitted-rule drift fail together.
+- Covered script help guidance warnings for existing script references.
+- Added packaged CLI smoke coverage for JSON stdout and blocking-scan exit behavior.
+
+## [0.3.1] - 2026-06-16
+
+### Added
+
+- Added line numbers to quality-rule findings where a specific source line can be resolved.
+
+### Fixed
+
+- Hid repair handoff subset options that do not match any findings (for warning-only and advice-only scans).
+- Made CLI module import safe by removing side-effect execution and routing runtime entry through `bin/skills-doctor.js`.
 
 ## [0.3.0] - 2026-06-16
 

package/README.md

@@ -40,6 +40,8 @@ Use the `skills-doctor` skill when people ask for an agent workflow to:
 
 The CLI is the primary source of rule logic and output shape.
 The skill wrapper is a convenience entrypoint so agents can discover and invoke the same scanner from within skill workflows.
+When installed from npm, the wrapper is shipped at `node_modules/skills-doctor/skills/skills-doctor/SKILL.md`.
+Copy or reference that file from an agent skill directory when you want an agent to discover the workflow, but keep scans delegated to `bunx skills-doctor@latest` or the installed `skills-doctor` binary.
 
 ## What It Scans
 
@@ -59,8 +61,9 @@ to scan local project skills, global/root skills, or both. When both Claude and
 Codex/agents roots exist in the selected scope, it asks whether to scan Claude,
 Codex/agents, or both. If you already have standard roots detected, it also lets
 you add a custom skills directory path in the same interactive flow. Non-interactive
-runs use conservative defaults and fail with a clear user error when a required
-choice cannot be made.
+runs scan only a single unambiguous detected root. If multiple local/global
+scopes or multiple ecosystems are detected, they fail with a clear user error
+instead of guessing.
 
 ## What It Checks
 
@@ -77,15 +80,17 @@ the Agent Skills standards from <https://agentskills.io/home>, including:
 - divergent same-name skills across Claude and Codex/agents roots
 
 See `docs/RULES.md` for a full rule catalog, severity, and intended rationale.
+Programmatic consumers can import `ruleCatalog` for the same metadata as structured data.
 
 Findings are grouped as blocking errors, warnings, and advisory improvements.
 The human summary opens with a score header showing a face, `0` to `100` score,
 label, and proportional terminal bar. The score starts at 100 and deducts 1.5
 points for each distinct error rule and 0.75 points for each distinct warning
-rule; repeated findings from the same rule do not increase the penalty. Advisory
-findings are counted in the report but do not affect the score. Score labels are
-`Great` for 75 or higher, `Needs work` for 50 through 74, and `Critical` below
-50.
+rule; each distinct blocking diagnostic code is scored like an error rule.
+Repeated findings from the same rule do not increase the penalty. Advisory
+findings and warning diagnostics are counted in the report but do not affect the
+score. Score labels are `Great` for 75 or higher, `Needs work` for 50 through
+74, and `Critical` below 50.
 
 ## Interactive Repair Flow
 
@@ -119,10 +124,14 @@ Use JSON output for automation:
 skills-doctor --json
 skills-doctor --json --json-compact
 skills-doctor --yes --json
+skills-doctor --yes --json --fail-on warning
+skills-doctor --yes --json --min-score 95
 ```
 
 JSON mode writes one machine-readable report to stdout and suppresses prompts
 and spinners. Human logs and expected errors stay out of stdout.
+By default, the exit code fails only for blocking errors and error diagnostics.
+Use `--fail-on warning`, `--fail-on advice`, or `--min-score <number>` for stricter CI gates.
 
 ## Programmatic API
 
@@ -143,6 +152,7 @@ const report = buildScanReport({
 ```
 
 The CLI remains the primary interface for interactive repair workflows.
+See `docs/API.md` for supported exports and the `schemaVersion: 1` report schema.
 
 ## Exit Codes
 
@@ -162,15 +172,21 @@ agent then follows its own configuration.
 Before tagging a release:
 
 ```bash
+VERSION=<x.y.z>
 bun run verify
 bun run pack:dry-run
-node scripts/extract-release-notes.mjs 0.1.0
+node scripts/extract-release-notes.mjs "$VERSION"
 ```
 
 Then:
 
 1. Update `package.json` version.
 2. Move changelog entries from `Unreleased` into `## [x.y.z] - YYYY-MM-DD`.
-3. Commit the release prep.
-4. Tag `v<x.y.z>`.
-5. Push the tag to trigger the release workflow.
+3. Confirm `node scripts/extract-release-notes.mjs "$VERSION"` prints the intended notes.
+4. Commit the release prep.
+5. Tag `v<x.y.z>`.
+6. Ensure the `NPM_TOKEN` repository secret can publish the npm package.
+7. Push the tag to trigger the release workflow.
+
+The release workflow derives the same version from the pushed tag with
+`node scripts/extract-release-notes.mjs "${GITHUB_REF_NAME#v}"`.

package/bin/skills-doctor.js

@@ -10,4 +10,5 @@ if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
   }
 }
 
-await import("../dist/cli/index.js");
+const { runCli } = await import("../dist/cli/index.js");
+await runCli();

package/dist/cli/commands/scan.d.ts

@@ -6,6 +6,8 @@ export type ScanFlags = {
     readonly json?: boolean;
     readonly jsonCompact?: boolean;
     readonly yes?: boolean;
+    readonly failOn?: string | undefined;
+    readonly minScore?: string | undefined;
 };
 export type ScanActionOptions = {
     readonly cwd?: string;

package/dist/cli/commands/scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/scan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAU/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM5F,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;CAC5C,CAAC;AAMF,eAAO,MAAM,UAAU,GACrB,WAAW,MAAM,EACjB,OAAO,SAAS,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,UAAU,CAsGpB,CAAC"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/scan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAgB/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM5F,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;CAC5C,CAAC;AAUF,eAAO,MAAM,UAAU,GACrB,WAAW,MAAM,EACjB,OAAO,SAAS,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,UAAU,CAkHpB,CAAC"}

package/dist/cli/commands/scan.js

@@ -2,8 +2,9 @@ import path from "node:path";
 import { buildScanReport } from "../../domain/build-report.js";
 import { compareFindings, renderPostHandoffSummary } from "../../domain/compare-findings.js";
 import { discoverSkillRoots } from "../../domain/discover-skill-roots.js";
+import { groupFindingsByKey } from "../../domain/group-findings.js";
 import { scanSkillRoots } from "../../domain/scan-skills.js";
-import { renderHumanSummary, resolveScanExitCode } from "../../domain/summarize-findings.js";
+import { renderHumanSummary, resolveScanExitCode, } from "../../domain/summarize-findings.js";
 import { CliInputError } from "../utils/handle-error.js";
 import { prepareRepairHandoff } from "../utils/handoff-to-agent.js";
 import { enableJsonMode, writeJsonReport } from "../utils/json-mode.js";
@@ -14,6 +15,7 @@ import { shouldSkipPrompts } from "../utils/should-skip-prompts.js";
 import { createSpinner } from "../utils/spinner.js";
 export const scanAction = async (directory, flags, options = {}) => {
     const cwd = path.resolve(options.cwd ?? process.cwd(), directory);
+    const gateOptions = resolveGateOptions(flags);
     const prompts = options.prompts ?? inquirerPromptAdapter;
     const writeStdout = options.writeStdout ?? ((message) => process.stdout.write(message));
     const writeStderr = options.writeStderr ?? ((message) => process.stderr.write(message));
@@ -35,36 +37,46 @@ export const scanAction = async (directory, flags, options = {}) => {
     }
     const discovered = await spinner.run("Finding local skill roots...", () => discoverSkillRoots({ cwd, homeDir: options.homeDir }));
     let roots = discovered.roots;
+    const diagnostics = [...discovered.diagnostics];
     if (roots.length === 0) {
         if (skipPrompts) {
             throw new CliInputError("No .claude/skills or .agents/skills root was found. Re-run interactively or add a supported skills root.");
         }
-        roots = await selectCustomRoot({
+        const selection = await selectCustomRoot({
             cwd,
             homeDir: options.homeDir,
             prompts,
             roots,
         });
+        roots = selection.roots;
+        diagnostics.push(...selection.diagnostics);
+    }
+    else if (skipPrompts) {
+        assertNonInteractiveRootSelectionIsUnambiguous(roots);
     }
     else if (!skipPrompts) {
-        roots = await selectRootScopes({
+        const scopeSelection = await selectRootScopes({
             roots,
             prompts,
             cwd,
             homeDir: options.homeDir,
         });
-        roots = await selectRoots({
+        roots = scopeSelection.roots;
+        diagnostics.push(...scopeSelection.diagnostics);
+        const rootSelection = await selectRoots({
             roots,
             prompts,
             cwd,
             homeDir: options.homeDir,
         });
+        roots = rootSelection.roots;
+        diagnostics.push(...rootSelection.diagnostics);
     }
     if (roots.length === 0) {
         throw new CliInputError("No readable skills root was selected.");
     }
     const startedAt = now();
-    const scan = await spinner.run("Scanning skills...", () => scanSkillRoots({ roots }));
+    const scan = await spinner.run("Scanning skills...", () => scanSkillRoots({ roots, diagnostics }));
     const elapsedMilliseconds = Math.max(0, Math.round(now() - startedAt));
     const report = buildScanReport({
         version: options.version ?? "0.0.0",
@@ -102,9 +114,40 @@ export const scanAction = async (directory, flags, options = {}) => {
                 })) ?? report;
         }
     }
-    process.exitCode = resolveScanExitCode(finalReport);
+    process.exitCode = resolveScanExitCode(finalReport, gateOptions);
     return finalReport;
 };
+const resolveGateOptions = (flags) => ({
+    failOn: parseFailOnSeverity(flags.failOn),
+    minScore: parseMinScore(flags.minScore),
+});
+const parseFailOnSeverity = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (value === "error" || value === "warning" || value === "advice")
+        return value;
+    throw new CliInputError("Invalid --fail-on value. Use one of: error, warning, advice.");
+};
+const parseMinScore = (value) => {
+    if (value === undefined)
+        return undefined;
+    const score = Number(value);
+    if (!Number.isFinite(score) || score < 0 || score > 100) {
+        throw new CliInputError("Invalid --min-score value. Use a number from 0 to 100.");
+    }
+    return score;
+};
+const assertNonInteractiveRootSelectionIsUnambiguous = (roots) => {
+    const standardRoots = roots.filter((root) => root.source !== "custom");
+    const standardSources = new Set(standardRoots.map((root) => root.source));
+    if (standardSources.has("local") && standardSources.has("global")) {
+        throw new CliInputError("Multiple local and global skills roots were found. Re-run interactively to choose which scope to scan.");
+    }
+    const standardEcosystems = new Set(standardRoots.map((root) => root.ecosystem));
+    if (standardEcosystems.has("claude") && standardEcosystems.has("codex")) {
+        throw new CliInputError("Multiple Claude and Codex/agents skills roots were found. Re-run interactively to choose which ecosystem to scan.");
+    }
+};
 const selectRoots = async (input) => {
     const { prompts, cwd, homeDir, roots } = input;
     const customRoots = roots.filter((root) => root.source === "custom");
@@ -112,7 +155,7 @@ const selectRoots = async (input) => {
     const hasClaude = standardRoots.some((root) => root.ecosystem === "claude");
     const hasCodex = standardRoots.some((root) => root.ecosystem === "codex");
     if (!hasClaude || !hasCodex)
-        return roots;
+        return { roots, diagnostics: [] };
     const selection = await prompts.select("Choose skills folder to scan", [
         { name: "Both", value: "all" },
         { name: "Claude (.claude/skills)", value: "claude" },
@@ -120,7 +163,7 @@ const selectRoots = async (input) => {
         { name: "Add custom skills path", value: "custom" },
     ]);
     if (selection === "all")
-        return roots;
+        return { roots, diagnostics: [] };
     if (selection === "custom") {
         return selectCustomRoot({
             cwd,
@@ -129,7 +172,10 @@ const selectRoots = async (input) => {
             roots,
         });
     }
-    return [...standardRoots.filter((root) => root.ecosystem === selection), ...customRoots];
+    return {
+        roots: [...standardRoots.filter((root) => root.ecosystem === selection), ...customRoots],
+        diagnostics: [],
+    };
 };
 const selectRootScopes = async (input) => {
     const { prompts, cwd, homeDir, roots } = input;
@@ -137,7 +183,7 @@ const selectRootScopes = async (input) => {
     const hasGlobal = roots.some((root) => root.source === "global");
     const hasBothScopes = hasLocal && hasGlobal;
     if (!hasLocal && !hasGlobal)
-        return roots;
+        return { roots, diagnostics: [] };
     const allLabel = hasBothScopes
         ? "Both local project and global/root skills"
         : "Detected skills root";
@@ -156,7 +202,7 @@ const selectRootScopes = async (input) => {
     }
     choices.push({ name: "Add custom skills path", value: "custom" });
     if (choices.length <= 1) {
-        return roots;
+        return { roots, diagnostics: [] };
     }
     const selection = await prompts.select("Choose skills scope to scan", choices);
     if (selection === "custom") {
@@ -168,17 +214,17 @@ const selectRootScopes = async (input) => {
         });
     }
     if (selection === "all")
-        return roots;
+        return { roots, diagnostics: [] };
     if (selection === "claude") {
-        return roots.filter((root) => root.ecosystem === "claude");
+        return { roots: roots.filter((root) => root.ecosystem === "claude"), diagnostics: [] };
     }
     if (selection === "codex") {
-        return roots.filter((root) => root.ecosystem === "codex");
+        return { roots: roots.filter((root) => root.ecosystem === "codex"), diagnostics: [] };
     }
     if (selection === "local" || selection === "global") {
-        return roots.filter((root) => root.source === selection);
+        return { roots: roots.filter((root) => root.source === selection), diagnostics: [] };
     }
-    return roots;
+    return { roots, diagnostics: [] };
 };
 const selectCustomRoot = async (input) => {
     const customRoot = await input.prompts.input("Skills directory path", ".");
@@ -187,7 +233,10 @@ const selectCustomRoot = async (input) => {
         homeDir: input.homeDir,
         customRoots: [{ rootPath: customRoot, ecosystem: "custom" }],
     });
-    return mergeRoots(input.roots, custom.roots);
+    return {
+        roots: mergeRoots(input.roots, custom.roots),
+        diagnostics: custom.diagnostics,
+    };
 };
 const mergeRoots = (existingRoots, additionalRoots) => {
     const merged = new Map();
@@ -228,34 +277,35 @@ const reviewFindings = async (report, input) => {
 };
 const runRepairAgentFlow = async (report, input) => {
     try {
-        const agent = await chooseRepairAgent({
-            prompts: input.prompts,
-            isAvailable: input.isRepairAgentAvailable,
-        });
-        if (agent === undefined) {
-            input.write("Repair handoff cancelled.\n");
-            return undefined;
-        }
         const handoff = await prepareRepairHandoff({
             report,
             prompts: input.prompts,
             outputRoot: input.repairReportOutputRoot,
             timestamp: input.repairReportTimestamp,
         });
-        input.write(`Selected ${agent.displayName}.\n`);
-        input.write(`Launch preview: ${formatRepairAgentPreview(agent.id)}\n`);
-        if (handoff.reportDirectory !== undefined) {
-            input.write(`Report directory: ${handoff.reportDirectory}\n`);
-        }
-        if (handoff.promptPath !== undefined) {
-            input.write(`Repair prompt: ${handoff.promptPath}\n`);
+        let agent;
+        try {
+            agent = await chooseRepairAgent({
+                prompts: input.prompts,
+                isAvailable: input.isRepairAgentAvailable,
+            });
         }
-        else {
-            input.write(`Repair prompt:\n${handoff.prompt}\n`);
+        catch (error) {
+            if (error instanceof CliInputError) {
+                writeRepairHandoffSummary(handoff, input.write);
+                input.write(`${error.message}\n`);
+                return undefined;
+            }
+            throw error;
         }
-        if (handoff.reportWriteError !== undefined) {
-            input.write(`Report write failed: ${handoff.reportWriteError.message}\n`);
+        if (agent === undefined) {
+            writeRepairHandoffSummary(handoff, input.write);
+            input.write("Repair handoff cancelled.\n");
+            return undefined;
         }
+        input.write(`Selected ${agent.displayName}.\n`);
+        input.write(`Launch preview: ${formatRepairAgentPreview(agent.id)}\n`);
+        writeRepairHandoffSummary(handoff, input.write);
         const shouldLaunch = await input.prompts.confirm(`Launch ${agent.displayName} now?`, false);
         if (!shouldLaunch) {
             input.write("Agent launch cancelled.\n");
@@ -301,19 +351,28 @@ const runRepairAgentFlow = async (report, input) => {
         throw error;
     }
 };
+const writeRepairHandoffSummary = (handoff, write) => {
+    if (handoff.reportDirectory !== undefined) {
+        write(`Report directory: ${handoff.reportDirectory}\n`);
+    }
+    if (handoff.promptPath !== undefined) {
+        write(`Repair prompt: ${handoff.promptPath}\n`);
+    }
+    else {
+        write(`Repair prompt:\n${handoff.prompt}\n`);
+    }
+    if (handoff.reportWriteError !== undefined) {
+        write(`Report write failed: ${handoff.reportWriteError.message}\n`);
+    }
+};
 const renderFindings = (findings) => `${findings
     .map((finding) => `[${finding.severity}] ${finding.ruleId} ${finding.skillName ?? finding.skillPath}\n${finding.message}\nSuggestion: ${finding.suggestion}`)
     .join("\n\n")}\n`;
 const renderFindingsBySkill = (findings) => {
-    const groups = new Map();
-    for (const finding of findings) {
-        const key = finding.skillName ?? finding.skillPath;
-        groups.set(key, [...(groups.get(key) ?? []), finding]);
-    }
-    return [...groups.entries()]
-        .map(([skillName, skillFindings]) => {
-        const lines = [`${skillName}:`];
-        lines.push(...skillFindings.map((finding) => `- [${finding.severity}] ${finding.ruleId}`));
+    return groupFindingsByKey(findings, (finding) => finding.skillName ?? finding.skillPath)
+        .map((group) => {
+        const lines = [`${group.key}:`];
+        lines.push(...group.findings.map((finding) => `- [${finding.severity}] ${finding.ruleId}`));
         return lines.join("\n");
     })
         .join("\n\n")

package/dist/cli/index.d.ts

@@ -1,4 +1,8 @@
 import { Command } from "commander";
-export declare const buildProgram: () => Command;
+export type BuildProgramOptions = {
+    readonly jsonMode?: boolean;
+};
+export declare const buildProgram: (options?: BuildProgramOptions) => Command;
 export declare const main: (argv?: readonly string[]) => Promise<void>;
+export declare const runCli: (argv?: readonly string[]) => Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,eAAO,MAAM,YAAY,QAAO,OAmB/B,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAAiB,KAAG,OAAO,CAAC,IAAI,CAY/E,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,UAAS,mBAAwB,KAAG,OAkChE,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAAiB,KAAG,OAAO,CAAC,IAAI,CAiB/E,CAAC;AAEF,eAAO,MAAM,MAAM,GAAU,OAAM,SAAS,MAAM,EAAiB,KAAG,OAAO,CAAC,IAAI,CAEjF,CAAC"}

package/dist/cli/index.js

@@ -1,8 +1,10 @@
+import path from "node:path";
 import { Command } from "commander";
 import packageJson from "../../package.json" with { type: "json" };
 import { scanAction } from "./commands/scan.js";
 import { handleCliError } from "./utils/handle-error.js";
-export const buildProgram = () => {
+import { enableJsonMode } from "./utils/json-mode.js";
+export const buildProgram = (options = {}) => {
     const program = new Command()
         .name("skills-doctor")
         .description("Scan Agent Skills and report quality issues.")
@@ -10,13 +12,25 @@ export const buildProgram = () => {
         .argument("[directory]", "directory to scan from", ".")
         .option("--json", "output one machine-readable JSON report")
         .option("--json-compact", "with --json, omit indentation")
+        .option("--fail-on <severity>", "fail on findings at or above severity: error, warning, advice")
+        .option("--min-score <number>", "fail when the scan score is below this threshold")
         .option("-y, --yes", "skip prompts and use conservative defaults")
         .action(async (directory, flags) => {
         await scanAction(directory, flags);
     });
+    if (options.jsonMode) {
+        program.exitOverride();
+        program.configureOutput({
+            writeErr: () => { },
+        });
+    }
     return program;
 };
 export const main = async (argv = process.argv) => {
+    const preParseJsonMode = resolvePreParseJsonMode(argv);
+    if (preParseJsonMode !== undefined) {
+        enableJsonMode(preParseJsonMode);
+    }
     process.on("SIGINT", () => process.exit(130));
     process.on("SIGTERM", () => process.exit(143));
     process.stdout.on("error", (error) => {
@@ -24,10 +38,31 @@ export const main = async (argv = process.argv) => {
             process.exit(0);
     });
     try {
-        await buildProgram().parseAsync([...argv]);
+        await buildProgram({ jsonMode: preParseJsonMode !== undefined }).parseAsync([...argv]);
     }
     finally {
         process.stdin.unref?.();
     }
 };
-main().catch(handleCliError);
+export const runCli = async (argv = process.argv) => {
+    await main(argv).catch(handleCliError);
+};
+const resolvePreParseJsonMode = (argv) => {
+    const userArgs = argv.slice(2);
+    if (!userArgs.includes("--json"))
+        return undefined;
+    return {
+        compact: userArgs.includes("--json-compact"),
+        directory: path.resolve(process.cwd(), findDirectoryArg(userArgs) ?? "."),
+    };
+};
+const findDirectoryArg = (args) => args.find((arg, index) => isDirectoryArg(args, arg, index));
+const VALUE_FLAGS = new Set(["--fail-on", "--min-score"]);
+const isDirectoryArg = (args, arg, index) => {
+    if (arg === "--")
+        return false;
+    if (arg.startsWith("-"))
+        return false;
+    const previous = args[index - 1];
+    return previous === undefined || !VALUE_FLAGS.has(previous);
+};

package/dist/cli/utils/handoff-to-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handoff-to-agent.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/handoff-to-agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAKrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,qBAAqB,GAAG,KAAK,GAAG,iBAAiB,CAAC;AAE/F,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,sBAAsB,GAAG,SAAS,CAAC;CACrE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,OAAO,yBAAyB,KAC/B,OAAO,CAAC,qBAAqB,CAgC/B,CAAC"}
+{"version":3,"file":"handoff-to-agent.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/handoff-to-agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAKrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,qBAAqB,GAAG,KAAK,GAAG,iBAAiB,CAAC;AAE/F,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,sBAAsB,GAAG,SAAS,CAAC;CACrE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,OAAO,yBAAyB,KAC/B,OAAO,CAAC,qBAAqB,CAsC/B,CAAC"}

package/dist/cli/utils/handoff-to-agent.js

@@ -21,25 +21,40 @@ export const prepareRepairHandoff = async (input) => {
         reportDirectory: reportResult.result?.directory,
     });
     let promptPath;
+    let promptWriteError;
     if (reportResult.result !== undefined) {
-        promptPath = path.join(reportResult.result.directory, "handoff-prompt.md");
-        await writeFile(promptPath, `${prompt}\n`);
+        const targetPromptPath = path.join(reportResult.result.directory, "handoff-prompt.md");
+        try {
+            await writeFile(targetPromptPath, `${prompt}\n`);
+            promptPath = targetPromptPath;
+        }
+        catch (error) {
+            promptWriteError = normalizeError(error);
+        }
     }
     return {
         findings,
         prompt,
         reportDirectory: reportResult.result?.directory,
         promptPath,
-        reportWriteError: reportResult.error,
+        reportWriteError: reportResult.error ?? promptWriteError,
     };
 };
 const chooseRepairFindings = async (report, prompts) => {
-    const subset = await prompts.select("Choose findings to repair", [
-        { name: "Blocking errors only", value: "errors" },
-        { name: "Blocking errors and warnings", value: "errors-and-warnings" },
-        { name: "All findings", value: "all" },
-        { name: "Selected skills", value: "selected-skills" },
-    ]);
+    const choices = [];
+    if (report.errorCount > 0) {
+        choices.push({ name: "Blocking errors only", value: "errors" });
+    }
+    if (report.errorCount + report.warningCount > 0) {
+        choices.push({ name: "Blocking errors and warnings", value: "errors-and-warnings" });
+    }
+    if (report.findingCount > 0) {
+        choices.push({ name: "All findings", value: "all" });
+    }
+    if (report.skills.some((skill) => skill.findingCount > 0)) {
+        choices.push({ name: "Selected skills", value: "selected-skills" });
+    }
+    const subset = await prompts.select("Choose findings to repair", choices);
     if (subset === "errors") {
         return report.findings.filter((finding) => finding.severity === "error");
     }
@@ -74,6 +89,7 @@ const tryWriteFindingsDirectory = async (input) => {
         };
     }
     catch (error) {
-        return { error: error instanceof Error ? error : new Error(String(error)) };
+        return { error: normalizeError(error) };
     }
 };
+const normalizeError = (error) => error instanceof Error ? error : new Error(String(error));

package/dist/domain/build-handoff-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-handoff-prompt.d.ts","sourceRoot":"","sources":["../../src/domain/build-handoff-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,YAAY,CAAC;AAKrD,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,OAAO,uBAAuB,KAAG,MAmEnE,CAAC"}
+{"version":3,"file":"build-handoff-prompt.d.ts","sourceRoot":"","sources":["../../src/domain/build-handoff-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,YAAY,CAAC;AAKrD,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,OAAO,uBAAuB,KAAG,MAmEnE,CAAC"}

package/dist/domain/build-handoff-prompt.js

@@ -1,3 +1,4 @@
+import { groupFindingsByKey } from "./group-findings.js";
 const MAX_INLINE_GROUPS = 5;
 const MAX_INLINE_FINDINGS_PER_GROUP = 3;
 export const buildHandoffPrompt = (input) => {
@@ -38,15 +39,11 @@ export const buildHandoffPrompt = (input) => {
 };
 const formatRoots = (roots) => roots.map((root) => `${root.ecosystem}: ${root.rootPath}`).join("; ");
 const groupFindingsBySkill = (findings) => {
-    const groups = new Map();
-    for (const finding of findings) {
-        groups.set(finding.skillPath, [...(groups.get(finding.skillPath) ?? []), finding]);
-    }
-    return [...groups.entries()]
-        .map(([skillPath, skillFindings]) => ({
-        skillPath,
-        skillLabel: skillFindings[0]?.skillName ?? skillPath,
-        findings: sortFindings(skillFindings),
+    return groupFindingsByKey(findings, (finding) => finding.skillPath)
+        .map((group) => ({
+        skillPath: group.key,
+        skillLabel: group.findings[0]?.skillName ?? group.key,
+        findings: sortFindings(group.findings),
     }))
         .sort((left, right) => severityScore(right.findings[0]) - severityScore(left.findings[0]) ||
         right.findings.length - left.findings.length ||