Plan the safe README presentation rollout

.github/workflows/validate.yml

@@ -44,6 +44,22 @@ jobs:
           examples/pace.lock.json
           --as-of "2026-08-22T00:00:00Z"
 
+      - name: Validate repository-presentation fleet inventory
+        run: >-
+          python3 scripts/plan_repository_presentation.py
+          validate-inventory
+          --inventory "examples/repository-presentation.inventory.json"
+
+      - name: Prove deterministic no-write fleet planning
+        shell: bash
+        run: |
+          plan_path="${RUNNER_TEMP}/repository-presentation.plan.json"
+          python3 scripts/plan_repository_presentation.py plan \
+            --inventory "examples/repository-presentation.inventory.json" \
+            --output "${plan_path}"
+          python3 scripts/plan_repository_presentation.py verify-plan \
+            --plan "${plan_path}"
+
       - name: Run adversarial validator tests
         run: >-
           python3 -m unittest discover

ARCHITECTURE.md

@@ -8,7 +8,7 @@ status: provisional
 owners:
   - egohygiene
 created: 2026-08-19
-updated: 2026-08-21
+updated: 2026-08-31
 governed_by:
   - architecture-architecture
 depends_on:
@@ -75,6 +75,23 @@ updaters. It reads one lock, validates immutable provenance, ownership,
 compatibility, rollback, and exception time bounds, and emits evidence without
 network or write capabilities.
 
+## Implemented repository-presentation planning slice
+
+```text
+examples/repository-presentation.inventory.json  # privacy-safe observed fleet snapshot
+schemas/repository-presentation-*-v1.schema.json  # inventory, plan, review, proposal contracts
+scripts/plan_repository_presentation.py           # deterministic no-write planner and review gate
+tests/test_repository_presentation_rollout.py     # privacy, integrity, and authority evidence
+docs/repository-presentation-rollout.md           # operator workflow and rollback boundary
+```
+
+The planner is a pure adapter over checked observed state. It has no GitHub
+client, credential input, consumer filesystem access, or pull-request write
+port. Its proposal output binds one repository, represented commit, README blob,
+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.
+
 ## Dependency rules
 
 - Sibling domain capabilities integrate through versioned public contracts, not direct access to internals.
@@ -98,10 +115,11 @@ The architecture favors independently usable local and self-hosted operation. Op
 
 ## Evidence and uncertainty
 
-- **Observed:** Pace owns a versioned dependency-lock schema, six-kind example,
-  standalone offline validator, adversarial test suite, and least-privilege CI
-  gate. Update resolution, drift detection, planning, and application remain
-  unimplemented.
+- **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.
 - **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,8 +29,30 @@ 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 repository-presentation rollout
+
+Pace now owns a read-only, privacy-safe repository-presentation inventory and a
+deterministic fleet planner. The checked snapshot classifies every repository,
+defines the Mantle/Identity/Antidote canary wave, reports blockers and drift,
+and requires an exact reviewed plan plus pinned Egolint evidence before it can
+emit one credential-free repository proposal.
+
+```bash
+python3 scripts/plan_repository_presentation.py validate-inventory \
+  --inventory "examples/repository-presentation.inventory.json"
+python3 scripts/plan_repository_presentation.py plan \
+  --inventory "examples/repository-presentation.inventory.json" \
+  --output "/tmp/repository-presentation.plan.json"
+python3 scripts/plan_repository_presentation.py verify-plan \
+  --plan "/tmp/repository-presentation.plan.json"
+```
+
+See the [rollout contract and operating guide](docs/repository-presentation-rollout.md).
+
 ## Current authority boundary
 
-Pace v1 validates desired state only. It does not resolve updates, edit files,
-open pull requests, or apply changes. Future detection, planning, application,
-verification, and publication phases remain separate authority boundaries.
+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.

ROADMAP.md

@@ -8,7 +8,7 @@ status: provisional
 owners:
   - egohygiene
 created: 2026-08-19
-updated: 2026-08-24
+updated: 2026-08-31
 governed_by:
   - architecture-roadmap
 depends_on:
