From 9f6c19b4ed8b2e4f62f1d58eee67cc542baa82f9 Mon Sep 17 00:00:00 2001 From: Alan Szmyt Date: Mon, 31 Aug 2026 11:34:44 -0400 Subject: [PATCH] Plan safe repository presentation rollout --- .github/workflows/validate.yml | 16 + ARCHITECTURE.md | 28 +- README.md | 28 +- ROADMAP.md | 21 +- docs/repository-presentation-rollout.md | 147 +++ .../repository-presentation.inventory.json | 1151 +++++++++++++++++ schemas/README.md | 4 + ...tory-presentation-inventory-v1.schema.json | 156 +++ ...epository-presentation-plan-v1.schema.json | 48 + ...itory-presentation-proposal-v1.schema.json | 53 + ...ository-presentation-review-v1.schema.json | 34 + scripts/plan_repository_presentation.py | 535 ++++++++ tests/test_repository_presentation_rollout.py | 196 +++ 13 files changed, 2401 insertions(+), 16 deletions(-) create mode 100644 docs/repository-presentation-rollout.md create mode 100644 examples/repository-presentation.inventory.json create mode 100644 schemas/repository-presentation-inventory-v1.schema.json create mode 100644 schemas/repository-presentation-plan-v1.schema.json create mode 100644 schemas/repository-presentation-proposal-v1.schema.json create mode 100644 schemas/repository-presentation-review-v1.schema.json create mode 100644 scripts/plan_repository_presentation.py create mode 100644 tests/test_repository_presentation_rollout.py diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index cc029a1..4e6dd61 100644 --- a/.github/workflows/validate.yml +++ b/.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 diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 89b8135..adc88b7 100644 --- a/ARCHITECTURE.md +++ b/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? diff --git a/README.md b/README.md index 861d315..a23b1e1 100644 --- a/README.md +++ b/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. diff --git a/ROADMAP.md b/ROADMAP.md index fc3ebd6..efb3fa5 100644 --- a/ROADMAP.md +++ b/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.