code-coordinator 0.5.449__tar.gz → 0.5.451__tar.gz

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.449
+Version: 0.5.451
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.449
+Version: 0.5.451
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.449",
+  "tag": "0.5.451",
   "distance": 0,
-  "node": "g7dfdcb7b4d399030cd2ec41d318600ac37e88140",
+  "node": "g75985b1122962fa0ccd6b97ab453eabdc7a1b5e9",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-11"

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/coord/commands/gates.py

@@ -45,9 +45,11 @@ def _gates_via_daemon(svc, params: dict) -> None:
     help=(
         "Print a work row's gate columns (test_state, smoke_test, test_reason, "
         "test_toolchain, review_state, review_verdict, review_of_assignment_id), "
-        "plus the LIVE review/test/merge gate decision — including whether a recorded verdict "
-        "is #1479-stale (recorded against a base/branch SHA that has since "
-        "moved) and the SHAs compared. Read-only: never mutates board state."
+        "plus the LIVE review/test/uat/merge gate decision — including whether a recorded "
+        "verdict is #1479-stale (recorded against a base/branch SHA that has since "
+        "moved) and the SHAs compared. A gate that does not apply (e.g. uat, when "
+        "not configured for this repo) is still shown, with an explicit reason. "
+        "Read-only: never mutates board state."
     )
 )
 @click.argument("repo")

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/coord/gates.py