@@ -40,7 +40,7 @@ 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:** Add observed-state capture and a drift report before attempting the reviewable convergence plan tracked by issue #2.  
+**Current gate:** Review issue #14's no-write repository-presentation fleet plan, then unblock and independently approve its three canaries before any consumer PR.  
 **North-star outcome:** Reviewable fleet convergence from declared desired state, observed state, and explicit drift.
 
 ### Visual roadmap publication
@@ -96,7 +96,8 @@ issues: []
 
 **Current evidence:**
 
-- No observed-state implementation was found.
+- A bounded, privacy-safe repository-presentation inventory now records all 29 repositories and explicit adoption states.
+- General-purpose observed-state collection remains unimplemented.
 
 <!-- roadmap-step
 id: PAC-Q03
@@ -118,7 +119,8 @@ issues: []
 
 **Current evidence:**
 
-- No drift engine or report was observed.
+- Issue #14 implements deterministic repository-presentation drift categories and an Observatory-safe projection.
+- The general cross-capability drift engine remains planned.
 
 <!-- roadmap-step
 id: PAC-Q04
@@ -140,7 +142,8 @@ issues: [2]
 
 **Current evidence:**
 
-- Issue #2 is the identified next planning gate.
+- 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.
 
 <!-- roadmap-step
 id: PAC-Q05
@@ -162,7 +165,8 @@ issues: []
 
 **Current evidence:**
 
-- No observed-state, drift, or fleet pilot evidence was found.
+- A 29-repository public-safe snapshot and Mantle/Identity/Antidote canary wave now exist.
+- Every canary is honestly blocked on Identity artifacts, reviewed facts, and pinned Egolint evidence; operator approval and consumer writes remain pending.
 
 <!-- roadmap-step
 id: PAC-Q06
@@ -278,8 +282,9 @@ Optional managed services, enterprise controls, marketplaces, and the conversati
 ## Evidence and uncertainty
 
 - **Observed:** Pace owns `egohygiene.pace.lock/v1`, an offline validator,
-  adversarial exception and provenance tests, a six-kind example, and a CI gate.
-  No updater or repository mutation path exists.
+  and a bounded repository-presentation inventory/planner with explicit review,
+  proposal, rollback, privacy, and Observatory contracts. No updater or
+  repository 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?

docs/repository-presentation-rollout.md

