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

1"""The deterministic ship decisions — keel's value-add as pure functions. 

2 

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""" 

7 

8from __future__ import annotations 

9 

10import fnmatch 

11from collections.abc import Mapping, Sequence 

12from dataclasses import dataclass 

13from typing import Any 

14 

15from . import classify 

16from . import team as team_policy 

17from .findings import Verdict, decision_for 

18from .window import is_merge_open 

19 

20#: Hard cap on review→fix rounds (matches ship's budget). 

21MAX_FIX_ROUNDS = 3 

22 

23#: GitHub check-rollup conclusions that count as "not failing". 

24CI_OK_STATES = frozenset({"SUCCESS", "NEUTRAL", "SKIPPED"}) 

25 

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) 

30 

31POSTING_MODES = frozenset({"inline", "summary"}) 

32 

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 

38 

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") 

48 

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") 

54 

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) 

73 

74 

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) 

78 

79 

80def reviewer_focuses(count: int) -> tuple[dict[str, Any], ...]: 

81 """Focus coverage for each reviewer slot. Lower counts merge focus; none are dropped. 

82 

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 ) 

115 

116 

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. 

131 

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``. 

140 

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. 

152 

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). 

159 

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. 

168 

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. 

173 

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 } 

249 

250 

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? 

253 

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] 

266 

267 

268def check_reviewer_override(reviewer_override: int | None) -> None: 

269 """Refuse a reviewer count keel has no reviewer vocabulary for. 

270 

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") 

278 

279 

280def _jury_panel_size(jury_record: dict[str, Any], panel_size: int | None) -> int: 

281 """How many verdicts a jury-panel tier requires (#1015). 

282 

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. 

287 

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. 

297 

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. 

311 

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. 

317 

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 

335 

336 

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. 

354 

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. 

360 

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. 

364 

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 } 

492 

493 

494@dataclass(frozen=True) 

495class MergeDecision: 

496 action: str # "merge" | "defer" | "block" | "wait" 

497 reason: str 

498 

499 

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:" 

503 

504 

505def _gate_id(source: str) -> str: 

506 """The gate a finding's ``source`` belongs to. 

507 

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 

513 

514 

515def blocking_sources(verdict: Verdict) -> tuple[str, ...]: 

516 """The distinct gates whose findings block this verdict, sorted. 

517 

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 ) 

531 

532 

533def block_reason(verdict: Verdict) -> str: 

534 """The reason a blocked verdict gives, naming what blocked it when it can. 

535 

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)}" 

545 

546 

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. 

556 

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). 

563 

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) 

585 

586 

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 

590 

591 

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) 

604 

605 

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) 

616 

617 

618def ci_ran(ci_conclusion: str | None) -> bool | None: 

619 """Did any check report for this head? ``None`` == we could not find out. 

620 

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. 

626 

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()) 

635 

636 

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. 

643 

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". 

648 

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``. 

655 

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. 

664 

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 ) 

678 

679 

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) 

688 

689 

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 

698 

699 

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 

724 

725 

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. 

777 

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. 

781 

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. 

787 

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 )