@@ -1,6 +1,6 @@
 """#1657: ``coord gates <repo> <issue>`` — read a work row's gate columns
-plus the LIVE gate decision (review / test / merge), without a hand-extracted
-bearer token and a raw ``/board`` curl.
+plus the LIVE gate decision (review / test / uat / merge), without a
+hand-extracted bearer token and a raw ``/board`` curl.
 
 Two things were missing before this module existed:
 
@@ -24,6 +24,12 @@ reuses ``coord.merge_queue``'s own review/smoke gate functions
 :func:`~coord.merge_queue.evaluate_smoke_verdict`) rather than
 re-implementing the #1479 freshness math a second time, so this can never
 drift from what ``coord merge``/``coord merge --plan`` actually decide.
+#3273 (S-5 of #3261): any OTHER gate described in
+``coord.pipeline.GATE_REGISTRY`` (today just ``"uat"``) is walked generically
+rather than hardcoded here — a gate added to that registry in the future
+needs no further change to this module, and one that doesn't currently
+apply (not configured, an exempt issue, ...) is reported with an explicit
+reason rather than silently omitted.
 
 Read-only by construction: nothing in this module calls ``save_board``,
 ``save_queue``, or any ``gh`` write. The synthetic
@@ -680,20 +686,64 @@ def build_gate_report(
             "round has actually been tested (#2024)."
         )
 
+    # #3273 (S-5 of #3261): walk every OTHER registry-backed gate (today just
+    # "uat" — "review"/"test" stay the bespoke blocks above, since they carry
+    # richer per-gate detail — #1479 SHA staleness anchors, #1956 verdict-
+    # unparseable detection — that doesn't fit GateSpec's generic
+    # ``(ok, message)`` evaluator shape; see #3273's epic-closing comment on
+    # #3261 for why that's a real seam, not an oversight). This is what lets
+    # a gate added to `coord.pipeline.GATE_REGISTRY` in the future show up
+    # here with zero further changes to this module, and it's what fixes the
+    # actual #3273 gap: before this, `coord gates` never even asked about
+    # UAT, so it could print "merge READY" for an entry `coord merge` would
+    # refuse outright on `uat_required`.
+    from coord.pipeline import GATE_REGISTRY  # noqa: PLC0415
+
+    registry_decisions: dict[str, GateDecision] = {}
+    for gate_name, spec in GATE_REGISTRY.items():
+        if gate_name in ("review", "test"):
+            continue  # already covered by the bespoke blocks above
+        gate_required = spec.applies(entry, config)
+        if not gate_required:
+            decision = GateDecision(
+                gate=gate_name,
+                required=False,
+                ok=True,
+                reason=spec.explain_inapplicable(entry, config)
+                if spec.explain_inapplicable is not None
+                else None,
+            )
+        else:
+            gate_ok, gate_message = spec.evaluate(entry, board, config, gh_ops)
+            decision = GateDecision(
+                gate=gate_name,
+                required=True,
+                ok=gate_ok,
+                reason=(gate_message or None) if not gate_ok else None,
+            )
+        registry_decisions[gate_name] = decision
+        report.decisions.append(decision)
+
     merge_blocked_gate: str | None = None
     if review_required and not review_ok:
         merge_blocked_gate = REVIEW_REQUIRED
     elif smoke_required and not test_ok:
         merge_blocked_gate = SMOKE_REQUIRED
+    else:
+        for gate_name, decision in registry_decisions.items():
+            if decision.required and not decision.ok:
+                merge_blocked_gate = f"{gate_name}_required"
+                break
     merge_decision = GateDecision(
         gate="merge", required=True, ok=merge_blocked_gate is None, reason=merge_blocked_gate,
     )
     report.decisions.append(merge_decision)
     if merge_decision.ok:
+        gate_names_summary = "/".join(["review", "test", *registry_decisions.keys()])
         report.notes.append(
-            "merge READY reflects the review/test gates only — CI checks and the "
-            "#1318 epic-closing-keyword guard are evaluated live by `coord merge`/"
-            "`coord merge --plan`, not by `coord gates`."
+            f"merge READY reflects the {gate_names_summary} gates only — CI checks "
+            "and the #1318 epic-closing-keyword guard are evaluated live by "
+            "`coord merge`/`coord merge --plan`, not by `coord gates`."
         )
 
     # #3236: the apply-verdict gate, appended ONLY when a --hold-after entry
@@ -808,6 +858,30 @@ def format_gate_report(report: GateReport) -> str:
                 lines.append(f"           {test.reason}")
             else:
                 lines.append(f"  test   : BLOCKED — {test.reason}")
+        # #3273 (S-5 of #3261): any other registry-backed gate (today just
+        # "uat") renders generically here, in `report.decisions`' own
+        # insertion order — a gate GATE_REGISTRY grows in the future needs no
+        # new branch here, and — the actual fix this slice makes — a
+        # skipped/inapplicable one (UAT not configured, or an exempt issue)
+        # gets an explicit reason instead of being silently omitted like it
+        # was before #3273.
+        _KNOWN_GATE_LINES = ("review", "test", "merge", "apply")
+        for decision in report.decisions:
+            if decision.gate in _KNOWN_GATE_LINES:
+                continue
+            label = f"{decision.gate:<6}"
+            if not decision.required:
+                lines.append(
+                    f"  {label} : not required"
+                    + (f" — {decision.reason}" if decision.reason else "")
+                )
+            elif decision.ok:
+                lines.append(
+                    f"  {label} : passed"
+                    + (f" (recorded on {decision.assignment_id})" if decision.assignment_id else "")
+                )
+            else:
+                lines.append(f"  {label} : BLOCKED — {decision.reason}")
         merge = by_gate.get("merge")
         if merge is not None:
             lines.append(

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/coord/merge_queue.py

@@ -1005,10 +1005,15 @@ def _uat_repo_for(entry, config):
         return None
 
 
-def requires_uat(entry: "QueuedMerge", config) -> bool:
-    """True when *entry* must have a recorded UAT verdict before merging.
-
-    See the module-comment above this function for the two-part opt-in.
+def _uat_applicability(entry: "QueuedMerge", config) -> tuple[bool, str | None]:
+    """``(applies, reason_if_not)`` — the single source both :func:`requires_uat`
+    and :func:`uat_inapplicable_reason` (#3273, S-5 of #3261) read, so a
+    caller asking "does UAT gate this entry" and one asking "why not" can
+    never disagree about which condition actually decided it (#2096: one
+    question, one answer). *reason* is only meaningful when *applies* is
+    ``False`` — always ``None`` on the ``True`` branch.
+
+    See the module comment above this function for the two-part opt-in.
     Duck-typed on ``entry.repo_name``/``entry.required_gates``, matching
     :func:`requires_review`/:func:`requires_smoke`.
 
@@ -1027,18 +1032,43 @@ def requires_uat(entry: "QueuedMerge", config) -> bool:
     """
     pipeline = getattr(config, "pipeline", None)
     if pipeline is None or config is None:
-        return False
+        return False, "no pipeline configuration available"
     if not _gate_in_effective_gates("uat", entry, config):
-        return False
+        return False, '"uat" is not in this entry\'s effective gate list (required_gates / pipeline.default_gates)'
     repo = _uat_repo_for(entry, config)
     if repo is None:
-        return False
+        return False, f"repo {getattr(entry, 'repo_name', None)!r} not found in configuration"
     uat_checks_cfg = getattr(repo, "uat_checks", None)
-    if uat_checks_cfg is not None and uat_checks_cfg.is_exempt(
-        getattr(entry, "issue_number", None)
-    ):
-        return False
-    return bool(repo.uat_preview) or bool(getattr(repo, "uat_live_preview", False))
+    issue_number = getattr(entry, "issue_number", None)
+    if uat_checks_cfg is not None and uat_checks_cfg.is_exempt(issue_number):
+        return False, f"issue #{issue_number} is exempt via this repo's uat_checks.exempt"
+    if not (bool(repo.uat_preview) or bool(getattr(repo, "uat_live_preview", False))):
+        return False, "repo has neither uat_preview nor uat_live_preview configured"
+    return True, None
+
+
+def requires_uat(entry: "QueuedMerge", config) -> bool:
+    """True when *entry* must have a recorded UAT verdict before merging.
+
+    Delegates entirely to :func:`_uat_applicability` — see that function's
+    docstring for the full two-part opt-in this decides.
+    """
+    return _uat_applicability(entry, config)[0]
+
+
+def uat_inapplicable_reason(entry: "QueuedMerge", config) -> str | None:
+    """Human-readable reason UAT does *not* gate *entry*, or ``None`` when it
+    does (i.e. :func:`requires_uat` would return ``True``).
+
+    #3273 (S-5 of #3261): the ``coord gates`` render path used to omit the
+    UAT gate entirely rather than say why it isn't running — this is what
+    lets it render "uat : not required — <reason>" instead of silently
+    dropping the gate, mirroring how ``milestone_gate.plan_sequence`` gives
+    every remaining gate an explicit reason rather than skipping the ones
+    that won't fire. Shares :func:`_uat_applicability` with
+    :func:`requires_uat` so the two can never drift apart on WHY.
+    """
+    return _uat_applicability(entry, config)[1]
 
 
 def _uat_branch_work(entry: "QueuedMerge", board) -> list:

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/coord/pipeline.py

@@ -32,7 +32,12 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Callable
 
-from coord.merge_queue import evaluate_uat_verdict, is_uat_gate_reason, requires_uat
+from coord.merge_queue import (
+    evaluate_uat_verdict,
+    is_uat_gate_reason,
+    requires_uat,
+    uat_inapplicable_reason,
+)
 
 if TYPE_CHECKING:
     from coord.config import Config
@@ -187,6 +192,17 @@ class GateSpec:
     #: for the same allowance).
     identifies_reason: Callable[[str], bool] | None = None
 
+    #: ``(entry, config) -> str | None`` — a human-readable reason THIS gate
+    #: does not apply to *entry*, populated only when ``applies`` would
+    #: return ``False`` (``None`` on the ``applies=True`` branch). #3273
+    #: (S-5 of #3261): this is what lets a render path (``coord gates``) walk
+    #: every registry gate and give the skipped ones an explicit reason
+    #: ("UAT not configured for this repo", "issue exempt via
+    #: uat_checks.exempt", ...) instead of silently omitting them — the same
+    #: posture ``milestone_gate.plan_sequence`` already takes for the
+    #: Gate-A..D walk. ``None`` for a gate that hasn't grown this yet.
+    explain_inapplicable: Callable[["QueuedMerge", "Config"], str | None] | None = None
+
 
 GATE_REGISTRY: dict[str, GateSpec] = {
     "uat": GateSpec(
@@ -196,6 +212,7 @@ GATE_REGISTRY: dict[str, GateSpec] = {
         verdicts=("passed", "failed", None),
         fail_route="coord.drive._park_uat_fixup_dispatch_failure",
         identifies_reason=is_uat_gate_reason,
+        explain_inapplicable=uat_inapplicable_reason,
     ),
 }
 

{code_coordinator-0.5.449 → code_coordinator-0.5.451}/coord/serve_app.py

@@ -5665,6 +5665,104 @@ def openapi_spec() -> dict:
     )
 
 
