Coverage for src/keel/contracts.py: 100%

307 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-20 19:17 +0000

1"""Structured command contracts for adapters and parity tests. 

2 

3The contract is intentionally plain JSON-compatible data. Agent adapters can read it before 

4mutating work starts, compare required capabilities with the current runtime, and execute the 

5same command graph without re-deriving keel behavior from prose. 

6""" 

7 

8from __future__ import annotations 

9 

10import re 

11from collections.abc import Mapping 

12from dataclasses import asdict 

13from pathlib import Path 

14from typing import Any 

15 

16from . import ( 

17 agents, 

18 artifacts, 

19 capture, 

20 checkpoint, 

21 closure, 

22 consent, 

23 evidence, 

24 gates, 

25 github_transport, 

26 install, 

27 intake, 

28 ledger, 

29 lock, 

30 loop, 

31 model, 

32 orchestrator, 

33 provenance, 

34 runcontrols, 

35 runtime, 

36 stepverifier, 

37 tdd, 

38 team, 

39 workblock, 

40 workcreation, 

41) 

42from . import config as cfg 

43from . import ship as ship_decisions 

44from .extensions import Extension 

45from .project_commands import get_project_command, list_project_commands 

46 

47SCHEMA_VERSION = "keel.command-contract.v1" 

48 

49_COMPOUND_OVERRIDES: dict[str, str] = { 

50 "s4": "compound", 

51 "s7": "compound", 

52 "s9": "compound", 

53 "s11": "compound", 

54} 

55 

56_STEP_RE = re.compile( 

57 r"^#{2,3}\s+(?P<id>(?:Step\s+[0-9A-Za-z.]+|s\d+))\s*(?:[\u2014-]\s*)?" 

58 r"(?P<name>.*)$" 

59) 

60 

61_BASE_SIDE_EFFECTS: dict[str, tuple[str, ...]] = { 

62 "ship": ( 

63 "git_worktree", 

64 "git_branch", 

65 "file_edit", 

66 "git_push", 

67 "pull_request", 

68 "comments", 

69 "reviews", 

70 "merge", 

71 "issue_close", 

72 "capture", 

73 ), 

74 "pr-loop": ("file_edit", "git_commit", "git_push", "comments", "reviews", "check_runs"), 

75 "review-cycle": ("file_edit", "comments", "reviews", "git_commit", "git_push"), 

76 "morning": ("issue_read", "pr_read", "report_write"), 

77 "wrap": ("git_commit", "git_push", "pull_request", "session_recap"), 

78 "work-block": ( 

79 "git_branch", 

80 "git_push", 

81 "pull_request", 

82 "comments", 

83 "reviews", 

84 "merge", 

85 "deferral_queue", 

86 "session_report", 

87 ), 

88 "overnight": ( 

89 "git_branch", 

90 "git_push", 

91 "pull_request", 

92 "comments", 

93 "reviews", 

94 "merge", 

95 "deferral_queue", 

96 "session_report", 

97 ), 

98 "implement": ( 

99 "git_worktree", 

100 "git_branch", 

101 "file_edit", 

102 "git_commit", 

103 "git_push", 

104 "pull_request", 

105 "comments", 

106 ), 

107 "ci-check": ("check_runs",), 

108 "triage": ("labels", "comments"), 

109 "stale-prs": ("comments", "git_checkout", "git_push"), 

110 "regression": ("git_worktree", "issue_write", "labels"), 

111 "review-all-day": ("issue_write", "labels"), 

112 "coverage": ("git_worktree", "git_checkout", "comments", "labels", "issue_write"), 

113 "deps-audit": ("comments", "issue_write"), 

114 "flake-audit": ("issue_write", "comments"), 

115} 

116 

117_DEFAULT_FEEDBACK_WORKFLOWS: dict[str, dict[str, Any]] = { 

118 "pr-loop": { 

119 "posting_mode": "summary", 

120 "posting_owner": "orchestrator", 

121 "reviewer_isolation": { 

122 "shared_with_ship": True, 

123 "codename_prefix": "PR-LOOP", 

124 "no_cross_reading": True, 

125 }, 

126 "inputs": { 

127 "auto_detect_current_branch": True, 

128 "explicit_pr_targets": True, 

129 "reads_review_comments": True, 

130 "reads_issue_conversation_comments": True, 

131 }, 

132 "ci": { 

133 "recheck_after_push": True, 

134 "green_required_to_exit": True, 

135 "degrade_when_logs_unavailable": True, 

136 }, 

137 "fix_loop": { 

138 "budget": 3, 

139 "self_review_before_push": True, 

140 "reviewer_fanout_after_each_push": True, 

141 }, 

142 "completion": { 

143 "marker": None, 

144 "merge": "handoff", 

145 "summary_comment": True, 

146 }, 

147 }, 

148 "review-cycle": { 

149 "posting_mode": "inline", 

150 "posting_owner": "orchestrator", 

151 "reviewer_isolation": { 

152 "shared_with_ship": True, 

153 "codename_prefix": "REVIEW-CYCLE", 

154 "no_cross_reading": True, 

155 }, 

156 "inputs": { 

157 "multi_pr": True, 

158 "sequential_pr_processing": True, 

159 }, 

160 "review": { 

161 "parallel_reviewers_within_pr": True, 

162 "partial_reviewer_failures_degrade": True, 

163 "severity_histogram_source_of_truth": True, 

164 }, 

165 "fix_loop": { 

166 "budget": 3, 

167 "enabled": True, 

168 }, 

169 "completion": { 

170 "marker": "review-cycle-complete", 

171 "marker_after_summary": True, 

172 "merge": "never", 

173 "formal_approval": "never", 

174 }, 

175 }, 

176} 

177 

178_REPORTING_COMMANDS = {"coverage", "deps-audit", "flake-audit"} 

179 

180 

181def available_commands() -> tuple[str, ...]: 

182 """Every packaged adapter command that can expose a structured contract.""" 

183 return tuple(name.removesuffix(".md") for name in install.adapter_names()) 

184 

185 

186def command_graph(command: str, *, profile: str = "standard") -> list[dict[str, Any]]: 

187 """Return the command's step graph as JSON-compatible records. 

188 

189 ``ship`` uses the fixed keel backbone as the canonical graph. When the ``compound`` 

190 profile is selected, the s4/s7/s9/s11 steps are marked as compound overrides. Other 

191 commands expose their adapter step headings, so adapters can still reason about their 

192 command-local sequence without parsing Markdown themselves. 

193 """ 

194 if command == "ship": 

195 compound = profile == "compound" 

196 return [ 

197 { 

198 "step_id": step.id, 

199 "step_name": step.name, 

200 "agentic": step.agentic, 

201 "slot": step.slot, 

202 "source": "backbone", 

203 "profile_step": _COMPOUND_OVERRIDES.get(step.id, "standard") 

204 if compound 

205 else "standard", 

206 } 

207 for step in model.BACKBONE 

208 ] 

209 steps = _adapter_steps(command) 

210 return steps if steps else [] 

211 

212 

213def build_command_contract( 

214 *, 

215 command: str, 

216 profile: str = "standard", 

217 config: cfg.ProjectConfig, 

218 loaded: dict[str, list[Extension]], 

219 plan: tuple[orchestrator.PlanItem, ...], 

220 requirement: runtime.CapabilityRequirement, 

221 evaluation: runtime.CapabilityEvaluation, 

222 transport: github_transport.GitHubTransport, 

223 extension_problems: tuple[str, ...] = (), 

224 dry_run: bool = True, 

225 approved_consent_scopes: tuple[str, ...] = (), 

226 consent_approval_source: str = "flag", 

227 consent_mode: str = "explicit", 

228 operator: str | None = None, 

229 target: str | None = None, 

230 reviewer_override: int | None = None, 

231 review_tier: int | None = None, 

232 review_comments: str = "inline", 

233 jury: bool = False, 

234 no_jury: bool = False, 

235 jury_advisory: bool = False, 

236 issue_title: str | None = None, 

237 issue_body: str | None = None, 

238 #: The retrieved past learnings for this task (#1155), measured by the caller 

239 #: because reading a directory is I/O. The **plan** contract carries it as well 

240 #: as ship's: s4 composes the implement brief from what `keel plan` printed, 

241 #: long before s5 runs `keel ship`, so wiring it into ship alone meant the brief 

242 #: this feature exists for never saw a lesson. 

243 learnings: dict[str, Any] | None = None, 

244 issue_labels: tuple[str, ...] = (), 

245 role: str | None = None, 

246 delegate: str | None = None, 

247 review_delegates: tuple[str, ...] = (), 

248 host_agent: str = agents.HOST_DEFAULT, 

249 tdd_override: bool = False, 

250 loop_override: bool = False, 

251 #: An explicit `--max-iterations` budget for this run, which outranks both the 

252 #: flag and the knob and publishes its own source (#1173). 

253 loop_budget: int | None = None, 

254 effort: str | None = None, 

255 team_profile: str | None = None, 

256 jury_availability: Mapping[str, Any] | None = None, 

257) -> dict[str, Any]: 

