Release v0.1.7

docs/RELEASE_DEPENDENCIES.md

@@ -111,10 +111,12 @@ scripts/push-release-tag.sh --version 0.1.6
 `ModuleManifest` objects while writing catalog entries. When a manifest is
 available, the catalog entry uses the manifest version, points package refs at
 `v<manifest.version>`, and copies `provides_interfaces` /
-`requires_interfaces` from the manifest. If a manifest cannot be discovered,
-the entry falls back to the release version passed with `--version` and omits
-interface metadata. This keeps the catalog aligned with independently
-versioned module packages instead of relying on a hardcoded compatibility table.
+`requires_interfaces` from the manifest. It also copies module migration order
+and `migration_tasks` metadata when present. If a manifest cannot be
+discovered, the entry falls back to the release version passed with `--version`
+and omits interface and migration-task metadata. This keeps the catalog aligned
+with independently versioned module packages instead of relying on a hardcoded
+compatibility table.
 
 The script also includes GovOPlaN roadmap/scaffold module repositories that do
 not yet have package metadata. Those repositories are committed, tagged, and
@@ -211,6 +213,21 @@ Each module entry can declare:
   or `destructive`
 - `migration_notes`, operator-facing data/migration guidance for review,
   forward-only, or destructive changes
+- `migration_after` and `migration_before`, explicit module ids used to order
+  module-owned migration heads when a release needs a live-data sequencing rule
+- `migration_tasks`, constrained live-data tasks that run around Alembic
+  migration phases. Each task declares `task_id`, `phase`, `summary`,
+  `task_version`, `safety`, `idempotent`, and optionally `timeout_seconds`.
+  The allowed phases are `pre_migration_check`, `pre_migration_prepare`,
+  `post_migration_backfill`, and `post_migration_verify`.
+- `current_version_min` and `current_version_max_exclusive`, the installed
+  version window from which this catalog target may be applied directly
+- `bridge_release` and `bridge_notes`, marking a target as an intermediate
+  compatibility release in a staged update path
+- `allow_downgrade` and `allow_same_version`, explicit opt-ins for reviewed
+  rollback or package-refresh plans
+- `recovery_tested` and `recovery_notes`, documenting the rehearsal for
+  forward-only or destructive data changes
 - `provides_interfaces`, named interface contracts exported by this module
 - `requires_interfaces`, named interface contracts and version ranges required
   by this module
@@ -282,8 +299,18 @@ Catalog provenance changes preflight severity:
   block activation before the installer runs
 - selected catalog entries whose target dependencies are neither installed nor
   planned block activation before the installer runs
+- catalog update targets older than the installed module version block unless
+  the catalog entry declares `allow_downgrade: true`
+- catalog update targets equal to the installed module version block unless the
+  catalog entry declares `allow_same_version: true`
+- catalog update targets with a `current_version_min` /
+  `current_version_max_exclusive` window block when the installed version is
+  outside that window; publish and apply a bridge release instead
 - catalog entries marked `forward_only` or `destructive` block activation until
   the plan row has an explicit data-safety acknowledgement
+- catalog entries marked `forward_only` or `destructive` also block unless the
+  catalog entry declares `recovery_tested: true` and either the catalog entry or
+  operator plan row contains recovery notes
 - catalog entries marked `destructive` also require catalog migration notes or
   operator notes describing the cleanup or retirement plan
 
@@ -298,12 +325,37 @@ activate the resulting set together.
 Install-plan rows support explicit `install`, `update`, and `uninstall`
 actions. Catalog planning writes `update` when the module is already installed.
 Preflight resolves the target set from installed manifests plus the planned
-catalog entries. Unplanned catalog entries are not treated as installed; when
-they would satisfy a missing dependency or named interface, preflight blocks
-activation with a companion-update issue so the operator can add them to the
-same plan. The preflight response also includes a structured `target_plan`
-summary with each planned module's action, current version, catalog target
-version, package refs, migration-safety level, and acknowledgement state.
+catalog entries. Unplanned catalog entries are not treated as installed. When a
+catalog entry would satisfy a missing dependency or named interface, preflight
+blocks activation with a companion-update issue; the admin catalog planner adds
+those companion rows automatically when it can resolve them from the current
+catalog. The preflight response also includes a structured `target_plan` summary
+with each planned module's action, current version, catalog target version,
+package refs, migration-safety level, current-version update window, bridge
+metadata, recovery metadata, and acknowledgement state.
+
+Database migrations are planned against that same target module set. When the
+installer is run with `--migrate`, it calls `govoplan_core.commands.init_db`
+with the target enabled modules rather than the pre-update startup module list,
+so newly installed module migration directories are discovered before
+activation. Preflight also returns a structured migration plan. Its step order is
+derived from:
+
+- manifest and catalog `migration_after` / `migration_before` declarations
+- module dependencies and optional dependencies when both modules are in the
+  target plan
+- named interface provider/consumer relationships when both sides are in the
+  target plan
+
+Preflight blocks cycles in that ordering graph. It also blocks non-idempotent
+module migration tasks, forward-only/destructive tasks without operator
+acknowledgement, and installed manifest tasks that declare no executor.
+Catalog-only task executors are marked as pending because they can only be
+confirmed after the target package is installed. The migrator runs pre-migration
+tasks, upgrades the ordered module heads first, finishes with Alembic `heads`,
+and then runs post-migration tasks, so Alembic's revision graph remains
+authoritative while GovOPlaN still gives operators a module-aware live-data
+order.
 
 This avoids circular "upgrade A first / upgrade B first" traps: named interface
 requirements are solved against the target set, not against each intermediate
@@ -330,15 +382,20 @@ modules with registered migrations as `requires_review` by default. Release
 authors should keep that value for ordinary reversible migrations, raise it to
 `forward_only` when database rollback requires restoring a snapshot, and raise
 it to `destructive` when the update removes or irreversibly rewrites persisted
-data. The admin install-plan UI exposes the safety level and lets operators
-record an explicit acknowledgement; preflight keeps acknowledged
-forward-only/destructive changes visible as warnings.
+data. Forward-only and destructive entries must include `recovery_tested: true`
+and recovery notes after a verified restore or forward-recovery rehearsal. The
+admin install-plan UI exposes the safety level and lets operators record an
+explicit acknowledgement; preflight keeps acknowledged forward-only/destructive
+changes visible as warnings.
 
 In practice, circular dependencies are avoided by designing interfaces with
 compatibility windows and by publishing bridge releases. A bridge release keeps
 the old interface while introducing the new one, allowing dependent modules to
 move first; a later release can retire the old interface after every dependent
-module has a compatible target version.
+module has a compatible target version. Use `current_version_min` and
+`current_version_max_exclusive` to make those direct-update windows explicit in
+the catalog, and set `bridge_release: true` on intermediate targets that exist
+primarily to carry installations safely across a compatibility gap.
 
 Trusted catalog keys are configured locally: