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

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 dataclasses import asdict 

12from pathlib import Path 

13from typing import Any 

14 

15from . import ( 

16 artifacts, 

17 capture, 

18 checkpoint, 

19 closure, 

20 consent, 

21 evidence, 

22 gates, 

23 github_transport, 

24 install, 

25 intake, 

26 ledger, 

27 lock, 

28 model, 

29 orchestrator, 

30 provenance, 

31 runcontrols, 

32 runtime, 

33 stepverifier, 

34 workblock, 

35 workcreation, 

36) 

37from . import config as cfg 

38from . import ship as ship_decisions 

39from .extensions import Extension 

40from .project_commands import get_project_command, list_project_commands 

41 

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

43 

44_COMPOUND_OVERRIDES: dict[str, str] = { 

45 "s4": "compound", 

46 "s7": "compound", 

47 "s9": "compound", 

48 "s11": "compound", 

49} 

50 

51_STEP_RE = re.compile( 

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

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

54) 

55 

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

57 "ship": ("git_worktree", "git_branch", "file_edit", "git_push", "pull_request", "comments", 

58 "reviews", "merge", 

59 "issue_close", "capture"), 

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

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

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

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

64 "work-block": ("git_branch", "git_push", "pull_request", "comments", "reviews", "merge", 

65 "deferral_queue", "session_report"), 

66 "overnight": ("git_branch", "git_push", "pull_request", "comments", "reviews", "merge", 

67 "deferral_queue", "session_report"), 

68 "implement": ("git_worktree", "git_branch", "file_edit", "git_commit", "git_push", 

69 "pull_request", "comments"), 

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

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

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

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

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

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

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

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

78} 

79 

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

81 "pr-loop": { 

82 "posting_mode": "summary", 

83 "posting_owner": "orchestrator", 

84 "reviewer_isolation": { 

85 "shared_with_ship": True, 

86 "codename_prefix": "PR-LOOP", 

87 "no_cross_reading": True, 

88 }, 

89 "inputs": { 

90 "auto_detect_current_branch": True, 

91 "explicit_pr_targets": True, 

92 "reads_review_comments": True, 

93 "reads_issue_conversation_comments": True, 

94 }, 

95 "ci": { 

96 "recheck_after_push": True, 

97 "green_required_to_exit": True, 

98 "degrade_when_logs_unavailable": True, 

99 }, 

100 "fix_loop": { 

101 "budget": 3, 

102 "self_review_before_push": True, 

103 "reviewer_fanout_after_each_push": True, 

104 }, 

105 "completion": { 

106 "marker": None, 

107 "merge": "handoff", 

108 "summary_comment": True, 

109 }, 

110 }, 

111 "review-cycle": { 

112 "posting_mode": "inline", 

113 "posting_owner": "orchestrator", 

114 "reviewer_isolation": { 

115 "shared_with_ship": True, 

116 "codename_prefix": "REVIEW-CYCLE", 

117 "no_cross_reading": True, 

118 }, 

119 "inputs": { 

120 "multi_pr": True, 

121 "sequential_pr_processing": True, 

122 }, 

123 "review": { 

124 "parallel_reviewers_within_pr": True, 

125 "partial_reviewer_failures_degrade": True, 

126 "severity_histogram_source_of_truth": True, 

127 }, 

128 "fix_loop": { 

129 "budget": 3, 

130 "enabled": True, 

131 }, 

132 "completion": { 

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

134 "marker_after_summary": True, 

135 "merge": "never", 

136 "formal_approval": "never", 

137 }, 

138 }, 

139} 

140 

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

142 

143 

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

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

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

147 

148 

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

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

151 

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

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

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

155 command-local sequence without parsing Markdown themselves. 

