feat: upgrade subcommand — regenerate-lockfile MVP (PR-5a)

[pofallon]

Implements the regenerate path of `deacon upgrade` per `docs/subcommand-specs/upgrade/SPEC.md`: re-resolve every Feature against the OCI registry, build a fresh `Lockfile`, and either print it to stdout (`--dry-run`) or write it to disk via `write_lockfile(force_init = true)`.

CLI surface

```
deacon upgrade [--dry-run]
[--docker-path ]
[--docker-compose-path ]
[-f ] [-v ] # hidden, Dependabot-only
```

Workspace + `--config` come from the global flags (parity with other consumer subcommands).

What this PR includes

• Validation (fail-fast per spec §2/§3):
  • `--feature` and `--target-version` must both be set or both absent. Error message matches upstream: `"The '--target-version' and '--feature' flag must be used together."`
  • `--target-version` must match `^\d+(\.\d+(\.\d+)?)?$`. Error matches upstream: `"Invalid version 'X'. Must be in the form of 'x', 'x.y', or 'x.y.z'"`
• Config load via the shared `load_config` helper (extends chain honored).
• Feature resolution via the existing OCI fetcher (`default_fetcher()` + `fetch_feature`), which returns each feature's manifest digest + metadata version.
• Lockfile assembly keyed by the user-provided feature ID (matches upstream `generateLockfile` + PR-4b's helper in `up`). Metadata-version missing → falls back to the user-requested tag (e.g. `"1"`) with a WARN.
• `--dry-run`: pretty-printed canonical JSON to stdout (sorted keys, trailing newline) — byte-identical to what `write_lockfile` would emit.
• Default: `write_lockfile(force_init = true)` per spec §5 phase 4.

Tests

13 new unit tests in `upgrade::tests`:

• Pin-flag pairing (4): both-set, both-absent, only-feature, only-target-version
• Target-version regex (2): 5 valid forms (`1`, `1.2`, `1.2.3`, `10`, `10.20.30`); 8 invalid forms (incl. `latest`, `v1`, `1.x.3`, `1.`, `.1`, `1.2.3.4`)
• Spec-exact error message on invalid `--target-version`
• Lockfile entry assembly (3): metadata-version-present, tag-fallback when metadata version missing, sorted `dependsOn`
• Empty-features short-circuit (2): missing features object, empty features object
• Argument defaults

Verification:

• `cargo fmt --all -- --check`
• `cargo clippy --all-targets -- -D warnings`
• `cargo test -p deacon --lib` → 226 pass (no regression; baseline includes PR-4a since this branch is based on `pr4-lockfile-graduation`)
• CI green (gated until base lands)
• End-to-end smoke against a real OCI registry — deferred to integration-test follow-up; the unit tests pin the in-process behavior precisely

Deferred to PR-5b

• `--feature` / `--target-version` config-pin behavior (modifies `devcontainer.json` in place). The flags are accepted today so the CLI surface is stable, but using them returns `"--feature/--target-version pinning is not yet implemented (PR-5b)"` rather than silently doing nothing. Pinning needs JSON5-AST-preserving edits to avoid clobbering comments — substantial enough to warrant its own PR.

Code-dedup follow-up

The lockfile-entry assembly logic is intentionally duplicated from PR-4b (`crates/deacon/src/commands/up/features_build.rs::build_lockfile_from_features`) so PR-5a doesn't depend on PR-4b's diff. Once both land on `main`, a small follow-up PR can lift the shared logic into `deacon_core::lockfile`.

Base branch

Based on `pr4-lockfile-graduation` (#33) since upgrade needs `deacon_core::lockfile::{Lockfile, LockfileFeature, get_lockfile_path, write_lockfile}` — all added in PR-4a. After #33 merges, this branch auto-rebases onto `main`.

Refs

• Closes part of the "Implement `upgrade`" Tier 1 blocker (issue 1.0 readiness: Tier 1 blocker progress tracker #34)
• Spec: `docs/subcommand-specs/upgrade/SPEC.md`
• PR-4a (feat: lockfile graduation — schema parity + CLI surface (PR-4 of 7, phase 1) #33): `deacon_core::lockfile` (consumed here)
• PR-4b (feat: lockfile graduation — wire writer in up's feature pipeline (PR-4b) #35): `build_lockfile_from_features` in `up` (helper duplicated)

🤖 Generated with Claude Code