From a6a2243aad9c3e385fc70509f4941a0f0ec33162 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Thu, 16 Jul 2026 06:40:18 -0400 Subject: [PATCH] docs: remediate stable control runtime ADR review findings (#615) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review 443 on PR #616: mandatory operator-guide/runbook cross-links, LLM vs operator restart/relaunch split, and sanctioned post-merge parity staleness response (stop, report, operator reload, re-verify). Add docs tests enforcing F1–F3. Refs: #615 --- .../mcp-stable-control-runtime-policy-adr.md | 72 +++++++-- docs/llm-workflow-runbooks.md | 21 ++- docs/wiki/Operator-Guide.md | 4 +- docs/wiki/Runbooks.md | 11 ++ ...test_stable_control_runtime_policy_docs.py | 139 ++++++++++++++++++ 5 files changed, 223 insertions(+), 24 deletions(-) create mode 100644 tests/test_stable_control_runtime_policy_docs.py diff --git a/docs/architecture/mcp-stable-control-runtime-policy-adr.md b/docs/architecture/mcp-stable-control-runtime-policy-adr.md index d4a3e6a..00608eb 100644 --- a/docs/architecture/mcp-stable-control-runtime-policy-adr.md +++ b/docs/architecture/mcp-stable-control-runtime-policy-adr.md @@ -43,17 +43,27 @@ MCP **server code** development and testing: ### 2.3 Forbidden actions (normal sessions) -Normal **author, reviewer, merger, and reconciler** sessions **must not**: +Normal **author, reviewer, merger, and reconciler** LLM sessions **must not**: | Forbidden | Why | |-----------|-----| | Kill the running MCP server process | Drops all concurrent sessions; loses preflight state | -| Restart the MCP server process | Same as kill; causes stale/identity churn mid-workflow | +| Restart / relaunch the MCP server process | Same as kill; causes stale/identity churn mid-workflow | | Relaunch MCP from a development worktree | Runs unpromoted code against production mutations | | Edit files in the stable runtime checkout | Hot-mutates control plane under concurrent users | | Use experimental/dev MCP for real Gitea mutations | Bypasses promotion proof and audit expectations | +| Bypass or self-reset a stale master-parity gate | The gate is fail-closed; only an operator reload restores parity | -EOF / transport recovery: **client reconnect only** (see `docs/mcp-namespace-eof-recovery.md`). Do not “fix” health by killing PIDs or bumping MCP config mtimes as a normal session procedure. +**LLM-allowed vs operator-owned (authoritative split):** + +| Actor | May do | Must not do | +|-------|--------|-------------| +| **LLM session** | Call tools on the already-running stable namespaces; **client reconnect** after transport EOF (no process kill); pass `worktree_path` / role worktree args; report blockers and stop mutations when unhealthy/stale | Kill, restart, or relaunch any MCP process; bump config mtimes to force reload; edit the stable checkout; switch to a dev MCP for production mutations | +| **Operator / release-manager** | Supervised restart/reload of the **stable** control runtime; dual-namespace client configuration; §2.4 promotions; incident recovery | — | + +EOF / transport recovery for LLM sessions: **client reconnect only** (see `docs/mcp-namespace-eof-recovery.md`). Do not “fix” health by killing PIDs or bumping MCP config mtimes as a normal session procedure. + +This ADR **supersedes** any older runbook wording that told the LLM to relaunch or restart the client/MCP as a self-service step. Where `docs/llm-workflow-runbooks.md` (or wiki runbooks) discuss dual-namespace setup or workspace rebind, **process restart/relaunch is operator-owned**; the LLM stops, reports, and waits. ### 2.4 Promotion (operator / release-manager only) @@ -95,14 +105,42 @@ Timestamp: ### 2.5 Unhealthy stable runtime → stop work -If the stable MCP runtime is **unhealthy** (client-namespace probes fail, wrong identity, wrong root, missing mutation capability, persistent EOF after reconnect): +If the stable MCP runtime is **unhealthy**, including any of: -1. **Normal PR / review / merge / issue-mutation work must stop.** -2. Do **not** improvise by switching to a dev worktree MCP for production mutations. -3. Resume only after: - - runtime is restored, **or** - - a **controlled** promotion/rollback completes with the promotion record above, **or** - - a controller invokes the narrow **bootstrap review path** (#557) when the defect is self-hosted and documented. +- client-namespace probes fail +- wrong identity / wrong profile +- wrong workspace root +- missing mutation capability for the intended role +- persistent EOF after **client reconnect** +- **master parity is stale** (`startup_head` behind on-disk `master` / `restart_required` from the parity gate) + +then: + +1. **Normal PR / review / merge / issue-mutation work must stop immediately.** +2. The session **reports** the unhealthy/stale state (tool error, CTH, or operator handoff) with startup vs current head when known. +3. Do **not** improvise: no LLM process kill/restart, no dev-worktree MCP for production mutations, no env escape hatches, no manual gate bypass. +4. Resume only after: + - an **operator** restores the runtime (see §2.6 for routine post-merge parity reload), **or** + - a **controlled** promotion/rollback completes with the §2.4 promotion record, **or** + - a controller invokes the narrow **bootstrap review path** (#557) when the defect is self-hosted and documented, + - **and** the session re-verifies health (and master parity when applicable) before the next mutation. + +### 2.6 Routine post-merge master-parity staleness (operator reload, not promotion) + +**Symptom:** After merges land on `master`, a long-lived stable MCP process still runs the pre-merge `startup_head`. The master-parity gate marks the server **stale** / `restart_required` and **blocks mutations**. + +**Sanctioned response (authoritative):** + +| Step | Actor | Action | +|------|-------|--------| +| 1 | LLM session | Mutations stop immediately when the gate reports stale. | +| 2 | LLM session | Report the stale state (startup head, current master head, that operator reload is required). Do not retry mutations. | +| 3 | **Operator** | Reload/restart the **stable** control MCP so it loads current `master` (supervised client/daemon reload). | +| 4 | LLM session | Resume only after startup/current-head parity is verified (e.g. `gitea_get_runtime_context` / parity assessment shows in parity). | + +**Not a §2.4 promotion:** Catching the already-designated stable control checkout up to a newly advanced `master` is a **routine operator reload** of the stable runtime. It does **not** require the nine-field promotion ledger. Use §2.4 only when **changing which unpromoted/dev revision** becomes the stable control runtime (new source branch/PR into the stable designation). + +**Code note:** `master_parity_gate.py` may still say “restart the server” in machine-facing reason strings. That string names the **operator recovery action**, not an LLM self-service instruction. This ADR and the runbooks define the actor split. ## 3. Relationship to other controls @@ -140,17 +178,21 @@ These may land in later issues; the **policy binds sessions now**: 1. Session preflight that refuses mutations if workspace root equals a `branches/` feature worktree configured as “dev only.” 2. Explicit `runtime_kind=stable|dev` in MCP config and `gitea_whoami` profile metadata. 3. Promotion checklist script that emits the durable promotion marker fields. -4. Operator Guide wiki cross-link to this ADR. + +**Not optional (issue #615 acceptance criterion 2):** operator guide and runbooks **must** cross-link this ADR (see §6). Cross-links are documentation acceptance, not deferred tooling. ## 6. Acceptance for this ADR -1. Document merged under `docs/architecture/`. -2. Issue #615 references this path. -3. LLM/operator runbooks treat kill/restart/relaunch-from-worktree as **violations**. -4. Unhealthy runtime stops normal mutation work until restore/promotion/rollback/bootstrap. +1. Document merged under `docs/architecture/mcp-stable-control-runtime-policy-adr.md`. +2. **Operator guide / runbooks cross-link this ADR** (`docs/wiki/Operator-Guide.md`, `docs/wiki/Runbooks.md`, `docs/llm-workflow-runbooks.md`). +3. Issue #615 references this path. +4. LLM/operator runbooks treat kill/restart/relaunch-from-worktree as **LLM violations**; process restart is **operator-owned**. +5. Unhealthy runtime (including **stale master parity**) stops normal mutation work until operator restore/reload, promotion/rollback, or #557 bootstrap — then re-verify parity before mutating. +6. Routine post-merge parity reload is documented as operator reload (§2.6), not an LLM self-restart and not a full §2.4 promotion. ## 7. Document history | Date | Change | |------|--------| | 2026-07-09 | Initial ADR: stable vs dev runtime, forbidden session actions, promotion proof fields, stop-work rule | +| 2026-07-16 | Review 443 remediation (#615 / PR #616): mandatory cross-links; LLM vs operator restart split; routine post-merge parity staleness (§2.6); stale parity in §2.5 unhealthy triggers | diff --git a/docs/llm-workflow-runbooks.md b/docs/llm-workflow-runbooks.md index 5fc591b..213b661 100644 --- a/docs/llm-workflow-runbooks.md +++ b/docs/llm-workflow-runbooks.md @@ -195,7 +195,7 @@ To avoid the bottleneck of relaunching/restarting the MCP server to switch betwe `gitea_reconcile_already_landed_pr` after ancestry proof — not for normal review or author workflows. -* **Fallback:** If the dual-profile MCP launcher pattern is not supported or configured in the client, the LLM must relaunch or restart the client/MCP with the correct profile environment variable before claiming or working on any tasks. +* **Fallback (operator-owned):** If the dual-profile MCP launcher pattern is not supported or configured in the client, **do not** have the LLM relaunch or restart the client/MCP. The LLM **stops** role-switching work, reports that the correct static namespace is missing, and waits for an **operator** to configure dual namespaces or reload the client with the correct `GITEA_MCP_PROFILE` for that role. Process restart/relaunch is operator-owned under the [stable control runtime ADR](architecture/mcp-stable-control-runtime-policy-adr.md) (#615). ## Setup runbook — interactive menu @@ -1200,10 +1200,13 @@ When a mutation blocks on workspace binding: 1. Read the error — it names the **resolved workspace path**, **role namespace**, and **binding source** (tool arg, env var, or process root). -2. Reconnect or relaunch the correct namespace MCP server from the intended - workspace (or set the role-specific env var before launch). -3. Pass `worktree_path` on reviewer/merger mutation tools when the active - branches/ worktree differs from the MCP process root. +2. **LLM-allowed:** pass `worktree_path` on reviewer/merger mutation tools when + the active `branches/` worktree differs from the MCP process root; **client + reconnect** after transport EOF only (no process kill). +3. **Operator-owned:** if the wrong namespace process was launched, or a role- + specific `GITEA_*_WORKTREE` must be set at process start, an **operator** + reloads/relaunches the correct static namespace MCP. LLM sessions must not + kill or restart MCP processes (see [stable control runtime ADR](architecture/mcp-stable-control-runtime-policy-adr.md)). 4. **Do not** clean, reset, or discard foreign role worktrees to unblock your own namespace — that destroys another agent's WIP. @@ -1213,9 +1216,10 @@ When posting a Canonical Thread Handoff after a binding blocker: - State which namespace was active (author / reviewer / merger / reconciler). - Quote the resolved workspace path and binding source from the error. -- Name the safe reconnect action (relaunch MCP from `branches/...`, set - `GITEA_*_WORKTREE`, or pass `worktree_path`). -- Explicitly note that foreign worktrees must not be cleaned to unblock. +- Name the safe next action: pass `worktree_path` if that unblocks the tool, or + request an **operator** reload of the correct namespace MCP / env binding. +- Explicitly note that foreign worktrees must not be cleaned to unblock, and + that the LLM must not self-restart the MCP process. ## Safety notes @@ -1226,6 +1230,7 @@ When posting a Canonical Thread Handoff after a binding blocker: ## Related documents +- [`architecture/mcp-stable-control-runtime-policy-adr.md`](architecture/mcp-stable-control-runtime-policy-adr.md) — stable control runtime vs dev runtime; LLM must not kill/restart MCP; operator-owned reload and promotions; routine post-merge parity staleness (#615). - [`reviewer-handoff-consistency.md`](reviewer-handoff-consistency.md) — reject contradictory reviewer handoffs (#501). - [`issue-acceptance-gate.md`](issue-acceptance-gate.md) — controller issue-acceptance audit after PR merge (#500). - [`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) — portable cross-project LLM workflow skill. diff --git a/docs/wiki/Operator-Guide.md b/docs/wiki/Operator-Guide.md index 9052c47..80c2356 100644 --- a/docs/wiki/Operator-Guide.md +++ b/docs/wiki/Operator-Guide.md @@ -14,6 +14,7 @@ Handbook for LLM operators and human developers using the Gitea-Tools MCP server 4. **No self-review / no self-merge** — The authenticated Gitea user must not approve or merge a PR they authored. 5. **Follow the gates** — Prompts express intent; MCP tools enforce safety. Never bypass gates via prompt instructions. 6. **Global LLM Worktree Rule** — Main checkout stays on `master`/`main`/`dev`; all mutations happen under `branches/`. Prove project root, `cwd`, branch, stable main-checkout branch, and session worktree path before editing. No exceptions. +7. **Stable control runtime** — Real Gitea mutations use only the **stable** MCP control runtime. LLM sessions must not kill, restart, or relaunch MCP processes, edit the stable checkout, or use a dev MCP for production mutations. See the policy ADR: [mcp-stable-control-runtime-policy-adr.md](../architecture/mcp-stable-control-runtime-policy-adr.md) (#615). ## Supported Gitea instances @@ -29,4 +30,5 @@ Always pass `remote` explicitly on tool calls. The server default is `dadeschool 1. `gitea_whoami` — confirm authenticated user and profile. 2. `gitea_get_runtime_context` — allowed/forbidden operations for this session. 3. `gitea_resolve_task_capability` — prove the session may perform the planned task. -4. For reviewer work: dry-run validation (`gitea_dry_run_pr_review`) before live review mutations. \ No newline at end of file +4. For reviewer work: dry-run validation (`gitea_dry_run_pr_review`) before live review mutations. +5. Confirm master parity / runtime health when tools report stale or unhealthy control runtime — stop mutations and request an **operator** reload of the stable MCP (see [stable control runtime ADR](../architecture/mcp-stable-control-runtime-policy-adr.md)). \ No newline at end of file diff --git a/docs/wiki/Runbooks.md b/docs/wiki/Runbooks.md index d42fe19..2dcb4b2 100644 --- a/docs/wiki/Runbooks.md +++ b/docs/wiki/Runbooks.md @@ -12,6 +12,17 @@ 4. `gitea_mark_final_review_decision` → approve via `gitea_review_pr`. 5. `gitea_merge_pr` with pinned head SHA and `confirmation="MERGE PR "`. +## Stable MCP control runtime (#615) + +Policy ADR: [mcp-stable-control-runtime-policy-adr.md](../architecture/mcp-stable-control-runtime-policy-adr.md). + +| Situation | Who acts | What to do | +|-----------|----------|------------| +| Transport EOF / missing tools | LLM | **Client reconnect only** — do not kill PIDs | +| Wrong profile / dual-namespace missing | Operator | Configure or reload the correct static namespace(s) | +| Master parity stale after merge | LLM stops + reports; **operator** reloads stable MCP | Resume only after parity re-verified | +| Promote unpromoted MCP code to stable | Operator / release-manager only | Full §2.4 promotion record | + ## Gitea Wiki sync The Gitea Wiki mirrors `docs/wiki/` (source of truth). After merging wiki changes: diff --git a/tests/test_stable_control_runtime_policy_docs.py b/tests/test_stable_control_runtime_policy_docs.py new file mode 100644 index 0000000..b533aeb --- /dev/null +++ b/tests/test_stable_control_runtime_policy_docs.py @@ -0,0 +1,139 @@ +"""Documentation acceptance for the stable control runtime ADR (#615 / PR #616). + +Enforces review 443 remediation: + +* F1 — operator guide / runbooks cross-link the ADR (issue #615 AC2). +* F2 — LLM sessions are not instructed to kill/restart/relaunch MCP; process + restart is operator-owned; ADR is the authoritative split. +* F3 — routine post-merge master-parity staleness has a sanctioned response + (stop → report → operator reload → re-verify parity) and is not a full + promotion ledger requirement. +""" +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +ADR = ( + REPO_ROOT + / "docs" + / "architecture" + / "mcp-stable-control-runtime-policy-adr.md" +) +ADR_REL = "architecture/mcp-stable-control-runtime-policy-adr.md" +ADR_BASENAME = "mcp-stable-control-runtime-policy-adr.md" + +CROSS_LINK_DOCS = ( + REPO_ROOT / "docs" / "wiki" / "Operator-Guide.md", + REPO_ROOT / "docs" / "wiki" / "Runbooks.md", + REPO_ROOT / "docs" / "llm-workflow-runbooks.md", +) + + +def _read(path: Path) -> str: + assert path.is_file(), f"missing {path.relative_to(REPO_ROOT)}" + return path.read_text(encoding="utf-8") + + +def test_adr_exists_with_policy_core(): + text = _read(ADR) + assert text.lstrip().startswith("#"), "ADR lacks a title" + assert "#615" in text + assert "stable control runtime" in text.lower() + assert "2.3" in text and "2.4" in text and "2.5" in text and "2.6" in text + + +def test_f1_operator_docs_cross_link_adr(): + for path in CROSS_LINK_DOCS: + text = _read(path) + assert ADR_BASENAME in text, ( + f"{path.relative_to(REPO_ROOT)} must cross-link {ADR_BASENAME} " + f"(issue #615 acceptance criterion 2)" + ) + + +def test_f1_adr_lists_cross_links_as_acceptance_not_optional_tooling(): + text = _read(ADR) + # Acceptance section must require guide/runbook cross-links. + assert "Operator guide / runbooks cross-link" in text or ( + "operator guide" in text.lower() and "cross-link" in text.lower() + and "Acceptance" in text + ) + # Cross-link must not remain only as optional tooling item #4. + optional = text.split("## 5. Implementation follow-ups", 1)[-1].split( + "## 6. Acceptance", 1 + )[0] + assert "Operator Guide wiki cross-link to this ADR" not in optional, ( + "ADR §5 must not list operator-guide cross-link as optional tooling" + ) + assert "Not optional" in text or "must** cross-link" in text.lower() or ( + "must cross-link" in text.lower() + ) + + +def test_f2_runbook_fallback_is_operator_owned_not_llm_restart(): + runbooks = _read(REPO_ROOT / "docs" / "llm-workflow-runbooks.md") + # Forbidden historical self-service instruction. + forbidden = ( + "the LLM must relaunch or restart the client/MCP with the correct " + "profile environment variable before claiming or working on any tasks" + ) + assert forbidden not in runbooks, ( + "llm-workflow-runbooks must not instruct the LLM to relaunch/restart MCP" + ) + assert "operator-owned" in runbooks.lower() or "Operator-owned" in runbooks + assert ADR_BASENAME in runbooks + + +def test_f2_workspace_rebind_does_not_require_llm_process_relaunch(): + runbooks = _read(REPO_ROOT / "docs" / "llm-workflow-runbooks.md") + section = runbooks.split("### Safe reconnect / rebind procedure", 1)[-1] + section = section.split("## Safety notes", 1)[0] + # Must not tell the LLM alone to relaunch the MCP process as step 2. + assert "Reconnect or relaunch the correct namespace MCP server from the intended" not in section + assert "Operator-owned" in section or "operator" in section.lower() + assert "worktree_path" in section + collapsed = " ".join(section.lower().split()) + assert "client reconnect" in collapsed + + +def test_f2_adr_forbids_llm_restart_and_supersedes_self_service_relaunch(): + text = _read(ADR) + lower = text.lower() + assert "must not" in lower and "restart" in lower + assert "operator" in lower and "reload" in lower + assert "supersedes" in lower + assert "llm" in lower + + +def test_f3_adr_defines_post_merge_parity_staleness_response(): + text = _read(ADR) + lower = text.lower() + assert "2.6" in text + assert "post-merge" in lower or "post merge" in lower + assert "parity" in lower and "stale" in lower + # Sanctioned steps: stop, report, operator reload, re-verify. + assert "stop" in lower + assert "report" in lower + assert "operator" in lower + assert "parity is verified" in lower or "re-verif" in lower or ( + "startup/current-head" in lower + ) + # Not a full promotion ledger for routine reload. + assert "not a §2.4 promotion" in lower or "not a section 2.4 promotion" in lower or ( + "not a §2.4" in text or "Not a §2.4 promotion" in text + ) + # Stale parity listed among unhealthy triggers. + assert "master parity is stale" in lower or "stale master parity" in lower + + +def test_f3_adr_forbids_llm_bypass_of_parity_gate(): + text = _read(ADR) + lower = text.lower() + assert "bypass" in lower or "self-reset" in lower or "self-service" in lower + assert "parity" in lower + + +def test_cross_links_do_not_embed_secrets_or_raw_hosts_in_wiki_snippets(): + for path in CROSS_LINK_DOCS: + text = _read(path) + for marker in ("ghp_", "BEGIN PRIVATE KEY", "Authorization: Bearer"): + assert marker not in text, f"{path} contains {marker!r}"