258 """Build the stable adapter contract shared by ``plan --json`` and dry-run commands. 

259 

260 ``tdd_override`` is the per-run ``--tdd`` flag. The resolved s4 profile is published as 

261 ``implement_mode`` — a sibling of ``workflow_profile``, because ``tdd`` is an s4 profile 

262 the same way ``compound`` is a workflow one — and is what selects the ``tdd-order`` gate 

263 in the contract's ``gates`` list.""" 

264 implement_mode = tdd.resolve_mode(config.knobs.implement_mode, flag=tdd_override) 

265 # The s4 iteration policy rides inside `implement_mode` (#1165): it is not a third 

266 # profile but a policy around whichever profile is running, and `wraps` says which. 

267 loop_policy = loop.resolve( 

268 config.knobs.loop, 

269 flag=loop_override, 

270 implement_mode=implement_mode.name, 

271 max_iterations=loop_budget, 

272 ) 

273 declared_side_effects = command_side_effects(command, config, requirement, loaded) 

274 graph = command_graph(command, profile=profile) 

275 if not graph and (project_command := get_project_command(config, command)): 

276 graph = [ 

277 { 

278 "step_id": f"project-command:{project_command.name}", 

279 "step_name": project_command.name, 

280 "agentic": bool(project_command.agent_role), 

281 "slot": None, 

282 "source": "project_command", 

283 } 

284 ] 

285 contract = { 

286 "schema_version": SCHEMA_VERSION, 

287 "command": command, 

288 "mode": "dry-run" if dry_run else "live", 

289 "dry_run": dry_run, 

290 "no_mutations": dry_run, 

291 "project": project_as_dict(config), 

292 "workflow_profile": workflow_profile(command, profile=profile), 

293 "implement_mode": {**implement_mode.as_dict(), "loop": loop_policy.as_dict()}, 

294 "graph": graph, 

295 "backbone_plan": orchestrator.plan_as_dict(plan), 

296 "gates": [ 

297 gate_as_dict(spec) 

298 for spec in gates.plan_gates(config, loaded, implement_mode=implement_mode.name) 

299 ], 

300 "project_commands": [command.as_dict() for command in list_project_commands(config)], 

301 "extension_hooks": extension_hooks_as_dict(config, loaded), 

302 "extension_problems": list(extension_problems), 

303 "required_capabilities": list(requirement.required), 

304 "optional_capabilities": list(requirement.optional), 

305 "capabilities": evaluation.as_dict(), 

306 "github_transport": transport.as_dict(), 

307 "checkpoint": checkpoint.checkpoint_contract_as_dict(config), 

308 "capture": capture.contract_as_dict(config), 

309 # The same block `keel ship` publishes, so s4 can open the implement brief 

310 # from the plan it was told not to re-derive. 

311 "learnings": learnings if learnings is not None else capture.learning_retrieval_as_dict(), 

312 "run_ledger": ledger.ledger_contract_as_dict(config), 

313 "resource_claims": lock.contract_as_dict(), 

314 "side_effects": { 

315 "declared": list(declared_side_effects), 

316 "mutates_in_dry_run": False, 

317 }, 

318 "operator_consent": consent.build_consent_contract( 

319 command=command, 

320 side_effects=declared_side_effects, 

321 dry_run=dry_run, 

322 approved_scopes=approved_consent_scopes, 

323 approval_source=consent_approval_source, 

324 mode=consent_mode, 

325 operator=operator, 

326 target=target, 

327 ), 

328 "agent_output_provenance": provenance.contract_as_dict(), 

329 } 

330 if command == "morning": 

331 contract["morning_contract"] = morning_contract_as_dict( 

332 config=config, 

333 evaluation=evaluation, 

334 transport=transport, 

335 ) 

336 if command in _REPORTING_COMMANDS: 

337 contract["reporting_contract"] = reporting_contract_as_dict( 

338 command=command, 

339 config=config, 

340 transport=transport, 

341 ) 

342 if command in {"wrap", "work-block", "overnight"}: 

343 contract["session_contract"] = session_contract_as_dict( 

344 command=command, 

345 config=config, 

346 transport=transport, 

347 delegation=workblock.delegation_as_dict( 

348 delegate=delegate, 

349 review_delegates=review_delegates, 

350 effort=effort, 

351 team_profile=team_profile, 

352 reviewer_override=reviewer_override, 

353 ), 

354 ) 

355 if command in {"regression", "review-all-day"}: 

356 contract["scan_contract"] = scan_contract_as_dict( 

357 command=command, 

358 config=config, 

359 transport=transport, 

360 ) 

361 if command == "triage": 

362 contract["triage_contract"] = { 

363 "scope": "label-only-advisory", 

364 "one_comment_per_issue": True, 

365 "renderer": "keel.artifacts.render_triage_audit", 

366 "marker": artifacts.TRIAGE_AUDIT_MARKER, 

367 } 

368 if command in {"ship", "pr-loop", "review-cycle", "work-block", "overnight"}: 

369 # Resolved once and shared: the reviewer bench the contract publishes and the 

370 # assignment a host dispatches have to be the same answer, or two agents reading 

371 # the same JSON run different teams (#1014). 

372 assignment = team.resolve_assignment( 

373 config.knobs.team, 

374 tier=review_tier, 

375 role=role, 

376 default_count=ship_decisions.reviewer_count(review_tier or 2), 

377 reviewer_override=reviewer_override, 

378 delegate=delegate, 

379 review_delegates=review_delegates, 

380 host_agent=host_agent, 

381 legacy=agents.legacy_team_seats(config), 

382 jury_disabled=no_jury, 

383 jury_advisory=jury_advisory, 

384 team_profile=team_profile, 

385 effort=effort, 

386 # The panel-availability probe, measured by 

387 # `keel.providerprobe.jury_availability` and handed to every resolver 

388 # (#1066). This is one more site that resolves a bench, and it has to see 

389 # the same measurement as the rest or `keel plan` publishes a panel the run 

390 # it plans cannot convene. 

391 jury_availability=jury_availability, 

392 ) 

393 contract["assignment"] = assignment 

394 contract["review_merge_contract"] = ship_decisions.resolve_review_contract( 

395 tier=review_tier, 

396 reviewer_override=reviewer_override, 

397 review_comments=review_comments, 

398 gates=config.gates, 

399 policy_pack=config.policy_pack, 

400 jury=jury, 

401 no_jury=no_jury, 

402 jury_advisory=jury_advisory, 

403 require_distinct_vendors=config.knobs.evidence_require_distinct_vendors, 

404 assignment=assignment, 

405 learnings=learnings, 

406 ) 

407 if command == "ship": 

408 contract["evidence"] = evidence.contract_as_dict( 

409 contract["review_merge_contract"], 

410 dry_run=dry_run, 

411 ) 

412 contract["step_verification"] = stepverifier.contract_as_dict( 

413 contract["review_merge_contract"], 

414 dry_run=dry_run, 

415 ) 

416 contract["run_controls"] = runcontrols.contract_as_dict() 

417 if command == "ship": 

418 contract["closure_comment"] = closure.contract_as_dict() 

419 contract["artifact_renderers"] = artifacts.contract_as_dict() 

420 if command in {"ship", "implement", "overnight"}: 

421 contract["issue_intake"] = intake.assess_issue( 

422 title=issue_title, 

423 body=issue_body, 

424 labels=issue_labels, 

425 ) 

426 if command in {"pr-loop", "review-cycle"}: 

427 contract["feedback_workflow"] = feedback_workflow_as_dict(config, command) 

428 return contract 

429 

430 

431def workflow_profile(command: str, *, profile: str = "standard") -> dict[str, Any]: 

432 """First-class workflow profile metadata for command variants. 

433 

434 ``ship`` carries the ``standard`` profile by default; selecting the ``compound`` 

435 profile swaps the s4/s7/s9/s11 steps to compound step overrides without forking the 

436 backbone. 

437 """ 

438 if command == "ship" and profile == "compound": 

439 return { 

440 "name": "ship", 

441 "profile": "compound", 

442 "inherits": "ship", 

443 "first_class_variant": True, 

444 "shared_primitives": [ 

445 "select", 

446 "branch", 

447 "worktree", 

448 "guard", 

449 "classify", 

450 "ci", 

451 "test", 

452 "merge_window", 

453 "merge_lock", 

454 "merge", 

455 "capture_marker", 

456 "close", 

457 ], 

458 "step_overrides": { 

459 "s4": { 

460 "step": "implement", 

461 "mode": "compound", 

462 "reason": "compound implement and PR-quality pass", 

463 }, 

464 "s7": { 

465 "step": "review", 

466 "mode": "compound", 

467 "reason": "persona and diff-aware reviewer fan-out", 

468 }, 

469 "s9": { 

470 "step": "fixloop", 

471 "mode": "compound", 

472 "reason": "structured PR-feedback resolution", 

473 }, 

474 "s11": { 

475 "step": "capture", 

476 "mode": "compound", 

477 "reason": "durable-learning capture", 

478 }, 

479 }, 

480 } 

481 if command == "pr-loop": 

482 return { 

483 "name": "pr-loop", 

484 "profile": "feedback-loop", 

485 "inherits": "ship.s6-s9", 

486 "first_class_variant": True, 

487 "shared_primitives": [ 

488 "linked_worktree_preflight", 

489 "github_transport", 

490 "reviewer_isolation", 

491 "ci_recheck", 

492 "fixloop", 

493 "summary_comment", 

494 "operator_consent", 

495 ], 

496 "step_overrides": { 

497 "merge": { 

498 "mode": "handoff", 

499 "reason": "pr-loop exits after feedback and CI are satisfied.", 

500 }, 

501 }, 

502 } 

503 if command == "review-cycle": 

504 return { 

505 "name": "review-cycle", 

506 "profile": "review-feedback", 

507 "inherits": "ship.s7-s9", 

508 "first_class_variant": True, 

509 "shared_primitives": [ 

510 "multi_pr_targets", 

511 "reviewer_isolation", 

512 "posting_mode", 

513 "severity_histogram", 

514 "fixloop", 

515 "completion_marker", 

516 "operator_consent", 

517 ], 

518 "step_overrides": { 

519 "merge": { 

520 "mode": "never", 

521 "reason": "review-cycle never merges or posts formal approval.", 

522 }, 

523 }, 

524 } 

525 if command == "implement": 

526 return { 

527 "name": "implement", 

528 "profile": "standalone-step", 

529 "inherits": "ship.s4", 

530 "first_class_variant": True, 

531 "shared_primitives": [ 

532 "issue_target", 

533 "branch", 

534 "worktree", 

535 "implementer_routing", 

536 "operator_consent", 

537 "handoff", 

538 ], 

539 "step_overrides": {}, 

540 } 

541 if command == "ci-check": 

542 return { 

543 "name": "ci-check", 

544 "profile": "standalone-diagnostic", 

545 "inherits": None, 

546 "first_class_variant": True, 

547 "shared_primitives": [ 

548 "github_transport", 

549 "check_runs", 

550 "latest_run_context", 

551 "log_diagnostics", 

552 "read_only", 

553 "routing_recommendation", 

554 ], 

555 "step_overrides": {}, 

556 } 

557 if command == "morning": 

558 return { 

559 "name": "morning", 

560 "profile": "daily-brief", 

561 "inherits": None, 

562 "first_class_variant": True, 

563 "shared_primitives": [ 

564 "date_window", 

565 "deferral_queue", 

566 "shipped_since", 

567 "github_summary", 

568 "health_providers", 

569 "priority_sources", 

570 "ranked_focus", 

571 "report_output", 

572 ], 

573 "step_overrides": {}, 

574 } 

575 if command == "wrap": 

576 return { 

577 "name": "wrap", 

578 "profile": "session-wrap", 

579 "inherits": None, 

580 "first_class_variant": True, 

581 "shared_primitives": [ 

582 "linked_worktree_preflight", 

583 "base_branch_guard", 

584 "configured_gates", 

585 "conventional_commit", 

586 "ready_pr_create", 

587 "session_recap", 

588 "deferral_queue", 

589 "operator_consent", 

590 ], 

591 "step_overrides": {}, 

592 } 

593 if command == "overnight": 

594 return { 

595 "name": "overnight", 

596 "profile": "session-overnight", 

597 "inherits": "ship", 

598 "first_class_variant": True, 

599 "shared_primitives": [ 

600 "work_block", 

601 "merge_window", 

602 "ship_handoff", 

603 "priority_queue", 

604 "per_issue_worktree", 

605 "no_night_merge", 

606 "blocker_policy", 

607 "session_report", 

608 "deferral_queue", 

609 "stop_conditions", 

610 "operator_consent", 

611 ], 

612 "step_overrides": {}, 

613 } 

614 if command == "work-block": 

615 return { 

616 "name": "work-block", 

617 "profile": "session-work-block-daytime", 

618 "inherits": "ship", 

619 "first_class_variant": True, 

620 "shared_primitives": [ 

621 "work_block", 

622 "queue_snapshot", 

623 "readiness_refresh", 

624 "ship_handoff", 

625 "per_issue_worktree", 

626 "operator_between_item_control", 

627 "progress_snapshot", 

628 "session_report", 

629 "deferral_queue", 

630 "stop_conditions", 

631 "operator_consent", 

632 ], 

633 "step_overrides": {}, 

634 } 

635 if command in _REPORTING_COMMANDS: 

636 return { 

637 "name": command, 

638 "profile": "reporting", 

639 "inherits": None, 

640 "first_class_variant": True, 

641 "shared_primitives": [ 

642 "project_policy", 

643 "github_transport", 

644 "codename_anchor", 

645 "dedupe", 

646 "dry_run_no_mutations", 

647 "ship_handoff", 

648 "operator_consent", 

649 ], 

650 "step_overrides": {}, 

651 } 

652 if command == "regression": 

653 return { 

654 "name": "regression", 

655 "profile": "scan-and-file", 

656 "inherits": None, 

657 "first_class_variant": True, 

658 "shared_primitives": [ 

659 "canonical_base_scan", 

660 "clean_tree_preflight", 

661 "read_only_worktree", 

662 "area_fanout", 

663 "reviewer_isolation", 

664 "confidence_filter", 

665 "dedupe", 

666 "issue_lock", 

667 "issue_create", 

668 "ship_handoff", 

669 "final_report", 

670 "operator_consent", 

671 ], 

672 "step_overrides": {}, 

673 } 

674 if command == "review-all-day": 

675 return { 

676 "name": "review-all-day", 

677 "profile": "time-window-scan", 

678 "inherits": None, 

679 "first_class_variant": True, 

680 "shared_primitives": [ 

681 "merge_window_span", 

682 "remote_ref_scope", 

683 "batch_or_fanout", 

684 "reviewer_isolation", 

685 "diff_truncation", 

686 "finding_filter", 

687 "dedupe", 

688 "issue_prefix", 

689 "issue_create", 

690 "final_report", 

691 "operator_consent", 

692 ], 

693 "step_overrides": {}, 

694 } 

695 if command == "ship": 

696 return { 

697 "name": "ship", 

698 "profile": "standard", 

699 "inherits": None, 

700 "first_class_variant": True, 

701 "shared_primitives": [ 

702 "select", 

703 "branch", 

704 "guard", 

705 "implement", 

706 "classify", 

707 "ci", 

708 "review", 

709 "test", 

710 "fixloop", 

711 "merge", 

712 "capture", 

713 "close", 

714 ], 

715 "step_overrides": {}, 

716 } 

717 return { 

718 "name": command, 

719 "profile": "adapter", 

720 "inherits": None, 

721 "first_class_variant": False, 

722 "shared_primitives": [], 

723 "step_overrides": {}, 

724 } 

725 

726 

727def command_side_effects( 

728 command: str, 

729 config: cfg.ProjectConfig, 

730 requirement: runtime.CapabilityRequirement, 

731 loaded: dict[str, list[Extension]], 

732) -> tuple[str, ...]: 

733 """Return command side effects plus project capability-derived consent effects.""" 

734 effects: list[str] = list(_BASE_SIDE_EFFECTS.get(command, ())) 

735 if project_command := get_project_command(config, command): 

736 effects.extend(project_command.side_effects) 

737 effects.extend(consent.capability_side_effects(requirement.required)) 

738 effects.extend(consent.capability_side_effects(requirement.optional)) 

739 for extensions in loaded.values(): 

740 for ext in extensions: 

741 effects.extend(consent.capability_side_effects(ext.required_capabilities)) 

742 effects.extend(consent.capability_side_effects(ext.optional_capabilities)) 

743 return tuple(dict.fromkeys(effects)) 

744 

745 

746def reporting_contract_as_dict( 

747 *, 

748 command: str, 

749 config: cfg.ProjectConfig, 

750 transport: github_transport.GitHubTransport | None = None, 

751) -> dict[str, Any]: 

752 """Project-neutral reporting parity contract for audit/report adapters.""" 

753 github = transport.as_dict() if transport is not None else {} 

754 base = { 

755 "command": command, 

756 "base_branch": config.base_branch, 

757 "timezone": config.timezone, 

758 "github_transport": github, 

759 "policy_source": "policy_pack + adapter arguments", 

760 "dry_run": { 

761 "mutates": False, 

762 "prints_planned_writes": True, 

763 }, 

764 "handoff": { 

765 "fixes_route_to": "ship", 

766 "auto_applies_fixes": False, 

767 }, 

768 "work_creation_policy": workcreation.contract_as_dict( 

769 near_text_similarity=_near_text_similarity(config), 

770 ), 

771 } 

772 if command == "coverage": 

773 return { 

774 **base, 

775 "target": "pull_request", 

776 "codename_prefix": "COVERAGE-<PR>-", 

777 "renderer": "keel.artifacts.render_coverage_delta", 

778 "marker": artifacts.COVERAGE_DELTA_MARKER, 

779 "idempotency": { 

780 "scope": "one-comment-per-pr", 

781 "find_by_first_line_prefix": "COVERAGE-<PR>-", 

782 "existing_comment": "update-in-place", 

783 "update_unavailable": "do-not-post-duplicate", 

784 }, 

785 "labels": { 

786 "regression": "coverage-regression", 

787 "operation": "idempotent-add-or-remove", 

788 }, 

789 "degradation": { 

790 "unwired_tool": "skip-area", 

791 "coverage_command_failure": "fatal", 

792 }, 

793 "arguments": ["pr", "--base", "--threshold", "--changed", "--open-issues", "--dry-run"], 

794 } 

795 if command == "deps-audit": 

796 return { 

797 **base, 

798 "target": "daily_tracking_issue", 

799 "tracking_issue_title": "deps-audit: <DATE>", 

800 "codename_prefix": "DEPS-AUDIT-<DATE>-", 

801 "renderer": "keel.artifacts.render_deps_audit", 

802 "marker": artifacts.DEPS_AUDIT_MARKER, 

803 "idempotency": { 

804 "scope": "append-per-run", 

805 "find_tracking_issue_by_exact_title": "deps-audit: <DATE>", 

806 "find_latest_run_by_first_line_prefix": "DEPS-AUDIT-<DATE>-", 

807 "existing_comment": "append-fresh-run-comment", 

808 }, 

809 "degradation": { 

810 "per_ecosystem_failure": "skipped-section", 

811 "argument_failure": "fatal", 

812 }, 

813 "arguments": [ 

814 "ecosystem", 

815 "--severity", 

816 "--security-only", 

817 "--open-issues", 

818 "--dry-run", 

819 ], 

820 } 

821 if command == "flake-audit": 

822 return { 

823 **base, 

824 "target": "ci_history_or_local_runs", 

825 "codename_prefix": "FLAKE-AUDIT-<DATE>-", 

826 "renderer": "keel.artifacts.render_flake_audit", 

827 "marker": artifacts.FLAKE_AUDIT_MARKER, 

828 "idempotency": { 

829 "scope": "one-issue-per-flake", 

830 "dedupe_issue_title": "flaky test: <fully.qualified.name>", 

831 "find_run_by_first_line_prefix": "FLAKE-AUDIT-<DATE>-", 

832 }, 

833 "classification": { 

834 "rule": "across-run-disagreement-only", 

835 "minimum_failures": 3, 

836 "consistent_failures": "real-bug-not-flake", 

837 }, 

838 "degradation": { 

839 "artifact_unavailable": "run-level-limitations-section", 

840 "no_ci_or_local_gate": "clean-exit", 

841 }, 

842 "arguments": ["--days", "--runs", "--threshold", "--open-issues", "--dry-run"], 

843 } 

844 return base 

845 

846 

847def project_as_dict(config: cfg.ProjectConfig) -> dict[str, Any]: 

848 """Resolved project config summary safe for adapter planning.""" 

849 return { 

850 "config_hash": cfg.config_hash(config), 

851 "extends": config.extends, 

852 "core_version": config.core_version, 

853 "base_branch": config.base_branch, 

854 "owner": config.owner, 

855 "repo": config.repo, 

856 "platform": config.platform, 

857 "timezone": config.timezone, 

858 "merge_window": config.merge_window, 

859 "merge_window_mode": config.merge_window_mode, 

860 "extensions_dir": config.extensions_dir, 

861 "gates": list(config.gates), 

862 "extensions": {slot: list(files) for slot, files in sorted(config.extensions.items())}, 

863 "policy_pack": config.policy_pack, 

864 "knobs": { 

865 "build_gate_cmd": config.knobs.build_gate_cmd, 

866 "lint_cmd": config.knobs.lint_cmd, 

867 "implementer_agents": dict(sorted(config.knobs.implementer_agents.items())), 

868 **cfg.delegate_profiles_dict(config), 

869 **team.canonical(config.knobs.team), 

870 "tier3_globs": list(config.knobs.tier3_globs), 

871 "ci_workflows": dict(sorted(config.knobs.ci_workflows.items())), 

872 "docs_gate_paths": list(config.knobs.docs_gate_paths), 

873 "docs_only_allowlist": list(config.knobs.docs_only_allowlist), 

874 "sot_doc": config.knobs.sot_doc, 

875 "required_capabilities": list(config.knobs.required_capabilities), 

876 "optional_capabilities": list(config.knobs.optional_capabilities), 

877 }, 

878 } 

879 

880 

881def gate_as_dict(spec: gates.GateSpec) -> dict[str, Any]: 

882 """Render a planned gate without losing its capability declarations.""" 

883 return asdict(spec) 

884 

885 

886def gate_outcome_as_dict(outcome: gates.GateOutcome) -> dict[str, Any]: 

887 """One gate outcome as ``keel ship --json`` and ``keel run-gates --json`` publish it. 

888 

889 The severity and whether the gate ran at all travel with it (#1165): ``keel loop 

890 brief`` reads these documents, and without them a failing *soft* gate would hold the 

891 loop open and an unrun blocking gate would read as a pass. ``unconfigured`` says the 

892 gate cannot judge at all — no command, or no gate planned — which the loop stops on 

893 at once rather than iterating against (#1364). 

894 """ 

895 return { 

896 "gate": outcome.gate, 

897 "ok": outcome.ok, 

898 "skipped": outcome.skipped, 

899 "timed_out": outcome.timed_out, 

900 "on_fail": outcome.on_fail, 

901 "not_run": outcome.not_run, 

902 "unconfigured": outcome.unconfigured, 

903 "error": outcome.error, 

904 "findings": [_finding_as_dict(finding) for finding in outcome.findings], 

905 **( 

906 {"reused_from": outcome.reused_from.as_dict()} 

907 if outcome.reused_from is not None 

908 else {} 

909 ), 

910 } 

911 

912 

913def extension_hooks_as_dict( 

914 config: cfg.ProjectConfig, loaded: dict[str, list[Extension]] 

915) -> dict[str, list[dict[str, Any]]]: 

916 """Render loaded extension hooks grouped by backbone slot.""" 

917 return { 

918 slot: [ 

919 { 

920 "id": ext.id, 

921 "slot": ext.slot, 

922 "kind": ext.kind, 

923 "mode": ext.mode, 

924 "agent": ext.agent, 

925 "on_fail": ext.on_fail, 

926 "anchorable": ext.anchorable, 

927 "source": ext.source, 

928 "has_run": ext.run is not None, 

929 "has_prompt": ext.prompt is not None or bool(ext.body.strip()), 

930 "required_capabilities": list(ext.required_capabilities), 

931 "optional_capabilities": list(ext.optional_capabilities), 

932 } 

933 for ext in loaded.get(slot, []) 

934 ] 

935 for slot in model.SLOTS 

936 } 

937 

938 

