Implement reviewed fleet convergence

.github/workflows/validate.yml

@@ -60,6 +60,18 @@ jobs:
           python3 scripts/plan_repository_presentation.py verify-plan \
             --plan "${plan_path}"
 
+      - name: Prove reviewed general fleet convergence planning
+        shell: bash
+        run: |
+          plan_path="${RUNNER_TEMP}/fleet-convergence.plan.json"
+          python3 scripts/plan_fleet_convergence.py plan \
+            --manifest "examples/convergence/fleet.manifest.json" \
+            --catalog "examples/convergence/catalog.json" \
+            --observatory "examples/convergence/observatory.snapshot.json" \
+            --output "${plan_path}"
+          python3 scripts/plan_fleet_convergence.py verify-plan \
+            --plan "${plan_path}"
+
       - name: Run adversarial validator tests
         run: >-
           python3 -m unittest discover
@@ -76,4 +88,4 @@ jobs:
           set -euo pipefail
           while IFS= read -r document; do
             python3 -m json.tool "${document}" >/dev/null
-          done < <(find examples schemas -type f -name "*.json" -print | sort)
+          done < <(find contracts examples schemas -type f -name "*.json" -print | sort)

ARCHITECTURE.md

@@ -8,7 +8,7 @@ status: provisional
 owners:
   - egohygiene
 created: 2026-08-19
-updated: 2026-08-31
+updated: 2026-09-02
 governed_by:
   - architecture-architecture
 depends_on:
@@ -92,6 +92,29 @@ Egolint report, reviewed plan, immutable contract set, and rollback snapshot.
 An external authorized operator may consume that artifact only after the review
 boundary; application remains outside this slice.
 
+## Implemented fleet convergence slice
+
+```text
+Hygiene catalog + Holon manifest + Pace current/desired locks
+                         +
+          Observatory organization-health snapshot
+                         |
+                         v
+ deterministic drift -> ordered repository units -> exact review
+                         |
+                         v
+        bounded candidate verification -> one upgrade PR
+```
+
+`scripts/plan_fleet_convergence.py` activates the general inventory reader,
+desired-state resolver, drift engine, reconciliation planner, and a deliberately
+narrow GitHub adapter. Observatory supplies observation; Pace does not scan.
+Holon supplies exact generated-file plans and rendering; Pace verifies the
+resulting candidate rather than reproducing the materializer. The adapter can
+create one non-default branch and pull request only when the remote base still
+equals the represented commit and the local diff exactly equals the reviewed
+allowlist. Merge remains outside the adapter.
+
 ## Dependency rules
 
 - Sibling domain capabilities integrate through versioned public contracts, not direct access to internals.
@@ -115,11 +138,11 @@ The architecture favors independently usable local and self-hosted operation. Op
 
 ## Evidence and uncertainty
 
-- **Observed:** Pace owns a versioned dependency-lock validator plus a bounded
-  repository-presentation inventory, deterministic drift/plan projection,
-  exact review authorization, credential-free single-repository proposal,
-  adversarial tests, and least-privilege CI gate. General update resolution and
-  every consumer write/application path remain unimplemented.
+- **Observed:** Pace owns a versioned dependency-lock validator, a general
+  deterministic convergence planner, exact partial-fleet review records,
+  bounded candidate verification, an idempotent one-PR GitHub adapter, and the
+  specialized repository-presentation rollout planner. It consumes pinned
+  sibling contracts and does not merge or mutate a default branch.
 - **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
 - **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
 - **Open question:** Which parts of this draft should become active in the first independently versioned release?

README.md

@@ -29,6 +29,28 @@ See the complete [lock and update policy](LOCK_POLICY.md), the
 [JSON Schema](schemas/pace-lock-v1.schema.json), and the
 [six-kind example](examples/pace.lock.json).
 
+## Plan reviewed fleet convergence
+
+The general convergence path consumes Hygiene catalog membership, Holon
+foundation intent, current and desired Pace locks, and Observatory's current
+represented state. It produces deterministic dependency-ordered drift before
+any write and requires an exact review for each repository-sized upgrade unit.
+
+```bash
+python3 scripts/plan_fleet_convergence.py plan \
+  --manifest "examples/convergence/fleet.manifest.json" \
+  --catalog "examples/convergence/catalog.json" \
+  --observatory "examples/convergence/observatory.snapshot.json" \
+  --output "/tmp/fleet-convergence.plan.json"
+
+python3 scripts/plan_fleet_convergence.py verify-plan \
+  --plan "/tmp/fleet-convergence.plan.json"
+```
+
+After review, `propose` prepares one credential-free PR request and `open-pr`
+accepts only an exact candidate tree on the still-current represented commit.
+See the [fleet convergence contract and operator guide](docs/fleet-convergence.md).
+
 ## Plan repository-presentation rollout
 
 Pace now owns a read-only, privacy-safe repository-presentation inventory and a