156 """ 

157 if command == "ship": 

158 compound = profile == "compound" 

159 return [ 

160 { 

161 "step_id": step.id, 

162 "step_name": step.name, 

163 "agentic": step.agentic, 

164 "slot": step.slot, 

165 "source": "backbone", 

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

167 if compound else "standard", 

168 } 

169 for step in model.BACKBONE 

170 ] 

171 steps = _adapter_steps(command) 

172 return steps if steps else [] 

173 

174 

175def build_command_contract( 

176 *, 

177 command: str, 

178 profile: str = "standard", 

179 config: cfg.ProjectConfig, 

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

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

182 requirement: runtime.CapabilityRequirement, 

183 evaluation: runtime.CapabilityEvaluation, 

184 transport: github_transport.GitHubTransport, 

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

186 dry_run: bool = True, 

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

188 consent_approval_source: str = "flag", 

189 consent_mode: str = "explicit", 

190 operator: str | None = None, 

191 target: str | None = None, 

192 reviewer_override: int | None = None, 

193 review_tier: int | None = None, 

194 review_comments: str = "inline", 

195 jury: bool = False, 

196 no_jury: bool = False, 

197 jury_advisory: bool = False, 

198 issue_title: str | None = None, 

199 issue_body: str | None = None, 

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

201) -> dict[str, Any]: 

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

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

204 graph = command_graph(command, profile=profile) 

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

206 graph = [{ 

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

208 "step_name": project_command.name, 

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

210 "slot": None, 

211 "source": "project_command", 

212 }] 

213 contract = { 

214 "schema_version": SCHEMA_VERSION, 

215 "command": command, 

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

217 "dry_run": dry_run, 

218 "no_mutations": dry_run, 

219 "project": project_as_dict(config), 

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

221 "graph": graph, 

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

223 "gates": [gate_as_dict(spec) for spec in gates.plan_gates(config, loaded)], 

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

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

226 "extension_problems": list(extension_problems), 

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

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

229 "capabilities": evaluation.as_dict(), 

230 "github_transport": transport.as_dict(), 

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

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

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

234 "resource_claims": lock.contract_as_dict(), 

235 "side_effects": { 

236 "declared": list(declared_side_effects), 

237 "mutates_in_dry_run": False, 

238 }, 

239 "operator_consent": consent.build_consent_contract( 

240 command=command, 

241 side_effects=declared_side_effects, 

242 dry_run=dry_run, 

243 approved_scopes=approved_consent_scopes, 

244 approval_source=consent_approval_source, 

245 mode=consent_mode, 

246 operator=operator, 

247 target=target, 

248 ), 

249 "agent_output_provenance": provenance.contract_as_dict(), 

250 } 

251 if command == "morning": 

252 contract["morning_contract"] = morning_contract_as_dict( 

253 config=config, 

254 evaluation=evaluation, 

255 transport=transport, 

256 ) 

257 if command in _REPORTING_COMMANDS: 

258 contract["reporting_contract"] = reporting_contract_as_dict( 

259 command=command, 

260 config=config, 

261 transport=transport, 

262 ) 

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

264 contract["session_contract"] = session_contract_as_dict( 

265 command=command, 

266 config=config, 

267 transport=transport, 

268 ) 

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

270 contract["scan_contract"] = scan_contract_as_dict( 

271 command=command, 

272 config=config, 

273 transport=transport, 

274 ) 

275 if command == "triage": 

276 contract["triage_contract"] = { 

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

278 "one_comment_per_issue": True, 

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

280 "marker": artifacts.TRIAGE_AUDIT_MARKER, 

281 } 

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

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

284 tier=review_tier, 

285 reviewer_override=reviewer_override, 

286 review_comments=review_comments, 

287 gates=config.gates, 

288 policy_pack=config.policy_pack, 

289 jury=jury, 

290 no_jury=no_jury, 

291 jury_advisory=jury_advisory, 

292 ) 

293 if command == "ship": 

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

295 contract["review_merge_contract"], 

296 dry_run=dry_run, 

297 ) 

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

299 contract["review_merge_contract"], 

300 dry_run=dry_run, 

301 ) 

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

303 if command == "ship": 

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

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

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

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

308 title=issue_title, 

309 body=issue_body, 

310 labels=issue_labels, 

311 ) 

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

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

314 return contract 

315 

316 

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

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

319 

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

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

322 backbone. 

323 """ 

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

325 return { 

326 "name": "ship", 

327 "profile": "compound", 

328 "inherits": "ship", 

329 "first_class_variant": True, 

330 "shared_primitives": [ 

331 "select", 

332 "branch", 

333 "worktree", 

334 "guard", 

335 "classify", 

336 "ci", 

337 "test", 

338 "merge_window", 

339 "merge_lock", 

340 "merge", 

341 "capture_marker", 

342 "close", 

343 ], 

344 "step_overrides": { 

345 "s4": { 

346 "step": "implement", 

347 "mode": "compound", 

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

349 }, 

350 "s7": { 

351 "step": "review", 

352 "mode": "compound", 

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

354 }, 

355 "s9": { 

356 "step": "fixloop", 

357 "mode": "compound", 

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

359 }, 

360 "s11": { 

361 "step": "capture", 

362 "mode": "compound", 

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

364 }, 

365 }, 

366 } 