939def ship_result_as_dict( 

940 *, 

941 changed_files: list[str] | None, 

942 outcomes: list[gates.GateOutcome], 

943 verdict, 

944 assessment, 

945 issue_intake: dict[str, Any] | None = None, 

946 run_ledger: dict[str, Any] | None = None, 

947 jury_consensus: str | None = None, 

948 base_facts: bool = False, 

949) -> dict[str, Any]: 

950 """Normalized deterministic result record for ``keel ship --json``. 

951 

952 ``base_facts`` is ``team.jury.base_facts`` (#1570): the rendered ``pr_body`` then 

953 carries the ``## Base facts`` section the jury is handed ahead of the diff. 

954 

955 ``jury_consensus`` is the panel's own verdict (the chair's, as 

956 :func:`keel.jury.jury_verdict` reports it) when the caller has one; the 

957 ``jury_verdict_template`` renders it, and renders 

958 :data:`keel.artifacts.JURY_CONSENSUS_PLACEHOLDER` — which the evidence gate reads as 

959 no approval — when it has none (#1429). 

960 """ 

961 closure_comment = None 

962 issue_number = None 

963 pr_number = None 

964 head_sha = None 

965 run_id = None 

966 implementer_attribution = None 

967 if isinstance(run_ledger, dict): 

968 record = run_ledger.get("record") 

969 if isinstance(record, dict): 

970 closure_comment = closure.render_closure_comment(record) 

971 issue = record.get("issue") 

972 pull_request = record.get("pull_request") 

973 issue_number = issue.get("number") if isinstance(issue, dict) else None 

974 pr_number = pull_request.get("number") if isinstance(pull_request, dict) else None 

975 head_sha = record.get("head_sha") 

976 head_sha = head_sha if isinstance(head_sha, str) else None 

977 run_id = record.get("run_id") 

978 run_id = run_id if isinstance(run_id, str) else None 

979 # Derived from the record, never from a caller-supplied string: the 

980 # provenance comment and the evidence cross-check must read the same 

981 # implementer through the same helper (#1013). 

982 implementer_attribution = agents.attribution_from_implementer( 

983 evidence.ledger_implementer(record) 

984 ) 

985 finding_dicts = [_finding_as_dict(finding) for finding in verdict.findings] 

986 testing = _testing_summary(outcomes) 

987 artifact_bodies = { 

988 "pr_body": artifacts.render_pr_body( 

989 issue_number=issue_number, 

990 issue_intake=issue_intake, 

991 changed_files=changed_files, 

992 testing=testing, 

993 docs_impact=_docs_impact(changed_files), 

994 base_facts=base_facts, 

995 ), 

996 "issue_update": artifacts.render_issue_update( 

997 issue_number=issue_number, 

998 pull_request=pr_number, 

999 status="ready-for-merge" if not verdict.blocked else "blocked", 

1000 summary=assessment.merge.reason, 

1001 next_step="Merge when CI and evidence are green." 

1002 if not verdict.blocked 

1003 else "Resolve blocking findings before merge.", 

1004 ), 

1005 "review_verdict_template": artifacts.render_review_verdict( 

1006 reviewer="reviewer", 

1007 head_sha=head_sha, 

1008 verdict="REQUEST_CHANGES" if verdict.blocked else "LGTM", 

1009 scope="Full changed-file diff and keel command contract.", 

1010 findings=finding_dicts, 

1011 testing="; ".join(testing) if testing else "See PR Testing section.", 

1012 ), 

1013 # The consensus is the panel's, never this run's gate verdict (#1429): an unblocked 

1014 # ship says nothing about what the panel concluded, and a template that wrote 

1015 # `LGTM` there approved for a panel that may have rejected the change. Without a 

1016 # consensus it carries a placeholder the evidence gate reads as no approval. 

1017 "jury_verdict_template": artifacts.render_jury_verdict( 

1018 head_sha=head_sha, 

1019 participants=("reviewer-a", "reviewer-b", "reviewer-c", "orchestrator"), 

1020 verdict=jury_consensus or artifacts.JURY_CONSENSUS_PLACEHOLDER, 

1021 findings_summary=_finding_summaries(finding_dicts), 

1022 remaining_risks=( 

1023 ship_decisions.block_reason(verdict) if verdict.blocked else "none identified" 

1024 ), 

1025 ), 

1026 "extension_result_template": artifacts.render_extension_result( 

1027 slot="<slot>", 

1028 extension_id="<extension-id>", 

1029 status="not-run", 

1030 mode="advisory", 

1031 summary="Extension result summary goes here.", 

1032 ), 

1033 "ship_provenance": artifacts.render_ship_provenance( 

1034 run_id=run_id, 

1035 issue=issue_number, 

1036 head_sha=head_sha, 

1037 implementer_attribution=implementer_attribution, 

1038 ), 

1039 } 

1040 return { 

1041 # None stays None: "could not read the diff" must not report as "0 files". 

1042 "changed_files": None if changed_files is None else list(changed_files), 

1043 "changed_file_count": None if changed_files is None else len(changed_files), 

1044 "changed_files_unreadable": changed_files is None, 

1045 "issue_intake": issue_intake, 

1046 "run_ledger": run_ledger, 

1047 "closure_comment": closure_comment, 

1048 "artifact_bodies": artifact_bodies, 

1049 "gate_outcomes": [gate_outcome_as_dict(outcome) for outcome in outcomes], 

1050 "verdict": { 

1051 "blocked": verdict.blocked, 

1052 "counts": dict(verdict.counts), 

1053 "findings": [_finding_as_dict(finding) for finding in verdict.findings], 

1054 }, 

1055 "assessment": { 

1056 "tier": assessment.tier, 

1057 "reviewers": assessment.reviewers, 

1058 "window_open": assessment.window_open, 

1059 "ci_ok": assessment.ci_ok, 

1060 "merge": { 

1061 "action": assessment.merge.action, 

1062 "reason": assessment.merge.reason, 

1063 }, 

1064 "halted": assessment.halted, 

1065 "bypassed_window": assessment.bypassed_window, 

1066 "review_merge_contract": assessment.review_contract, 

1067 "assignment": assessment.assignment, 

1068 }, 

1069 } 

1070 

1071 

1072def _testing_summary(outcomes: list[gates.GateOutcome]) -> list[str]: 

1073 if not outcomes: 

1074 return [] 

1075 lines: list[str] = [] 

1076 for outcome in outcomes: 

1077 if outcome.skipped: 

1078 state = "skipped" 

1079 elif outcome.ok: 

1080 state = "passed" 

1081 elif outcome.timed_out: 

1082 # Still a blocking outcome — but "failed" would read as a broken test. 

1083 state = "timed out" 

1084 else: 

1085 state = "failed" 

1086 suffix = f" ({outcome.error})" if outcome.error else "" 

1087 lines.append(f"{outcome.gate}: {state}{suffix}") 

1088 return lines 

1089 

1090 

1091def _docs_impact(changed_files: list[str] | None) -> str: 

1092 if changed_files is None: 

1093 return "Docs Impact: unknown — the changed-file list could not be read from git." 

1094 docs = [file for file in changed_files if _is_doc_path(file)] 

1095 if docs: 

1096 return "Updated docs: " + ", ".join(f"`{file}`" for file in docs) 

1097 return "Docs Impact: none — no documentation files changed." 

1098 

1099 

1100def _is_doc_path(file: str) -> bool: 

1101 lowered = file.lower() 

1102 return ( 

1103 "/docs/" in f"/{lowered}" 

1104 or lowered.startswith("docs/") 

1105 or lowered.endswith((".md", ".mdx", ".rst", ".adoc")) 

1106 ) 

1107 

1108 

1109def _finding_summaries(findings: list[dict[str, Any]]) -> list[str]: 

1110 return [ 

1111 f"{finding['severity']}: {finding['message']}" 

1112 for finding in findings 

1113 if isinstance(finding.get("severity"), str) and isinstance(finding.get("message"), str) 

1114 ] 

1115 

1116 

1117def standalone_result_as_dict( 

1118 *, 

1119 command: str, 

1120 config: cfg.ProjectConfig, 

1121 target: str | None = None, 

1122 delegate: str | None = None, 

1123 transport: github_transport.GitHubTransport | None = None, 

1124 evaluation: runtime.CapabilityEvaluation | None = None, 

1125 delegation: dict[str, Any] | None = None, 

1126) -> dict[str, Any]: 

1127 """Deterministic dry-run result records for standalone non-ship commands.""" 

1128 if command == "implement": 

1129 issue_id = _target_identifier(target) 

