codingbuddy-rules 2.4.2 → 3.0.2

package/.ai-rules/skills/dependency-management/SKILL.md

@@ -0,0 +1,381 @@
+---
+name: dependency-management
+description: Use when CVE discovered, major version upgrade needed, lock file conflicts occur, or license compliance audit required - guides systematic dependency health management
+---
+
+# Dependency Management
+
+## Overview
+
+Dependencies rot silently. Unmanaged packages become security liabilities, compatibility nightmares, and legal risks.
+
+**Core principle:** ALWAYS assess, prioritize, and plan before updating. Rushed upgrades break production; ignored vulnerabilities enable breaches.
+
+**Violating the letter of this process is violating the spirit of dependency management.**
+
+## First 5 Minutes Checklist (Security Vulnerability)
+
+**Use this when CVE alert arrives. Don't think, follow the list.**
+
+| Minute | Action | Output |
+|--------|--------|--------|
+| 0-1 | Identify affected package and version | `package@version` confirmed |
+| 1-2 | Check CVE severity (CVSS score) | Severity (Critical/High/Medium/Low) |
+| 2-3 | Verify if your app is affected | `affected` or `not_affected` |
+| 3-4 | Check if patch available | `patch_available` or `no_patch` |
+| 4-5 | If Critical/High: Create incident ticket | Stakeholders aware |
+
+**After 5 minutes:** Proceed to Phase 2 (Assess Impact) - you've completed Detect.
+
+## The Iron Law
+
+```
+NO UPGRADES WITHOUT IMPACT ASSESSMENT FIRST
+```
+
+If you haven't assessed breaking changes and tested compatibility, you cannot merge dependency updates.
+
+## When to Use
+
+Use for ANY dependency management task:
+- Security vulnerability (CVE) response
+- Major version upgrades
+- Lock file merge conflicts
+- License compliance audits
+- Dependency health reviews
+- Outdated package remediation
+
+**Use this ESPECIALLY when:**
+- Critical CVE discovered (pressure to "just update")
+- Major version jump required (2.x to 3.x)
+- Multiple conflicting lock file changes
+- Preparing for compliance audit
+- Inheriting legacy project with outdated deps
+
+**Don't skip when:**
+- "It's just a patch version" (patches can break too)
+- "We're in a hurry" (systematic is faster than hotfix loops)
+- "Everyone else uses this version" (your context differs)
+
+## When NOT to Use
+
+This skill is for **systematic dependency management**. Don't use it for:
+
+- **Adding new dependencies** - Evaluate need first, then use normal PR process
+- **Development-only tools** - devDependencies with no prod impact
+- **Automatic security patches** - Dependabot/Renovate auto-merge for patch versions
+- **Learning/prototyping** - Experimental projects without production constraints
+
+**Key distinction:** This skill manages systematic upgrade and security response. For simple package additions, use standard code review.
+
+## The Six Phases
+
+You MUST complete each phase before proceeding to the next.
+
+```dot
+digraph dependency_management {
+    rankdir=TB;
+    node [shape=box];
+
+    "1. Detect" -> "2. Assess Impact";
+    "2. Assess Impact" -> "3. Plan Upgrade";
+    "3. Plan Upgrade" -> "4. Execute";
+    "4. Execute" -> "5. Verify";
+    "5. Verify" -> "6. Document";
+
+    "Skip Phase?" [shape=diamond];
+    "2. Assess Impact" -> "Skip Phase?" [style=dashed, label="tempted?"];
+    "Skip Phase?" -> "STOP" [label="NO"];
+    "STOP" [shape=doublecircle, color=red];
+}
+```
+
+### Phase 1: Detect
+
+**Identify the dependency issue:**
+
+1. **For Security Vulnerabilities:**
+   - Run `npm audit` / `yarn audit` / `pnpm audit`
+   - Check CVE databases (NVD, GitHub Advisory)
+   - Note CVSS score and attack vector
+   - Identify affected versions
+
+2. **For Outdated Packages:**
+   - Run `npm outdated` / `yarn outdated`
+   - Identify major version gaps
+   - Check changelog for breaking changes
+   - Note last update date (maintenance status)
+
+3. **For License Issues:**
+   - Run license audit tool
+   - Identify copyleft licenses (GPL, AGPL)
+   - Check commercial restrictions
+   - Note transitive dependencies
+
+**Completion criteria:**
+- [ ] `issue_identified` - Package, version, and issue type documented
+- [ ] `severity_classified` - Critical/High/Medium/Low assigned
+
+### Phase 2: Assess Impact
+
+**Understand the blast radius BEFORE planning:**
+
+See `security-vulnerability-response.md` for CVE-specific assessment.
+
+1. **Usage Analysis**
+   - Where is this package used in codebase?
+   - How many files/modules import it?
+   - Is it in critical path?
+
+2. **Breaking Change Analysis**
+   - Read CHANGELOG completely
+   - Identify API changes
+   - Check migration guide if available
+   - List incompatible changes
+
+3. **Dependency Chain**
+   - What depends on this package?
+   - Are there peer dependency conflicts?
+   - Will upgrading cascade to other packages?
+
+4. **Risk Assessment**
+   - Business impact if upgrade fails?
+   - Rollback complexity?
+   - Testing coverage for affected areas?
+
+**Completion criteria:**
+- [ ] `usage_mapped` - All import locations identified
+- [ ] `breaking_changes_listed` - API changes documented
+- [ ] `risk_assessed` - Impact level determined
+
+### Phase 3: Plan Upgrade
+
+**Design the upgrade strategy:**
+
+See `major-upgrade-guide.md` for staged upgrade patterns.
+
+1. **Choose Upgrade Path**
+   - Direct upgrade (minor/patch)
+   - Staged upgrade (major versions)
+   - Alternative package (if unmaintained)
+
+2. **For Major Upgrades:**
+   - Plan intermediate versions if needed
+   - Identify code changes required
+   - Estimate effort per change
+
+3. **For Security Patches:**
+   - Check if patch version available
+   - If not, evaluate workarounds
+   - Consider temporary mitigations
+
+4. **Create Upgrade Ticket**
+   - Document the plan
+   - Assign owner
+   - Set timeline based on severity
+
+**Completion criteria:**
+- [ ] `upgrade_path_defined` - Strategy documented
+- [ ] `changes_estimated` - Code modifications listed
+- [ ] `timeline_set` - Deadline based on severity
+
+### Phase 4: Execute
+
+**Implement the upgrade:**
+
+See `lock-file-management.md` for conflict resolution.
+
+1. **Create Feature Branch**
+   - Branch from main
+   - Clear naming: `deps/upgrade-package-v3`
+
+2. **Update Package**
+   - Update package.json
+   - Run install to update lock file
+   - Commit lock file changes separately
+
+3. **Make Required Code Changes**
+   - Apply API changes
+   - Update deprecated usages
+   - Add any new configurations
+
+4. **Run Tests**
+   - Full test suite
+   - Manual testing for critical paths
+   - Integration tests if applicable
+
+**Completion criteria:**
+- [ ] `package_updated` - Version bumped in package.json
+- [ ] `lock_file_clean` - No merge conflicts
+- [ ] `tests_passing` - All tests green
+
+### Phase 5: Verify
+
+**Confirm the upgrade works:**
+
+1. **Build Verification**
+   - Production build succeeds
+   - No new warnings
+   - Bundle size acceptable
+
+2. **Runtime Verification**
+   - Application starts
+   - Critical paths work
+   - No console errors
+
+3. **Security Verification (if CVE)**
+   - Re-run audit tool
+   - Vulnerability resolved
+   - No new vulnerabilities introduced
+
+**Completion criteria:**
+- [ ] `build_verified` - Production build succeeds
+- [ ] `runtime_verified` - Application works correctly
+- [ ] `security_verified` - Audit passes (if CVE)
+
+### Phase 6: Document
+
+**The upgrade is NOT complete until documented:**
+
+1. **Update Changelog**
+   - Note the upgrade
+   - List any breaking changes handled
+   - Reference CVE if security-related
+
+2. **Update Documentation**
+   - Update any version-specific docs
+   - Note configuration changes
+   - Update README if relevant
+
+3. **Close Tickets**
+   - Link PR to issue
+   - Close vulnerability ticket
+   - Update audit tracking
+
+**Completion criteria:**
+- [ ] `changelog_updated` - Upgrade documented
+- [ ] `ticket_closed` - Issue resolved and linked
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Just bump the version and see if it works"
+- "It's only a patch, won't break anything"
+- "We'll fix breaking changes as we find them"
+- "Skip the audit, we need this deployed"
+- "License doesn't matter for internal tools"
+- "Lock file conflicts are fine to auto-resolve"
+- "Dependabot will handle security"
+- "We can deal with deprecation warnings later"
+
+**ALL of these mean: STOP. Return to Phase 2.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "It's just a patch version" | Patch versions can contain breaking changes. Semantic versioning is a promise, not a guarantee. |
+| "We're behind, need to catch up" | Rushed upgrades cause production incidents. Systematic upgrades are faster long-term. |
+| "Everyone else uses this version" | Your codebase has unique usage patterns. Test YOUR code. |
+| "Lock file changes are noise" | Lock file integrity prevents "works on my machine." Treat it as source code. |
+| "License is fine, it's open source" | Open source has obligations. GPL can require code disclosure. Check ALWAYS. |
+| "CVE doesn't affect us" | Verify with evidence, don't assume. Attack vectors are creative. |
+| "We'll handle deprecations later" | Deprecation warnings become errors. Address when upgrading. |
+| "Auto-merge is safe for patches" | Auto-merge is safe for MONITORED patches. Set up failure alerts. |
+
+## Quick Reference
+
+| Phase | Key Activities | Verification Key |
+|-------|---------------|------------------|
+| **1. Detect** | Audit, identify, classify severity | `issue_identified` |
+| **2. Assess** | Usage mapping, breaking changes, risk | `risk_assessed` |
+| **3. Plan** | Upgrade path, code changes, timeline | `upgrade_path_defined` |
+| **4. Execute** | Branch, update, test | `tests_passing` |
+| **5. Verify** | Build, runtime, security audit | `build_verified` |
+| **6. Document** | Changelog, docs, close tickets | `ticket_closed` |
+
+## Severity Response Times
+
+| Severity | CVSS Score | Response Time | Action |
+|----------|------------|---------------|--------|
+| **Critical** | 9.0-10.0 | 24 hours | Immediate patch or mitigation |
+| **High** | 7.0-8.9 | 7 days | Prioritized upgrade |
+| **Medium** | 4.0-6.9 | 30 days | Scheduled upgrade |
+| **Low** | 0.1-3.9 | 90 days | Next maintenance cycle |
+
+## Monorepo Considerations
+
+When managing dependencies in monorepos (multiple package.json files):
+
+### Workspace Tools
+
+| Tool | Command | Purpose |
+|------|---------|---------|
+| npm workspaces | `npm audit --workspaces` | Audit all workspaces |
+| Yarn workspaces | `yarn workspaces foreach npm audit` | Audit each workspace |
+| pnpm | `pnpm -r audit` | Recursive audit |
+| Lerna | `lerna exec -- npm audit` | Execute in each package |
+| Turborepo | `turbo run audit` | Run audit task |
+| Nx | `nx run-many --target=audit` | Parallel audit |
+
+### Monorepo-Specific Workflow
+
+1. **Detect (Modified)**
+   - Audit ALL packages: `npm audit --workspaces`
+   - Check shared dependencies in root
+   - Identify which packages are affected
+
+2. **Assess Impact (Critical)**
+   - Map internal package dependencies
+   - Check if upgrade affects shared packages
+   - Consider publish order for internal packages
+
+3. **Execute (Coordinated)**
+   - Update root and workspace packages together
+   - Use `--workspace=<name>` for targeted updates
+   - Regenerate root lock file after all changes
+
+### Shared vs Package-Specific Dependencies
+
+| Location | Use For | Example |
+|----------|---------|---------|
+| Root `package.json` | Shared tooling, workspace-wide deps | TypeScript, ESLint, build tools |
+| Package `package.json` | Package-specific runtime deps | React (if only some packages need it) |
+
+### Version Synchronization
+
+```bash
+# Ensure consistent versions across workspaces
+npx syncpack list-mismatches
+npx syncpack fix-mismatches
+```
+
+### CI Considerations
+
+- Run audit in each workspace
+- Verify all lock files are in sync
+- Test affected packages after dependency changes
+
+## Supporting Files
+
+These files provide detailed guidance for specific phases:
+
+- **`security-vulnerability-response.md`** - CVE severity handling, patch assessment, temporary mitigations
+- **`major-upgrade-guide.md`** - Breaking change analysis, staged upgrades, compatibility testing
+- **`lock-file-management.md`** - Merge conflict resolution, CI validation, automation
+- **`license-compliance.md`** - License obligations, compatibility matrices, audit procedures
+
+## Related Skills
+
+- **superpowers:systematic-debugging** - For diagnosing upgrade-related failures
+- **superpowers:test-driven-development** - For adding tests before risky upgrades
+- **superpowers:incident-response** - If security upgrade causes production incident
+
+## Real-World Impact
+
+From dependency management data:
+- Systematic upgrades: 95% success rate, avg 30 min per package
+- Ad-hoc upgrades: 60% success rate, avg 2 hours debugging
+- CVE response with process: 4 hour average resolution
+- CVE response without process: 48+ hour average resolution
+- License audit findings: 70% caught by automated tooling

