skills-doctor 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,63 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-04
+
+### Added
+
+- Added past-30-day detected usage counts to usage summaries and the unused-skill cleanup picker.
+- Added scoped bulk agent handoffs for selected usage recommendation groups.
+- Added `b back` navigation to nested interactive checkbox selectors and select-based submenus with a `Back to main menu` choice.
+- Added severity bucket selection to security repair handoffs so users can select Critical, High, Medium, or Review findings in bulk while still selecting individual findings.
+- Added security review incident grouping for human output while preserving raw security findings in JSON reports.
+- Added security priority and capability aggregate counts to JSON reports, plus `--fail-on-security` for stricter P1/P2 security gates.
+- Added P2 security hygiene rules for missing boundaries, missing human approval, ambiguous authority, unpinned tools, hidden artifacts, and large context bait.
+- Added P1 high-risk security rules for broad tool grants, missing denylists, broad implicit invocation, external dependencies, cross-modal mismatch, self-modifying skills, MCP exposure, and MCP OAuth scope excess.
+- Added P0 security priorities and spec-aligned `SKILL001_*` through `SKILL008_*` rule IDs for blocker security detections.
+- Added derived security capability facts for package artifacts, including secret access, network egress, remote execution, persistence, approval bypass, destructive actions, broad tools, MCP access, and obfuscation indicators.
+- Added package artifact discovery metadata to scan results, including script/resource/config files and symlink status.
+- Added package security model types for future artifact, capability, priority, and cross-file evidence reporting.
+- Added a full-screen interactive TTY dashboard with scan progress, usage metrics, cleanup candidates, and keyboard-driven next-step actions.
+- Added a public security-rule validator API surface for future malicious skill detection rules.
+
+### Changed
+
+- Replaced the TUI dashboard completion progress strip with a scan score panel showing the score, label, penalty, and contributing rule counts.
+- Reformatted interactive security review output into severity and category summary tables plus a compact incident table with user-facing Critical/High/Medium labels instead of P-code prose dumps.
+- Made the TUI dashboard adaptive across terminal widths, with percentage progress, a package-version brand card, a security findings metric, and responsive metric wrapping.
+- Human security review output now groups related rule hits into concise incidents and omits rationale/counterevidence noise by default.
+- P0 security findings now fail scan exit-code gates by default.
+- P2 security hygiene findings now contribute to scan score while remaining separate from default severity-based exit gates.
+- Security validation now evaluates package records and can report risky non-`SKILL.md` artifacts while preserving the existing `validateSecurityRules()` API.
+- Added confidence, rationale, and counterevidence metadata to security findings in JSON and human reports.
+- Replaced the plain interactive review prompt with a painted ANSI dashboard while preserving JSON, non-interactive, and injected-prompt output paths.
+- Separated security findings from quality issue counts, scoring, and default exit gates.
+- Added source excerpts to security findings and a per-finding security repair selection flow.
+
+### Fixed
+
+- Kept the TUI dashboard repainting on terminal resize and preserved the version brand card on medium-width terminal windows without line overruns.
+- Passed the package version into interactive scan reports so the TUI brand card no longer falls back to a hard-coded version.
+- Enforced non-empty compatibility metadata, string-only metadata maps, and deterministic checks for interactive or unsafe referenced scripts.
+- Reported package-level secret reads and persistence capabilities as their required P0 security findings, and included both secret and network evidence in package exfiltration chains.
+- Reduced prompt-injection false positives for ask-first admin flows and verified confirmation-skip CLI examples.
+- Reduced exfiltration-rule false positives for webhook troubleshooting table rows and notification webhook destinations.
+- Reduced exfiltration-rule false positives for webhook signing-secret setup and official API bearer-token examples while preserving arbitrary external secret-transfer findings.
+- Suppressed prompt-injection false positives for defensive guidance about untrusted content, refusals, secret handling, signatures, and confirmations.
+- Reduced false-positive remote-execution warnings for remote specs piped into local Node or shell parser scripts.
+- Reduced false-positive remote-execution warnings for skills that fetch remote docs or specs for static parsing without executing the fetched content.
+- Suppressed the reported real-world false positives for defensive untrusted-content handling and explicit public-issue confirmation guidance.
+- Made `bun run dev` rebuild ignored `dist/` output before launching the packaged bin so local CLI runs reflect source changes.
+
+### Security
+
+- Added package-level MCP, denylist, external-dependency, self-modification, and cross-modal mismatch checks with P1 priority evidence chains.
+- Added standalone local secret-access and persistence-installation blocker detections, including path-like sources such as `~/.ssh`, `.aws`, and shell startup files.
+- Surfaced security findings in the interactive CLI summary and review menu.
+- Integrated security findings into normal skill scans and report exit-code behavior.
+- Added deterministic detection for remote execution, safety-disablement, destructive, and obfuscated command patterns in skill files.
+- Added deterministic detection for instruction-subversion and secret-exfiltration patterns in skill files.
+
 ## [0.5.2] - 2026-06-20
 
 ### Added