@@ -51,8 +73,8 @@ See the [rollout contract and operating guide](docs/repository-presentation-roll
 
 ## Current authority boundary
 
-Pace validates desired locks and can now turn a reviewed repository-presentation
-inventory into a deterministic no-write fleet plan. It may emit a credential-free
-single-repository proposal only after exact plan review and valid pinned Egolint
-evidence. It still does not edit consumer files, open pull requests, or apply
-changes; those remain separately authorized authority boundaries.
+Pace validates desired locks and can turn pinned catalog, Holon, lock, and
+Observatory inputs into deterministic no-write fleet plans. After an exact
+human review, it can verify a locally materialized candidate and open one
+bounded consumer pull request. It never scans repositories, renders Holon
+outputs, updates a default branch, or merges a pull request.

ROADMAP.md

@@ -8,7 +8,7 @@ status: provisional
 owners:
   - egohygiene
 created: 2026-08-19
-updated: 2026-08-31
+updated: 2026-09-02
 governed_by:
   - architecture-roadmap
 depends_on:
@@ -40,7 +40,8 @@ updated: 2026-08-24
 > This evidence-reconciled snapshot is the issue-generation and visual-roadmap handoff. The longer-horizon strategy below remains canonical context; generated HTML, JSON, progress, issue plans, and commit lists are projections.
 
 **Lifecycle:** seed implementation  
-**Current gate:** Review issue #14's no-write repository-presentation fleet plan, then unblock and independently approve its three canaries before any consumer PR.  
+**Current gate:** Review PAC-02's general convergence contracts and bounded PR adapter, while issue #14 separately unblocks its three presentation canaries.
+
 **North-star outcome:** Reviewable fleet convergence from declared desired state, observed state, and explicit drift.
 
 ### Visual roadmap publication
@@ -78,72 +79,75 @@ issues: []
 
 <!-- roadmap-step
 id: PAC-Q02
-status: active
+status: complete
 depends_on: [PAC-Q01]
 issues: []
 -->
 #### PAC-Q02 — Capture observed state
 
-**State:** `active`  
+**State:** `complete`
+
 **Depends on:** `PAC-Q01`
 
 **Outcome:** Pace can record what is actually deployed without mutating it.
 
 **Exit criteria:**
 
-- [ ] An observed-state schema and collector are implemented.
-- [ ] Fixtures prove stable normalization of at least one representative fleet.
+- [x] Pace consumes Observatory's pinned organization-health schema instead of adding a second collector.
+- [x] Fixtures prove stable ingestion of represented fleet state and block stale or ambiguous evidence.
 
 **Current evidence:**
 
-- A bounded, privacy-safe repository-presentation inventory now records all 29 repositories and explicit adoption states.
-- General-purpose observed-state collection remains unimplemented.
+- Observatory PR #15 provides the read-only organization-health contract.
+- Pace pins that contract and binds the exact catalog bytes, snapshot ID, freshness, and represented commit into every plan.
 
 <!-- roadmap-step
 id: PAC-Q03
-status: planned
+status: complete
 depends_on: [PAC-Q02]
 issues: []
 -->
 #### PAC-Q03 — Render actionable drift
 
-**State:** `planned`  
+**State:** `complete`
+
 **Depends on:** `PAC-Q02`
 
 **Outcome:** Desired and observed states produce a deterministic, human-reviewable drift report.
 
 **Exit criteria:**
 
-- [ ] Additions, removals, and changes are distinguished.
-- [ ] Repeated runs on unchanged input are identical.
+- [x] Additions, removals, and changes are distinguished.
+- [x] Repeated runs on unchanged input are identical.
 
 **Current evidence:**
 
-- Issue #14 implements deterministic repository-presentation drift categories and an Observatory-safe projection.
-- The general cross-capability drift engine remains planned.
+- PAC-02 compares complete current and desired Pace lock entries and explains categorical risk.
+- The canonical plan digest binds inputs, dependency order, drift, risk, blockers, and rollback state.
 
 <!-- roadmap-step
 id: PAC-Q04
-status: planned
+status: complete
 depends_on: [PAC-Q03]
 issues: [2]
 -->
 #### PAC-Q04 — Create a reviewable convergence plan
 
-**State:** `planned`  
+**State:** `complete`
+
 **Depends on:** `PAC-Q03`
 
 **Outcome:** Issue #2 yields an ordered plan with explicit risk, ownership, and rollback information.
 
 **Exit criteria:**
 
-- [ ] The plan is generated without applying changes.
-- [ ] Each action links to the drift that caused it.
+- [x] The plan is generated without applying changes.
+- [x] Each action links to the drift that caused it.
 
 **Current evidence:**
 
-- Issue #14 now proves an exact no-write plan, plan digest, review record, supersession boundary, and one-repository proposal contract for repository presentation.
-- Issue #2 remains the broader convergence-planning gate.
+- PAC-02 emits topologically ordered repository units with full before/after lock entries, risk reasons, exact review records, and partial-fleet selection.
+- One reviewed unit can verify one bounded candidate and open one non-default-branch PR; merge remains human-owned.
 
 <!-- roadmap-step
 id: PAC-Q05
@@ -206,8 +210,8 @@ This roadmap describes capability evolution, not promised dates or an issue queu
 
 ## Phase 1: Define desired and observed state schemas
 
-**Status:** Desired dependency lock v1 is implemented and independently
-validated. Observed-state and drift schemas remain planned for Phase 2.
+**Status:** Desired dependency lock v1 and pinned Observatory ingestion are
+implemented and independently validated.
 
 **Outcome:** A bounded capability advances from documented intent to validated, independently usable behavior.
 
@@ -221,6 +225,9 @@ validated. Observed-state and drift schemas remain planned for Phase 2.
 
 ## Phase 2: Implement read-only drift
 
+**Status:** Implemented for current and desired Pace locks with explainable risk
+and fail-closed Observatory freshness.
+
 **Outcome:** A bounded capability advances from documented intent to validated, independently usable behavior.
 
 **Exit signals:**
@@ -233,6 +240,9 @@ validated. Observed-state and drift schemas remain planned for Phase 2.
 
 ## Phase 3: Generate reviewable reconciliation plans
 
+**Status:** Implemented with deterministic dependency order, exact-digest
+reviews, blockers, pause state, and partial-fleet approval.
+
 **Outcome:** A bounded capability advances from documented intent to validated, independently usable behavior.
 
 **Exit signals:**
@@ -245,6 +255,9 @@ validated. Observed-state and drift schemas remain planned for Phase 2.
 
 ## Phase 4: Apply bounded changes
 
+**Status:** Implemented only for one exact candidate tree and one pull request.
+Default-branch writes, force, and merge remain unavailable.
+
 **Outcome:** A bounded capability advances from documented intent to validated, independently usable behavior.
 
 **Exit signals:**
@@ -282,9 +295,9 @@ Optional managed services, enterprise controls, marketplaces, and the conversati
 ## Evidence and uncertainty
 
 - **Observed:** Pace owns `egohygiene.pace.lock/v1`, an offline validator,
-  and a bounded repository-presentation inventory/planner with explicit review,
-  proposal, rollback, privacy, and Observatory contracts. No updater or
-  repository mutation path exists.
+  general fleet convergence contracts, exact review and rollback anchors, a
+  bounded one-PR adapter, and a specialized repository-presentation planner.
+  No default-branch or merge mutation path exists.
 - **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
 - **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
 - **Open question:** Which parts of this draft should become active in the first independently versioned release?

SYSTEM.md

@@ -8,7 +8,7 @@ status: provisional
 owners:
   - egohygiene
 created: 2026-08-19
-updated: 2026-08-21
+updated: 2026-09-02
 governed_by:
   - architecture-system
 depends_on:
@@ -34,13 +34,13 @@ This document identifies Pace's logical systems and responsibilities. It answers
 | --- | --- | --- |
 | Desired-state lock contract | Active | Records immutable source identity, content digest, target ownership, compatibility, rollback, and bounded exceptions for six dependency kinds. |
 | Independent lock validator | Active | Validates lock structure and semantics offline without trusting an updater or receiving write authority. |
-| Repository inventory reader | Target | Owns its bounded portion of the repository adoption, reconciliation, synchronization, and conformance mechanism for the Ego Hygiene organization; exposes explicit inputs, outputs, failure states, and evidence. |
-| Desired-state resolver | Target | Owns its bounded portion of the repository adoption, reconciliation, synchronization, and conformance mechanism for the Ego Hygiene organization; exposes explicit inputs, outputs, failure states, and evidence. |
-| Drift engine | Target | Owns its bounded portion of the repository adoption, reconciliation, synchronization, and conformance mechanism for the Ego Hygiene organization; exposes explicit inputs, outputs, failure states, and evidence. |
-| Reconciliation planner | Target | Owns its bounded portion of the repository adoption, reconciliation, synchronization, and conformance mechanism for the Ego Hygiene organization; exposes explicit inputs, outputs, failure states, and evidence. |
-| Change applier | Target | Owns its bounded portion of the repository adoption, reconciliation, synchronization, and conformance mechanism for the Ego Hygiene organization; exposes explicit inputs, outputs, failure states, and evidence. |
+| Repository inventory reader | Active | Joins Hygiene membership to pinned Holon, Pace lock, and Observatory inputs without scanning repositories. |
+| Desired-state resolver | Active | Validates desired locks and binds repository intent to the matching foundation manifest. |
+| Drift engine | Active | Distinguishes lock additions, removals, and updates with deterministic risk reasons. |
+| Reconciliation planner | Active | Emits topologically ordered repository units with blockers, rollback anchors, source digests, and an exact review gate. |
+| Change applier | Active, bounded | Verifies one local candidate against one reviewed unit and opens one non-default-branch pull request; never merges. |
 | Override registry | Target | Owns its bounded portion of the repository adoption, reconciliation, synchronization, and conformance mechanism for the Ego Hygiene organization; exposes explicit inputs, outputs, failure states, and evidence. |
-| Reporting adapter | Target | Owns its bounded portion of the repository adoption, reconciliation, synchronization, and conformance mechanism for the Ego Hygiene organization; exposes explicit inputs, outputs, failure states, and evidence. |
+| Reporting adapter | Active | Publishes machine-readable fleet plans, PR proposals, and PR results with explicit coverage and failure state. |
 
 ## External systems
 
@@ -63,9 +63,10 @@ Systems fail closed at destructive, publication, privacy, and security boundarie
 
 ## Evidence and uncertainty
 
-- **Observed:** Desired-state lock validation is active. Repository inventory,
-  drift, planning, application, override storage, and reporting remain target
-  systems.
+- **Observed:** Desired-state lock validation and the general catalog/manifest/
+  lock/Observatory convergence path are active. Application is restricted to
+  one exact reviewed candidate PR. A durable override registry beyond explicit
+  paused manifest state and lock exceptions remains a target system.
 - **Decided for this draft:** The repository owns the bounded concern described here and participates through versioned contracts.
 - **Proposed:** Target systems and later roadmap phases remain proposals until accepted and implemented.
 - **Open question:** Which parts of this draft should become active in the first independently versioned release?

contracts/holon.foundation-materialization.v1.lock.json

@@ -0,0 +1,22 @@
+{
+  "contracts": [
+    "https://egohygiene.io/schemas/holon/foundation-manifest.v1.schema.json",
+    "holon.materialization-plan/v1"
+  ],
+  "source_commit": "cd15eea31300997ce05a99d1a0bedc9c3437a8cc",
+  "source_repository": "https://github.com/egohygiene/holon",
+  "sources": [
+    {
+      "path": "schemas/foundation-manifest.v1.schema.json",
+      "sha256": "405a88a0df1b2d77ed534bdc65e833d61764883f93f5ef2c6042858bed0c9069"
+    },
+    {
+      "path": "schemas/materialization-plan.v1.schema.json",
+      "sha256": "7be8cd77ff41540889470937956e19b142077aa4721d62e205b2c3c2183845bd"
+    }
+  ],
+  "versions": {
+    "foundation_manifest": "1.0.0",
+    "materialization_plan": "holon.materialization-plan/v1"
+  }
+}

contracts/hygiene.repository-catalog.v1.lock.json

@@ -0,0 +1,16 @@
+{
+  "contract": "egohygiene.hygiene.repository-catalog/v1",
+  "source_commit": "28f9d6c7519d820644572634ba4476614f418d83",
+  "source_repository": "https://github.com/egohygiene/hygiene",
+  "sources": [
+    {
+      "path": "catalog/repositories.yaml",
+      "sha256": "e1193c772640ceb8d3d569a1826d3931ee9de64b0a8357a94c9f03fbceab52e5"
+    },
+    {
+      "path": "schemas/repository-catalog.v1.schema.json",
+      "sha256": "3a06f19e8c0be6590223b04f580aef7ee9c9b23bcb11e8b3da3db6dd1e764724"
+    }
+  ],
+  "version": "1.0.0"
+}

contracts/observatory.organization-health.v1.lock.json

@@ -0,0 +1,12 @@
+{
+  "contract": "egohygiene.observatory.organization-health/v1",
+  "source_commit": "a4526ba65a4ec1110ad9f2f47dc866a0c6d2c5a3",
+  "source_repository": "https://github.com/egohygiene/observatory",
+  "sources": [
+    {
+      "path": "schemas/organization-health.v1.schema.json",
+      "sha256": "4f61ece1f744f5fc8dda519305c43de4a855f3368b8eb7508d066b3bc2103af9"
+    }
+  ],
+  "version": "1.0.0-alpha.1"
+}