1130 return { 

1131 "command": command, 

1132 "target": target, 

1133 "base_branch": config.base_branch, 

1134 "branch_pattern": f"feature/issue-{issue_id}-<slug>", 

1135 "worktree_path_pattern": f"worktrees/issue-{issue_id}", 

1136 "implementer": { 

1137 "source": "delegate" if delegate else "project-routing-or-host", 

1138 "selected": delegate, 

1139 # Sorted here, not in the rule: the contract's ordering is the contract's 

1140 # business. Which spellings name a role is `agents.known_roles`'. 

1141 "routing_keys": sorted(agents.known_roles(config)), 

1142 }, 

1143 "handoff": { 

1144 "opens_pr": True, 

1145 "merges": False, 

1146 "next_commands": ["ship", "pr-loop"], 

1147 }, 

1148 } 

1149 if command == "ci-check": 

1150 resolved = transport.as_dict() if transport is not None else {} 

1151 return { 

1152 "command": command, 

1153 "target": target, 

1154 "base_branch": config.base_branch, 

1155 "ci_workflows": dict(sorted(config.knobs.ci_workflows.items())), 

1156 "latest_run_context": { 

1157 "limit": 3, 

1158 "selected": "newest available run", 

1159 "history": "previous runs used for flake or infra classification", 

1160 }, 

1161 "diagnostics": { 

1162 "read_only": True, 

1163 "log_tail": "available when the selected GitHub transport exposes logs", 

1164 "classifications": ["real-failure", "flake", "infra-or-quota"], 

1165 "proposed_fix_count": 1, 

1166 }, 

1167 "github_transport": resolved, 

1168 "routing": { 

1169 "never_direct_merge": True, 

1170 "recommendations": ["review-cycle", "pr-loop", "ship", "flake-audit"], 

1171 }, 

1172 } 

1173 if command == "morning": 

1174 return { 

1175 "command": command, 

1176 "target": target, 

1177 "base_branch": config.base_branch, 

1178 "brief": morning_contract_as_dict( 

1179 config=config, 

1180 evaluation=evaluation, 

1181 transport=transport, 

1182 ), 

1183 "execution": { 

1184 "runs_project_health_commands": False, 

1185 "writes_reports": False, 

1186 "live_work_owner": "adapter-or-extension-after-consent", 

1187 }, 

1188 } 

1189 if command in {"wrap", "work-block", "overnight"}: 

1190 return { 

1191 "command": command, 

1192 "target": target, 

1193 "base_branch": config.base_branch, 

1194 "session": session_contract_as_dict( 

1195 command=command, 

1196 config=config, 

1197 transport=transport, 

1198 delegation=delegation, 

1199 ), 

1200 "execution": { 

1201 "runs_gates": False, 

1202 "creates_prs": False, 

1203 "merges": False, 

1204 "writes_reports": False, 

1205 "live_work_owner": "adapter-after-consent", 

1206 }, 

1207 } 

1208 if command in {"pr-loop", "review-cycle"}: 

1209 workflow = feedback_workflow_as_dict(config, command) 

1210 return { 

1211 "command": command, 

1212 "target": target, 

1213 "base_branch": config.base_branch, 

1214 "feedback_workflow": workflow, 

1215 "execution": { 

1216 "commits": False, 

1217 "pushes": False, 

1218 "posts_comments": False, 

1219 "merges": False, 

1220 "live_work_owner": "adapter-after-consent", 

1221 }, 

1222 } 

1223 if command in {"regression", "review-all-day"}: 

1224 return { 

1225 "command": command, 

1226 "target": target, 

1227 "base_branch": config.base_branch, 

1228 "scan": scan_contract_as_dict( 

1229 command=command, 

1230 config=config, 

1231 transport=transport, 

1232 ), 

1233 "execution": { 

1234 "edits_code": False, 

1235 "pushes": False, 

1236 "merges": False, 

1237 "writes_issues": False, 

1238 "live_work_owner": "adapter-after-consent", 

1239 }, 

1240 } 

1241 return {"command": command, "target": target} 

1242 

1243 

1244def feedback_workflow_as_dict(config: cfg.ProjectConfig, command: str) -> dict[str, Any]: 

1245 """Return command-specific feedback-loop policy with project overrides applied.""" 

1246 defaults = _DEFAULT_FEEDBACK_WORKFLOWS.get(command, {}) 

1247 policy = _feedback_workflow_policy(config).get(command, {}) 

1248 return _deep_merge(defaults, policy) 

1249 

1250 

1251def scan_contract_as_dict( 

1252 *, 

1253 command: str, 

1254 config: cfg.ProjectConfig, 

1255 transport: github_transport.GitHubTransport | None = None, 

1256) -> dict[str, Any]: 

1257 """Project-neutral scan-and-file contract for regression and review-all-day.""" 

1258 pack = config.policy_pack or {} 

1259 reports = pack.get("reports") if isinstance(pack.get("reports"), dict) else {} 

1260 scan = pack.get("scan") if isinstance(pack.get("scan"), dict) else {} 

1261 areas = scan.get("areas") if isinstance(scan.get("areas"), dict) else {} 

1262 issue_labels = scan.get("issue_labels") if isinstance(scan.get("issue_labels"), dict) else {} 

1263 github = transport.as_dict() if transport is not None else {} 

1264 base = { 

1265 "timezone": config.timezone, 

1266 "merge_window": config.merge_window, 

1267 "base_branch": config.base_branch, 

1268 "github_transport": github, 

1269 "reports": _report_destinations(reports), 

1270 "project_policy_sources": { 

1271 "scan": "policy_pack.scan", 

1272 "areas": "policy_pack.scan.areas", 

1273 "active_branch_patterns": "policy_pack.scan.active_branch_patterns", 

1274 "risk_globs": "knobs.tier3_globs", 

1275 "labels": "policy_pack.labels + policy_pack.scan.issue_labels", 

1276 "ci_workflows": "knobs.ci_workflows", 

1277 }, 

1278 "write_safety": { 

1279 "dry_run_no_writes": True, 

1280 "orchestrator_only_writes": True, 

1281 "code_mutation": False, 

1282 "pr_mutation": False, 

1283 "issue_write_requires_consent": True, 

1284 }, 

1285 "dedupe": { 

1286 "source": "policy_pack.scan.dedupe + canonical defaults", 

1287 "path_token_boundary": True, 

1288 "type_must_match": True, 

1289 "near_text_similarity": _near_text_similarity(config), 

1290 "open_duplicate": "skip", 

1291 "closed_duplicate": "promote-regression-of", 

1292 "lock": "mkdir", 

1293 }, 

1294 "reviewer_isolation": { 

1295 "parallel": True, 

1296 "no_cross_reading": True, 

1297 "orchestrator_collects_findings": True, 

1298 }, 

1299 "areas": [ 

1300 {"name": name, "paths": list(paths)} 

1301 for name, paths in sorted(areas.items()) 

1302 if isinstance(paths, list) 

1303 ], 

1304 "risk_globs": list(config.knobs.tier3_globs), 

1305 "scan_finding": { 

1306 "renderer": "keel.artifacts.render_scan_finding_issue", 

1307 "marker": artifacts.SCAN_FINDING_MARKER, 

1308 }, 

1309 "issue_labels": { 

1310 key: list(value) 

1311 for key, value in sorted(issue_labels.items()) 

1312 if isinstance(value, list) 

1313 }, 

1314 "work_creation_policy": workcreation.contract_as_dict( 

1315 near_text_similarity=_near_text_similarity(config), 

1316 ), 

1317 } 

1318 if command == "regression": 

1319 base["regression"] = { 

1320 "scan_target": { 

1321 "source": "canonical base head", 

1322 "base_branch": config.base_branch, 

1323 "read_only_worktree": True, 

1324 "clean_tree_preflight": True, 

1325 }, 

1326 "scope": { 

1327 "default": "full", 

1328 "supported": ["full", "changed", "since"], 

1329 }, 

1330 "confidence_filter": { 

1331 "drop": ["low"], 

1332 "downgrade_blocker_when": "medium-confidence", 

1333 "file_only_when": ["high-confidence", "medium-security"], 

1334 }, 

1335 "issue_creation": { 

1336 "one_issue_per_finding": True, 

1337 "route_to": "ship", 

1338 "regression_of_line": "regression-of: #N", 

1339 "labels": issue_labels.get("regression", []), 

1340 }, 

1341 "final_report": [ 

1342 "raw_findings", 

1343 "after_confidence_filter", 

1344 "duplicates_skipped", 

1345 "promoted_regressions", 

1346 "issues_opened", 

1347 "ship_handoffs", 

1348 ], 

1349 } 

