Coverage for src/keel/ship.py: 100%
205 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 19:17 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 19:17 +0000
1"""The deterministic ship decisions — keel's value-add as pure functions.
3The agentic steps and the git/gh plumbing live in the adapter + I/O layer; the
4*decisions* (how many reviewers, whether to merge / defer / block, whether to keep
5fixing) are pure and live here, so they are reproducible and fully unit-tested.
6"""
8from __future__ import annotations
10import fnmatch
11from collections.abc import Mapping, Sequence
12from dataclasses import dataclass
13from typing import Any
15from . import classify
16from . import team as team_policy
17from .findings import Verdict, decision_for
18from .window import is_merge_open
20#: Hard cap on review→fix rounds (matches ship's budget).
21MAX_FIX_ROUNDS = 3
23#: GitHub check-rollup conclusions that count as "not failing".
24CI_OK_STATES = frozenset({"SUCCESS", "NEUTRAL", "SKIPPED"})
26#: GitHub check-rollup conclusions/states that mean a check is in-flight/pending.
27CI_PENDING_STATES = frozenset(
28 {"EXPECTED", "PENDING", "QUEUED", "REQUESTED", "WAITING", "IN_PROGRESS"}
29)
31POSTING_MODES = frozenset({"inline", "summary"})
33# A cross-vendor jury needs at least this many distinct vendors to gate. Below it
34# the panel cannot produce cross-vendor consensus, so the verdict is advisory —
35# and a run where no agent produced output counts as zero, which is how "a jury
36# that did not complete cleanly never gates" falls out of the same comparison.
37MINIMUM_JURY_VENDORS = 2
39#: What ``keel merge --hotfix`` actually skips, named by the keys the ``keel.merge.v1``
40#: record marks ``{"bypassed": true, "reason": "hotfix"}``.
41#:
42#: The contract used to publish a single ``hotfix_bypasses_window_only: True``, which
43#: has been false since the gates-SHA bypass landed: a consumer reading it would treat a
44#: hotfix merge as gates-verified when no gates-pass ledger record was ever matched
45#: (#1078). Keep this tuple derived from :func:`keel.cli._cmd_merge` — the agreement is
46#: pinned by ``tests/test_cli.py``, which reads it back off a real ``--hotfix`` run.
47HOTFIX_BYPASSES = ("gates_sha", "window")
49#: What ``--hotfix`` never skips. All but ``findings`` are keys of the same merge record,
50#: present and un-bypassed on a hotfix run. ``findings`` blocks earlier — at the review
51#: verdict this contract's ``finding_policy`` block governs — so a blocked change never
52#: reaches the merge command to have a key there at all.
53HOTFIX_NEVER_BYPASSES = ("checkpoint_gate", "ci", "evidence", "findings", "lock")
55REVIEW_FOCUS_A = (
56 "logic correctness",
57 "null safety",
58 "language interop",
59)
60REVIEW_FOCUS_B = (
61 "platform compatibility",
62 "lifecycle safety",
63 "API compatibility",
64 "threading",
65)
66REVIEW_FOCUS_C = (
67 "test coverage",
68 "docs gate",
69 "scope creep",
70 "CI prediction",
71 "security",
72)
75def reviewer_count(tier: int) -> int:
76 """Reviewers for a risk tier: TIER-3→3, TIER-2→2, TIER-1→1 (default 2)."""
77 return {3: 3, 2: 2, 1: 1}.get(tier, 2)
80def reviewer_focuses(count: int) -> tuple[dict[str, Any], ...]:
81 """Focus coverage for each reviewer slot. Lower counts merge focus; none are dropped.
83 Zero slots is not "one slot with everything merged in": it is a tier whose
84 ``knobs.team`` policy made the jury the review panel (#1014), so there is no host
85 reviewer to carry a focus. The panel's own coverage is the jury's business.
86 """
87 if count <= 0:
88 return ()
89 if count <= 1:
90 return (
91 {
92 "slot": "A",
93 "focus": list(REVIEW_FOCUS_A + REVIEW_FOCUS_B + REVIEW_FOCUS_C),
94 "merged_from": ["A", "B", "C"],
95 },
96 )
97 if count == 2:
98 return (
99 {
100 "slot": "A",
101 "focus": list(REVIEW_FOCUS_A + REVIEW_FOCUS_B),
102 "merged_from": ["A", "B"],
103 },
104 {
105 "slot": "C",
106 "focus": list(REVIEW_FOCUS_C),
107 "merged_from": ["C"],
108 },
109 )
110 return (
111 {"slot": "A", "focus": list(REVIEW_FOCUS_A), "merged_from": ["A"]},
112 {"slot": "B", "focus": list(REVIEW_FOCUS_B), "merged_from": ["B"]},
113 {"slot": "C", "focus": list(REVIEW_FOCUS_C), "merged_from": ["C"]},
114 )
117def resolve_jury(
118 *,
119 tier: int | None,
120 gates: tuple[str, ...] = (),
121 jury: bool = False,
122 no_jury: bool = False,
123 jury_advisory: bool = False,
124 participating_vendors: int | None = None,
125 panel_is_jury: bool = False,
126 policy_mode: str | None = None,
127 minimum_vendors: int = MINIMUM_JURY_VENDORS,
128 panel_unavailable: bool = False,
129) -> dict[str, Any]:
130 """Resolve the cross-vendor jury mode using ship flag precedence.
132 ``panel_unavailable`` outranks everything, including ``tier == 3``'s auto-on (#1066).
133 It is set only when a measured probe found the panel unstaffable *and* the project's
134 ``team.jury.on_unavailable`` allowed a host bench in its place, and it turns the jury
135 off because there is no panel to produce a verdict: leaving ``tier-3 auto`` standing
136 would require a ``jury-verdict`` artifact from a panel this machine just established
137 cannot convene, which is the tier stuck all over again one layer down. It is not the
138 flag route #1014 closed — a preference still cannot do this, and the reason string
139 names the fallback so nothing reads it as a plain ``--no-jury``.
141 ``panel_is_jury`` is a ``knobs.team`` tier whose review policy is ``jury``, and it
142 **outranks every per-run jury flag**. At such a tier the panel *is* the review: there
143 are no host reviewer slots, so a flag that turned the jury off or made it advisory
144 would leave that tier with no required review evidence at all — a stricter policy
145 producing a weaker gate. It is also the only answer the six commands that resolve this
146 contract can agree on, because they are not all *given* the flags: every surface
147 accepts them since #1043, but keel's CI passes ``--no-jury`` to ``evidence-verify`` on
148 every run and to ``ship``/``plan`` on none. So on a panel tier the verdict stays
149 required, whatever was typed; the flag is recorded in ``assignment.warnings`` instead
150 of applied. Below that
151 tier ``--no-jury`` keeps its pre-existing meaning and still beats the tier-3 auto-jury.
153 ``policy_mode`` is ``team.jury.mode``, which can make an enabled jury *advisory* — a
154 project cannot promote a jury that ``--no-jury`` turned off. Pairing it with a jury
155 *panel* is refused by :func:`keel.team.team_issues`, because "the panel is the review"
156 and "the panel does not gate" together mean the tier has no enforceable review at all.
157 ``minimum_vendors`` is ``team.jury.min_vendors``, which may raise
158 :data:`MINIMUM_JURY_VENDORS` but never lowers it (the schema's floor is 2).
160 ``participating_vendors`` is the count of distinct vendors that actually took
161 part in the panel. Below :data:`MINIMUM_JURY_VENDORS` a gating mode is
162 downgraded to advisory **unless the panel is the tier's review**, because a
163 panel that small cannot produce cross-vendor consensus — and a run where no
164 agent returned output is simply zero, so "a jury that did not complete cleanly
165 never gates" needs no separate branch. ``None`` means the panel is not known
166 yet (planning, ``keel plan``, any caller resolving the contract before s8
167 runs), and leaves the mode alone.
169 The downgrade must live here rather than in adapter prose: the evidence gate
170 derives its ``jury-verdict`` requirement from this ``mode``, so a mode that
171 ignores the real panel makes the gate demand a verdict the jury step would
172 decline to treat as gating.
174 On a **panel tier** the downgrade is suppressed for the mirror-image reason.
175 There the verdict is not a second opinion beside a host bench — it is the
176 tier's own consensus record, and dropping it because the panel came back
177 short lets a short panel excuse itself from the one artifact that says so.
178 The short panel is still refused, by
179 :func:`keel.evidence.panel_vendor_check`; what it may not do is quietly stop
180 being required. ``downgraded`` reports ``False`` there, and the reason string
181 is left alone, so nothing downstream reads a relaxation that did not happen.
182 """
183 if panel_unavailable:
184 enabled = False
185 reason = "jury panel unavailable; host bench fallback (team.jury.on_unavailable)"
186 elif panel_is_jury:
187 enabled = True
188 reason = "team.review panel"
189 ignored = [
190 flag
191 for flag, passed in (("--no-jury", no_jury), ("--jury-advisory", jury_advisory))
192 if passed
193 ]
194 if ignored:
195 reason = f"{reason} ({' and '.join(ignored)} does not apply: the panel is the review)"
196 elif no_jury:
197 enabled = False
198 reason = "--no-jury"
199 elif jury:
200 enabled = True
201 reason = "--jury"
202 elif tier == 3:
203 enabled = True
204 reason = "tier-3 auto"
205 else:
206 enabled = False
207 reason = "default"
208 # A panel tier gates, full stop: it has no host reviewers to fall back on, so an
209 # advisory panel there is a tier with nothing required of it.
210 advisory = not panel_is_jury and (jury_advisory or policy_mode == "advisory")
211 mode = "off" if not enabled else ("advisory" if advisory else "gating")
212 # …and the vendor downgrade is the same door, so it carries the same guard. Round 3
213 # of #1014 closed the flag route only; a panel tier reaching this with one
214 # participating vendor still came out advisory, which drops `jury-verdict` from the
215 # required evidence of a tier whose panel is the *whole* review. That is the short
216 # panel excusing itself from the verdict it came back short on. Elsewhere the
217 # downgrade is right and stays: a jury sitting beside a host bench that did not
218 # convene cross-vendor should not gate, because the bench still reviewed the change.
219 downgraded = (
220 not panel_is_jury
221 and mode == "gating"
222 and participating_vendors is not None
223 and participating_vendors < minimum_vendors
224 )
225 if downgraded:
226 mode = "advisory"
227 reason = (
228 f"{reason}; downgraded to advisory "
229 f"({participating_vendors} participating vendor(s), "
230 f"minimum {minimum_vendors})"
231 )
232 return {
233 "enabled": enabled,
234 "mode": mode,
235 "reason": reason,
236 "configured_gate": "jury" in gates,
237 "fail_soft": True,
238 "minimum_vendors": minimum_vendors,
239 "participating_vendors": participating_vendors,
240 "downgraded": downgraded,
241 "verified_consensus_gates": enabled and mode == "gating",
242 "severity_policy": {
243 "critical": "block",
244 "major": "block",
245 "minor": "gated-suggestion",
246 "nit": "advisory",
247 },
248 }
251def panel_fell_back(assignment: dict[str, Any] | None) -> bool:
252 """Did a measured probe move this tier's review off the panel and onto a host bench?
254 Read off the resolved assignment rather than re-derived, so every surface that resolves
255 the review contract reaches the same answer from the same measurement (#1066). Total:
256 an assignment from before the block existed, or one with no availability recorded,
257 reads as "no fallback" — the answer that leaves the contract exactly as it was.
258 """
259 if not isinstance(assignment, dict):
260 return False
261 jury = assignment.get("jury")
262 availability = jury.get("availability") if isinstance(jury, dict) else None
263 if not isinstance(availability, dict):
264 return False
265 return availability.get("decision") == team_policy.JURY_ON_UNAVAILABLE[0]
268def check_reviewer_override(reviewer_override: int | None) -> None:
269 """Refuse a reviewer count keel has no reviewer vocabulary for.
271 Extracted so :func:`assess` can apply it **before** it resolves the team: the
272 assignment is resolved first, and an out-of-range override reaching that resolver
273 produced an ``IndexError`` from inside it instead of the documented ``ValueError``
274 the caller has always been able to catch.
275 """
276 if reviewer_override is not None and reviewer_override not in {1, 2, 3}:
277 raise ValueError("reviewer_override must be one of 1, 2, or 3")
280def _jury_panel_size(jury_record: dict[str, Any], panel_size: int | None) -> int:
281 """How many verdicts a jury-panel tier requires (#1015).
283 The panel *is* the review there, so its ballots are the required s7 verdicts —
284 ``keel review --from-jury`` posts one head-pinned verdict per ballot — and the
285 required count is the panel's own size, declared as ``panelists: <N>`` on the
286 posted jury verdict.
288 ``minimum_vendors`` is a **floor, not a fallback**: the answer is
289 ``max(declared, minimum_vendors)``, so a declared count can only ever *raise*
290 the requirement. Taking the declared count verbatim let a verdict lower it —
291 ``panelists: 1`` against a minimum of 2 asked for one ballot, while the
292 unmeasured cases (absent, ``0``, negative) still asked for two, so the one
293 shape that means "the panel came back short" was the one shape that relaxed
294 the gate. The declared count is attacker-adjacent evidence in exactly the way
295 the vendor count is: it is read off a comment, and it must not be able to
296 shrink what the tier owes.
298 **What this deliberately does not do is move the bench.** Neither a jury flag
299 nor the measured participating-vendor count may change *who reviews*, only
300 whether the panel's verdict gates. The bench is a pure function of config +
301 tier + role + ``--reviewers``/``--review-delegate`` (:func:`keel.team._review_seats`),
302 and for the same reason: the six commands that resolve this contract are not
303 *given* the other inputs uniformly. All six accept the jury flags since #1043,
304 but keel's CI passes ``--no-jury`` to ``evidence-verify`` on every run and to
305 ``ship``/``plan`` on none, and only the surfaces that can read the PR's posted
306 jury verdict — ``evidence-verify`` and ``keel merge`` — ever see a vendor
307 count. A bench that
308 moved with either input would have ``keel plan`` requiring the panel's ballots
309 while ``evidence-verify`` demanded a host bench of the same PR, which is the
310 contract disagreement #1014 exists to prevent, reintroduced along a new axis.
312 A short panel therefore does not buy fewer eyes: the ballots stay required in
313 full, the jury verdict stays required (:func:`resolve_jury` suppresses the
314 downgrade on a panel tier), and a panel that spans too few vendors is refused
315 by :func:`keel.evidence.panel_vendor_check` rather than quietly swapped for a
316 bench nobody dispatched.
318 **Why the planning surfaces publish the floor rather than the real count.**
319 ``keel plan`` is offline by construction and has no pull request to read a
320 verdict from. ``keel ship --pr N`` does have one — it already makes three
321 GitHub reads for CI status, and could make a fourth for the posted
322 ``panelists`` — and deliberately does not. Two reasons, both about keeping one
323 answer rather than two: the floor is *provably conservative* (this function
324 only ever raises, so a planning surface can under-state what will be required
325 and never over-state it), and ``keel ship`` without ``--pr``, and every dry
326 run, must resolve the same contract with no verdict in reach — so the floor
327 has to be right on its own regardless. Reading it only sometimes would buy a
328 number that is sharper on some runs and identical on the rest, at the cost of
329 a contract whose value depends on which flags the caller happened to pass.
330 """
331 floor = jury_record["minimum_vendors"]
332 if isinstance(panel_size, int) and panel_size > floor:
333 return panel_size
334 return floor
337def resolve_review_contract(
338 *,
339 tier: int | None,
340 reviewer_override: int | None = None,
341 review_comments: str = "inline",
342 gates: tuple[str, ...] = (),
343 policy_pack: dict[str, Any] | None = None,
344 jury: bool = False,
345 no_jury: bool = False,
346 jury_advisory: bool = False,
347 require_distinct_vendors: bool | None = None,
348 jury_participating_vendors: int | None = None,
349 jury_panel_size: int | None = None,
350 assignment: dict[str, Any] | None = None,
351 learnings: Mapping[str, Any] | None = None,
352) -> dict[str, Any]:
353 """Machine-readable review, jury, test, and merge-gate plan for ship-like flows.
355 ``assignment`` is the resolved ``knobs.team`` team (:func:`keel.team.resolve_assignment`).
356 When one is supplied it owns the reviewer bench — how many slots there are, who sits in
357 each, and whether the jury is the panel instead — so the contract a host executes and
358 the assignment it renders cannot disagree. Without one the tier-derived counts stand,
359 which is every pre-#1014 caller.
361 ``require_distinct_vendors`` is tri-state at the config boundary, but ``None`` — unset
362 — resolves to ``False`` on every tier (#1065): the independence claim is opt-in, and a
363 bool is the project's explicit answer.
365 ``jury_panel_size`` is the number of ballots a jury panel actually returned, which
366 only a run that has seen the panel can know (a posted jury verdict declares it; see
367 :func:`keel.evidence.jury_panel_size`). On a tier whose panel *is* the review it
368 becomes the required reviewer count, so the panel sizes its own bench (#1015).
369 """
370 check_reviewer_override(reviewer_override)
371 if review_comments not in POSTING_MODES:
372 raise ValueError("review_comments must be 'inline' or 'summary'")
373 if assignment is None:
374 count = reviewer_override if reviewer_override is not None else reviewer_count(tier or 2)
375 source = (
376 "override"
377 if reviewer_override is not None
378 else ("risk-tier" if tier is not None else "unresolved")
379 )
380 panel, slots = "reviewers", []
381 panel_is_jury = False
382 panel_unavailable = False
383 else:
384 count = assignment["reviewer_count"]
385 source = assignment["reviewer_source"]
386 panel = assignment["review_panel"]
387 slots = list(assignment["reviewers"])
388 panel_is_jury = bool(assignment["jury"]["panel_is_review"])
389 panel_unavailable = panel_fell_back(assignment)
390 jury_record = resolve_jury(
391 tier=tier,
392 gates=gates,
393 jury=jury,
394 no_jury=no_jury,
395 jury_advisory=jury_advisory,
396 participating_vendors=jury_participating_vendors,
397 panel_is_jury=panel_is_jury,
398 policy_mode=None if assignment is None else assignment["jury"]["mode"],
399 minimum_vendors=(
400 MINIMUM_JURY_VENDORS if assignment is None else assignment["jury"]["min_vendors"]
401 ),
402 panel_unavailable=panel_unavailable,
403 )
404 # The probe's verdict travels *on the contract*, not only in the assignment (#1066).
405 # `evidence-verify`, the ledger and the closure comment all read the contract, and a
406 # fallback that only the assignment recorded would be exactly the silent downgrade
407 # ai-jury #682 was opened for: a review that says nothing about the panel it replaced.
408 jury_record["panel_unavailable"] = panel_unavailable
409 jury_record["availability"] = None if assignment is None else assignment["jury"]["availability"]
410 # The opt-in COMMENT-consensus rule (#1570) travels on the contract for the same
411 # reason: `keel merge` and `evidence-verify` judge the verdict off the contract alone.
412 jury_record["comment_consensus"] = (
413 None if assignment is None else assignment["jury"].get("comment_consensus")
414 )
415 if panel_is_jury:
416 count, source = _jury_panel_size(jury_record, jury_panel_size), "jury"
417 pack = policy_pack or {}
418 review_policy = pack.get("review", {}) if isinstance(pack.get("review", {}), dict) else {}
419 return {
420 "reviewers": {
421 "count": count,
422 "source": source,
423 "tier": tier,
424 "independent": True,
425 "self_review_counts_toward_lgtm": False,
426 "minimum_lgtm": count,
427 "require_distinct_vendors": team_policy.require_distinct_vendors(
428 require_distinct_vendors
429 ),
430 "orchestrator_owns_writes": True,
431 "panel": panel,
432 # Per-slot provider/model/effort, so a host dispatches the configured vendor
433 # for slot B instead of running one vendor N times (#1014). Empty for every
434 # caller that resolves no team, which keeps the pre-#1014 contract intact.
435 "slots": slots,
436 # A panel picks its own coverage; keel's A/B/C focus slices describe a bench
437 # keel staffs, and handing them to ai-jury would be keel briefing reviewers it
438 # never dispatched.
439 "focuses": ([] if panel == team_policy.JURY_PANEL else list(reviewer_focuses(count))),
440 "project_additions": list(review_policy.get("additions", [])),
441 "required_sections": list(review_policy.get("required_sections", [])),
442 # The lessons this project already recorded about work of this shape
443 # (#1155), same shape as `project_additions` and for the same reason:
444 # a reviewer who is told what went wrong last time can check the
445 # implementation against it. Empty for every project with no
446 # learnings on disk, which is every project until it has some.
447 "past_learnings": list((learnings or {}).get("hits", [])),
448 },
449 "posting": {
450 "mode": review_comments,
451 "inline_default": True,
452 "per_reviewer_inline_fallback": "summary",
453 "summary_mode": review_comments == "summary",
454 },
455 "jury": jury_record,
456 "finding_policy": {
457 "critical": "block",
458 "major": "block",
459 "minor": "gated-suggestion",
460 "nit": "advisory",
461 "suggestions_require_fix_or_explicit_deferral": True,
462 "parser_source": "reviewer-returned-findings",
463 },
464 "fixloop": {
465 "max_rounds": MAX_FIX_ROUNDS,
466 "blocker_rerun": "full-review",
467 "suggestion_only_rerun": "narrowed-originating-focus",
468 },
469 "ci": {
470 "failure_before_pending": True,
471 "empty_check_set_allowed_for_docs_only": True,
472 "retry_budget": 3,
473 },
474 "test_gates": {
475 "configured_gates": list(gates),
476 "no_jury_preserves_review_and_test_gates": True,
477 },
478 "merge_gate": {
479 "merge_window_applies_to": "literal-merge-only",
480 "merge_lock_scope": "literal-merge-only",
481 "final_mergeability_recheck_inside_lock": True,
482 "hotfix_bypasses": list(HOTFIX_BYPASSES),
483 "hotfix_never_bypasses": list(HOTFIX_NEVER_BYPASSES),
484 "pr_merged_state_authoritative": True,
485 },
486 "closeout": {
487 "comment_targets": ["issue", "pull_request"],
488 "capture_marker_required": True,
489 "status_done_after_merge_only": True,
490 },
491 }
494@dataclass(frozen=True)
495class MergeDecision:
496 action: str # "merge" | "defer" | "block" | "wait"
497 reason: str
500#: The built-in jury gate writes ``jury:<reviewer>`` (and ``jury:consensus`` /
501#: ``jury:incomplete-run`` / …) as a finding's source: one gate with several voices.
502_JURY_SOURCE_PREFIX = "jury:"
505def _gate_id(source: str) -> str:
506 """The gate a finding's ``source`` belongs to.
508 Command gates write their ``spec.id`` verbatim, and nothing forbids a colon in an
509 extension's id, so only the jury's own ``jury:`` prefix is collapsed — splitting
510 every source on ``:`` would turn an operator's ``sec:scan`` gate into ``sec``.
511 """
512 return "jury" if source.startswith(_JURY_SOURCE_PREFIX) else source
515def blocking_sources(verdict: Verdict) -> tuple[str, ...]:
516 """The distinct gates whose findings block this verdict, sorted.
518 Ship's verdict is built from gate outcomes, so a finding's ``source`` is the gate's
519 id, except for the jury's ``jury:<voice>`` sources, which :func:`_gate_id` folds
520 back to the one gate they belong to.
521 """
522 return tuple(
523 sorted(
524 {
525 _gate_id(finding.source)
526 for finding in verdict.findings
527 if finding.source and decision_for(finding.severity) == "block"
528 }
529 )
530 )
533def block_reason(verdict: Verdict) -> str:
534 """The reason a blocked verdict gives, naming what blocked it when it can.
536 "blocking findings present" is true and useless next to a reviewer verdict that says
537 "none blocking": the findings it means are the ones a failed ``on_fail: block`` gate
538 produced, and the line was the one place the operator looked that did not say which
539 gate (#1007). A verdict blocked with no attributable source keeps the old wording.
540 """
541 sources = blocking_sources(verdict)
542 if not sources:
543 return "blocking findings present"
544 return f"blocking findings from gate(s): {', '.join(sources)}"
547def decide_merge(
548 verdict: Verdict,
549 *,
550 window_open: bool,
551 is_blocker: bool = False,
552 unrun_blocking_gates: tuple[str, ...] = (),
553 ci_pending: bool = False,
554) -> MergeDecision:
555 """Decide what to do with a green-or-not PR given the window.
557 * blocking findings ⇒ **block** (never merges);
558 * a required gate that nobody ran ⇒ **block** (no verdict exists to clear it);
559 * outside the merge window and not a blocker ⇒ **defer** to the morning queue;
560 * pending checks ⇒ **wait** (never merges while required checks are in flight);
561 * otherwise ⇒ **merge**. A blocker bypasses the window (but never the
562 findings or pending checks).
564 ``unrun_blocking_gates`` names ``on_fail: block`` gates this run did not execute —
565 agentic gates reach the command-only runner, which does not dispatch them. The
566 assessment must say so: :func:`keel.ledger.record_gates_passed` refuses to certify
567 such a record, so reporting "clear to merge" would promise a merge that
568 ``keel merge`` will then refuse, with the operator given no reason why.
569 """
570 if verdict.blocked:
571 return MergeDecision("block", block_reason(verdict))
572 if unrun_blocking_gates:
573 listed = ", ".join(unrun_blocking_gates)
574 return MergeDecision(
575 "block",
576 f"required gate(s) not run: {listed} — record a result with "
577 "--gate-result <id>=pass|fail once the gate has been dispatched",
578 )
579 if not window_open and not is_blocker:
580 return MergeDecision("defer", "outside merge window (night no-merge)")
581 if ci_pending:
582 return MergeDecision("wait", "checks pending")
583 reason = "blocker bypass" if (is_blocker and not window_open) else "clear to merge"
584 return MergeDecision("merge", reason)
587def should_run_fixloop(verdict: Verdict, *, current_round: int, cap: int = MAX_FIX_ROUNDS) -> bool:
588 """True if there are blocking findings and the fix budget is not exhausted."""
589 return verdict.blocked and current_round < cap
592def ci_passing(ci_conclusion: str | None) -> bool | None:
593 """Interpret a check-rollup string (e.g. ``"SUCCESS,FAILURE"``). ``None`` == unknown."""
594 if ci_conclusion is None:
595 return None
596 parts = [p.strip().upper() for p in ci_conclusion.split(",") if p.strip()]
597 if not parts:
598 return None
599 if any(p not in CI_OK_STATES and p not in CI_PENDING_STATES for p in parts):
600 return False
601 if any(p in CI_PENDING_STATES for p in parts):
602 return None
603 return CI_OK_STATES.issuperset(parts)
606def ci_pending(ci_conclusion: str | None) -> bool:
607 """Return whether any check is pending and no check has failed."""
608 if ci_conclusion is None:
609 return False
610 parts = [p.strip().upper() for p in ci_conclusion.split(",") if p.strip()]
611 if not parts:
612 return False
613 if any(p not in CI_OK_STATES and p not in CI_PENDING_STATES for p in parts):
614 return False
615 return any(p in CI_PENDING_STATES for p in parts)
618def ci_ran(ci_conclusion: str | None) -> bool | None:
619 """Did any check report for this head? ``None`` == we could not find out.
621 Separate from :func:`ci_passing` on purpose. "Every check passed" and "no check
622 ran" are not the same fact, and folding them together is the defect in #675: an
623 empty rollup used to reach the merge decision as *unknown*, and unknown did not
624 block, so a PR nothing had verified assessed identically to a green one — then
625 that assessment was written into the run ledger as evidence.
627 ``""`` is ``gh`` reporting an empty rollup (a fact about the PR) and returns
628 **False**. ``None`` is ``gh`` never answered, or no PR was supplied at all (a
629 fact about the runner) and stays **None** — keel does not block on what it
630 could not observe, it blocks on having observed nothing.
631 """
632 if ci_conclusion is None:
633 return None
634 return bool(ci_conclusion.strip())
637def missing_ci_workflows(
638 workflow_names: Sequence[str] | None,
639 ci_workflows: dict[str, str] | None,
640 changed_files: Sequence[str] | None = None,
641) -> tuple[str, ...]:
642 """Declared workflows in ``ci_workflows`` that reported nothing for this head.
644 ``knobs.ci_workflows`` is the project stating which workflows gate a merge, so
645 presence can be checked against a **declaration** instead of inferred from an
646 empty set — the difference between "I saw no failures" and "I saw the things
647 that were supposed to run".
649 ``workflow_names`` must be *workflow* names (:func:`keel.github.ci_workflow_names`),
650 not job names. The distinction is not cosmetic: `ci_workflows` is keyed ``CI``,
651 while the rollup reports ``test (py3.13 / ubuntu-latest)``, so comparing against
652 job names would report every declared workflow missing on any repo using a matrix.
653 Matching is exact and case-insensitive — a prefix rule would let an unrelated
654 ``testing-utils`` satisfy a declared ``test``.
656 Each declaration's value is the path glob that gates the workflow (#1469): a
657 workflow whose ``paths:`` filter matches nothing in the change never triggers, so
658 its absence is not a missing run. With ``changed_files`` given, a declared
659 workflow is expected only if at least one changed file matches its glob (same
660 ``fnmatch`` semantics as :mod:`keel.classify`; a comma-separated value is several
661 globs). ``changed_files`` of ``None`` or ``[]`` is an unknown change set and keeps
662 the fail-closed answer — every declared workflow is expected — as does a
663 declaration with no usable glob.
665 ``()`` when nothing is declared or the names could not be read — absence of a
666 declaration is not evidence of a missing run.
667 """
668 if not ci_workflows or workflow_names is None:
669 return ()
670 reported = {name.strip().lower() for name in workflow_names if name.strip()}
671 return tuple(
672 sorted(
673 declared
674 for declared, glob in ci_workflows.items()
675 if declared.strip().lower() not in reported and _workflow_expected(glob, changed_files)
676 )
677 )
680def _workflow_expected(glob: str, changed_files: Sequence[str] | None) -> bool:
681 """Whether a declared workflow's path glob is touched by ``changed_files``."""
682 if not changed_files:
683 return True
684 globs = [g.strip() for g in str(glob).split(",") if g.strip()]
685 if not globs:
686 return True
687 return any(fnmatch.fnmatch(path, g) for path in changed_files for g in globs)
690def is_hotfix(labels: list[str] | tuple[str, ...], *, hotfix_label: str = "hotfix") -> bool:
691 """True if the issue/PR carries the hotfix label (case-insensitive)."""
692 # ⚡ Bolt Optimization: Unroll any() generator and pre-compute lower() target
693 target = hotfix_label.lower()
694 for label in labels:
695 if label.strip().lower() == target:
696 return True
697 return False
700@dataclass(frozen=True)
701class ShipAssessment:
702 tier: int
703 reviewers: int
704 window_open: bool
705 ci_ok: bool | None
706 merge: MergeDecision
707 halted: bool = False # pause mode + outside window ⇒ pipeline halted
708 bypassed_window: bool = False # hotfix merged outside the window (audited)
709 review_contract: dict[str, Any] | None = None
710 #: Did any check report? False == the rollup was empty (nothing verified this
711 #: head); None == keel could not find out. Distinct from ``ci_ok`` (#675).
712 ci_ran: bool | None = None
713 #: Declared ``knobs.ci_workflows`` that produced no check for this head.
714 missing_workflows: tuple[str, ...] = ()
715 #: The resolved ``knobs.team`` assignment: who implements, gates, reviews, juries.
716 assignment: dict[str, Any] | None = None
717 #: What ``policy_pack.capture.learning.source`` retrieved for this task (#1155),
718 #: as :func:`keel.capture.learning_retrieval_as_dict` builds it. ``None`` for
719 #: every caller that measured nothing, which is not the same as a project whose
720 #: directory is empty — that one retrieves and finds no hits.
721 learnings: dict[str, Any] | None = None
722 #: Are any checks still in-flight/pending (without failure)?
723 ci_pending: bool = False
726def assess(
727 *,
728 changed_files: list[str] | None,
729 gate_verdict: Verdict,
730 tier3_globs: tuple[str, ...] = (),
731 docs_globs: tuple[str, ...] = (),
732 allowlist_globs: tuple[str, ...] = (),
733 patches: dict[str, str] | None = None,
734 timezone: str | None = None,
735 merge_window: str | None = None,
736 merge_window_mode: str = "freeze",
737 ci_conclusion: str | None = None,
738 ci_check_names: Sequence[str] | None = None,
739 ci_workflow_names: Sequence[str] | None = None,
740 ci_workflows: dict[str, str] | None = None,
741 now=None,
742 is_blocker: bool = False,
743 unrun_blocking_gates: tuple[str, ...] = (),
744 reviewer_override: int | None = None,
745 review_comments: str = "inline",
746 gates: tuple[str, ...] = (),
747 policy_pack: dict[str, Any] | None = None,
748 jury: bool = False,
749 no_jury: bool = False,
750 jury_advisory: bool = False,
751 team: team_policy.TeamPolicy | None = None,
752 legacy_agents: dict[str, team_policy.Seat] | None = None,
753 role: str | None = None,
754 delegate: str | None = None,
755 review_delegates: Sequence[str] = (),
756 #: ``--team`` / ``--effort``: the bench this run is staffed from (#1017). Resolved
757 #: here as well as in ``cli._review_assignment`` because ``keel ship`` *replaces* the
758 #: planned assignment with this one once the real tier is known — dropping them here
759 #: published a ship contract whose team disagreed with the plan the operator read.
760 team_profile: str | None = None,
761 effort: str | None = None,
762 host_agent: str = team_policy.HOST_DEFAULT,
763 require_distinct_vendors: bool | None = None,
764 #: The s7 panel-availability probe (#1066), measured by
765 #: :func:`keel.providerprobe.jury_availability` and passed in for the same reason
766 #: ``team_profile``/``effort`` are: ``keel ship`` **replaces** the planned assignment
767 #: with this one once the real tier is known, so a measurement that stopped here would
768 #: publish a ship contract naming a panel the plan had already found unstaffable.
769 jury_availability: Mapping[str, Any] | None = None,
770 #: The retrieved past learnings for this task (#1155), measured in `cli` for the
771 #: same reason ``jury_availability`` is: reading a directory is I/O, and this
772 #: function is pure. ``None`` means nothing was retrieved *or attempted*.
773 learnings: Mapping[str, Any] | None = None,
774) -> ShipAssessment:
775 """The whole deterministic ship decision in one place: tier → reviewers, window,
776 CI, and the final merge action. Pure — identical inputs give identical output.
778 ``merge_window_mode`` 'pause' halts the pipeline outside the window; 'freeze'
779 (default) only blocks the merge. ``is_blocker`` (a hotfix) bypasses the window —
780 but never the findings or a failing CI.
782 ``patches`` is the per-file diff, keyed by path. Without it this classified
783 from filenames alone and so could not apply the diff-based TIER-3 downgrade,
784 which made the assessment a human reads disagree with the evidence gate that
785 enforces it (#845). ``None`` keeps the old behaviour — no diff is no evidence,
786 and the path decides.
788 ``changed_files`` is ``None`` when git could not be read (as
789 :func:`keel.git.changed_files` reports it), which is deliberately *not* the same
790 as ``[]``. An empty list classifies as the default tier; an unreadable one
791 classifies fail-closed at :data:`keel.classify.UNKNOWN_TIER`, so a change nobody
792 could see never buys itself a lighter review contract."""
793 tier = (
794 classify.UNKNOWN_TIER
795 if changed_files is None
796 else classify.tier_for_files(
797 changed_files,
798 tier3_globs=tier3_globs,
799 docs_globs=docs_globs,
800 allowlist_globs=allowlist_globs,
801 patches=patches,
802 )
803 )
804 check_reviewer_override(reviewer_override)
805 assignment = team_policy.resolve_assignment(
806 team if team is not None else team_policy.TeamPolicy(),
807 tier=tier,
808 role=role,
809 default_count=reviewer_count(tier),
810 reviewer_override=reviewer_override,
811 delegate=delegate,
812 review_delegates=review_delegates,
813 host_agent=host_agent,
814 legacy=legacy_agents,
815 jury_disabled=no_jury,
816 jury_advisory=jury_advisory,
817 team_profile=team_profile,
818 effort=effort,
819 jury_availability=jury_availability,
820 )
821 reviewers = assignment["reviewer_count"]
822 window_open = (
823 is_merge_open(timezone, merge_window, now=now) if (timezone and merge_window) else True
824 )
825 halted = (merge_window_mode == "pause") and not window_open and not is_blocker
826 ci_ok = ci_passing(ci_conclusion)
827 ran = ci_ran(ci_conclusion)
828 pending = ci_pending(ci_conclusion)
829 docs_only = changed_files is not None and classify.is_docs_only(list(changed_files), docs_globs)
830 missing = (
831 () if docs_only else missing_ci_workflows(ci_workflow_names, ci_workflows, changed_files)
832 )
833 if ci_ok is False:
834 merge = MergeDecision("block", "CI failing")
835 elif ran is False and not docs_only:
836 # Fail closed, and say which it was: an operator needs "nothing verified
837 # this commit" to read differently from "a check went red".
838 #
839 # The docs-only carve-out is not a softening — it is what `keel merge`
840 # already applies to its own `no-checks` state (cli._ci_state), and this
841 # assessment must not contradict the gate it is predicting. A docs-only
842 # change legitimately matches no workflow's path filter; anything else
843 # with an empty rollup was simply never verified.
844 merge = MergeDecision("block", "no CI ran — nothing verified this commit")
845 elif missing:
846 merge = MergeDecision("block", f"declared CI workflow(s) never ran: {', '.join(missing)}")
847 else:
848 merge = decide_merge(
849 gate_verdict,
850 window_open=window_open,
851 is_blocker=is_blocker,
852 unrun_blocking_gates=unrun_blocking_gates,
853 ci_pending=pending,
854 )
855 bypassed = is_blocker and not window_open and merge.action == "merge"
856 review_contract = resolve_review_contract(
857 tier=tier,
858 reviewer_override=reviewer_override,
859 review_comments=review_comments,
860 gates=gates,
861 policy_pack=policy_pack,
862 jury=jury,
863 no_jury=no_jury,
864 jury_advisory=jury_advisory,
865 require_distinct_vendors=require_distinct_vendors,
866 assignment=assignment,
867 learnings=learnings,
868 )
869 return ShipAssessment(
870 tier,
871 reviewers,
872 window_open,
873 ci_ok,
874 merge,
875 halted,
876 bypassed,
877 review_contract,
878 ran,
879 missing,
880 assignment,
881 None if learnings is None else dict(learnings),
882 ci_pending=pending,
883 )