@@ -0,0 +1,147 @@
+# Repository-presentation fleet rollout
+
+Pace reconciles repository presentation in two distinct authority phases:
+
+1. read-only inventory, deterministic planning, and human review;
+2. one credential-free proposal per repository, followed by separately authorized
+   pull-request creation.
+
+The planner never edits a consumer repository or calls GitHub. A generated
+proposal is an integrity-bound handoff to an authorized operator, not a fleet
+write.
+
+## Immutable contract set
+
+| Owner | Version | Revision |
+| --- | --- | --- |
+| Hygiene repository-presentation profile | 1.0.0-alpha.1 (proposed) | `cb2ed63425d29abada2d2bbb43a3b3e59d11aeb8` |
+| Identity presentation package | 1.0.0 | `3c2fd3141371b355628e81f66f63159f19d63338` |
+| Holon presentation blueprint | 1.0.0 | `4d436b631ea82c463d3a6a04b5664633f3c64b4c` |
+| Egolint presentation validator | 0.1.0-alpha.1 | `4efe92a2609b3384fcf3b5cda343a4f64d108824` |
+
+The Hygiene profile remains proposed. Inventory or rollout does not activate it
+and cannot manufacture a passing evidence state.
+
+## Reviewed fleet snapshot
+
+`examples/repository-presentation.inventory.json` records every repository
+visible to the linked organization installation on 2026-08-31. Every entry is
+explicitly `eligible`, `deferred`, `exempt`, `blocked`, or
+`not_applicable`.
+
+The public artifact contains no private README digest, represented commit, facts,
+or exception prose. The private repository is deferred to a separately
+authorized private plan.
+
+The first canary wave is:
+
+| Role | Repository | Why |
+| --- | --- | --- |
+| Small tool | `egohygiene/mantle` | Exercises the CLI profile and preserves a substantial existing README. |
+| Customized | `egohygiene/identity` | Exercises a deeply customized source repository and visual ownership boundary. |
+| Publication/product | `egohygiene/antidote` | Exercises publication semantics and an incubating product/research surface. |
+
+The observed canaries are currently blocked. They lack a complete consumer-local
+Identity package, reviewed repository fact source, and current pinned Egolint
+report. This is actionable drift, not a template placeholder and not a rollout
+failure.
+
+## Generate the exact dry-run plan
+
+Validate the checked inventory:
+
+    python3 scripts/plan_repository_presentation.py validate-inventory \
+      --inventory "examples/repository-presentation.inventory.json"
+
+Generate a deterministic plan without credentials or consumer writes:
+
+    python3 scripts/plan_repository_presentation.py plan \
+      --inventory "examples/repository-presentation.inventory.json" \
+      --output "/tmp/repository-presentation.plan.json"
+
+Verify it independently:
+
+    python3 scripts/plan_repository_presentation.py verify-plan \
+      --plan "/tmp/repository-presentation.plan.json"
+
+The plan reports each repository's declared state, blockers, drift, represented
+commit, Egolint state, rollback binding, wave, and privacy-safe Observatory
+projection. Repeated runs over identical inventory bytes produce the same
+inventory and plan digests.
+
+## Unblock one repository
+
+A repository becomes eligible only after all of the following are observed at
+one represented commit:
+
+- a consumer-local, immutable Identity package and manifest;
+- complete, reviewed repository-owned presentation facts;
+- an exact README Git blob identity;
+- a valid report from the pinned Egolint revision; and
+- no unresolved profile or merge blocker.
+
+Holon must then create the exact preview plan. Pace records its checksum and
+never asks Holon to force an overwrite. Existing authored README prose remains
+outside Holon's checksum-bound managed region.
+
+Update the inventory in a new reviewable Pace pull request. The changed
+represented commit supersedes every earlier plan and proposal.
+
+## Review authorization and proposal
+
+Plan review is an explicit document, not an implicit CLI flag:
+
+    {
+      "schema": "egohygiene.pace.repository-presentation-review/v1",
+      "planDigest": "<exact reviewed plan digest>",
+      "reviewer": "szmyty",
+      "reviewedAt": "2026-08-31T16:00:00Z",
+      "decision": "approved"
+    }
+
+Only then can Pace produce a proposal:
+
+    python3 scripts/plan_repository_presentation.py propose \
+      --plan "/tmp/repository-presentation.plan.json" \
+      --review "/tmp/repository-presentation.review.json" \
+      --repository "egohygiene/mantle" \
+      --output "/tmp/mantle.repository-presentation.proposal.json"
+
+Proposal creation fails closed when the review digest, inventory, represented
+commit, Identity package, facts, README blob, or Egolint evidence is missing or
+stale. The proposal contains no token and grants no GitHub authority.
+
+An authorized operator may turn one proposal into one small pull request. Canary
+repositories are proposed independently; no all-or-nothing fleet branch exists.
+
+## Verification after merge
+
+A consumer adoption is not complete until its merged represented commit records:
+
+- consumer CI success;
+- Holon render verification;
+- the pinned Egolint report;
+- local banner and badge file integrity;
+- alt and fallback text;
+- local and canonical links;
+- badge evidence destination and represented commit; and
+- a fresh inventory observation showing no managed-region drift.
+
+Observatory receives only adoption state, profile, freshness, drift categories,
+and bounded exception metadata. Pace deliberately emits `healthScore: null`;
+presentation polish is not a universal health score.
+
+## Retry, supersession, and rollback
+
+A proposal ID binds repository and represented commit, so retrying unchanged
+input is idempotent. A new represented commit or inventory creates new digests
+and supersedes the proposal.
+
+Each proposal records the previous README Git blob and represented commit.
+Rollback restores the reviewed README and Holon state together. Holon refuses
+rollback after unreviewed README drift; Pace must then create a new observation
+and plan rather than force replacement.
+
+Deferred, exempt, private, archived, and not-applicable repositories remain
+visible in later inventories. Archived repositories are never reopened solely
+for visual consistency.