docs(webui): MCP Control Plane Web Console architecture ADR (Closes #632) #796
Merged
sysadmin
merged 1 commits from 2026-07-22 06:22:11 -05:00
docs/issue-632-web-console-architecture into master
Labels
Clear labels
allocator
anti-stomp
architecture
bug
chore
codex
concurrency
contamination
control-plane
dashboard
database
design
documentation
enhancement
gitea
glitchtip
important
incident
incident-bridge
integration
jenkins
labels
leases
mcp
mcp-health
mcp-menu
multi-project
mutating
nice-to-have
observability
portability
preflight
protected-branch
queue
read-only
reconnect
recovery
refactor
release
reliability
resumable-review
reviewer
roadmap
safety
security
self-hosted
sentry
stale-runtime
status:blocked
status:in-progress
status:pr-open
status:ready
terminal-lock
testing
tracker
type:bug
type:feature
type:feature
type:guardrail
visibility
workflow
workflow-hardening
workflow-hardening
Controller-owned work allocator
Prevent concurrent LLM session stomping
Architecture / structural design
OpenAI Codex client / workflow session surface
Concurrent session safety
Workflow or session contamination incident
MCP control-plane coordination and allocation authority
MCP operational dashboard/queue view
Internal coordination storage (SQLite/Postgres)
Design / investigation, no implementation
Docs / runbooks
New feature or improvement
Gitea MCP workflow
GlitchTip integration
Operational or process incident requiring durable audit trail
Sentry-to-Gitea incident bridging
Integration testing
Jenkins integration
Label taxonomy management
Lease adopt/release/expire lifecycle
MCP server / tooling
MCP namespace and runtime health
MCP menu surface
Work spanning multiple monitoring projects or Gitea repos
Mutating action; requires gating
Observability, metrics, traces, error reporting
Cross-platform / portability
Shared preflight gates before mutation
Protected branch / stable-branch policy concern
Work queue visibility and allocation
Read-only, no mutation
MCP client reconnect/reload recovery path
Recovery paths for stale/foreign leases
Code refactor / restructure
Release / versioning
Reliability / failure handling
Persist and resume prepared review verdicts across sessions
Reviewer workflow tooling
Roadmap / umbrella issue
Safety rails and fail-closed mutation guards
Security / trust boundary
Self-hosted infrastructure integration
Sentry error monitoring integration
Stale backend daemon / runtime-vs-master parity failures
Issue is blocked
Issue is being worked on
Issue has an open pull request
Issue is ready for work
Terminal review lock (#332) path
Tests / test coverage
Issue tracker hygiene / meta
Bug or defect
Feature or enhancement
Feature or enhancement
Safety gate or guardrail
Workflow state visibility for LLMs/operators
Cross-tool workflow
LLM workflow coordination hardening
LLM workflow coordination hardening
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Scaled-Tech-Consulting/Gitea-Tools#796
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Closes #632
Problem
The MVP web UI (#425–#436) ships under
webui/as a read-only Starlette application with ten operator routes and a JSON export beside most of them, but the expanded console described by epic #631 has 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 likeliest failure is not a bad view — it is a privileged action wired into the browser before the authorization and audit model of #633 exists.
What changed
Documentation only. No UI, no API, no deployment-topology change.
docs/architecture/webui-control-plane-console-architecture-adr.md(new, 244 lines).task_capability_mapplusgitea_resolve_task_capabilityremain the only mutation authority; filesystem and git hold local state; providers observe only./api/v1/.... The existing unversioned MVP exports stay as compatibility aliases for the whole of Phase 1 and may be retired no earlier than Phase 2, only after the replacing route ships and the operator doc records the swap. Breaking payload changes require/api/v2/...rather than an in-place edit.docs/webui-local-dev.md. One cross-link paragraph pointing at the ADR, placed beside the existing deployment-doc pointer.tests/test_webui_architecture_docs.py(new). A doc gate in the style oftests/test_stable_control_runtime_policy_docs.py, covering each acceptance criterion rather than mere file existence: required sections present; versioning decision including the fate of the unversioned routes; MVP routes accounted for in the page map; every child #632–#651 present in the ownership table with a phase digit; MVP stated as foundation; all four forbidden paths named with their issue references; the approval checklist self-contained; both boundary invariants stated; open questions naming #633; the cross-link fromdocs/webui-local-dev.md; and no credential markers in either document.Acceptance criteria
test_ac2_every_epic_child_maps_to_a_componenttest_ac4_forbidden_paths_are_explicitTests and results
Run with
venv/bin/python -m pytestfrom the allocated worktree.test_webui_*, offline mode) — 117 passed, 106 subtests passed.Failure classification: the eleven failing node identifiers are byte-for-byte the ones recorded for master
620ed6e9a9550b8da2ceb82d9ab8744e8920490fin PR #794 — six intest_commit_payloads.py, two intest_issue_702_review_findings_f1_f6.py, and one each intest_mcp_server.py::TestPreflightVerification,test_post_merge_moot_lease.py, andtest_reconciler_supersession_close.py. All are author-worktree binding and preflight fixtures; none touches documentation or the web UI. This branch is based on that exact commit, so the comparison is against an identical base. Stated plainly for the reviewer: a fresh baseline worktree was not re-run in this cycle, because this change adds no executable production code — the diff is two Markdown files and one new test module. Pass count moves 4240 → 4252, which is exactly the twelve new cases.Risk
Minimal. The ADR constrains future work and changes no runtime behavior. The one enforcement surface added is the doc gate, which fails only if the ADR loses a required section or the cross-link is dropped.
Known limitations
webui/ci_paths.pytriggers the web UI CI gate onwebui/,tests/test_webui_*, anddocs/webui*. The ADR lives underdocs/architecture/, so editing the ADR alone does not trigger that gate; the new test still runs in the full suite. Widening the filter is recorded as a follow-up in ADR §13 and deliberately left out of a documentation-only change.Adjacent work kept out of scope: #667 (restart status, impact preview, approval controls) belongs to the #655 restart-governance umbrella; the ADR notes it must reuse the #642 action class rather than adding a second restart surface.
Provenance
docs/issue-632-web-console-architecture/Users/jasonwalker/Development/Gitea-Tools/branches/docs-issue-632-web-console-architecturee33b8d37122a1153432a44dcf5213812d7e6ebf6620ed6e9a9550b8da2ceb82d9ab8744e8920490fgitea_commit_filesfrom the worktree, so the local worktree commit52f6e7dand the published head are siblings carrying identical trees; the published head above is authoritative for review.CTH: Author Handoff
Status: published_awaiting_independent_review
Next owner: reviewer (prgs-reviewer / sysadmin)
Current blocker: none
Decision: PR #796 is documentation-only ADR for #632; ready for independent review
Proof: published head
e33b8d37122a1153432a44dcf5213812d7e6ebf6ondocs/issue-632-web-console-architecture; base master; Closes #632Next action: independent formal review at exact head
e33b8d37122a1153432a44dcf5213812d7e6ebf6Ready-to-paste prompt: see NEXT_PROMPT below
Canonical Issue State
STATE: pr_open_awaiting_review
WHO_IS_NEXT: reviewer
NEXT_ACTION: formal independent review of PR #796 at head
e33b8d3712NEXT_PROMPT:
WHAT_HAPPENED: Canonical author handoff posted for already-published PR #796 (incomplete handoff). Implementation and validation evidence are in the PR body.
WHY: Queue hygiene — open PR lacked CTH handoff so reviewer ownership was unclear.
RELATED_PRS: #796 (this PR); parent epic #631
BLOCKERS: none
VALIDATION: See PR body — new doc gate 12 passed; web UI suite 117 passed; full suite 4252 passed / 11 baseline fail.
LAST_UPDATED_BY: jcwalker3 (prgs-author)
REPOSITORY: Scaled-Tech-Consulting/Gitea-Tools
ISSUE: #632
PR: #796
HEAD_SHA:
e33b8d3712BASE_BRANCH: master
ACTING_ROLE: author
ACTING_IDENTITY: jcwalker3
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #796
issue: #632
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 50914-11d3fdcfec3f
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-796
phase: claimed
candidate_head:
e33b8d3712target_branch: master
target_branch_sha:
5032965e3alast_activity: 2026-07-22T11:20:38Z
expires_at: 2026-07-22T11:30:38Z
blocker: none
Canonical PR State
STATE: approved
WHO_IS_NEXT: merger
NEXT_ACTION: Merge PR #796 via gated gitea_merge_pr with expected_head_sha
e33b8d3712and confirmation MERGE PR 796.NEXT_PROMPT:
WHAT_HAPPENED: Independent review of next eligible open PR #796 after skipping #794 and #795 (live REQUEST_CHANGES at unchanged heads). Docs-only ADR + cross-link + doc-gate tests. Validation passed in branches/review-pr-796 via native MCP.
WHY: Scope matches #632 only; ACs 1-5 met by ADR and gated by tests; no production runtime change; layer/authority/redaction/versioning/page map/phase gates/forbidden paths explicit.
ISSUE: #632
HEAD_SHA:
e33b8d3712REVIEW_STATUS: approved / approval_at_current_head
MERGE_READY: true
BLOCKERS: none
VALIDATION: pytest tests/test_webui_architecture_docs.py 12 passed; pytest -k webui 117 passed 106 subtests; worktree clean; not already-landed; mergeable true; author jcwalker3 != sysadmin
NATIVE_REVIEW_PROOF: transport=native_mcp; entrypoint=mcp_server; token_fingerprint=73992c6535105066
LAST_UPDATED_BY: sysadmin (prgs-reviewer)
Review summary
Approve. Documentation-only change that correctly closes #632 without over-claiming epic #631.
Diff: ADR (layers, authority, redaction invariants, /api/v1 versioning, page map, all children #632-#651 with phases, phase gates, forbidden paths, checklist), webui-local-dev cross-link, doc-gate tests.
Validation: 12/12 architecture tests; 117 webui tests green.
adopted_at: 2026-07-22T11:21:56Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 50914-11d3fdcfec3f
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 14130
adoption_reason: merger-handoff-approved-head
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #796
issue: #632
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 50911-62ac4e098ef9
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-796
phase: adopted
candidate_head:
e33b8d3712target_branch: master
target_branch_sha:
5032965e3alast_activity: 2026-07-22T11:21:56Z
expires_at: 2026-07-22T11:31:56Z
blocker: none
Stale #332 review-decision lock cleanup (#594)
Status: APPLIED
sysadminprgs-merger2026-07-22T11:22:13.265454+00:00approveon PR docs(webui): MCP Control Plane Web Console architecture ADR (Closes #632) (#796)closed(merged=True)0b294040314ecf661dcd010cb55a05d923233a953prgs-reviewerManual deletion of session-state files is not the workflow.
This path only clears a lock when the referenced PR is merged/closed.