367 if command == "pr-loop": 

368 return { 

369 "name": "pr-loop", 

370 "profile": "feedback-loop", 

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

372 "first_class_variant": True, 

373 "shared_primitives": [ 

374 "linked_worktree_preflight", 

375 "github_transport", 

376 "reviewer_isolation", 

377 "ci_recheck", 

378 "fixloop", 

379 "summary_comment", 

380 "operator_consent", 

381 ], 

382 "step_overrides": { 

383 "merge": { 

384 "mode": "handoff", 

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

386 }, 

387 }, 

388 } 

389 if command == "review-cycle": 

390 return { 

391 "name": "review-cycle", 

392 "profile": "review-feedback", 

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

394 "first_class_variant": True, 

395 "shared_primitives": [ 

396 "multi_pr_targets", 

397 "reviewer_isolation", 

398 "posting_mode", 

399 "severity_histogram", 

400 "fixloop", 

401 "completion_marker", 

402 "operator_consent", 

403 ], 

404 "step_overrides": { 

405 "merge": { 

406 "mode": "never", 

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

408 }, 

409 }, 

410 } 

411 if command == "implement": 

412 return { 

413 "name": "implement", 

414 "profile": "standalone-step", 

415 "inherits": "ship.s4", 

416 "first_class_variant": True, 

417 "shared_primitives": [ 

418 "issue_target", 

419 "branch", 

420 "worktree", 

421 "implementer_routing", 

422 "operator_consent", 

423 "handoff", 

424 ], 

425 "step_overrides": {}, 

426 } 

427 if command == "ci-check": 

428 return { 

429 "name": "ci-check", 

430 "profile": "standalone-diagnostic", 

431 "inherits": None, 

432 "first_class_variant": True, 

433 "shared_primitives": [ 

434 "github_transport", 

435 "check_runs", 

436 "latest_run_context", 

437 "log_diagnostics", 

438 "read_only", 

439 "routing_recommendation", 

440 ], 

441 "step_overrides": {}, 

442 } 

443 if command == "morning": 

444 return { 

445 "name": "morning", 

446 "profile": "daily-brief", 

447 "inherits": None, 

448 "first_class_variant": True, 

449 "shared_primitives": [ 

450 "date_window", 

451 "deferral_queue", 

452 "shipped_since", 

453 "github_summary", 

454 "health_providers", 

455 "priority_sources", 

456 "ranked_focus", 

457 "report_output", 

458 ], 

459 "step_overrides": {}, 

460 } 

461 if command == "wrap": 

462 return { 

463 "name": "wrap", 

464 "profile": "session-wrap", 

465 "inherits": None, 

466 "first_class_variant": True, 

467 "shared_primitives": [ 

468 "linked_worktree_preflight", 

469 "base_branch_guard", 

470 "configured_gates", 

471 "conventional_commit", 

472 "ready_pr_create", 

473 "session_recap", 

474 "deferral_queue", 

475 "operator_consent", 

476 ], 

477 "step_overrides": {}, 

478 } 

479 if command == "overnight": 

480 return { 

481 "name": "overnight", 

482 "profile": "session-overnight", 

483 "inherits": "ship", 

484 "first_class_variant": True, 

485 "shared_primitives": [ 

486 "work_block", 

487 "merge_window", 

488 "ship_handoff", 

489 "priority_queue", 

490 "per_issue_worktree", 

491 "no_night_merge", 

492 "blocker_policy", 

493 "session_report", 

494 "deferral_queue", 

495 "stop_conditions", 

496 "operator_consent", 

497 ], 

498 "step_overrides": {}, 

499 } 

500 if command == "work-block": 

