docs: define repository observation and safe cleanup boundaries

docs/development/ENGINEERING_PLATFORM_ROADMAP.md

@@ -1,5 +1,26 @@
 # Engineering Platform Roadmap
 
+## Repository observation and safe cleanup — documented target
+
+The coordinated `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1` increment
+adds [EP-owned observation and safe cleanup](../engineering/REPOSITORY_HYGIENE_AND_SAFE_CLEANUP.md)
+and the [HY-E/HY-C/HY-Q roadmap](PROJECT_HYGIENE_V1_ROADMAP.md).
+EP owns fresh host/provider facts and actual scoped cleanup; Forge owns
+project-wide cases and reasoning; Workspace presents requests/decisions.
+Own-run finalization cleanup does not require a Forge Mission or online UI.
+
+`HY-0 -> HY-E -> HY-C -> HY-Q` is the local documentary lane; HY-Q also consumes
+Forge HY-F/HY-S. All implementation/qualification remains PLANNED. Reuse existing
+admission, providers, leases and finalization rather than add a second queue or
+arbitrary-shell execution mode. Mutation requires current actor/scope, exact
+expected state, no active owner, retention and conditional provider safety.
+Semantic supersession, branch age and a merged PR alone are not delete authority.
+
+Cleanup warnings preserve proven delivery; protected/unknown-owned work and
+ignored/untracked runtime state remain retained. The full hygiene family is not
+a new first-canary or global release gate. No package, schema, workflow, grant,
+budget, active programme or installed-state change is made by this document set.
+
 ## Policy governance and effective assurance profiles — documented target
 
 The coordinated `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1` increment adds
@@ -357,7 +378,7 @@ Forge may consume canonical EP readiness/status/result/evidence APIs but must no
 | `EP::P_NEUTRAL_V1` | No active generic DJConnect platform identity/authority. | MERGED / CLOSED; completion evidence `b44af091`. |
 | `EP::P_INSTALLER_V1` | Reproducible standalone Server-side EP install/repair/update boundary; excludes Forge/Workspace/general Agent productization. | CURRENT AUTONOMY FRONTIER. |
 | `EP::STANDALONE_EP_VERIFIED` | One independent installed governed DJConnect execution with canonical evidence. | AFTER P-INSTALLER-V1 + DJConnect canary. |
-| `EP::SELF_HOSTED_ENGINEERING_VERIFIED` | Installed EP executes a real bounded Engineering Platform source change through CENTRAL. | IMMEDIATE POST-STANDALONE dogfood gate. |
+| `EP::SELF_HOSTED_ENGINEERING_VERIFIED` | Installed EP executes a real bounded Engineering Platform self-development Action through CENTRAL. | IMMEDIATE POST-STANDALONE dogfood gate. |
 | `EP::PROJECT_ATTACHMENT_AND_ADMISSION_V1` | Consumer-facing attachment/admission hardening beyond current B8R runtime. | FOLLOW-ON consumer qualification. |
 | `EP::ENGINEERING_CONTRACT_FOUNDATION_V1` | Rich DoR/DoD/Human-Gate/Action-quality producer contract. | Long-term Forge producer contract. |
 
@@ -391,4 +412,4 @@ This historical milestone marker is retained for documentation-contract compatib
 
 Platform code must not acquire DJConnect runtime, Home Assistant, branding or repository-name dependencies. Historical evidence and explicitly bounded migration compatibility may retain names without retaining authority.
 
-The planned home deployment of one authoritative Forge installation, one authoritative EP installation and one primary execution host on a Mac mini is a deployment profile, not a product-wide singleton invariant.
+The planned home deployment of one authoritative Forge installation, one authoritative EP installation and one primary execution host on a Mac mini is a deployment profile, not a product-wide singleton invariant.

docs/development/PROJECT_HYGIENE_V1_ROADMAP.md