package/README.md

@@ -8,6 +8,9 @@ findings-specific repair prompt to `claude` or `codex`.
 It can also analyze local Codex usage traces to surface unused skills and
 skills context-budget pressure before handing a cleanup prompt to a local agent.
 
+> ★ If Skills Doctor helps you clean up or harden your agent skills, please
+> [star the repo on GitHub](https://github.com/ametel01/skills-doctor).
+
 ## Install And Run
 
 From a repository that contains project-local skills, or from anywhere when you
@@ -67,6 +70,11 @@ 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.
 
+For each skill package, security scanning also classifies `SKILL.md`,
+`scripts/**`, `references/**`, `assets/**`, agent/MCP/Claude config files,
+hooks, package manifests, shell scripts, Dockerfiles, CI files, hidden files,
+executable artifacts, and symlink metadata.
+
 ## What It Checks
 
 The scanner validates skills against `docs/SKILLS_SPEC.md`, which consolidates
@@ -80,11 +88,26 @@ the Agent Skills standards from <https://agentskills.io/home>, including:
 - script guidance that is non-interactive and reproducible
 - eval guidance for non-trivial skills
 - divergent same-name skills across Claude and Codex/agents roots
+- suspicious security patterns across the skill package, including prompt
+  override, permission bypass, secret access, exfiltration chains, destructive
+  commands, persistence, remote execution, obfuscation, broad tools, missing
+  denylists, external dependencies, MCP exposure, self-modification, hidden
+  artifacts, and large context bait
 
 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.
+Security findings are deterministic heuristic findings about suspicious
+instructions or capabilities such as `reads_secrets`, `network_egress`,
+`remote_code_exec`, `persistence`, `bypasses_approval`, or `mcp_access`; they
+are not proof that a skill author intended harm.
+
+Quality findings are grouped as blocking errors, warnings, and advisory improvements.
+Security findings stay rule-by-rule in JSON, but human output groups related
+signals into review incidents so a secret read, network transfer, missing
+denylist, and cross-modal mismatch can be reviewed as one issue. Incident cards
+show the primary risk, source excerpt, priority, related rule IDs, and
+capabilities; detailed rationale and counterevidence remain available in JSON
+and repair report files.
 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
@@ -103,17 +126,23 @@ available, reads local Codex usage traces from known `~/.codex` paths. It can:
 2. Show usage ranking and cleanup recommendations when usage analysis ran.
 3. Let you choose a repair subset: errors, errors plus warnings, all findings,
    or selected skills.
-4. Detect local `claude` and `codex` executables.
-5. Write a full report under the OS temp directory, for example
+4. Let you launch a scoped agent handoff for a selected usage recommendation
+   group, such as disable candidates or context-heavy descriptions.
+5. Detect local `claude` and `codex` executables.
+6. Write a full report under the OS temp directory, for example
    `/tmp/skills-doctor-<uid>/reports/<timestamp>/` on Linux.
-6. Generate a compact `handoff-prompt.md` tailored to the selected findings or
+7. Generate a compact `handoff-prompt.md` tailored to the selected findings or
    `cleanup-prompt.md` tailored to usage cleanup.
-7. Preview the launch command.
-8. Ask for explicit confirmation before handing the terminal to the selected
+8. Preview the launch command.
+9. Ask for explicit confirmation before handing the terminal to the selected
    agent.
-9. Re-scan the same roots after the agent exits and report changed findings or
+10. Re-scan the same roots after the agent exits and report changed findings or
    cleanup summary details.
 
+Nested repair and cleanup selection menus let you return to the next-step
+chooser without launching an agent. Checkbox prompts show `b back` in the footer
+next to the normal navigation keys.
+
 Launch mappings:
 
 - Claude: `claude --dangerously-skip-permissions <prompt>`
@@ -123,10 +152,12 @@ Skills Doctor does not edit skill files during the scan phase. Repairs are made
 only by the local agent after you confirm the handoff.
 
 Cleanup handoff writes `usage.json`, `usage.md`, and `cleanup-prompt.md` before
-any agent launch. The prompt tells the agent to preserve recent/frequent skills,
-never delete skills, ignore non-disable recommendations during cleanup, disable
-unused global/plugin skills only through Codex `[[skills.config]]` entries in
-`~/.codex/config.toml`, and verify with `npx skills-doctor@latest`.
+any agent launch. Disable prompts tell the agent to preserve recent/frequent
+skills, never delete skills, ignore non-disable recommendations during cleanup,
+disable unused global/plugin skills only through Codex `[[skills.config]]`
+entries in `~/.codex/config.toml`, and verify with `npx skills-doctor@latest`.
+Grouped usage-recommendation prompts are scoped to the selected action, such as
+shortening context-heavy descriptions or reviewing duplicate skill names.
 Skills already disabled in Codex config are omitted from scan, usage-ranking,
 and cleanup-candidate results.
 
@@ -139,14 +170,19 @@ skills-doctor --json
 skills-doctor --json --json-compact
 skills-doctor --yes --json
 skills-doctor --yes --json --fail-on warning
+skills-doctor --yes --json --fail-on-security P1
 skills-doctor --yes --json --min-score 95
 skills-doctor --yes --json --usage
 ```
 
 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.
+By default, the exit code fails for blocking quality errors, error diagnostics,
+and P0 security findings. Use `--fail-on warning`, `--fail-on advice`,
+`--fail-on-security P1`, `--fail-on-security P2`, or `--min-score <number>` for
+stricter CI gates. JSON reports include security priority counts, capability
+counts, and per-finding security fields such as `priority`, `capabilities`,
+`confidence`, `rationale`, and `counterevidence`.
 
 Use `--usage` to include local Codex usage analysis in JSON or non-interactive
 runs. Interactive runs analyze usage by default; pass `--no-logs` to skip local

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

@@ -11,6 +11,7 @@ export type ScanFlags = {
     readonly logs?: boolean;
     readonly yes?: boolean;
     readonly failOn?: string | undefined;
+    readonly failOnSecurity?: string | undefined;
     readonly minScore?: string | undefined;
 };
 export type ScanActionOptions = {

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,EACL,KAAK,sBAAsB,EAC3B,iBAAiB,EAElB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAI/D,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAEhC,MAAM,wCAAwC,CAAC;AAehD,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,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,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,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAC9B,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACzC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAC3B,KAAK,EAAE,sBAAsB,KAC1B,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;CAC3C,CAAC;AAkBF,eAAO,MAAM,UAAU,GACrB,WAAW,MAAM,EACjB,OAAO,SAAS,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,UAAU,CAwIpB,CAAC"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/scan.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,sBAAsB,EAC3B,iBAAiB,EAGlB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAI/D,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAEhC,MAAM,wCAAwC,CAAC;AAqBhD,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM5F,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQzE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,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,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAC9B,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACzC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAC3B,KAAK,EAAE,sBAAsB,KAC1B,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;CAC3C,CAAC;AAqBF,eAAO,MAAM,UAAU,GACrB,WAAW,MAAM,EACjB,OAAO,SAAS,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,UAAU,CA2JpB,CAAC"}