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
« 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.
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"""
8from __future__ import annotations
10import re
11from collections.abc import Mapping
12from dataclasses import asdict
13from pathlib import Path
14from typing import Any
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
47SCHEMA_VERSION = "keel.command-contract.v1"
49_COMPOUND_OVERRIDES: dict[str, str] = {
50 "s4": "compound",
51 "s7": "compound",
52 "s9": "compound",
53 "s11": "compound",
54}
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)
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}
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}
178_REPORTING_COMMANDS = {"coverage", "deps-audit", "flake-audit"}
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())
186def command_graph(command: str, *, profile: str = "standard") -> list[dict[str, Any]]:
187 """Return the command's step graph as JSON-compatible records.
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 []
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.
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
431def workflow_profile(command: str, *, profile: str = "standard") -> dict[str, Any]:
432 """First-class workflow profile metadata for command variants.
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 }
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))
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
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 }
881def gate_as_dict(spec: gates.GateSpec) -> dict[str, Any]:
882 """Render a planned gate without losing its capability declarations."""
883 return asdict(spec)
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.
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 }
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 }
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``.
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.
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 }
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
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."
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 )
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 ]
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}
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)
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
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
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 }
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 }
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)
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
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 }
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 }
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 }
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
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
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
1718def _near_text_similarity(config: cfg.ProjectConfig) -> float:
1719 """The project's resolved ``policy_pack.scan.near_text_similarity``.
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)
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"
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
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 }