code-coordinator 0.5.545__tar.gz → 0.5.547__tar.gz

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.545
+Version: 0.5.547
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -33,6 +33,8 @@ Requires-Dist: openpyxl>=3.1; extra == "reports-xlsx"
 Provides-Extra: tui-pty
 Requires-Dist: pyte>=0.8; extra == "tui-pty"
 Requires-Dist: pywinpty>=2.0; sys_platform == "win32" and extra == "tui-pty"
+Provides-Extra: win-native
+Requires-Dist: comtypes>=1.2; sys_platform == "win32" and extra == "win-native"
 Provides-Extra: all
 Requires-Dist: code-coordinator[server]; extra == "all"
 Requires-Dist: code-coordinator[reports-xlsx]; extra == "all"

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.545
+Version: 0.5.547
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -33,6 +33,8 @@ Requires-Dist: openpyxl>=3.1; extra == "reports-xlsx"
 Provides-Extra: tui-pty
 Requires-Dist: pyte>=0.8; extra == "tui-pty"
 Requires-Dist: pywinpty>=2.0; sys_platform == "win32" and extra == "tui-pty"
+Provides-Extra: win-native
+Requires-Dist: comtypes>=1.2; sys_platform == "win32" and extra == "win-native"
 Provides-Extra: all
 Requires-Dist: code-coordinator[server]; extra == "all"
 Requires-Dist: code-coordinator[reports-xlsx]; extra == "all"

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/code_coordinator.egg-info/SOURCES.txt

@@ -169,6 +169,7 @@ coord/uat_checks.py
 coord/usage.py
 coord/usage_limits.py
 coord/usage_rollup.py
+coord/win_native_driver.py
 coord/worker_events.py
 coord/agents/opencode/.gitignore
 coord/agents/opencode/routing.jsonc
@@ -867,6 +868,7 @@ tests/test_usage_rollup.py
 tests/test_venv_live_install_2121.py
 tests/test_version_single_source.py
 tests/test_watch.py
+tests/test_win_native_driver.py
 tests/test_windows_job_is_a_real_gate_2000.py
 tests/test_worker_env_venv_isolation.py
 tests/test_worker_events.py

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/code_coordinator.egg-info/requires.txt

@@ -39,3 +39,8 @@ pyte>=0.8
 
 [tui-pty:sys_platform == "win32"]
 pywinpty>=2.0
+
+[win-native]
+
+[win-native:sys_platform == "win32"]
+comtypes>=1.2

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/code_coordinator.egg-info/scm_file_list.json

@@ -296,6 +296,7 @@
     "coord/usage.py",
     "coord/usage_limits.py",
     "coord/usage_rollup.py",
+    "coord/win_native_driver.py",
     "coord/worker_events.py",
     "coordinator.example.yml",
     "deploy/coord-agent.service",
@@ -894,6 +895,7 @@
     "tests/test_venv_live_install_2121.py",
     "tests/test_version_single_source.py",
     "tests/test_watch.py",
+    "tests/test_win_native_driver.py",
     "tests/test_windows_job_is_a_real_gate_2000.py",
     "tests/test_worker_env_venv_isolation.py",
     "tests/test_worker_events.py",

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.545",
+  "tag": "0.5.547",
   "distance": 0,
-  "node": "g43201054b1bb8cd75c1a632db8f016f315da8957",
+  "node": "ga4436afc4ebb3ad2bce2aaa13d348ba57d117902",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-30"

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/coord/acceptance_drivers.py