501 return { 

502 "name": "work-block", 

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

504 "inherits": "ship", 

505 "first_class_variant": True, 

506 "shared_primitives": [ 

507 "work_block", 

508 "queue_snapshot", 

509 "readiness_refresh", 

510 "ship_handoff", 

511 "per_issue_worktree", 

512 "operator_between_item_control", 

513 "progress_snapshot", 

514 "session_report", 

515 "deferral_queue", 

516 "stop_conditions", 

517 "operator_consent", 

518 ], 

519 "step_overrides": {}, 

520 } 

521 if command in _REPORTING_COMMANDS: 

522 return { 

523 "name": command, 

524 "profile": "reporting", 

525 "inherits": None, 

526 "first_class_variant": True, 

527 "shared_primitives": [ 

528 "project_policy", 

529 "github_transport", 

530 "codename_anchor", 

531 "dedupe", 

532 "dry_run_no_mutations", 

533 "ship_handoff", 

534 "operator_consent", 

535 ], 

536 "step_overrides": {}, 

537 } 

538 if command == "regression": 

539 return { 

540 "name": "regression", 

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

542 "inherits": None, 

543 "first_class_variant": True, 

544 "shared_primitives": [ 

545 "canonical_base_scan", 

546 "clean_tree_preflight", 

547 "read_only_worktree", 

548 "area_fanout", 

549 "reviewer_isolation", 

550 "confidence_filter", 

551 "dedupe", 

552 "issue_lock", 

553 "issue_create", 

554 "ship_handoff", 

555 "final_report", 

556 "operator_consent", 

557 ], 

558 "step_overrides": {}, 

559 } 

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

561 return { 

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

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

564 "inherits": None, 

565 "first_class_variant": True, 

566 "shared_primitives": [ 

567 "merge_window_span", 

568 "remote_ref_scope", 

569 "batch_or_fanout", 

570 "reviewer_isolation", 

571 "diff_truncation", 

572 "finding_filter", 

573 "dedupe", 

574 "issue_prefix", 

575 "issue_create", 

576 "final_report", 

577 "operator_consent", 

578 ], 

579 "step_overrides": {}, 

580 } 

581 if command == "ship": 

582 return { 

583 "name": "ship", 

584 "profile": "standard", 

585 "inherits": None, 

586 "first_class_variant": True, 

587 "shared_primitives": [ 

588 "select", 

589 "branch", 

590 "guard", 

591 "implement", 

592 "classify", 

593 "ci", 

594 "review", 

595 "test", 

596 "fixloop", 

597 "merge", 

598 "capture", 

599 "close", 

600 ], 

601 "step_overrides": {}, 

602 } 

603 return { 

604 "name": command, 

605 "profile": "adapter", 

606 "inherits": None, 

607 "first_class_variant": False, 

608 "shared_primitives": [], 

609 "step_overrides": {}, 

610 } 

611 

612 