1350 elif command == "review-all-day": 

1351 base["review_all_day"] = { 

1352 "span": { 

1353 "timezone": config.timezone, 

1354 "merge_window": config.merge_window, 

1355 "days_are_inclusive_calendar_days": True, 

1356 "n_days_argument_covers_calendar_days": "N+1", 

1357 }, 

1358 "ref_scope": { 

1359 "branches": ["trunk", "active-work-branches"], 

1360 "active_branch_patterns": list(scan.get("active_branch_patterns") or ()), 

1361 "remote_refs_default": True, 

1362 "warn_on_stale_fetch": True, 

1363 }, 

1364 "strategy": { 

1365 "batch_threshold": _scan_int(scan, "batch_threshold", 5), 

1366 "fanout_when_commit_count_gt": _scan_int(scan, "batch_threshold", 5), 

1367 }, 

1368 "diff_truncation": { 

1369 "max_bytes": _scan_int(scan, "large_diff_max_bytes", 200000), 

1370 "boundary": "file", 

1371 }, 

1372 "finding_filter": { 

1373 "skip_minor": True, 

1374 "keep_minor_categories": ["security"], 

1375 "file_categories": [ 

1376 "bug-insert", 

1377 "regression", 

1378 "security", 

1379 "config", 

1380 "test-coverage", 

1381 ], 

1382 }, 

1383 "issue_creation": { 

1384 "title_prefix": "[review-all-day] ", 

1385 "one_issue_per_serious_finding": True, 

1386 "labels": issue_labels.get("review-all-day", []), 

1387 }, 

1388 "final_report": [ 

1389 "commit_range", 

1390 "reviewers", 

1391 "findings", 

1392 "duplicates_skipped", 

1393 "issues_opened", 

1394 ], 

1395 } 

1396 return base 

1397 

1398 

1399def session_contract_as_dict( 

1400 *, 

1401 command: str, 

1402 config: cfg.ProjectConfig, 

1403 transport: github_transport.GitHubTransport | None = None, 

1404 delegation: dict[str, Any] | None = None, 

1405) -> dict[str, Any]: 

1406 """Project-neutral session workflow contract for session/work-block commands.""" 

1407 pack = config.policy_pack or {} 

1408 reports = pack.get("reports") if isinstance(pack.get("reports"), dict) else {} 

1409 github = transport.as_dict() if transport is not None else {} 

1410 base = { 

1411 "timezone": config.timezone, 

1412 "merge_window": config.merge_window, 

1413 "merge_window_mode": config.merge_window_mode, 

1414 "base_branch": config.base_branch, 

1415 "github_transport": github, 

1416 "reports": _report_destinations(reports), 

1417 "deferral_queue": _deferral_queue_as_dict(reports), 

1418 "run_ledger": ledger.ledger_contract_as_dict(config), 

1419 "project_policy_sources": { 

1420 "gates": list(config.gates), 

1421 "extensions": {slot: list(files) for slot, files in sorted(config.extensions.items())}, 

1422 "risk_rules": [ 

1423 rule.get("id") for rule in pack.get("risk_rules", []) if isinstance(rule, dict) 

1424 ], 

1425 "source_of_truth_doc": config.knobs.sot_doc, 

1426 }, 

1427 } 

1428 if command in {"work-block", "overnight"}: 

1429 base["work_block"] = workblock.contract_as_dict( 

1430 config=config, 

1431 mode="overnight" if command == "overnight" else "daytime", 

1432 transport=github, 

1433 delegation=delegation, 

1434 ) 

1435 if command == "wrap": 

1436 base["wrap"] = { 

1437 "workspace_preflight": { 

1438 "must_run_from_linked_worktree": True, 

1439 "abort_on_base_branch": True, 

1440 "git_dir_rule": "main worktree returns .git; linked worktree uses .git/worktrees", 

1441 }, 

1442 "quality_gates": { 

1443 "runner": "keel run-gates", 

1444 "changed_file_policy_source": "policy_pack + extension hooks", 

1445 }, 

1446 "commit": { 

1447 "format": "conventional-commits", 

1448 "supports_closes_issue": True, 

1449 }, 

1450 "pull_request": { 

1451 "ready_not_draft": True, 

1452 "base_branch": config.base_branch, 

1453 "requires_pr_write": True, 

1454 "body_sections": ["Summary", "Docs Impact", "Test Plan"], 

1455 }, 

1456 "recap": { 

1457 "report_key": "session", 

1458 "path": reports.get("session") or reports.get("wrap"), 

1459 "status": "configured" 

1460 if reports.get("session") or reports.get("wrap") 

1461 else "unconfigured", 

1462 }, 

1463 } 

1464 elif command == "work-block": 

1465 base["daytime"] = { 

1466 "mode_source": { 

1467 "command": "keel work-block", 

1468 "shared_with_overnight": True, 

1469 }, 

1470 "queue": { 

1471 "source": "explicit issue numbers or project queue selector", 

1472 "deterministic_order": ( 

1473 "explicit numbers keep their provided order; selectors sort by policy" 

1474 ), 

1475 }, 

1476 "ship_handoff": { 

1477 "command": "ship", 

1478 "passes_operator_consent_scope": True, 

1479 "per_issue_worktree": True, 

1480 "refreshes_readiness_between_issues": True, 

1481 }, 

1482 "operator_control": { 

1483 "between_items": True, 

1484 "stop_on_consent_gap": True, 

1485 "stop_on_needs_input": True, 

1486 }, 

1487 "report": { 

1488 "day_key": "session", 

1489 "day_path": reports.get("session"), 

1490 "status": "configured" if reports.get("session") else "unconfigured", 

1491 }, 

1492 } 

1493 elif command == "overnight": 

1494 base["overnight"] = { 

1495 "mode_source": { 

1496 "command": "keel window", 

1497 "shared_with_ship": True, 

1498 "timezone": config.timezone, 

1499 "merge_window": config.merge_window, 

1500 }, 

1501 "merge_policy": { 

1502 "day": "ship may merge reviewed CI-green PRs inside the configured window", 

1503 "night": "no merge outside the configured window except true blockers", 

1504 "blocker_source": "ship blocker heuristics + project policy extensions", 

1505 "cannot_weaken_core_window": True, 

1506 }, 

1507 "queue": { 

1508 "source": "project policy or adapter query", 

1509 "tiers": [ 

1510 "T0-blocker", 

1511 "T1-open-prs", 

1512 "T2-coverage", 

1513 "T3-ci-quality", 

1514 "T4-modernization", 

1515 "T5-docs-backlog", 

1516 ], 

1517 }, 

1518 "ship_handoff": { 

1519 "command": "ship", 

1520 "passes_operator_consent_scope": True, 

1521 "per_issue_worktree": True, 

1522 "shared_work_block_contract": True, 

1523 }, 

1524 "report": { 

1525 "night_key": "overnight", 

1526 "day_key": "session", 

1527 "night_path": reports.get("overnight") or reports.get("morning"), 

1528 "day_path": reports.get("session"), 

1529 "status": ( 

1530 "configured" 

1531 if ( 

1532 reports.get("overnight") or reports.get("morning") or reports.get("session") 

1533 ) 

1534 else "unconfigured" 

1535 ), 

1536 }, 

1537 "stop_conditions": [ 

1538 "merge-window-close", 

1539 "time-budget-exhausted", 

1540 "max-items-reached", 

1541 "hard-blocker", 

1542 "three-consecutive-unresolved-ci-failures", 

1543 "user-cancelled", 

1544 ], 

1545 } 

1546 return base 

1547 

1548 

1549def morning_contract_as_dict( 

1550 *, 

1551 config: cfg.ProjectConfig, 

1552 evaluation: runtime.CapabilityEvaluation | None = None, 

1553 transport: github_transport.GitHubTransport | None = None, 

1554) -> dict[str, Any]: 

1555 """Project-neutral morning briefing contract for adapters and dry-run output.""" 

1556 pack = config.policy_pack or {} 

1557 reports = pack.get("reports") if isinstance(pack.get("reports"), dict) else {} 

1558 health = pack.get("health_providers") if isinstance(pack.get("health_providers"), dict) else {} 

1559 github = transport.as_dict() if transport is not None else {} 

1560 github_status = "available" if github.get("transport") not in {None, "none"} else "degraded" 

