docs: define Repository Health and reconciliation chat

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.

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.

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.