From 2e09d1f641ac555737dad70eb09d1991c7cc3567 Mon Sep 17 00:00:00 2001 From: DJConnect Date: Tue, 8 Sep 2026 23:30:30 +0200 Subject: [PATCH] docs: preserve release and installer authority in repository hygiene --- .../REPOSITORY_HYGIENE_RELEASE_BOUNDARY.md | 75 +++++++++++++++++++ docs/roadmap/PROJECT_HYGIENE_V1.md | 23 ++++++ docs/roadmap/README.md | 17 +++++ 3 files changed, 115 insertions(+) create mode 100644 docs/architecture/REPOSITORY_HYGIENE_RELEASE_BOUNDARY.md create mode 100644 docs/roadmap/PROJECT_HYGIENE_V1.md diff --git a/docs/architecture/REPOSITORY_HYGIENE_RELEASE_BOUNDARY.md b/docs/architecture/REPOSITORY_HYGIENE_RELEASE_BOUNDARY.md new file mode 100644 index 0000000..bf5fe09 --- /dev/null +++ b/docs/architecture/REPOSITORY_HYGIENE_RELEASE_BOUNDARY.md @@ -0,0 +1,75 @@ +# Repository hygiene at release and installation boundaries + +## Decision and owner + +Increment: `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1`. +Documentation/roadmap target only; no installer behavior, source scanner, registry +policy or cleanup permission is activated here. + +Forge owns project-wide [hygiene/reconciliation](https://github.com/pcvantol/forge/blob/main/docs/architecture/PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION.md); +EP owns repository observation and admitted cleanup. Forge Platform remains the +qualified artifact composer/installer, under the [ownership matrix](OWNERSHIP_MATRIX.md), +[evidence-gated composition](EVIDENCE_GATED_COMPONENT_COMPOSITION.md) and +[existing delivery authority](DELIVERY_AUTHORITY_AND_PROMOTION_GATES.md). + +## Scope-specific input, not a universal release veto + +A repository-hygiene assessment is an input bound to a selected repository, +source revision, release/composition operation, observation scope/freshness, +case/decision references and relevant unresolved conflicts. It is not evidence +that an artifact exists, that its bytes match, or that an external CD gate passed. + +Only applicable source/operation risks block: for example an active conflicting +writer on the selected source, unexplained candidate changes or unavailable +mandatory evidence. An old retained branch unrelated to the chosen artifact +does not prohibit a release. A closed case for one branch is not proof that the +whole repository contains no unexplained work. Partial/unknown scope stays +visible rather than converted into a blanket healthy signal. + +Full native hygiene scanning is not a new prerequisite for first Forge/EP +canary or every existing package install. If policy requires an assessment, +validate its exact supported contract and required coverage. Unknown or stale +required evidence blocks the dependent operation; missing optional evidence is +a warning, not fabricated success or a global halt. + +## Artifact and repository lifecycles remain separate + +Deleting a source branch must not delete an installed wheel, publication receipt, +release provenance, rollback artifact or archive needed to recover old work. +Published component pins continue to bind actual artifact digest, source revision +and qualification. A later branch state does not silently retarget those pins. + +Conversely, installing/updating/uninstalling Forge, EP or Workspace must not prune +project refs/worktrees, erase cases/receipts, reset grants/budgets or activate a +cleanup profile. Product-owned data-root backup/migration and installer cache +retention are different contracts. No installer recursive-clean command is a +substitute for EP repository cleanup. + +If repository cleanup affects a source/recovery object referenced by an active +release, retain it until the owning release/retention requirements are resolved. +Forge Platform can report such dependencies through authenticated owner contracts; +it cannot write a Forge ledger or EP CENTRAL record directly. + +## Capability composition and external authority + +Distributions declare only genuinely implemented/qualified observation, +reconciliation, command/readback and UI contracts. Installing a newer product +version does not itself grant repository write/delete scope. Observe-only profiles +may operate without mutation capability; unsupported mutation stays unavailable. +No full Agent fleet, Workspace UI or native Forge releaseplanner is smuggled in +as a requirement for a single-host read-only slice. + +Existing project/organization CD retains approval, deployment credentials and +rollback. A hygiene report, Workspace confirmation or version match cannot +satisfy that separate authority. No duplicate CD approval or direct deploy path +is introduced by this increment. + +## Qualification and roadmap + +The [scoped roadmap](../roadmap/PROJECT_HYGIENE_V1.md) joins after qualified producer/consumer +facts and cleanup semantics where those are actually composed. Required tests: +exact source/operation/digest binding; unrelated retained branch does not block; +relevant stale conflict does; optional unavailable scan remains a warning; +source-ref cleanup preserves artifact/rollback provenance; install/uninstall +cannot delete project data; unsupported peer contract is explicit; external CD +gates remain enforced. No implementation or installed qualification is claimed. diff --git a/docs/roadmap/PROJECT_HYGIENE_V1.md b/docs/roadmap/PROJECT_HYGIENE_V1.md new file mode 100644 index 0000000..28391d3 --- /dev/null +++ b/docs/roadmap/PROJECT_HYGIENE_V1.md @@ -0,0 +1,23 @@ +# Forge Platform repository-hygiene composition roadmap + +Increment: `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1`. +Owning design: [Repository hygiene at release/installation boundaries](../architecture/REPOSITORY_HYGIENE_RELEASE_BOUNDARY.md). +Parent: [Forge Platform roadmap](README.md). +Coordinated [documentary DAG](https://github.com/pcvantol/forge/blob/main/docs/roadmap/project-hygiene-v1.json). + +`HY-P` is PLANNED composition qualification after the relevant Forge/EP `HY-Q` +contracts are qualified. It is not a new package, scanner, release gate for every +artifact, or prerequisite to the first serial autonomy canary. Workspace UI and +general Agent fleet support are not prerequisites for a bounded composition. + +Acceptance: bind applicable assessment to selected source/repository/operation; +retain unrelated branches without blocking release; block genuine relevant stale +conflicts; report partial optional scope; preserve artifact/rollback provenance; +keep installer state cleanup separate from project repository cleanup; enforce +actual supported capabilities and existing external CD authority. + +An observation-only composition does not claim mutation support. Installation +must not enable automatic deletion or alter scopes/grants. Runtime activation +requires real owner-supported contracts, policy and operator authorization, +separate from this documentation delivery. Existing published component-manifest +and product-source/installer trust gates remain unchanged. diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md index efaf5c2..83b8b89 100644 --- a/docs/roadmap/README.md +++ b/docs/roadmap/README.md @@ -2,6 +2,23 @@ This directory is the canonical roadmap location for Forge Platform's cross-product composition product. Architecture remains authoritative for ownership, trust, topology, and runtime boundaries; roadmaps state intent, maturity, sequencing, and qualification work without changing those decisions. +## Repository hygiene and release scope — documented target + +The coordinated `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1` increment +adds the [repository-hygiene release/install boundary](../architecture/REPOSITORY_HYGIENE_RELEASE_BOUNDARY.md) +and [HY-P composition roadmap](PROJECT_HYGIENE_V1.md). +Forge reasons about project-wide branch/case evidence; EP owns host facts and +admitted cleanup. Forge Platform may consume an applicable source/operation-bound +assessment but does not become a scanner, cleanup executor or CD authority. + +HY-P is PLANNED after relevant Forge/EP HY-Q qualification. Optional read-only +composition remains distinct from mutation support. Retained unrelated branches +do not block every release; actual relevant conflicts and required stale evidence +do. Installer/update/uninstall must not delete project refs or runtime case/ +receipt history. All artifact/publisher/rollback and external CD gates remain +independent. No new first-canary predecessor, executable DAG, package version, +workflow, grant, runtime activation or actual cleanup is changed here. + ## Canonical entrypoints - [Forge Platform MVP 1.0](MVP_1_0.md) — product boundary, capability waves, a two-chain DAG that joins only at `MVP_1_0_RELEASE_READY`, the B8 → B8C → B8D → B9 → `STANDALONE_EP_VERIFIED` → `EP_EXTRACTION_CUTOVER_COMPLETE` transition gates, and separate post-verification lanes (CENTRAL relocation, EP self-hosting, and bounded multi-repository parallel execution).