diff --git a/ROADMAP.md b/ROADMAP.md index e087a8f..8fbb8ea 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,23 @@ # Workspace Roadmap +## Repository Health and reconciliation chat — documented target + +`WORKSPACE::REPOSITORY_HEALTH_AND_RECONCILIATION_V1` is specified in the +[Repository Health/chat design](docs/REPOSITORY_HEALTH_AND_RECONCILIATION.md) +and [scoped roadmap](docs/PROJECT_HYGIENE_V1_ROADMAP.md), coordinated with +Forge's documentary Project Hygiene DAG. Workspace presents evidence-backed +observations, cases, proposals and decisions; Forge owns reasoning and EP owns +host facts and admitted cleanup. Asking about/reconciling an old branch does +not automatically allocate a Mission or authorize deletion. + +Sequence: `HY-0 -> HY-WC -> HY-WO -> HY-WM`. HY-WO additionally consumes Forge +HY-F observations/cases; HY-WM requires qualified Forge/EP HY-Q command/receipt +semantics. Read-only health/chat can ship without destructive controls. All +implementation nodes remain PLANNED. Preserve actual actor/project scope, +partial/stale inventory, exact confirmation sets and per-target audit outcomes. +The full UI is not a first-canary prerequisite; no runtime configuration, +credentials, policy activation, version or executable programme DAG changes here. + ## Governed progression and existing external delivery gates The coordinated `GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY_V1` increment adds @@ -206,7 +224,7 @@ committed Workspace .engineering-platform/repository.json -> real bounded Workspace repository mutation -> Workspace canonical validation -> finalization - -> immutable receipt/result/provenance + -> immutable EP evidence ``` This proves EP can engineer Workspace; it does not grant Workspace execution authority and does not require Workspace to orchestrate the run itself. diff --git a/docs/PROJECT_HYGIENE_V1_ROADMAP.md b/docs/PROJECT_HYGIENE_V1_ROADMAP.md new file mode 100644 index 0000000..ca26546 --- /dev/null +++ b/docs/PROJECT_HYGIENE_V1_ROADMAP.md @@ -0,0 +1,27 @@ +# Workspace Repository Health V1 roadmap + +Increment: `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1`. +Owning design: [Repository Health, chat and reconciliation](REPOSITORY_HEALTH_AND_RECONCILIATION.md). +Parent: [Workspace Roadmap](../ROADMAP.md). +Coordinated [documentary DAG](https://github.com/pcvantol/forge/blob/main/docs/roadmap/project-hygiene-v1.json). + +| Node | Deliverable | Dependencies | Status | +| --- | --- | --- | --- | +| HY-WC | Health/chat/case/decision request and projection contracts with real actor/scope and evidence classification | HY-0 coordinated documentation | PLANNED | +| HY-WO | Read-only Repository Health and chat: explain, refresh, reconcile; no automatic Mission or deletion | HY-WC, Forge HY-F | PLANNED | +| HY-WM | Scoped cleanup proposal/decision and receipt/history UX | HY-WO, Forge/EP HY-Q | PLANNED | + +HY-WC may proceed contract-first in parallel with EP observation. HY-WO does not +wait for destructive command support; unsupported mutation is absent/disabled +with an explanation. HY-WM requires the actual qualified authority/conditional +cleanup/receipt path, not just a green interface mock. + +Required acceptance includes project isolation, stale/partial/offline inventories, +read versus reconciliation versus delete-intent separation, no Mission allocation +for a case, frozen bulk set, cancel/stale confirmation, retained/partial outcomes, +external owner routing, en/nl/de/fr/es and accessibility, live/history parity and +source/evidence freshness. Chat and view use the same owner-backed operation. + +No Workspace UI is inserted before the first Forge/EP autonomy canary. These +nodes do not implement a client filesystem scanner, second planner, policy engine +or provider credential store. The source-only increment activates nothing. diff --git a/docs/REPOSITORY_HEALTH_AND_RECONCILIATION.md b/docs/REPOSITORY_HEALTH_AND_RECONCILIATION.md new file mode 100644 index 0000000..6cdc02a --- /dev/null +++ b/docs/REPOSITORY_HEALTH_AND_RECONCILIATION.md @@ -0,0 +1,133 @@ +# Repository Health, chat and reconciliation + +## Decision and scope + +Increment: `PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION_V1`. +Target: `WORKSPACE::REPOSITORY_HEALTH_AND_RECONCILIATION_V1`. +Documentation/roadmap only; canonical after owning merge. No application UI, +client scanner, database table or credential-bearing adapter is implemented here. + +This surface extends [Workspace architecture](ARCHITECTURE.md), +[Policy & Automation](POLICY_AND_AUTOMATION.md) and +[governed progression/external gates](GOVERNED_PROGRESSION_AND_EXTERNAL_GATES.md). +Forge owns the native [hygiene/reconciliation capability](https://github.com/pcvantol/forge/blob/main/docs/architecture/PROJECT_HYGIENE_AND_REPOSITORY_RECONCILIATION.md). +EP owns fresh host facts and admitted mutations; Workspace owns the human +experience, not Git truth, Forge planning or EP cleanup authority. + +## One request boundary for chat and structured views + +Users can ask “why does this branch still exist?”, “reconcile this branch” or +“clean the proven-safe branches in this project”. The project/repository must +be explicit or unambiguously resolved through the authenticated workspace +selection. If ambiguous, ask a scoped clarification before any protected action; +never infer write authority from the current directory, a chat mention or a +client's ability to see a branch. + +Chat produces the same typed request/proposal as the structured interface: + +| Intent | Product operation | No implied permission | +| --- | --- | --- | +| Explain/list/refresh | Authorized read-only Forge observation/projection | No cleanup, Mission or provider execution | +| Reconcile a selected branch | Bounded Forge case with evidence/analysis budget | No branch deletion or product-code salvage | +| Clean safe items | Frozen target-set cleanup proposal evaluated by Forge/EP policy | Not a wildcard, credential grant or future auto-delete subscription | +| Preserve/adopt residual work | Governed engineering proposal | Not an automatically approved Mission/Action | + +A reconciliation case is not a Mission and opening it must not allocate Mission +or Action IDs. A genuine product residual is routed through the applicable +existing Mission/successor or new governed intake. No second intake workflow +inside chat bypasses Business/Architecture or protected engineering delivery. +The generic command transport/schema is future owning implementation work. + +## Repository Health projection + +Show repository identity and scope, observed main/head, active PR/Action/lease +references, pending own-run cleanup, reconciliation cases, retained/protected +items and coverage/freshness. Counts state their inventory scope. Offline Agents, +permission-limited provider pages and unknown ignored-file state do not appear +as zero or healthy. A case closed for one branch never implies a clean project. + +Separate facts, inferences, recommendations and decisions visually and in +machine-readable responses. “Likely superseded” includes exact comparison refs, +reason and uncertainty; it is not a green “safe to delete” check. Display +`SUPERSEDED_RECONCILED` independently from `RETAINED` or actual cleanup receipts. +An old merged PR and a branch with new post-merge commits must not look identical. + +Branch detail offers current observations, original intent-to-main mapping, +code/test references, unresolved contradictions, policy obligations, retained +recovery reference, related Mission/run IDs when real, and an audit timeline. +Do not expose hidden reasoning transcripts, raw bearer credentials, private +host paths or source content to roles lacking access. Repository text is untrusted +content and cannot instruct chat to change its scope or approve deletion. + +## Decisions and safe interaction + +Render operations only when supported and provisionally eligible. Server-side +owners still authenticate and revalidate every command. Presentation is not +authorization; clients do not receive GitHub/admin/provider credentials. + +A destructive preview states exact repository, remote/local ref or worktree, +expected head/revision, why it is eligible, what will be retained, and exclusions. +Freeze the target set and proposal digest. An explicit approved proposal or a +current permitted delegation supplies authority; “reconcile” alone does not. + +Use the existing role-aware Decision Evidence Package. Required decisions can +include explicit adoption of unknown-owned work or acceptance of semantic +supersession. Routine EP-owned cleanup within a valid grant needs no redundant +click. If an external owner has the decision, show its status/deep-link rather +than a second Workspace Approve button. + +Confirmation carries operation ID, expected proposal/observation revision and +actual authenticated actor context. Cancel creates no execution command. A stale +modal/conflicting revision refreshes the facts; never silently retry with a new +operation ID or auto-include newly discovered branches. Bulk results remain +per-target: completed, retained, denied, stale, unknown or partial. Lost responses +recover the same operation. Do not report all-success after a mixed result. + +## Policy and notification model + +Expose supported project hygiene profile fields through Policy & Automation: +read-only scan cadence/scope, semantic-analysis budget, freshness/retention, +protected targets and delegated cleanup classes. Profiles do not mint grants or +create unsupported execution capabilities. Lower scopes cannot remove mandatory +protection, retention or authorization requirements. + +Default interaction is read-only and exception-oriented. Coalesce duplicate +notifications, distinguish informational residue from true operation blockers, +and let users defer analysis while retaining its reason. Do not repeatedly ask +for approval after every harmless post-EA refresh. Scope expansion, destructive +ambiguity or expired authority still follows the owning gate. + +The interface must preserve the existing localization targets en/nl/de/fr/es, +keyboard/screen-reader access, suitable narrow-screen layouts, destructive +confirmation styling, and live/historical parity. No browser alert()-based +administration or purely DOM-owned status. + +## Server/client and storage boundary + +Workspace Server stores its own session/navigation/decision-presentation state. +Forge stores authoritative case conclusions and its Project Context projection; +EP stores admitted cleanup and outcome receipts. Cached views show provenance +and freshness; none becomes an independently editable copy of peer authority. +No shared SQL, local filesystem probing from a remote client or API fallback to +peer databases. A local Agent, where used, follows EP's separately qualified +identity/capability contract and never self-admits a cleanup command. + +A chat is not required for native scheduled scans or EP finalizer cleanup. +Conversely, shipping this UI cannot activate an unavailable cleanup executor. + +## Qualification and sequencing + +The [scoped roadmap](PROJECT_HYGIENE_V1_ROADMAP.md) allows contract-first design +in parallel. Read-only health/chat can follow qualified observation and case +contracts; destructive controls additionally require qualified EP command and +receipt behavior. Do not block read-only delivery on unavailable delete support. + +Qualify cross-project isolation, missing permission, stale/offline coverage, +read-only versus delete-intent distinction, no Mission allocation for cases, +meaningful reason/actor evidence, exact bulk target set, ref changes after modal, +cancel, duplicate command, mixed outcomes, external gate routing, accessible +five-language UI and historical/restart parity. These are acceptance targets, +not executed UI tests in this documentation change. + +Full Workspace productization is not a first installed Forge/EP canary gate. +Only the actual obligations of a chosen operation can block that operation.