@skillcap/gdh 0.8.0 → 0.10.0

package/RELEASE-SPAN-UPDATE-CONTRACTS.json

@@ -0,0 +1,628 @@
+{
+  "schemaVersion": 1,
+  "releases": [
+    {
+      "version": "0.0.0",
+      "releaseTag": "v0.0.0",
+      "migrationStatus": "no_op",
+      "summary": "This explicit pre-public baseline resets live version truth and release archives without requiring managed-project migration for supported GDH targets.",
+      "releaseHighlights": {
+        "summary": "`v0.0.0` is the explicit live pre-public GDH baseline. It keeps the current bounded broader-internal support contract while reclassifying the older local `1.x` line as retained internal history so the first real public GDH release can begin cleanly at `0.1.0`.",
+        "operatorChanges": [
+          "The live GDH package and current-truth docs now use `0.0.0` as the explicit pre-public line instead of presenting the retained internal `1.x` history as the current public product story.",
+          "Older local release notes and migration artifacts now live under `docs/releases/internal/` and `docs/releases/migrations/internal/`, paired with retained `internal/v...` tags instead of public `v...` tags.",
+          "The generated root `CHANGELOG.md` now starts from the explicit pre-public baseline and points older retained history to the internal archive instead of mixing both stories in one current public-facing file.",
+          "The bounded support contract, package boundary, and maintainer release/publish workflow remain the same product behavior that was already exercised before the public-start reset."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "This explicit pre-public baseline resets live version truth and release archives without requiring managed-project migration for supported GDH targets. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.1.0",
+      "releaseTag": "v0.1.0",
+      "migrationStatus": "no_op",
+      "summary": "The first public GDH release line finalizes release and staged-package workflow truth without changing managed-project surfaces.",
+      "releaseHighlights": {
+        "summary": "`v0.1.0` is the first public GDH release line. It promotes the repo from the explicit `0.0.0` pre-public baseline to a real releasable line while keeping managed GDH project surfaces unchanged.",
+        "operatorChanges": [
+          "Release automation now distinguishes product-visible history from suppressed maintainer-only history, so generated SemVer bumps and `CHANGELOG.md` entries follow the product-only release policy.",
+          "Maintainers now have a guarded public-package workflow for `@skillcap/gdh` around `dist/publish/gdh`, `corepack yarn check:public-release`, and the explicit `/gdh-publish` handoff instead of publishing ad hoc from the repo root or `packages/cli`.",
+          "Current-truth docs, package metadata, and release archives are aligned around the first public line, while retained `1.x` history stays under `docs/releases/internal/` and `internal/v...` tags.",
+          "Preview for `v0.1.0` includes three product-visible commits (`abdb434`, `cbd662f`, and `1d2ab66`) while suppressing maintainer-only release, publish, planning, and handoff history from the generated changelog entry."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "The first public GDH release line finalizes release and staged-package workflow truth without changing managed-project surfaces. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.1.1",
+      "releaseTag": "v0.1.1",
+      "migrationStatus": "no_op",
+      "summary": "This patch release corrects live release truth and documents the scoped npm install contract without changing managed-project surfaces.",
+      "releaseHighlights": {
+        "summary": "`v0.1.1` is a patch follow-up to the first public GDH line. It keeps managed GDH project surfaces unchanged while correcting live release truth and making the scoped npm install path explicit for operators.",
+        "operatorChanges": [
+          "Current-truth docs now consistently describe the shipped line as `0.1.0` instead of leaving stale pre-public `0.0.0` references in live maintainer and planning surfaces.",
+          "Install guidance now names the published package explicitly as `@skillcap/gdh` while keeping the executable entrypoint as `gdh`.",
+          "The generated patch changelog for `v0.1.1` includes the scoped install guidance fix separately from the release-artifact maintenance needed to keep the live docs aligned with the first public line."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "This patch release corrects live release truth and documents the scoped npm install contract without changing managed-project surfaces. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.1.2",
+      "releaseTag": "v0.1.2",
+      "migrationStatus": "no_op",
+      "summary": "This patch release synchronizes live release truth with the shipped 0.1.1 line and adds maintainership guardrails without changing managed-project surfaces.",
+      "releaseHighlights": {
+        "summary": "`v0.1.2` is a patch follow-up that keeps the first public GDH line internally consistent after `v0.1.1`. It preserves the same managed-project contract while syncing the repo's live current-truth docs to the shipped line.",
+        "operatorChanges": [
+          "Live current-truth docs now consistently describe the shipped line as `0.1.1` across the root README, install guidance, runtime support docs, and planning surfaces that anchor the active support contract.",
+          "The local release and npm-publish workflow now has explicit maintainer guardrails against two previously observed failure modes: cutting a release while current-truth docs still describe the old line, and publishing from a branch that has moved ahead of the matching release tag.",
+          "The generated `v0.1.2` changelog remains intentionally narrow: the only product-visible history is the live-truth correction for the `0.1.1` line, while maintainer-only guardrail work stays suppressed from product release history."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "This patch release synchronizes live release truth with the shipped 0.1.1 line and adds maintainership guardrails without changing managed-project surfaces. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.2.0",
+      "releaseTag": "v0.2.0",
+      "migrationStatus": "required",
+      "summary": "Existing targets need gdh migrate --apply to regenerate guidance files with updated content (worktree import, process launch guidance) and add .gdh-state/ to .gitignore.",
+      "releaseHighlights": {
+        "summary": "`v0.2.0` is the first dogfooding-driven release. It addresses real issues found during the first GDH deployment on a production monorepo (nested Godot project at `apps/game/`, git worktrees, aseprite importers). Four fixes ship: CWD resolution, `.gitignore` hygiene, import error reporting, and worktree/process guidance.",
+        "operatorChanges": [
+          "**CWD resolution walk-up:** All GDH commands now walk up parent directories to find `.gdh/project.yaml`. Running `gdh status` from `apps/game/` inside a monorepo with `.gdh/` at the repo root now works correctly instead of returning misleading \"project_not_onboarded\".",
+          "**Setup gitignore:** `gdh setup` now adds `.gdh-state/` and `**/.gdh-state/` to the target project's `.gitignore`, preventing machine-local state (LSP instances, session logs, run artifacts) from being accidentally staged.",
+          "**Import refresh error reporting:** `gdh imports refresh` now captures Godot stdout and includes up to five stderr lines in the summary instead of only the first. The full process output is available in the `processOutput` field of the JSON result.",
+          "**Worktree import guidance:** Generated onboarding and authoring guidance now surfaces `gdh target prepare --source-target` for cold worktree hydration, and advises persistent background execution for Godot process launches."
+        ]
+      },
+      "updateContract": {
+        "summary": "Review and apply the release-specific migration after self-update.",
+        "steps": [
+          {
+            "id": "review_release_specific_migration",
+            "kind": "agent_reasoning",
+            "summary": "Review the migrate preview for this release line.",
+            "detail": "Existing targets need gdh migrate --apply to regenerate guidance files with updated content (worktree import, process launch guidance) and add .gdh-state/ to .gitignore. Inspect the surfaced compatibility reasons before deciding to apply.",
+            "commands": [
+              "gdh migrate"
+            ],
+            "validationCommands": []
+          },
+          {
+            "id": "apply_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Apply the release-specific migration and verify status.",
+            "detail": "Once the preview is acceptable, apply the migration and confirm the target returns to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.2.1",
+      "releaseTag": "v0.2.1",
+      "migrationStatus": "required",
+      "summary": "Corrective patch: existing targets need gdh migrate --apply to regenerate guidance files (version 1 to 2) and add .gdh-state/ to .gitignore. These actions should have shipped with v0.2.0.",
+      "releaseHighlights": {
+        "summary": "`v0.2.1` fixes the migration gap in `v0.2.0`. The v0.2.0 release incorrectly declared `migrationStatus: \"no_op\"` when existing targets actually needed guidance regeneration and `.gitignore` updates. This patch bumps the guidance version markers, makes `gdh migrate` regenerate stale guidance files and add `.gdh-state/` to `.gitignore`.",
+        "operatorChanges": [
+          "`gdh migrate` now detects outdated guidance files (version 1 → 2) and regenerates them with worktree import and process launch content.",
+          "`gdh migrate` now adds `.gdh-state/` and `**/.gdh-state/` to `.gitignore` if not already present.",
+          "Guidance version mismatch is now auto-migratable (`migration_needed`) instead of requiring manual review (`compatibility_degraded`)."
+        ]
+      },
+      "updateContract": {
+        "summary": "Review and apply the release-specific migration after self-update.",
+        "steps": [
+          {
+            "id": "review_release_specific_migration",
+            "kind": "agent_reasoning",
+            "summary": "Review the migrate preview for this release line.",
+            "detail": "Corrective patch: existing targets need gdh migrate --apply to regenerate guidance files (version 1 to 2) and add .gdh-state/ to .gitignore. These actions should have shipped with v0.2.0. Inspect the surfaced compatibility reasons before deciding to apply.",
+            "commands": [
+              "gdh migrate"
+            ],
+            "validationCommands": []
+          },
+          {
+            "id": "apply_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Apply the release-specific migration and verify status.",
+            "detail": "Once the preview is acceptable, apply the migration and confirm the target returns to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.3.0",
+      "releaseTag": "v0.3.0",
+      "migrationStatus": "required",
+      "summary": "MCP scope reduced to engine-only tools. 5 new agent workflow skills added. Run gdh migrate --apply for guidance/gitignore, then gdh setup --yes to install new skills.",
+      "releaseHighlights": {
+        "summary": "`v0.3.0` reshapes GDH's agent integration surface. MCP is now strictly for Godot engine interaction (11 tools). Project management workflows move to 5 new agent skills generated during `gdh setup` for Claude, Codex, and Cursor.",
+        "operatorChanges": [
+          "**5 new agent skills:** `/gdh-status`, `/gdh-migrate`, `/gdh-check`, `/gdh-prepare`, `/gdh-verify` — generated for all three supported agents during `gdh setup`.",
+          "**MCP scope reduction:** Removed 6 non-engine MCP tools (`status.get`, `guidance.resolve`, `verify.recommend`, `verify.done`, `verify.inspect`, `verify.readiness`). These workflows are now handled by agent skills + CLI.",
+          "**MCP retains 11 engine tools:** `docs.*`, `target.prepare`, `authoring.check`, `run-config.*`, `bridge.*`, `verify.run`.",
+          "Existing targets need `gdh setup --yes` re-run to pick up the new skills."
+        ]
+      },
+      "updateContract": {
+        "summary": "Review and apply the release-specific migration after self-update.",
+        "steps": [
+          {
+            "id": "review_release_specific_migration",
+            "kind": "agent_reasoning",
+            "summary": "Review the migrate preview for this release line.",
+            "detail": "MCP scope reduced to engine-only tools. 5 new agent workflow skills added. Run gdh migrate --apply for guidance/gitignore, then gdh setup --yes to install new skills. Inspect the surfaced compatibility reasons before deciding to apply.",
+            "commands": [
+              "gdh migrate"
+            ],
+            "validationCommands": []
+          },
+          {
+            "id": "apply_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Apply the release-specific migration and verify status.",
+            "detail": "Once the preview is acceptable, apply the migration and confirm the target returns to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.3.1",
+      "releaseTag": "v0.3.1",
+      "migrationStatus": "required",
+      "summary": "Same migration as v0.3.0 but now works from nested directories. Run gdh migrate --apply for guidance regen, gitignore, and skill installation.",
+      "releaseHighlights": {
+        "summary": "Fixes migrate and lifecycle compatibility to work from nested directories in monorepos. Corrects skill text and ensures adapter skills are always installed during migration.",
+        "operatorChanges": [
+          "`gdh migrate` now works from nested directories (e.g. `apps/game/`) by resolving the project root.",
+          "`gdh migrate --apply` now always installs/updates agent skills (not gated by narrow surface checks).",
+          "Fixed skill text that referenced non-existent `--dry-run` flag on migrate."
+        ]
+      },
+      "updateContract": {
+        "summary": "Review and apply the release-specific migration after self-update.",
+        "steps": [
+          {
+            "id": "review_release_specific_migration",
+            "kind": "agent_reasoning",
+            "summary": "Review the migrate preview for this release line.",
+            "detail": "Same migration as v0.3.0 but now works from nested directories. Run gdh migrate --apply for guidance regen, gitignore, and skill installation. Inspect the surfaced compatibility reasons before deciding to apply.",
+            "commands": [
+              "gdh migrate"
+            ],
+            "validationCommands": []
+          },
+          {
+            "id": "apply_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Apply the release-specific migration and verify status.",
+            "detail": "Once the preview is acceptable, apply the migration and confirm the target returns to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.3.2",
+      "releaseTag": "v0.3.2",
+      "migrationStatus": "required",
+      "summary": "Fixes migration to actually overwrite stale guidance files. Run gdh migrate --apply.",
+      "releaseHighlights": {
+        "summary": "Fixes `gdh migrate --apply` silently skipping guidance file overwrites. Stale guidance (version 1) was never actually written to version 2 during migration because the durable-truth guard blocked it.",
+        "operatorChanges": [
+          "`gdh migrate --apply` now correctly overwrites outdated guidance files during migration.",
+          "Previously, migration reported \"applied\" but files remained at version 1 on disk."
+        ]
+      },
+      "updateContract": {
+        "summary": "Review and apply the release-specific migration after self-update.",
+        "steps": [
+          {
+            "id": "review_release_specific_migration",
+            "kind": "agent_reasoning",
+            "summary": "Review the migrate preview for this release line.",
+            "detail": "Fixes migration to actually overwrite stale guidance files. Run gdh migrate --apply. Inspect the surfaced compatibility reasons before deciding to apply.",
+            "commands": [
+              "gdh migrate"
+            ],
+            "validationCommands": []
+          },
+          {
+            "id": "apply_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Apply the release-specific migration and verify status.",
+            "detail": "Once the preview is acceptable, apply the migration and confirm the target returns to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.4.0",
+      "releaseTag": "v0.4.0",
+      "migrationStatus": "no_op",
+      "summary": "Documentation truth and evidence hardening. No managed project surfaces changed.",
+      "releaseHighlights": {
+        "summary": "Documentation truth and evidence hardening milestone. Widens `validate:docs` to 39 checks, reorganizes product vision docs, introduces session-event contract, tiered corpus refresh, and YAML schema reference. Fixes ~20 stale claims across 10+ docs.",
+        "operatorChanges": [
+          "`validate:docs` expanded from 28 to 39 structural checks covering version alignment, cross-reference integrity, and temporal-language guards.",
+          "Product vision docs (`SPEC.md`, `PAIN-POINTS.md`) moved to `docs/product/` with staleness fixes and guardrails.",
+          "Dogfooding doc updated with session 2 findings and shipped backlog cleanup.",
+          "Session-event contract and tiered corpus refresh added to observability and runtime validation surfaces."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "Documentation truth and evidence hardening. No managed project surfaces changed. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.4.1",
+      "releaseTag": "v0.4.1",
+      "migrationStatus": "no_op",
+      "summary": "No managed project surface versions changed. The fix changes generated .mcp.json output from relative to absolute paths. Existing targets will see updated content on next gdh migrate --apply or gdh adapters install.",
+      "releaseHighlights": {
+        "summary": "Patch fix for MCP launcher path resolution in monorepo layouts. Generated `.mcp.json` now uses absolute paths so MCP servers start correctly regardless of agent CWD.",
+        "operatorChanges": [
+          "`.mcp.json` generated by `gdh setup`, `gdh migrate --apply`, and `gdh adapters install` now uses absolute paths for the launcher script and `--target` argument instead of relative paths.",
+          "Existing targets need `gdh migrate --apply` or `gdh adapters install` to regenerate `.mcp.json` with absolute paths."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "No managed project surface versions changed. The fix changes generated .mcp.json output from relative to absolute paths. Existing targets will see updated content on next gdh migrate --apply or gdh adapters install. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.5.0",
+      "releaseTag": "v0.5.0",
+      "migrationStatus": "required",
+      "summary": "GDH_PROJECT_CONFIG_VERSION bumped 2 -> 3 to carry the new gdh_version pinning field; GDH_MCP_LAUNCHER_VERSION bumped 1 -> 2 for the pinned-npx launcher body. Existing managed targets on v0.4.1 or earlier need `gdh migrate --apply` to backfill `gdh_version` into `.gdh/project.yaml` and regenerate the managed MCP launcher, Claude commands, Cursor rules, and Codex skills at the pinned version.",
+      "releaseHighlights": {
+        "summary": "Install, update, and release-plumbing milestone. Pins managed targets to an exact `gdh_version` in `.gdh/project.yaml` so MCP launchers, skills, and hooks all invoke the same version across sessions. Fixes the `npx -y @skillcap/gdh@<v> <subcmd>` invocation so fresh installs on npm 10.8.2+ stop failing with \"could not determine executable to run\". Bumps `GDH_PROJECT_CONFIG_VERSION` to 3 and `GDH_MCP_LAUNCHER_VERSION` to 2 — existing managed targets require `gdh migrate --apply`.",
+        "operatorChanges": [
+          "**`.gdh/project.yaml` adds a required `gdh_version` field** (EXACT_SEMVER) pinning the GDH product version. `gdh setup` emits it automatically; `gdh migrate --apply` backfills it on existing targets.",
+          "**Managed MCP launcher now invokes `npx -y @skillcap/gdh@<pinned> mcp serve`** — no more floating tags. Same pinning flows through Claude commands, Cursor rules, and Codex skills.",
+          "**`gdh setup` pre-warms the npx cache** for the pinned `gdh_version` so the first MCP handshake does not pay cold-start cost. Opt out with `GDH_SKIP_NPX_PREWARM=1`. Pre-warm failures are non-fatal.",
+          "**NPX invocation fix (CRITICAL)**: managed launchers and the `gdh setup` pre-warm now inject `cwd: targetPath` into every `npx` spawn, avoiding npm 10.8.2+ workspace-shadowing that made `npx -y @skillcap/gdh@<v> setup` fail with \"could not determine executable to run\" on fresh installs.",
+          "**`gdh migrate --apply`** now reports per-adapter-action `state: applied` in JSON output instead of stale `planned` after the apply loop runs.",
+          "**New `gdh verify drift` subcommand** compares the launcher's baked version against `.gdh/project.yaml`'s `gdh_version` to catch drift after partial updates.",
+          "**`gdh run-config` and `gdh verification-scenario` handlers** (7 surfaces: list, show, check, run under run-config; list, show under verification-scenario; plus `gdh verify run`) now resolve project root from nested subdirectories via `resolveProjectRoot` walk-up — same behavior as `gdh setup`.",
+          "**`gdh scan` persists `.gdh-state/inventory.json`** on onboarded targets and emits a `scan` session event; `gdh status` reads the cache first so `inventoryPresent`/`inventoryObservedAt` reflect disk truth after a successful scan.",
+          "**New canonical guidance doc `docs/agent/persistence-semantics.md`** documents the command → disk-effect table for `scan`, `onboard`, `status`. Registered as a guidance unit (`persistence_semantics`, `strength: required`) and cross-referenced from all 9 adapter skill renderers.",
+          "**Release plumbing (maintainer-facing)**: `release:apply` now rewrites live doc version refs, bumps `package.json`, writes `CHANGELOG.md`, and runs `check:public-release` against post-write state — no manual pre-bump edits, no env-var override. `publish:npm` accepts the release tag as an ancestor of HEAD (merge-to-main flow) instead of requiring `HEAD === tag`.",
+          "**Install bundle fully dropped**: npm tarball via `@skillcap/gdh` is the one production path. Operator docs carry no install-bundle framing. \"Install with npx, that's it.\""
+        ]
+      },
+      "updateContract": {
+        "summary": "Review and apply the release-specific migration after self-update.",
+        "steps": [
+          {
+            "id": "review_release_specific_migration",
+            "kind": "agent_reasoning",
+            "summary": "Review the migrate preview for this release line.",
+            "detail": "GDH_PROJECT_CONFIG_VERSION bumped 2 -> 3 to carry the new gdh_version pinning field; GDH_MCP_LAUNCHER_VERSION bumped 1 -> 2 for the pinned-npx launcher body. Existing managed targets on v0.4.1 or earlier need `gdh migrate --apply` to backfill `gdh_version` into `.gdh/project.yaml` and regenerate the managed MCP launcher, Claude commands, Cursor rules, and Codex skills at the pinned version. Inspect the surfaced compatibility reasons before deciding to apply.",
+            "commands": [
+              "gdh migrate"
+            ],
+            "validationCommands": []
+          },
+          {
+            "id": "apply_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Apply the release-specific migration and verify status.",
+            "detail": "Once the preview is acceptable, apply the migration and confirm the target returns to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.6.0",
+      "releaseTag": "v0.6.0",
+      "migrationStatus": "no_op",
+      "summary": "v0.6.0 ships forward-migration capability (`/gdh-update` skill, `gdh self-update` CLI, `bumpAndRebakePin` mechanics, update-detection surfaces across Claude/Cursor/Codex) but does not require any managed project migration. No existing surface contract was bumped: GDH_PROJECT_CONFIG_VERSION stays at 3, GDH_MCP_LAUNCHER_VERSION stays at 2, GDH_RUNTIME_BRIDGE_SURFACE_VERSION stays at 1. GDH_UPDATE_HOOK_VERSION=1 is a NEW additive constant for the new managed SessionStart-hook surface introduced by this release. Existing managed targets pinned at 0.5.0 continue to function unchanged; the new update-detection hints and self-update machinery are only exercised when an operator opts in via `gdh setup` or `gdh self-update`.",
+      "releaseHighlights": {
+        "summary": "v0.6.0 establishes the forward-migration contract: from this release onward, every shipped GDH version can migrate forward to npm latest through shipped commands, with no human edits to YAML or skill files. The release is anchored by four coordinated deliverables — update detection, migration mechanics, user-facing self-update surfaces, and a release-gating verification harness — that together close the gap a v1.8 dogfooding pass surfaced: the `rewriteProjectConfig` guard in `packages/cli/src/migrate.ts` only added `gdh_version` when missing, with no shipped path to bump an existing pin. v0.6.0 ships that path. Agent-First drives the default-latest behavior throughout: human intent is \"update GDH\"; the agent invokes `/gdh-update` (or `gdh self-update`); the CLI resolves npm latest and performs the transactional bump plus re-bake against `bumpAndRebakePin` from Phase 12. The dev-from-source escape hatch (`GDH_DEV_REPO` + `.gdh-state/local-paths.json`) is preserved and enforced at the mechanics layer so contributors are not affected.",
+        "operatorChanges": [
+          "**Update detection surfaces are live across all three adapters.** Claude SessionStart hook announces newer versions on session start (UPD-01); Claude statusline shows a stale-version indicator (UPD-02); Cursor and Codex MCP tool responses carry `_meta.gdh.updateAvailable` when newer versions are available (UPD-03); `gdh status` and `gdh verify` print an honest stderr banner with a `/gdh-update` hint when the pinned version lags npm latest (UPD-04). All surfaces degrade silently when npm is unreachable — no false positives, no command failures.",
+          "**`/gdh-update` slash command is the canonical agent-facing update entry point** across Claude, Cursor, and Codex (SELF-01). The rendered skill performs a preview-then-apply flow: it dry-runs, surfaces the planned version delta to chat context, applies without a blocking confirmation prompt (intent expressed in conversation is the approval), and chases the apply with `gdh verify drift` to confirm every baked surface reflects the new pin.",
+          "**`gdh self-update [version]` CLI subcommand defaults to npm latest** (SELF-02). Explicit positional version overrides the default for power-user paths. Idempotent re-runs with the same target are no-ops. Transactional: a partial failure during the apply is rolled back to the pre-apply state with no half-updated surfaces. Exposes `--dry-run` for the Phase 14 release harness and skill preview flows, and `--target <path>` for multi-target workstations.",
+          "**Dev-from-source escape hatch preserved end-to-end** (SELF-03). `GDH_DEV_REPO` or `.gdh-state/local-paths.json` signals dev mode; both `/gdh-update` and `gdh self-update` detect this at the mechanics layer inside `bumpAndRebakePin` and exit cleanly without modifying production-pin state.",
+          "**Pin-bump mechanics are now shipped as `bumpAndRebakePin` in `@gdh/adapters`** (MIG-01 / MIG-02). Updates an existing `gdh_version` field (not just adds when missing); `gdh migrate` stays pin-preserving. After the pin update, every managed surface (skills, launcher, MCP entries across all three adapters) is re-baked at the new pin in the same transactional sequence — either all baked at the new pin, or none and the filesystem is restored.",
+          "**Release pipeline now blocks publish when self-update is broken** (VERIF-01). A new forward-migration harness (`tests/integration/forward-migration.test.ts`) runs as step 6 of `corepack yarn check:public-release`, stages `fixtures/greenfield-minimal` pinned at `0.4.1`, and proves a clean end-to-end self-update cycle through the packed tarball. A broken self-update path halts the release chain before npm upload.",
+          "**New `test:forward-migration` npm script** for maintainers debugging the harness in isolation.",
+          "**Session-event contract gains a `self_update` kind** recorded non-blocking after every `gdh self-update` invocation with the from/to version pair and result state."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "v0.6.0 ships forward-migration capability (`/gdh-update` skill, `gdh self-update` CLI, `bumpAndRebakePin` mechanics, update-detection surfaces across Claude/Cursor/Codex) but does not require any managed project migration. No existing surface contract was bumped: GDH_PROJECT_CONFIG_VERSION stays at 3, GDH_MCP_LAUNCHER_VERSION stays at 2, GDH_RUNTIME_BRIDGE_SURFACE_VERSION stays at 1. GDH_UPDATE_HOOK_VERSION=1 is a NEW additive constant for the new managed SessionStart-hook surface introduced by this release. Existing managed targets pinned at 0.5.0 continue to function unchanged; the new update-detection hints and self-update machinery are only exercised when an operator opts in via `gdh setup` or `gdh self-update`. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.7.0",
+      "releaseTag": "v0.7.0",
+      "migrationStatus": "required",
+      "summary": "v0.7.0 retires the managed MCP launcher (`.gdh/bin/gdh-mcp.mjs`) across every shipped surface and replaces it with a portable `npx -y @skillcap/gdh@<pinned> mcp serve` invocation in committed MCP configs (`.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`). Targets onboarded before the lc1 stop-emit point still carry the legacy launcher file on disk; `gdh migrate --apply` now performs a one-shot idempotent cleanup via a new `retire_legacy_mcp_launcher` action of kind `delete_file`. `GDH_MCP_LAUNCHER_VERSION` is removed from `@gdh/core` as the underlying surface no longer exists. `GDH_PROJECT_CONFIG_VERSION` stays at 3 and `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1 — no schema or bridge contract was bumped.",
+      "releaseHighlights": {
+        "summary": "v0.7.0 replaces the managed MCP launcher indirection with a portable `npx -y @skillcap/gdh@<pin> mcp serve` invocation across every committed MCP config surface, adds a project-local `.codex/config.toml` so Codex teammates get zero-config clones in parity with Claude and Cursor, moves the contributor `GDH_DEV_REPO` escape hatch into the `gdh mcp serve` CLI entry itself, and retires the legacy `.gdh/bin/gdh-mcp.mjs` launcher from every shipped surface — including a new `gdh migrate --apply` step that cleans up the residual file on targets onboarded before the lc1 stop-emit point. The release closes the clone-portability regression that the quick-task 260416 absolute-path fix had introduced and removes the `GDH_MCP_LAUNCHER_VERSION` surface contract that the launcher retirement makes obsolete.",
+        "operatorChanges": [
+          "**Committed MCP configs are clone-portable.** Generated `.mcp.json`, `.cursor/mcp.json`, and `.codex/config.toml` now emit `command: \"npx\"`, `args: [\"-y\", \"@skillcap/gdh@<pinned>\", \"mcp\", \"serve\"]`. No absolute paths, no launcher indirection, no CWD dependence. Teammate clones receive byte-identical committed configs that resolve the CLI from PATH on each invocation.",
+          "**Codex gets a project-local `.codex/config.toml` by default.** `gdh setup --agent codex` now emits a managed `[mcp_servers.gdh]` section in `.codex/config.toml` at the repo root. Codex picks it up for trusted projects. The user-global `codex mcp add` path remains available behind `--user` and uses the same npx invocation shape. Existing user-authored TOML content is preserved via line-based section replacement.",
+          "**`GDH_DEV_REPO` contributor escape hatch now lives in `gdh mcp serve`.** Setting `GDH_DEV_REPO=<local-gdh-checkout>` (or persisting `gdhDevRepoPath` in `.gdh-state/local-paths.json`) redirects the MCP server to the local development checkout regardless of which agent spawned it. Three loop-prevention guards cover self-reexec, nested-checkout, and missing-hint cases.",
+          "**`gdh mcp serve --target` is now optional.** Omitting it defaults to `process.cwd()` and the existing `resolveEffectiveTargetPath` helper walks up to find `.gdh/project.yaml`. Works identically from repo root and monorepo subdirectories.",
+          "**Managed MCP launcher (`.gdh/bin/gdh-mcp.mjs`) is retired.** `gdh setup` and `gdh adapters install` no longer emit the launcher file. The status surface no longer flags its absence as drift or as `migration_needed`. Every source symbol (`renderManagedMcpLauncher`, `inspectLauncherFile`, `MCP_LAUNCHER_RELATIVE_PATH`, `inspectMcpLauncherLifecycleSurface`, `mcp_launcher` surface id, `launcher_file` adapter-surface kind) has been deleted.",
+          "**`gdh migrate --apply` cleans up the legacy launcher residue on pre-lc1 targets.** A new `retire_legacy_mcp_launcher` migration action of kind `delete_file` runs immediately after the gitignore step in `migrateProjectLifecycleSurface`. Idempotent — no-op when the file is absent. When present, deletes `.gdh/bin/gdh-mcp.mjs` and best-effort removes the empty `.gdh/bin/` parent directory. The `\"delete_file\"` variant is additive to `MigrationActionKind`.",
+          "**`GDH_MCP_LAUNCHER_VERSION` is removed from `@gdh/core` exports.** The version-contract doc and Check 40 of the docs validator were retracted to the two remaining constants (`GDH_PROJECT_CONFIG_VERSION`, `GDH_RUNTIME_BRIDGE_SURFACE_VERSION`). Historical release notes and migration manifests that mention `GDH_MCP_LAUNCHER_VERSION` remain untouched as frozen release artifacts.",
+          "**README + demo surface refreshed against the 9 README-quality criteria.** Requirements section added (Node ≥20, Godot 4.4–4.6, macOS), \"What GDH does not do\" scope block added, Support subsection links GitHub Issues and `CONTRIBUTING.md`, and `demo.tape` + `demo.gif` are re-rendered with the clean publishable tape."
+        ]
+      },
+      "updateContract": {
+        "summary": "Review and apply the release-specific migration after self-update.",
+        "steps": [
+          {
+            "id": "review_release_specific_migration",
+            "kind": "agent_reasoning",
+            "summary": "Review the migrate preview for this release line.",
+            "detail": "v0.7.0 retires the managed MCP launcher (`.gdh/bin/gdh-mcp.mjs`) across every shipped surface and replaces it with a portable `npx -y @skillcap/gdh@<pinned> mcp serve` invocation in committed MCP configs (`.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`). Targets onboarded before the lc1 stop-emit point still carry the legacy launcher file on disk; `gdh migrate --apply` now performs a one-shot idempotent cleanup via a new `retire_legacy_mcp_launcher` action of kind `delete_file`. `GDH_MCP_LAUNCHER_VERSION` is removed from `@gdh/core` as the underlying surface no longer exists. `GDH_PROJECT_CONFIG_VERSION` stays at 3 and `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1 — no schema or bridge contract was bumped. Inspect the surfaced compatibility reasons before deciding to apply.",
+            "commands": [
+              "gdh migrate"
+            ],
+            "validationCommands": []
+          },
+          {
+            "id": "apply_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Apply the release-specific migration and verify status.",
+            "detail": "Once the preview is acceptable, apply the migration and confirm the target returns to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.8.0",
+      "releaseTag": "v0.8.0",
+      "migrationStatus": "no_op",
+      "summary": "v0.8.0 ships the v1.10 milestone (Update-Flow Polish And CLI Path-Normalization) as a pure no-op for managed project surfaces. Changes are internal CLI-boundary normalization (Phase 15 ingress helpers + Path Contracts lint tripwire), probe-level update-cache coherence wiring (Phase 16), additive status/migrate-surface JSON fields (Phase 17 `blockingReasons`/`coupledReasons` split with union preserved, `mode: \"preview\" | \"applied\"` discriminant on `GdhMigrationResult`), an idempotent-friendly setup re-run path with a new `DurableTruthCollisionError` class and `detectExistingOnboarding` helper (Phase 18), and three new `validate:docs` README-quality checks (Phase 19). `GDH_PROJECT_CONFIG_VERSION` stays at 3, `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1, and `GDH_UPDATE_HOOK_VERSION` stays at 1 — no schema or bridge contract bumped. No new `MigrationActionKind` variants and no new migrate actions. Running `gdh migrate --apply` against a v0.7.0-migrated target remains a no-op on this release line.",
+      "releaseHighlights": {
+        "summary": "v0.8.0 closes the four verified P1/P2 bugs surfaced by the 0.6.0 → 0.7.0 TheBeacon dogfood and consumes the SEED-001 human-surface themes deferred from v1.9. 10 requirements landed across 5 phases (15–19): ingress-path normalization with a standing lint tripwire, update-flow polish that makes post-self-update state coherent across every surface, additive migrate-shape and status-surface UX improvements backed by a reusable recovery-hints map, an idempotent-friendly `gdh setup` re-run path, and three new `validate:docs` README-quality checks. No new runtime dependencies. `GDH_PROJECT_CONFIG_VERSION` stays at 3 and `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1 — no schema or bridge contract bumped.",
+        "operatorChanges": [
+          "**`targetPath` is absolute post-ingress — enforced at the boundary (Phase 15).** `parseSingleTargetPathArg` was extended and a new `parseOptionalPositionalTargetPath` helper added; roughly 33 inline CLI entry sites were swept onto the helpers. The Path Contracts invariant is committed in `docs/architecture/package-boundaries.md#path-contracts` and backed by a standing lint tripwire. Closes the 4th recurrence of the relative-path-at-boundary bug class. `gdh prepare` and friends now work from any subdirectory without double-resolving a relative path against the wrong base.",
+          "**Post-self-update state is coherent across every surface (Phase 16).** `readGdhUpdateMetaOrNull` now re-evaluates the live pin at probe time, and `invalidateGdhUpdateCache` is wired into the `bumpAndRebakePin` success branch so the stale-version banner clears across CLI, MCP `_meta.gdh.updateAvailable`, and the Claude statusline immediately after self-update. The CLI stale-version banner now carries a structured `pendingMigration` JSON field plus a stderr suffix, and the three `/gdh-update` skill renderers (Claude, Cursor, Codex) gained a step-5 narration that closes the self-update → migrate chain gap end-to-end.",
+          "**Additive migrate-shape and status-surface UX (Phase 17).** `GdhProjectLifecycleCompatibilityResult` now splits `blockingReasons` from `coupledReasons` (union preserved — no breaking consumers). A new `recovery-hints.ts` static map with 26 entries is consumed by all three adapter renderers and by the CLI JSON surface. `GdhMigrationResult` gains a `mode: \"preview\" | \"applied\"` discriminant plus a shared `PREVIEW_HEADER_LITERAL` so dry-run versus applied migrate output is structurally unambiguous.",
+          "**`gdh setup` is idempotent-friendly on re-run (Phase 18).** A new `DurableTruthCollisionError` class carries a typed `recoveryHint` payload; a new `detectExistingOnboarding` helper in `@gdh/scan` feeds the three-way recovery matrix (refresh / migrate / cancel). A 4-site spinner try/catch sweep keeps the Clack flow from leaving orphaned spinners on error, and `summarizePlannedActions` now dispatches on a tagged union (`action.kind` = `run_command` | `file_write` | summary fallback) instead of an ad-hoc branch ladder.",
+          "**Three new `validate:docs` README-quality checks (Phase 19).** The gate now enforces required structural sections, a length ceiling, and a canonical pinned-npx install path in `README.md`. Delivered as the autonomous DOC-01 slice: policy + paired validator in a single change."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "v0.8.0 ships the v1.10 milestone (Update-Flow Polish And CLI Path-Normalization) as a pure no-op for managed project surfaces. Changes are internal CLI-boundary normalization (Phase 15 ingress helpers + Path Contracts lint tripwire), probe-level update-cache coherence wiring (Phase 16), additive status/migrate-surface JSON fields (Phase 17 `blockingReasons`/`coupledReasons` split with union preserved, `mode: \"preview\" | \"applied\"` discriminant on `GdhMigrationResult`), an idempotent-friendly setup re-run path with a new `DurableTruthCollisionError` class and `detectExistingOnboarding` helper (Phase 18), and three new `validate:docs` README-quality checks (Phase 19). `GDH_PROJECT_CONFIG_VERSION` stays at 3, `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1, and `GDH_UPDATE_HOOK_VERSION` stays at 1 — no schema or bridge contract bumped. No new `MigrationActionKind` variants and no new migrate actions. Running `gdh migrate --apply` against a v0.7.0-migrated target remains a no-op on this release line. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.9.0",
+      "releaseTag": "v0.9.0",
+      "migrationStatus": "no_op",
+      "summary": "v0.9.0 adds repo-owned runtime-bridge proof surfaces: a dedicated bridge fixture, a real host-Godot baseline lane, an opt-in Docker/Xvfb graphical lane, and an additive `GDH_BRIDGE_BIND_HOST` seam in the managed bridge surface used only by that graphical harness. No managed-project schema version changed, `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1, and no new migrate action was introduced. Existing managed targets do not require `gdh migrate --apply` for this release line.",
+      "releaseHighlights": {
+        "summary": "v0.9.0 adds a real runtime-bridge proof harness to the GDH implementation repo: a dedicated `bridge-runtime-minimal` fixture, a real host-Godot baseline lane, and an opt-in Docker/Xvfb graphical lane that proves the shipped bridge entries end-to-end through the current runtime manager and MCP-facing surfaces. The release also adds an explicit `GDH_BRIDGE_BIND_HOST` seam to the managed bridge surface so the graphical test lane can publish the bridge port out of a container without widening GDH's shipped runtime-provider contract. The default `corepack yarn test` loop stays unchanged; the new harnesses live behind explicit `test:bridge` and `test:bridge:graphical` commands.",
+        "operatorChanges": [
+          "**New opt-in bridge proof commands.** `corepack yarn test:bridge` now runs the dedicated baseline runtime-bridge harness, and `corepack yarn test:bridge:graphical` runs the opt-in Docker/Xvfb graphical lane when `GDH_RUNTIME_BRIDGE_GRAPHICAL=1` is set locally.",
+          "**Dedicated bridge fixture and reusable test helpers.** The repo now carries `fixtures/bridge-runtime-minimal` with deterministic player movement and a committed project-owned `project.player.snapshot` bridge entry. Baseline and graphical lanes reuse the same assertion contract, so the bounded bridge surface is now proven against real Godot sessions instead of mock-only coverage.",
+          "**Explicit container reachability seam in the managed bridge surface.** `gdh_runtime_bridge.gd` now accepts optional `GDH_BRIDGE_BIND_HOST` (default still `127.0.0.1`). This is used only by the repo-owned graphical harness to publish the reserved bridge port out of Docker while preserving loopback-only default behavior for ordinary local runtime sessions.",
+          "**Bounded rollout documented in live docs.** Runtime support docs and runtime release-readiness docs now say explicitly that the Docker/Xvfb lane is test-only, non-default, and not screenshot support or a shipped Docker runtime provider."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "v0.9.0 adds repo-owned runtime-bridge proof surfaces: a dedicated bridge fixture, a real host-Godot baseline lane, an opt-in Docker/Xvfb graphical lane, and an additive `GDH_BRIDGE_BIND_HOST` seam in the managed bridge surface used only by that graphical harness. No managed-project schema version changed, `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1, and no new migrate action was introduced. Existing managed targets do not require `gdh migrate --apply` for this release line. Run the standard post-update drift verification and stop if status remains healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.10.0",
+      "releaseTag": "v0.10.0",
+      "migrationStatus": "no_op",
+      "summary": "v0.10.0 ships the v1.11 guided update and sequential migration flow. Runtime update preview now reads packaged release-span metadata, `gdh self-update --dry-run` emits structured `preview` data, `gdh self-update` apply now performs one ordered `update -> migrate -> validate` path, and adapter/generated guidance now follows explicit terminal-state truth. `GDH_PROJECT_CONFIG_VERSION` stays at 3, `GDH_UPDATE_HOOK_VERSION` stays at 1, `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1, and no new release-scoped migrate action is introduced. Existing managed targets do not require `gdh migrate --apply` specifically for the v0.10.0 release line.",
+      "releaseHighlights": {
+        "summary": "v0.10.0 turns GDH project updates into a guided, release-span-aware workflow. `gdh self-update --dry-run` and `/gdh-update` now surface the exact ordered release span, bounded changelog highlights, and the specific `mechanical`, `agent_reasoning`, and `manual_review` steps that apply before any disk mutation. After approval, `gdh self-update` now owns one ordered `update -> migrate -> validate` path and returns explicit terminal states instead of leaving the agent to infer whether the project is healthy, needs follow-up, requires manual review, or is blocked.",
+        "operatorChanges": [
+          "**Packaged release-span update contracts.** Every public release line from `0.0.0` through `0.9.0` now contributes machine-readable update metadata that ships in the npm package as `RELEASE-SPAN-UPDATE-CONTRACTS.json`. Runtime update preview no longer depends on raw repo-only release docs.",
+          "**Structured preview before apply.** `gdh self-update --dry-run` now returns a `preview` payload with current and target version, ordered release entries, bounded highlights, exact ordered steps, approval state, and step counts split by `mechanical`, `agent_reasoning`, and `manual_review`.",
+          "**One sequenced apply path with explicit terminal truth.** `gdh self-update` apply now chains pin bump, managed-surface rebake, lifecycle migrate, and validation, then returns additive `migration` and `terminal` contracts. Supported terminal states are `healthy`, `follow_up_required`, `manual_review_required`, and `blocked`.",
+          "**Renderer and guidance parity across adapters.** `/gdh-update`, `/gdh-migrate`, and generated `project-migration.md` now all narrate the same preview, approval, sequential apply, and terminal follow-through story across Claude, Cursor, and Codex.",
+          "**Release-gated multi-hop and package-boundary proof.** Forward-migration tests now cover true multi-hop update spans and packaged staged/tarball installs prove that shipped update metadata works outside the source checkout."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific migration is required after self-update.",
+        "steps": [
+          {
+            "id": "verify_no_release_specific_migration",
+            "kind": "mechanical",
+            "summary": "Verify drift stays clean for this release line.",
+            "detail": "v0.10.0 ships the v1.11 guided update and sequential migration flow. Runtime update preview now reads packaged release-span metadata, `gdh self-update --dry-run` emits structured `preview` data, `gdh self-update` apply now performs one ordered `update -> migrate -> validate` path, and adapter/generated guidance now follows explicit terminal-state truth. `GDH_PROJECT_CONFIG_VERSION` stays at 3, `GDH_UPDATE_HOOK_VERSION` stays at 1, `GDH_RUNTIME_BRIDGE_SURFACE_VERSION` stays at 1, and no new release-scoped migrate action is introduced. Existing managed targets do not require `gdh migrate --apply` specifically for the v0.10.0 release line. Run the standard post-update drift verification and follow any exact commands surfaced by the terminal contract if the project is not already healthy.",
+            "commands": [
+              "gdh verify drift"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}