+# #3293: keys whose values are inherently volatile per-build (a sliding
+# window count) but carry no board-state signal of their own — excluded from
+# the ``/board`` ETag DIGEST INPUT only (see ``_board_digest_projection``
+# below and ``_stamp_board_version``'s docstring). Every one of these fields
+# still ships on the wire, unchanged; this only stops them from deciding
+# whether the version bumps.
+_BOARD_DIGEST_VOLATILE_TOP_KEYS = frozenset({"audit_recent_count"})
+
+
+def _board_digest_projection(result: dict) -> dict:
+    """A copy of *result* with digest-irrelevant volatile fields stripped.
+
+    Used ONLY to compute the ``/board`` ETag/version digest (#3293) — the
+    actual wire body is `result` itself, untouched. Three culprits, in order
+    of how often they move (see issue #3293's measurements):
+
+    - ``audit_recent_count``: a sliding 900s window count, changed on
+      essentially every build.
+    - ``issues[*].synced_at``: ~788 rows share one sync timestamp that moves
+      on the issues-sync tick, re-digesting the whole issues section at once.
+    - ``fleet_health``: moves on the 60s health tick. Its ``refreshed_at``
+      clock and its ``fleet_board_latency`` check are excluded — the latter
+      measures THIS /board response's own fetch latency and serialized size
+      and stores that measurement inside the response, which is structurally
+      self-invalidating for a content digest.
+
+    Deliberately narrow: per-machine health severities/results/headrooms are
+    left in the digest, because a real state change there (a machine going
+    offline, a disk filling up) SHOULD bump the ETag — only the fields that
+    move on their own, independent of any real state change, are excluded.
+    """
+    projection = {
+        k: v for k, v in result.items() if k not in _BOARD_DIGEST_VOLATILE_TOP_KEYS
+    }
+
+    issues = projection.get("issues")
+    if isinstance(issues, list):
+        projection["issues"] = [
+            {k: v for k, v in issue.items() if k != "synced_at"}
+            if isinstance(issue, dict) else issue
+            for issue in issues
+        ]
+
+    fleet_health = projection.get("fleet_health")
+    if isinstance(fleet_health, dict):
+        projection["fleet_health"] = _board_digest_fleet_health(fleet_health)
+
+    return projection
+
+
+def _board_digest_fleet_health(fleet_health: dict) -> dict:
+    """Strip ``fleet_health``'s clocks + self-referential latency check.
+
+    See ``_board_digest_projection`` — digest input only, never the wire body.
+    """
+    masked = {k: v for k, v in fleet_health.items() if k != "refreshed_at"}
+
+    machine_health = masked.get("machine_health")
+    if isinstance(machine_health, list):
+        masked["machine_health"] = [
+            _board_digest_health_row(row) if isinstance(row, dict) else row
+            for row in machine_health
+        ]
+
+    fleet_checks = masked.get("fleet_checks")
+    if isinstance(fleet_checks, list):
+        masked["fleet_checks"] = [
+            _board_digest_check_result(c) if isinstance(c, dict) else c
+            for c in fleet_checks
+        ]
+
+    return masked
+
+
+def _board_digest_health_row(row: dict) -> dict:
+    """Drop one machine's poll clocks (``received_at``/``checked_at``) from
+    the digest input — the results/severity/headroom that actually describe
+    the machine's state stay in, per ``_board_digest_projection``'s docstring.
+    """
+    return {k: v for k, v in row.items() if k not in ("received_at", "checked_at")}
+
+
+def _board_digest_check_result(check: dict) -> dict:
+    """Drop ``fleet_board_latency``'s self-measurement from the digest input.
+
+    This one check answers "how fast/big was the /board response that is
+    carrying this very check result?" — its ``headroom`` text and ``values``
+    (``latency_ms``/``payload_bytes``) are a measurement of the response
+    embedded in the response, so they change on every build regardless of
+    whether anything a human/client cares about actually changed. Every
+    other fleet check's headroom/values reflect real, digest-worthy state
+    and are left untouched.
+    """
+    if check.get("check_id") != "fleet_board_latency":
+        return check
+    return {k: v for k, v in check.items() if k not in ("headroom", "values")}
+
+
 def build_app(
     store: CoordStore,
     config: Config,
@@ -5768,13 +5866,31 @@ def build_app(
     _board_inflight: asyncio.Future[tuple] | None = None
 
     def _stamp_board_version(result: dict) -> tuple[str, bytes]:
-        """Serialize *result* to JSON exactly once, bump the version when the
-        content changed, stamp ``board_version`` into the payload, and
-        return ``(etag, body_bytes)`` — the SAME bytes serve as both the
-        content-hash input and the wire body (#1597 Part 2: previously this
-        hashed a separate ``sort_keys=True`` dump and the caller re-encoded
-        the dict a second time via ``JSONResponse`` — ~10 MB of JSON work per
-        build for a 5 MB board).
+        """Serialize *result* to JSON exactly once for the wire body, bump
+        the version when a STABLE PROJECTION of the content changed, stamp
+        ``board_version`` into the payload, and return ``(etag, body_bytes)``.
+
+        #1597 Part 2: the wire ``body`` bytes below are the same bytes
+        published to callers — no second encoder pass for the response
+        itself.
+
+        #3293: the content-hash input is deliberately NOT those same bytes
+        any more. The payload embeds fields that move on every build without
+        any board-state signal of their own — ``audit_recent_count`` (a
+        sliding 900s window count), ``issues[*].synced_at`` (~788 rows
+        re-stamped on one shared sync tick), and ``fleet_health``'s clocks
+        and its self-referential ``fleet_board_latency`` check (which
+        measures THIS response's own fetch latency/size and stores the
+        measurement inside the response being measured). Hashing those made
+        the ETag change on effectively every request, defeating #1336's
+        cache-validated polling entirely. ``_board_digest_projection`` builds
+        a masked copy for hashing only; the wire ``body`` — and every field
+        in it, unchanged — still carries the real values. This does cost a
+        second JSON encode of (most of) the payload on every cache-miss
+        rebuild, which is rare relative to requests (TTL-cached in between);
+        that's the trade #1597 avoided but #3293 requires; a truly stable
+        ETag that lets pollers 304 is worth far more than skipping it on the
+        rebuild path.
 
         ``board_version`` can't be known before the hash is computed (it
         depends on whether the hash changed), so it is deliberately excluded
@@ -5822,7 +5938,19 @@ def build_app(
                 indent=None, separators=(",", ":"), default=str,
             ).encode("utf-8")
         else:
-            digest = hashlib.sha256(body).hexdigest()[:16]
+            # #3293: hash a stable PROJECTION of the content, not the wire
+            # bytes themselves — see the docstring above. The wire `body`
+            # computed just above is untouched and still carries every
+            # field, including the ones excluded here.
+            # No `default=str` needed (unlike the fallback above): reaching
+            # this branch means the strict encode of `result` just SUCCEEDED,
+            # and the projection is a key-subset of those same values, so it
+            # cannot contain a type the strict encoder would reject.
+            digest_body = _json.dumps(
+                _board_digest_projection(result), ensure_ascii=False,
+                allow_nan=False, indent=None, separators=(",", ":"),
+            ).encode("utf-8")
+            digest = hashlib.sha256(digest_body).hexdigest()[:16]
         if digest != _board_hash:
             _board_hash = digest
             _board_version += 1