613def command_side_effects( 

614 command: str, 

615 config: cfg.ProjectConfig, 

616 requirement: runtime.CapabilityRequirement, 

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

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

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

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

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

622 effects.extend(project_command.side_effects) 

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

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

625 for extensions in loaded.values(): 

626 for ext in extensions: 

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

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

629 return tuple(dict.fromkeys(effects)) 

630 

631 

632def reporting_contract_as_dict( 

633 *, 

634 command: str, 

635 config: cfg.ProjectConfig, 

636 transport: github_transport.GitHubTransport | None = None, 

637) -> dict[str, Any]: 

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

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

640 base = { 

641 "command": command, 

642 "base_branch": config.base_branch, 

643 "timezone": config.timezone, 

644 "github_transport": github, 

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

646 "dry_run": { 

647 "mutates": False, 

648 "prints_planned_writes": True, 

649 }, 

650 "handoff": { 

651 "fixes_route_to": "ship", 

652 "auto_applies_fixes": False, 

653 }, 

654 "work_creation_policy": workcreation.contract_as_dict( 

655 near_text_similarity=_near_text_similarity(config), 

656 ), 

657 } 

658 if command == "coverage": 

659 return { 

660 **base, 

661 "target": "pull_request", 

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

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

664 "marker": artifacts.COVERAGE_DELTA_MARKER, 

665 "idempotency": { 

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

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

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

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

670 }, 

671 "labels": { 

672 "regression": "coverage-regression", 

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

674 }, 

675 "degradation": { 

676 "unwired_tool": "skip-area", 

677 "coverage_command_failure": "fatal", 

678 }, 

679 "arguments": ["pr", "--base", "--threshold", "--changed", "--open-issues", 

680 "--dry-run"], 

681 } 

682 if command == "deps-audit": 

683 return { 

684 **base, 

685 "target": "daily_tracking_issue", 

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

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

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

689 "marker": artifacts.DEPS_AUDIT_MARKER, 

690 "idempotency": { 

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

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

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

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

695 }, 

696 "degradation": { 

697 "per_ecosystem_failure": "skipped-section", 

698 "argument_failure": "fatal", 

699 }, 

700 "arguments": ["ecosystem", "--severity", "--security-only", "--open-issues", 

701 "--dry-run"], 

702 } 

703 if command == "flake-audit": 

704 return { 

705 **base, 

706 "target": "ci_history_or_local_runs", 

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

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

709 "marker": artifacts.FLAKE_AUDIT_MARKER, 

710 "idempotency": { 

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

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

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

714 }, 

715 "classification": { 

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

717 "minimum_failures": 3, 

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

719 }, 

720 "degradation": { 

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

722 "no_ci_or_local_gate": "clean-exit", 

723 }, 

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

725 } 

726 return base 

727 

728 

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

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

731 return { 

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

733 "extends": config.extends, 

734 "core_version": config.core_version, 

735 "base_branch": config.base_branch, 

736 "owner": config.owner, 

737 "repo": config.repo, 

738 "platform": config.platform, 

739 "timezone": config.timezone, 

740 "merge_window": config.merge_window, 

741 "merge_window_mode": config.merge_window_mode, 

742 "extensions_dir": config.extensions_dir, 

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

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

745 "policy_pack": config.policy_pack, 

746 "knobs": { 

747 "build_gate_cmd": config.knobs.build_gate_cmd, 

748 "lint_cmd": config.knobs.lint_cmd, 

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

750 **cfg.delegate_profiles_dict(config), 

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

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

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

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

755 "sot_doc": config.knobs.sot_doc, 

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

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

758 }, 

759 } 

760 

761 

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

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

764 return asdict(spec) 

765 

766 

767def extension_hooks_as_dict( 

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

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

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

771 return { 

772 slot: [ 

773 { 

774 "id": ext.id, 

775 "slot": ext.slot, 

776 "kind": ext.kind, 

777 "mode": ext.mode, 

778 "agent": ext.agent, 

779 "on_fail": ext.on_fail, 

780 "anchorable": ext.anchorable, 

781 "source": ext.source, 

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

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

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

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

786 } 

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

788 ] 

789 for slot in model.SLOTS 

790 } 

791 

792 

793def ship_result_as_dict( 

794 *, 

795 changed_files: list[str] | None, 

796 outcomes: list[gates.GateOutcome], 

797 verdict, 

798 assessment, 

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

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

801) -> dict[str, Any]: 

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

803 closure_comment = None 

804 issue_number = None 

805 pr_number = None 

806 head_sha = None 

807 if isinstance(run_ledger, dict): 

808 record = run_ledger.get("record") 

809 if isinstance(record, dict): 

810 closure_comment = closure.render_closure_comment(record) 

811 issue = record.get("issue") 

812 pull_request = record.get("pull_request") 

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

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

815 head_sha = record.get("head_sha") 

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

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

818 testing = _testing_summary(outcomes) 

819 artifact_bodies = { 

820 "pr_body": artifacts.render_pr_body( 

821 issue_number=issue_number, 

822 issue_intake=issue_intake, 

823 changed_files=changed_files, 

824 testing=testing, 

825 docs_impact=_docs_impact(changed_files), 

826 ), 

827 "issue_update": artifacts.render_issue_update( 

828 issue_number=issue_number, 

829 pull_request=pr_number, 

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

831 summary=assessment.merge.reason, 

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

833 if not verdict.blocked else "Resolve blocking findings before merge.", 

834 ), 

835 "review_verdict_template": artifacts.render_review_verdict( 

836 reviewer="reviewer", 

837 head_sha=head_sha, 

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

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

840 findings=finding_dicts, 

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

842 ), 

843 "jury_verdict_template": artifacts.render_jury_verdict( 

844 head_sha=head_sha, 

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

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

847 findings_summary=_finding_summaries(finding_dicts), 

848 remaining_risks="blocking findings present" if verdict.blocked else "none identified", 

849 ),