code-coordinator 0.5.544__tar.gz → 0.5.546__tar.gz

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.544
+Version: 0.5.546
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -30,12 +30,17 @@ Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
 Provides-Extra: reports-xlsx
 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: all
 Requires-Dist: code-coordinator[server]; extra == "all"
 Requires-Dist: code-coordinator[reports-xlsx]; extra == "all"
+Requires-Dist: code-coordinator[tui-pty]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: code-coordinator[server]; extra == "dev"
 Requires-Dist: code-coordinator[reports-xlsx]; extra == "dev"
+Requires-Dist: code-coordinator[tui-pty]; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-xdist>=3.5; extra == "dev"

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.544
+Version: 0.5.546
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -30,12 +30,17 @@ Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
 Provides-Extra: reports-xlsx
 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: all
 Requires-Dist: code-coordinator[server]; extra == "all"
 Requires-Dist: code-coordinator[reports-xlsx]; extra == "all"
+Requires-Dist: code-coordinator[tui-pty]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: code-coordinator[server]; extra == "dev"
 Requires-Dist: code-coordinator[reports-xlsx]; extra == "dev"
+Requires-Dist: code-coordinator[tui-pty]; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-xdist>=3.5; extra == "dev"

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/code_coordinator.egg-info/SOURCES.txt

@@ -163,6 +163,7 @@ coord/test_author.py
 coord/test_chat.py
 coord/test_orchestrator.py
 coord/test_report.py
+coord/tui_pty_driver.py
 coord/tui_release.py
 coord/uat_checks.py
 coord/usage.py
@@ -858,6 +859,7 @@ tests/test_throwaway_vm.py
 tests/test_tmux_host.py
 tests/test_tmux_session.py
 tests/test_transcript_floor.py
+tests/test_tui_pty_driver.py
 tests/test_uat_checks.py
 tests/test_usage.py
 tests/test_usage_limits.py

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/code_coordinator.egg-info/requires.txt

@@ -9,10 +9,12 @@ tzdata
 [all]
 code-coordinator[server]
 code-coordinator[reports-xlsx]
+code-coordinator[tui-pty]
 
 [dev]
 code-coordinator[server]
 code-coordinator[reports-xlsx]
+code-coordinator[tui-pty]
 pytest>=8.0
 pytest-asyncio>=0.23
 pytest-xdist>=3.5
@@ -31,3 +33,9 @@ starlette>=0.37
 uvicorn>=0.30
 websockets>=12.0
 psutil>=5.9
+
+[tui-pty]
+pyte>=0.8
+
+[tui-pty:sys_platform == "win32"]
+pywinpty>=2.0

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/code_coordinator.egg-info/scm_file_list.json

@@ -290,6 +290,7 @@
     "coord/test_chat.py",
     "coord/test_orchestrator.py",
     "coord/test_report.py",
+    "coord/tui_pty_driver.py",
     "coord/tui_release.py",
     "coord/uat_checks.py",
     "coord/usage.py",
@@ -885,6 +886,7 @@
     "tests/test_tmux_host.py",
     "tests/test_tmux_session.py",
     "tests/test_transcript_floor.py",
+    "tests/test_tui_pty_driver.py",
     "tests/test_uat_checks.py",
     "tests/test_usage.py",
     "tests/test_usage_limits.py",

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.544",
+  "tag": "0.5.546",
   "distance": 0,
-  "node": "g9d671b639715e489d153691e9b55302116326817",
+  "node": "g943ce5e80a36cebf246516f67c4e6727011815e4",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-30"

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/coord/acceptance_drivers.py

@@ -8,11 +8,11 @@ is the one seam that varies per medium — TUI (quadraui ``TuiDriver``), CLI
 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), and ``terraform``
-(#3232) 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).
+``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).
 
 ``cli-pytest`` parses pytest's built-in ``--junit-xml`` report (a core
 pytest flag, not a plugin — no extra dependency required in the driven
@@ -45,6 +45,22 @@ enough to run ``validate`` at all) comes out regardless of what the driven
 repo's own terraform version prints to plain stdout. This is a compile
 check, not an acceptance oracle — see :data:`VALIDATE_ONLY_KINDS`.
 
