diff --git a/docs/development/ENGINEERING_PLATFORM_ROADMAP.md b/docs/development/ENGINEERING_PLATFORM_ROADMAP.md index e11989e2..de6f0fa6 100644 --- a/docs/development/ENGINEERING_PLATFORM_ROADMAP.md +++ b/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. \ No newline at end of file diff --git a/docs/development/PROJECT_HYGIENE_V1_ROADMAP.md b/docs/development/PROJECT_HYGIENE_V1_ROADMAP.md new file mode 100644 index 00000000..732032ce --- /dev/null +++ b/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. diff --git a/docs/engineering/REPOSITORY_HYGIENE_AND_SAFE_CLEANUP.md b/docs/engineering/REPOSITORY_HYGIENE_AND_SAFE_CLEANUP.md new file mode 100644 index 00000000..bf6b2bb1 --- /dev/null +++ b/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.