feat(skills): add api-version-upgrade skill for dated-package bumps

[jeffredodd]

Summary

Codifies the @gusto/embedded-api-v-<YYYY-MM-DD> upgrade playbook into a reusable skill at .claude/skills/api-version-upgrade/. The skill runs the full 6-phase workflow autonomously: side-by-side package diff, codemod across import paths + cache-key + bare-date sites, type-level verification, E2E scaffolding, and draft base PR creation with a breaking-change matrix in the description.

Born from the live v2025-11-15 → v2026-02-01 execution (PR #2233). Three iterations of evals against three upgrade scenarios validated and refined it. The most important finding: the skill caught a silent-runtime-failure bug in PR #2233 that the live execution had missed.

What's in the skill

.claude/skills/api-version-upgrade/
├── SKILL.md                              ← 6-phase autonomous playbook
├── evals/
│   └── evals.json                        ← 3 test cases, 18 assertions
├── references/
│   ├── diff-methodology.md               ← how to diff each package layer
│   ├── codemod-commands.md               ← sed commands, cache-key + bare-date sweeps
│   ├── e2e-patterns.md                   ← spec patterns + brittleness lessons
│   ├── pr-template.md                    ← PR description template w/ matrix
│   └── known-pitfalls.md                 ← lessons from prior upgrades
└── scripts/
    ├── install-old-package.sh            ← side-by-side install for diffing
    └── diff-packages.sh                  ← runs the full diff and emits findings

Also adds dictionary entries (codemod, worktrees, networkidle, the http-verb prefixes used by embedded-api operation names) to cspell.json.

The bug it caught in PR #2233

src/contexts/ApiProvider/apiVersionHook.ts:3 had const CURRENT_API_VERSION = '2025-11-15' as a bare date string — not part of any package path. The codemod's package-name sweep didn't match it. Without the skill's reference catching this, our v2026-02-01 upgrade would have shipped as a runtime no-op: types claim v2026-02-01, server answers with v2025-11-15 schemas because the header still says v2025-11-15. Typecheck passes, unit tests pass, e2e passes. Partners hit production with the wrong API contract.

The skill's references/codemod-commands.md § "CRITICAL — the bare-date X-Gusto-API-Version sweep" now flags this as a mandatory step. PR #2233 commit 9a9b79e70 fixed it before merge.

Validation: 3 iterations of evals

Eval	Scenario	Iter 3 result
1	v0.13.0 → v2025-11-15 (the original migration)	6/6 assertions pass — uses boundary-anchored regex (no bare→dated substring corruption)
2	v2025-11-15 → v2026-02-01 (replay of PR #2233)	6/6 assertions pass — avoids migration_blocker conflation, single base PR, includes bare-date sweep
3	v2026-02-01 → v2026-06-15 (pre-flight)	6/6 assertions pass — identifies off-cycle reimbursement as 🔴 with mandatory E2E, classifies helpers.test.ts refactor as ⚠️ optional

18/18 total assertions pass on iteration 3. Eval outputs preserved under .claude/skills/api-version-upgrade-workspace/iteration-3/ locally (gitignored — they're throwaway artifacts).

Confidence notes

• High confidence in the skill's analysis capability (3× validated, caught real bugs)
• Lower confidence in fully autonomous live execution — every eval was --dry-run analysis-only. The autonomous end-to-end path (open real PRs, run real codemods) has not been live-tested yet. Recommend exercising it on the v2026-02-01 → v2026-06-15 upgrade as the first real-world run.

Test plan

• CI green on this branch
• Run the skill against the next upgrade (v2026-02-01 → v2026-06-15) as a real autonomous test
• Compare the skill's output to PR feat!: bump @gusto/embedded-api to v2026-02-01 #2233's hand-built history to confirm convergence

🤖 Generated with Claude Code