1561 return { 

1562 "timezone": config.timezone, 

1563 "merge_window": config.merge_window, 

1564 "base_branch": config.base_branch, 

1565 "sections": [ 

1566 { 

1567 "id": "deferrals", 

1568 "source": "shared_queue", 

1569 "status": "configured" if reports.get("deferrals") else "unconfigured", 

1570 "path": reports.get("deferrals"), 

1571 }, 

1572 { 

1573 "id": "shipped_since_last_brief", 

1574 "source": "github", 

1575 "transport": github.get("transport"), 

1576 "status": github_status, 

1577 }, 

1578 { 

1579 "id": "github_status", 

1580 "source": "github", 

1581 "transport": github.get("transport"), 

1582 "status": github_status, 

1583 }, 

1584 { 

1585 "id": "project_health", 

1586 "source": "policy_pack.health_providers", 

1587 "status": "configured" if health else "unconfigured", 

1588 }, 

1589 { 

1590 "id": "ranked_focus", 

1591 "source": "policy_pack + github", 

1592 "status": "configured" if _priority_sources(config, reports) else "unconfigured", 

1593 }, 

1594 ], 

1595 "health_providers": [ 

1596 _health_provider_as_dict(name, provider, evaluation) 

1597 for name, provider in sorted(health.items()) 

1598 if isinstance(provider, dict) 

1599 ], 

1600 "priority_sources": _priority_sources(config, reports), 

1601 "reports": _report_destinations(reports), 

1602 "deferral_queue": _deferral_queue_as_dict(reports), 

1603 "run_ledger": ledger.ledger_contract_as_dict(config), 

1604 "missing_optional_policy": "unavailable-not-success", 

1605 } 

1606 

1607 

1608def _health_provider_as_dict( 

1609 name: str, 

1610 provider: dict[str, Any], 

1611 evaluation: runtime.CapabilityEvaluation | None, 

1612) -> dict[str, Any]: 

1613 required = tuple(provider.get("required_capabilities") or ()) 

1614 optional = tuple(provider.get("optional_capabilities") or ()) 

1615 missing_required = _missing_capabilities(required, evaluation) 

1616 missing_optional = _missing_capabilities(optional, evaluation) 

1617 status = "available" 

1618 if missing_required: 

1619 status = "blocked" 

1620 elif missing_optional: 

1621 status = "unavailable" 

1622 elif provider.get("command") is None and provider.get("kind") == "project-command": 

1623 status = "unavailable" 

1624 return { 

1625 "name": name, 

1626 "kind": provider.get("kind"), 

1627 "command": provider.get("command"), 

1628 "reports": list(provider.get("reports") or ()), 

1629 "required_capabilities": list(required), 

1630 "optional_capabilities": list(optional), 

1631 "missing_required_capabilities": list(missing_required), 

1632 "missing_optional_capabilities": list(missing_optional), 

1633 "status": status, 

1634 } 

1635 

1636 

1637def _missing_capabilities( 

1638 names: tuple[str, ...], 

1639 evaluation: runtime.CapabilityEvaluation | None, 

1640) -> tuple[str, ...]: 

1641 if evaluation is None: 

1642 return () 

1643 missing = set(evaluation.missing_required) | set(evaluation.missing_optional) 

1644 return tuple(name for name in names if name in missing) 

1645 

1646 

1647def _priority_sources(config: cfg.ProjectConfig, reports: dict[str, Any]) -> list[dict[str, Any]]: 

1648 sources: list[dict[str, Any]] = [] 

1649 if config.knobs.sot_doc: 

1650 sources.append({"id": "source_of_truth", "path": config.knobs.sot_doc}) 

1651 if reports.get("priorities"): 

1652 sources.append({"id": "priorities_report", "path": reports["priorities"]}) 

1653 if config.knobs.ci_workflows: 

1654 sources.append({"id": "ci_workflows", "names": sorted(config.knobs.ci_workflows)}) 

1655 return sources 

1656 

1657 

1658def _report_destinations(reports: dict[str, Any]) -> dict[str, dict[str, Any]]: 

1659 return { 

1660 key: { 

1661 "path": value, 

1662 "write_status": "skipped-in-dry-run", 

1663 } 

1664 for key, value in sorted(reports.items()) 

1665 } 

1666 

1667 

1668def _deferral_queue_as_dict(reports: dict[str, Any]) -> dict[str, Any]: 

1669 return { 

1670 "source": "policy_pack.reports.deferrals", 

1671 "path": reports.get("deferrals"), 

1672 "status": "configured" if reports.get("deferrals") else "unconfigured", 

1673 "shared_with": ["ship", "overnight", "wrap", "morning"], 

1674 } 

1675 

1676 

1677def _feedback_workflow_policy(config: cfg.ProjectConfig) -> dict[str, dict[str, Any]]: 

1678 pack = config.policy_pack or {} 

1679 policy = pack.get("workflow_policies") 

1680 if not isinstance(policy, dict): 

1681 return {} 

1682 return { 

1683 name: value 

1684 for name, value in policy.items() 

1685 if isinstance(name, str) and isinstance(value, dict) 

1686 } 

1687 

1688 

1689def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]: 

1690 merged: dict[str, Any] = {} 

1691 for key, value in base.items(): 

1692 if isinstance(value, dict): 

1693 merged[key] = _deep_merge(value, {}) 

1694 elif isinstance(value, list): 

1695 merged[key] = list(value) 

1696 else: 

1697 merged[key] = value 

1698 for key, value in override.items(): 

1699 if isinstance(value, dict) and isinstance(merged.get(key), dict): 

1700 merged[key] = _deep_merge(merged[key], value) 

1701 elif isinstance(value, list): 

1702 merged[key] = list(value) 

1703 else: 

1704 merged[key] = value 

1705 return merged 

1706 

1707 

1708def _scan_int(scan: dict[str, Any], key: str, default: int) -> int: 

1709 value = scan.get(key) 

1710 return value if isinstance(value, int) else default 

1711 

1712 

1713def _scan_float(scan: dict[str, Any], key: str, default: float) -> float: 

1714 value = scan.get(key) 

1715 return value if isinstance(value, int | float) else default 

1716 

1717 

1718def _near_text_similarity(config: cfg.ProjectConfig) -> float: 

1719 """The project's resolved ``policy_pack.scan.near_text_similarity``. 

1720 

1721 Both contract builders embed a ``work_creation_policy`` block carrying this 

1722 threshold, and the scan contract carries a second copy under ``dedupe``. One 

1723 resolver keeps every copy in agreement — hardcoding the default in 

1724 ``workcreation`` shipped two different values under near-identical keys, agreeing 

1725 only while the project happened to set the knob to the built-in default (#633). 

1726 """ 

1727 pack = config.policy_pack or {} 

1728 scan = pack.get("scan") if isinstance(pack.get("scan"), dict) else {} 

1729 return _scan_float(scan, "near_text_similarity", workcreation.DEFAULT_NEAR_TEXT_SIMILARITY) 

1730 

1731 

1732def _target_identifier(target: str | None) -> str: 

1733 if not target: 

1734 return "selected-issue" 

1735 match = re.search(r"#?(\d+)", target) 

1736 if match: 

1737 return match.group(1) 

1738 return re.sub(r"[^a-z0-9]+", "-", target.lower()).strip("-") or "selected-issue" 

1739 

1740 

1741def _adapter_steps(command: str) -> list[dict[str, Any]]: 

1742 path = Path(install.ADAPTERS) / f"{command}.md" 

1743 if not path.exists(): 

1744 return [] 

1745 steps: list[dict[str, Any]] = [] 

1746 for line in path.read_text(encoding="utf-8").splitlines(): 

1747 match = _STEP_RE.match(line) 

1748 if not match: 

1749 continue 

1750 raw_id = match.group("id").strip() 

1751 step_id = raw_id.lower().replace(" ", "-").replace(".", "-") 

1752 steps.append( 

1753 { 

1754 "step_id": step_id, 

1755 "step_name": match.group("name").strip() or raw_id, 

1756 "agentic": "agent" in match.group("name").lower(), 

1757 "slot": None, 

1758 "source": "adapter", 

1759 } 

1760 ) 

1761 return steps 

1762 

1763 

1764def _finding_as_dict(finding) -> dict[str, Any]: 

1765 tag = provenance.normalize_tag( 

1766 getattr(finding, "provenance", None), 

1767 fallback_agent=finding.source, 

1768 step_id="finding", 

1769 ) 

1770 return { 

1771 "severity": finding.severity, 

1772 "message": finding.message, 

1773 "source": finding.source, 

1774 "path": finding.path, 

1775 "line": finding.line, 

1776 "anchorable": finding.anchorable, 

1777 "provenance": tag, 

1778 }