docs(webui): add MCP Control Plane Web Console architecture ADR (Closes #632 )

Adds the durable architecture record epic #631 lacked: layer contract, authority boundaries, the redaction boundary, /api/v1 versioning with a compatibility rule for the existing unversioned MVP exports, a target page map, per-child component ownership for all twenty children (#632-#651), phase gates, and explicit forbidden paths. Documentation only. No UI, API, or deployment change. - docs/architecture/webui-control-plane-console-architecture-adr.md (new) - docs/webui-local-dev.md: cross-link to the ADR - tests/test_webui_architecture_docs.py: doc gate for the acceptance criteria and the cross-link (12 cases) Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-22 04:52:21 -05:00
7 changed files with 382 additions and 575 deletions
@@ -0,0 +1,201 @@
 # ADR: MCP Control Plane Web Console architecture and information architecture
 - **Status:** Proposed (documentation only; blocks no code, gates every #631 child)
 - **Date:** 2026-07-22
 - **Tracking issue:** [#632](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/632) — architecture and information architecture (Phase 1)
 - **Parent epic:** [#631](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/631) — MCP Control Plane Web Console
 - **Foundation (closed, extend — do not recreate):** #425 tracker and children #426 skeleton, #427 projects, #428 prompts, #429 queue, #430 runtime, #431 audit paste, #432 worktrees, #433 leases, #434 gated actions, #435 auth/deployment boundary, #436 tests/CI
 - **Related:** `mcp-allocator-control-plane-observability-adr.md`, `mcp-stable-control-runtime-policy-adr.md`, `control-plane-db-substrate.md`, `../safety-model.md`, `../tool-boundaries.md`, `../credential-isolation.md`, `../webui-local-dev.md`, `../webui-deployment.md`
 ## 1. Context
 The MVP web UI shipped under `webui/` as a read-only Starlette application with ten operator routes and a JSON export beside most of them. It is a working foundation, not the console product described by epic #631, and it carries no durable architecture record: no layer contract, no authority boundary, no API versioning rule, no page map, and no statement of which phase may open a write path.
 Twenty children (#632–#651) hang off #631. Without one architecture document each implementer re-derives boundaries, and the most likely failure is not a bad view — it is a privileged action wired into the browser before the authorization and audit model of #633 exists.
 This ADR is the single retrievable design source for the console. It decides structure only. It implements no UI, no API, and no change to deployment topology.
 ## 2. Decision summary (core)
 | Layer | Owns | Must not |
 |-------|------|----------|
 | **Browser UI** | Rendering, navigation, operator affordances | Hold tokens, call Gitea/providers directly, or execute an action the server did not gate |
 | **HTTP route layer** (`webui/app.py`) | Versioned routing, authentication, authorization, redaction boundary, audit emission | Contain domain logic or reach past a loader to a raw credential |
 | **Domain loaders** (`webui/*_loader.py`, `*_scanner.py`, `runtime_health.py`, `project_registry.py`) | Assembling read models from authoritative sources | Mutate anything, or emit unredacted secrets across the boundary |
 | **Gitea** | Durable work record: issues, PRs, comments, reviews, labels, merges | Be the concurrency lock under multi-session load |
 | **Control-plane DB** | Sessions, assignment, leases, heartbeats, events | Replace Gitea history |
 | **MCP tools / capability gates** | Mutation authorization | Be re-implemented, mirrored, or bypassed by console code |
 | **External providers** (Sentry/GlitchTip, AI providers) | Incident and usage data | Assign work or mutate Gitea outside the #612 bridge |
 **One-liner:** **Gitea records. The DB coordinates. MCP tools authorize. The console projects state and executes only capability-checked, audited actions. Providers observe.**
 ## 3. Console surface today versus target
 `webui/app.py` currently registers these routes (see `../webui-local-dev.md` for the operator-facing table): `/`, `/health`, `/queue`, `/projects`, `/projects/{id}`, `/prompts`, `/runtime`, `/audit`, `/worktrees`, `/leases`, `/actions`, and the unversioned exports `/api/queue`, `/api/projects`, `/api/prompts`, `/api/runtime`, `/api/audit`, `/api/worktrees`, `/api/leases`, `/api/actions`, `/api/actions/{id}/preview`, `/api/actions/{id}/attempt`.
 Every one of these is **retained and evolved**. No child issue may recreate a route from scratch; each states in its PR which MVP surface it extends and what it changes.
 ## 4. Authority boundaries
 ### 4.1 Gitea (durable record)
 Authoritative for issue and PR identity and state, comments, reviews and verdicts, labels, merges, and branch refs. When the console and Gitea disagree about durable state, Gitea wins and the console view is refreshed — never the reverse.
 ### 4.2 Control-plane DB (coordination)
 Authoritative for live coordination: which session holds which assignment or lease, heartbeat freshness, expiry, and the allocation event log. The console reads it; only allocator and lease tools write it.
 ### 4.3 MCP capability gates (authorization)
 `task_capability_map.py` and `gitea_resolve_task_capability` remain the only authority that decides whether a mutation may run. The console asks; it never answers. A console action that cannot name the MCP tool it delegates to is not an action — it is a defect.
 ### 4.4 Filesystem and git (local state)
 Issue lock files, `branches/` worktrees, and registered git worktrees are read through existing scanners. The console never deletes, rebinds, or force-clears local state outside a Phase 2 gated action.
 ### 4.5 Providers (observe only)
 Sentry/GlitchTip and AI providers are read surfaces. The #612 incident bridge is the only path that turns an observation into Gitea work.
 ## 5. Request flow and the redaction boundary
 ```text
 browser ──HTTP──> route layer ──> domain loader ──> Gitea REST
                      │                        ├──> control-plane DB
                      │                        ├──> filesystem / git
                      │                        └──> providers
                      │
                 [redaction boundary]
                      │
                 audit event
 ```
 | Stage | May hold credentials | Emits |
 |-------|----------------------|-------|
 | Loader → route layer | yes (server-side, via `gitea_auth`) | domain objects |
 | Route layer → browser | **no** | redacted DTOs, HTML |
 Two invariants govern the boundary and are non-negotiable for every child:
 1. **No secrets to the browser.** Tokens, keychain identifiers, Authorization headers, raw provider endpoints, and credential-bearing URLs are redacted by default, consistent with `../safety-model.md` §3 and `../credential-isolation.md`. Serializers redact; templates do not sanitize after the fact.
 2. **No ungated mutations.** A write reaches an authoritative system only by delegating to an MCP tool that passed its own capability gate. HTML forms and JSON endpoints are transport, never authority.
 ## 6. API naming and versioning
 **Decision:** all console APIs added from Phase 1 onward are served under `/api/v1/...`.
 - Nouns are plural and hierarchical: `/api/v1/inventory/leases`, `/api/v1/system/health`.
 - Read endpoints are `GET` and side-effect free.
 - Phase 2 action endpoints are `POST /api/v1/actions/{action_id}/preview` and `POST /api/v1/actions/{action_id}/execute`; `preview` stays side-effect free and returns a mutation ledger.
 - The existing unversioned MVP exports remain as **compatibility aliases** for the whole of Phase 1 so the current operator flow never breaks. They may be retired no earlier than Phase 2, and only after the replacing `v1` route ships and `../webui-local-dev.md` records the swap.
 - A breaking change to a `v1` payload requires `/api/v2/...`, not an in-place edit.
 - Every JSON payload carries enough provenance for an auditor to tell where the data came from — at minimum the source system and whether the inventory was complete, matching the pagination-proof habit the MVP queue export already established.
 ## 7. Page map
 | Page | Purpose | Owning child | Evolves |
 |------|---------|--------------|---------|
 | `/` | Console shell, navigation, next-safe-action summary | #638 | MVP `/` (#426) |
 | `/system` | System-health dashboard | #639 | new, backed by #634 |
 | `/traffic` | Workflow traffic control, queues, blockers | #640 | MVP `/queue` (#429) |
 | `/runtime` | Runtime and session view | #641 | MVP `/runtime` (#430) |
 | `/projects`, `/projects/{id}` | Project registry and onboarding | #635 | MVP `/projects` (#427) |
 | `/inventory` | Sessions, leases, locks, worktrees in one surface | #636 | MVP `/leases` (#433) + `/worktrees` (#432) |
 | `/timeline` | Workflow events and conversation timeline | #637 | new |
 | `/actions` | Gated action registry, preview, execution | #642, #643, #644 | MVP `/actions` (#434) |
 | `/gitea` | Issue and PR linkage console | #645 | new |
 | `/policy` | Guardrail visibility, then versioned editing | #646, #647 | new |
 | `/notifications` | Human-attention routing | #648 | new |
 | `/observability` | Sentry/GlitchTip correlation and durable issue creation | #649 | new |
 | `/providers` | AI-provider connections and insights | #650 | new |
 | `/analytics` | Usage, token cost, latency, workflow performance | #651 | new |
 | `/audit` | Final-report validator preview and audit log | #431 foundation, extended by #633 | MVP `/audit` (#431) |
 | `/prompts`, `/prompts/{id}` | Canonical prompt library | #638 | MVP `/prompts` (#428) |
 | `/health` | Liveness and deployment metadata | #634 | MVP `/health` (#435) |
 ## 8. Component ownership for every epic child
 Each #631 child maps to at least one architectural component defined above.
 | Child | Capability area | Primary component | Phase |
 |-------|-----------------|-------------------|-------|
 | #632 | Architecture and information architecture | this ADR | 1 |
 | #633 | Authorization, RBAC, secret redaction, audit and retention | route layer + redaction boundary (§5) | 1 |
 | #634 | Read-only system-health API | `/api/v1/system/health` + health loader | 1 |
 | #635 | Project registry API evolution | `/api/v1/projects` + `project_registry.py` | 1 |
 | #636 | Session, lease, lock, worktree inventory API | `/api/v1/inventory/*` + `lease_loader.py`, `worktree_scanner.py` | 1 |
 | #637 | Workflow-event and conversation timeline model | `/api/v1/events` + control-plane DB event log | 1 |
 | #638 | Application shell evolution | browser UI layer + `layout.py` | 1 |
 | #639 | System-health dashboard | `/system` page over #634 | 1 |
 | #640 | Workflow traffic-control view | `/traffic` page over the queue loader | 1 |
 | #641 | Runtime and session view | `/runtime` page over `runtime_health.py` | 1 |
 | #642 | Sanctioned restart and graceful reload controls | gated action framework, restart class | 2 |
 | #643 | Requests, intent preview, authorization, workflow initiation | `/api/v1/actions/*` execute path | 2 |
 | #644 | Stale-runtime recovery, worktree rebinding, reconciliation controls | gated actions over filesystem/git authority | 2 |
 | #645 | Gitea issue and PR linkage console | `/gitea` page over Gitea authority | 3 |
 | #646 | Workflow policy and guardrail visibility | `/policy` read view over the capability map | 3 |
 | #647 | Versioned policy editing, validation, simulation, approval, rollback | `/policy` write path, gated | 3 |
 | #648 | Notifications and human-attention routing | notification component over the event model | 3 |
 | #649 | Sentry/GlitchTip connections, correlation, durable issue creation | provider layer + #612 incident bridge | 4 |
 | #650 | AI-provider connections and operational insights | provider layer | 4 |
 | #651 | Model usage, token cost, latency, workflow analytics | analytics component over the event model | 4 |
 Related but **outside** this epic: #667 (restart status, impact preview, and approval controls) belongs to the #655 restart-governance umbrella and must reuse the #642 action class rather than adding a second restart surface.
 ## 9. Phase gates
 | Phase | May ship | Entry condition |
 |-------|----------|-----------------|
 | **1 — read-only visibility** | `GET` pages and `GET /api/v1/...` | this ADR accepted |
 | **2 — controlled actions** | gated `POST` action execution | #633 authorization, RBAC, and audit model landed |
 | **3 — orchestration and policy** | linkage, policy visibility, versioned policy editing | Phase 1 inventory plus the Phase 2 action framework |
 | **4 — insights** | provider correlation, analytics | evidence-backed sources from Phases 1–3 |
 Phase 1 must not open a mutation endpoint, and the read-only guard that returns `405 read-only-mvp` stays in force until the Phase 2 entry condition is met. A phase is not entered by exception; if a control is urgent, the entry condition is what gets prioritized.
 ## 10. Security and workflow safety
 - **Fail closed** on unknown authentication, missing RBAC mapping, or ambiguous lease ownership. An unknown state renders as blocked, never as permitted.
 - **Redact by default**, per §5.
 - **Every privileged action** requires a resolved capability, an explicit operator confirmation, and a durable audit event naming actor, action, target, and outcome.
 - **Contamination surfaces.** Session contamination — including a manually killed MCP daemon (#630) — must be shown and must block clean claims rather than being silently repaired.
 - **Deployment boundary unchanged.** Loopback by default, with the existing refusal of public binds (#435). This ADR documents that target; it does not widen it.
 ## 11. Forbidden paths
 These are rejected designs, not preferences:
 1. **Raw provider incidents as work.** The allocator never receives an unclassified Sentry/GlitchTip incident; only the #612 bridge turns an observation into a Gitea issue.
 2. **Browser-held tokens.** No credential, keychain identifier, or Authorization header is ever sent to the browser or embedded in a client bundle.
 3. **Process-kill recovery.** The console must not expose `pkill`, process-identifier termination, or any host process kill as a recovery affordance (#630). Restart is the sanctioned, operator-owned path of #642 and the #655 umbrella.
 4. **Ungated browser mutations.** No review, approval, merge, close, or comment may originate from the browser without passing an MCP capability gate.
 5. **Policy invented in the console.** The console projects policy from the capability map and canonical workflows; it never encodes a second copy.
 6. **Recreating MVP scope.** Re-implementing a #426–#436 surface without an explicit evolve-or-extend statement is out of bounds.
 ## 12. Approval checklist (readable without chat history)
 A controller can accept or reject this ADR against these six points alone:
 1. Layers and their owners are defined (§2) and each authority is named (§4).
 2. The redaction boundary and the two invariants are stated (§5).
 3. API versioning is decided, including what happens to the existing unversioned routes (§6).
 4. A page map exists and names an owning child for every page (§7).
 5. Every #631 child maps to at least one component and one phase (§8).
 6. Phase gates and forbidden paths are explicit (§9, §11).
 ## 13. Open questions and follow-ups
 Unresolved choices are recorded here rather than settled by implication. Each needs its own durable issue before the phase that depends on it:
 - **Authentication mechanism.** Whether the console authenticates via an access proxy (Cloudflare Access or equivalent) or an application-level session is deferred to #633. This ADR requires only that it fail closed.
 - **Event model substrate.** Whether the #637 timeline reads the control-plane event log directly or through a projection is deferred to #637.
 - **CI path filter coverage.** `webui/ci_paths.py` triggers the web UI suite on `webui/`, `tests/test_webui_*`, and `docs/webui*`. This ADR lives under `docs/architecture/`, so editing it alone does not trigger that gate; the accompanying `tests/test_webui_architecture_docs.py` does run in the full suite. Widening the filter is a small follow-up, deliberately not bundled into a documentation-only change.
 - **Retention.** Audit-event retention duration is owned by #633.
 ## 14. Acceptance
 Accepting this ADR means:
 - Phase 1 children may proceed against the layers, page map, and API rules above.
 - Phase 2 children may not open a write path until #633 lands.
 - Any deviation is recorded as an amendment to this file with its own issue reference, not as an undocumented divergence in code.
@@ -37,6 +37,12 @@ Optional environment variables:
 See [webui-deployment.md](webui-deployment.md) for internal-only serving,
 Cloudflare Access/WARP/VPN guidance, and unsafe bind overrides (#435).
 See
 [architecture/webui-control-plane-console-architecture-adr.md](architecture/webui-control-plane-console-architecture-adr.md)
 for the console architecture: layer and authority boundaries, the redaction
 boundary, `/api/v1/...` versioning, the target page map, and the phase gates
 that govern when a write path may open (#632, epic #631).
 ## Routes (MVP)
 | Path | Description |
@@ -12536,39 +12536,10 @@ def _try_auto_switch_for_operation(op: str, host: str | None = None) -> bool:
    return False
 def _git_default_remote_name(root: str) -> str:
    """First configured git remote name for *root*, defaulting to 'origin'.
    Used to resolve the live remote master target for parity (#610). Best
    effort: any failure falls back to 'origin' so callers never raise.
    """
    try:
        res = subprocess.run(
            ["git", "-C", root, "remote"],
            capture_output=True, text=True, check=False,
        )
    except Exception:
        return "origin"
    if res.returncode != 0:
        return "origin"
    names = [n.strip() for n in (res.stdout or "").splitlines() if n.strip()]
    return names[0] if names else "origin"
 def _current_master_parity() -> dict:
-    """Assess this process's code against local and live remote master (#420/#610).
+    """Assess this process's code against the on-disk master HEAD (#420)."""
    Compares the daemon's startup commit, the on-disk checkout HEAD, and the
    live remote master target. A stale daemon relative to live master fails
    closed for mutations even when the local checkout HEAD still matches the
    startup commit. The live-remote read is best effort: an unresolved live
    head leaves read-only diagnostics unblocked but is never mutation-safe.
    """
    current_head = master_parity_gate.read_git_head(PROJECT_ROOT)
-    live_head = master_parity_gate.read_remote_master_head(
+    return master_parity_gate.assess_master_parity(_STARTUP_PARITY, current_head)
        PROJECT_ROOT, remote=_git_default_remote_name(PROJECT_ROOT))
    return master_parity_gate.assess_master_parity(
        _STARTUP_PARITY, current_head, live_remote_head=live_head)
 def _current_runtime_mode_report(refresh: bool = False) -> dict:
@@ -16509,34 +16480,15 @@ def gitea_get_runtime_context(
        "restart_required": parity["restart_required"],
        "startup_head": parity["startup_head"],
        "current_head": parity["current_head"],
        # #610 distinguished mutation-safety signals:
        "daemon_start_head": parity["daemon_start_head"],
        "local_head": parity["local_head"],
        "live_remote_head": parity["live_remote_head"],
        "live_known": parity["live_known"],
        "live_stale": parity["live_stale"],
        "mutation_safe": parity["mutation_safe"],
        "summary": master_parity_gate.format_parity(parity),
        "mutation_gate_enforced": not master_parity_gate.gate_disabled(),
        # #610: the capability resolver is authoritative for mutation safety;
        # local parity alone must never authorize a mutation.
        "resolver_authoritative_for_mutation_safety": True,
    }
-    if parity["restart_required"] and not master_parity_gate.gate_disabled():
+    if parity["stale"] and not master_parity_gate.gate_disabled():
-        if parity["live_stale"]:
+        safe_next_action = (
-            safe_next_action = (
+            "Server code is stale relative to master; restart the Gitea MCP "
-                "Daemon is stale relative to LIVE remote master "
+            "server to load current capability gates before mutating. "
-                f"(started {parity['startup_head'][:12] if parity['startup_head'] else 'unknown'}, "
+            f"({master_parity_gate.format_parity(parity)})"
-                f"live master {parity['live_remote_head'][:12] if parity['live_remote_head'] else 'unknown'}); "
+        )
                "restart/reconnect the Gitea MCP server before mutating. The "
                "capability resolver is authoritative for mutation safety."
            )
        else:
            safe_next_action = (
                "Server code is stale relative to master; restart the Gitea MCP "
                "server to load current capability gates before mutating. "
                f"({master_parity_gate.format_parity(parity)})"
            )
        result["safe_next_action"] = safe_next_action
    if reveal and h:
@@ -16585,13 +16537,6 @@ def gitea_assess_master_parity(
        "determinable": parity["determinable"],
        "startup_head": parity["startup_head"],
        "current_head": parity["current_head"],
        # #610 distinguished mutation-safety signals:
        "daemon_start_head": parity["daemon_start_head"],
        "local_head": parity["local_head"],
        "live_remote_head": parity["live_remote_head"],
        "live_known": parity["live_known"],
        "live_stale": parity["live_stale"],
        "mutation_safe": parity["mutation_safe"],
        "mutation_gate_enforced": enforced,
        "summary": master_parity_gate.format_parity(parity),
        "reasons": parity["reasons"],
@@ -16608,7 +16553,7 @@ def gitea_assess_master_parity(
            source=canonical_source,
        ),
    }
-    if parity["restart_required"] and enforced:
+    if parity["stale"] and enforced:
        out["report"] = master_parity_gate.parity_report(parity)
    return out
@@ -24,50 +24,12 @@ from __future__ import annotations
 import os
 import subprocess
 import time
 # Live-remote head cache: the parity gate runs on every mutation and every
 # runtime-context read, so the ``git ls-remote`` result is cached briefly to
 # avoid a network round-trip per call (#610). Keyed by (root, remote, branch).
 _REMOTE_HEAD_CACHE: dict[tuple[str, str, str], tuple[float, str | None]] = {}
 _REMOTE_HEAD_TTL = 60.0
 # When True, ``read_remote_master_head`` never performs ``git ls-remote`` unless
 # ``GITEA_TEST_LIVE_REMOTE_HEAD`` is set. Conftest enables this suite-wide so
 # feature worktrees (whose HEAD differs from live master) cannot flip legacy
 # runtime-context assertions to live_stale, and so unit tests never depend on
 # a live network (PR #788 F1/F2 / issue #610). Module-level (not env-only) so
 # ``patch.dict(os.environ, …, clear=True)`` cannot re-enable the probe.
 _HERMETIC_TEST_MODE: bool = False
 def _clear_remote_head_cache() -> None:
    """Reset the live-remote head cache (test isolation / forced refresh)."""
    _REMOTE_HEAD_CACHE.clear()
 def set_hermetic_test_mode(enabled: bool) -> None:
    """Enable or disable suite-wide hermetic live-remote reads (tests only)."""
    global _HERMETIC_TEST_MODE
    _HERMETIC_TEST_MODE = bool(enabled)
    _clear_remote_head_cache()
 def hermetic_test_mode() -> bool:
    """Return whether hermetic live-remote reads are active."""
    return bool(_HERMETIC_TEST_MODE)
 # Environment escape hatches (ops + tests):
 #   GITEA_MCP_DISABLE_PARITY_GATE  -> disable enforcement entirely (fail open).
 #   GITEA_TEST_CURRENT_HEAD        -> force the "current" HEAD read, for tests.
 ENV_DISABLE = "GITEA_MCP_DISABLE_PARITY_GATE"
 ENV_TEST_CURRENT_HEAD = "GITEA_TEST_CURRENT_HEAD"
 # GITEA_TEST_LIVE_REMOTE_HEAD -> force the live remote master read, for tests.
 ENV_TEST_LIVE_REMOTE_HEAD = "GITEA_TEST_LIVE_REMOTE_HEAD"
 # GITEA_TEST_ALLOW_LIVE_REMOTE_PROBE -> opt a single test into a real ls-remote
 # even when hermetic mode is on (rare; prefer ENV_TEST_LIVE_REMOTE_HEAD).
 ENV_TEST_ALLOW_LIVE_REMOTE_PROBE = "GITEA_TEST_ALLOW_LIVE_REMOTE_PROBE"
 def read_git_head(root: str) -> str | None:
@@ -96,75 +58,6 @@ def read_git_head(root: str) -> str | None:
    return (res.stdout or "").strip() or None
 def read_remote_master_head(
    root: str,
    remote: str = "origin",
    branch: str = "master",
    ttl: float = _REMOTE_HEAD_TTL,
 ) -> str | None:
    """Return the live remote ``branch`` commit SHA, or ``None`` (#610).
    Resolves the *live* target commit via ``git ls-remote`` so parity can tell
    a daemon that is behind the live remote master apart from one whose local
    checkout simply hasn't been pulled. ``None`` means the live head could not
    be resolved (offline, no such remote, git unavailable, error) -- callers
    must treat unknown live state as *not mutation-safe* while never blocking
    read-only diagnostics. A ``GITEA_TEST_LIVE_REMOTE_HEAD`` override takes
    precedence so the wiring can be exercised deterministically and offline.
    The result is cached for *ttl* seconds per (root, remote, branch) so the
    gate does not run a network probe on every mutation/read (``ttl=0`` forces
    a live probe). Both hits and ``None`` misses are cached to bound offline
    latency; the env override bypasses the cache and the subprocess entirely.
    Under suite hermetic mode (``set_hermetic_test_mode(True)``, set by
    conftest) a missing override returns ``None`` without network I/O so
    feature-worktree test runs cannot observe live_stale against real master
    (PR #788 F1) and unit tests stay offline (F2). Opt out with an explicit
    ``GITEA_TEST_LIVE_REMOTE_HEAD`` pin or ``GITEA_TEST_ALLOW_LIVE_REMOTE_PROBE``.
    """
    forced = os.environ.get(ENV_TEST_LIVE_REMOTE_HEAD)
    if forced is not None:
        return forced.strip() or None
    if _HERMETIC_TEST_MODE and not (
        os.environ.get(ENV_TEST_ALLOW_LIVE_REMOTE_PROBE) or ""
    ).strip():
        # Hermetic default: live head unknown. live_stale stays False;
        # mutation_safe is False when live is unknown (documented #610 note).
        return None
    # Defense in depth: even without the module flag, never probe while pytest
    # is running unless the test opted into a real probe or set an override.
    if (os.environ.get("PYTEST_CURRENT_TEST") or "").strip() and not (
        os.environ.get(ENV_TEST_ALLOW_LIVE_REMOTE_PROBE) or ""
    ).strip():
        return None
    if not root:
        return None
    key = (root, remote, branch)
    now = time.monotonic()
    if ttl > 0:
        cached = _REMOTE_HEAD_CACHE.get(key)
        if cached is not None and (now - cached[0]) < ttl:
            return cached[1]
    sha: str | None = None
    try:
        res = subprocess.run(
            ["git", "-C", root, "ls-remote", remote, f"refs/heads/{branch}"],
            capture_output=True,
            text=True,
            check=False,
            timeout=5,
        )
        if res.returncode == 0:
            lines = (res.stdout or "").strip().splitlines()
            if lines:
                sha = lines[0].split("\t", 1)[0].split()[0].strip() or None
    except Exception:
        sha = None
    _REMOTE_HEAD_CACHE[key] = (now, sha)
    return sha
 def capture_startup_parity(root: str, head: str | None = None) -> dict:
    """Capture the process source-tree baseline once at server startup.
@@ -179,38 +72,18 @@ def _short(sha: str | None) -> str:
    return sha[:12] if sha else "unknown"
-def assess_master_parity(
+def assess_master_parity(startup: dict | None, current_head: str | None) -> dict:
    startup: dict | None,
    current_head: str | None,
    live_remote_head: str | None = None,
 ) -> dict:
    """Compare the startup baseline against the current on-disk ``HEAD``.
-    Pure: all HEADs are supplied by the caller. Returns a structured result:
+    Pure: both HEADs are supplied by the caller. Returns a structured result:
    - ``in_parity``    -- server code matches the on-disk master (or parity
      could not be determined, which is not treated as stale).
    - ``stale``        -- the on-disk master has definitively advanced past the
      running process.
-    - ``restart_required`` -- ``stale`` or ``live_stale``; the recovery action.
+    - ``restart_required`` -- alias of ``stale``; the recovery action.
-    - ``determinable`` -- whether both local HEADs were known well enough to
+    - ``determinable`` -- whether both HEADs were known well enough to compare.
      compare.
    - ``startup_head`` / ``current_head`` / ``reasons``.
    #610 adds live-remote awareness so a daemon that is stale relative to the
    *live* remote master cannot report a mutation-safe result even when the
    local checkout HEAD still matches the daemon's startup commit:
    - ``daemon_start_head`` -- the commit the running process started at
      (alias of ``startup_head``, named for clarity in reports).
    - ``local_head`` -- the on-disk checkout HEAD (alias of ``current_head``).
    - ``live_remote_head`` -- the live remote target commit, or ``None`` when it
      could not be fetched.
    - ``live_known`` -- whether the live remote target was resolved.
    - ``live_stale`` -- the live remote master has advanced past the running
      process (daemon is behind live master) even if local parity is green.
    - ``mutation_safe`` -- the daemon code, local checkout, and live remote
      target all agree; the only state in which a mutation may rely on parity.
    """
    startup_head = (startup or {}).get("startup_head")
    reasons: list[str] = []
@@ -218,56 +91,32 @@ def assess_master_parity(
    if startup_head is None:
        reasons.append(
            "startup commit was not captured; code parity cannot be enforced")
-        return _result(True, False, False, startup_head, current_head,
+        return _result(True, False, False, startup_head, current_head, reasons)
                       live_remote_head, False, reasons)
    if current_head is None:
        reasons.append(
            "current workspace HEAD could not be read; code parity cannot be "
            "enforced")
-        return _result(True, False, False, startup_head, current_head,
+        return _result(True, False, False, startup_head, current_head, reasons)
                       live_remote_head, False, reasons)
-    local_in_parity = startup_head == current_head
+    if startup_head == current_head:
-    local_stale = not local_in_parity
+        return _result(True, False, True, startup_head, current_head, reasons)
    if local_stale:
        reasons.append(
            f"MCP server started at commit {_short(startup_head)} but the "
            f"workspace master is now {_short(current_head)}; restart the "
            f"server to load the current capability gates")
-    live_known = live_remote_head is not None
+    reasons.append(
-    live_stale = live_known and live_remote_head != startup_head
+        f"MCP server started at commit {_short(startup_head)} but the workspace "
-    if live_stale:
+        f"master is now {_short(current_head)}; restart the server to load the "
-        reasons.append(
+        f"current capability gates")
-            f"live remote master is {_short(live_remote_head)} but the MCP "
+    return _result(False, True, True, startup_head, current_head, reasons)
            f"server started at {_short(startup_head)}; the daemon is stale "
            f"relative to live master -- restart/reconnect before mutating")
    return _result(
        local_in_parity, local_stale, True, startup_head, current_head,
        live_remote_head, live_stale, reasons)
-def _result(in_parity, stale, determinable, startup_head, current_head,
+def _result(in_parity, stale, determinable, startup_head, current_head, reasons):
            live_remote_head, live_stale, reasons):
    live_known = live_remote_head is not None
    mutation_safe = (
        determinable and in_parity and live_known and not live_stale)
    return {
        "in_parity": in_parity,
        "stale": stale,
-        "restart_required": stale or live_stale,
+        "restart_required": stale,
        "determinable": determinable,
        "startup_head": startup_head,
        "current_head": current_head,
        # #610 distinguished signals:
        "daemon_start_head": startup_head,
        "local_head": current_head,
        "live_remote_head": live_remote_head,
        "live_known": live_known,
        "live_stale": live_stale,
        "mutation_safe": mutation_safe,
        "reasons": list(reasons),
    }
@@ -281,13 +130,11 @@ def parity_block_reasons(assessment: dict) -> list[str]:
    """Block reasons for a mutation gate (empty when the mutation may proceed).
    A disabled gate or an in-parity / non-determinable assessment yields no
-    reasons. A definitively stale server blocks, and (#610) a daemon that is
+    reasons; only a definitively stale server blocks.
    stale relative to the *live* remote master blocks even when the local
    checkout HEAD still matches the daemon's startup commit.
    """
    if gate_disabled():
        return []
-    if assessment.get("stale") or assessment.get("live_stale"):
+    if assessment.get("stale"):
        return list(assessment.get("reasons") or
                    ["server code is stale relative to master (fail closed)"])
    return []
@@ -300,10 +147,6 @@ def parity_report(assessment: dict) -> dict:
        "restart_required": True,
        "startup_head": assessment.get("startup_head"),
        "current_head": assessment.get("current_head"),
        # #610: name the live remote target so the report distinguishes a
        # local-code stale from a daemon-behind-live-master stale.
        "live_remote_head": assessment.get("live_remote_head"),
        "live_stale": bool(assessment.get("live_stale")),
        "reasons": list(assessment.get("reasons") or []),
        "recovery": [
            "The running MCP server is executing code older than the current "
@@ -314,45 +157,6 @@ def parity_report(assessment: dict) -> dict:
    }
 def parity_resolver_disagreement(
    assessment: dict,
    resolver_restart_required: bool,
 ) -> dict | None:
    """Typed blocker when the resolver requires restart but parity looks green.
    The capability resolver (``gitea_resolve_task_capability``) detects stale
    runtime authoritatively for mutation safety (#610). When it requires a
    restart, local-only parity must never override it: this returns a typed,
    fail-closed blocker that names the resolver as authoritative. Returns
    ``None`` when the resolver does not require a restart.
    """
    if not resolver_restart_required:
        return None
    parity_optimistic = bool(assessment.get("in_parity")) and not (
        assessment.get("stale") or assessment.get("live_stale"))
    return {
        "kind": "parity_resolver_disagreement",
        "restart_required": True,
        "resolver_authoritative": True,
        "parity_optimistic": parity_optimistic,
        "daemon_start_head": assessment.get("daemon_start_head"),
        "local_head": assessment.get("local_head"),
        "live_remote_head": assessment.get("live_remote_head"),
        "reasons": [
            "The capability resolver requires a restart/reconnect (stale "
            "runtime) but master-parity reported local code as in-parity. "
            "The resolver is authoritative for mutation safety; do not mutate "
            "on local parity alone. Restart/reconnect the Gitea MCP server "
            "and re-verify before mutating.",
        ],
        "recovery": [
            "Trust the resolver: treat this session as stale.",
            "Restart or /mcp reconnect the Gitea MCP namespace so it reloads "
            "current master and live target state, then re-run preflight.",
        ],
    }
 def format_parity(assessment: dict) -> str:
    """One-line human summary for logs / runtime context."""
    if assessment.get("stale"):
@@ -167,35 +167,6 @@ def _reset_mutation_authority(monkeypatch):
 import pytest
@pytest.fixture(autouse=True)
 def _hermetic_live_remote_master_head():
    """#610 / PR #788 F1/F2: keep live-remote parity reads offline in tests.
    ``read_remote_master_head`` would otherwise ``git ls-remote`` whenever
    ``GITEA_TEST_LIVE_REMOTE_HEAD`` is unset. Feature worktrees under
    ``branches/`` always differ from live master, so legacy suites that assert
    runtime-context ``safe_next_action`` flip to live_stale. Module-level
    hermetic mode survives ``patch.dict(os.environ, …, clear=True)``.
    Tests that exercise the real probe path call
    ``master_parity_gate.set_hermetic_test_mode(False)`` and/or set
    ``GITEA_TEST_ALLOW_LIVE_REMOTE_PROBE``.
    """
    try:
        import master_parity_gate as _mpg
        _mpg.set_hermetic_test_mode(True)
    except Exception:
        _mpg = None
    try:
        yield
    finally:
        if _mpg is not None:
            try:
                _mpg.set_hermetic_test_mode(False)
            except Exception:
                pass
@pytest.fixture(autouse=True)
 def _deterministic_workspace_remotes():
    try:
@@ -78,95 +78,6 @@ class TestBlockReasonsAndReport(unittest.TestCase):
        self.assertTrue(report["recovery"])
 class TestLiveRemoteParity(unittest.TestCase):
    """#610: parity must account for the live remote master, not just local.
    The daemon can be stale relative to the live remote target while the local
    checkout HEAD still matches the daemon's startup commit, so local parity
    reports green even though a mutation would run against outdated code.
    """
    SHA_C = "c" * 40
    def test_distinguishes_three_shas(self):
        res = mp.assess_master_parity(
            {"startup_head": SHA_A}, SHA_A, live_remote_head=SHA_B)
        self.assertEqual(res["daemon_start_head"], SHA_A)
        self.assertEqual(res["local_head"], SHA_A)
        self.assertEqual(res["live_remote_head"], SHA_B)
    def test_mutation_safe_only_when_all_three_match(self):
        res = mp.assess_master_parity(
            {"startup_head": SHA_A}, SHA_A, live_remote_head=SHA_A)
        self.assertTrue(res["mutation_safe"])
        self.assertTrue(res["live_known"])
        self.assertFalse(res["live_stale"])
    def test_live_stale_when_remote_advanced_past_daemon(self):
        # Local checkout still matches the daemon start (local parity green),
        # but the live remote master has advanced -> daemon is live-stale.
        res = mp.assess_master_parity(
            {"startup_head": SHA_A}, SHA_A, live_remote_head=SHA_B)
        self.assertTrue(res["in_parity"])  # local parity still green
        self.assertTrue(res["live_stale"])
        self.assertFalse(res["mutation_safe"])
        self.assertTrue(any("live" in r.lower() for r in res["reasons"]))
    def test_live_unknown_is_not_mutation_safe_but_not_stale(self):
        # Non-goal: unfetchable live remote must not be treated as stale for
        # read-only, but a mutation-safe claim fails closed.
        res = mp.assess_master_parity(
            {"startup_head": SHA_A}, SHA_A, live_remote_head=None)
        self.assertFalse(res["live_known"])
        self.assertFalse(res["mutation_safe"])
        self.assertFalse(res["live_stale"])
        self.assertTrue(res["in_parity"])
    def test_default_live_remote_preserves_legacy_shape(self):
        # Callers that do not supply a live head keep the pre-#610 behavior:
        # in-parity, not live-stale, no live-derived block.
        res = mp.assess_master_parity({"startup_head": SHA_A}, SHA_A)
        self.assertFalse(res["live_stale"])
        self.assertEqual(mp.parity_block_reasons(res), [])
 class TestLiveStaleBlockAndReport(unittest.TestCase):
    """#610: live-staleness must block mutations and surface a typed blocker."""
    def test_live_stale_produces_block_reasons(self):
        res = mp.assess_master_parity(
            {"startup_head": SHA_A}, SHA_A, live_remote_head=SHA_B)
        self.assertTrue(mp.parity_block_reasons(res))
    def test_disable_env_suppresses_live_stale_block(self):
        res = mp.assess_master_parity(
            {"startup_head": SHA_A}, SHA_A, live_remote_head=SHA_B)
        with patch.dict(os.environ, {mp.ENV_DISABLE: "1"}):
            self.assertEqual(mp.parity_block_reasons(res), [])
    def test_resolver_disagreement_returns_typed_blocker(self):
        # Parity says local-green, resolver says restart required -> disagreement
        # is a typed, fail-closed blocker naming the resolver as authoritative.
        res = mp.assess_master_parity({"startup_head": SHA_A}, SHA_A)
        blocker = mp.parity_resolver_disagreement(res, resolver_restart_required=True)
        self.assertIsNotNone(blocker)
        self.assertEqual(blocker["kind"], "parity_resolver_disagreement")
        self.assertTrue(blocker["restart_required"])
        self.assertTrue(blocker["resolver_authoritative"])
    def test_no_disagreement_when_resolver_agrees(self):
        res = mp.assess_master_parity({"startup_head": SHA_A}, SHA_A)
        self.assertIsNone(
            mp.parity_resolver_disagreement(res, resolver_restart_required=False))
    def test_live_stale_report_names_live_remote(self):
        res = mp.assess_master_parity(
            {"startup_head": SHA_A}, SHA_A, live_remote_head=SHA_B)
        report = mp.parity_report(res)
        self.assertEqual(report["live_remote_head"], SHA_B)
        self.assertTrue(report["restart_required"])
 class TestReadGitHead(unittest.TestCase):
    def test_test_override_takes_precedence(self):
        with patch.dict(os.environ, {mp.ENV_TEST_CURRENT_HEAD: SHA_B}):
@@ -184,149 +95,6 @@ class TestReadGitHead(unittest.TestCase):
            self.assertIsNone(mp.read_git_head(""))
 class TestReadRemoteMasterHead(unittest.TestCase):
    """#610: live remote master head reader (env-overridable, fails to None)."""
    def test_test_override_takes_precedence(self):
        with patch.dict(os.environ, {mp.ENV_TEST_LIVE_REMOTE_HEAD: SHA_B}):
            self.assertEqual(mp.read_remote_master_head("/nonexistent"), SHA_B)
    def test_blank_override_is_none(self):
        with patch.dict(os.environ, {mp.ENV_TEST_LIVE_REMOTE_HEAD: "   "}):
            self.assertIsNone(mp.read_remote_master_head("/nonexistent"))
    def test_unfetchable_remote_is_none(self):
        # No override; a bogus root/remote must fail closed to None, never raise.
        env = {k: v for k, v in os.environ.items()
               if k != mp.ENV_TEST_LIVE_REMOTE_HEAD}
        with patch.dict(os.environ, env, clear=True):
            self.assertIsNone(
                mp.read_remote_master_head("/nonexistent", remote="nope"))
 class TestRemoteHeadCache(unittest.TestCase):
    """#610: live remote reads are cached with a TTL to stay off the network.
    The parity gate runs on every mutation and every runtime-context read, so an
    unbounded ``git ls-remote`` per call would be a latency/flakiness regression.
    """
    def setUp(self):
        # These cases intentionally exercise the subprocess/cache path, so they
        # opt out of suite-wide hermetic mode (PR #788 F1).
        self._saved_hermetic = mp.hermetic_test_mode()
        mp.set_hermetic_test_mode(False)
        mp._clear_remote_head_cache()
        env = {
            k: v for k, v in os.environ.items()
            if k not in (mp.ENV_TEST_LIVE_REMOTE_HEAD,
                         mp.ENV_TEST_ALLOW_LIVE_REMOTE_PROBE,
                         "PYTEST_CURRENT_TEST")
        }
        # Allow the probe path under hermetic defenses while still mocking
        # subprocess so no real network call runs.
        env[mp.ENV_TEST_ALLOW_LIVE_REMOTE_PROBE] = "1"
        self._env = patch.dict(os.environ, env, clear=True)
        self._env.start()
        self.addCleanup(self._env.stop)
        self.addCleanup(mp._clear_remote_head_cache)
        self.addCleanup(
            lambda: mp.set_hermetic_test_mode(self._saved_hermetic)
        )
    def _fake_run(self, sha):
        class _R:
            returncode = 0
            stdout = f"{sha}\trefs/heads/master\n"
        calls = {"n": 0}
        def run(*args, **kwargs):
            calls["n"] += 1
            return _R()
        return run, calls
    def test_second_call_within_ttl_uses_cache(self):
        run, calls = self._fake_run(SHA_B)
        with patch.object(mp.subprocess, "run", run):
            a = mp.read_remote_master_head("/repo", remote="prgs", ttl=100)
            b = mp.read_remote_master_head("/repo", remote="prgs", ttl=100)
        self.assertEqual(a, SHA_B)
        self.assertEqual(b, SHA_B)
        self.assertEqual(calls["n"], 1)
    def test_zero_ttl_bypasses_cache(self):
        run, calls = self._fake_run(SHA_B)
        with patch.object(mp.subprocess, "run", run):
            mp.read_remote_master_head("/repo", remote="prgs", ttl=0)
            mp.read_remote_master_head("/repo", remote="prgs", ttl=0)
        self.assertEqual(calls["n"], 2)
    def test_env_override_never_touches_subprocess(self):
        run, calls = self._fake_run(SHA_B)
        with patch.dict(os.environ, {mp.ENV_TEST_LIVE_REMOTE_HEAD: SHA_A}):
            with patch.object(mp.subprocess, "run", run):
                self.assertEqual(
                    mp.read_remote_master_head("/repo", remote="prgs"), SHA_A)
        self.assertEqual(calls["n"], 0)
 class TestHermeticLiveRemoteReads(unittest.TestCase):
    """#610 / PR #788 F1/F2: suite hermetic mode never hits the network."""
    def setUp(self):
        self._saved = mp.hermetic_test_mode()
        mp.set_hermetic_test_mode(True)
        mp._clear_remote_head_cache()
        self.addCleanup(lambda: mp.set_hermetic_test_mode(self._saved))
        self.addCleanup(mp._clear_remote_head_cache)
    def test_hermetic_mode_returns_none_without_subprocess(self):
        run_calls = {"n": 0}
        def boom(*args, **kwargs):
            run_calls["n"] += 1
            raise AssertionError("ls-remote must not run under hermetic mode")
        env = {
            k: v for k, v in os.environ.items()
            if k not in (mp.ENV_TEST_LIVE_REMOTE_HEAD,
                         mp.ENV_TEST_ALLOW_LIVE_REMOTE_PROBE)
        }
        with patch.dict(os.environ, env, clear=True):
            with patch.object(mp.subprocess, "run", boom):
                self.assertIsNone(
                    mp.read_remote_master_head("/repo", remote="prgs")
                )
        self.assertEqual(run_calls["n"], 0)
    def test_hermetic_mode_survives_clear_true_env(self):
        """Module flag, not env pin: clear=True cannot re-enable the probe."""
        run_calls = {"n": 0}
        def boom(*args, **kwargs):
            run_calls["n"] += 1
            raise AssertionError("ls-remote must not run after clear=True")
        with patch.dict(os.environ, {}, clear=True):
            with patch.object(mp.subprocess, "run", boom):
                self.assertIsNone(mp.read_remote_master_head("/repo"))
        self.assertEqual(run_calls["n"], 0)
    def test_explicit_override_still_wins_under_hermetic(self):
        run_calls = {"n": 0}
        def boom(*args, **kwargs):
            run_calls["n"] += 1
            raise AssertionError("override must bypass subprocess")
        with patch.dict(os.environ, {mp.ENV_TEST_LIVE_REMOTE_HEAD: SHA_B}):
            with patch.object(mp.subprocess, "run", boom):
                self.assertEqual(
                    mp.read_remote_master_head("/repo"), SHA_B
                )
        self.assertEqual(run_calls["n"], 0)
 class TestServerWiring(unittest.TestCase):
    """Integration with the gate choke point in the server namespace."""
@@ -337,13 +105,6 @@ class TestServerWiring(unittest.TestCase):
        self._saved = self.srv._STARTUP_PARITY
        self.srv._STARTUP_PARITY = {"root": self.srv.PROJECT_ROOT,
                                    "startup_head": SHA_A}
        # Keep the live-remote read hermetic (no real ls-remote network call):
        # default the live master to the daemon start so parity is fully green
        # unless a test overrides the live head explicitly (#610).
        self._live_patch = patch.dict(
            os.environ, {mp.ENV_TEST_LIVE_REMOTE_HEAD: SHA_A})
        self._live_patch.start()
        self.addCleanup(self._live_patch.stop)
    def tearDown(self):
        self.srv._STARTUP_PARITY = self._saved
@@ -386,36 +147,6 @@ class TestServerWiring(unittest.TestCase):
            self.assertTrue(out["in_parity"])
            self.assertNotIn("report", out)
    # --- #610: live-remote wiring -------------------------------------------
    def test_live_stale_blocks_mutation_though_local_green(self):
        # Local checkout matches the daemon start (local parity green) but the
        # live remote master has advanced -> mutations must fail closed.
        with patch.dict(os.environ, {mp.ENV_TEST_CURRENT_HEAD: SHA_A,
                                     mp.ENV_TEST_LIVE_REMOTE_HEAD: SHA_B}):
            self.assertEqual(self.srv._master_parity_block("gitea.read"), [])
            self.assertTrue(
                self.srv._master_parity_block("gitea.pr.create"))
    def test_assess_tool_exposes_three_distinct_shas(self):
        with patch.dict(os.environ, {mp.ENV_TEST_CURRENT_HEAD: SHA_A,
                                     mp.ENV_TEST_LIVE_REMOTE_HEAD: SHA_B}):
            out = self.srv.gitea_assess_master_parity(remote="prgs")
            self.assertEqual(out["daemon_start_head"], SHA_A)
            self.assertEqual(out["local_head"], SHA_A)
            self.assertEqual(out["live_remote_head"], SHA_B)
            self.assertTrue(out["live_stale"])
            self.assertFalse(out["mutation_safe"])
            self.assertIn("report", out)
    def test_assess_tool_mutation_safe_when_all_three_match(self):
        with patch.dict(os.environ, {mp.ENV_TEST_CURRENT_HEAD: SHA_A,
                                     mp.ENV_TEST_LIVE_REMOTE_HEAD: SHA_A}):
            out = self.srv.gitea_assess_master_parity(remote="prgs")
            self.assertTrue(out["mutation_safe"])
            self.assertFalse(out["live_stale"])
            self.assertNotIn("report", out)
 if __name__ == "__main__":
    unittest.main()
@@ -0,0 +1,149 @@
 """Documentation acceptance for the web console architecture ADR (#632 / epic #631).
 Enforces the acceptance criteria of issue #632:
 * AC1 — the ADR exists and covers layers, authority, phases, API versioning,
  and a page map.
 * AC2 — every #631 child (#632–#651) maps to at least one architectural
  component.
 * AC3 — the closed MVP (#425–#436) is stated as foundation, not recreated.
 * AC4 — forbidden paths are explicit: raw provider incidents as work,
  browser-held tokens, process-kill recovery.
 * AC5 — a controller can approve the document without reading chat history.
 Plus the linkage requirement: ``docs/webui-local-dev.md`` cross-links the ADR.
 """
 from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 ADR = (
    REPO_ROOT
    / "docs"
    / "architecture"
    / "webui-control-plane-console-architecture-adr.md"
 )
 ADR_BASENAME = "webui-control-plane-console-architecture-adr.md"
 LOCAL_DEV = REPO_ROOT / "docs" / "webui-local-dev.md"
 # Epic #631 children, phases 1-4 (twenty capability areas).
 EPIC_CHILDREN = tuple(f"#{number}" for number in range(632, 652))
 def _read(path: Path) -> str:
    assert path.is_file(), f"missing {path.relative_to(REPO_ROOT)}"
    return path.read_text(encoding="utf-8")
 def test_ac1_adr_exists_with_required_sections():
    text = _read(ADR)
    lower = text.lower()
    assert text.lstrip().startswith("#"), "ADR lacks a title"
    assert "#631" in text and "#632" in text
    for heading in (
        "## 2. Decision summary",
        "## 4. Authority boundaries",
        "## 5. Request flow and the redaction boundary",
        "## 6. API naming and versioning",
        "## 7. Page map",
        "## 8. Component ownership",
        "## 9. Phase gates",
        "## 11. Forbidden paths",
    ):
        assert heading in text, f"ADR must contain section {heading!r}"
    assert "browser ui" in lower and "domain loader" in lower
    assert "control-plane db" in lower and "capability gate" in lower
 def test_ac1_api_versioning_is_decided_including_legacy_routes():
    text = _read(ADR)
    assert "/api/v1/" in text, "ADR must decide the versioned API prefix"
    assert "/api/v2/" in text, "ADR must state how breaking changes are handled"
    lower = text.lower()
    assert "compatibility alias" in lower, (
        "ADR must say what happens to the existing unversioned MVP exports"
    )
 def test_ac1_page_map_covers_mvp_routes():
    text = _read(ADR)
    for route in ("`/`", "`/health`", "`/projects`", "`/prompts`", "`/runtime`",
                  "`/audit`", "`/actions`"):
        assert route in text, f"page map must account for MVP route {route}"
 def test_ac2_every_epic_child_maps_to_a_component():
    text = _read(ADR)
    ownership = text.split("## 8. Component ownership", 1)[-1].split("## 9.", 1)[0]
    missing = [child for child in EPIC_CHILDREN if child not in ownership]
    assert not missing, (
        f"epic #631 children without an architectural component: {missing}"
    )
 def test_ac2_every_child_row_declares_a_phase():
    text = _read(ADR)
    ownership = text.split("## 8. Component ownership", 1)[-1].split("## 9.", 1)[0]
    for child in EPIC_CHILDREN:
        row = next(
            (line for line in ownership.splitlines() if line.startswith(f"| {child} ")),
            None,
        )
        assert row is not None, f"no ownership row for {child}"
        assert row.rstrip().endswith(("| 1 |", "| 2 |", "| 3 |", "| 4 |")), (
            f"ownership row for {child} must end with its phase: {row!r}"
        )
 def test_ac3_mvp_is_foundation_not_recreated():
    text = _read(ADR)
    assert "#425" in text and "#436" in text
    lower = text.lower()
    assert "do not recreate" in lower or "recreating mvp scope" in lower
    assert "retained and evolved" in lower
 def test_ac4_forbidden_paths_are_explicit():
    text = _read(ADR)
    forbidden = text.split("## 11. Forbidden paths", 1)[-1].split("## 12.", 1)[0]
    lower = forbidden.lower()
    assert "raw provider incidents" in lower and "#612" in forbidden
    assert "browser-held tokens" in lower
    assert "process-kill recovery" in lower and "#630" in forbidden
    assert "ungated browser mutations" in lower
 def test_ac5_approval_checklist_is_self_contained():
    text = _read(ADR)
    assert "## 12. Approval checklist" in text
    checklist = text.split("## 12. Approval checklist", 1)[-1].split("## 13.", 1)[0]
    for marker in ("1.", "2.", "3.", "4.", "5.", "6."):
        assert marker in checklist, f"approval checklist missing item {marker}"
 def test_adr_states_the_two_boundary_invariants():
    text = _read(ADR)
    lower = text.lower()
    assert "no secrets to the browser" in lower
    assert "no ungated mutations" in lower
 def test_open_questions_are_recorded_not_implied():
    text = _read(ADR)
    assert "## 13. Open questions and follow-ups" in text
    section = text.split("## 13. Open questions and follow-ups", 1)[-1]
    assert "#633" in section, "deferred authorization work must name its issue"
 def test_local_dev_doc_cross_links_the_adr():
    text = _read(LOCAL_DEV)
    assert ADR_BASENAME in text, (
        "docs/webui-local-dev.md must cross-link the console architecture ADR "
        "(issue #632 scope)"
    )
 def test_docs_do_not_embed_secrets():
    for path in (ADR, LOCAL_DEV):
        text = _read(path)
        for marker in ("ghp_", "BEGIN PRIVATE KEY", "Authorization: Bearer"):
            assert marker not in text, f"{path.name} contains {marker!r}"