feat(tools): add upgrade subcommand for in-place AI-DLC install upgrades

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.11] - 2026-07-07
+
+Adds an `upgrade` utility subcommand that replaces the manual "download the release zip and `cp -r dist/<harness>/` into your project" recipe every prior `## [N.N.N]` entry has documented. One command fetches the newest tag in the installed major series from the upstream tags API (not `releases/latest`, which answers the v1 line for this repo), auto-detects the harness (`.claude` / `.kiro` / `.codex`), and copies new files in — PRESERVING any file whose local bytes differ from the incoming upstream file (the user-modification signal). No backup dir is created — commit your harness dir or take a snapshot yourself before running upgrade if you want rollback insurance. Windows requires Git Bash or WSL (uses system `tar`).
+
+* NEW `aidlc-utility upgrade`: runs the upgrade. Reports installed vs latest, prints `up to date` / `ahead of upstream` and exits when no work is needed. Otherwise: downloads the tarball to /tmp, copies added + byte-identical upstream files into the harness dir, and preserves user-modified files (naming each one).
+* NEW `aidlc-utility upgrade --dry-run`: same discovery + download + diff, but writes nothing. Prints the per-file counts (added / unchanged / kept-local) and lists the user-modified files that would be preserved. Useful before letting a script mutate a live install.
+* The installed version is read from the target project's `.claude/tools/aidlc-version.ts` (or `.kiro/...` / `.codex/...`), not from the tool binary's own compiled-in constant, so `upgrade` reports the truth for the install being operated on even when the tool binary lives elsewhere.
+* Cross-major upgrades are refused deliberately: a 2.x install is never auto-offered a 3.x jump — the pick keeps to `v<installed-major>.*` tags. Pre-release tags (`-rc1`, etc.) are also filtered out.
+* Auto-detects the target harness by looking for `.claude/` / `.kiro/` / `.codex/` under the project. Errors clearly if none exist ("install AI-DLC first") or if multiple are present ("pick one with `--harness <name>`").
+
 ## [2.2.10] - 2026-07-06
 
 Workspace detection now recognizes git submodules. A workspace whose code lives in uninitialized submodules (empty dirs plus a `.gitmodules` file) previously scanned as Greenfield, so reverse-engineering was auto-skipped and every design stage ran with zero code understanding. The scanner gains a sixth brownfield signal: a parseable `.gitmodules` with at least one submodule path entry classifies the workspace Brownfield. When submodule paths are uninitialized, the scan warns and names the remedy (`git submodule update --init --recursive`) at birth, in the doctor report, and on `detect`. Languages stay as scanned (Unknown is truthful until the submodules are fetched). **Upgrade:** re-copy your `dist/<harness>/` shell into the project.
@@ -79,10 +89,6 @@ Stops help requests from accidentally creating intents. `/aidlc intent help` was
 * The "Unknown intent" error from a failed `/aidlc intent <name>` switch no longer suggests describing new work; it points at the read-only `/aidlc intent` listing and explicitly says not to start a new workflow to recover. The "Unknown space" error likewise no longer instructs creating the missing space - creation stays a separate, deliberate move.
 * The orchestrator skill's second-intent CONFIRM step named the wrong binary (`aidlc-utility.ts next ...`, which dies with a usage error listing `intent-birth` - a guard-bypass temptation); it now names `aidlc-orchestrate.ts next` on all four harnesses.
 * The Codex orchestrator skill's forwarding loop now tells the conductor to drop the leading `$aidlc`/`/aidlc` invocation marker and forward the remaining text as separate arguments (observed live on Codex exec: the conductor echoed the whole slash line as one quoted token, which hid `intent help` from the router and dead-ended on a scope ask). The engine deliberately does NOT try to repair marker-prefixed input - a mangled echo lands in the scope-confirmation ask, a safe human gate.
-||||||| parent of ef64a3e (fix: detect nested projects in workspace detection (2.2.7))
-||||||| parent of 48f8b61 (fix: bound the compose-pending carve-out and guard recompose against autonomy (2.2.8))
-||||||| parent of 4fd686b (fix: exempt optional produces from per-unit coverage so conditional artifacts can be skipped (2.2.9))
-||||||| parent of 4ad1db9 (fix: detect git submodules as a brownfield signal in workspace detection (2.2.10))
 
 ## [2.2.0] - 2026-07-04
 

README.md

@@ -8,7 +8,7 @@ A native implementation of the **AI-DLC methodology** (AI-Driven Development Lif
 
 The methodology lives once, in a harness-neutral `core/`; each harness adds a thin surface that decides how it shows up on that harness. So you edit the methodology in one place, and every harness distribution is generated from it — no harness gets special treatment. (See [Repository layout](#repository-layout) for how the pieces fit together.)
 
-![version](https://img.shields.io/badge/version-2.2.10-blue)
+![version](https://img.shields.io/badge/version-2.2.11-blue)
 ![license](https://img.shields.io/badge/license-MIT--0-green)
 ![Kiro IDE](https://img.shields.io/badge/harness-Kiro%20IDE-orange)
 ![Kiro CLI](https://img.shields.io/badge/harness-Kiro%20CLI-orange)
@@ -61,7 +61,7 @@ The deterministic engine — state machine, audit log, and the referee that coor
 
 ## Recommended Model
 
-This release works better with `Claude Opus 4.8`. We are sharpening it for previous model versions. 
+This release works better with `Claude Opus 4.8`. We are sharpening it for previous model versions.
 
 ## Quick Start