security: harden skill supply-chain with version ranges and trust model

[skoshx]

Summary

Addresses supply-chain hardening concerns raised in #1440 by replacing @latest with @0.x version ranges throughout the codebase and documenting the trust model.

Changes

1. Added SECURITY.md

• Documents trust model, threat boundaries, and hardening options
• Explains the rationale for version range strategy vs pinning
• Provides guidance for security-sensitive environments
• Defines supported versions and disclosure policy

2. Updated Skill Files

• Replace react-doctor@latest with react-doctor@0.x in:
  • skills/react-doctor/SKILL.md
  • .agents/skills/react-doctor/SKILL.md
  • skills/improve-react/SKILL.md
  • All skill reference files
• Add security notes explaining version strategy
• Document playbook vendoring option for hardened environments

3. Updated CLI Source

• Replace @latest with @0.x in all CLI-generated commands:
  • Install scripts (install-doctor-script.ts)
  • Git hooks (install-git-hook-file.ts)
  • CI configuration (gitlab-ci-provider.ts)
  • Terminal output messages (render-diagnostics.ts, render-agent-guidance.ts)
  • Agent handoff payloads (build-handoff-payload.ts)

4. Updated Package Spec Resolver

• scripts/resolve-package-spec.mjs now maps latest → 0.x
• Ensures GitHub Action defaults to 0.x when no version is specified
• Maintains backward compatibility for existing workflows

5. Updated Tests

• All test expectations updated to match @0.x behavior
• Tests verify CLI generates correct version ranges

Rationale

The change from @latest to @0.x provides a balanced approach:

Benefits

✅ Automatic updates within major version - Users get patch and minor updates automatically
✅ Protection against breaking changes - Won't auto-upgrade to 1.0+ without explicit action
✅ Better reproducibility - Version range is more specific than latest
✅ Security-conscious - Reduces supply-chain risk while maintaining UX benefits

Trade-offs

⚖️ Not as hardened as exact pins - Still allows automatic updates within 0.x
⚖️ Requires major version upgrade action - Users must explicitly upgrade to 1.0+

For Maximum Security

For security-critical environments, the SECURITY.md document recommends:

• Pin to exact versions: react-doctor@0.9.1
• Vendor the runtime playbook locally
• Use lockfiles to pin transitive dependencies
• Review version changes before upgrading

Runtime Instruction Fetching

The skill's runtime playbook fetch (curl https://www.react.doctor/prompts/...) is intentionally preserved because:

• The playbook contains agent instructions (how to triage/fix), not executable code
• Central updates allow bug fixes without skill reinstalls
• The website is under project maintainers' control and served over HTTPS

For environments requiring vendored instructions, SECURITY.md documents how to download and commit the playbook locally.

Testing

• ✅ Typecheck passes
• ✅ All test expectations updated to match new behavior
• ✅ Package spec resolver correctly maps latest → 0.x

Issue Reference

Closes #1440

Migration Path

For Users

No action required. The change is backward compatible:

• Existing installations continue working
• New installs use @0.x automatically
• npx react-doctor continues to work as before

For Upgrading to 1.0 (Future)

When 1.0 is released, users will need to:

• Update skills to reference @1.x
• Update CI configs to use @1.x
• Or pin to exact 1.0.x version for maximum stability

  

[github-actions]

📦 GitHub Action release recommended

This PR changes the React Doctor GitHub Action's release surface:

• scripts/resolve-package-spec.mjs

The composite action is versioned independently from the npm packages, so it
needs its own git tag once this merges. Based on the PR title, this looks like
a patch bump (fix / refactor / chore / docs): v2.2.8 → v2.2.9.

After merging, cut the tag from the merge commit on main (tags are GPG-signed
annotated tags, so run this locally where your signing key is configured):

git checkout main && git pull --ff-only
merge_commit=$(git rev-parse HEAD)
git tag -a v2.2.9 "$merge_commit" -m "react-doctor action v2.2.9"
git tag -fa v2 "$merge_commit" -m "react-doctor action v2 (floating major -> v2.2.9)"
git push origin v2.2.9
git push --force origin v2   # moves only the floating major pointer

_{This bump can also be performed automatically on merge — set the repo
variable AUTO_BUMP_ACTION_TAG=true. Recommendation by the Action Version Bump workflow.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/eslint-plugin-react-doctor@1441

npm i https://pkg.pr.new/oxlint-plugin-react-doctor@1441

npm i https://pkg.pr.new/react-doctor@1441

commit: d55b238

[github-actions]

React Doctor found no new issues. 🎉

_{Reviewed by React Doctor for commit d55b238.}