@@ -0,0 +1,33 @@
+# EP Project Hygiene V1 roadmap
+
+Increment: `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1`.
+Owning design: [Repository observation and safe cleanup](../engineering/REPOSITORY_HYGIENE_AND_SAFE_CLEANUP.md).
+Parent: [EP Roadmap](ENGINEERING_PLATFORM_ROADMAP.md).
+Coordinated [DAG](https://github.com/pcvantol/forge/blob/main/docs/roadmap/project-hygiene-v1.json)
+is documentary; EP retains its own implementation/admission authority.
+
+| Node | EP deliverable | Dependencies | Status |
+| --- | --- | --- | --- |
+| HY-0 | Shared documented boundary, adopted in owning EP main | Owning documentation merges | DOCUMENTATION_ONLY |
+| HY-E | Scoped observation/provider contracts, freshness and coverage | HY-0 | PLANNED |
+| HY-C | Safe own-run primitives reused for typed project-maintenance commands, current authority/ref checks, retention and durable per-target receipts | HY-E | PLANNED |
+| HY-Q | Forge/EP cross-contract qualification of actual cleanup and recovery; no Mission fiction or delivery downgrade | Forge HY-F/HY-S, EP HY-C | PLANNED |
+
+HY-E first proves metadata observation without hooks, checkout mutation, second
+queue or direct consumer SQL. HY-C then proves the separate mutation boundary:
+actor/scope, no active owner, exact expected refs, protected targets, ignored-file
+and runtime preservation, conditional external mutation and verified retention.
+Use actual existing provider/lease/finalization services; no generalized Agent
+fleet is required for a single-host implementation.
+
+HY-Q must include ambiguous squash/supersession, stale proposal, new branch commit,
+external writer, duplicate request, wrong project, denied/expired capability,
+archive failure, partial remote/local effects and restart/lost-ack tests. Unsupported
+atomic provider operations remain unavailable rather than getting a dangerous
+fallback. Own-run cleanup remains usable without Forge or Workspace online.
+
+All non-documentation nodes are PLANNED. This increment does not activate a
+command route, grant, database schema or schedule and changes no package version.
+It is not a new gate before the first serial installed canary. Existing required
+EP safety checks remain mandatory; only actual relevant conflicts block later
+admission. A completed delivery plus cleanup warning is not changed to FAILED.

docs/engineering/REPOSITORY_HYGIENE_AND_SAFE_CLEANUP.md

@@ -0,0 +1,161 @@
+# Repository observation and safe cleanup
+
+## Decision and authority
+
+Increment: `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1`.
+This is an EP-owned documentation/roadmap target, canonical only on owning main.
+No command, schema, API, runtime policy, grant or scheduled scan is implemented
+or activated by this change. The coordinating Forge
+[design](https://github.com/pcvantol/forge/blob/main/docs/architecture/PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION.md)
+does not transfer EP execution authority.
+
+Reuse [Execution Host](EXECUTION_HOST_ARCHITECTURE.md) application services,
+canonical Git/GitHub providers, admission, resource exclusion, finalization and
+[effective policy](POLICY_GOVERNANCE_AND_ASSURANCE_PROFILES.md). Existing own-run
+cleanup remains a lifecycle concern, not a new Forge Mission or a dependency on
+Forge/Workspace availability. Product capability targets are
+`EP::REPOSITORY_OBSERVATION_V1` and `EP::SCOPED_REPOSITORY_CLEANUP_V1`.
+
+Forge owns project-wide interpretation/cases/proposals; the repository provider
+owns remote facts/protection; EP owns host facts and actual mutation. Workspace
+is a human interface. Product/organization CD, registry retention and installer
+state are not acquired through repository cleanup.
+
+## Two bounded seams, not a second execution engine
+
+**Observation** provides authenticated project/repository-scoped snapshots and
+incremental events/readback through declared EP interfaces. It may expose ref
+identities/object IDs, PR/delivery bindings, host/worktree state, leases and
+ownership evidence with timestamps, freshness, collection bounds and coverage.
+Missing host coverage, unknown local provenance, inaccessible provider pages,
+shallow history and unavailable protection facts remain explicit unknowns.
+No implicit filesystem walk across unregistered repositories or execution of
+repository hooks/tests. A qualified read-only collector may use an isolated
+mirror; it does not mutate the user's checkout to manufacture a clean snapshot.
+
+**Maintenance cleanup** is a closed set of typed operations for a local ref,
+remote ref or EP-owned worktree. It reuses current admission/lease/provider and
+receipt infrastructure. It is not an arbitrary-shell endpoint, another queue,
+a new engineering mode or a fabricated Action/run. A parent run, Mission or
+Forge case may be a correlation reference; a real scoped operator command may
+exist without a Mission. A necessary new contract must be versioned and qualified
+before exposure; this document does not assert that a current endpoint accepts it.
+
+EP's own finalizer uses the same safe primitives for its actual run resources.
+A project-wide caller cannot claim finalizer privileges by sending a run ID.
+
+## Logical command and receipt contract
+
+Required command semantics (not an implemented schema): contract version,
+operation ID, authenticated actor/delegation reference, project/repository and
+provider identity, operation kind, exact target identities, expected ref object
+IDs/worktree inventory revision, proposal and observation digests, decision and
+effective-policy references, retention/recovery prerequisites and bounded scope.
+Each target has its own outcome. Identifiers and paths are strictly validated;
+no wildcard, recursive deletion root, caller-selected shell or caller-asserted actor.
+
+Persist accepted command intent before external side effects. Same operation ID
+and canonical payload recovers the same operation; different payload conflicts.
+Recheck current authority before any outstanding side effect even on retry.
+A receipt records actual actor, command/policy/proposal binding, observed before
+and after state, expected and actual object IDs, provider result, retained recovery
+reference, timestamps and partial/denied/unknown outcomes. No secrets or source
+contents in operational logs. “Not found” does not by itself prove our deletion.
+Consumer readback is project-scoped, durable and restart-safe. Maintenance
+outcomes are not fabricated engineering terminal receipts or merge commits.
+
+## Eligibility and mutation boundary
+
+All applicable conditions must hold, not merely one:
+
+1. The real actor has current permission for this operation, repository and
+   target; read/producer/push access alone is insufficient. Remote-ref delete,
+   local-ref delete and worktree removal are distinct privileges. Read-only
+   reconciliation does not imply any of them.
+2. Ownership is verified from EP lifecycle/provider evidence or explicit bounded
+   adoption. A branch prefix, age, author display string or Forge model assertion
+   is not ownership. Standalone EP operation still uses its own approved policy.
+3. No conflicting active run, Action, PR, checkout user, lease or required
+   recovery resource claims the target. Incomplete coverage denies unattended
+   mutation, not reads. The finalizer retains its own valid run/cleanup lease
+   while cleaning that run's proven-delivered resources; that coordinating lease
+   is not a conflicting owner. Do not release it early to pass this check or
+   treat unfinished implementation as completed cleanup work. A separate
+   maintenance operation cannot borrow this exception from another run.
+4. Default/main/release/protected refs and tags are excluded by this capability.
+   Retention/legal holds and active release-source/installer references win over
+   cleanup preferences. Changing these exclusions is separate governance.
+5. Delivery/reconciliation is current for the exact branch head. A merged PR
+   covers its delivered head, not later commits. Ancestry-only and semantic
+   equivalence are distinguished; semantic acceptance never replaces authority.
+6. Required recovery objects/bundles exist, are integrity-verified, accessible
+   under controlled retention, and preserve unmerged/superseded history before
+   destructive cleanup. Missing backup evidence blocks that target. Do not
+   create release-triggering refs or expose private source as an archive.
+7. Local worktree inspection includes tracked, untracked AND ignored content,
+   attached checkouts, symlink/real-path containment and active processes. Never
+   erase `.engineering`, `.git/forge-runtime`, product data-roots, credentials,
+   artifacts or databases because Git's ordinary clean check ignored them.
+8. The expected target snapshot is still current immediately at mutation.
+   Use EP exclusion for cooperating writers and a provider's atomic expected-ref
+   operation for remote races. An EP lease cannot prevent unrelated Git writers.
+   If conditional deletion is unavailable, return UNSUPPORTED/RETAINED for
+   unattended cleanup rather than perform check-then-unconditional-delete.
+
+Branch recreation/name reuse, new commit, new PR/lease, permission/hold change
+or changed cleanup set invalidates stale eligibility. Inspect symlinks and
+containment at use time; the command cannot escape approved roots by replacing
+a path between preview and execution. Unsupported filesystem/provider guarantees
+are explicit capability limits, not a fallback to force-delete.
+
+## Semantic cases, decisions and safety
+
+Forge can supply a bounded intent-to-current-main reconciliation with code/test
+references and uncertainty. EP treats it as evidence/proposal, not an instruction
+to trust an LLM. Automatic deterministic own-run cleanup is allowed only under
+current scoped delegation and qualification. Semantically superseded history
+requires accepted disposition, recovery retention and all current safety checks;
+this architecture enables no model-only deletion.
+
+The safety decision and destructive operation are separate from routine analysis
+budgets. No new provider repair allowance is created by a maintenance case;
+corrective engineering work follows the existing run/lineage and shared limits.
+
+## Recovery, partial effects and result integrity
+
+There is no atomic transaction across GitHub refs, local Git, filesystem and
+CENTRAL. Journal each admitted target operation and reconcile actual remote/local
+state after lost acknowledgement, restart or crash. Finish only the still-
+authorized outstanding stages. Do not repeat completed deletion, allocate a new
+command to bypass denial, or silently recreate a now-reused ref as compensation.
+
+Local cleanup can fail after remote deletion; retain a PARTIAL receipt. Repository
+or provider busy is a bounded wait, not permission to remove locks. Garbage
+collection, reflog expiry, archive deletion and arbitrary `git clean`/reset are
+outside this capability. Archive retention is a separately governed lifecycle.
+
+A delivered Action remains delivered if later cleanup fails. Store cleanup
+warnings/evidence separately; only an actual unresolved safety/lease condition
+blocks relevant later admission. An unrelated retained branch cannot block every
+repository or overwrite a successful terminal delivery.
+
+## Required qualification and rollout
+
+First qualify observation freshness/completeness and command/readback contracts.
+Then qualify own-run safe primitives, explicit project-maintenance admission,
+replay/partial effects and Forge consumer interpretation. Reuse current product
+services; do not require generalized Agent fleet management for a single-host proof.
+Workspace UI is not required for approved CLI/API/producer operations.
+
+Tests must cover exact delivery versus post-merge commits, squash-equivalent
+history, active/unknown ownership, cross-project/forged actor, expired grant,
+retained/release refs, dirty/untracked/ignored state, runtime-data preservation,
+concurrent push/ref reuse, own-finalizer lease versus conflicting owner,
+unsupported conditional delete, archive failure, symlink escape,
+duplicate/conflicting operation IDs, interrupted effect, restart/lost
+acknowledgement, partial cleanup and preserved delivery outcome.
+Use isolated repositories/fixtures; no product branch deletion in ordinary CI.
+
+The [EP scoped roadmap](../development/PROJECT_HYGIENE_V1_ROADMAP.md) sequences
+these proofs. No live repo cleanup, database migration, protocol downgrade,
+version bump or host mutation is authorized by this documentation increment.