100%

Section 02 - harness migration registry + consumer-pin contract (INV-7b)

Goal

Generalize the plan_corpus migration pattern to the harness: a scripts/harness_dist/migrations/ directory with auto-discovery (VERSION / DESCRIPTION / up), latest_registered_version(), HARNESS_MIGRATIONS populated from it (today empty, version.py:153), harness_migrate_or_refuse (version.py:168) wired to the registry, and a --health drift subcommand that asserts CURRENT == latest_registered and surfaces consumer-pin drift. A consumer N versions behind is brought fully current by deterministic, ordered migration.

Implementation Sketch

  • New scripts/harness_dist/migrations/__init__.py mirroring scripts/plan_corpus/migrations/__init__.py:102-148 (introspect each module for VERSION/DESCRIPTION/up, reject duplicate VERSIONs, sorted list, latest_registered_version).
  • Wire HARNESS_MIGRATIONS (version.py:153) from the registry; harness_migrate_or_refuse (version.py:168-241) already implements migrate-forward / refuse-downgrade (HarnessDowngradeError) and is called pre-write at apply.py:522 — extend it to consult the registry.
  • --health subcommand in scripts/harness_dist/__main__.py asserting the integrity invariant + reporting consumer-pin drift (mirror the plan_corpus --health/pin_drift shape; the harness gets its OWN, not the intel-envelope one).
  • The consumer-pin contract: a breaking change registers a numbered migration BEFORE the version bump lands, else a stale consumer cannot advance and apply refuses (the existing refusal at apply.py:522).

Spec & Rule References

INV-7 (mission). scripts/plan_corpus/migrate.py:run_migrate + migrations/__init__.py are the SSOT pattern. script-first.md §10.

Layer Coverage

Tooling-scope: L1-L11 N/A. L12 = --health + migrate run on a stale-pin fixture consumer. pytest gate: scripts/harness_dist/tests/test_version.py (registry + integrity) + test_migrations.py (new).

Work Items

  • Add scripts/harness_dist/migrations/init.py with VERSION/DESCRIPTION/up auto-discovery + latest_registered_version (mirror plan_corpus).
  • Wire HARNESS_MIGRATIONS + harness_migrate_or_refuse to the registry; add a —health drift subcommand.
  • Prove a stale-pin consumer is brought current by ordered migration; apply refuses a missing-migration advance.

Fresh intel (regenerated)

{ “schema_version”: 1, “target”: { “kind”: “plan-section”, “ref”: “installable-harness/s-8b79c54e” }, “generated_at”: “2026-06-25T13:49:24.980122+00:00”, “graph_state”: { “head_sha”: “b74d6b9a”, “last_code_import_at”: “2026-06-25T13:46:15.824Z”, “embedding_stale”: false, “insights_stale”: false, “cpg_stale”: false }, “surfaces”: {}, “summary”: “intel-package[plan-section:installable-harness/s-8b79c54e] agent-authored dossier”, “degraded”: false, “dossier”: { “objective_symbols”: [], “tiers”: {}, “agent_authored”: true, “difficulty”: { “class”: “routine”, “research_online”: false, “research_mode”: “auto”, “signals”: [], “plan_dir”: “/home/eric/projects/ori_lang/plans/installable-harness” } } }

(full dossier: migration-registry-pin—s-8b79c54e.intel.json)