+``tui-pty`` (#3483, Tier 2 of the TUI acceptance ladder — ``tui-tuidriver``
+above is Tier 1, in-process) launches the driven repo's real compiled
+binary under a real pty/ConPTY and drives it with real terminal byte
+sequences, rather than going through quadraui's in-process ``TuiDriver``.
+Three real Windows TUI bugs (vimcode#1634-#1636) all passed their
+in-process tests on 2026-09-29 — the bytes an in-process harness feeds and
+reads are never generated by, or read back through, a real terminal, so a
+whole class of bug is invisible to it by construction. All of the actual
+byte-level driving, the VT emulation, and the platform-neutral YAML smoke
+spec live in :mod:`coord.tui_pty_driver` — see that module's docstring for
+the spec format and the ``ESC[6n`` startup-handshake lesson folded in from
+vimcode's own ConPTY tests. This adapter (:func:`_run_tui_pty`) is a thin
+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`.
+
 ``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
@@ -75,7 +91,7 @@ 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")
+SUPPORTED_KINDS = ("tui-tuidriver", "cli-pytest", "web-playwright", "terraform", "tui-pty")
 
 # #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
@@ -229,7 +245,7 @@ def render_run_command(run_command: str, *, ms: str | None = None) -> str:
 
 def run_driver(
     kind: str, run_command: str, cwd: str, *, timeout: int = 900, ms: str | None = None,
-    setup_command: str = "",
+    setup_command: str = "", entrypoint: str = "",
 ) -> DriverResult:
     """Execute *run_command* in *cwd* and parse its output for *kind*.
 
@@ -250,6 +266,13 @@ def run_driver(
     before *run_command* ever executes — with a message that names it as a
     provisioning failure so it isn't mistaken for a test failure or folded
     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.
     """
     if kind not in SUPPORTED_KINDS:
         raise DriverError(
@@ -269,6 +292,8 @@ def run_driver(
         return _run_web_playwright(run_command, cwd, timeout=timeout)
     if kind == "terraform":
         return _run_terraform(run_command, cwd, timeout=timeout)
+    if kind == "tui-pty":
+        return _run_tui_pty(run_command, cwd, entrypoint, timeout=timeout)
     return _run_generic(run_command, cwd, timeout=timeout)
 
 
@@ -572,6 +597,68 @@ def _run_terraform_policy_gate(cwd: str, *, timeout: int) -> tuple[list[dict], s
     return tests, raw_output
 
 
+def _run_tui_pty(run_command: str, cwd: str, entrypoint: str, *, timeout: int) -> DriverResult:
+    """The ``tui-pty`` shape (#3483): *run_command* is the shell command
+    that launches the driven repo's real compiled binary (e.g.
+    ``./target/release/vcd``) — the platform-neutral smoke spec YAML that
+    drives it lives at *entrypoint* (repo-root-relative), the ``tui-pty``
+    analogue of ``tui-tuidriver``'s own ``entrypoint:``-as-sealed-file
+    convention (see the module docstring and CLAUDE.md's sealed-paths
+    section).
+
+    All the actual pty/ConPTY spawning, real terminal-byte input, and VT
+    screen assertions live in :mod:`coord.tui_pty_driver` — this function is
+    the thin seam that resolves *entrypoint* to a spec file and calls
+    :func:`coord.tui_pty_driver.run_smoke_spec`, then folds its normalized
+    ``tests`` list into a :class:`DriverResult` the same way every other
+    kind in this module 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.tui_pty_driver.TuiPtySpecError`).
+    A child process that dies mid-run, a step that times out, or a failed
+    assertion do NOT raise here — :func:`coord.tui_pty_driver.run_smoke_spec`
+    folds those into individual failing entries in ``tests`` instead, so a
+    real regression (e.g. vimcode#1634's idle-flicker check) reads as a
+    normal failing test, not a crashed driver run.
+    """
+    from coord.tui_pty_driver import (  # noqa: PLC0415 — see module docstring on the deferred import
+        TuiPtyRuntimeError,
+        TuiPtySpecError,
+        run_smoke_spec,
+    )
+
+    if not entrypoint:
+        raise DriverError(
+            "tui-pty driver requires an `entrypoint:` naming the smoke-spec "
+            "YAML file (repo-root-relative) — none configured"
+        )
+    spec_path = Path(cwd) / entrypoint
+    if not spec_path.is_file():
+        raise DriverError(f"tui-pty smoke spec not found: {spec_path}")
+
+    try:
+        spec_text = spec_path.read_text()
+    except OSError as e:
+        raise DriverError(f"tui-pty smoke spec could not be read: {spec_path}: {e}") from e
+
+    try:
+        tests = run_smoke_spec(
+            spec_text, launch_command=run_command, cwd=cwd, timeout=timeout,
+        )
+    except TuiPtySpecError as e:
+        raise DriverError(f"tui-pty smoke spec is invalid: {e}") from e
+    except TuiPtyRuntimeError as e:
+        raise DriverError(f"tui-pty 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.544 → code_coordinator-0.5.546}/coord/commands/acceptance.py

@@ -352,7 +352,7 @@ def acceptance_run(
     try:
         result = run_driver(
             driver_cfg.kind, driver_cfg.run, cwd=str(cwd), ms=ms,
-            setup_command=driver_cfg.setup,
+            setup_command=driver_cfg.setup, entrypoint=driver_cfg.entrypoint,
         )
     except DriverError as e:
         click.echo(f"error: {e}", err=True)
@@ -1019,7 +1019,7 @@ def _acceptance_record_local(
         try:
             result = run_driver(
                 driver_cfg.kind, driver_cfg.run, cwd=str(wt_path), ms=ms,
-                setup_command=driver_cfg.setup,
+                setup_command=driver_cfg.setup, entrypoint=driver_cfg.entrypoint,
             )
         except DriverError as e:
             click.echo(f"error: {e}", err=True)

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/coord/commands/milestone.py

@@ -1842,7 +1842,10 @@ def milestone_gate_c_cmd(
     # suite dir for Gate C's "full accumulated suite" semantics.
     ms = ms_dirname(ctx.milestone_number)
     try:
-        result = run_driver(driver_cfg.kind, driver_cfg.run, cwd=str(repo_dir), ms=ms)
+        result = run_driver(
+            driver_cfg.kind, driver_cfg.run, cwd=str(repo_dir), ms=ms,
+            entrypoint=driver_cfg.entrypoint,
+        )
     except DriverError as e:
         click.echo(f"error: {e}", err=True)
         sys.exit(1)
@@ -2148,7 +2151,10 @@ def milestone_ship_cmd(
     click.echo(f"Gate C: running the full accumulated acceptance suite in {repo_dir}...")
     ms = ms_dirname(ctx.milestone_number)
     try:
-        result = run_driver(driver_cfg.kind, driver_cfg.run, cwd=str(repo_dir), ms=ms)
+        result = run_driver(
+            driver_cfg.kind, driver_cfg.run, cwd=str(repo_dir), ms=ms,
+            entrypoint=driver_cfg.entrypoint,
+        )
     except DriverError as e:
         click.echo(f"error: {e}", err=True)
         sys.exit(1)

{code_coordinator-0.5.544 → code_coordinator-0.5.546}/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.544 → code_coordinator-0.5.546}/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