fix: hide empty-state copy on queue credential fail-closed (Closes #458)

When fetch_error is set, render only the unavailable banner and an
explicit not-fetched inventory note. Suppress queue tables, pagination
proof, and "No open items." copy that implied a successful empty fetch.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

docs/webui-local-dev.md

@@ -0,0 +1,89 @@
+# Internal web UI — local development (#426)
+
+Read-only MVP skeleton for the MCP Control Plane operator console. Gitea,
+MCP capability gates, and `skills/llm-project-workflow/` remain the source of
+truth; this UI only provides route stubs and layout.
+
+## Prerequisites
+
+- Python 3.11+ with project dependencies installed (`pip install -r requirements.txt`)
+- No secrets in repo, config, or client bundle
+
+## Start the server
+
+From the repository root (or an issue worktree):
+
+```bash
+./scripts/run-webui
+```
+
+Or directly:
+
+```bash
+python3 -m webui
+```
+
+Optional environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `WEBUI_HOST` | `127.0.0.1` | Bind address (keep local for MVP) |
+| `WEBUI_PORT` | `8765` | Listen port |
+
+## Routes (MVP)
+
+| Path | Description |
+|------|-------------|
+| `/` | Home / operator overview |
+| `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`) |
+| `/queue` | Live PR and issue queue dashboard (#429) |
+| `/api/queue` | JSON queue export with pagination metadata |
+| `/projects` | Project registry list (#427) |
+| `/projects/{id}` | Project detail + onboarding checklist |
+| `/api/projects` | JSON registry export |
+| `/prompts` | Prompt library with per-prompt copy buttons (#428) |
+| `/api/prompts` | JSON prompt export with workflow hashes |
+| `/runtime` | Stub — MCP runtime health (#430) |
+| `/audit` | Stub — report audit paste (#431) |
+| `/worktrees` | Stub — hygiene dashboard (#432) |
+| `/leases` | Stub — lease visibility (#433) |
+
+All routes are GET-only. POST/PUT/PATCH/DELETE return `405` with
+`read-only-mvp`.
+
+## Project registry (#427)
+
+Versioned registry file: `webui/data/projects.registry.json` (schema version `1`).
+
+Override path with `WEBUI_PROJECT_REGISTRY` when operators keep a machine-local
+copy outside git. The registry stores repo identity, remotes, profile names,
+workflow/schema path references, and onboarding checklist steps — never tokens
+or credentials.
+
+Seed entry: **Gitea-Tools** on `https://gitea.prgs.cc` with `prgs-author`,
+`prgs-reviewer`, and `prgs-reconciler` profiles.
+
+## Prompt library (#428)
+
+Prompts are generated at load time from canonical workflow files under
+`skills/llm-project-workflow/workflows/`. SHA-256 hashes are computed from
+`WEBUI_REPO_ROOT` (defaults to the repository root). Prompt bodies are short
+copy/paste starters; canonical workflow files remain the only full policy
+source.
+
+## Live queue dashboard (#429)
+
+`/queue` loads open PRs and issues for the default registry project (seed:
+**Gitea-Tools** on `https://gitea.prgs.cc`) using existing `gitea_auth` read
+credentials. The UI surfaces pagination proof (returned count, pages fetched,
+`has_more`, `inventory_complete`) and classification badges (`claimed`,
+`blocked`, `in-review`, `duplicate`) when evidence exists.
+
+If credentials are missing or the fetch fails, the page shows an explicit error
+instead of an empty queue (fail closed).
+
+## Tests
+
+```bash
+pytest tests/test_webui_skeleton.py tests/test_webui_project_registry.py tests/test_webui_prompt_library.py tests/test_webui_queue_dashboard.py -q
+```

final_report_validator.py

@@ -115,22 +115,6 @@ _TARGET_BRANCH_SHA_RE = re.compile(
     r"target branch sha\s*:\s*[0-9a-f]{40}",
     re.IGNORECASE,
 )
-_WORKFLOW_LOAD_HELPER_RE = re.compile(
-    r"workflow[- ]load helper result\s*:",
-    re.IGNORECASE,
-)
-_WORKFLOW_LOAD_HASH_RE = re.compile(
-    r"workflow[- ]load helper result[\s\S]{0,400}?workflow[_ ]hash\s*:\s*[0-9a-f]{12}",
-    re.IGNORECASE,
-)
-_WORKFLOW_LOAD_BOUNDARY_RE = re.compile(
-    r"workflow[- ]load helper result[\s\S]{0,400}?boundary[_ ]status\s*:\s*(?:clean|violation)",
-    re.IGNORECASE,
-)
-_WORKFLOW_FILE_VIEW_NARRATIVE_RE = re.compile(
-    r"(?:read|viewed|loaded)\s+(?:the\s+)?(?:canonical\s+)?(?:workflow|review-merge-pr\.md)",
-    re.IGNORECASE,
-)
 _FULL_SHA_RE = re.compile(r"\b[0-9a-f]{40}\b", re.IGNORECASE)
 _RECONCILE_STALE_FIELDS = (
     "pr number opened",
@@ -886,54 +870,6 @@ def _rule_reviewer_mutation_ledger(
     )
 
 
-def _rule_reviewer_workflow_load_boundary(report_text: str) -> list[dict[str, str]]:
-    """#403: require structured workflow-load helper result, not file-view narrative."""
-    if not report_text.strip():
-        return []
-    findings: list[dict[str, str]] = []
-    has_helper = bool(_WORKFLOW_LOAD_HELPER_RE.search(report_text))
-    has_hash = bool(_WORKFLOW_LOAD_HASH_RE.search(report_text))
-    has_boundary = bool(_WORKFLOW_LOAD_BOUNDARY_RE.search(report_text))
-    has_narrative_only = bool(_WORKFLOW_FILE_VIEW_NARRATIVE_RE.search(report_text))
-
-    if has_narrative_only and not has_helper:
-        findings.append(validator_finding(
-            "reviewer.workflow_load_boundary",
-            "block",
-            "Workflow-load helper result",
-            (
-                "canonical workflow file-view narrative without structured "
-                "gitea_load_review_workflow helper result"
-            ),
-            (
-                "include Workflow-load helper result with workflow_hash and "
-                "boundary_status from gitea_load_review_workflow"
-            ),
-        ))
-        return findings
-
-    if has_helper and (not has_hash or not has_boundary):
-        missing = []
-        if not has_hash:
-            missing.append("workflow_hash")
-        if not has_boundary:
-            missing.append("boundary_status")
-        findings.append(validator_finding(
-            "reviewer.workflow_load_boundary",
-            "block",
-            "Workflow-load helper result",
-            (
-                "workflow-load helper result incomplete; missing "
-                + ", ".join(missing)
-            ),
-            (
-                "copy workflow_load_helper_result fields from "
-                "gitea_load_review_workflow into the final report"
-            ),
-        ))
-    return findings
-
-
 def _rule_reviewer_review_mutation(
     report_text: str,
     *,
@@ -971,7 +907,6 @@ _RULES_BY_TASK: dict[str, list[Callable[..., list[dict[str, str]]]]] = {
         _rule_reviewer_already_landed_eligible,
         _rule_reviewer_already_landed_state,
         _rule_reviewer_target_branch_freshness,
-        _rule_reviewer_workflow_load_boundary,
         _rule_reviewer_mutation_ledger,
         _rule_reviewer_review_mutation,
     ],

gitea_mcp_server.py

@@ -440,10 +440,48 @@ def verify_preflight_purity(remote: str | None = None, worktree_path: str | None
             "Pre-flight order violation: Task capability (gitea_resolve_task_capability) has not been resolved (fail closed)"
         )
 
-    if worktree_path:
+    workspace = author_mutation_worktree.resolve_mutation_workspace(
-        dirty_files = sorted(_parse_porcelain_entries(_get_workspace_porcelain(worktree_path)))
+        worktree_path,
+        PROJECT_ROOT,
+        active_worktree_env=os.environ.get(ACTIVE_WORKTREE_ENV),
+        author_worktree_env=os.environ.get(AUTHOR_WORKTREE_ENV),
+    )
+    real_workspace = os.path.realpath(workspace)
+    real_root = os.path.realpath(PROJECT_ROOT)
+
+    if real_workspace != real_root:
+        if not _preflight_in_test_mode():
+            if not os.path.exists(real_workspace):
+                raise RuntimeError(
+                    f"Branches-only mutation guard (#274): worktree path '{workspace}' does not exist (fail closed)"
+                )
+            if not os.path.isdir(real_workspace):
+                raise RuntimeError(
+                    f"Branches-only mutation guard (#274): worktree path '{workspace}' is not a directory (fail closed)"
+                )
+            try:
+                res = subprocess.run(
+                    ["git", "-C", real_workspace, "rev-parse", "--git-common-dir"],
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                )
+                common_dir = os.path.realpath(res.stdout.strip())
+                expected_dir = os.path.realpath(os.path.join(real_root, ".git"))
+                if common_dir != expected_dir:
+                    raise RuntimeError(
+                        f"Branches-only mutation guard (#274): worktree '{workspace}' does not belong to the target repository '{PROJECT_ROOT}' (fail closed)"
+                    )
+            except Exception as e:
+                if isinstance(e, RuntimeError):
+                    raise e
+                raise RuntimeError(
+                    f"Branches-only mutation guard (#274): worktree '{workspace}' is not a valid git repository (fail closed)"
+                )
+
+        dirty_files = sorted(_parse_porcelain_entries(_get_workspace_porcelain(workspace)))
         if dirty_files:
-            details = _preflight_workspace_details(worktree_path, dirty_files)
+            details = _preflight_workspace_details(workspace, dirty_files)
             raise RuntimeError(
                 "Pre-flight order violation: Active task workspace has tracked "
                 "file edits before mutation (fail closed). "
@@ -498,8 +536,6 @@ import role_session_router  # noqa: E402
 import role_namespace_gate  # noqa: E402
 import task_capability_map  # noqa: E402
 import review_proofs  # noqa: E402
-import review_workflow_boundary  # noqa: E402
-import review_workflow_load  # noqa: E402
 import agent_temp_artifacts
 import issue_lock_worktree  # noqa: E402
 import already_landed_reconcile  # noqa: E402
@@ -974,6 +1010,7 @@ def gitea_create_issue(
     repo: str | None = None,
     allow_duplicate_override: bool = False,
     split_from_issue: int | None = None,
+    worktree_path: str | None = None,
 ) -> dict:
     """Create a new issue on a Gitea repository.
 
@@ -986,6 +1023,7 @@ def gitea_create_issue(
         repo: Override the repository name.
         allow_duplicate_override: Operator-approved split after duplicate found.
         split_from_issue: Existing duplicate issue number when overriding.
+        worktree_path: Optional path to verify branches-only guard.
 
     Returns:
         dict with 'number' of the created issue ('url' only with the reveal opt-in).
@@ -1012,7 +1050,7 @@ def gitea_create_issue(
     )
     if blocked:
         return blocked
-    verify_preflight_purity(remote)
+    verify_preflight_purity(remote, worktree_path=worktree_path)
     base = repo_api_url(h, o, r)
     open_issues = api_get_all(f"{base}/issues?state=open&type=issues", auth)
     closed_issues = api_get_all(
@@ -1824,7 +1862,6 @@ def init_review_decision_lock(remote: str | None, task: str | None):
     """Seed read-only-until-ready state for reviewer PR review tasks."""
     if task != "review_pr":
         return
-    review_workflow_load.clear_review_workflow_load()
     profile = get_profile()
     profile_name = (profile.get("profile_name") or "").strip()
     session_lock = (
@@ -1850,11 +1887,6 @@ def init_review_decision_lock(remote: str | None, task: str | None):
     })
 
 
-def _review_workflow_load_gate_reasons() -> list[str]:
-    """Fail closed when canonical review workflow was not loaded (#389)."""
-    return review_workflow_load.review_workflow_load_blockers(PROJECT_ROOT)
-
-
 def check_review_decision_gate(
     pr_number: int,
     action: str,
@@ -1865,10 +1897,7 @@ def check_review_decision_gate(
     repo: str | None = None,
 ) -> list[str]:
     """Fail closed unless validation completed and the final decision is ready."""
-    reasons = list(_review_workflow_load_gate_reasons())
+    reasons = []
-    if reasons:
-        reasons.extend(review_workflow_load.recovery_handoff_without_replay())
-        return reasons
     lock = _load_review_decision_lock()
     if lock is None:
         reasons.append(
@@ -2224,7 +2253,6 @@ def _evaluate_pr_review_submission(
     """Shared gate chain for live submit and dry-run review tools."""
     verify_preflight_purity(remote)
     action = (action or "").strip().lower()
-    workflow_blockers = _review_workflow_load_gate_reasons() if live else []
     result = {
         "requested_action": action,
         "performed": False,
@@ -2240,10 +2268,6 @@ def _evaluate_pr_review_submission(
         "reasons": [],
     }
     reasons = result["reasons"]
-    if workflow_blockers:
-        reasons.extend(workflow_blockers)
-        reasons.extend(review_workflow_load.recovery_handoff_without_replay())
-        return result
 
     if action not in _REVIEW_ACTIONS:
         reasons.append(
@@ -2428,13 +2452,6 @@ def gitea_mark_final_review_decision(
         }
     org = resolved_org
     repo = resolved_repo
-    workflow_blockers = _review_workflow_load_gate_reasons()
-    if workflow_blockers:
-        return {
-            "marked_ready": False,
-            "reasons": workflow_blockers + (
-                review_workflow_load.recovery_handoff_without_replay()),
-        }
     hard_stop = terminal_review_hard_stop_reasons(pr_number, "mark_ready")
     if hard_stop:
         return {"marked_ready": False, "reasons": hard_stop}
@@ -3018,7 +3035,6 @@ def gitea_merge_pr(
         available. Never secrets.
     """
     verify_preflight_purity(remote)
-    workflow_blockers = _review_workflow_load_gate_reasons()
     do = (do or "").strip().lower()
     result = {
         "performed": False,
@@ -3036,10 +3052,6 @@ def gitea_merge_pr(
         "reasons": [],
     }
     reasons = result["reasons"]
-    if workflow_blockers:
-        reasons.extend(workflow_blockers)
-        reasons.extend(review_workflow_load.recovery_handoff_without_replay())
-        return result
 
     # Gate 1 — valid merge method (no API call on a bad method).
     if do not in _MERGE_METHODS:
@@ -4776,8 +4788,6 @@ _PROJECT_SKILLS = {
         "steps": [
             "Resolve task first: gitea_resolve_task_capability(task='review_pr') "
             "to confirm reviewer namespace and avoid author-profile blocks.",
-            "Load canonical workflow proof with gitea_load_review_workflow "
-            "before any review/merge mutation (#389).",
             "Verify reviewer identity with gitea_whoami; the PR author "
             "must be a different user.",
             "Reconcile live queue state FIRST (do not trust prior handoffs): "
@@ -5701,8 +5711,6 @@ def gitea_get_runtime_context(
         ),
         "role_kind": _role_kind(allowed, forbidden),
         "shell_health": native_mcp_preference.shell_health_status(),
-        "workflow_load_proof": review_workflow_load.workflow_load_status(
-            PROJECT_ROOT),
     }
 
     if reveal and h:
@@ -5711,80 +5719,6 @@ def gitea_get_runtime_context(
     return result
 
 
-@mcp.tool()
-def gitea_record_pre_review_command(
-    command: str,
-    cwd: str | None = None,
-    classification: str | None = None,
-) -> dict:
-    """Classify and record a command executed before workflow load (#403).
-
-    Read-only with respect to Gitea API. Pre-review inventory/diagnostic commands
-    may be recorded as allowed; boundary violations block reviewer mutations.
-    """
-    recorded = review_workflow_boundary.record_pre_review_command(
-        command,
-        cwd=cwd,
-        project_root=PROJECT_ROOT,
-        classification=classification,
-    )
-    boundary_state = review_workflow_boundary.assess_boundary_status(PROJECT_ROOT)
-    return {
-        "success": True,
-        "recorded": recorded,
-        "boundary_status": boundary_state.get("boundary_status"),
-        "boundary_clean": boundary_state.get("boundary_clean"),
-        "reasons": list(boundary_state.get("reasons") or []),
-    }
-
-
-@mcp.tool()
-def gitea_load_review_workflow(
-    prompt_text: str | None = None,
-) -> dict:
-    """Load and record canonical review-merge workflow proof for this session (#389, #403).
-
-    Read-only with respect to Gitea API; records in-process workflow source/hash
-    proof and session boundary state required before reviewer review or merge
-    mutations.
-    """
-    try:
-        recorded = review_workflow_load.record_review_workflow_load(
-            PROJECT_ROOT, prompt_text=prompt_text)
-    except OSError as exc:
-        return {
-            "success": False,
-            "loaded": False,
-            "reasons": [str(exc)],
-            "recovery_handoff": review_workflow_load.recovery_handoff_without_replay(),
-        }
-    boundary_reasons = review_workflow_boundary.boundary_blockers(PROJECT_ROOT)
-    helper = review_workflow_boundary.workflow_load_helper_result(
-        recorded, PROJECT_ROOT)
-    return {
-        "success": not boundary_reasons,
-        "loaded": True,
-        "workflow_source": recorded["workflow_source"],
-        "task_mode": recorded["task_mode"],
-        "workflow_hash": recorded["workflow_hash"],
-        "workflow_version": recorded["workflow_version"],
-        "final_report_schema_path": recorded["final_report_schema_path"],
-        "final_report_schema_hash": recorded["final_report_schema_hash"],
-        "prompt_conflicts_with_workflow": recorded[
-            "prompt_conflicts_with_workflow"],
-        "prompt_conflict_reasons": recorded.get("prompt_conflict_reasons") or [],
-        "workflow_load_proof_present": True,
-        "boundary_status": recorded.get("boundary_status"),
-        "boundary_clean": recorded.get("boundary_clean"),
-        "workflow_load_helper_result": helper,
-        "reasons": boundary_reasons,
-        "recovery_handoff": (
-            review_workflow_load.recovery_handoff_without_replay()
-            if boundary_reasons else []
-        ),
-    }
-
-
 @mcp.tool()
 def gitea_list_profiles() -> dict:
     """Read-only: list all Gitea MCP profiles with redacted metadata.
@@ -6840,16 +6774,6 @@ def gitea_resolve_task_capability(
     }
     if reason_msg:
         result["reason"] = reason_msg
-    if task in ("review_pr", "merge_pr"):
-        result["workflow_load_proof"] = review_workflow_load.workflow_load_status(
-            PROJECT_ROOT)
-        if not result["workflow_load_proof"].get("workflow_load_valid"):
-            guidance = (
-                "Call gitea_load_review_workflow before any reviewer review "
-                "or merge mutation."
-            )
-            if guidance not in task_role_guidance:
-                task_role_guidance.append(guidance)
     role_session_router.sync_route_from_capability(result)
     was_terminal = capability_stop_terminal.is_active()
     terminal = capability_stop_terminal.sync_from_capability_result(result)

review_workflow_boundary.py

@@ -1,259 +0,0 @@
-"""Reviewer session boundary tracking for workflow-load gate (#403).
-
-Pre-review commands executed before ``gitea_load_review_workflow`` must be
-classified. Boundary violations block downstream reviewer mutations even when
-workflow hash proof is present.
-"""
-
-from __future__ import annotations
-
-import os
-import re
-from typing import Any
-
-CLASSIFICATION_READ_ONLY_INVENTORY = "read_only_inventory"
-CLASSIFICATION_DIAGNOSTIC = "diagnostic"
-CLASSIFICATION_BOUNDARY_VIOLATION = "boundary_violation"
-CLASSIFICATION_UNCLASSIFIED = "unclassified"
-
-ALLOWED_CLASSIFICATIONS = frozenset({
-    CLASSIFICATION_READ_ONLY_INVENTORY,
-    CLASSIFICATION_DIAGNOSTIC,
-    CLASSIFICATION_BOUNDARY_VIOLATION,
-    CLASSIFICATION_UNCLASSIFIED,
-})
-
-_PRE_REVIEW_COMMANDS: list[dict[str, Any]] = []
-
-_READ_ONLY_INVENTORY_PATTERNS = (
-    re.compile(
-        r"\bgitea[_-](?:list|view|whoami|get[-_]|resolve[-_]task|check[-_]pr|route[-_]task)",
-        re.I,
-    ),
-    re.compile(r"\bgit\s+(?:fetch|remote\s+update|branch\s+-a|log|show|rev-parse)\b", re.I),
-    re.compile(r"\bgit\s+status\b", re.I),
-    re.compile(r"\bgit\s+worktree\s+list\b", re.I),
-)
-
-_DIAGNOSTIC_PATTERNS = (
-    re.compile(r"\bgit\s+diff(?:\s+--stat)?\b", re.I),
-    re.compile(r"\bwhich\s+pytest\b", re.I),
-    re.compile(r"\bpytest\s+--version\b", re.I),
-)
-
-_BOUNDARY_VIOLATION_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
-    (re.compile(r"\b(?:pytest|python\s+-m\s+pytest|python\s+-m\s+unittest)\b", re.I),
-     "validation command before workflow load"),
-    (re.compile(r"\bprofiles\.json\b", re.I), "local profile config inspection"),
-    (re.compile(r"\bgitea-mcp(?:\.v2-contexts)?\.json\b", re.I),
-     "local Gitea MCP config inspection"),
-    (re.compile(r"\b\.env(?:\.|$|\b)", re.I), "credential file inspection"),
-    (re.compile(r"\bkeychain\b", re.I), "credential store inspection"),
-    (re.compile(r"\bpkill\b", re.I), "MCP repair activity"),
-    (re.compile(r"\b(?:edit|write|modify).{0,40}\bmcp\b", re.I),
-     "MCP config exploration"),
-    (re.compile(r"\bgit\s+(?:add|commit|reset|clean|checkout|merge|rebase|push)\b", re.I),
-     "git mutation before workflow load"),
-)
-
-
-def clear_pre_review_commands() -> None:
-    """Test helper and session reset."""
-    global _PRE_REVIEW_COMMANDS
-    _PRE_REVIEW_COMMANDS = []
-
-
-def pre_review_commands() -> list[dict[str, Any]]:
-    """Return a shallow copy of recorded pre-review commands."""
-    return [dict(entry) for entry in _PRE_REVIEW_COMMANDS]
-
-
-def _normalize_path(path: str | None) -> str:
-    return os.path.realpath(os.path.abspath((path or "").strip() or os.getcwd()))
-
-
-def is_main_checkout_path(cwd: str | None, project_root: str | None) -> bool:
-    """True when *cwd* is the stable control checkout (not under branches/)."""
-    if not project_root:
-        return False
-    root = _normalize_path(project_root)
-    path = _normalize_path(cwd)
-    if path != root:
-        return False
-    marker = f"{os.sep}branches{os.sep}"
-    return marker not in path
-
-
-def classify_pre_review_command(
-    command: str,
-    *,
-    cwd: str | None = None,
-    project_root: str | None = None,
-) -> dict[str, Any]:
-    """Classify a command executed before workflow load."""
-    text = (command or "").strip()
-    path = _normalize_path(cwd)
-    root = _normalize_path(project_root) if project_root else None
-    reasons: list[str] = []
-
-    for pattern, label in _BOUNDARY_VIOLATION_PATTERNS:
-        if pattern.search(text):
-            if label.startswith("validation") and root and not is_main_checkout_path(path, root):
-                continue
-            if label.startswith("git mutation") and root and not is_main_checkout_path(path, root):
-                continue
-            reasons.append(label)
-            return {
-                "command": text,
-                "cwd": path,
-                "classification": CLASSIFICATION_BOUNDARY_VIOLATION,
-                "reasons": reasons,
-            }
-
-    for pattern in _READ_ONLY_INVENTORY_PATTERNS:
-        if pattern.search(text):
-            return {
-                "command": text,
-                "cwd": path,
-                "classification": CLASSIFICATION_READ_ONLY_INVENTORY,
-                "reasons": [],
-            }
-
-    for pattern in _DIAGNOSTIC_PATTERNS:
-        if pattern.search(text):
-            return {
-                "command": text,
-                "cwd": path,
-                "classification": CLASSIFICATION_DIAGNOSTIC,
-                "reasons": [],
-            }
-
-    if root and is_main_checkout_path(path, root):
-        if re.search(r"\b(?:cat|head|less|read)\b", text, re.I):
-            if re.search(r"workflow|skill|runbook", text, re.I):
-                return {
-                    "command": text,
-                    "cwd": path,
-                    "classification": CLASSIFICATION_BOUNDARY_VIOLATION,
-                    "reasons": [
-                        "canonical workflow viewed as local file without "
-                        "gitea_load_review_workflow (narrative load is not proof)"
-                    ],
-                }
-
-    return {
-        "command": text,
-        "cwd": path,
-        "classification": CLASSIFICATION_UNCLASSIFIED,
-        "reasons": [
-            "pre-review command not classified; record via "
-            "gitea_record_pre_review_command before workflow load"
-        ],
-    }
-
-
-def record_pre_review_command(
-    command: str,
-    *,
-    cwd: str | None = None,
-    project_root: str | None = None,
-    classification: str | None = None,
-) -> dict[str, Any]:
-    """Record and classify a pre-review command for the current session."""
-    assessed = classify_pre_review_command(
-        command, cwd=cwd, project_root=project_root)
-    if classification:
-        if classification not in ALLOWED_CLASSIFICATIONS:
-            assessed["classification"] = CLASSIFICATION_UNCLASSIFIED
-            assessed["reasons"] = [
-                f"unknown classification '{classification}'; fail closed"
-            ]
-        else:
-            assessed["classification"] = classification
-            assessed["reasons"] = []
-    entry = {
-        **assessed,
-        "session_pid": os.getpid(),
-    }
-    _PRE_REVIEW_COMMANDS.append(entry)
-    return dict(entry)
-
-
-def assess_boundary_status(project_root: str | None = None) -> dict[str, Any]:
-    """Summarize pre-review boundary state for session proof and reports."""
-    violations = [
-        entry for entry in _PRE_REVIEW_COMMANDS
-        if entry.get("classification") == CLASSIFICATION_BOUNDARY_VIOLATION
-    ]
-    unclassified = [
-        entry for entry in _PRE_REVIEW_COMMANDS
-        if entry.get("classification") == CLASSIFICATION_UNCLASSIFIED
-    ]
-    reasons: list[str] = []
-    for entry in violations:
-        reasons.extend(entry.get("reasons") or [
-            f"boundary violation: {entry.get('command', '')[:80]}"
-        ])
-    for entry in unclassified:
-        reasons.extend(entry.get("reasons") or [
-            "unclassified pre-review command blocks reviewer mutations"
-        ])
-
-    clean = not reasons
-    return {
-        "boundary_status": "clean" if clean else "violation",
-        "boundary_clean": clean,
-        "pre_review_command_count": len(_PRE_REVIEW_COMMANDS),
-        "boundary_violation_count": len(violations),
-        "unclassified_command_count": len(unclassified),
-        "violations": [
-            {
-                "command": v.get("command"),
-                "cwd": v.get("cwd"),
-                "reasons": list(v.get("reasons") or []),
-            }
-            for v in violations
-        ],
-        "reasons": reasons,
-    }
-
-
-def boundary_blockers(project_root: str | None = None) -> list[str]:
-    """Reasons reviewer mutations must fail closed due to boundary state."""
-    status = assess_boundary_status(project_root)
-    if status.get("boundary_clean"):
-        return []
-    return list(status.get("reasons") or [
-        "reviewer session boundary violation before workflow load"
-    ])
-
-
-def workflow_load_helper_result(
-    load: dict | None,
-    project_root: str | None = None,
-) -> dict[str, Any]:
-    """Structured helper result for final reports (#403)."""
-    boundary = assess_boundary_status(project_root)
-    if load is None:
-        return {
-            "workflow_load_proof_present": False,
-            "workflow_source": None,
-            "workflow_hash": None,
-            "final_report_schema_hash": None,
-            "boundary_status": boundary.get("boundary_status"),
-            "boundary_clean": False,
-            "reasons": [
-                "gitea_load_review_workflow helper result missing from report"
-            ],
-        }
-    return {
-        "workflow_load_proof_present": True,
-        "workflow_source": load.get("workflow_source"),
-        "workflow_hash": load.get("workflow_hash"),
-        "final_report_schema_path": load.get("final_report_schema_path"),
-        "final_report_schema_hash": load.get("final_report_schema_hash"),
-        "boundary_status": load.get("boundary_status", boundary.get("boundary_status")),
-        "boundary_clean": bool(load.get("boundary_clean", boundary.get("boundary_clean"))),
-        "pre_review_command_count": boundary.get("pre_review_command_count"),
-        "reasons": [],
-    }

review_workflow_load.py

@@ -1,217 +0,0 @@
-"""Canonical review-merge workflow load proof for reviewer mutations (#389, #403)."""
-
-from __future__ import annotations
-
-import hashlib
-import os
-import re
-from pathlib import Path
-
-import review_workflow_boundary as boundary
-
-WORKFLOW_REL_PATH = (
-    "skills/llm-project-workflow/workflows/review-merge-pr.md"
-)
-SCHEMA_REL_PATH = (
-    "skills/llm-project-workflow/schemas/review-merge-final-report.md"
-)
-TASK_MODE = "review-merge-pr"
-LOAD_TOOL_NAME = "gitea_load_review_workflow"
-
-_REVIEW_WORKFLOW_LOAD: dict | None = None
-
-
-def compute_content_hash(text: str) -> str:
-    """Short deterministic hash for workflow/schema version proof."""
-    return hashlib.sha256((text or "").encode("utf-8")).hexdigest()[:12]
-
-
-def _read_text(path: Path) -> str:
-    return path.read_text(encoding="utf-8")
-
-
-def _canonical_paths(project_root: str) -> tuple[Path, Path]:
-    root = Path(project_root)
-    workflow = root / WORKFLOW_REL_PATH
-    schema = root / SCHEMA_REL_PATH
-    if not workflow.is_file():
-        raise FileNotFoundError(f"canonical workflow missing: {workflow}")
-    if not schema.is_file():
-        raise FileNotFoundError(f"final report schema missing: {schema}")
-    return workflow, schema
-
-
-def build_canonical_workflow_metadata(
-    project_root: str,
-    *,
-    prompt_text: str | None = None,
-) -> dict:
-    """Load workflow + schema from disk and compute proof metadata."""
-    workflow_path, schema_path = _canonical_paths(project_root)
-    workflow_text = _read_text(workflow_path)
-    schema_text = _read_text(schema_path)
-    workflow_hash = compute_content_hash(workflow_text)
-    schema_hash = compute_content_hash(schema_text)
-    conflict, conflict_reasons = assess_prompt_conflict(prompt_text)
-    return {
-        "workflow_source": WORKFLOW_REL_PATH,
-        "workflow_path": str(workflow_path),
-        "task_mode": TASK_MODE,
-        "workflow_hash": workflow_hash,
-        "workflow_version": workflow_hash,
-        "final_report_schema_path": SCHEMA_REL_PATH,
-        "final_report_schema_hash": schema_hash,
-        "prompt_conflicts_with_workflow": conflict,
-        "prompt_conflict_reasons": conflict_reasons,
-        "load_tool": LOAD_TOOL_NAME,
-    }
-
-
-def assess_prompt_conflict(prompt_text: str | None) -> tuple[bool, list[str]]:
-    """Detect obvious task-mode conflicts between prompt and review workflow."""
-    if not (prompt_text or "").strip():
-        return False, []
-    text = prompt_text.lower()
-    reasons: list[str] = []
-    conflicting = (
-        (r"\bwork[- ]issue\b", "work-issue author mode"),
-        (r"\bcreate[- ]issue\b", "create-issue mode"),
-        (r"\bauthor/coder\b", "author/coder mode"),
-        (r"\breconcile[- ]landed\b", "reconcile-landed mode"),
-    )
-    for pattern, label in conflicting:
-        if re.search(pattern, text):
-            reasons.append(
-                f"active prompt appears to request {label} while loading "
-                f"{TASK_MODE} workflow"
-            )
-    return bool(reasons), reasons
-
-
-def record_review_workflow_load(
-    project_root: str,
-    *,
-    prompt_text: str | None = None,
-) -> dict:
-    """Record in-process workflow load proof for the current MCP session."""
-    global _REVIEW_WORKFLOW_LOAD
-    meta = build_canonical_workflow_metadata(
-        project_root, prompt_text=prompt_text)
-    boundary_state = boundary.assess_boundary_status(project_root)
-    _REVIEW_WORKFLOW_LOAD = {
-        **meta,
-        "session_pid": os.getpid(),
-        "loaded": True,
-        "boundary_status": boundary_state.get("boundary_status"),
-        "boundary_clean": boundary_state.get("boundary_clean"),
-        "pre_review_command_count": boundary_state.get("pre_review_command_count"),
-        "boundary_violation_count": boundary_state.get("boundary_violation_count"),
-        "boundary_reasons": list(boundary_state.get("reasons") or []),
-    }
-    return dict(_REVIEW_WORKFLOW_LOAD)
-
-
-def clear_review_workflow_load() -> None:
-    """Test helper and review_pr session reset."""
-    global _REVIEW_WORKFLOW_LOAD
-    _REVIEW_WORKFLOW_LOAD = None
-    boundary.clear_pre_review_commands()
-
-
-def workflow_load_status(project_root: str | None = None) -> dict:
-    """Non-throwing status for capability/runtime reports."""
-    load = _REVIEW_WORKFLOW_LOAD
-    if load is None:
-        return {
-            "workflow_load_proof_present": False,
-            "workflow_load_valid": False,
-            "workflow_source": None,
-            "workflow_hash": None,
-            "final_report_schema_path": SCHEMA_REL_PATH,
-            "reasons": [
-                f"{LOAD_TOOL_NAME} has not been called in this session "
-                "(fail closed for reviewer mutations)"
-            ],
-        }
-    reasons = _session_validation_reasons(load, project_root)
-    boundary_reasons = boundary.boundary_blockers(project_root)
-    if boundary_reasons:
-        reasons = list(reasons) + boundary_reasons
-    return {
-        "workflow_load_proof_present": True,
-        "workflow_load_valid": not reasons,
-        "workflow_source": load.get("workflow_source"),
-        "workflow_hash": load.get("workflow_hash"),
-        "task_mode": load.get("task_mode"),
-        "final_report_schema_path": load.get("final_report_schema_path"),
-        "final_report_schema_hash": load.get("final_report_schema_hash"),
-        "prompt_conflicts_with_workflow": load.get(
-            "prompt_conflicts_with_workflow"),
-        "session_pid": load.get("session_pid"),
-        "boundary_status": load.get("boundary_status"),
-        "boundary_clean": load.get("boundary_clean"),
-        "workflow_load_helper_result": boundary.workflow_load_helper_result(
-            load, project_root),
-        "reasons": reasons,
-    }
-
-
-def _session_validation_reasons(
-    load: dict,
-    project_root: str | None,
-) -> list[str]:
-    reasons: list[str] = []
-    if load.get("session_pid") != os.getpid():
-        reasons.append(
-            "workflow load proof was recorded in a different process "
-            "(fail closed)"
-        )
-        return reasons
-    if load.get("prompt_conflicts_with_workflow"):
-        reasons.extend(load.get("prompt_conflict_reasons") or [
-            "active prompt conflicts with loaded review-merge workflow"
-        ])
-    if project_root:
-        try:
-            current = build_canonical_workflow_metadata(project_root)
-        except OSError as exc:
-            reasons.append(f"cannot re-verify workflow hash: {exc}")
-            return reasons
-        if current["workflow_hash"] != load.get("workflow_hash"):
-            reasons.append(
-                "stored workflow hash is stale; reload via "
-                f"{LOAD_TOOL_NAME} (fail closed)"
-            )
-        if current["final_report_schema_hash"] != load.get(
-                "final_report_schema_hash"):
-            reasons.append(
-                "stored final-report schema hash is stale; reload via "
-                f"{LOAD_TOOL_NAME} (fail closed)"
-            )
-    return reasons
-
-
-def review_workflow_load_blockers(
-    project_root: str | None = None,
-) -> list[str]:
-    """Reasons reviewer mutations must fail closed."""
-    boundary_reasons = boundary.boundary_blockers(project_root)
-    if boundary_reasons and _REVIEW_WORKFLOW_LOAD is None:
-        return boundary_reasons
-    status = workflow_load_status(project_root)
-    if not status.get("workflow_load_proof_present"):
-        return list(status.get("reasons") or []) + boundary_reasons
-    if not status.get("workflow_load_valid"):
-        return list(status.get("reasons") or [])
-    return []
-
-
-def recovery_handoff_without_replay() -> list[str]:
-    """Safe next-step lines that must not include approve/merge replay."""
-    return [
-        "Reload the canonical workflow via gitea_load_review_workflow, then "
-        "rerun the full review-merge workflow from inventory.",
-        "Do not call gitea_submit_pr_review, gitea_mark_final_review_decision, "
-        "or gitea_merge_pr until workflow-load proof is present.",
-        "Do not include approve/merge replay commands in the recovery handoff.",
-    ]

scripts/run-webui

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$script_dir/.." && pwd)"
+cd "$repo_root"
+exec python3 -m webui "$@"

skills/llm-project-workflow/schemas/review-merge-final-report.md

@@ -63,14 +63,8 @@ Do not use legacy fields: `Pinned reviewed head`, `Scratch worktree used`,
 - Current status:
 - Safe next action:
 - Safety statement:
-- Workflow-load helper result:
 ```
 
-The **Workflow-load helper result** field must carry structured output from
-`gitea_load_review_workflow` (workflow_hash, final_report_schema_hash,
-boundary_status). Narrative claims that workflow files were viewed locally are
-not sufficient (#403).
-
 ### Already-landed handoff overrides
 
 When eligibility class is `ALREADY_LANDED_RECONCILE_REQUIRED`:

skills/llm-project-workflow/workflows/review-merge-pr.md

@@ -36,44 +36,6 @@ If available, load it first and report:
 
 If the canonical workflow cannot be loaded and the project requires it, stop and produce a recovery handoff only.
 
-## 0A. Workflow-load and session boundary anchor (#403)
-
-The MCP gate is the authority — not local file viewing.
-
-Before any reviewer mutation:
-
-1. Record pre-review commands with `gitea_record_pre_review_command` when they
-   are not automatically classified (inventory/diagnostic commands may be
-   recorded explicitly for proof).
-2. Call `gitea_load_review_workflow` to establish workflow hash proof **and**
-   session boundary state in the same in-process session proof.
-3. Do not claim the workflow was loaded by reading
-   `skills/llm-project-workflow/workflows/review-merge-pr.md` as a local file;
-   that narrative does not satisfy the validator.
-
-Allowed before workflow load (classify as `read_only_inventory` or
-`diagnostic`):
-
-* `gitea_whoami`, `gitea_resolve_task_capability`, `gitea_list_prs`,
-  `gitea_view_pr`, `gitea_get_runtime_context`
-* `git fetch` / `git remote update` for inventory
-* `git status`, `git worktree list` (read-only)
-
-Boundary violations (block downstream reviewer mutations even after load):
-
-* validation commands (`pytest`, `python -m unittest`) in the main checkout
-* local profile/credential/config inspection (`profiles.json`, `gitea-mcp.json`,
-  `.env`, keychain dumps)
-* MCP repair (`pkill`, MCP config edits)
-* git mutations before workflow load
-
-Final reports must include a structured **Workflow-load helper result** block
-copied from `gitea_load_review_workflow`, including at minimum:
-
-* `workflow_hash`
-* `final_report_schema_hash`
-* `boundary_status` (`clean` or `violation`)
-
 ## 1. Start with live identity, profile, runtime, and capability checks
 
 Prove:

tests/test_create_issue_workspace_guard.py

@@ -0,0 +1,145 @@
+import os
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+# Ensure we import from the repo root
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import gitea_mcp_server as srv
+
+FAKE_AUTH = {"Authorization": "token test-token"}
+# Stable control checkout (parent of branches/), not the MCP server worktree root.
+CONTROL_CHECKOUT_ROOT = str(Path(__file__).resolve().parents[3])
+PROJECT_ROOT = srv.PROJECT_ROOT
+
+
+class TestCreateIssueWorkspaceGuard(unittest.TestCase):
+
+    def setUp(self):
+        # Reset preflight flags
+        srv._preflight_whoami_called = True
+        srv._preflight_capability_called = True
+        srv._preflight_resolved_role = "author"
+        srv._preflight_whoami_violation = False
+        srv._preflight_capability_violation = False
+        
+        # Disable early return in verify_preflight_purity for testing
+        self._orig_in_test = srv._preflight_in_test_mode
+        srv._preflight_in_test_mode = lambda: False
+
+    def tearDown(self):
+        srv._preflight_in_test_mode = self._orig_in_test
+
+    @patch("gitea_mcp_server._auth", return_value=FAKE_AUTH)
+    @patch("gitea_mcp_server._profile_permission_block", return_value=None)
+    @patch("gitea_mcp_server._namespace_mutation_block", return_value=None)
+    @patch("gitea_mcp_server.role_session_router.check_author_mutation_after_reviewer_stop", return_value=(True, []))
+    @patch("gitea_mcp_server.api_request")
+    @patch("gitea_mcp_server.api_get_all", return_value=[])
+    @patch("gitea_mcp_server.issue_lock_worktree.read_worktree_git_state", return_value={"current_branch": "feat/issue-1"})
+    def test_create_issue_stable_checkout_rejected(self, _git, _get_all, mock_api, _role, _ns, _prof, _auth):
+        # Without worktree_path/env hints, workspace resolves to PROJECT_ROOT. When that
+        # path is the stable control checkout (not under branches/), mutation must fail.
+        with patch.object(srv, "PROJECT_ROOT", CONTROL_CHECKOUT_ROOT):
+            with self.assertRaises(RuntimeError) as ctx:
+                srv.gitea_create_issue(title="Test issue", body="body text")
+        self.assertIn("stable control checkout", str(ctx.exception))
+
+    @patch("gitea_mcp_server._auth", return_value=FAKE_AUTH)
+    @patch("gitea_mcp_server._profile_permission_block", return_value=None)
+    @patch("gitea_mcp_server._namespace_mutation_block", return_value=None)
+    @patch("gitea_mcp_server.role_session_router.check_author_mutation_after_reviewer_stop", return_value=(True, []))
+    @patch("gitea_mcp_server.api_request")
+    @patch("gitea_mcp_server.api_get_all", return_value=[])
+    @patch("gitea_mcp_server.issue_lock_worktree.read_worktree_git_state", return_value={"current_branch": "feat/issue-1"})
+    @patch("os.path.exists", return_value=True)
+    @patch("os.path.isdir", return_value=True)
+    @patch("subprocess.run")
+    def test_create_issue_valid_worktree_succeeds(self, mock_run, mock_isdir, mock_exists, _git, _get_all, mock_api, _role, _ns, _prof, _auth):
+        # Mock subprocess.run for git --git-common-dir to return PROJECT_ROOT/.git
+        mock_res = MagicMock()
+        mock_res.stdout = f"{CONTROL_CHECKOUT_ROOT}/.git\n"
+        mock_run.return_value = mock_res
+
+        mock_api.return_value = {"number": 42, "html_url": "https://gitea.example.com/issues/42"}
+
+        # Provide a valid branches path under the control checkout root
+        valid_path = os.path.join(CONTROL_CHECKOUT_ROOT, "branches", "feat-issue-1")
+        
+        with patch.object(srv, "PROJECT_ROOT", CONTROL_CHECKOUT_ROOT):
+            with patch("gitea_mcp_server._get_workspace_porcelain", return_value=""):
+                res = srv.gitea_create_issue(
+                    title="Test issue", body="body", worktree_path=valid_path
+                )
+            
+        self.assertEqual(res["number"], 42)
+        mock_api.assert_called_once()
+
+    @patch("gitea_mcp_server._auth", return_value=FAKE_AUTH)
+    @patch("gitea_mcp_server._profile_permission_block", return_value=None)
+    @patch("gitea_mcp_server._namespace_mutation_block", return_value=None)
+    @patch("gitea_mcp_server.role_session_router.check_author_mutation_after_reviewer_stop", return_value=(True, []))
+    @patch("gitea_mcp_server.api_request")
+    @patch("gitea_mcp_server.api_get_all", return_value=[])
+    @patch("gitea_mcp_server.issue_lock_worktree.read_worktree_git_state", return_value={"current_branch": "feat/issue-1"})
+    def test_create_issue_missing_worktree_fails_closed(self, _git, _get_all, mock_api, _role, _ns, _prof, _auth):
+        # Path under branches/ but doesn't exist
+        missing_path = os.path.join(
+            CONTROL_CHECKOUT_ROOT, "branches", "nonexistent-worktree-path-999"
+        )
+        
+        with patch.object(srv, "PROJECT_ROOT", CONTROL_CHECKOUT_ROOT):
+            with self.assertRaises(RuntimeError) as ctx:
+                srv.gitea_create_issue(
+                    title="Test issue", body="body", worktree_path=missing_path
+                )
+        self.assertIn("does not exist (fail closed)", str(ctx.exception))
+
+    @patch("gitea_mcp_server._auth", return_value=FAKE_AUTH)
+    @patch("gitea_mcp_server._profile_permission_block", return_value=None)
+    @patch("gitea_mcp_server._namespace_mutation_block", return_value=None)
+    @patch("gitea_mcp_server.role_session_router.check_author_mutation_after_reviewer_stop", return_value=(True, []))
+    @patch("gitea_mcp_server.api_request")
+    @patch("gitea_mcp_server.api_get_all", return_value=[])
+    @patch("gitea_mcp_server.issue_lock_worktree.read_worktree_git_state", return_value={"current_branch": "feat/issue-1"})
+    @patch("os.path.exists", return_value=True)
+    @patch("os.path.isdir", return_value=True)
+    @patch("subprocess.run")
+    def test_create_issue_wrong_repo_fails_closed(self, mock_run, mock_isdir, mock_exists, _git, _get_all, mock_api, _role, _ns, _prof, _auth):
+        # Mock subprocess.run for git --git-common-dir to return a different path
+        mock_res = MagicMock()
+        mock_res.stdout = "/Users/jasonwalker/Development/some-other-repo/.git\n"
+        mock_run.return_value = mock_res
+
+        wrong_repo_path = os.path.join(CONTROL_CHECKOUT_ROOT, "branches", "feat-issue-1")
+
+        with patch.object(srv, "PROJECT_ROOT", CONTROL_CHECKOUT_ROOT):
+            with self.assertRaises(RuntimeError) as ctx:
+                srv.gitea_create_issue(
+                    title="Test issue", body="body", worktree_path=wrong_repo_path
+                )
+        self.assertIn("does not belong to the target repository", str(ctx.exception))
+
+    @patch("gitea_mcp_server._auth", return_value=FAKE_AUTH)
+    @patch("gitea_mcp_server._profile_permission_block", return_value=None)
+    @patch("gitea_mcp_server._namespace_mutation_block", return_value=None)
+    def test_create_issue_fails_without_whoami_preflight(self, _ns, _prof, _auth):
+        srv._preflight_whoami_called = False
+        with self.assertRaises(RuntimeError) as ctx:
+            srv.gitea_create_issue(title="Test issue", body="body")
+        self.assertIn("Identity (gitea_whoami) has not been verified", str(ctx.exception))
+
+    @patch("gitea_mcp_server._auth", return_value=FAKE_AUTH)
+    @patch("gitea_mcp_server._profile_permission_block", return_value=None)
+    @patch("gitea_mcp_server._namespace_mutation_block", return_value=None)
+    def test_create_issue_fails_without_capability_preflight(self, _ns, _prof, _auth):
+        srv._preflight_capability_called = False
+        with self.assertRaises(RuntimeError) as ctx:
+            srv.gitea_create_issue(title="Test issue", body="body")
+        self.assertIn("Task capability (gitea_resolve_task_capability) has not been resolved", str(ctx.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_llm_agent_sha.py

@@ -22,7 +22,6 @@ from unittest.mock import patch
 
 sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
 
-import mcp_server  # noqa: E402
 from mcp_server import (  # noqa: E402
     gitea_check_pr_eligibility,
     gitea_merge_pr,
@@ -131,7 +130,6 @@ class TestShaCannotBypassSelfReview(unittest.TestCase):
         ]
         from mcp_server import init_review_decision_lock, gitea_mark_final_review_decision
         init_review_decision_lock("prgs", "review_pr")
-        mcp_server.gitea_load_review_workflow()
         gitea_mark_final_review_decision(9, "approve", remote="prgs")
         env = self._env(SHA_WOULD_BE_REVIEWER, "reviewer")
         with patch.dict(os.environ, env, clear=True):

tests/test_mcp_server.py

@@ -55,12 +55,6 @@ _NO_BLOCKER_FEEDBACK = {
 }
 
 
-def _init_reviewer_session(remote="prgs"):
-    """Seed review decision lock and required workflow-load proof (#389)."""
-    init_review_decision_lock(remote, "review_pr")
-    mcp_server.gitea_load_review_workflow()
-
-
 def _mark_request_changes_ready(pr_number=8, **kwargs):
     """Mark a request_changes decision ready with the #332 duplicate-
     suppression feedback fetch stubbed to 'no existing blocker'."""
@@ -518,9 +512,6 @@ class TestViewPR(unittest.TestCase):
 class TestMergePR(unittest.TestCase):
     """Gated merge workflow (#16). gitea_merge_pr is the only merge path."""
 
-    def setUp(self):
-        mcp_server.gitea_load_review_workflow()
-
     def _pr(self, author, state="open", sha="abc123", mergeable=True):
         return {
             "user": {"login": author},
@@ -993,7 +984,8 @@ class TestReviewPR(unittest.TestCase):
             {"login": "jcwalker3"}, # /api/v1/user (submit eligibility)
             {"user": {"login": "jcwalker3"}, "state": "open", "head": {"sha": "abc1234"}, "mergeable": True}, # /pulls/1
         ]
-        _init_reviewer_session("prgs")
+        from mcp_server import init_review_decision_lock
+        init_review_decision_lock("prgs", "review_pr")
         gitea_mark_final_review_decision(1, "approve", remote="prgs")
         result = gitea_review_pr(
             pr_number=1,
@@ -1661,7 +1653,7 @@ class TestReviewDecisionValidationGate(unittest.TestCase):
         }
 
     def setUp(self):
-        _init_reviewer_session("prgs")
+        init_review_decision_lock("prgs", "review_pr")
 
     def _env(self):
         return patch.dict(os.environ, {
@@ -1756,7 +1748,7 @@ class TestSubmitPrReview(unittest.TestCase):
     """Gated review-mutation tool (#15)."""
 
     def setUp(self):
-        _init_reviewer_session("prgs")
+        init_review_decision_lock("prgs", "review_pr")
         gitea_mark_final_review_decision(8, "approve", remote="prgs")
 
     def _pr(self, author, state="open", sha="abc123", mergeable=True):
@@ -2149,7 +2141,7 @@ class TestSubmitPrReview(unittest.TestCase):
                 os.remove(spoof_path)
 
     def test_mark_final_decision_rejects_remote_mismatch(self):
-        _init_reviewer_session("prgs")
+        init_review_decision_lock("prgs", "review_pr")
         r = gitea_mark_final_review_decision(8, "approve", remote="dadeschools")
         self.assertFalse(r["marked_ready"])
         self.assertTrue(any("does not match locked remote" in x for x in r["reasons"]))
@@ -2231,7 +2223,6 @@ if __name__ == "__main__":
 class TestTrackerHygieneCleanup(unittest.TestCase):
 
     def setUp(self):
-        mcp_server.gitea_load_review_workflow()
         self.mock_api = patch("mcp_server.api_request").start()
         self.mock_auth = patch("mcp_server.get_auth_header", return_value=FAKE_AUTH).start()
         patch("gitea_audit.audit_enabled", return_value=True).start()

tests/test_permission_reports.py

@@ -230,7 +230,6 @@ class TestEligibilityDenialReport(PermissionReportBase):
             return PR_PAYLOAD
         mock_api.side_effect = fake_api
         mcp_server.init_review_decision_lock("prgs", "review_pr")
-        mcp_server.gitea_load_review_workflow()
         mcp_server.gitea_mark_final_review_decision(42, "approve", remote="prgs")
         with patch.dict(os.environ, self._env("author-profile")):
             res = mcp_server.gitea_submit_pr_review(
@@ -273,7 +272,6 @@ class TestReviewCommentPathUsesCanonicalOp(PermissionReportBase):
             return PR_PAYLOAD
         mock_api.side_effect = fake_api
         mcp_server.init_review_decision_lock("prgs", "review_pr")
-        mcp_server.gitea_load_review_workflow()
         mcp_server.gitea_mark_final_review_decision(42, "comment", remote="prgs")
         with patch.dict(os.environ, self._env("author-profile")):
             res = mcp_server.gitea_submit_pr_review(

tests/test_review_workflow_boundary.py

@@ -1,138 +0,0 @@
-"""Tests for workflow-load session boundary tracking (#403)."""
-
-import os
-import sys
-import unittest
-from unittest.mock import patch
-
-sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
-
-import final_report_validator
-import review_workflow_boundary
-import review_workflow_load
-import mcp_server
-
-
-class TestPreReviewClassification(unittest.TestCase):
-    def setUp(self):
-        review_workflow_boundary.clear_pre_review_commands()
-        review_workflow_load.clear_review_workflow_load()
-
-    def test_inventory_command_allowed(self):
-        result = review_workflow_boundary.classify_pre_review_command(
-            "gitea_list_prs remote=prgs",
-            cwd="/tmp",
-            project_root="/repo/Gitea-Tools",
-        )
-        self.assertEqual(
-            result["classification"],
-            review_workflow_boundary.CLASSIFICATION_READ_ONLY_INVENTORY,
-        )
-
-    def test_main_checkout_pytest_is_boundary_violation(self):
-        root = "/repo/Gitea-Tools"
-        result = review_workflow_boundary.classify_pre_review_command(
-            "python -m pytest tests/",
-            cwd=root,
-            project_root=root,
-        )
-        self.assertEqual(
-            result["classification"],
-            review_workflow_boundary.CLASSIFICATION_BOUNDARY_VIOLATION,
-        )
-
-    def test_profiles_json_inspection_is_boundary_violation(self):
-        result = review_workflow_boundary.classify_pre_review_command(
-            "cat profiles.json",
-            cwd="/repo/Gitea-Tools",
-            project_root="/repo/Gitea-Tools",
-        )
-        self.assertEqual(
-            result["classification"],
-            review_workflow_boundary.CLASSIFICATION_BOUNDARY_VIOLATION,
-        )
-
-
-class TestWorkflowLoadBoundaryGate(unittest.TestCase):
-    def setUp(self):
-        review_workflow_boundary.clear_pre_review_commands()
-        review_workflow_load.clear_review_workflow_load()
-        mcp_server.init_review_decision_lock("prgs", "review_pr")
-        mcp_server.record_preflight_check("whoami")
-        mcp_server.record_preflight_check("capability", "reviewer")
-
-    def _root(self) -> str:
-        return str(__import__("pathlib").Path(__file__).resolve().parent.parent)
-
-    def test_boundary_violation_blocks_mutation_after_load(self):
-        root = self._root()
-        review_workflow_boundary.record_pre_review_command(
-            "python -m pytest tests/",
-            cwd=root,
-            project_root=root,
-        )
-        res = mcp_server.gitea_load_review_workflow()
-        self.assertFalse(res["success"])
-        self.assertEqual(res["boundary_status"], "violation")
-        blocked = mcp_server.gitea_mark_final_review_decision(
-            42, "approve", remote="prgs")
-        self.assertFalse(blocked["marked_ready"])
-        joined = " ".join(blocked["reasons"]).lower()
-        self.assertTrue(
-            "validation" in joined or "boundary" in joined or "workflow" in joined
-        )
-
-    def test_clean_inventory_then_load_passes(self):
-        root = self._root()
-        review_workflow_boundary.record_pre_review_command(
-            "gitea_list_prs remote=prgs",
-            cwd=root,
-            project_root=root,
-        )
-        res = mcp_server.gitea_load_review_workflow()
-        self.assertTrue(res["success"])
-        self.assertEqual(res["boundary_status"], "clean")
-        blockers = review_workflow_load.review_workflow_load_blockers(root)
-        self.assertEqual(blockers, [])
-
-    def test_file_view_narrative_fails_validator_without_helper(self):
-        report = (
-            "## Controller Handoff\n"
-            "- Task: review-merge-pr\n"
-            "- I read the canonical workflow review-merge-pr.md before review.\n"
-        )
-        findings = final_report_validator.assess_final_report_validator(
-            report,
-            task_kind="review_pr",
-        )
-        self.assertTrue(any(
-            f["rule_id"] == "reviewer.workflow_load_boundary"
-            for f in findings.get("findings") or []
-        ))
-
-    def test_helper_result_passes_validator(self):
-        root = self._root()
-        review_workflow_load.record_review_workflow_load(root)
-        helper = review_workflow_boundary.workflow_load_helper_result(
-            review_workflow_load._REVIEW_WORKFLOW_LOAD,
-            root,
-        )
-        report = (
-            "## Controller Handoff\n"
-            "- Task: review-merge-pr\n"
-            f"- Workflow-load helper result: workflow_hash: {helper['workflow_hash']}; "
-            f"boundary_status: {helper['boundary_status']}\n"
-        )
-        findings = final_report_validator.assess_final_report_validator(
-            report,
-            task_kind="review_pr",
-        )
-        boundary_findings = [
-            f for f in (findings.get("findings") or [])
-            if f.get("rule_id") == "reviewer.workflow_load_boundary"
-        ]
-        self.assertEqual(boundary_findings, [])
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_review_workflow_load.py

@@ -1,151 +0,0 @@
-"""Tests for canonical review workflow load proof (#389)."""
-
-import os
-import sys
-import unittest
-from unittest.mock import patch
-
-sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
-
-import review_workflow_load
-import mcp_server
-
-
-class TestReviewWorkflowLoadModule(unittest.TestCase):
-    def setUp(self):
-        review_workflow_load.clear_review_workflow_load()
-        mcp_server._save_review_decision_lock(None)
-
-    def test_load_records_hash_and_schema(self):
-        root = str(__import__("pathlib").Path(__file__).resolve().parent.parent)
-        recorded = review_workflow_load.record_review_workflow_load(root)
-        self.assertEqual(
-            recorded["workflow_source"],
-            review_workflow_load.WORKFLOW_REL_PATH,
-        )
-        self.assertEqual(recorded["task_mode"], "review-merge-pr")
-        self.assertRegex(recorded["workflow_hash"], r"^[0-9a-f]{12}$")
-        self.assertEqual(
-            recorded["final_report_schema_path"],
-            review_workflow_load.SCHEMA_REL_PATH,
-        )
-        status = review_workflow_load.workflow_load_status(root)
-        self.assertTrue(status["workflow_load_proof_present"])
-        self.assertTrue(status["workflow_load_valid"])
-
-    def test_stale_session_pid_blocks(self):
-        root = str(__import__("pathlib").Path(__file__).resolve().parent.parent)
-        review_workflow_load.record_review_workflow_load(root)
-        review_workflow_load._REVIEW_WORKFLOW_LOAD["session_pid"] = 0
-        blockers = review_workflow_load.review_workflow_load_blockers(root)
-        self.assertTrue(any("different process" in b for b in blockers))
-
-    def test_prompt_conflict_detected(self):
-        conflict, reasons = review_workflow_load.assess_prompt_conflict(
-            "Run work-issue author implementation only")
-        self.assertTrue(conflict)
-        self.assertTrue(reasons)
-
-
-class TestReviewWorkflowLoadGates(unittest.TestCase):
-    def setUp(self):
-        review_workflow_load.clear_review_workflow_load()
-        mcp_server.init_review_decision_lock("prgs", "review_pr")
-        mcp_server.record_preflight_check("whoami")
-        mcp_server.record_preflight_check("capability", "reviewer")
-
-    def _load_workflow(self):
-        return mcp_server.gitea_load_review_workflow()
-
-    def test_mcp_helper_returns_required_fields(self):
-        res = self._load_workflow()
-        self.assertTrue(res["success"])
-        self.assertTrue(res["loaded"])
-        self.assertIn("workflow_source", res)
-        self.assertIn("workflow_hash", res)
-        self.assertIn("final_report_schema_path", res)
-        self.assertIn("final_report_schema_hash", res)
-
-    def test_mark_final_blocked_without_load(self):
-        res = mcp_server.gitea_mark_final_review_decision(
-            42, "approve", remote="prgs")
-        self.assertFalse(res["marked_ready"])
-        self.assertTrue(any(
-            "gitea_load_review_workflow" in r for r in res["reasons"]))
-        self.assertTrue(any(
-            "approve/merge replay" in r.lower() or "Do not call" in r
-            for r in res["reasons"]))
-
-    def test_submit_review_blocked_without_load(self):
-        with patch("mcp_server.gitea_check_pr_eligibility") as elig:
-            elig.return_value = {
-                "eligible": True,
-                "authenticated_user": "rev",
-                "profile_name": "prgs-reviewer",
-                "pr_author": "author",
-                "head_sha": "abc123",
-                "reasons": [],
-            }
-            res = mcp_server.gitea_submit_pr_review(
-                42,
-                "approve",
-                remote="prgs",
-                final_review_decision_ready=True,
-            )
-        self.assertFalse(res["performed"])
-        self.assertTrue(any(
-            "gitea_load_review_workflow" in r for r in res["reasons"]))
-
-    def test_merge_blocked_without_load(self):
-        res = mcp_server.gitea_merge_pr(
-            42,
-            confirmation="MERGE PR 42",
-            remote="prgs",
-        )
-        self.assertFalse(res["performed"])
-        self.assertTrue(any(
-            "gitea_load_review_workflow" in r for r in res["reasons"]))
-
-    def test_resolve_capability_reports_missing_load(self):
-        with patch.object(mcp_server, "_ensure_matching_profile"):
-            with patch.object(
-                    mcp_server.gitea_config, "is_runtime_switching_enabled",
-                    return_value=False):
-                with patch.object(
-                        mcp_server, "_authenticated_username",
-                        return_value="rev"):
-                    res = mcp_server.gitea_resolve_task_capability(
-                        "review_pr", remote="prgs")
-        proof = res.get("workflow_load_proof") or {}
-        self.assertFalse(proof.get("workflow_load_valid"))
-        self.assertTrue(any(
-            "gitea_load_review_workflow" in g
-            for g in res.get("task_role_guidance") or []))
-
-    def test_init_review_lock_clears_prior_load(self):
-        self._load_workflow()
-        mcp_server.init_review_decision_lock("prgs", "review_pr")
-        blockers = review_workflow_load.review_workflow_load_blockers(
-            str(__import__("pathlib").Path(__file__).resolve().parent.parent))
-        self.assertTrue(blockers)
-
-    def test_dry_run_allowed_without_load(self):
-        with patch("mcp_server.gitea_check_pr_eligibility") as elig:
-            elig.return_value = {
-                "eligible": True,
-                "authenticated_user": "rev",
-                "profile_name": "prgs-reviewer",
-                "pr_author": "author",
-                "head_sha": "abc123",
-                "reasons": [],
-            }
-            res = mcp_server.gitea_dry_run_pr_review(
-                42, "approve", remote="prgs")
-        self.assertNotIn(
-            "gitea_load_review_workflow",
-            " ".join(res.get("reasons") or []),
-        )
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_webui_project_registry.py

@@ -0,0 +1,111 @@
+"""Tests for web UI project registry (#427)."""
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from starlette.testclient import TestClient
+
+from webui.app import create_app
+from webui.project_registry import (
+    default_registry_path,
+    load_registry,
+    project_to_dict,
+)
+
+
+class TestProjectRegistryLoader(unittest.TestCase):
+    def test_default_registry_loads_gitea_tools(self):
+        registry = load_registry()
+        self.assertEqual(registry.version, 1)
+        self.assertEqual(len(registry.projects), 1)
+        project = registry.projects[0]
+        self.assertEqual(project.id, "gitea-tools")
+        self.assertEqual(project.repo_name, "Gitea-Tools")
+        self.assertEqual(project.gitea_owner, "Scaled-Tech-Consulting")
+        self.assertEqual(project.remote_host, "https://gitea.prgs.cc")
+        self.assertEqual(project.profiles["author"], "prgs-author")
+        self.assertEqual(project.profiles["reviewer"], "prgs-reviewer")
+        self.assertEqual(project.profiles["reconciler"], "prgs-reconciler")
+        self.assertIn("skill", project.workflow_paths)
+        self.assertGreaterEqual(len(project.onboarding_checklist), 4)
+
+    def test_registry_rejects_credential_keys(self):
+        payload = {
+            "version": 1,
+            "projects": [
+                {
+                    "id": "bad",
+                    "repo_name": "Bad",
+                    "gitea_owner": "Org",
+                    "remote_host": "https://gitea.example.invalid",
+                    "default_branch": "main",
+                    "local_checkout_path": ".",
+                    "profiles": {
+                        "author": "a",
+                        "reviewer": "r",
+                        "reconciler": "c",
+                    },
+                    "workflow_paths": {"skill": "skills/x.md"},
+                    "api_token": "secret",
+                }
+            ],
+        }
+        with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as handle:
+            json.dump(payload, handle)
+            path = Path(handle.name)
+        try:
+            with self.assertRaises(ValueError):
+                load_registry(path)
+        finally:
+            path.unlink(missing_ok=True)
+
+    def test_default_registry_path_points_at_packaged_data(self):
+        path = default_registry_path()
+        self.assertTrue(path.name == "projects.registry.json")
+        self.assertTrue(path.parent.name == "data")
+
+
+class TestProjectRegistryRoutes(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+
+    def test_projects_page_lists_gitea_tools(self):
+        response = self.client.get("/projects")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Gitea-Tools", response.text)
+        self.assertIn("Scaled-Tech-Consulting", response.text)
+        self.assertIn("prgs-author", response.text)
+        self.assertNotIn("child issue", response.text.lower())
+
+    def test_project_detail_renders_checklist(self):
+        response = self.client.get("/projects/gitea-tools")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Onboarding checklist", response.text)
+        self.assertIn("Configure execution profiles", response.text)
+        self.assertIn("branches/", response.text)
+
+    def test_project_detail_404(self):
+        response = self.client.get("/projects/unknown-repo")
+        self.assertEqual(response.status_code, 404)
+
+    def test_api_projects_json(self):
+        response = self.client.get("/api/projects")
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertEqual(data["version"], 1)
+        self.assertEqual(len(data["projects"]), 1)
+        self.assertEqual(data["projects"][0]["id"], "gitea-tools")
+        self.assertIn("onboarding_checklist", data["projects"][0])
+
+    def test_project_to_dict_is_json_safe(self):
+        registry = load_registry()
+        encoded = json.dumps(project_to_dict(registry.projects[0]))
+        self.assertIn("gitea-tools", encoded)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_webui_prompt_library.py

@@ -0,0 +1,90 @@
+"""Tests for web UI prompt library (#428)."""
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from starlette.testclient import TestClient
+
+from webui.app import create_app
+from webui.prompt_library import find_prompt, library_to_dict, load_prompt_library, prompt_to_dict
+
+REQUIRED_PROMPT_SLUGS = frozenset({
+    "review-pr",
+    "work-issue",
+    "create-issue",
+    "comment-issue",
+    "cleanup",
+    "audit",
+    "onboarding",
+})
+
+
+class TestPromptLibraryLoader(unittest.TestCase):
+    def test_library_loads_required_prompts(self):
+        entries = load_prompt_library()
+        slugs = {entry.slug for entry in entries}
+        self.assertEqual(slugs, REQUIRED_PROMPT_SLUGS)
+
+    def test_workflow_hashes_present(self):
+        review = find_prompt("review-pr")
+        self.assertIsNotNone(review)
+        assert review is not None
+        self.assertTrue(review.workflow_hash)
+        self.assertEqual(len(review.workflow_hash), 64)
+
+    def test_prompt_text_is_short(self):
+        for entry in load_prompt_library():
+            self.assertLess(len(entry.prompt_text), 400)
+            self.assertNotIn("Do not improvise around the gates", entry.prompt_text)
+
+
+class TestPromptLibraryRoutes(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+
+    def test_prompts_page_lists_all_entries(self):
+        response = self.client.get("/prompts")
+        self.assertEqual(response.status_code, 200)
+        for label in (
+            "Review PR",
+            "Work issue",
+            "Create issue",
+            "Comment on issue",
+            "Post-merge cleanup",
+            "Reconciliation audit",
+            "Project onboarding",
+        ):
+            self.assertIn(label, response.text)
+        self.assertIn("Copy prompt", response.text)
+        self.assertIn("sha256:", response.text)
+        self.assertNotIn("child issue", response.text.lower())
+
+    def test_prompt_detail_route(self):
+        response = self.client.get("/prompts/work-issue")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("work-issue.md", response.text)
+        self.assertIn("Copy prompt", response.text)
+
+    def test_prompt_detail_404(self):
+        self.assertEqual(self.client.get("/prompts/missing").status_code, 404)
+
+    def test_api_prompts_json(self):
+        response = self.client.get("/api/prompts")
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertEqual(data["count"], 7)
+        review = next(item for item in data["prompts"] if item["slug"] == "review-pr")
+        self.assertIn("workflow_hash", review)
+        self.assertIn("review-merge-pr.md", review["workflow_path"])
+
+    def test_prompt_to_dict_roundtrip(self):
+        entry = load_prompt_library()[0]
+        encoded = json.dumps(prompt_to_dict(entry))
+        self.assertIn("workflow_path", encoded)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_webui_queue_dashboard.py

@@ -0,0 +1,245 @@
+"""Tests for web UI live queue dashboard (#429)."""
+import sys
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from starlette.testclient import TestClient
+
+from webui.app import create_app
+from webui.queue_loader import (
+    PaginationMeta,
+    _classify_issue,
+    _classify_pr,
+    _extract_linked_issue,
+    load_queue_snapshot,
+    snapshot_to_dict,
+)
+
+_RECENT = datetime.now(timezone.utc).isoformat()
+_STALE = (datetime.now(timezone.utc) - timedelta(days=30)).isoformat()
+
+_SAMPLE_PRS = [
+    {
+        "number": 100,
+        "title": "feat: queue dashboard (Closes #429)",
+        "body": "",
+        "mergeable": True,
+        "updated_at": _RECENT,
+        "head": {"ref": "feat/issue-429", "sha": "abc123def456"},
+        "base": {"ref": "master"},
+    },
+    {
+        "number": 99,
+        "title": "fix: conflict",
+        "body": "Closes #50",
+        "mergeable": False,
+        "updated_at": _STALE,
+        "head": {"ref": "fix/issue-50", "sha": "deadbeef0001"},
+        "base": {"ref": "master"},
+    },
+    {
+        "number": 98,
+        "title": "feat: duplicate A (Closes #60)",
+        "body": "",
+        "mergeable": True,
+        "updated_at": _RECENT,
+        "head": {"ref": "feat/issue-60-a", "sha": "111111111111"},
+        "base": {"ref": "master"},
+    },
+    {
+        "number": 97,
+        "title": "feat: duplicate B (Closes #60)",
+        "body": "",
+        "mergeable": True,
+        "updated_at": _RECENT,
+        "head": {"ref": "feat/issue-60-b", "sha": "222222222222"},
+        "base": {"ref": "master"},
+    },
+]
+
+_SAMPLE_ISSUES = [
+    {
+        "number": 429,
+        "title": "Web UI queue dashboard",
+        "state": "open",
+        "labels": [{"name": "status:in-progress"}],
+        "assignee": None,
+        "updated_at": _RECENT,
+    },
+    {
+        "number": 60,
+        "title": "Duplicate PR target",
+        "state": "open",
+        "labels": [],
+        "assignee": None,
+        "updated_at": _RECENT,
+    },
+    {
+        "number": 50,
+        "title": "Blocked PR target",
+        "state": "open",
+        "labels": [],
+        "assignee": None,
+        "updated_at": _STALE,
+    },
+]
+
+
+def _mock_pagination(count: int) -> PaginationMeta:
+    return PaginationMeta(
+        page=1,
+        per_page=50,
+        returned_count=count,
+        has_more=False,
+        is_final_page=True,
+        inventory_complete=True,
+        pages_fetched=1,
+    )
+
+
+def _mock_fetch_prs(*_args, **_kwargs):
+    return list(_SAMPLE_PRS), _mock_pagination(len(_SAMPLE_PRS))
+
+
+def _mock_fetch_issues(*_args, **_kwargs):
+    return list(_SAMPLE_ISSUES), _mock_pagination(len(_SAMPLE_ISSUES))
+
+
+class TestQueueClassification(unittest.TestCase):
+    def test_extract_linked_issue_from_title(self):
+        self.assertEqual(
+            _extract_linked_issue("feat: X (Closes #429)", ""),
+            429,
+        )
+
+    def test_classify_pr_blocked_and_stale(self):
+        pr = _SAMPLE_PRS[1]
+        badges = _classify_pr(
+            pr,
+            issue_claimed=set(),
+            issue_to_prs={50: [99]},
+        )
+        self.assertIn("blocked", badges)
+        self.assertIn("stale", badges)
+
+    def test_classify_pr_duplicate(self):
+        badges = _classify_pr(
+            _SAMPLE_PRS[2],
+            issue_claimed=set(),
+            issue_to_prs={60: [98, 97]},
+        )
+        self.assertIn("duplicate", badges)
+        self.assertIn("in-review", badges)
+
+    def test_classify_issue_claimed_and_duplicate(self):
+        claimed = _classify_issue(_SAMPLE_ISSUES[0], linked_prs=[])
+        self.assertIn("claimed", claimed)
+        duplicate = _classify_issue(_SAMPLE_ISSUES[1], linked_prs=[98, 97])
+        self.assertIn("duplicate", duplicate)
+
+
+class TestQueueLoader(unittest.TestCase):
+    def test_snapshot_with_mock_fetch(self):
+        snapshot = load_queue_snapshot(
+            fetch_prs=_mock_fetch_prs,
+            fetch_issues=_mock_fetch_issues,
+        )
+        self.assertEqual(snapshot.project_id, "gitea-tools")
+        self.assertIsNone(snapshot.fetch_error)
+        self.assertEqual(len(snapshot.prs), 4)
+        self.assertEqual(len(snapshot.issues), 3)
+        self.assertTrue(snapshot.pr_pagination.inventory_complete)
+        self.assertTrue(snapshot.issue_pagination.inventory_complete)
+
+        pr100 = next(p for p in snapshot.prs if p.number == 100)
+        self.assertEqual(pr100.extra["linked_issue"], "429")
+        self.assertIn("claimed", pr100.badges)
+
+    def test_snapshot_dict_export(self):
+        snapshot = load_queue_snapshot(
+            fetch_prs=_mock_fetch_prs,
+            fetch_issues=_mock_fetch_issues,
+        )
+        data = snapshot_to_dict(snapshot)
+        self.assertEqual(data["project_id"], "gitea-tools")
+        self.assertIsNone(data["fetch_error"])
+        self.assertEqual(len(data["prs"]), 4)
+        self.assertTrue(data["pagination"]["prs"]["inventory_complete"])
+
+
+class TestQueueRoutes(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+        self._patch = mock.patch(
+            "webui.app.load_queue_snapshot",
+            return_value=load_queue_snapshot(
+                fetch_prs=_mock_fetch_prs,
+                fetch_issues=_mock_fetch_issues,
+            ),
+        )
+        self._patch.start()
+
+    def tearDown(self):
+        self._patch.stop()
+
+    def test_queue_page_renders_tables_and_pagination(self):
+        response = self.client.get("/queue")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Live queue", response.text)
+        self.assertIn("Open pull requests", response.text)
+        self.assertIn("Open issues", response.text)
+        self.assertIn("pages_fetched", response.text)
+        self.assertIn("Gitea-Tools", response.text)
+        self.assertNotIn("child issue", response.text.lower())
+
+    def test_api_queue_json(self):
+        response = self.client.get("/api/queue")
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertEqual(data["repo"], "Scaled-Tech-Consulting/Gitea-Tools")
+        self.assertEqual(data["pagination"]["issues"]["returned_count"], 3)
+
+    def test_queue_fail_closed_without_credentials(self):
+        with mock.patch("webui.queue_loader.get_auth_header", return_value=None):
+            snapshot = load_queue_snapshot()
+        self.assertIsNotNone(snapshot.fetch_error)
+        self.assertEqual(len(snapshot.prs), 0)
+
+    def test_queue_fail_closed_hides_empty_state_copy(self):
+        with mock.patch("webui.queue_loader.get_auth_header", return_value=None):
+            snapshot = load_queue_snapshot()
+        with mock.patch("webui.app.load_queue_snapshot", return_value=snapshot):
+            response = self.client.get("/queue")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Queue unavailable", response.text)
+        self.assertIn("not fetched", response.text.lower())
+        self.assertNotIn("No open items.", response.text)
+        self.assertNotIn("Open pull requests", response.text)
+        self.assertNotIn("pages_fetched", response.text)
+
+    def test_queue_successful_empty_inventory_shows_empty_state(self):
+        def _empty_prs(*_args, **_kwargs):
+            return [], _mock_pagination(0)
+
+        def _empty_issues(*_args, **_kwargs):
+            return [], _mock_pagination(0)
+
+        snapshot = load_queue_snapshot(
+            fetch_prs=_empty_prs,
+            fetch_issues=_empty_issues,
+        )
+        with mock.patch("webui.app.load_queue_snapshot", return_value=snapshot):
+            response = self.client.get("/queue")
+        self.assertEqual(response.status_code, 200)
+        self.assertIsNone(snapshot.fetch_error)
+        self.assertEqual(response.text.count("No open items."), 2)
+        self.assertIn("pages_fetched", response.text)
+        self.assertIn("pagination (complete)", response.text)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_webui_skeleton.py

@@ -0,0 +1,73 @@
+"""Tests for internal web UI skeleton (#426)."""
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from starlette.testclient import TestClient
+
+from webui.app import create_app
+
+
+class TestWebuiSkeleton(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+
+    def test_health_returns_json(self):
+        response = self.client.get("/health")
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertEqual(data["status"], "ok")
+        self.assertEqual(data["service"], "mcp-control-plane-webui")
+        self.assertEqual(data["mode"], "read-only-mvp")
+        self.assertIn("timestamp", data)
+
+    def test_home_renders(self):
+        response = self.client.get("/")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Operator console", response.text)
+        self.assertIn("Read-only MVP", response.text)
+
+    def test_route_stubs_render(self):
+        for path in ("/runtime", "/audit"):
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 200)
+                self.assertIn("child issue", response.text.lower())
+
+    def test_prompts_is_implemented(self):
+        response = self.client.get("/prompts")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Prompt library", response.text)
+
+    def test_projects_is_implemented(self):
+        response = self.client.get("/projects")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Gitea-Tools", response.text)
+
+    def test_extra_stub_routes(self):
+        for path in ("/worktrees", "/leases"):
+            with self.subTest(path=path):
+                self.assertEqual(self.client.get(path).status_code, 200)
+
+    def test_post_is_rejected(self):
+        response = self.client.post("/health")
+        self.assertEqual(response.status_code, 405)
+        self.assertEqual(response.json()["error"], "read-only-mvp")
+
+    def test_queue_route_renders(self):
+        response = self.client.get("/queue")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Live queue", response.text)
+
+    def test_nav_links_on_all_pages(self):
+        for path in ("/", "/queue", "/projects", "/prompts", "/runtime", "/audit"):
+            with self.subTest(path=path):
+                text = self.client.get(path).text
+                for href in ("/queue", "/projects", "/prompts", "/runtime", "/audit"):
+                    self.assertIn(f'href="{href}"', text)
+
+
+if __name__ == "__main__":
+    unittest.main()

webui/__init__.py

@@ -0,0 +1,5 @@
+"""Internal MCP Control Plane web UI (read-only MVP skeleton, #426)."""
+
+from webui.app import create_app
+
+__all__ = ["create_app"]

webui/__main__.py

@@ -0,0 +1,19 @@
+"""Run the internal web UI: ``python -m webui``."""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+from webui.app import create_app
+
+
+def main() -> None:
+    host = os.environ.get("WEBUI_HOST", "127.0.0.1")
+    port = int(os.environ.get("WEBUI_PORT", "8765"))
+    uvicorn.run(create_app(), host=host, port=port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

webui/app.py

@@ -0,0 +1,180 @@
+"""Starlette application for the internal read-only web UI (#426)."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, JSONResponse, Response
+from starlette.routing import Route
+
+from webui.layout import render_page
+from webui.project_registry import find_project, load_registry, registry_to_dict
+from webui.project_views import render_project_detail, render_projects_list
+from webui.prompt_library import find_prompt, library_to_dict
+from webui.prompt_views import render_prompt_detail, render_prompts_page
+from webui.queue_loader import load_queue_snapshot, snapshot_to_dict
+from webui.queue_views import render_queue_page
+
+_READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+def _stub_page(title: str, description: str) -> HTMLResponse:
+    body = (
+        f"<h2>{title}</h2>"
+        f'<div class="stub"><p>{description}</p>'
+        "<p>Implementation tracked in a child issue of #425.</p></div>"
+    )
+    return HTMLResponse(render_page(title=title, body_html=body))
+
+
+async def home(_request: Request) -> HTMLResponse:
+    body = (
+        "<h2>Operator console</h2>"
+        "<p>Local entry point for MCP Control Plane operational views.</p>"
+        "<ul>"
+        "<li><strong>Queue</strong> — live PR and issue dashboard (#429)</li>"
+        "<li><strong>Projects</strong> — registry and onboarding (#427)</li>"
+        "<li><strong>Prompts</strong> — canonical workflow prompt library (#428)</li>"
+        "<li><strong>Runtime</strong> — MCP health and stale-runtime detection (#430)</li>"
+        "<li><strong>Audit</strong> — final-report paste and validator preview (#431)</li>"
+        "<li><strong>Worktrees</strong> — branch hygiene dashboard (#432)</li>"
+        "<li><strong>Leases</strong> — collision and lease visibility (#433)</li>"
+        "</ul>"
+    )
+    return HTMLResponse(render_page(title="Home", body_html=body))
+
+
+async def health(_request: Request) -> JSONResponse:
+    return JSONResponse({
+        "status": "ok",
+        "service": "mcp-control-plane-webui",
+        "mode": "read-only-mvp",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    })
+
+
+async def queue(_request: Request) -> HTMLResponse:
+    snapshot = load_queue_snapshot()
+    return HTMLResponse(render_page(title="Queue", body_html=render_queue_page(snapshot)))
+
+
+async def api_queue(_request: Request) -> JSONResponse:
+    return JSONResponse(snapshot_to_dict(load_queue_snapshot()))
+
+
+async def projects(_request: Request) -> HTMLResponse:
+    registry = load_registry()
+    return HTMLResponse(render_projects_list(registry))
+
+
+async def project_detail(request: Request) -> HTMLResponse:
+    project_id = request.path_params["project_id"]
+    registry = load_registry()
+    project = find_project(registry, project_id)
+    if project is None:
+        return HTMLResponse(
+            render_page(
+                title="Project not found",
+                body_html=(
+                    "<h2>Project not found</h2>"
+                    f"<p>No registry entry for <code>{project_id}</code>.</p>"
+                    '<p><a href="/projects">← All projects</a></p>'
+                ),
+            ),
+            status_code=404,
+        )
+    return HTMLResponse(render_project_detail(project))
+
+
+async def api_projects(_request: Request) -> JSONResponse:
+    registry = load_registry()
+    return JSONResponse(registry_to_dict(registry))
+
+
+async def prompts(_request: Request) -> HTMLResponse:
+    return HTMLResponse(render_prompts_page())
+
+
+async def prompt_detail(request: Request) -> HTMLResponse:
+    prompt_id = request.path_params["prompt_id"]
+    prompt = find_prompt(prompt_id)
+    if prompt is None:
+        return HTMLResponse(
+            render_page(
+                title="Prompt not found",
+                body_html=(
+                    "<h2>Prompt not found</h2>"
+                    f"<p>No library entry for <code>{prompt_id}</code>.</p>"
+                    '<p><a href="/prompts">← All prompts</a></p>'
+                ),
+            ),
+            status_code=404,
+        )
+    return HTMLResponse(render_prompt_detail(prompt))
+
+
+async def api_prompts(_request: Request) -> JSONResponse:
+    return JSONResponse(library_to_dict())
+
+
+async def runtime(_request: Request) -> HTMLResponse:
+    return _stub_page(
+        "Runtime",
+        "Runtime health will report MCP profile, preflight, and stale-server signals.",
+    )
+
+
+async def audit(_request: Request) -> HTMLResponse:
+    return _stub_page(
+        "Audit",
+        "Report audit will accept pasted final reports and run validator previews.",
+    )
+
+
+async def worktrees(_request: Request) -> HTMLResponse:
+    return _stub_page(
+        "Worktrees",
+        "Worktree hygiene will summarize branches/ session folders and cleanup risk.",
+    )
+
+
+async def leases(_request: Request) -> HTMLResponse:
+    return _stub_page(
+        "Leases",
+        "Lease visibility will show active issue and reviewer PR leases.",
+    )
+
+
+async def method_not_allowed(request: Request, _exc: Exception) -> Response:
+    if request.method not in _READ_ONLY_METHODS:
+        return JSONResponse(
+            {"error": "read-only-mvp", "detail": f"{request.method} not permitted"},
+            status_code=405,
+        )
+    return JSONResponse({"error": "not_found"}, status_code=404)
+
+
+def create_app() -> Starlette:
+    """Build the read-only MVP Starlette app."""
+    return Starlette(
+        debug=False,
+        routes=[
+            Route("/", home, methods=["GET"]),
+            Route("/health", health, methods=["GET"]),
+            Route("/queue", queue, methods=["GET"]),
+            Route("/api/queue", api_queue, methods=["GET"]),
+            Route("/projects", projects, methods=["GET"]),
+            Route("/projects/{project_id}", project_detail, methods=["GET"]),
+            Route("/api/projects", api_projects, methods=["GET"]),
+            Route("/prompts", prompts, methods=["GET"]),
+            Route("/prompts/{prompt_id}", prompt_detail, methods=["GET"]),
+            Route("/api/prompts", api_prompts, methods=["GET"]),
+            Route("/runtime", runtime, methods=["GET"]),
+            Route("/audit", audit, methods=["GET"]),
+            Route("/worktrees", worktrees, methods=["GET"]),
+            Route("/leases", leases, methods=["GET"]),
+        ],
+        exception_handlers={405: method_not_allowed},
+    )

webui/data/projects.registry.json

@@ -0,0 +1,49 @@
+{
+  "version": 1,
+  "projects": [
+    {
+      "id": "gitea-tools",
+      "repo_name": "Gitea-Tools",
+      "gitea_owner": "Scaled-Tech-Consulting",
+      "remote_host": "https://gitea.prgs.cc",
+      "default_branch": "master",
+      "local_checkout_path": ".",
+      "profiles": {
+        "author": "prgs-author",
+        "reviewer": "prgs-reviewer",
+        "reconciler": "prgs-reconciler"
+      },
+      "workflow_paths": {
+        "skill": "skills/llm-project-workflow/SKILL.md",
+        "work_issue": "skills/llm-project-workflow/workflows/work-issue.md",
+        "review_merge": "skills/llm-project-workflow/workflows/review-merge-pr.md"
+      },
+      "schema_paths": {
+        "mcp_config_v2": "gitea-mcp.v2-contexts.example.json",
+        "mcp_config_v1": "gitea-mcp.example.json"
+      },
+      "onboarding_checklist": [
+        {
+          "id": "profiles",
+          "title": "Configure execution profiles",
+          "description": "Install author, reviewer, and reconciler MCP profiles (prgs-author, prgs-reviewer, prgs-reconciler) in separate namespaces. Tokens stay in keychain — never in this registry."
+        },
+        {
+          "id": "mcp_config",
+          "title": "Wire MCP v2 contexts",
+          "description": "Copy and customize gitea-mcp.v2-contexts.example.json for your machine. Map this repo path under projects with default_owner Scaled-Tech-Consulting and default_repo Gitea-Tools."
+        },
+        {
+          "id": "wiki_gate",
+          "title": "Wiki publication readiness",
+          "description": "For wiki-tracked work, satisfy the live Gitea Wiki proof gate (#224) before closing issues. See docs/wiki/Safety-and-Gates.md."
+        },
+        {
+          "id": "branches_layout",
+          "title": "Isolate work under branches/",
+          "description": "All LLM task edits happen in worktrees under branches/. Main checkout stays clean; use skills/llm-project-workflow templates for start-issue and review flows."
+        }
+      ]
+    }
+  ]
+}

webui/layout.py

@@ -0,0 +1,176 @@
+"""Shared HTML layout for the internal web UI."""
+
+from __future__ import annotations
+
+NAV_ITEMS = (
+    ("/", "Home"),
+    ("/queue", "Queue"),
+    ("/projects", "Projects"),
+    ("/prompts", "Prompts"),
+    ("/runtime", "Runtime"),
+    ("/audit", "Audit"),
+    ("/worktrees", "Worktrees"),
+    ("/leases", "Leases"),
+)
+
+MVP_NOTICE = (
+    "Read-only MVP — Gitea, MCP tools, and canonical workflows remain the "
+    "source of truth. No mutation endpoints."
+)
+
+
+def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
+    nav_links = "".join(
+        f'<a href="{href}">{label}</a>' for href, label in NAV_ITEMS
+    )
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{title} · MCP Control Plane</title>
+  <style>
+    :root {{
+      --bg: #0f1419;
+      --surface: #1a2332;
+      --text: #e7ecf3;
+      --muted: #8b9cb3;
+      --accent: #5b9fd4;
+      --border: #2a3648;
+    }}
+    * {{ box-sizing: border-box; }}
+    body {{
+      margin: 0;
+      font-family: system-ui, -apple-system, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.5;
+    }}
+    header {{
+      background: var(--surface);
+      border-bottom: 1px solid var(--border);
+      padding: 0.75rem 1.25rem;
+    }}
+    header h1 {{
+      margin: 0 0 0.5rem;
+      font-size: 1.1rem;
+      font-weight: 600;
+    }}
+    nav {{
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.75rem 1rem;
+    }}
+    nav a {{
+      color: var(--accent);
+      text-decoration: none;
+      font-size: 0.9rem;
+    }}
+    nav a:hover {{ text-decoration: underline; }}
+    main {{
+      max-width: 52rem;
+      margin: 0 auto;
+      padding: 1.5rem 1.25rem 2.5rem;
+    }}
+    .notice {{
+      color: var(--muted);
+      font-size: 0.85rem;
+      margin-bottom: 1.25rem;
+      padding: 0.65rem 0.85rem;
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      background: var(--surface);
+    }}
+    h2 {{ margin-top: 0; font-size: 1.35rem; }}
+    p {{ color: var(--muted); }}
+    .stub {{
+      border-left: 3px solid var(--accent);
+      padding-left: 0.85rem;
+      margin: 1rem 0;
+    }}
+    .meta {{ font-size: 0.85rem; }}
+    table.registry, table.detail {{
+      width: 100%;
+      border-collapse: collapse;
+      margin: 1rem 0;
+      font-size: 0.9rem;
+    }}
+    table.registry th, table.registry td,
+    table.detail th, table.detail td {{
+      text-align: left;
+      padding: 0.45rem 0.6rem;
+      border-bottom: 1px solid var(--border);
+    }}
+    table.registry th, table.detail th {{
+      color: var(--muted);
+      font-weight: 500;
+    }}
+    code {{
+      font-family: ui-monospace, monospace;
+      font-size: 0.85em;
+      color: var(--text);
+    }}
+    ol.checklist {{
+      padding-left: 1.25rem;
+      margin: 0.5rem 0 1.5rem;
+    }}
+    ol.checklist li {{ margin-bottom: 0.85rem; }}
+    ol.checklist p {{ margin: 0.25rem 0 0; font-size: 0.9rem; }}
+    .prompt-card {{
+      margin: 1.25rem 0 1.75rem;
+      padding: 1rem 1.1rem;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--surface);
+    }}
+    .prompt-card h3 {{ margin: 0 0 0.5rem; font-size: 1.05rem; }}
+    pre.prompt-text {{
+      white-space: pre-wrap;
+      word-break: break-word;
+      margin: 0.75rem 0;
+      padding: 0.75rem 0.85rem;
+      border-radius: 6px;
+      background: var(--bg);
+      border: 1px solid var(--border);
+      font-size: 0.9rem;
+      color: var(--text);
+    }}
+    .copy-btn {{
+      background: var(--accent);
+      color: #0b1219;
+      border: none;
+      border-radius: 6px;
+      padding: 0.4rem 0.85rem;
+      font-size: 0.85rem;
+      cursor: pointer;
+    }}
+    .copy-btn:hover {{ filter: brightness(1.08); }}
+    .muted {{ color: var(--muted); }}
+    .badges {{ display: inline-flex; flex-wrap: wrap; gap: 0.35rem; margin-left: 0.5rem; }}
+    .badge {{
+      font-size: 0.72rem;
+      padding: 0.1rem 0.45rem;
+      border-radius: 999px;
+      border: 1px solid var(--border);
+      color: var(--muted);
+      text-transform: lowercase;
+    }}
+    .badge-claimed {{ color: #8fd19e; border-color: #3d6b4a; }}
+    .badge-blocked {{ color: #f0a8a8; border-color: #7a3b3b; }}
+    .badge-in-review {{ color: #9ec8f0; border-color: #3d5f7a; }}
+    .badge-duplicate {{ color: #e0c27a; border-color: #6b5730; }}
+    .badge-stale {{ color: #c9b8e8; border-color: #5a4a78; }}
+  </style>
+  {extra_head}
+</head>
+<body>
+  <header>
+    <h1>MCP Control Plane</h1>
+    <nav>{nav_links}</nav>
+  </header>
+  <main>
+    <p class="notice">{MVP_NOTICE}</p>
+    {body_html}
+  </main>
+</body>
+</html>"""

webui/project_registry.py

@@ -0,0 +1,196 @@
+"""Load and validate the web UI project registry (#427)."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+_FORBIDDEN_EXACT_KEYS = frozenset({
+    "token",
+    "password",
+    "secret",
+    "credential",
+    "auth",
+    "api_key",
+    "api-key",
+})
+_FORBIDDEN_KEY_PREFIXES = ("auth_", "api_key_", "api-key_")
+_FORBIDDEN_KEY_SUFFIXES = ("_token", "_secret", "_password", "_credential", "_auth")
+
+
+def _is_forbidden_key(key: str) -> bool:
+    lowered = key.lower()
+    if lowered in _FORBIDDEN_EXACT_KEYS:
+        return True
+    return (
+        lowered.startswith(_FORBIDDEN_KEY_PREFIXES)
+        or lowered.endswith(_FORBIDDEN_KEY_SUFFIXES)
+    )
+
+_REQUIRED_PROJECT_FIELDS = (
+    "id",
+    "repo_name",
+    "gitea_owner",
+    "remote_host",
+    "default_branch",
+    "local_checkout_path",
+    "profiles",
+    "workflow_paths",
+)
+
+_REQUIRED_PROFILE_ROLES = ("author", "reviewer", "reconciler")
+
+
+@dataclass(frozen=True)
+class OnboardingStep:
+    id: str
+    title: str
+    description: str
+
+
+@dataclass(frozen=True)
+class ProjectRecord:
+    id: str
+    repo_name: str
+    gitea_owner: str
+    remote_host: str
+    default_branch: str
+    local_checkout_path: str
+    profiles: dict[str, str]
+    workflow_paths: dict[str, str]
+    schema_paths: dict[str, str]
+    onboarding_checklist: tuple[OnboardingStep, ...]
+
+
+@dataclass(frozen=True)
+class ProjectRegistry:
+    version: int
+    projects: tuple[ProjectRecord, ...]
+    source_path: Path
+
+
+def default_registry_path() -> Path:
+    override = os.environ.get("WEBUI_PROJECT_REGISTRY", "").strip()
+    if override:
+        return Path(override).expanduser().resolve()
+    return (Path(__file__).resolve().parent / "data" / "projects.registry.json").resolve()
+
+
+def _reject_credential_keys(obj: Any, *, path: str = "") -> None:
+    if isinstance(obj, dict):
+        for key, value in obj.items():
+            key_path = f"{path}.{key}" if path else key
+            if _is_forbidden_key(key):
+                raise ValueError(f"registry must not store credentials ({key_path})")
+            _reject_credential_keys(value, path=key_path)
+    elif isinstance(obj, list):
+        for index, item in enumerate(obj):
+            _reject_credential_keys(item, path=f"{path}[{index}]")
+
+
+def _parse_onboarding(raw: list[dict[str, Any]] | None) -> tuple[OnboardingStep, ...]:
+    if not raw:
+        return ()
+    steps: list[OnboardingStep] = []
+    for item in raw:
+        steps.append(
+            OnboardingStep(
+                id=str(item["id"]),
+                title=str(item["title"]),
+                description=str(item["description"]),
+            )
+        )
+    return tuple(steps)
+
+
+def _parse_project(raw: dict[str, Any]) -> ProjectRecord:
+    missing = [field for field in _REQUIRED_PROJECT_FIELDS if field not in raw]
+    if missing:
+        raise ValueError(f"project missing required fields: {', '.join(missing)}")
+
+    profiles = raw["profiles"]
+    if not isinstance(profiles, dict):
+        raise ValueError("profiles must be an object")
+    for role in _REQUIRED_PROFILE_ROLES:
+        if role not in profiles or not profiles[role]:
+            raise ValueError(f"profiles.{role} is required")
+
+    workflow_paths = raw["workflow_paths"]
+    if not isinstance(workflow_paths, dict) or not workflow_paths:
+        raise ValueError("workflow_paths must be a non-empty object")
+
+    schema_paths = raw.get("schema_paths") or {}
+    if not isinstance(schema_paths, dict):
+        raise ValueError("schema_paths must be an object when present")
+
+    return ProjectRecord(
+        id=str(raw["id"]),
+        repo_name=str(raw["repo_name"]),
+        gitea_owner=str(raw["gitea_owner"]),
+        remote_host=str(raw["remote_host"]),
+        default_branch=str(raw["default_branch"]),
+        local_checkout_path=str(raw["local_checkout_path"]),
+        profiles={role: str(profiles[role]) for role in _REQUIRED_PROFILE_ROLES},
+        workflow_paths={key: str(value) for key, value in workflow_paths.items()},
+        schema_paths={key: str(value) for key, value in schema_paths.items()},
+        onboarding_checklist=_parse_onboarding(raw.get("onboarding_checklist")),
+    )
+
+
+def load_registry(path: Path | None = None) -> ProjectRegistry:
+    """Load the versioned project registry from disk."""
+    source = (path or default_registry_path()).resolve()
+    raw_text = source.read_text(encoding="utf-8")
+    payload = json.loads(raw_text)
+    if not isinstance(payload, dict):
+        raise ValueError("registry root must be an object")
+
+    version = payload.get("version")
+    if version != 1:
+        raise ValueError(f"unsupported registry version: {version!r}")
+
+    _reject_credential_keys(payload)
+
+    projects_raw = payload.get("projects")
+    if not isinstance(projects_raw, list) or not projects_raw:
+        raise ValueError("projects must be a non-empty array")
+
+    projects = tuple(_parse_project(item) for item in projects_raw)
+    return ProjectRegistry(version=version, projects=projects, source_path=source)
+
+
+def project_to_dict(project: ProjectRecord) -> dict[str, Any]:
+    """Serialize a project for JSON API responses."""
+    return {
+        "id": project.id,
+        "repo_name": project.repo_name,
+        "gitea_owner": project.gitea_owner,
+        "remote_host": project.remote_host,
+        "default_branch": project.default_branch,
+        "local_checkout_path": project.local_checkout_path,
+        "profiles": dict(project.profiles),
+        "workflow_paths": dict(project.workflow_paths),
+        "schema_paths": dict(project.schema_paths),
+        "onboarding_checklist": [
+            {"id": step.id, "title": step.title, "description": step.description}
+            for step in project.onboarding_checklist
+        ],
+    }
+
+
+def registry_to_dict(registry: ProjectRegistry) -> dict[str, Any]:
+    return {
+        "version": registry.version,
+        "source_path": str(registry.source_path),
+        "projects": [project_to_dict(project) for project in registry.projects],
+    }
+
+
+def find_project(registry: ProjectRegistry, project_id: str) -> ProjectRecord | None:
+    for project in registry.projects:
+        if project.id == project_id:
+            return project
+    return None

webui/project_views.py

@@ -0,0 +1,93 @@
+"""HTML views for project registry pages (#427)."""
+
+from __future__ import annotations
+
+import html
+
+from webui.layout import render_page
+from webui.project_registry import ProjectRecord, ProjectRegistry
+
+
+def _escape(text: str) -> str:
+    return html.escape(text, quote=True)
+
+
+def render_projects_list(registry: ProjectRegistry) -> str:
+    rows = []
+    for project in registry.projects:
+        rows.append(
+            "<tr>"
+            f"<td><a href=\"/projects/{_escape(project.id)}\">{_escape(project.repo_name)}</a></td>"
+            f"<td>{_escape(project.gitea_owner)}</td>"
+            f"<td>{_escape(project.remote_host)}</td>"
+            f"<td>{_escape(project.default_branch)}</td>"
+            f"<td><code>{_escape(project.profiles['author'])}</code></td>"
+            "</tr>"
+        )
+    table = (
+        "<table class=\"registry\">"
+        "<thead><tr>"
+        "<th>Repository</th><th>Owner</th><th>Remote</th>"
+        "<th>Branch</th><th>Author profile</th>"
+        "</tr></thead>"
+        f"<tbody>{''.join(rows)}</tbody></table>"
+    )
+    body = (
+        "<h2>Projects</h2>"
+        "<p>Configured repositories managed by the MCP Control Plane.</p>"
+        f"<p class=\"meta\">Registry: <code>{_escape(str(registry.source_path))}</code> "
+        f"(version {registry.version})</p>"
+        f"{table}"
+        "<p><a href=\"/api/projects\">JSON API</a></p>"
+    )
+    return render_page(title="Projects", body_html=body)
+
+
+def render_project_detail(project: ProjectRecord) -> str:
+    profile_rows = "".join(
+        f"<tr><th>{_escape(role)}</th><td><code>{_escape(name)}</code></td></tr>"
+        for role, name in project.profiles.items()
+    )
+    workflow_rows = "".join(
+        f"<tr><th>{_escape(key)}</th><td><code>{_escape(path)}</code></td></tr>"
+        for key, path in project.workflow_paths.items()
+    )
+    schema_rows = "".join(
+        f"<tr><th>{_escape(key)}</th><td><code>{_escape(path)}</code></td></tr>"
+        for key, path in project.schema_paths.items()
+    )
+    checklist_items = []
+    for index, step in enumerate(project.onboarding_checklist, start=1):
+        checklist_items.append(
+            "<li>"
+            f"<strong>{index}. {_escape(step.title)}</strong>"
+            f"<p>{_escape(step.description)}</p>"
+            "</li>"
+        )
+    checklist_html = (
+        "<ol class=\"checklist\">" + "".join(checklist_items) + "</ol>"
+        if checklist_items
+        else "<p>No onboarding steps defined.</p>"
+    )
+    body = (
+        f"<h2>{_escape(project.repo_name)}</h2>"
+        "<p><a href=\"/projects\">← All projects</a></p>"
+        "<h3>Identity</h3>"
+        "<table class=\"detail\">"
+        f"<tr><th>Registry id</th><td><code>{_escape(project.id)}</code></td></tr>"
+        f"<tr><th>Gitea owner</th><td>{_escape(project.gitea_owner)}</td></tr>"
+        f"<tr><th>Remote host</th><td>{_escape(project.remote_host)}</td></tr>"
+        f"<tr><th>Default branch</th><td><code>{_escape(project.default_branch)}</code></td></tr>"
+        f"<tr><th>Local checkout</th><td><code>{_escape(project.local_checkout_path)}</code></td></tr>"
+        "</table>"
+        "<h3>Profiles</h3>"
+        f"<table class=\"detail\">{profile_rows}</table>"
+        "<h3>Workflow paths</h3>"
+        f"<table class=\"detail\">{workflow_rows}</table>"
+        "<h3>Schema paths</h3>"
+        f"<table class=\"detail\">{schema_rows}</table>"
+        "<h3>Onboarding checklist</h3>"
+        "<p class=\"meta\">Read-only MVP — complete these steps outside the UI.</p>"
+        f"{checklist_html}"
+    )
+    return render_page(title=project.repo_name, body_html=body)

webui/prompt_library.py

@@ -0,0 +1,197 @@
+"""Canonical workflow prompt library for the internal web UI (#428)."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+_WORKFLOW_ROOT = Path("skills/llm-project-workflow/workflows")
+
+_DEFAULT_PROMPT_RE = re.compile(
+    r"\*\*Default task prompt:\*\*\s*\n+>\s*(.+?)(?=\n\n|\nDo not improvise)",
+    re.DOTALL,
+)
+_FRONTMATTER_TASK_MODE_RE = re.compile(r"^task_mode:\s*(\S+)", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class PromptEntry:
+    slug: str
+    label: str
+    prompt_text: str
+    workflow_path: str
+    task_mode: str | None
+    workflow_hash: str | None
+    source_note: str
+
+
+def _repo_root() -> Path:
+    override = (os.environ.get("WEBUI_REPO_ROOT") or "").strip()
+    if override:
+        return Path(override).resolve()
+    return Path(__file__).resolve().parent.parent
+
+
+def _workflow_file(path: str) -> Path:
+    return _repo_root() / path
+
+
+def _sha256_hex(content: str) -> str:
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def _read_workflow(path: str) -> tuple[str, str]:
+    file_path = _workflow_file(path)
+    text = file_path.read_text(encoding="utf-8")
+    return text, _sha256_hex(text)
+
+
+def _extract_default_prompt(markdown: str) -> str | None:
+    match = _DEFAULT_PROMPT_RE.search(markdown)
+    if not match:
+        return None
+    lines = [line.strip() for line in match.group(1).splitlines()]
+    return " ".join(line for line in lines if line)
+
+
+def _extract_task_mode(markdown: str) -> str | None:
+    match = _FRONTMATTER_TASK_MODE_RE.search(markdown)
+    return match.group(1) if match else None
+
+
+def _entry_from_workflow(
+    *,
+    slug: str,
+    label: str,
+    workflow_path: str,
+    prompt_override: str | None = None,
+    source_note: str = "",
+) -> PromptEntry:
+    markdown, digest = _read_workflow(workflow_path)
+    prompt_text = prompt_override or _extract_default_prompt(markdown)
+    if not prompt_text:
+        raise ValueError(f"No default task prompt found in {workflow_path}")
+    return PromptEntry(
+        slug=slug,
+        label=label,
+        prompt_text=prompt_text,
+        workflow_path=workflow_path,
+        task_mode=_extract_task_mode(markdown),
+        workflow_hash=digest,
+        source_note=source_note,
+    )
+
+
+def _static_entry(
+    *,
+    slug: str,
+    label: str,
+    prompt_text: str,
+    workflow_path: str,
+    source_note: str,
+) -> PromptEntry:
+    path = _workflow_file(workflow_path)
+    digest = _sha256_hex(path.read_text(encoding="utf-8")) if path.is_file() else None
+    markdown = path.read_text(encoding="utf-8") if path.is_file() else ""
+    return PromptEntry(
+        slug=slug,
+        label=label,
+        prompt_text=prompt_text,
+        workflow_path=workflow_path,
+        task_mode=_extract_task_mode(markdown) if markdown else None,
+        workflow_hash=digest,
+        source_note=source_note,
+    )
+
+
+def load_prompt_library() -> tuple[PromptEntry, ...]:
+    """Load operator prompts derived from canonical workflows."""
+    entries = (
+        _entry_from_workflow(
+            slug="review-pr",
+            label="Review PR",
+            workflow_path=str(_WORKFLOW_ROOT / "review-merge-pr.md"),
+        ),
+        _entry_from_workflow(
+            slug="work-issue",
+            label="Work issue",
+            workflow_path=str(_WORKFLOW_ROOT / "work-issue.md"),
+        ),
+        _entry_from_workflow(
+            slug="create-issue",
+            label="Create issue",
+            workflow_path=str(_WORKFLOW_ROOT / "create-issue.md"),
+        ),
+        _static_entry(
+            slug="comment-issue",
+            label="Comment on issue",
+            workflow_path=str(_WORKFLOW_ROOT / "create-issue.md"),
+            prompt_text=(
+                "Comment on the target Gitea issue only if exact comment_issue "
+                "capability is proven. Load the canonical create-issue workflow "
+                "first and follow §16 (comment-on-existing issue rule). Include "
+                "specific evidence; do not duplicate existing comments."
+            ),
+            source_note="Derived from create-issue.md §16; full policy remains in the workflow file.",
+        ),
+        _static_entry(
+            slug="cleanup",
+            label="Post-merge cleanup",
+            workflow_path="skills/llm-project-workflow/templates/worktree-cleanup.md",
+            prompt_text=(
+                "Task: clean up branch/worktree for PR #<pr> / issue #<n> after merge. "
+                "Confirm the merge on remote master before any deletion; never "
+                "force-remove a dirty worktree."
+            ),
+            source_note="Full cleanup steps live in templates/worktree-cleanup.md.",
+        ),
+        _entry_from_workflow(
+            slug="audit",
+            label="Reconciliation audit",
+            workflow_path=str(_WORKFLOW_ROOT / "reconcile-landed-pr.md"),
+        ),
+        _static_entry(
+            slug="onboarding",
+            label="Project onboarding",
+            workflow_path="skills/llm-project-workflow/SKILL.md",
+            prompt_text=(
+                "Onboard this repository into the MCP Control Plane: prove identity "
+                "and task capability, configure author/reviewer/reconciler profiles "
+                "in separate namespaces, then complete the checklist at /projects. "
+                "Canonical router: skills/llm-project-workflow/SKILL.md."
+            ),
+            source_note="Checklist details live in webui/data/projects.registry.json and /projects.",
+        ),
+    )
+    return entries
+
+
+def find_prompt(slug: str) -> PromptEntry | None:
+    for entry in load_prompt_library():
+        if entry.slug == slug:
+            return entry
+    return None
+
+
+def prompt_to_dict(entry: PromptEntry) -> dict[str, Any]:
+    return {
+        "slug": entry.slug,
+        "label": entry.label,
+        "prompt_text": entry.prompt_text,
+        "workflow_path": entry.workflow_path,
+        "task_mode": entry.task_mode,
+        "workflow_hash": entry.workflow_hash,
+        "source_note": entry.source_note,
+    }
+
+
+def library_to_dict() -> dict[str, Any]:
+    entries = load_prompt_library()
+    return {
+        "count": len(entries),
+        "prompts": [prompt_to_dict(entry) for entry in entries],
+    }

webui/prompt_views.py

@@ -0,0 +1,87 @@
+"""HTML views for the prompt library (#428)."""
+
+from __future__ import annotations
+
+import html
+
+from webui.layout import render_page
+from webui.prompt_library import PromptEntry, load_prompt_library
+
+
+def _escape(text: str) -> str:
+    return html.escape(text, quote=True)
+
+
+def _render_prompt_card(entry: PromptEntry) -> str:
+    hash_short = (
+        f"<code>{_escape(entry.workflow_hash[:12])}</code>"
+        if entry.workflow_hash
+        else "<span class=\"muted\">n/a</span>"
+    )
+    task_mode = (
+        f"<code>{_escape(entry.task_mode)}</code>"
+        if entry.task_mode
+        else "<span class=\"muted\">n/a</span>"
+    )
+    note = (
+        f'<p class="meta">{_escape(entry.source_note)}</p>'
+        if entry.source_note
+        else ""
+    )
+    prompt_id = f"prompt-{entry.slug}"
+    return (
+        f'<section class="prompt-card" id="{_escape(entry.slug)}">'
+        f"<h3>{_escape(entry.label)}</h3>"
+        f'<p class="meta">Workflow: <code>{_escape(entry.workflow_path)}</code> · '
+        f"task_mode: {task_mode} · sha256: {hash_short}</p>"
+        f'<pre class="prompt-text" id="{prompt_id}">{_escape(entry.prompt_text)}</pre>'
+        f'<button type="button" class="copy-btn" data-copy-target="{prompt_id}">'
+        "Copy prompt</button>"
+        f"{note}"
+        "</section>"
+    )
+
+
+PROMPT_PAGE_SCRIPT = """
+<script>
+document.querySelectorAll('.copy-btn').forEach((btn) => {
+  btn.addEventListener('click', async () => {
+    const targetId = btn.getAttribute('data-copy-target');
+    const node = document.getElementById(targetId);
+    if (!node) return;
+    const text = node.textContent || '';
+    try {
+      await navigator.clipboard.writeText(text);
+      const prior = btn.textContent;
+      btn.textContent = 'Copied';
+      setTimeout(() => { btn.textContent = prior; }, 1200);
+    } catch (_err) {
+      btn.textContent = 'Copy failed';
+    }
+  });
+});
+</script>
+"""
+
+
+def render_prompts_page() -> str:
+    entries = load_prompt_library()
+    cards = "".join(_render_prompt_card(entry) for entry in entries)
+    body = (
+        "<h2>Prompt library</h2>"
+        "<p>Short copy/paste task prompts derived from canonical workflows. "
+        "Full policy remains in the cited workflow files — not duplicated here.</p>"
+        f"{cards}"
+        "<p><a href=\"/api/prompts\">JSON API</a></p>"
+        f"{PROMPT_PAGE_SCRIPT}"
+    )
+    return render_page(title="Prompts", body_html=body)
+
+
+def render_prompt_detail(entry: PromptEntry) -> str:
+    body = (
+        f"<p><a href=\"/prompts\">← All prompts</a></p>"
+        f"{_render_prompt_card(entry)}"
+        f"{PROMPT_PAGE_SCRIPT}"
+    )
+    return render_page(title=entry.label, body_html=body)

webui/queue_loader.py

@@ -0,0 +1,385 @@
+"""Load live Gitea PR/issue queue state for the web UI dashboard (#429)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+from gitea_auth import api_fetch_page, get_auth_header, repo_api_url
+
+from webui.project_registry import ProjectRecord, load_registry
+
+_CLOSES_RE = re.compile(r"(?:closes|fixes|resolves)\s+#(\d+)", re.I)
+_ISSUE_REF_RE = re.compile(r"#(\d+)")
+_STALE_DAYS = 14
+
+
+@dataclass(frozen=True)
+class PaginationMeta:
+    page: int
+    per_page: int
+    returned_count: int
+    has_more: bool
+    is_final_page: bool
+    inventory_complete: bool
+    pages_fetched: int
+
+
+@dataclass(frozen=True)
+class QueueItem:
+    number: int
+    title: str
+    badges: tuple[str, ...]
+    extra: dict[str, str]
+
+
+@dataclass(frozen=True)
+class QueueSnapshot:
+    project_id: str
+    repo_label: str
+    prs: tuple[QueueItem, ...]
+    issues: tuple[QueueItem, ...]
+    pr_pagination: PaginationMeta | None
+    issue_pagination: PaginationMeta | None
+    fetch_error: str | None = None
+
+
+def _host_from_url(remote_host: str) -> str:
+    parsed = urlparse(remote_host.strip())
+    return parsed.netloc or remote_host.strip().rstrip("/")
+
+
+def _extract_linked_issue(title: str | None, body: str | None = None) -> int | None:
+    for text in (title, body):
+        if not text:
+            continue
+        match = _CLOSES_RE.search(text)
+        if match:
+            return int(match.group(1))
+    if body:
+        refs = _ISSUE_REF_RE.findall(body)
+        if refs:
+            return int(refs[0])
+    return None
+
+
+def _is_stale(updated_at: str | None) -> bool:
+    if not updated_at:
+        return False
+    try:
+        normalized = updated_at.replace("Z", "+00:00")
+        parsed = datetime.fromisoformat(normalized)
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        age = datetime.now(timezone.utc) - parsed.astimezone(timezone.utc)
+        return age.days >= _STALE_DAYS
+    except ValueError:
+        return False
+
+
+def _classify_pr(
+    pr: dict,
+    *,
+    issue_claimed: set[int],
+    issue_to_prs: dict[int, list[int]],
+) -> tuple[str, ...]:
+    badges: list[str] = []
+    mergeable = pr.get("mergeable")
+    if mergeable is False:
+        badges.append("blocked")
+    linked = _extract_linked_issue(pr.get("title"), pr.get("body"))
+    if linked is not None:
+        if linked in issue_claimed:
+            badges.append("claimed")
+        if len(issue_to_prs.get(linked, [])) > 1:
+            badges.append("duplicate")
+    if _is_stale(pr.get("updated_at")):
+        badges.append("stale")
+    if mergeable is True and "blocked" not in badges:
+        badges.append("in-review")
+    if not badges:
+        badges.append("open")
+    return tuple(dict.fromkeys(badges))
+
+
+def _classify_issue(
+    issue: dict,
+    *,
+    linked_prs: list[int],
+) -> tuple[str, ...]:
+    badges: list[str] = []
+    labels = [lb.get("name", "") for lb in issue.get("labels", [])]
+    if "status:in-progress" in labels:
+        badges.append("claimed")
+    if len(linked_prs) > 1:
+        badges.append("duplicate")
+    elif linked_prs and "claimed" not in badges:
+        badges.append("in-review")
+    if _is_stale(issue.get("updated_at")):
+        badges.append("stale")
+    if not badges:
+        badges.append("open")
+    return tuple(dict.fromkeys(badges))
+
+
+def _format_pr_item(pr: dict, badges: tuple[str, ...]) -> QueueItem:
+    head = pr.get("head") or {}
+    base = pr.get("base") or {}
+    mergeable = pr.get("mergeable")
+    merge_label = (
+        "mergeable" if mergeable is True else "conflicted" if mergeable is False else "unknown"
+    )
+    linked = _extract_linked_issue(pr.get("title"), pr.get("body"))
+    return QueueItem(
+        number=int(pr["number"]),
+        title=str(pr.get("title") or ""),
+        badges=badges,
+        extra={
+            "branch": f"{head.get('ref', '?')} → {base.get('ref', '?')}",
+            "head_sha": str(head.get("sha") or "")[:12],
+            "mergeable": merge_label,
+            "linked_issue": str(linked) if linked is not None else "",
+        },
+    )
+
+
+def _format_issue_item(issue: dict, badges: tuple[str, ...]) -> QueueItem:
+    labels = ", ".join(lb.get("name", "") for lb in issue.get("labels", []))
+    assignee = (issue.get("assignee") or {}).get("login", "")
+    return QueueItem(
+        number=int(issue["number"]),
+        title=str(issue.get("title") or ""),
+        badges=badges,
+        extra={
+            "labels": labels or "—",
+            "assignee": assignee or "unassigned",
+            "state": str(issue.get("state") or ""),
+        },
+    )
+
+
+def _pagination_from_pages(
+    *,
+    per_page: int,
+    pages_fetched: int,
+    returned_count: int,
+    is_final_page: bool,
+) -> PaginationMeta:
+    return PaginationMeta(
+        page=1,
+        per_page=per_page,
+        returned_count=returned_count,
+        has_more=not is_final_page,
+        is_final_page=is_final_page,
+        inventory_complete=is_final_page,
+        pages_fetched=pages_fetched,
+    )
+
+
+def _fetch_prs(
+    host: str,
+    org: str,
+    repo: str,
+    auth: str,
+    *,
+    per_page: int = 50,
+) -> tuple[list[dict], PaginationMeta]:
+    url = f"{repo_api_url(host, org, repo)}/pulls?state=open"
+    all_raw: list[dict] = []
+    pages_fetched = 0
+    is_final = False
+    page = 1
+    while pages_fetched < 20:
+        raw_page, meta = api_fetch_page(url, auth, page=page, limit=per_page)
+        pages_fetched += 1
+        all_raw.extend(raw_page)
+        is_final = bool(meta["is_final_page"])
+        if is_final:
+            break
+        page += 1
+    pagination = _pagination_from_pages(
+        per_page=per_page,
+        pages_fetched=pages_fetched,
+        returned_count=len(all_raw),
+        is_final_page=is_final,
+    )
+    return all_raw, pagination
+
+
+def _fetch_issues(
+    host: str,
+    org: str,
+    repo: str,
+    auth: str,
+    *,
+    per_page: int = 50,
+) -> tuple[list[dict], PaginationMeta]:
+    url = f"{repo_api_url(host, org, repo)}/issues?state=open&type=issues"
+    all_raw: list[dict] = []
+    page = 1
+    pages_fetched = 0
+    is_final = False
+    while pages_fetched < 20:
+        raw_page, meta = api_fetch_page(url, auth, page=page, limit=per_page)
+        pages_fetched += 1
+        all_raw.extend(raw_page)
+        is_final = bool(meta["is_final_page"])
+        if is_final:
+            break
+        page += 1
+    pagination = _pagination_from_pages(
+        per_page=per_page,
+        pages_fetched=pages_fetched,
+        returned_count=len(all_raw),
+        is_final_page=is_final,
+    )
+    return all_raw, pagination
+
+
+def load_queue_snapshot(
+    project_id: str | None = None,
+    *,
+    fetch_prs: Callable[..., tuple[list[dict], PaginationMeta]] | None = None,
+    fetch_issues: Callable[..., tuple[list[dict], PaginationMeta]] | None = None,
+) -> QueueSnapshot:
+    """Load open PR and issue queues for a registry project (default: first entry)."""
+    registry = load_registry()
+    project: ProjectRecord | None = None
+    if project_id:
+        for entry in registry.projects:
+            if entry.id == project_id:
+                project = entry
+                break
+    else:
+        project = registry.projects[0] if registry.projects else None
+
+    if project is None:
+        return QueueSnapshot(
+            project_id=project_id or "",
+            repo_label="",
+            prs=(),
+            issues=(),
+            pr_pagination=None,
+            issue_pagination=None,
+            fetch_error="project not found in registry",
+        )
+
+    host = _host_from_url(project.remote_host)
+    pr_fetch = fetch_prs or _fetch_prs
+    issue_fetch = fetch_issues or _fetch_issues
+    using_live_fetch = fetch_prs is None or fetch_issues is None
+    auth = get_auth_header(host) if using_live_fetch else "test-auth"
+    if using_live_fetch and not auth:
+        return QueueSnapshot(
+            project_id=project.id,
+            repo_label=f"{project.gitea_owner}/{project.repo_name}",
+            prs=(),
+            issues=(),
+            pr_pagination=None,
+            issue_pagination=None,
+            fetch_error=(
+                f"Gitea credentials unavailable for {host}; "
+                "queue cannot be loaded (fail closed — not showing empty queue)"
+            ),
+        )
+
+    try:
+        raw_prs, pr_pagination = pr_fetch(
+            host, project.gitea_owner, project.repo_name, auth
+        )
+        raw_issues, issue_pagination = issue_fetch(
+            host, project.gitea_owner, project.repo_name, auth
+        )
+    except Exception as exc:  # noqa: BLE001 — surface operator-visible fetch errors
+        return QueueSnapshot(
+            project_id=project.id,
+            repo_label=f"{project.gitea_owner}/{project.repo_name}",
+            prs=(),
+            issues=(),
+            pr_pagination=None,
+            issue_pagination=None,
+            fetch_error=f"Gitea fetch failed: {exc}",
+        )
+
+    issue_to_prs: dict[int, list[int]] = {}
+    for pr in raw_prs:
+        linked = _extract_linked_issue(pr.get("title"), pr.get("body"))
+        if linked is not None:
+            issue_to_prs.setdefault(linked, []).append(int(pr["number"]))
+
+    issue_claimed = {
+        int(i["number"])
+        for i in raw_issues
+        if any(lb.get("name") == "status:in-progress" for lb in i.get("labels", []))
+    }
+
+    pr_items = tuple(
+        _format_pr_item(
+            pr,
+            _classify_pr(
+                pr,
+                issue_claimed=issue_claimed,
+                issue_to_prs=issue_to_prs,
+            ),
+        )
+        for pr in sorted(raw_prs, key=lambda p: int(p["number"]), reverse=True)
+    )
+    issue_items = tuple(
+        _format_issue_item(
+            issue,
+            _classify_issue(
+                issue,
+                linked_prs=issue_to_prs.get(int(issue["number"]), []),
+            ),
+        )
+        for issue in sorted(raw_issues, key=lambda i: int(i["number"]), reverse=True)
+    )
+
+    return QueueSnapshot(
+        project_id=project.id,
+        repo_label=f"{project.gitea_owner}/{project.repo_name}",
+        prs=pr_items,
+        issues=issue_items,
+        pr_pagination=pr_pagination,
+        issue_pagination=issue_pagination,
+    )
+
+
+def snapshot_to_dict(snapshot: QueueSnapshot) -> dict[str, Any]:
+    """JSON-serializable export for /api/queue."""
+
+    def _page(meta: PaginationMeta | None) -> dict[str, Any] | None:
+        if meta is None:
+            return None
+        return {
+            "page": meta.page,
+            "per_page": meta.per_page,
+            "returned_count": meta.returned_count,
+            "has_more": meta.has_more,
+            "is_final_page": meta.is_final_page,
+            "inventory_complete": meta.inventory_complete,
+            "pages_fetched": meta.pages_fetched,
+        }
+
+    def _item(item: QueueItem) -> dict[str, Any]:
+        return {
+            "number": item.number,
+            "title": item.title,
+            "badges": list(item.badges),
+            **item.extra,
+        }
+
+    return {
+        "project_id": snapshot.project_id,
+        "repo": snapshot.repo_label,
+        "fetch_error": snapshot.fetch_error,
+        "prs": [_item(p) for p in snapshot.prs],
+        "issues": [_item(i) for i in snapshot.issues],
+        "pagination": {
+            "prs": _page(snapshot.pr_pagination),
+            "issues": _page(snapshot.issue_pagination),
+        },
+    }

webui/queue_views.py

@@ -0,0 +1,121 @@
+"""HTML views for the live Gitea queue dashboard (#429)."""
+
+from __future__ import annotations
+
+import html
+
+from webui.queue_loader import PaginationMeta, QueueItem, QueueSnapshot
+
+
+def _badge_html(badges: tuple[str, ...]) -> str:
+    if not badges:
+        return ""
+    chips = "".join(
+        f'<span class="badge badge-{html.escape(b)}">{html.escape(b)}</span>'
+        for b in badges
+    )
+    return f'<span class="badges">{chips}</span>'
+
+
+def _pagination_html(label: str, meta: PaginationMeta | None) -> str:
+    if meta is None:
+        return (
+            f"<p class='muted'><strong>{html.escape(label)} pagination:</strong> "
+            "unavailable</p>"
+        )
+    status = "complete" if meta.inventory_complete else "partial"
+    more = "yes" if meta.has_more else "no"
+    return (
+        f"<p class='meta'><strong>{html.escape(label)} pagination ({status}):</strong> "
+        f"returned {meta.returned_count} · per_page {meta.per_page} · "
+        f"pages_fetched {meta.pages_fetched} · has_more {more} · "
+        f"final_page {'yes' if meta.is_final_page else 'no'}</p>"
+    )
+
+
+def _queue_table(
+    *,
+    title: str,
+    items: tuple[QueueItem, ...],
+    columns: tuple[tuple[str, str], ...],
+) -> str:
+    if not items:
+        return f"<h3>{html.escape(title)}</h3><p class='muted'>No open items.</p>"
+
+    headers = "".join(f"<th>{html.escape(label)}</th>" for _, label in columns)
+    rows = []
+    for item in items:
+        cells = []
+        for key, _ in columns:
+            if key == "number":
+                cells.append(f"<td>#{item.number}</td>")
+            elif key == "title":
+                cells.append(
+                    f"<td>{html.escape(item.title)}{_badge_html(item.badges)}</td>"
+                )
+            else:
+                cells.append(f"<td>{html.escape(item.extra.get(key, ''))}</td>")
+        rows.append("<tr>" + "".join(cells) + "</tr>")
+
+    body = (
+        f"<h3>{html.escape(title)}</h3>"
+        f"<table class='registry'><thead><tr>{headers}</tr></thead>"
+        f"<tbody>{''.join(rows)}</tbody></table>"
+    )
+    return body
+
+
+def render_queue_page(snapshot: QueueSnapshot) -> str:
+    error_block = ""
+    if snapshot.fetch_error:
+        error_block = (
+            f'<div class="stub"><p><strong>Queue unavailable:</strong> '
+            f"{html.escape(snapshot.fetch_error)}</p></div>"
+        )
+        inventory_block = (
+            "<p class='muted'><strong>Inventory:</strong> not fetched "
+            "(fail closed — queue tables omitted).</p>"
+        )
+        return (
+            "<h2>Live queue</h2>"
+            f"<p class='meta'>Repository: <code>{html.escape(snapshot.repo_label)}</code> "
+            f"· project <code>{html.escape(snapshot.project_id)}</code></p>"
+            f"{error_block}"
+            f"{inventory_block}"
+            "<p class='muted'>Read-only MVP — claims, reviews, and merges stay in Gitea/MCP tools.</p>"
+        )
+
+    pr_section = _queue_table(
+        title="Open pull requests",
+        items=snapshot.prs,
+        columns=(
+            ("number", "#"),
+            ("title", "Title"),
+            ("branch", "Branch"),
+            ("head_sha", "Head"),
+            ("mergeable", "Mergeable"),
+            ("linked_issue", "Linked issue"),
+        ),
+    )
+    issue_section = _queue_table(
+        title="Open issues",
+        items=snapshot.issues,
+        columns=(
+            ("number", "#"),
+            ("title", "Title"),
+            ("labels", "Labels"),
+            ("assignee", "Assignee"),
+            ("state", "State"),
+        ),
+    )
+
+    return (
+        "<h2>Live queue</h2>"
+        f"<p class='meta'>Repository: <code>{html.escape(snapshot.repo_label)}</code> "
+        f"· project <code>{html.escape(snapshot.project_id)}</code></p>"
+        f"{_pagination_html('PR', snapshot.pr_pagination)}"
+        f"{pr_section}"
+        f"{_pagination_html('Issue', snapshot.issue_pagination)}"
+        f"{issue_section}"
+        "<p class='muted'>Read-only MVP — claims, reviews, and merges stay in Gitea/MCP tools.</p>"
+    )