docs: bound repository hygiene at release and installation

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.

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.

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).