Add thv skill upgrade: re-resolve pinned skills to newer content

[samuv]

Summary

• Why: RFC THV-0080 needs a controlled way to pull newer content for skills pinned by source (a registry name, an OCI tag, a git branch), without silently drifting the lock file on every plain re-install. This ships the full upgrade vertical slice in one PR, matching PR4's precedent (the CLI command can't exist without its API endpoint).
• What:
  • Upgrade re-resolves each targeted entry's Source — via the same git/OCI/registry dispatch order Install uses (resolveLatestState), stopping short of extraction/DB/lock writes — and installs newer content only when the digest actually changed. Source itself is never rewritten.
  • Entries pinned to an immutable reference (an OCI digest or a full git commit hash — isImmutableSource, added in PR4's pin.go) report not-upgradable: there's nothing newer to resolve to.
  • --preview reports what would change without persisting it (still fetches to compare digests — an OCI pull has no lighter "digest only" primitive, matching the RFC's own "preview is not side-effect-free" note; git sources resolve without touching disk). --allow-ref-change permits the resolved reference itself changing. --fail-on-changes gives CI a freshness gate.
  • var _ skills.SkillLockService = (*service)(nil) lands here now that both Sync (PR4) and Upgrade exist; SkillsRouter widens from PR4's narrow skillSyncer interface to the full skills.SkillLockService.
  • thv skill upgrade [name...] CLI.

Part of the production stack for #5715 (RFC THV-0080). Stack: 5/6 — lockfile → lock-service → install-hooks → sync → upgrade → cli-exitcodes. Based on #5895 (PR4).

Type of change

• New feature

Test plan

• Unit tests (task test)
• E2E tests (task test-e2e, scoped: ginkgo --label-filter=skills-lock)
• Linting (task lint-fix)

Unit tests cover: up-to-date (source unchanged), installs newer content and preserves Source, preview reports without persisting, not-upgradable for an immutable source, unknown name returns 404, --fail-on-changes stops at the first change. API handler tests including the 501 path and a --fail-on-changes 409 propagation. New E2E spec: build+push v1 → install → republish newer content at the same OCI reference → upgrade --preview reports the change without touching the lock file → upgrade applies it and the lock file records the new digest with Source unchanged.

Does this introduce a user-facing change?

Not yet — same TOOLHIVE_SKILLS_LOCK_ENABLED gate as the rest of the stack. Once the full stack lands: thv skill upgrade re-resolves and updates a project's pinned skills.

Special notes for reviewers

• resolveLatestState/resolveOCILatest/resolveGitLatest intentionally duplicate a slice of Install's dispatch logic rather than refactoring Install to expose a resolve-only phase — a deeper split felt like more surgery than this PR should carry; flagging for a second opinion on whether that tradeoff is right.
• The API layer discards partial UpgradeResult outcomes when --fail-on-changes trips (only the error is returned) — a caller doesn't currently see which earlier entries already succeeded before the stop. Noting as a known simplification, not fixed here.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 56.47059% with 74 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (skills-lock/04-sync@e4b12ca). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
pkg/skills/skillsvc/upgrade.go	53.73%	51 Missing and 11 partials ⚠️
pkg/skills/client/client.go	0.00%	12 Missing ⚠️

Additional details and impacted files

@@                  Coverage Diff                   @@
##             skills-lock/04-sync    #5896   +/-   ##
======================================================
  Coverage                       ?   71.73%           
======================================================
  Files                          ?      709           
  Lines                          ?    72653           
  Branches                       ?        0           
======================================================
  Hits                           ?    52115           
  Misses                         ?    16767           
  Partials                       ?     3771           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[samuv]

Tracked in #5899 (RFC THV-0080 stack).