@@ -7,12 +7,14 @@ is the one seam that varies per medium — TUI (quadraui ``TuiDriver``), CLI
 *run* a repo's declared acceptance suite and *parse* its raw output into a
 normalized list of ``{"id": str, "status": "pass"|"fail"|"skip", "message":
 str}`` dicts (``cli-pytest`` additionally carries ``"expected"``/``"got"``
-on a failing test — see :func:`parse_pytest_junit_xml`). ``tui-tuidriver``,
-``cli-pytest`` (#1125), ``web-playwright`` (#1539), ``terraform``
-(#3232), and ``tui-pty`` (#3483) are implemented; other ``kind`` values are
-declared in ``coordinator.yml`` (see :class:`coord.config.AcceptanceConfig`)
-but rejected here with a clear "not yet implemented" error until their
-issues land (native).
+on a failing test — see :func:`parse_pytest_junit_xml`; ``win-native``
+additionally carries ``"capture_b64"`` on a failing step — see
+:func:`_run_win_native`). ``tui-tuidriver``, ``cli-pytest`` (#1125),
+``web-playwright`` (#1539), ``terraform`` (#3232), ``tui-pty`` (#3483), and
+``win-native`` (#3484) are implemented; other ``kind`` values are declared
+in ``coordinator.yml`` (see :class:`coord.config.AcceptanceConfig`) but
+rejected here with a clear "not yet implemented" error until their issues
+land.
 
 ``cli-pytest`` parses pytest's built-in ``--junit-xml`` report (a core
 pytest flag, not a plugin — no extra dependency required in the driven
@@ -61,6 +63,23 @@ seam: it resolves the smoke spec from the driver's ``entrypoint:`` (the
 ``tui-pty`` analogue of ``tui-tuidriver``'s own entrypoint-as-sealed-file
 convention) and hands off to :func:`coord.tui_pty_driver.run_smoke_spec`.
 
+``win-native`` (#3484, the Win32-native tier below ``tui-pty``) launches the
+driven repo's real compiled Windows exe — a GUI app in its own window, or a
+TUI binary hosted inside a real Windows Terminal/conhost window — and drives
+it with real ``SendInput``/``PostMessage`` input while probing real OS
+state: ``GetMenu``, ``WM_NCHITTEST``, and the UI Automation tree, with a
+``PrintWindow`` capture attached to every failing step as evidence. On
+2026-09-29 vimcode's window had a real native menu (``GetMenu`` -> 7 items)
+that was completely invisible because a custom caption left 0 px of
+non-client area, and no min/max/close — both passed every ``tui-tuidriver``/
+``tui-pty`` test, because neither ever asks the real OS those questions.
+All of the spec parsing, the Win32/UIA call seam, and the step executor live
+in :mod:`coord.win_native_driver` — see that module's docstring for the spec
+format. This adapter (:func:`_run_win_native`) is the same thin seam
+:func:`_run_tui_pty` is: it resolves the native spec from the driver's
+``entrypoint:`` and hands off to
+:func:`coord.win_native_driver.run_native_spec`.
+
 ``terraform`` additionally runs a deterministic policy gate (#3234, epic
 #3230 child 3) whenever the driven repo has opted in by carrying the
 convention files: ``tflint`` (rule-based HCL/provider checks — pinned
@@ -91,7 +110,10 @@ from pathlib import Path
 # Driver kinds this module knows how to run. Keep in sync with the adapters
 # implemented below — a kind can be *declared* in coordinator.yml ahead of its
 # adapter landing, but running it must fail loudly rather than silently no-op.
-SUPPORTED_KINDS = ("tui-tuidriver", "cli-pytest", "web-playwright", "terraform", "tui-pty")
+SUPPORTED_KINDS = (
+    "tui-tuidriver", "cli-pytest", "web-playwright", "terraform", "tui-pty",
+    "win-native",
+)
 
 # #2748 (IL-2): driver kinds whose `run` produces a real pass/fail verdict
 # but NOT yet a deterministic one, because an input they depend on hasn't
@@ -268,11 +290,12 @@ def run_driver(
     into a driver's own "wrote no report" crash message.
 
     *entrypoint* (``AcceptanceDriverConfig.entrypoint``) is only consulted
-    by ``tui-pty`` (#3483) — it names the repo-root-relative smoke-spec YAML
-    file (see :mod:`coord.tui_pty_driver`), the same way ``entrypoint``
-    already names ``tui-tuidriver``'s sealed Rust acceptance file for
-    :func:`coord.acceptance.acceptance_root_for_driver`. Every other kind
-    ignores it.
+    by ``tui-pty`` (#3483) and ``win-native`` (#3484) — it names the
+    repo-root-relative smoke/native-spec YAML file (see
+    :mod:`coord.tui_pty_driver`/:mod:`coord.win_native_driver`), the same
+    way ``entrypoint`` already names ``tui-tuidriver``'s sealed Rust
+    acceptance file for :func:`coord.acceptance.acceptance_root_for_driver`.
+    Every other kind ignores it.
     """
     if kind not in SUPPORTED_KINDS:
         raise DriverError(
@@ -294,6 +317,8 @@ def run_driver(
         return _run_terraform(run_command, cwd, timeout=timeout)
     if kind == "tui-pty":
         return _run_tui_pty(run_command, cwd, entrypoint, timeout=timeout)
+    if kind == "win-native":
+        return _run_win_native(run_command, cwd, entrypoint, timeout=timeout)
     return _run_generic(run_command, cwd, timeout=timeout)
 
 
@@ -659,6 +684,67 @@ def _run_tui_pty(run_command: str, cwd: str, entrypoint: str, *, timeout: int) -
     return DriverResult(exit_code=exit_code, tests=tests, raw_output=raw_output)
 
 
+def _run_win_native(run_command: str, cwd: str, entrypoint: str, *, timeout: int) -> DriverResult:
+    """The ``win-native`` shape (#3484): *run_command* is the shell command
+    that launches the driven repo's real compiled Windows exe — the
+    platform-neutral native spec YAML that drives it lives at *entrypoint*
+    (repo-root-relative), the ``win-native`` analogue of ``tui-pty``'s own
+    ``entrypoint:`` convention (see :func:`_run_tui_pty` and the module
+    docstring).
+
+    All of the real Win32/UIA calls and the step executor live in
+    :mod:`coord.win_native_driver` — this function is the thin seam that
+    resolves *entrypoint* to a spec file and calls
+    :func:`coord.win_native_driver.run_native_spec`, then folds its
+    normalized ``tests`` list (each failing entry optionally carrying a
+    ``capture_b64`` ``PrintWindow`` snapshot) into a :class:`DriverResult`
+    the same way :func:`_run_tui_pty` does.
+
+    Raises :class:`DriverError` — never a bare exception — for a missing
+    ``entrypoint:``, a spec file that doesn't exist, or a malformed spec
+    (an invalid-YAML/unknown-step-type
+    :class:`coord.win_native_driver.WinNativeSpecError`). A process that
+    never launches, a window that never appears, or a failed probe do NOT
+    raise here — :func:`coord.win_native_driver.run_native_spec` folds those
+    into individual failing entries in ``tests`` instead.
+    """
+    from coord.win_native_driver import (  # noqa: PLC0415 — see module docstring on the deferred import
+        WinNativeRuntimeError,
+        WinNativeSpecError,
+        run_native_spec,
+    )
+
+    if not entrypoint:
+        raise DriverError(
+            "win-native driver requires an `entrypoint:` naming the native "
+            "spec YAML file (repo-root-relative) — none configured"
+        )
+    spec_path = Path(cwd) / entrypoint
+    if not spec_path.is_file():
+        raise DriverError(f"win-native spec not found: {spec_path}")
+
+    try:
+        spec_text = spec_path.read_text()
+    except OSError as e:
+        raise DriverError(f"win-native spec could not be read: {spec_path}: {e}") from e
+
+    try:
+        tests = run_native_spec(
+            spec_text, launch_command=run_command, cwd=cwd, timeout=timeout,
+        )
+    except WinNativeSpecError as e:
+        raise DriverError(f"win-native spec is invalid: {e}") from e
+    except WinNativeRuntimeError as e:
+        raise DriverError(f"win-native driver could not run: {e}") from e
+
+    exit_code = 0 if tests and all(t.get("status") != "fail" for t in tests) else 1
+    raw_output = "\n".join(
+        f"{t.get('status')}: {t.get('id')} {t.get('message', '')}".rstrip()
+        for t in tests
+    )
+    return DriverResult(exit_code=exit_code, tests=tests, raw_output=raw_output)
+
+
 def parse_test_output(output: str) -> list[dict]:
     """Parse a driver's stdout into normalized ``{"id", "status", "message"}``.
 

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/coord/config.py

@@ -169,6 +169,13 @@ class ConfigError(Exception):
     """Raised when coordinator.yml is missing, malformed, or fails validation."""
 
 
+# #3489: default repo-relative directory a repo's shared, backend-neutral
+# conformance scenarios live in when `reviews.require_shared_scenario`
+# opts a repo in with `true` rather than an explicit path string. Matches
+# quadraui's actual `tests/conformance/scenarios/*.scn.json` layout.
+DEFAULT_SHARED_SCENARIO_DIR = "tests/conformance/scenarios"
+
+
 @dataclass
 class HooksConfig:
     on_round_complete: list[str] = field(default_factory=list)
@@ -210,6 +217,35 @@ class ReviewsConfig:
         "Check for platform-specific code in shared/cross-platform paths",
     ])
     repo_overrides: dict[str, list[str]] = field(default_factory=dict)
+    # #3489: opt-in review rule — "if it works in one backend it works in
+    # all" only holds when behaviour is tested ONCE, through a shared,
+    # backend-neutral scenario suite every backend runs (quadraui's
+    # `tests/conformance/scenarios/*.scn.json` through `ConformanceDriver`).
+    # Without this, reviewers happily accept a single-backend test and the
+    # suites go lopsided — vimcode's driver suites are ~277 GTK / ~159 TUI /
+    # ~22 macOS / ~9 Windows `#[test]`s, and quadraui has only 19 shared
+    # scenarios to date.
+    #
+    # Keyed by repo name -> the repo-relative directory its shared scenarios
+    # live in (e.g. `tests/conformance/scenarios`). A repo absent from this
+    # mapping has NOT opted in and the rule is completely inert for it —
+    # `coord.review.diff_missing_shared_scenario` returns False before
+    # looking at the diff at all, so repos that don't declare a conformance
+    # suite see no behavior change from this feature existing. `true` (bool)
+    # is shorthand for `_DEFAULT_SHARED_SCENARIO_DIR` (parsed in
+    # `_parse_reviews`); an explicit string names a repo-specific location.
+    #
+    # Enforcement mirrors CLAUDE.md's existing black-box-coverage rule
+    # (`coord.review.diff_missing_test_coverage`, #2192): a free, path-only,
+    # non-blocking static nudge feeds the reviewer's own judgment via
+    # `build_review_briefing`'s prompt text, which names the rule and the
+    # repo's scenario directory and instructs the reviewer to request-changes
+    # when a behaviour-changing diff adds only a single-backend test. Pure
+    # refactors / internal-only changes stay exempt, the same way CLAUDE.md's
+    # black-box rule exempts them — honored the same way, by the diff simply
+    # touching no user-visible source, or by the worker's own stated
+    # refactor/internal-only claim in `completion_summary`.
+    require_shared_scenario: dict[str, str] = field(default_factory=dict)
     # Flood guard (incident 2026-06-08): bound *bulk* review dispatch so a
     # backlog "unmasking" (e.g. removing a gate that had been suppressing
     # reviews) can't fire hundreds of metered `claude -p` reviews in one pass.
@@ -3523,6 +3559,35 @@ def _parse_reviews(
                 f"reviews.repo_overrides[{repo_name}] must be a list of strings"
             )
     cfg.repo_overrides = overrides
+
+    # #3489: require_shared_scenario — opt-in per repo, keyed by repo name.
+    # Value is either `true` (shorthand for DEFAULT_SHARED_SCENARIO_DIR) or
+    # an explicit non-empty string naming the repo-relative scenario
+    # directory. A repo absent from this mapping is NOT opted in.
+    shared_scenario_raw = raw.get("require_shared_scenario", {}) or {}
+    if not isinstance(shared_scenario_raw, dict):
+        raise ConfigError(
+            "reviews.require_shared_scenario must be a mapping of repo → "
+            "scenario dir (string) or true"
+        )
+    shared_scenario: dict[str, str] = {}
+    for repo_name, value in shared_scenario_raw.items():
+        if not isinstance(repo_name, str):
+            raise ConfigError("reviews.require_shared_scenario keys must be repo names")
+        if repo_name not in repo_names:
+            raise ConfigError(
+                f"reviews.require_shared_scenario references unknown repo: {repo_name!r}"
+            )
+        if value is True:
+            shared_scenario[repo_name] = DEFAULT_SHARED_SCENARIO_DIR
+        elif isinstance(value, str) and value.strip():
+            shared_scenario[repo_name] = value.strip()
+        else:
+            raise ConfigError(
+                f"reviews.require_shared_scenario[{repo_name}] must be `true` "
+                "or a non-empty string (the repo-relative scenario directory)"
+            )
+    cfg.require_shared_scenario = shared_scenario
     return cfg
 
 

{code_coordinator-0.5.545 → code_coordinator-0.5.547}/coord/review.py

@@ -13,6 +13,12 @@ Public entry points:
   for a repo's `reviews.repo_overrides`. Shared with `coord.dispatch.dispatch`
   so the worker's briefing and the reviewer's briefing are graded/shown the
   exact same rule text, and can never drift apart.
+- `diff_missing_shared_scenario(...)`, `shared_scenario_focus_lines(...)` —
+  #3489: opt-in per-repo rule (`reviews.require_shared_scenario`) — a
+  behaviour-changing diff in an opted-in repo must add/extend a shared,
+  backend-neutral scenario (or Tier-2 smoke-spec step), not only a
+  single-backend test. Same free/non-blocking-nudge shape as
+  `diff_missing_test_coverage` below; inert for a repo that hasn't opted in.
 - `build_review_briefing(...)`  — assemble the reviewer's prompt from the
   repo's CLAUDE.md, the generic checklist, any repo-specific overrides
   (`repo_focus_lines`), and the worker's own claims (completion summary +
@@ -1719,6 +1725,153 @@ def diff_missing_test_coverage(diff_text: str | None) -> bool:
     return not any(_is_test_path(p) for p in paths)
 
 
+# ── #3489: opt-in "shared (backend-neutral) scenario" review rule ──────────
+#
+# "If it works in one backend it works in all" only holds when behaviour is
+# tested ONCE, through the shared scenario suite every backend runs
+# (quadraui's `tests/conformance/scenarios/*.scn.json` through
+# `ConformanceDriver`). Without this, reviewers happily accept a
+# single-backend test and the suites go lopsided (vimcode: ~277 GTK / ~159
+# TUI / ~22 macOS / ~9 Windows `#[test]`s; quadraui: only 19 shared
+# scenarios).
+#
+# Same shape as `diff_missing_test_coverage` (#2192) immediately above: a
+# free, path-only, non-blocking static check. It never gates dispatch by
+# itself — enforcement is the reviewer's own judgment, driven by the prompt
+# text `shared_scenario_focus_lines` appends to `build_review_briefing`,
+# naming the rule and instructing a `request-changes` verdict when it fires.
+# Inert (returns False unconditionally) for a repo absent from
+# `reviews.require_shared_scenario` — the per-repo opt-in guard.
+
+_REFACTOR_EXEMPTION_MARKERS = (
+    "pure refactor",
+    "internal-only",
+    "internal only",
+    "no user-visible",
+    "no behavior change",
+    "no behaviour change",
+)
+
+
+def _states_refactor_exemption(completion_summary: str | None) -> bool:
+    """Does the worker's own *completion_summary* state the CLAUDE.md "pure
+    refactor / internal-only" exemption (#3489)?
+
+    A path-only heuristic cannot tell a genuine behavior-preserving refactor
+    of shipped source from a real behavior change — the same limitation
+    `diff_missing_test_coverage`'s docstring notes. The worker's own stated
+    claim (#3112's `completion_summary` — the one surface a worker can
+    actually make this claim on) is the only signal available to a pure
+    function here; the reviewer still verifies the claim against the diff,
+    the same way it verifies any other claim in the "Worker's own claims"
+    section.
+    """
+    text = (completion_summary or "").lower()
+    return any(marker in text for marker in _REFACTOR_EXEMPTION_MARKERS)
+
+
+def _is_shared_scenario_path(path: str, scenario_dir: str) -> bool:
+    """Does *path* look like a shared/backend-neutral scenario (or Tier-2
+    smoke-spec step) for *scenario_dir* (#3489)?
+
+    Matches anything under *scenario_dir* itself, plus any path with a
+    `smoke-spec/` segment — the issue's explicit "or a Tier-2 smoke-spec
+    step" carve-out, which need not live under the same directory.
+    """
+    normalized_dir = scenario_dir.strip("/").lower()
+    lower = path.lower()
+    if normalized_dir and (lower == normalized_dir or lower.startswith(normalized_dir + "/")):
+        return True
+    return "/smoke-spec/" in f"/{lower}"
+
+
+def diff_missing_shared_scenario(
+    diff_text: str | None,
+    *,
+    repo_name: str,
+    reviews_cfg: ReviewsConfig,
+    completion_summary: str | None = None,
+) -> bool:
+    """#3489: True when *diff_text* changes user-visible behavior in a repo
+    that has opted into `reviews.require_shared_scenario` but adds/extends
+    no shared, backend-neutral scenario (or Tier-2 smoke-spec step) — e.g.
+    only a single-backend test, or no test at all.
+
+    Inert (always False) when *repo_name* hasn't opted in
+    (`reviews_cfg.require_shared_scenario`), when *diff_text* is empty, when
+    the diff touches no user-visible source (CLAUDE.md's internal-only
+    exemption, same granularity as `diff_missing_test_coverage`), or when
+    *completion_summary* states the pure-refactor/internal-only exemption
+    (`_states_refactor_exemption`).
+    """
+    scenario_dir = reviews_cfg.require_shared_scenario.get(repo_name)
+    if not scenario_dir:
+        return False
+    if not diff_text or not diff_text.strip():
+        return False
+    if _states_refactor_exemption(completion_summary):
+        return False
+    paths = github_ops.diff_file_paths(diff_text)
+    if not any(_is_user_visible_path(p) for p in paths):
+        return False
+    return not any(_is_shared_scenario_path(p, scenario_dir) for p in paths)
+
+
+def shared_scenario_focus_lines(
+    reviews_cfg: ReviewsConfig,
+    repo_name: str,
+    *,
+    diff_text: str | None = None,
+    completion_summary: str | None = None,
+) -> list[str]:
+    """Return the ``## Shared scenario coverage`` briefing section for
+    *repo_name*'s `reviews.require_shared_scenario` opt-in (#3489), or
+    ``[]`` when the repo hasn't opted in.
+
+    Mirrors `repo_focus_lines`'s "inert unless configured" shape (#3112) so
+    this rule changes nothing — not even prompt text — for a repo that
+    hasn't declared a conformance scenario suite. When configured, always
+    names the rule and the repo's scenario directory; when the free
+    `diff_missing_shared_scenario` check also fires for *diff_text*/
+    *completion_summary*, a mandatory ``request-changes`` instruction is
+    appended, naming the rule the same way the sealed-path tamper banner
+    names itself.
+    """
+    scenario_dir = reviews_cfg.require_shared_scenario.get(repo_name)
+    if not scenario_dir:
+        return []
+    lines = [
+        "",
+        "## Shared scenario coverage (`reviews.require_shared_scenario`, #3489)",
+        "",
+        "This repo opts into the shared-scenario review rule: a "
+        "behaviour-changing diff must add or extend a backend-neutral "
+        f"scenario under `{scenario_dir}/` (or a Tier-2 smoke-spec step) — "
+        "not only a single-backend test. \"If it works in one backend it "
+        "works in all\" only holds when behaviour is tested once, through "
+        "the shared scenario suite every backend runs. Pure refactors / "
+        "internal-only changes stay exempt — say so in the PR if that "
+        "applies, the same way CLAUDE.md's black-box rule is honored.",
+    ]
+    if diff_missing_shared_scenario(
+        diff_text,
+        repo_name=repo_name,
+        reviews_cfg=reviews_cfg,
+        completion_summary=completion_summary,
+    ):
+        lines.append("")
+        lines.append(
+            f"**This diff changes user-visible behavior but touches no file "
+            f"under `{scenario_dir}/` (and no Tier-2 smoke-spec step), and "
+            "claims no pure-refactor/internal-only exemption. Per the "
+            "`require_shared_scenario` rule, you MUST `request-changes`, "
+            "naming this rule — unless you independently determine this "
+            "diff really is a pure refactor / internal-only change the "
+            "static check couldn't see.**"
+        )
+    return lines
+
+
 def repo_focus_lines(reviews_cfg: ReviewsConfig, repo_name: str) -> list[str]:
     """Return the ``### Repo-specific focus`` block for *repo_name*, or ``[]``
     if the repo has no ``reviews.repo_overrides`` configured (#3112).
@@ -2002,6 +2155,14 @@ def build_review_briefing(
         lines.append("- Any security issues (injection, auth bypass, credential exposure)?")
 
     lines.extend(repo_focus_lines(reviews_cfg, repo_name))
+    lines.extend(
+        shared_scenario_focus_lines(
+            reviews_cfg,
+            repo_name,
+            diff_text=diff_text,
+            completion_summary=completion_summary,
+        )
+    )
 
     if reviews_cfg.reviewer_prompt.strip():
         lines.append("")
@@ -3398,6 +3559,25 @@ def dispatch_review(
                 completed.assignment_id,
             )
 
+        # #3489: same free/non-blocking shape as the #2192 nudge above, for
+        # the opt-in "shared (backend-neutral) scenario" rule — inert (never
+        # logs) for a repo absent from `reviews.require_shared_scenario`.
+        if diff_missing_shared_scenario(
+            full_diff_text,
+            repo_name=repo.name,
+            reviews_cfg=config.reviews,
+            completion_summary=completed.completion_summary,
+        ):
+            log.warning(
+                "[review] %s: repo %r opted into reviews.require_shared_scenario "
+                "and this diff changes user-visible behavior but adds/extends no "
+                "shared scenario under %r (free static check, non-blocking; "
+                "dispatching review as normal — the reviewer's briefing names "
+                "the rule)",
+                completed.assignment_id, repo.name,
+                config.reviews.require_shared_scenario.get(repo.name),
+            )
+
         # #1811: does the resolved review provider share the worker's model
         # family? ``completed.provider_name`` is the *resolved* name recorded at
         # work-dispatch time (spec > repo > providers.default); ``None`` means a