docs: add agent temp-artifact cleanup runbook and ignore patterns (closes #261)

Failed subagent runs left throwaway helpers (_encode_commit_payload.py,
_emit_payload.py) in the shared working tree, polluting git status and
tripping gitea_lock_issue / pre-flight purity gates.

Add an 'Agent temp artifact cleanup' runbook section requiring deletion
of _encode_*/_emit_*/_inline_* helpers when the MCP commit completes or
aborts, prefer scratchpad payload preparation, and document the cleanup
checklist. Back it with .gitignore patterns so strays cannot block
issue locks for later sessions, and pin both with doc-contract tests
(including a repo-root scan asserting the artifacts stay removed).

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

.gitignore

@@ -10,3 +10,8 @@ gitea-mcp*.json
 .vscode/
 graphify-out/
 branches/
+# Throwaway agent payload/encoding helpers (#261): delete after the MCP
+# commit completes or aborts; ignored here so strays cannot block issue locks.
+_encode_*.py
+_emit_*.py
+_inline_*.py

docs/architecture/jenkins-readonly-build-status-design.md

@@ -5,7 +5,7 @@
 - **Related:** #77 (repo/branch/PR → job mapping, designed separately)
 - **Date:** 2026-07-02
 
-Note on naming: This design used historical `jenkins-readonly` skill name in Gitea-Tools. Actual package/server is `jenkins-mcp` (see mcp-control-plane registration in #55). The server boundary now contains gated trigger (see #56), but read tools remain as designed.
+Note on naming: This design used historical `jenkins-readonly` skill name in Gitea-Tools. Actual package/server is `jenkins-mcp` (see mcp-control-plane registration in #55). The read server boundary remains read-only; gated triggers live on the separate `jenkins-write-mcp` / `jenkins_mcp.write_server` boundary (see #56 / #152).
 Client registration and reload instructions live in
 [`../mcp-client-registration.md`](../mcp-client-registration.md).
 
@@ -18,7 +18,9 @@ detail (build URL, number, timing, result) to report or investigate.
 Phase 1 is **primarily read-only**, per ADR-0001
 ([`adr-0001-mcp-control-plane-boundaries.md`](adr-0001-mcp-control-plane-boundaries.md)):
 
-- Build triggers are gated behind dedicated profile + exact confirmation (landed in #4, boundary correction in #56).
+- Build triggers are outside this read-only surface and require the separate
+  `jenkins-write-mcp` boundary, a dedicated profile, exact confirmation, and
+  fail-closed mutation audit (landed in #4, boundary correction in #56 / #152).
 - **Excluded: deploy triggers.**
 - **Excluded: parameterized job launches.**
 - Excluded: job creation/deletion/config changes, queue manipulation, node
@@ -109,7 +111,7 @@ by #76):
   `forbidden_operations: ["jenkins.build.trigger", "jenkins.deploy", "jenkins.job.configure"]`
   as belt-and-braces even though no mutating tool exists.
 - Missing URL/user/token/profile ⇒ **fail closed** with a clear message.
-- Since every tool is read-only, no confirmation gates are needed — but
+- Since every tool on `jenkins-mcp` is read-only, no confirmation gates are needed — but
   identity (`jenkins_whoami`) must still work so workflows can prove which
   Jenkins account they act as.
 

docs/llm-workflow-runbooks.md

@@ -229,6 +229,62 @@ Legacy environment-only setups keep working unchanged until migrated.
 Each runbook names the **profile role** it runs under, the steps, and a safe
 prompt. Confirm the active profile first (`gitea_get_profile` / `gitea_whoami`).
 
+## Work Selection Rule for LLMs
+
+Before starting any issue or PR work, acquire or verify a work lease. Do not
+begin coding, reviewing, fixing, branching, committing, pushing, commenting,
+or creating a PR until you prove the target is not already being worked.
+
+Required checks:
+
+1. List open PRs.
+2. Search for PRs linked to the target issue.
+3. Search local and remote branches for the issue number.
+4. Search registered worktrees for the issue branch.
+5. Check dirty worktrees.
+6. Check active leases or recent handoffs.
+7. Check whether the issue was already completed by a merged PR.
+
+If another active LLM/session owns the lease, stop. Allowed responses:
+continue as the lease owner; review the existing PR if reviewer capability
+allows; produce a handoff; request takeover after lease expiry; stop with
+"work already claimed."
+
+Never create a parallel branch or PR for the same issue unless the old branch
+is proven abandoned and the takeover is recorded.
+
+Gitea-Tools lease gates: `gitea_lock_issue` (fail-closed before author
+mutations), `status:in-progress`, and claim comments. Full portable wording:
+[`skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md).
+
+## Global LLM Worktree Rule
+
+The main project checkout is a stable control checkout. It must stay on the
+configured stable branch: `master`, `main`, or `dev`.
+
+All LLM task work must happen inside the project's `branches/` directory.
+
+Before any mutation, prove:
+
+1. current project root
+2. current working directory
+3. current branch
+4. stable branch for the main checkout
+5. session-owned worktree path under `branches/`
+
+If `cwd` is not inside `branches/`, stop. Do not edit, create, delete, format,
+test-write, commit, merge, rebase, checkout task branches, resolve conflicts,
+or run cleanup.
+
+There are no exceptions for small fixes, docs, tests, cleanup, PR review fixes,
+conflict resolution, or emergencies.
+
+The main checkout may only be used for read-only inspection, fetching,
+stable-branch update after merged PRs, creating `branches/` worktrees, or
+explicit control-checkout repair.
+
+Portable wording: [`skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md).
+
 ## Branch worktree isolation
 
 All LLM implementation and review work happens in an isolated branch worktree
@@ -403,6 +459,33 @@ touching anything.
   files, detected secret, or any production/deploy behavior — **stop, report the
   blocker, and take no mutating action.** Fail closed; never work around a gate.
 
+## Agent temp artifact cleanup (#261)
+
+Failed or aborted subagent runs have left throwaway helper scripts in the
+shared working tree — for example `_encode_commit_payload.py` and
+`_emit_payload.py` from the #152 commit-recovery attempt. These artifacts are
+never part of any issue scope. They pollute `git status`, which trips
+fail-closed gates: `gitea_lock_issue` refuses to lock over tracked edits, and
+the pre-flight purity checks attribute the dirt to the current session.
+
+Rules:
+
+- **Delete throwaway helpers as soon as the MCP commit completes or aborts.**
+  Any file matching `_encode_*`, `_emit_*`, or `_inline_*` created as a
+  scratch payload/encoding helper must be removed in the same session that
+  created it — success and failure paths alike.
+- **Prefer the scratchpad.** Payload preparation belongs in the session
+  scratchpad or a temp directory, never inside the repository worktree
+  (see the shell-free commit payload work in #263).
+- **`.gitignore` backstop.** The patterns `_encode_*.py`, `_emit_*.py`, and
+  `_inline_*.py` are ignored so a leftover helper cannot show up as an
+  untracked file and block issue locks for later sessions. Ignoring them is a
+  safety net, not permission to leave them behind.
+- **Cleanup checklist before ending any author session:** run
+  `git status --porcelain` in the worktree you mutated; remove any
+  `_encode_*` / `_emit_*` / `_inline_*` files you created; report the removal
+  in the final run report like any other local mutation.
+
 ## Task/role alignment (#167)
 
 The **requested task** decides what a session may do — not the credential it

docs/mcp-client-registration.md

@@ -9,9 +9,14 @@ Use these exact MCP server names in clients:
 
 | Server name | Boundary | Default capability |
 |---|---|---|
-| `jenkins-mcp` | Jenkins CI inspection | Read-only build/job inspection |
+| `jenkins-mcp` | Jenkins CI inspection (read) | Read-only build/job inspection |
+| `jenkins-write-mcp` | Jenkins build trigger (write) | Gated `jenkins_trigger_build` only |
 | `glitchtip-mcp` | GlitchTip observability inspection | Read-only issue/event inspection |
 
+The write boundary (`jenkins-write-mcp`) is **not** registered by default (#152).
+It exposes a single mutating tool and requires operator approval of a dedicated
+trigger profile before any client config references it.
+
 Historical names such as `jenkins-readonly` and `glitchtip-readonly` are
 descriptive profile labels only. They are not the canonical MCP server names
 unless an operator intentionally creates aliases and documents them.
@@ -54,7 +59,7 @@ entry, reconnect or reload the MCP client before claiming the tools are usable.
 Before using either server in a task, prove the expected tools are visible in
 the client. It is not enough for the config entry to exist.
 
-Expected Jenkins tools:
+Expected Jenkins read tools (`jenkins-mcp` only):
 
 - `jenkins_whoami`
 - `jenkins_list_jobs`
@@ -62,6 +67,10 @@ Expected Jenkins tools:
 - `jenkins_build_status`
 - `jenkins_get_build`
 
+`jenkins_trigger_build` must **not** appear on `jenkins-mcp`. When an operator
+explicitly enables the write boundary, the only expected tool on
+`jenkins-write-mcp` is `jenkins_trigger_build`.
+
 Expected GlitchTip tools:
 
 - `glitchtip_whoami`
@@ -78,8 +87,13 @@ back to shell commands, raw service APIs, or unrelated MCP servers.
 ## Boundary Rules
 
 - `jenkins-mcp` read profiles must not expose build trigger tools.
-- Jenkins build triggers require a separately named write profile, exact
-  confirmation, and fail-closed mutation audit.
+- Build triggers live on the separate `jenkins-write-mcp` server
+  (`jenkins_mcp.write_server`), not on `jenkins-mcp`.
+- Jenkins build triggers require a dedicated trigger profile with
+  `jenkins.build.trigger` allowed, exact confirmation
+  (`TRIGGER BUILD <job-path>`), and fail-closed mutation audit.
+- Do not register `jenkins-write-mcp` until an operator approves a trigger
+  profile; no shipped profile carries trigger capability by default.
 - `glitchtip-mcp` remains read-only. It must not file or mutate Gitea issues.
 - GlitchTip-to-Gitea filing is a separate orchestrator that composes GlitchTip
   read tools with Gitea issue-write tools.

docs/safety-model.md

@@ -21,5 +21,10 @@ Note on naming: Historical design docs used `jenkins-readonly` / `glitchtip-read
 
 ## 5. Mutation Gating
 Any mutating action (e.g., Gitea issue creation from GlitchTip, or Jenkins builds) must be explicitly allowed by the execution profile.
-- **Jenkins build triggers** exist in jenkins-mcp (landed #4) but require dedicated profile/identity and exact confirmation; not on standard reader profiles. See #56 for boundary correction.
-- **GlitchTip to Gitea issue filing** is documented as a gated, orchestrated workflow (not in glitchtip-mcp), currently partial (mocked, dedup not wired, audit missing). See #57.
+- **Jenkins build triggers** are gated on a separate write boundary
+  (`jenkins-write-mcp` / `jenkins_mcp.write_server`), not on the read-only
+  `jenkins-mcp` surface. Triggers require a dedicated profile with
+  `jenkins.build.trigger`, exact confirmation, and fail-closed mutation audit.
+  No default profile carries trigger capability (#152 / mcp-control-plane #56).
+- **GlitchTip to Gitea issue filing** is a library-only orchestrator in
+  mcp-control-plane (not on `glitchtip-mcp`). See #153 / mcp-control-plane #57.

docs/wiki/Operator-Guide.md

@@ -13,6 +13,7 @@ Handbook for LLM operators and human developers using the Gitea-Tools MCP server
 3. **One unit of work per session** — Implement one claimed issue *or* review/merge one PR; do not mix author and reviewer mutations in one session.
 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.
 
 ## Supported Gitea instances
 

docs/wiki/Workflow.md

@@ -14,6 +14,12 @@
 
 ## Step 2: Implement issues (author profile)
 
+0. Work Selection Rule — verify a work lease before any mutations (open PRs,
+   issue-linked PRs, branches, worktrees, dirty worktrees, active leases/
+   handoffs, merged-PR completion). Stop if another session owns the lease.
+0b. Global LLM Worktree Rule — main checkout on `master`/`main`/`dev` only;
+   mutate only from a `branches/` worktree after proving root, cwd, branch,
+   stable main-checkout branch, and session worktree path (no exceptions).
 1. `gitea_resolve_task_capability` for the author task.
 2. `gitea_lock_issue` before implementation mutations.
 3. Claim with `gitea_mark_issue` / `status:in-progress` label.

gitea_mcp_server.py

@@ -3460,11 +3460,40 @@ _GUIDE_RULES = {
         "Conflicting or stale PR state (e.g. prior said merged but live open, or head/updated mismatch) is a hard blocker: report it explicitly and stop until live state is unambiguous.",
         "After merge, re-list PRs and re-view the PR (plus verify master contains the merge) before claiming completion.",
     ],
+    "work_selection": (
+        "Before any issue or PR work, acquire or verify a work lease. Do not "
+        "code, review, branch, commit, push, comment, or open a PR until you "
+        "prove the target is not already being worked. Required checks: list "
+        "open PRs; search PRs linked to the issue; search local/remote "
+        "branches for the issue number; search worktrees for the issue "
+        "branch; check dirty worktrees; check active leases or recent "
+        "handoffs; check whether a merged PR already completed the issue. If "
+        "another session owns the lease, stop (continue as owner, review the "
+        "existing PR, hand off, request takeover after expiry, or report "
+        "'work already claimed'). Never create a parallel branch/PR unless "
+        "the old branch is proven abandoned and takeover is recorded. "
+        "gitea_lock_issue is the fail-closed author lease gate."),
+    "global_worktree": (
+        "Main checkout is a stable control checkout on master/main/dev only. "
+        "All LLM task work happens under branches/. Before any mutation, prove "
+        "project root, cwd, branch, main-checkout stable branch, and "
+        "session-owned branches/ worktree path. If cwd is not under "
+        "branches/, stop — no edit/create/delete/format/test-write/commit/"
+        "merge/rebase/checkout/cleanup, with no exceptions (docs, tests, "
+        "small fixes, review fixes, conflicts, emergencies). Main checkout: "
+        "read-only inspect, fetch, create worktrees, post-merge stable "
+        "update, explicit repair only."),
 }
 
 _COMMON_WORKFLOWS = [
     "task routing: resolve task capability via gitea_resolve_task_capability "
     "to check required permission/role kind and identify the safe next action.",
+    "work selection: acquire or verify a work lease before any issue/PR work "
+    "(open PRs, linked PRs, branches, worktrees, dirty worktrees, leases, "
+    "merged completion); stop if another session owns the lease.",
+    "global worktree: main checkout on master/main/dev only; mutate only "
+    "from a branches/ worktree after proving root, cwd, branch, stable "
+    "main-checkout branch, and session worktree path.",
     "issue authoring: verify identity, create/claim the issue, keep scope "
     "explicit (remote/org/repo).",
     "implementation: claim issue, branch from fresh master, implement only "
@@ -4074,6 +4103,90 @@ def gitea_get_profile(
     return result
 
 
+_RUNTIME_CAPABILITY_TASKS = (
+    "create_issue",
+    "comment_issue",
+    "create_pr",
+    "review_pr",
+    "merge_pr",
+    "close_issue",
+)
+
+
+def _matching_configured_profiles(
+    config: dict | None,
+    required_permission: str,
+) -> list[str]:
+    """Profile names that allow *required_permission* (redacted metadata only)."""
+    if not config or "profiles" not in config:
+        return []
+    matches: list[str] = []
+    for p_name, p_data in config["profiles"].items():
+        if not p_data.get("enabled", True):
+            continue
+        p_allowed = p_data.get("allowed_operations") or []
+        p_forbidden = p_data.get("forbidden_operations") or []
+        p_allowed_n = []
+        for op in p_allowed:
+            try:
+                p_allowed_n.append(gitea_config.normalize_operation(op))
+            except Exception:
+                pass
+        p_forbidden_n = []
+        for op in p_forbidden:
+            try:
+                p_forbidden_n.append(gitea_config.normalize_operation(op))
+            except Exception:
+                pass
+        ok, _ = gitea_config.check_operation(
+            required_permission, p_allowed_n, p_forbidden_n
+        )
+        if ok:
+            matches.append(p_name)
+    return sorted(matches)
+
+
+def _build_runtime_task_capabilities(
+    allowed: list[str],
+    forbidden: list[str],
+    config: dict | None,
+) -> dict:
+    """Per-task capability summary for role-aware runtime context (#139)."""
+    task_entries = []
+    flags: dict[str, bool] = {}
+    flag_keys = {
+        "create_issue": "can_create_issues",
+        "comment_issue": "can_comment_on_issues",
+        "create_pr": "can_author_prs",
+        "review_pr": "can_review_prs",
+        "merge_pr": "can_merge_prs",
+        "close_issue": "can_close_issues",
+    }
+    for task in _RUNTIME_CAPABILITY_TASKS:
+        permission = task_capability_map.required_permission(task)
+        allowed_here, _ = gitea_config.check_operation(
+            permission, allowed, forbidden
+        )
+        entry = {
+            "task": task,
+            "required_permission": permission,
+            "required_role_kind": task_capability_map.required_role(task),
+            "allowed_in_current_session": allowed_here,
+            "matching_configured_profiles": _matching_configured_profiles(
+                config, permission
+            ),
+        }
+        task_entries.append(entry)
+        flag_name = flag_keys.get(task)
+        if flag_name:
+            flags[flag_name] = allowed_here
+    return {
+        **flags,
+        "issue_comment_not_implied_by_pr_comment": True,
+        "task_capabilities": task_entries,
+    }
+
+
 @mcp.tool()
 def gitea_get_runtime_context(
     remote: str = "dadeschools",
@@ -4161,6 +4274,10 @@ def gitea_get_runtime_context(
             "or ask the operator to update GITEA_MCP_PROFILE to a reviewer profile."
         )
 
+    session_capabilities = _build_runtime_task_capabilities(
+        allowed, forbidden, config
+    )
+
     preflight = assess_preflight_status()
     if not preflight["preflight_ready"]:
         safe_next_action = (
@@ -4185,6 +4302,7 @@ def gitea_get_runtime_context(
         "safe_next_action": safe_next_action,
         "preflight_ready": preflight["preflight_ready"],
         "preflight_block_reasons": preflight["preflight_block_reasons"],
+        "session_capabilities": session_capabilities,
     }
 
     if reveal and h:

mcp_server.py

@@ -6,26 +6,24 @@ Runs over stdio. All tools authenticate via macOS keychain (git credential fill)
 import os
 import sys
 
+from role_session_router import (
+    python_bytes_have_conflict_markers,
+    skip_python_scan_walk_root,
+)
+
+
 # Startup health check: scan all python files in the Gitea-Tools directory for unresolved conflict markers.
 def check_conflict_markers():
     dir_path = os.path.dirname(os.path.abspath(__file__))
-    # Construct conflict patterns dynamically so the loader does not match itself
-    conflict_patterns = [
-        b"<" * 7 + b" ",
-        b"=" * 7 + b"\n",
-        b"=" * 7 + b"\r\n",
-        b">" * 7 + b" "
-    ]
     for root, dirs, files in os.walk(dir_path):
-        if any(p in root for p in ("venv", ".git", ".pytest_cache", "branches")):
+        if skip_python_scan_walk_root(dir_path, root):
             continue
         for file in files:
             if file.endswith(".py"):
                 file_path = os.path.join(root, file)
                 try:
                     with open(file_path, "rb") as f:
-                        content = f.read()
-                        if any(pattern in content for pattern in conflict_patterns):
+                        if python_bytes_have_conflict_markers(f.read()):
                             rel_path = os.path.relpath(file_path, dir_path)
                             print(
                                 f"infra_stop: Unresolved merge conflict detected in {rel_path}. "

review_proofs.py

@@ -1297,6 +1297,16 @@ HANDOFF_ROLE_FIELDS = {
         ("Session authored PR", ("session authored pr", "authored pr")),
         ("Why continuation allowed", ("why continuation", "continuation allowed")),
     ),
+    "issue_filing": (
+        ("Issue created or updated", (
+            "issue created or updated",
+            "issue created",
+            "issue updated",
+            "created issue",
+            "updated issue",
+        )),
+        ("Related issues", ("related issues",)),
+    ),
 }
 
 
@@ -2135,6 +2145,309 @@ def assess_issue_selection_final_report(
     }
 
 
+_SHA_EVIDENCE_LABEL = re.compile(
+    r"(?:\b(?:old|new)\s+head\b|\bhead\s+sha\b|\bcommit\s+sha\b|\bsha\b)"
+    r"\s*[:=]?\s*([0-9a-f]+)",
+    re.IGNORECASE,
+)
+
+
+def assess_issue_filing_sha_evidence(report_text: str) -> dict:
+    """Issue #191: commit evidence must use full 40-hex SHAs."""
+    text = report_text or ""
+    reasons = []
+    for match in _SHA_EVIDENCE_LABEL.finditer(text):
+        sha = match.group(1).strip().lower()
+        if sha and not _FULL_SHA.match(sha):
+            reasons.append(
+                f"abbreviated SHA in evidence ({len(sha)} hex chars); "
+                "full 40-character SHA required"
+            )
+    return {
+        "complete": not reasons,
+        "downgraded": bool(reasons),
+        "reasons": reasons,
+    }
+
+
+def assess_issue_filing_issue_reference(
+    report_text: str,
+    *,
+    issue_number: int | None = None,
+    issue_title: str | None = None,
+    action: str = "created",
+) -> dict:
+    """Issue #191: reports must cite exact issue number and title."""
+    text = (report_text or "").lower()
+    reasons = []
+    if issue_number is None:
+        reasons.append("issue number proof missing from assessment context")
+    else:
+        num_patterns = (f"#{issue_number}", f"issue #{issue_number}",
+                        f"issue {issue_number}")
+        if not any(p in text for p in num_patterns):
+            reasons.append(
+                f"report missing exact issue number #{issue_number}"
+            )
+    if issue_title:
+        title_fragment = issue_title.strip().lower()[:40]
+        if title_fragment and title_fragment not in text:
+            reasons.append("report missing exact issue title")
+    action = (action or "created").strip().lower()
+    if action == "created" and "creat" not in text:
+        reasons.append(
+            "report must distinguish new issue creation from update"
+        )
+    if action == "updated" and "updat" not in text:
+        reasons.append(
+            "report must distinguish issue update from new creation"
+        )
+    return {
+        "complete": not reasons,
+        "downgraded": bool(reasons),
+        "reasons": reasons,
+    }
+
+
+def assess_issue_filing_mutation_capability(
+    report_text: str,
+    mutations: list[str] | None,
+    resolved_capabilities: dict | None = None,
+) -> dict:
+    """Issue #191: every mutation needs exact capability proof in the report."""
+    import task_capability_map
+
+    text = (report_text or "").lower()
+    reasons = []
+    mutation_list = list(mutations or [])
+    if not mutation_list:
+        reasons.append("no mutations listed for capability proof")
+    cap_proof = assess_capability_proof(resolved_capabilities or {})
+    if not cap_proof.get("proven"):
+        reasons.extend(cap_proof.get("reasons") or [])
+
+    for task in mutation_list:
+        try:
+            permission = task_capability_map.required_permission(task)
+        except KeyError:
+            reasons.append(f"unknown mutation task '{task}'")
+            continue
+        if permission.lower() not in text and task.replace("_", " ") not in text:
+            reasons.append(
+                f"mutation '{task}' missing exact capability proof "
+                f"('{permission}')"
+            )
+        if task == "set_issue_labels":
+            label_proof = (
+                "label change",
+                "labels changed",
+                "set label",
+                "label mutation",
+                "issue labels",
+                "label:",
+            )
+            if not any(p in text for p in label_proof):
+                reasons.append(
+                    "label mutation missing label-specific capability proof"
+                )
+    return {
+        "complete": not reasons,
+        "downgraded": bool(reasons),
+        "reasons": reasons,
+    }
+
+
+def assess_issue_filing_mutation_scope(
+    report_text: str,
+    *,
+    performed_mutations: list[str] | None = None,
+    forbidden_mutations: list[str] | None = None,
+) -> dict:
+    """Issue #191: single-mutation runs must state scope and absent mutations."""
+    text = (report_text or "").lower()
+    performed = list(performed_mutations or [])
+    forbidden = list(forbidden_mutations or [
+        "label", "comment", "pr", "review", "merge", "close",
+    ])
+    reasons = []
+
+    if len(performed) == 1:
+        only_phrases = ("only mutation", "only mutations", "sole mutation")
+        if not any(p in text for p in only_phrases):
+            reasons.append(
+                "single-mutation run must state 'Only mutation(s): ...'"
+            )
+        for absent in forbidden:
+            if absent == "comment" and performed[0] in (
+                "comment_issue", "create_issue",
+            ):
+                continue
+            if absent not in text:
+                continue
+            denial_phrases = (
+                f"no {absent}",
+                f"no {absent}s",
+                f"without {absent}",
+                "none performed",
+                "none.",
+                "confirm no",
+            )
+            if any(phrase in text for phrase in denial_phrases):
+                continue
+            reasons.append(
+                f"single-mutation run mentions '{absent}' without "
+                f"confirming it was not performed"
+            )
+        if performed == ["create_issue"]:
+            for check in ("label", "comment", "pr", "review", "merge"):
+                if check in text and f"no {check}" not in text:
+                    if not any(
+                        n in text
+                        for n in (
+                            f"no {check}",
+                            f"no {check}s",
+                            "none performed",
+                            "confirm no",
+                        )
+                    ):
+                        reasons.append(
+                            f"create-only run must confirm no {check} "
+                            "mutations were performed"
+                        )
+
+    return {
+        "complete": not reasons,
+        "downgraded": bool(reasons),
+        "reasons": reasons,
+    }
+
+
+def assess_issue_filing_duplicate_summary(
+    report_text: str,
+    *,
+    issues_searched: int | None = None,
+    closest_matches: list[dict] | None = None,
+    duplicate_result: dict | None = None,
+) -> dict:
+    """Issue #191: duplicate-check evidence must be summarized in the report."""
+    text = (report_text or "").lower()
+    reasons = []
+    dup = duplicate_result or {}
+
+    if issues_searched is not None:
+        count_tokens = (
+            str(issues_searched),
+            f"{issues_searched} open",
+            f"{issues_searched} issue",
+        )
+        if not any(t in text for t in count_tokens):
+            reasons.append(
+                "duplicate-check summary missing open-issues searched count"
+            )
+
+    matches = closest_matches if closest_matches is not None else dup.get("matches")
+    for match in matches or []:
+        num = match.get("number")
+        if num is not None and f"#{num}" not in text and str(num) not in text:
+            reasons.append(
+                f"duplicate-check summary missing closest issue #{num}"
+            )
+            break
+
+    justification_phrases = (
+        "why new",
+        "why update",
+        "rejected update",
+        "new issue justified",
+        "not a duplicate",
+        "no duplicate",
+        "justified",
+        "instead of expanding",
+    )
+    if not any(p in text for p in justification_phrases):
+        reasons.append(
+            "duplicate-check summary missing why update was rejected or "
+            "why a new issue was justified"
+        )
+
+    dup_proof = issue_duplicate_gate.assess_duplicate_search_proof(
+        report_text, matches or []
+    )
+    if not dup_proof.get("valid"):
+        reasons.extend(dup_proof.get("reasons") or [])
+
+    return {
+        "complete": not reasons,
+        "downgraded": bool(reasons),
+        "reasons": reasons,
+    }
+
+
+def assess_issue_filing_final_report(
+    report_text: str,
+    *,
+    issue_number: int | None = None,
+    issue_title: str | None = None,
+    action: str = "created",
+    mutations: list[str] | None = None,
+    resolved_capabilities: dict | None = None,
+    issues_searched: int | None = None,
+    closest_matches: list[dict] | None = None,
+    duplicate_result: dict | None = None,
+    performed_mutations: list[str] | None = None,
+) -> dict:
+    """Issue #191: composite A-bar for issue-filing final reports."""
+    checks = {
+        "controller_handoff": assess_controller_handoff(
+            report_text, role="issue_filing"
+        ),
+        "issue_reference": assess_issue_filing_issue_reference(
+            report_text,
+            issue_number=issue_number,
+            issue_title=issue_title,
+            action=action,
+        ),
+        "sha_evidence": assess_issue_filing_sha_evidence(report_text),
+        "mutation_capability": assess_issue_filing_mutation_capability(
+            report_text,
+            mutations or performed_mutations,
+            resolved_capabilities,
+        ),
+        "mutation_scope": assess_issue_filing_mutation_scope(
+            report_text,
+            performed_mutations=performed_mutations or mutations,
+        ),
+        "duplicate_summary": assess_issue_filing_duplicate_summary(
+            report_text,
+            issues_searched=issues_searched,
+            closest_matches=closest_matches,
+            duplicate_result=duplicate_result,
+        ),
+    }
+
+    reasons = []
+    downgraded = False
+    for name, result in checks.items():
+        verdict = result.get("verdict")
+        if verdict in ("missing", "incomplete"):
+            downgraded = True
+            reasons.extend(result.get("reasons") or [])
+        elif result.get("downgraded") or not result.get("complete", True):
+            downgraded = True
+            reasons.extend(
+                f"{name}: {r}" for r in (result.get("reasons") or [])
+            )
+
+    grade = "A" if not downgraded else "downgraded"
+    return {
+        "grade": grade,
+        "downgraded": downgraded,
+        "checks": checks,
+        "reasons": reasons,
+        "complete": not downgraded,
+    }
+
+
 def assess_duplicate_search_proof(report_text, matches):
     """#207: reject LLM duplicate summaries that omit known title matches."""
     return issue_duplicate_gate.assess_duplicate_search_proof(

role_session_router.py

@@ -14,6 +14,45 @@ ROUTE_TO_REVIEWER = "route_to_reviewer_session"
 ROUTE_AMBIGUOUS = "ambiguous_task_stop"
 ROUTE_INFRA_STOP = "infra_stop"
 
+_CONFLICT_HEAD = b"<" * 7 + b" "
+_CONFLICT_TAIL = b">" * 7 + b" "
+_CONFLICT_SEPARATOR = b"=" * 7
+
+
+def python_bytes_have_conflict_markers(content: bytes) -> bool:
+    """Return True when *content* contains git merge-conflict marker lines."""
+    for line in content.splitlines():
+        stripped = line.rstrip(b"\r\n")
+        if stripped.startswith(_CONFLICT_HEAD):
+            return True
+        if stripped.startswith(_CONFLICT_TAIL):
+            return True
+        if stripped == _CONFLICT_SEPARATOR:
+            return True
+    return False
+
+
+def skip_python_scan_walk_root(project_root: str, walk_root: str) -> bool:
+    """Skip venv/git/cache and sibling worktrees under orchestration checkout.
+
+    When *project_root* is itself a worktree inside ``branches/``, still scan
+    that tree — do not treat the ``branches`` path segment as a skip signal.
+    """
+    rel = os.path.relpath(walk_root, project_root)
+    if rel == ".":
+        return False
+    head = rel.split(os.sep, 1)[0]
+    if head in ("venv", ".git", ".pytest_cache"):
+        return True
+    if head == "branches":
+        nested = os.path.join(project_root, "branches")
+        if os.path.isdir(nested) and (
+            walk_root == nested or walk_root.startswith(nested + os.sep)
+        ):
+            return True
+    return False
+
+
 REVIEWER_TASKS = frozenset({
     "review_pr",
     "merge_pr",
@@ -259,6 +298,25 @@ def check_author_mutation_after_reviewer_stop(mutation_task: str) -> tuple[bool,
     return True, []
 
 
+def first_conflict_marker_path(project_root: str | None = None) -> str | None:
+    """Return the first .py path containing a git conflict marker, or None."""
+    root_dir = project_root or os.path.dirname(os.path.abspath(__file__))
+    for root, dirs, files in os.walk(root_dir):
+        if skip_python_scan_walk_root(root_dir, root):
+            continue
+        for file in files:
+            if not file.endswith(".py"):
+                continue
+            file_path = os.path.join(root, file)
+            try:
+                with open(file_path, "rb") as f:
+                    if python_bytes_have_conflict_markers(f.read()):
+                        return file_path
+            except OSError:
+                pass
+    return None
+
+
 def check_mid_merge() -> bool:
     """Return True if the repository is mid-merge, mid-rebase, or has conflict markers."""
     project_root = os.path.dirname(os.path.abspath(__file__))
@@ -269,24 +327,4 @@ def check_mid_merge() -> bool:
                 or os.path.exists(os.path.join(git_dir, "rebase-apply"))):
             return True
 
-    # Scan python files for conflict markers
-    conflict_patterns = [
-        b"<" * 7 + b" ",
-        b"=" * 7 + b"\n",
-        b"=" * 7 + b"\r\n",
-        b">" * 7 + b" "
-    ]
-    for root, dirs, files in os.walk(project_root):
-        if any(p in root for p in ("venv", ".git", ".pytest_cache", "branches")):
-            continue
-        for file in files:
-            if file.endswith(".py"):
-                file_path = os.path.join(root, file)
-                try:
-                    with open(file_path, "rb") as f:
-                        content = f.read()
-                        if any(pattern in content for pattern in conflict_patterns):
-                            return True
-                except Exception:
-                    pass
-    return False
+    return first_conflict_marker_path(project_root) is not None

skills/llm-project-workflow/SKILL.md

@@ -53,10 +53,73 @@ Additional issue-first rules:
   owner decision.** Do not create a new repository or a new tracker unless
   explicitly approved by the owner.
 
+## Work Selection Rule for LLMs
+
+Before starting any issue or PR work, acquire or verify a work lease.
+
+Do not begin coding, reviewing, fixing, branching, committing, pushing,
+commenting, or creating a PR until you prove the target is not already being
+worked.
+
+Required checks:
+
+1. List open PRs.
+2. Search for PRs linked to the target issue.
+3. Search local and remote branches for the issue number.
+4. Search registered worktrees for the issue branch.
+5. Check dirty worktrees.
+6. Check active leases or recent handoffs.
+7. Check whether the issue was already completed by a merged PR.
+
+If another active LLM/session owns the lease, stop.
+
+Allowed responses:
+
+- continue as the lease owner,
+- review the existing PR if reviewer capability allows,
+- produce a handoff,
+- request takeover after lease expiry,
+- stop with "work already claimed."
+
+Never create a parallel branch or PR for the same issue unless the old branch
+is proven abandoned and the takeover is recorded.
+
+For Gitea-Tools: `gitea_lock_issue` is the fail-closed lease gate before author
+mutations; `status:in-progress` and claim comments are supporting lease signals.
+Use `review_proofs.classify_issue_for_selection` when reporting fresh issue
+selection (#188).
+
+## Global LLM Worktree Rule
+
+The main project checkout is a stable control checkout. It must stay on the
+configured stable branch: `master`, `main`, or `dev`.
+
+All LLM task work must happen inside the project's `branches/` directory.
+
+Before any mutation, prove:
+
+1. current project root
+2. current working directory
+3. current branch
+4. stable branch for the main checkout
+5. session-owned worktree path under `branches/`
+
+If `cwd` is not inside `branches/`, stop. Do not edit, create, delete, format,
+test-write, commit, merge, rebase, checkout task branches, resolve conflicts,
+or run cleanup.
+
+There are no exceptions for small fixes, docs, tests, cleanup, PR review fixes,
+conflict resolution, or emergencies.
+
+The main checkout may only be used for read-only inspection, fetching,
+stable-branch update after merged PRs, creating `branches/` worktrees, or
+explicit control-checkout repair.
+
 ## B. Isolated worktree rule
 
-**Never implement or review in the main checkout.** The main checkout is for
-orchestration and status only (issue creation, `git status`, creating worktrees).
+**Never implement or review in the main checkout** (Global LLM Worktree Rule).
+The main checkout is for orchestration and status only (issue creation,
+`git status`, creating worktrees) and must remain on the stable branch.
 
 - Each issue gets its own branch worktree under an ignored `branches/` directory.
 - Review work uses a **separate** review worktree, never the author's folder.
@@ -142,7 +205,12 @@ Worktree folder = branch with `/` replaced by `-`
 
 ## E. Start-work workflow
 
-1. Verify the orchestration checkout (right repo, clean tree).
+0. Acquire or verify a work lease (Work Selection Rule) — complete all seven
+   checks before any claim, branch, or PR work.
+0b. Global LLM Worktree Rule — prove project root, `cwd`, branch, main-checkout
+    stable branch, and session-owned `branches/` worktree path. If `cwd` is not
+    under `branches/`, stop before any mutation (no exceptions).
+1. Verify the orchestration checkout (right repo, clean tree, on stable branch).
 2. Fetch/prune: `git fetch <remote> --prune`.
 3. Confirm local `master` equals remote `master` (`git rev-list --left-right --count <remote>/master...master` → `0	0`).
 4. Create/claim the issue (§A).
@@ -394,6 +462,12 @@ Role-specific fields (append to the compact block):
 - review/merge tasks: `Selected PR:`, `Reviewer eligibility:`,
   `Pinned reviewed head:`, `Review decision:`, `Merge result:`,
   `Linked issue status:`, `Cleanup status:`
+- issue-filing tasks (#191): `Issue created or updated:`, `Related issues:`;
+  body must cite exact issue number/title, duplicate-search summary (issues
+  searched, closest matches, why update rejected / new issue justified), full
+  40-char SHAs when citing commits, exact mutation capability per change, and
+  `Only mutation(s):` when a single mutation was performed
+  (`review_proofs.assess_issue_filing_final_report`).
 - author tasks: `Selected issue:`, `Claim/comment status:`,
   `PR number opened:`, `No review/merge:` (explicit confirmation)
 - continuation tasks (#188): `Continuation mode:`, `Existing PR:`,

skills/llm-project-workflow/templates/start-issue.md

@@ -13,6 +13,21 @@ Rules (llm-project-workflow):
 - Do not self-review or self-merge.
 
 Steps:
+0. Work Selection Rule — before any claim, branch, or file edits, acquire or
+   verify a work lease. Required checks: list open PRs; search PRs linked to
+   the target issue; search local/remote branches for the issue number; search
+   registered worktrees for the issue branch; check dirty worktrees; check
+   active leases or recent handoffs; check whether a merged PR already
+   completed the issue. If another session owns the lease, stop (continue only
+   as lease owner, review the existing PR, hand off, request takeover after
+   expiry, or report "work already claimed"). Never open a parallel branch/PR
+   unless the old branch is proven abandoned and takeover is recorded.
+0b. Global LLM Worktree Rule — before any mutation, prove and state: project
+   root; cwd; current branch; stable branch for the main checkout (master/main/dev);
+   session-owned worktree path under branches/. If cwd is not inside branches/,
+   STOP (no exceptions — not for docs, tests, small fixes, review fixes, conflicts,
+   or cleanup). Main checkout is control-only: read-only inspect, fetch, create
+   worktrees, stable-branch update after merge, explicit repair.
 1. Identity Checklist: Before claiming work, verify and state:
    - Required identity/profile for this task: author (allowed to push branches / create PRs)
    - Current authenticated identity (from whoami): <username>

tests/test_agent_temp_artifact_cleanup_docs.py

@@ -0,0 +1,76 @@
+"""Docs checks for agent temp-artifact cleanup guidance (#261).
+
+Failed subagent runs left throwaway helper scripts (e.g.
+``_encode_commit_payload.py``, ``_emit_payload.py``) in the shared working
+tree, polluting ``git status`` and tripping issue-lock / preflight gates.
+These tests keep the cleanup runbook guidance present and the ignore
+patterns in place so stray helpers can never dirty a worktree again.
+"""
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RUNBOOK = REPO_ROOT / "docs" / "llm-workflow-runbooks.md"
+GITIGNORE = REPO_ROOT / ".gitignore"
+
+ARTIFACT_PATTERNS = ("_encode_*.py", "_emit_*.py", "_inline_*.py")
+
+
+def _runbook_text():
+    assert RUNBOOK.is_file(), "missing docs/llm-workflow-runbooks.md"
+    return RUNBOOK.read_text(encoding="utf-8")
+
+
+def _gitignore_text():
+    assert GITIGNORE.is_file(), "missing .gitignore"
+    return GITIGNORE.read_text(encoding="utf-8")
+
+
+def test_runbook_has_agent_temp_artifact_cleanup_section():
+    text = _runbook_text()
+    assert "## Agent temp artifact cleanup" in text, (
+        "runbook lacks an 'Agent temp artifact cleanup' section")
+    assert "#261" in text, "cleanup guidance does not reference issue #261"
+
+
+def test_runbook_names_known_stray_artifacts():
+    text = _runbook_text()
+    for name in ("_encode_commit_payload.py", "_emit_payload.py"):
+        assert name in text, f"runbook does not name stray artifact {name!r}"
+
+
+def test_runbook_covers_all_artifact_patterns():
+    text = _runbook_text()
+    for pattern in ("_encode_*", "_emit_*", "_inline_*"):
+        assert pattern in text, f"runbook does not cover pattern {pattern!r}"
+
+
+def test_runbook_requires_cleanup_after_commit_or_abort():
+    text = _runbook_text().lower()
+    assert "delete" in text or "remove" in text
+    for phase in ("completes", "aborts"):
+        assert phase in text, (
+            f"runbook does not require cleanup when the MCP commit {phase}")
+
+
+def test_runbook_explains_lock_and_preflight_impact():
+    text = _runbook_text().lower()
+    assert "gitea_lock_issue" in text
+    assert "preflight" in text or "pre-flight" in text
+
+
+def test_gitignore_blocks_agent_helper_patterns():
+    lines = [
+        ln.strip() for ln in _gitignore_text().splitlines()
+        if ln.strip() and not ln.strip().startswith("#")
+    ]
+    for pattern in ARTIFACT_PATTERNS:
+        assert pattern in lines, f".gitignore lacks pattern {pattern!r}"
+
+
+def test_no_stray_agent_helpers_in_repo_root():
+    """Acceptance: artifacts stay removed from default worktrees."""
+    stray = [
+        p.name for pattern in ARTIFACT_PATTERNS
+        for p in REPO_ROOT.glob(pattern)
+    ]
+    assert not stray, f"stray agent helper artifacts present: {stray}"

tests/test_external_mcp_registration_docs.py

@@ -1,4 +1,4 @@
-"""Documentation checks for external Jenkins/GlitchTip MCP registration (#151)."""
+"""Documentation checks for external Jenkins/GlitchTip MCP registration (#151/#152)."""
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
@@ -52,11 +52,20 @@ def test_registration_doc_preserves_boundaries():
         "Do not add Jenkins or GlitchTip credentials to the Gitea MCP server",
         "do not add Gitea write credentials to the GlitchTip server",
         "must not expose build trigger tools",
+        "jenkins-write-mcp",
+        "jenkins_mcp.write_server",
         "remains read-only",
     ):
         assert phrase in text
 
 
+def test_registration_doc_separates_jenkins_trigger_from_read_surface():
+    text = _doc_text()
+    assert "jenkins_trigger_build" in text
+    assert "must **not** appear on `jenkins-mcp`" in text
+    assert "not" in text.lower() and "registered by default" in text.lower()
+
+
 def test_registration_doc_has_no_secret_material_or_live_urls():
     text = _doc_text()
     for marker in (
@@ -80,3 +89,14 @@ def test_related_docs_link_registration_doc():
         text = (REPO_ROOT / name).read_text(encoding="utf-8")
         assert "mcp-client-registration.md" in text, (
             f"{name} does not link docs/mcp-client-registration.md")
+
+
+def test_related_docs_keep_jenkins_trigger_off_read_surface():
+    for name in (
+        "docs/safety-model.md",
+        "docs/architecture/jenkins-readonly-build-status-design.md",
+    ):
+        text = (REPO_ROOT / name).read_text(encoding="utf-8")
+        assert "jenkins-write-mcp" in text
+        assert "jenkins_mcp.write_server" in text
+        assert "jenkins-mcp" in text

tests/test_health.py

@@ -5,6 +5,7 @@ import unittest
 from unittest.mock import patch
 
 import role_session_router
+from role_session_router import python_bytes_have_conflict_markers
 from mcp_server import gitea_route_task_session, gitea_resolve_task_capability
 
 _HEALTH_SUBPROCESS_TIMEOUT_SEC = 30
@@ -80,6 +81,20 @@ class TestMCPHealth(unittest.TestCase):
             with self.assertRaises(unittest.SkipTest):
                 _health_test_python()
 
+    def test_conflict_marker_helper_ignores_decorative_equals_border(self):
+        sample = b'banner = """\n===========================================\n"""\n'
+        self.assertFalse(python_bytes_have_conflict_markers(sample))
+
+    def test_conflict_marker_helper_detects_real_markers(self):
+        sample = (
+            b"<" * 7 + b" HEAD\n"
+            b"print('hello')\n"
+            b"=" * 7 + b"\n"
+            b"print('world')\n"
+            b">" * 7 + b" main\n"
+        )
+        self.assertTrue(python_bytes_have_conflict_markers(sample))
+
     def test_startup_conflict_detection(self):
         # Create a Python file with conflict markers constructed dynamically
         with open(self.temp_file, "w") as f:

tests/test_operator_guide.py

@@ -132,7 +132,8 @@ class TestControlPlaneGuide(GuideTestBase):
         rules = g["rules"]
         for key in ("hard_stops", "fail_closed", "head_sha_pinning",
                     "merge_confirmation", "redaction", "separation",
-                    "profile_switching", "identity_verification"):
+                    "profile_switching", "identity_verification",
+                    "work_selection", "global_worktree"):
             self.assertIn(key, rules)
         self.assertIn("MERGE PR", json.dumps(rules["merge_confirmation"]))
         self.assertTrue(rules["hard_stops"])

tests/test_review_proofs.py

@@ -33,6 +33,9 @@ from review_proofs import (  # noqa: E402
     assess_empty_queue_report,
     assess_fresh_issue_selection,
     assess_inventory_completeness,
+    assess_issue_filing_final_report,
+    assess_issue_filing_mutation_capability,
+    assess_issue_filing_sha_evidence,
     assess_issue_selection_final_report,
     assess_queue_target_final_report,
     assess_reviewer_queue_inventory,
@@ -1051,6 +1054,10 @@ class TestControllerHandoff(unittest.TestCase):
         self.assertIn("## Controller Handoff", skill)
         self.assertIn("assess_controller_handoff", skill)
         self.assertIn("issue #182", skill)
+        self.assertIn("## Work Selection Rule for LLMs", skill)
+        self.assertIn("work already claimed", skill)
+        self.assertIn("## Global LLM Worktree Rule", skill)
+        self.assertIn("branches/", skill)
 
     def test_handoff_rejects_none_workspace_mutations_when_local_edits_exist(self):
         # 1. Workspace mutations: none is rejected when local_edits is True
@@ -1925,5 +1932,115 @@ class TestIssueSelectionContinuation(unittest.TestCase):
         self.assertEqual(result["grade"], "A")
 
 
+class TestIssueFilingFinalReport(unittest.TestCase):
+    """Issue #191: issue-filing runs need A-bar final report proofs."""
+
+    ISSUE_TITLE = (
+        "Implement fail-closed continuation mode for issues already "
+        "represented by open PRs"
+    )
+    FULL_SHA = "a4060c5de00f2b1c9e88f4f6f0f3f9a7b2c1d0e9"
+    CAPABILITIES = {
+        "create_issue": {
+            "requested_task": "create_issue",
+            "required_operation_permission": "gitea.issue.create",
+            "allowed_in_current_session": True,
+        },
+    }
+    CLOSEST = [{"number": 183, "title": "Harden author-run reporting", "state": "open"}]
+
+    def _good_report(self, *, sha_line=None):
+        lines = [
+            "Created Gitea-Tools #189 — "
+            f"`{self.ISSUE_TITLE}`",
+            "Duplicate check: searched 12 open issues.",
+            "Closest existing: #183 — Harden author-run reporting "
+            "(update rejected — different scope).",
+            "Why new issue justified: continuation mode is distinct from #183.",
+            "Only mutation: issue creation (gitea.issue.create).",
+            "Confirm no labels, comments, PRs, reviews, merges, or closes.",
+            "## Controller Handoff",
+            "- Task: file issue",
+            "- Repo: Scaled-Tech-Consulting/Gitea-Tools",
+            "- Role: author",
+            "- Identity: prgs-author",
+            "- Issue/PR: #189",
+            "- Branch/SHA: n/a",
+            "- Files changed: none",
+            "- Validation: duplicate gate + create_issue capability resolved",
+            "- Mutations: create_issue via gitea.issue.create",
+            "- Workspace mutations: none",
+            "- Current status: issue created",
+            "- Blockers: none",
+            "- Next: implementation",
+            "- Safety: no review/merge",
+            "- Issue created or updated: created #189",
+            "- Related issues: #183, #188",
+        ]
+        if sha_line:
+            lines.insert(4, sha_line)
+        return "\n".join(lines)
+
+    def test_complete_issue_filing_report_earns_a(self):
+        result = assess_issue_filing_final_report(
+            self._good_report(),
+            issue_number=189,
+            issue_title=self.ISSUE_TITLE,
+            action="created",
+            mutations=["create_issue"],
+            resolved_capabilities=self.CAPABILITIES,
+            issues_searched=12,
+            closest_matches=self.CLOSEST,
+            performed_mutations=["create_issue"],
+        )
+        self.assertEqual(result["grade"], "A")
+        self.assertFalse(result["downgraded"])
+
+    def test_missing_controller_handoff_downgrades(self):
+        report = self._good_report().replace("## Controller Handoff", "")
+        result = assess_issue_filing_final_report(
+            report,
+            issue_number=189,
+            issue_title=self.ISSUE_TITLE,
+            mutations=["create_issue"],
+            resolved_capabilities=self.CAPABILITIES,
+            issues_searched=12,
+            performed_mutations=["create_issue"],
+        )
+        self.assertTrue(result["downgraded"])
+
+    def test_abbreviated_sha_downgrades(self):
+        result = assess_issue_filing_sha_evidence(
+            f"old head: {self.FULL_SHA[:7]}"
+        )
+        self.assertTrue(result["downgraded"])
+
+    def test_mutation_without_capability_proof_downgrades(self):
+        report = self._good_report().replace("gitea.issue.create", "allowed")
+        result = assess_issue_filing_mutation_capability(
+            report,
+            ["create_issue"],
+            self.CAPABILITIES,
+        )
+        self.assertTrue(result["downgraded"])
+
+    def test_label_mutation_without_label_proof_downgrades(self):
+        caps = {
+            "set_issue_labels": {
+                "requested_task": "set_issue_labels",
+                "required_operation_permission": "gitea.issue.comment",
+                "allowed_in_current_session": True,
+            },
+        }
+        report = "\n".join([
+            "Updated labels with gitea.issue.comment capability resolved.",
+            "Only mutations: set_issue_labels",
+        ])
+        result = assess_issue_filing_mutation_capability(
+            report, ["set_issue_labels"], caps
+        )
+        self.assertTrue(result["downgraded"])
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_role_session_router.py

@@ -204,5 +204,49 @@ class TestRoleSessionRouter(unittest.TestCase):
         self.assertTrue(complete["complete"])
 
 
+class TestCheckMidMerge(unittest.TestCase):
+    def test_skip_scan_walk_root_skips_sibling_worktrees_only(self):
+        worktree_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        main_root = os.path.dirname(os.path.dirname(worktree_root))
+        self.assertFalse(
+            role_session_router.skip_python_scan_walk_root(
+                main_root, main_root
+            )
+        )
+        self.assertTrue(
+            role_session_router.skip_python_scan_walk_root(
+                main_root, os.path.join(main_root, "branches", "fix-issue-1")
+            )
+        )
+        self.assertFalse(
+            role_session_router.skip_python_scan_walk_root(
+                worktree_root, worktree_root
+            )
+        )
+        self.assertFalse(
+            role_session_router.skip_python_scan_walk_root(
+                worktree_root, os.path.join(worktree_root, "tests")
+            )
+        )
+
+    def test_decorative_equals_banner_is_not_mid_merge(self):
+        self.assertFalse(role_session_router.check_mid_merge())
+
+    def test_python_bytes_have_conflict_markers_rejects_decorative_equals(self):
+        banner = b"===========================================\n"
+        self.assertFalse(role_session_router.python_bytes_have_conflict_markers(banner))
+
+    def test_python_bytes_have_conflict_markers_detects_real_markers(self):
+        self.assertTrue(
+            role_session_router.python_bytes_have_conflict_markers(b"<<<<<<< HEAD\n")
+        )
+        self.assertTrue(
+            role_session_router.python_bytes_have_conflict_markers(b"=======\n")
+        )
+        self.assertTrue(
+            role_session_router.python_bytes_have_conflict_markers(b">>>>>>> topic\n")
+        )
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_runtime_clarity.py

@@ -95,9 +95,13 @@ class TestRuntimeClarity(unittest.TestCase):
     # -------------------------------------------------------------------------
     # gitea_get_runtime_context
     # -------------------------------------------------------------------------
+    @patch(
+        "mcp_server.assess_preflight_status",
+        return_value={"preflight_ready": True, "preflight_block_reasons": []},
+    )
     @patch("mcp_server.api_request", return_value={"login": "author-user"})
     @patch("mcp_server.get_auth_header", return_value="token author-pass")
-    def test_get_runtime_context_author(self, _auth, _api):
+    def test_get_runtime_context_author(self, _auth, _api, _preflight):
         with patch.dict(os.environ, self._env("author-profile"), clear=True):
             ctx = mcp_server.gitea_get_runtime_context(remote="dadeschools")
         self.assertEqual(ctx["active_profile"], "author-profile")
@@ -110,10 +114,26 @@ class TestRuntimeClarity(unittest.TestCase):
         self.assertEqual(ctx["suggested_fix"], "reviewer namespace")
         self.assertIn("does not permit review or merge", ctx["review_merge_blocked_reasons"][0])
         self.assertIn("Switch to the reviewer MCP session", ctx["safe_next_action"])
+        caps = ctx["session_capabilities"]
+        self.assertTrue(caps["can_author_prs"])
+        self.assertFalse(caps["can_create_issues"])
+        self.assertFalse(caps["can_comment_on_issues"])
+        self.assertFalse(caps["can_review_prs"])
+        self.assertFalse(caps["can_merge_prs"])
+        self.assertTrue(caps["issue_comment_not_implied_by_pr_comment"])
+        merge_entry = next(
+            t for t in caps["task_capabilities"] if t["task"] == "merge_pr"
+        )
+        self.assertFalse(merge_entry["allowed_in_current_session"])
+        self.assertIn("reviewer-profile", merge_entry["matching_configured_profiles"])
 
+    @patch(
+        "mcp_server.assess_preflight_status",
+        return_value={"preflight_ready": True, "preflight_block_reasons": []},
+    )
     @patch("mcp_server.api_request", return_value={"login": "reviewer-user"})
     @patch("mcp_server.get_auth_header", return_value="token reviewer-pass")
-    def test_get_runtime_context_reviewer(self, _auth, _api):
+    def test_get_runtime_context_reviewer(self, _auth, _api, _preflight):
         with patch.dict(os.environ, self._env("reviewer-profile"), clear=True):
             ctx = mcp_server.gitea_get_runtime_context(remote="dadeschools")
         self.assertEqual(ctx["active_profile"], "reviewer-profile")
@@ -121,6 +141,15 @@ class TestRuntimeClarity(unittest.TestCase):
         self.assertTrue(ctx["review_merge_allowed"])
         self.assertEqual(ctx["suggested_fix"], "none")
         self.assertEqual(ctx["safe_next_action"], "None; ready for operations.")
+        caps = ctx["session_capabilities"]
+        self.assertFalse(caps["can_author_prs"])
+        self.assertFalse(caps["can_create_issues"])
+        self.assertFalse(caps["can_review_prs"])
+        self.assertTrue(caps["can_merge_prs"])
+        merge_entry = next(
+            t for t in caps["task_capabilities"] if t["task"] == "merge_pr"
+        )
+        self.assertTrue(merge_entry["allowed_in_current_session"])
 
     # -------------------------------------------------------------------------
     # gitea_list_profiles