package/.ai-rules/skills/dependency-management/license-compliance.md

@@ -0,0 +1,282 @@
+# License Compliance
+
+Guide to open-source license obligations and compliance procedures.
+
+## Why License Compliance Matters
+
+- **Legal risk:** License violations can result in lawsuits
+- **Copyleft exposure:** GPL can require source disclosure
+- **Commercial restrictions:** Some licenses prohibit commercial use
+- **Attribution requirements:** Many licenses require credits
+
+**Ignorance is not a defense.** Every dependency introduces license obligations.
+
+## License Categories
+
+### Permissive Licenses
+
+Low risk, minimal obligations:
+
+| License | Attribution | Modification | Commercial | Copyleft |
+|---------|-------------|--------------|------------|----------|
+| MIT | Required | Allowed | Allowed | No |
+| Apache 2.0 | Required | Allowed | Allowed | No |
+| BSD-2 | Required | Allowed | Allowed | No |
+| BSD-3 | Required | Allowed | Allowed | No |
+| ISC | Required | Allowed | Allowed | No |
+
+**Safe for:** Most projects, including commercial and proprietary
+
+### Weak Copyleft
+
+Medium risk, modifications must be shared:
+
+| License | Attribution | Modification | Commercial | Copyleft |
+|---------|-------------|--------------|------------|----------|
+| LGPL-2.1 | Required | Share changes | Allowed | Library only |
+| LGPL-3.0 | Required | Share changes | Allowed | Library only |
+| MPL-2.0 | Required | Share changes | Allowed | File-level |
+
+**Safe for:** Using as library, NOT modifying
+**Requires attention:** If you modify the library code
+
+### Strong Copyleft
+
+High risk, entire project may need to be open:
+
+| License | Attribution | Modification | Commercial | Copyleft |
+|---------|-------------|--------------|------------|----------|
+| GPL-2.0 | Required | Share all | Allowed* | Full project |
+| GPL-3.0 | Required | Share all | Allowed* | Full project |
+| AGPL-3.0 | Required | Share all | Allowed* | Network use |
+
+*Commercial allowed, but must open source entire work
+
+**Warning:** Including GPL code in proprietary software may require open-sourcing your entire project.
+
+### Restrictive/Proprietary
+
+High risk, limited or no use rights:
+
+| License | Risk Level | Typical Restrictions |
+|---------|------------|----------------------|
+| SSPL | Very High | Network use requires full stack disclosure |
+| BSL | High | Production use may require commercial license |
+| Proprietary | Varies | Check specific terms |
+
+## License Compatibility Matrix
+
+Can these licenses coexist in the same project?
+
+| Base License | MIT | Apache | LGPL | GPL | AGPL |
+|--------------|-----|--------|------|-----|------|
+| **MIT** | Yes | Yes | Yes | Yes* | Yes* |
+| **Apache 2.0** | Yes | Yes | Yes | No** | No |
+| **LGPL** | Yes | Yes | Yes | Yes | Yes |
+| **GPL** | Yes* | No** | Yes | Yes | Yes |
+| **AGPL** | Yes* | No | Yes | Yes | Yes |
+
+*Resulting work becomes GPL/AGPL
+**Apache 2.0 is incompatible with GPL-2.0 (compatible with GPL-3.0)
+
+## Audit Procedures
+
+### Automated License Scanning
+
+```bash
+# Using license-checker (npm)
+npx license-checker --summary
+
+# Detailed report
+npx license-checker --json > licenses.json
+
+# Check for problematic licenses
+npx license-checker --failOn "GPL;AGPL;SSPL"
+```
+
+### CI Integration
+
+```yaml
+# GitHub Actions
+- name: License check
+  run: |
+    npx license-checker --failOn "GPL-3.0;AGPL-3.0;SSPL" --excludePrivatePackages
+```
+
+### Quarterly Audit Checklist
+
+- [ ] Run license scanner on all projects
+- [ ] Review any new licenses added
+- [ ] Verify attribution files are current
+- [ ] Check for license changes in updated packages
+- [ ] Review transitive dependencies
+- [ ] Document any approved exceptions
+
+## Attribution Requirements
+
+### NOTICE File
+
+Create and maintain `NOTICE` or `THIRD_PARTY_LICENSES`:
+
+```markdown
+# Third-Party Licenses
+
+This software includes the following third-party components:
+
+## lodash
+- License: MIT
+- Copyright (c) JS Foundation and other contributors
+- https://github.com/lodash/lodash/blob/master/LICENSE
+
+## axios
+- License: MIT
+- Copyright (c) 2014-present Matt Zabriskie
+- https://github.com/axios/axios/blob/master/LICENSE
+```
+
+### Automated Attribution Generation
+
+```bash
+# Generate license report
+npx license-checker --customPath customFormat.json --out THIRD_PARTY_LICENSES.md
+```
+
+## Handling Problematic Licenses
+
+### GPL in JavaScript/Node.js
+
+**Common misconception:** "GPL doesn't apply to npm packages"
+
+**Reality:** If your code imports/requires GPL code, your code may become GPL.
+
+**Mitigation options:**
+1. Find MIT/Apache alternative
+2. Use as separate service (not linked)
+3. Get commercial license from author
+4. Open source your project
+
+### AGPL Implications
+
+AGPL extends GPL to network use. If your AGPL-licensed code runs on a server, users can request source code.
+
+**Implications:**
+- SaaS using AGPL must provide source
+- Internal tools may be exempt
+- Check with legal for specific cases
+
+### License Change After Adoption
+
+If a dependency changes license:
+1. You can continue using the old version (old license applies)
+2. New versions require new license compliance
+3. Document the version/license you're using
+
+## Compliance Workflow
+
+### New Dependency Check
+
+Before adding any dependency:
+
+```bash
+# Check license
+npm view <package> license
+
+# Check for problematic transitive deps
+npx license-checker --production --packages <package>
+```
+
+Decision tree:
+
+```dot
+digraph license_check {
+    "New dependency" -> "Check license";
+    "Check license" -> "Permissive?" [label="MIT/Apache/BSD"];
+    "Permissive?" -> "Approved" [label="yes"];
+    "Permissive?" -> "Weak copyleft?" [label="no"];
+    "Weak copyleft?" -> "Review modifications" [label="LGPL/MPL"];
+    "Weak copyleft?" -> "Strong copyleft?" [label="no"];
+    "Strong copyleft?" -> "Legal review" [label="GPL/AGPL"];
+    "Strong copyleft?" -> "Check restrictions" [label="other"];
+}
+```
+
+### Approval Workflow
+
+For non-permissive licenses:
+
+1. **Document the request**
+   - Package name and version
+   - License type
+   - Business justification
+
+2. **Legal/compliance review**
+   - Impact assessment
+   - Alternative evaluation
+   - Risk acceptance
+
+3. **Approval tracking**
+   - Record approval in decision log
+   - Add to approved exceptions list
+   - Set review date
+
+## Exception Tracking
+
+### Approved Exceptions Log
+
+```markdown
+# License Exceptions
+
+| Package | License | Approved By | Date | Reason | Review Date |
+|---------|---------|-------------|------|--------|-------------|
+| example-pkg | LGPL-2.1 | Legal Team | 2024-01-15 | No modification needed | 2025-01-15 |
+```
+
+### Exception Review Triggers
+
+Review exceptions when:
+- Package is updated
+- Package license changes
+- Usage pattern changes
+- Compliance audit scheduled
+
+## Tools and Resources
+
+### License Scanning Tools
+
+| Tool | Free Tier | CI Integration | Transitive Deps |
+|------|-----------|----------------|-----------------|
+| license-checker | Yes | Yes | Yes |
+| FOSSA | Yes | Yes | Yes |
+| Snyk | Yes | Yes | Yes |
+| WhiteSource | No | Yes | Yes |
+
+### License Databases
+
+- [SPDX License List](https://spdx.org/licenses/) - Standard identifiers
+- [choosealicense.com](https://choosealicense.com/) - Plain language summaries
+- [TLDRLegal](https://tldrlegal.com/) - License explanations
+
+### Legal Resources
+
+- Open Source Initiative (OSI) - Official license definitions
+- Software Freedom Conservancy - GPL compliance guidance
+- Linux Foundation - Open source legal resources
+
+## Emergency Procedures
+
+### License Violation Discovered
+
+1. **Stop distribution** - Don't deploy updates with violation
+2. **Document scope** - What's affected, how long, where
+3. **Legal consultation** - Get professional advice
+4. **Remediation plan** - Remove, replace, or comply
+5. **Communication** - If public exposure, prepare response
+
+### GPL Compliance Request
+
+If someone requests source under GPL:
+
+1. Verify the claim (is GPL code actually included?)
+2. Prepare the source code
+3. Provide within reasonable time (30 days typical)
+4. Review how to prevent future issues