agentic-project-kit 1.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (310) hide show
  1. agentic_project_kit/__init__.py +1 -0
  2. agentic_project_kit/absolute_path_portability_audit.py +241 -0
  3. agentic_project_kit/access_level_policy.py +14 -0
  4. agentic_project_kit/access_levels.py +22 -0
  5. agentic_project_kit/action_registry.py +195 -0
  6. agentic_project_kit/action_specs.py +286 -0
  7. agentic_project_kit/agent_command_runner.py +516 -0
  8. agentic_project_kit/audit_test_matrix.py +36 -0
  9. agentic_project_kit/audit_test_matrix_cli.py +43 -0
  10. agentic_project_kit/chat_bootloader.py +257 -0
  11. agentic_project_kit/chat_entrypoint_contract.py +297 -0
  12. agentic_project_kit/checks.py +511 -0
  13. agentic_project_kit/ci_readiness.py +211 -0
  14. agentic_project_kit/cli.py +147 -0
  15. agentic_project_kit/cli_commands/__init__.py +1 -0
  16. agentic_project_kit/cli_commands/absolute_path_audit.py +25 -0
  17. agentic_project_kit/cli_commands/actions.py +21 -0
  18. agentic_project_kit/cli_commands/artifact_gc.py +240 -0
  19. agentic_project_kit/cli_commands/boot.py +55 -0
  20. agentic_project_kit/cli_commands/chat.py +34 -0
  21. agentic_project_kit/cli_commands/checks.py +305 -0
  22. agentic_project_kit/cli_commands/cockpit.py +103 -0
  23. agentic_project_kit/cli_commands/command_taxonomy.py +25 -0
  24. agentic_project_kit/cli_commands/commands.py +129 -0
  25. agentic_project_kit/cli_commands/dev.py +23 -0
  26. agentic_project_kit/cli_commands/direction.py +92 -0
  27. agentic_project_kit/cli_commands/doc_currency_audit.py +25 -0
  28. agentic_project_kit/cli_commands/doc_registry.py +126 -0
  29. agentic_project_kit/cli_commands/docs.py +223 -0
  30. agentic_project_kit/cli_commands/dpa.py +1338 -0
  31. agentic_project_kit/cli_commands/evidence.py +251 -0
  32. agentic_project_kit/cli_commands/github.py +34 -0
  33. agentic_project_kit/cli_commands/governance.py +14 -0
  34. agentic_project_kit/cli_commands/gui.py +23 -0
  35. agentic_project_kit/cli_commands/gui_readiness_gate.py +27 -0
  36. agentic_project_kit/cli_commands/handoff.py +183 -0
  37. agentic_project_kit/cli_commands/human_workflows.py +430 -0
  38. agentic_project_kit/cli_commands/init.py +132 -0
  39. agentic_project_kit/cli_commands/instruction.py +75 -0
  40. agentic_project_kit/cli_commands/mutation_lock_audit.py +24 -0
  41. agentic_project_kit/cli_commands/ns_legacy_audit.py +25 -0
  42. agentic_project_kit/cli_commands/pass_already_done.py +66 -0
  43. agentic_project_kit/cli_commands/patch_failure_discipline_audit.py +26 -0
  44. agentic_project_kit/cli_commands/patch_preflight.py +37 -0
  45. agentic_project_kit/cli_commands/path_literal_audit.py +39 -0
  46. agentic_project_kit/cli_commands/patterns.py +40 -0
  47. agentic_project_kit/cli_commands/planning_docs_audit.py +25 -0
  48. agentic_project_kit/cli_commands/pr.py +133 -0
  49. agentic_project_kit/cli_commands/pr_hygiene.py +27 -0
  50. agentic_project_kit/cli_commands/profiles.py +26 -0
  51. agentic_project_kit/cli_commands/program_redundancy_audit.py +25 -0
  52. agentic_project_kit/cli_commands/project_direction.py +25 -0
  53. agentic_project_kit/cli_commands/release.py +392 -0
  54. agentic_project_kit/cli_commands/release_publish_orchestration.py +36 -0
  55. agentic_project_kit/cli_commands/remote_branch_hygiene.py +152 -0
  56. agentic_project_kit/cli_commands/remote_next.py +57 -0
  57. agentic_project_kit/cli_commands/removed_ns_commands.py +65 -0
  58. agentic_project_kit/cli_commands/rule_registry.py +129 -0
  59. agentic_project_kit/cli_commands/rules.py +222 -0
  60. agentic_project_kit/cli_commands/scaffold.py +46 -0
  61. agentic_project_kit/cli_commands/slice.py +21 -0
  62. agentic_project_kit/cli_commands/standard_gates_audit_suite.py +27 -0
  63. agentic_project_kit/cli_commands/state.py +51 -0
  64. agentic_project_kit/cli_commands/status_current_state_audit.py +30 -0
  65. agentic_project_kit/cli_commands/todo.py +53 -0
  66. agentic_project_kit/cli_commands/transfer.py +19 -0
  67. agentic_project_kit/cli_commands/transfer_context_flow.py +398 -0
  68. agentic_project_kit/cli_commands/transfer_context_helpers.py +398 -0
  69. agentic_project_kit/cli_commands/transfer_diagnostics.py +767 -0
  70. agentic_project_kit/cli_commands/transfer_evidence_flow.py +368 -0
  71. agentic_project_kit/cli_commands/transfer_handoff_flow.py +594 -0
  72. agentic_project_kit/cli_commands/transfer_order_contract.py +74 -0
  73. agentic_project_kit/cli_commands/transfer_post_merge_complete.py +442 -0
  74. agentic_project_kit/cli_commands/transfer_post_merge_settle.py +171 -0
  75. agentic_project_kit/cli_commands/transfer_pr_closeout_complete.py +124 -0
  76. agentic_project_kit/cli_commands/transfer_pr_create_flow.py +743 -0
  77. agentic_project_kit/cli_commands/transfer_pr_merge_flow.py +547 -0
  78. agentic_project_kit/cli_commands/transfer_repo_after_pr.py +160 -0
  79. agentic_project_kit/cli_commands/transfer_repo_pre_pr.py +664 -0
  80. agentic_project_kit/cli_commands/transfer_runner_flow.py +131 -0
  81. agentic_project_kit/cli_commands/transfer_runtime_initial.py +194 -0
  82. agentic_project_kit/cli_commands/transfer_shared.py +274 -0
  83. agentic_project_kit/cli_commands/validation.py +200 -0
  84. agentic_project_kit/cli_commands/version.py +27 -0
  85. agentic_project_kit/cli_commands/work_orders.py +219 -0
  86. agentic_project_kit/cli_commands/workflow.py +471 -0
  87. agentic_project_kit/cli_commands/workflow_guard.py +26 -0
  88. agentic_project_kit/cli_commands/workspace.py +252 -0
  89. agentic_project_kit/cockpit.py +608 -0
  90. agentic_project_kit/cockpit_readiness.py +67 -0
  91. agentic_project_kit/command_authority_audit.py +192 -0
  92. agentic_project_kit/command_inbox_check.py +103 -0
  93. agentic_project_kit/command_manifest.py +591 -0
  94. agentic_project_kit/command_queue_contract.py +161 -0
  95. agentic_project_kit/command_selector.py +245 -0
  96. agentic_project_kit/command_taxonomy.py +264 -0
  97. agentic_project_kit/commit_guard.py +67 -0
  98. agentic_project_kit/communication_artifact_gc.py +495 -0
  99. agentic_project_kit/communication_rule_context.py +437 -0
  100. agentic_project_kit/communication_state.py +115 -0
  101. agentic_project_kit/composed_wrapper_invariants.py +97 -0
  102. agentic_project_kit/composite_short_circuit.py +140 -0
  103. agentic_project_kit/contract.py +251 -0
  104. agentic_project_kit/control_state.py +83 -0
  105. agentic_project_kit/doc_currency_audit.py +536 -0
  106. agentic_project_kit/doc_lifecycle.py +1179 -0
  107. agentic_project_kit/doc_lifecycle_signals.py +446 -0
  108. agentic_project_kit/doc_lifecycle_sweep.py +639 -0
  109. agentic_project_kit/doc_mesh.py +491 -0
  110. agentic_project_kit/doctor.py +379 -0
  111. agentic_project_kit/documentation_registry.py +1122 -0
  112. agentic_project_kit/documentation_system_audit.py +310 -0
  113. agentic_project_kit/dpa_current_handoff_lifecycle.py +549 -0
  114. agentic_project_kit/dpa_dp2_decision_readiness.py +362 -0
  115. agentic_project_kit/dpa_dp3_dp4_adjudication.py +604 -0
  116. agentic_project_kit/dpa_dp5_block_new_gate.py +294 -0
  117. agentic_project_kit/dpa_dp5_stage_adoption.py +615 -0
  118. agentic_project_kit/dpa_dp5_strict_gate.py +187 -0
  119. agentic_project_kit/dpa_final_closeout.py +627 -0
  120. agentic_project_kit/dpa_fixture_evidence.py +680 -0
  121. agentic_project_kit/dpa_maintainer_record_check.py +711 -0
  122. agentic_project_kit/dpa_post_dp2_scope_assessment.py +734 -0
  123. agentic_project_kit/dpa_probe_002_readiness.py +509 -0
  124. agentic_project_kit/dpa_probe_003_readiness.py +417 -0
  125. agentic_project_kit/dpa_probe_004_readiness.py +437 -0
  126. agentic_project_kit/dpa_readiness.py +505 -0
  127. agentic_project_kit/dpa_readonly_probe_execution.py +500 -0
  128. agentic_project_kit/dpa_registry_contracts.py +312 -0
  129. agentic_project_kit/dpa_renderer_readiness.py +407 -0
  130. agentic_project_kit/dpa_repo_adoption_assessment.py +574 -0
  131. agentic_project_kit/dpa_stable_readiness.py +743 -0
  132. agentic_project_kit/dpa_successor_projection.py +168 -0
  133. agentic_project_kit/dpa_workspace_init_projection.py +93 -0
  134. agentic_project_kit/dpa_wrt_ch001_evidence.py +327 -0
  135. agentic_project_kit/entrypoint_slice_runner.py +153 -0
  136. agentic_project_kit/evidence_clean.py +152 -0
  137. agentic_project_kit/evidence_commit_paths.py +214 -0
  138. agentic_project_kit/evidence_finalize_log.py +204 -0
  139. agentic_project_kit/evidence_guard.py +114 -0
  140. agentic_project_kit/evidence_inspector.py +507 -0
  141. agentic_project_kit/evidence_state_contract.py +99 -0
  142. agentic_project_kit/execution_mode_state.py +148 -0
  143. agentic_project_kit/final_summary_contract.py +85 -0
  144. agentic_project_kit/finalize_guard.py +139 -0
  145. agentic_project_kit/gatekeeper_core.py +232 -0
  146. agentic_project_kit/github.py +25 -0
  147. agentic_project_kit/governance.py +59 -0
  148. agentic_project_kit/gui_action_execution.py +105 -0
  149. agentic_project_kit/gui_action_renderer.py +81 -0
  150. agentic_project_kit/gui_action_run_intent.py +98 -0
  151. agentic_project_kit/gui_action_views.py +195 -0
  152. agentic_project_kit/gui_activity_log.py +76 -0
  153. agentic_project_kit/gui_button_catalog.py +605 -0
  154. agentic_project_kit/gui_cockpit.py +365 -0
  155. agentic_project_kit/gui_cockpit_actions.py +695 -0
  156. agentic_project_kit/gui_cockpit_common.py +172 -0
  157. agentic_project_kit/gui_cockpit_header.py +501 -0
  158. agentic_project_kit/gui_cockpit_sidebar.py +387 -0
  159. agentic_project_kit/gui_cockpit_task.py +748 -0
  160. agentic_project_kit/gui_command_projection.py +355 -0
  161. agentic_project_kit/gui_communication_modes.py +130 -0
  162. agentic_project_kit/gui_dry_run.py +219 -0
  163. agentic_project_kit/gui_gatekeeper_status.py +259 -0
  164. agentic_project_kit/gui_layout_plan.py +148 -0
  165. agentic_project_kit/gui_open_folder.py +18 -0
  166. agentic_project_kit/gui_output_status_panel.py +61 -0
  167. agentic_project_kit/gui_panel_state.py +47 -0
  168. agentic_project_kit/gui_presenter.py +62 -0
  169. agentic_project_kit/gui_readiness_gate.py +206 -0
  170. agentic_project_kit/gui_release_flow.py +59 -0
  171. agentic_project_kit/gui_task_editor.py +1077 -0
  172. agentic_project_kit/gui_tk_widgets.py +177 -0
  173. agentic_project_kit/gui_tkinter_renderer.py +87 -0
  174. agentic_project_kit/gui_tkinter_shell.py +1176 -0
  175. agentic_project_kit/gui_transfer_contract.py +28 -0
  176. agentic_project_kit/gui_viewmodel.py +698 -0
  177. agentic_project_kit/gui_window_guard.py +46 -0
  178. agentic_project_kit/handoff_freshness.py +390 -0
  179. agentic_project_kit/handoff_prompt.py +180 -0
  180. agentic_project_kit/handoff_state.py +254 -0
  181. agentic_project_kit/instruction_lint.py +455 -0
  182. agentic_project_kit/llm_context_carriers.py +66 -0
  183. agentic_project_kit/llm_execution_context.py +285 -0
  184. agentic_project_kit/local_command_stack.py +133 -0
  185. agentic_project_kit/local_feature_gate.py +82 -0
  186. agentic_project_kit/local_garbage_collector.py +269 -0
  187. agentic_project_kit/models.py +18 -0
  188. agentic_project_kit/mutation_lock_audit.py +421 -0
  189. agentic_project_kit/next_turn_evidence.py +253 -0
  190. agentic_project_kit/next_turn_merge_if_green.py +459 -0
  191. agentic_project_kit/next_turn_pr_status.py +255 -0
  192. agentic_project_kit/next_turn_result.py +183 -0
  193. agentic_project_kit/next_turn_runner.py +159 -0
  194. agentic_project_kit/next_turn_slot.py +107 -0
  195. agentic_project_kit/next_turn_status.py +274 -0
  196. agentic_project_kit/ns_legacy_reference_audit.py +258 -0
  197. agentic_project_kit/ns_slice_runner.py +16 -0
  198. agentic_project_kit/operational_handoff_projection.py +124 -0
  199. agentic_project_kit/output_contract.py +80 -0
  200. agentic_project_kit/output_repair.py +61 -0
  201. agentic_project_kit/pass_already_done.py +216 -0
  202. agentic_project_kit/patch_artifact_preflight.py +147 -0
  203. agentic_project_kit/patch_cycle_workflow.py +440 -0
  204. agentic_project_kit/patch_failure_discipline_audit.py +223 -0
  205. agentic_project_kit/patch_preflight.py +215 -0
  206. agentic_project_kit/path_literal_audit.py +612 -0
  207. agentic_project_kit/patterns.py +99 -0
  208. agentic_project_kit/planning_docs_consolidation_audit.py +313 -0
  209. agentic_project_kit/portability_shell_gate.py +40 -0
  210. agentic_project_kit/post_merge_handoff_refresh.py +56 -0
  211. agentic_project_kit/post_release.py +252 -0
  212. agentic_project_kit/post_release_closeout.py +616 -0
  213. agentic_project_kit/pr_cleanup.py +172 -0
  214. agentic_project_kit/pr_closeout.py +50 -0
  215. agentic_project_kit/pr_closeout_complete.py +344 -0
  216. agentic_project_kit/pr_create_or_skip.py +71 -0
  217. agentic_project_kit/pr_hygiene.py +210 -0
  218. agentic_project_kit/program_redundancy_audit.py +251 -0
  219. agentic_project_kit/project_direction.py +840 -0
  220. agentic_project_kit/protected_change_planner.py +194 -0
  221. agentic_project_kit/release.py +401 -0
  222. agentic_project_kit/release_doi_safety.py +24 -0
  223. agentic_project_kit/release_gate_core.py +174 -0
  224. agentic_project_kit/release_metadata_authority_gate.py +328 -0
  225. agentic_project_kit/release_metadata_prep.py +43 -0
  226. agentic_project_kit/release_notes.py +823 -0
  227. agentic_project_kit/release_prep_core.py +204 -0
  228. agentic_project_kit/release_prepare.py +369 -0
  229. agentic_project_kit/release_process_guardrails.py +247 -0
  230. agentic_project_kit/release_publish_core.py +114 -0
  231. agentic_project_kit/release_publish_orchestration.py +469 -0
  232. agentic_project_kit/release_state.py +552 -0
  233. agentic_project_kit/release_verify_core.py +175 -0
  234. agentic_project_kit/remote_branch_hygiene.py +223 -0
  235. agentic_project_kit/remote_next.py +89 -0
  236. agentic_project_kit/remote_next_closeout.py +101 -0
  237. agentic_project_kit/remote_next_order_contract.py +391 -0
  238. agentic_project_kit/removed_ns_commands.py +458 -0
  239. agentic_project_kit/removed_source_audit.py +225 -0
  240. agentic_project_kit/rendering.py +13 -0
  241. agentic_project_kit/repair_report.py +79 -0
  242. agentic_project_kit/repo_identity.py +59 -0
  243. agentic_project_kit/result_report_classifier.py +57 -0
  244. agentic_project_kit/rule_ack.py +105 -0
  245. agentic_project_kit/rule_preservation.py +58 -0
  246. agentic_project_kit/rule_refresh.py +174 -0
  247. agentic_project_kit/rule_registry_registration.py +322 -0
  248. agentic_project_kit/rule_registry_report.py +206 -0
  249. agentic_project_kit/rule_registry_validator.py +704 -0
  250. agentic_project_kit/rule_snapshot.py +98 -0
  251. agentic_project_kit/rule_source_validator.py +133 -0
  252. agentic_project_kit/run_summary.py +68 -0
  253. agentic_project_kit/run_summary_renderer.py +238 -0
  254. agentic_project_kit/runtime_validator.py +68 -0
  255. agentic_project_kit/safe_file_replace.py +35 -0
  256. agentic_project_kit/safe_patch.py +47 -0
  257. agentic_project_kit/safe_push.py +218 -0
  258. agentic_project_kit/safe_remove_diagnostic.py +51 -0
  259. agentic_project_kit/scaffold.py +69 -0
  260. agentic_project_kit/site_claims.py +444 -0
  261. agentic_project_kit/site_generator.py +1140 -0
  262. agentic_project_kit/slice_gate.py +225 -0
  263. agentic_project_kit/slice_runner.py +75 -0
  264. agentic_project_kit/standard_gates_audit_suite.py +167 -0
  265. agentic_project_kit/state_freshness.py +135 -0
  266. agentic_project_kit/status_current_state_audit.py +762 -0
  267. agentic_project_kit/successor_handoff_package.py +1763 -0
  268. agentic_project_kit/templates.py +292 -0
  269. agentic_project_kit/terminal_block_guard.py +166 -0
  270. agentic_project_kit/terminal_logging.py +275 -0
  271. agentic_project_kit/todo.py +97 -0
  272. agentic_project_kit/transfer_closeout.py +136 -0
  273. agentic_project_kit/transfer_continue.py +215 -0
  274. agentic_project_kit/transfer_local_runner.py +101 -0
  275. agentic_project_kit/transfer_operation_monitor.py +236 -0
  276. agentic_project_kit/transfer_post_merge_lifecycle.py +356 -0
  277. agentic_project_kit/transfer_post_merge_settle.py +383 -0
  278. agentic_project_kit/transfer_pr_actions.py +164 -0
  279. agentic_project_kit/transfer_remote_next.py +959 -0
  280. agentic_project_kit/transfer_repo_actions.py +2253 -0
  281. agentic_project_kit/transfer_runner.py +347 -0
  282. agentic_project_kit/transfer_safety_context.py +291 -0
  283. agentic_project_kit/transfer_state.py +483 -0
  284. agentic_project_kit/transfer_uplink.py +471 -0
  285. agentic_project_kit/transfer_workflow_next.py +148 -0
  286. agentic_project_kit/typed_work_order_evidence.py +58 -0
  287. agentic_project_kit/typed_work_order_queue.py +166 -0
  288. agentic_project_kit/typed_work_order_runner.py +168 -0
  289. agentic_project_kit/work_cycle.py +317 -0
  290. agentic_project_kit/work_discard_changes.py +129 -0
  291. agentic_project_kit/work_order_patch.py +199 -0
  292. agentic_project_kit/work_order_runner.py +120 -0
  293. agentic_project_kit/work_order_uploader.py +220 -0
  294. agentic_project_kit/work_order_validator.py +185 -0
  295. agentic_project_kit/work_orders.py +246 -0
  296. agentic_project_kit/workflow_guard.py +262 -0
  297. agentic_project_kit/workflow_summary_runner.py +124 -0
  298. agentic_project_kit/workspace.py +665 -0
  299. agentic_project_kit/workspace_adopt.py +471 -0
  300. agentic_project_kit/workspace_dpa_intake.py +406 -0
  301. agentic_project_kit/workspace_init.py +487 -0
  302. agentic_project_kit/workspace_lock.py +129 -0
  303. agentic_project_kit/workspace_remove.py +381 -0
  304. agentic_project_kit/workspace_upgrade.py +324 -0
  305. agentic_project_kit/wrapper_live_status.py +104 -0
  306. agentic_project_kit-1.0.1.dist-info/METADATA +724 -0
  307. agentic_project_kit-1.0.1.dist-info/RECORD +310 -0
  308. agentic_project_kit-1.0.1.dist-info/WHEEL +4 -0
  309. agentic_project_kit-1.0.1.dist-info/entry_points.txt +3 -0
  310. agentic_project_kit-1.0.1.dist-info/licenses/LICENSE +10 -0
@@ -0,0 +1,762 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Callable, Sequence
4
+ from dataclasses import asdict, dataclass
5
+ import json
6
+ from pathlib import Path
7
+ import re
8
+ import subprocess
9
+ import tomllib
10
+ from typing import Any
11
+
12
+ from agentic_project_kit.release_state import (
13
+ ReleaseLifecycleStatus,
14
+ build_release_lifecycle_status,
15
+ )
16
+
17
+
18
+ GitRunner = Callable[[Path, Sequence[str]], "GitResult"]
19
+ ReleaseStatusBuilder = Callable[[Path], ReleaseLifecycleStatus]
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class GitResult:
24
+ returncode: int
25
+ stdout: str
26
+ stderr: str = ""
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class StatusCurrentStateFinding:
31
+ path: str
32
+ check: str
33
+ status: str
34
+ detail: str
35
+
36
+ def as_dict(self) -> dict[str, object]:
37
+ return asdict(self)
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class StatusCurrentStateAuditResult:
42
+ root: str
43
+ package_version: str | None
44
+ status_version: str | None
45
+ status_current_verified_release: str | None
46
+ status_current_verified_main: str | None
47
+ validation_status: str | None
48
+ validation_generated_head: str | None
49
+ origin_main: str | None
50
+ release_current_state: str | None
51
+ findings: tuple[StatusCurrentStateFinding, ...]
52
+ blockers: tuple[StatusCurrentStateFinding, ...]
53
+ warnings: tuple[StatusCurrentStateFinding, ...] = ()
54
+
55
+ @property
56
+ def ok(self) -> bool:
57
+ return not self.blockers
58
+
59
+ @property
60
+ def status(self) -> str:
61
+ return "PASS" if self.ok else "BLOCK"
62
+
63
+ @property
64
+ def returncode(self) -> int:
65
+ return 0 if self.ok else 2
66
+
67
+ def as_dict(self) -> dict[str, object]:
68
+ return {
69
+ "schema_version": 1,
70
+ "kind": "status_current_state_audit",
71
+ "root": self.root,
72
+ "status": self.status,
73
+ "package_version": self.package_version,
74
+ "status_version": self.status_version,
75
+ "status_current_verified_release": self.status_current_verified_release,
76
+ "status_current_verified_main": self.status_current_verified_main,
77
+ "validation_status": self.validation_status,
78
+ "validation_generated_head": self.validation_generated_head,
79
+ "origin_main": self.origin_main,
80
+ "release_current_state": self.release_current_state,
81
+ "finding_count": len(self.findings),
82
+ "blocker_count": len(self.blockers),
83
+ "warning_count": len(self.warnings),
84
+ "findings": [finding.as_dict() for finding in self.findings],
85
+ "blockers": [finding.as_dict() for finding in self.blockers],
86
+ "warnings": [finding.as_dict() for finding in self.warnings],
87
+ }
88
+
89
+
90
+ def audit_status_current_state(
91
+ root: Path = Path("."),
92
+ *,
93
+ git_runner: GitRunner | None = None,
94
+ release_status_builder: ReleaseStatusBuilder | None = None,
95
+ max_origin_lag: int = 3,
96
+ ) -> StatusCurrentStateAuditResult:
97
+ root = root.resolve()
98
+ findings: list[StatusCurrentStateFinding] = []
99
+ blockers: list[StatusCurrentStateFinding] = []
100
+ warnings: list[StatusCurrentStateFinding] = []
101
+ run_git = git_runner or _run_git
102
+
103
+ pyproject_version = _project_version(root)
104
+ status_text = _read_text(root / "docs" / "STATUS.md")
105
+ validation = _read_json(root / "docs" / "reports" / "handoff-packages" / "latest" / "validation_report.json")
106
+ current_block = _current_state_block(status_text)
107
+ status_version = _match(r"^Current version:\s*([^\s.]+(?:\.[^\s.]+){2})\.?$", current_block)
108
+ status_release = _match(r"^Current verified release:\s*v?([0-9]+\.[0-9]+\.[0-9]+)\.?", current_block)
109
+ status_verified_version_doi = _status_verified_version_doi(current_block)
110
+ status_main = _current_verified_main(current_block)
111
+ validation_status = _string_or_none(validation.get("status"))
112
+ validation_head = _string_or_none(validation.get("generated_head"))
113
+ origin_main = _origin_main(root, run_git)
114
+ release_status = _build_release_status(root, release_status_builder)
115
+ release_current_state = release_status.current_state if release_status is not None else None
116
+
117
+ _finding(findings, blockers, "docs/STATUS.md", "status_file_exists", bool(status_text), "exists" if status_text else "missing")
118
+ _finding(findings, blockers, "pyproject.toml", "package_version_exists", pyproject_version is not None, f"version={pyproject_version}")
119
+ _finding(
120
+ findings,
121
+ blockers,
122
+ "docs/STATUS.md",
123
+ "current_state_block_exists",
124
+ bool(current_block),
125
+ "## Current State block found" if current_block else "## Current State block missing",
126
+ )
127
+ _finding(
128
+ findings,
129
+ blockers,
130
+ "docs/STATUS.md",
131
+ "status_current_version_matches_pyproject",
132
+ bool(pyproject_version and status_version == pyproject_version),
133
+ f"status={status_version}, pyproject={pyproject_version}",
134
+ )
135
+ _audit_status_release_marker(
136
+ findings=findings,
137
+ blockers=blockers,
138
+ release_status=release_status,
139
+ pyproject_version=pyproject_version,
140
+ status_release=status_release,
141
+ )
142
+ _audit_changelog_current_pending_doi(
143
+ findings=findings,
144
+ blockers=blockers,
145
+ root=root,
146
+ pyproject_version=pyproject_version,
147
+ status_version=status_version,
148
+ status_verified_version_doi=status_verified_version_doi,
149
+ release_current_state=release_current_state,
150
+ )
151
+ _audit_status_current_state_instruction_freshness(
152
+ findings=findings,
153
+ blockers=blockers,
154
+ current_block=current_block,
155
+ pyproject_version=pyproject_version,
156
+ status_release=status_release,
157
+ status_verified_version_doi=status_verified_version_doi,
158
+ release_current_state=release_current_state,
159
+ )
160
+ _audit_status_main_marker(
161
+ root=root,
162
+ run_git=run_git,
163
+ findings=findings,
164
+ blockers=blockers,
165
+ status_text=status_text,
166
+ current_block=current_block,
167
+ status_main=status_main,
168
+ validation_head=validation_head,
169
+ release_current_state=release_current_state,
170
+ )
171
+ _finding(
172
+ findings,
173
+ blockers,
174
+ "docs/reports/handoff-packages/latest/validation_report.json",
175
+ "validation_report_status_pass",
176
+ validation_status == "PASS",
177
+ f"status={validation_status}",
178
+ )
179
+ _finding(
180
+ findings,
181
+ blockers,
182
+ "docs/reports/handoff-packages/latest/validation_report.json",
183
+ "validation_report_generated_head_exists",
184
+ bool(validation_head),
185
+ f"generated_head={validation_head}",
186
+ )
187
+ _audit_origin_main(
188
+ root=root,
189
+ run_git=run_git,
190
+ findings=findings,
191
+ blockers=blockers,
192
+ warnings=warnings,
193
+ validation_head=validation_head,
194
+ origin_main=origin_main,
195
+ release_current_state=release_current_state,
196
+ max_origin_lag=max_origin_lag,
197
+ )
198
+ _audit_release_status(
199
+ findings=findings,
200
+ blockers=blockers,
201
+ warnings=warnings,
202
+ release_status=release_status,
203
+ pyproject_version=pyproject_version,
204
+ status_release=status_release,
205
+ )
206
+
207
+ return StatusCurrentStateAuditResult(
208
+ root=root.as_posix(),
209
+ package_version=pyproject_version,
210
+ status_version=status_version,
211
+ status_current_verified_release=status_release,
212
+ status_current_verified_main=status_main,
213
+ validation_status=validation_status,
214
+ validation_generated_head=validation_head,
215
+ origin_main=origin_main,
216
+ release_current_state=release_current_state,
217
+ findings=tuple(findings),
218
+ blockers=tuple(blockers),
219
+ warnings=tuple(warnings),
220
+ )
221
+
222
+
223
+ def render_status_current_state_audit(result: StatusCurrentStateAuditResult) -> str:
224
+ lines = [
225
+ "STATUS_CURRENT_STATE_AUDIT",
226
+ f"STATUS={result.status}",
227
+ f"PACKAGE_VERSION={result.package_version}",
228
+ f"STATUS_VERSION={result.status_version}",
229
+ f"STATUS_CURRENT_VERIFIED_RELEASE={result.status_current_verified_release}",
230
+ f"STATUS_CURRENT_VERIFIED_MAIN={result.status_current_verified_main}",
231
+ f"VALIDATION_STATUS={result.validation_status}",
232
+ f"VALIDATION_GENERATED_HEAD={result.validation_generated_head}",
233
+ f"ORIGIN_MAIN={result.origin_main}",
234
+ f"RELEASE_CURRENT_STATE={result.release_current_state}",
235
+ f"FINDING_COUNT={len(result.findings)}",
236
+ f"BLOCKER_COUNT={len(result.blockers)}",
237
+ f"WARNING_COUNT={len(result.warnings)}",
238
+ ]
239
+ for item in result.blockers:
240
+ lines.append(f"BLOCKER={item.path}|{item.check}|{item.status}|{item.detail}")
241
+ for item in result.warnings:
242
+ lines.append(f"WARNING={item.path}|{item.check}|{item.status}|{item.detail}")
243
+ return "\n".join(lines) + "\n"
244
+
245
+
246
+ def _run_git(root: Path, args: Sequence[str]) -> GitResult:
247
+ completed = subprocess.run(
248
+ ["git", *args],
249
+ cwd=root,
250
+ text=True,
251
+ stdout=subprocess.PIPE,
252
+ stderr=subprocess.PIPE,
253
+ check=False,
254
+ )
255
+ return GitResult(completed.returncode, completed.stdout, completed.stderr)
256
+
257
+
258
+ def _read_text(path: Path) -> str:
259
+ return path.read_text(encoding="utf-8") if path.exists() else ""
260
+
261
+
262
+ def _read_json(path: Path) -> dict[str, Any]:
263
+ if not path.exists():
264
+ return {}
265
+ try:
266
+ loaded = json.loads(path.read_text(encoding="utf-8"))
267
+ except json.JSONDecodeError:
268
+ return {}
269
+ return loaded if isinstance(loaded, dict) else {}
270
+
271
+
272
+ def _project_version(root: Path) -> str | None:
273
+ pyproject = root / "pyproject.toml"
274
+ if not pyproject.exists():
275
+ return None
276
+ data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
277
+ value = data.get("project", {}).get("version")
278
+ return str(value) if value is not None else None
279
+
280
+
281
+ def _build_release_status(
282
+ root: Path,
283
+ builder: ReleaseStatusBuilder | None,
284
+ ) -> ReleaseLifecycleStatus | None:
285
+ try:
286
+ return (builder or (lambda project_root: build_release_lifecycle_status(project_root)))(root)
287
+ except Exception:
288
+ return None
289
+
290
+
291
+ def _match(pattern: str, text: str) -> str | None:
292
+ match = re.search(pattern, text, re.MULTILINE)
293
+ return match.group(1).strip() if match else None
294
+
295
+
296
+ def _current_state_block(status_text: str) -> str:
297
+ match = re.search(r"(?ms)^## Current State\s*(.*?)(?=^## |\Z)", status_text)
298
+ return match.group(1).strip() if match else ""
299
+
300
+
301
+ def _status_verified_version_doi(current_block: str) -> tuple[str, int] | None:
302
+ for index, line in enumerate(current_block.splitlines(), start=1):
303
+ match = re.search(r"^Verified Zenodo version DOI:\s*`?([^`.\s]+(?:\.[^`.\s]+)+)`?\.?", line)
304
+ if match:
305
+ return match.group(1).strip(), index
306
+ return None
307
+
308
+
309
+ def _current_changelog_block(changelog_text: str, version: str) -> tuple[str, int]:
310
+ pattern = re.compile(rf"(?ms)^## v{re.escape(version)}\b.*?(?=^## v|\Z)")
311
+ match = pattern.search(changelog_text)
312
+ if not match:
313
+ return "", 0
314
+ start_line = changelog_text[: match.start()].count("\n") + 1
315
+ return match.group(0), start_line
316
+
317
+
318
+ def _pending_doi_lines(block: str, *, start_line: int) -> list[tuple[int, str]]:
319
+ lines: list[tuple[int, str]] = []
320
+ for offset, line in enumerate(block.splitlines()):
321
+ if re.search(r"\bzenodo\b.*\bdoi\b.*\bverification\b.*\bpending\b", line, re.IGNORECASE):
322
+ lines.append((start_line + offset, line.strip()))
323
+ return lines
324
+
325
+
326
+ def _audit_changelog_current_pending_doi(
327
+ *,
328
+ findings: list[StatusCurrentStateFinding],
329
+ blockers: list[StatusCurrentStateFinding],
330
+ root: Path,
331
+ pyproject_version: str | None,
332
+ status_version: str | None,
333
+ status_verified_version_doi: tuple[str, int] | None,
334
+ release_current_state: str | None,
335
+ ) -> None:
336
+ changelog_path = root / "CHANGELOG.md"
337
+ changelog_text = _read_text(changelog_path)
338
+ if not pyproject_version:
339
+ return
340
+ block, start_line = _current_changelog_block(changelog_text, pyproject_version)
341
+ _finding(
342
+ findings,
343
+ blockers,
344
+ "CHANGELOG.md",
345
+ "changelog_current_version_block_exists",
346
+ True,
347
+ f"version={pyproject_version}; found={bool(block)}",
348
+ )
349
+ if not block:
350
+ return
351
+
352
+ pending_lines = _pending_doi_lines(block, start_line=start_line)
353
+ stale_pending = bool(
354
+ pending_lines
355
+ and status_version == pyproject_version
356
+ and status_verified_version_doi is not None
357
+ and release_current_state != "prepared"
358
+ )
359
+ if stale_pending:
360
+ doi, status_line = status_verified_version_doi
361
+ pending_locations = ", ".join(
362
+ f"CHANGELOG.md:{line_no}:{line_text}" for line_no, line_text in pending_lines
363
+ )
364
+ detail = (
365
+ f"version={pyproject_version}; pending={pending_locations}; "
366
+ f"verified=docs/STATUS.md:{status_line}:Verified Zenodo version DOI {doi}"
367
+ )
368
+ else:
369
+ detail = (
370
+ f"version={pyproject_version}; pending_lines={len(pending_lines)}; "
371
+ f"status_version={status_version}; "
372
+ f"status_verified_doi={status_verified_version_doi[0] if status_verified_version_doi else None}; "
373
+ f"release_state={release_current_state}"
374
+ )
375
+ _finding(
376
+ findings,
377
+ blockers,
378
+ "CHANGELOG.md",
379
+ "changelog_stale_pending_doi",
380
+ not stale_pending,
381
+ detail,
382
+ )
383
+
384
+
385
+ def _audit_status_current_state_instruction_freshness(
386
+ *,
387
+ findings: list[StatusCurrentStateFinding],
388
+ blockers: list[StatusCurrentStateFinding],
389
+ current_block: str,
390
+ pyproject_version: str | None,
391
+ status_release: str | None,
392
+ status_verified_version_doi: tuple[str, int] | None,
393
+ release_current_state: str | None,
394
+ ) -> None:
395
+ instruction_lines = _current_state_instruction_lines(current_block)
396
+ stale_lines: list[tuple[int, str]] = []
397
+ if (
398
+ release_current_state == "current_verified"
399
+ and pyproject_version
400
+ and status_release == pyproject_version
401
+ and status_verified_version_doi is not None
402
+ ):
403
+ stale_lines = [
404
+ (line_no, line)
405
+ for line_no, line in instruction_lines
406
+ if _is_stale_current_release_instruction(line, pyproject_version)
407
+ ]
408
+ detail = (
409
+ "stale_lines="
410
+ + repr([f"docs/STATUS.md current block line {line_no}: {line}" for line_no, line in stale_lines])
411
+ + f"; release_state={release_current_state}; status_release={status_release}; "
412
+ f"pyproject={pyproject_version}; verified_doi={status_verified_version_doi[0] if status_verified_version_doi else None}"
413
+ )
414
+ _finding(
415
+ findings,
416
+ blockers,
417
+ "docs/STATUS.md",
418
+ "status_current_state_stale_release_instruction",
419
+ not stale_lines,
420
+ detail,
421
+ )
422
+
423
+
424
+ def _current_state_instruction_lines(current_block: str) -> list[tuple[int, str]]:
425
+ lines: list[tuple[int, str]] = []
426
+ for index, line in enumerate(current_block.splitlines(), start=1):
427
+ stripped = line.strip()
428
+ if stripped.startswith(("Current governed slice:", "Next safe step:")):
429
+ lines.append((index, stripped))
430
+ return lines
431
+
432
+
433
+ def _is_stale_current_release_instruction(line: str, version: str) -> bool:
434
+ normalized = line.lower()
435
+ if any(
436
+ marker in normalized
437
+ for marker in ("do not ", "must not ", "avoid ", "not repeat", "no need to ")
438
+ ):
439
+ return False
440
+ version_refs = {version.lower(), f"v{version}".lower()}
441
+ release_ref = "release" in normalized or any(ref in normalized for ref in version_refs)
442
+ stale_verb = re.search(r"\b(publish|prepare|verify|regenerate|upload|create|cut)\b", normalized)
443
+ if release_ref and stale_verb:
444
+ return True
445
+ return "pre-release" in normalized
446
+
447
+
448
+ _CURRENT_VERIFIED_MAIN_PATTERN = r"^Current verified main:\s*`?([0-9a-f]{7,40})`?"
449
+ _CURRENT_VERIFIED_MAIN_HEAD_PATTERN = r"^Current verified main HEAD(?:\s+is)?(?::)?\s*`?([0-9a-f]{7,40})`?"
450
+
451
+
452
+ def _current_verified_main(current_block: str) -> str | None:
453
+ markers = _marker_values(current_block, _CURRENT_VERIFIED_MAIN_PATTERN)
454
+ return markers[0] if markers else None
455
+
456
+
457
+ def _marker_values(text: str, pattern: str) -> list[str]:
458
+ return re.findall(pattern, text, re.MULTILINE)
459
+
460
+
461
+ def _string_or_none(value: object) -> str | None:
462
+ return str(value) if value is not None else None
463
+
464
+
465
+ def _finding(
466
+ findings: list[StatusCurrentStateFinding],
467
+ blockers: list[StatusCurrentStateFinding],
468
+ path: str,
469
+ check: str,
470
+ ok: bool,
471
+ detail: str,
472
+ ) -> None:
473
+ item = StatusCurrentStateFinding(path, check, "PASS" if ok else "BLOCK", detail)
474
+ findings.append(item)
475
+ if not ok:
476
+ blockers.append(item)
477
+
478
+
479
+ def _warning(
480
+ findings: list[StatusCurrentStateFinding],
481
+ warnings: list[StatusCurrentStateFinding],
482
+ path: str,
483
+ check: str,
484
+ detail: str,
485
+ ) -> None:
486
+ item = StatusCurrentStateFinding(path, check, "WARN", detail)
487
+ findings.append(item)
488
+ warnings.append(item)
489
+
490
+
491
+ def _audit_status_main_marker(
492
+ *,
493
+ root: Path,
494
+ run_git: GitRunner,
495
+ findings: list[StatusCurrentStateFinding],
496
+ blockers: list[StatusCurrentStateFinding],
497
+ status_text: str,
498
+ current_block: str,
499
+ status_main: str | None,
500
+ validation_head: str | None,
501
+ release_current_state: str | None,
502
+ ) -> None:
503
+ live_text = status_text.split("## Historical State Snapshots", 1)[0]
504
+ live_markers = _marker_values(live_text, _CURRENT_VERIFIED_MAIN_PATTERN)
505
+ current_block_markers = _marker_values(current_block, _CURRENT_VERIFIED_MAIN_PATTERN)
506
+ live_unique = _unique_values(live_markers)
507
+ current_block_unique = _unique_values(current_block_markers)
508
+ _finding(
509
+ findings,
510
+ blockers,
511
+ "docs/STATUS.md",
512
+ "status_live_area_current_verified_main_values_consistent",
513
+ len(live_unique) <= 1,
514
+ f"live_values={live_unique}",
515
+ )
516
+ _finding(
517
+ findings,
518
+ blockers,
519
+ "docs/STATUS.md",
520
+ "status_current_block_current_verified_main_values_consistent",
521
+ len(current_block_unique) <= 1,
522
+ f"current_block_values={current_block_unique}",
523
+ )
524
+ _finding(
525
+ findings,
526
+ blockers,
527
+ "docs/STATUS.md",
528
+ "status_live_area_single_current_verified_main",
529
+ len(live_markers) == 1,
530
+ f"live_marker_count={len(live_markers)}",
531
+ )
532
+ _finding(
533
+ findings,
534
+ blockers,
535
+ "docs/STATUS.md",
536
+ "status_current_block_single_current_verified_main",
537
+ len(current_block_markers) == 1,
538
+ f"current_block_marker_count={len(current_block_markers)}",
539
+ )
540
+ live_head_markers = _marker_values(live_text, _CURRENT_VERIFIED_MAIN_HEAD_PATTERN)
541
+ live_head_unique = _unique_values(live_head_markers)
542
+ _finding(
543
+ findings,
544
+ blockers,
545
+ "docs/STATUS.md",
546
+ "status_md_internal_head_conflict",
547
+ len(live_head_unique) <= 1,
548
+ f"live_head_values={live_head_unique}",
549
+ )
550
+ matches_validation = bool(status_main and validation_head and validation_head.startswith(status_main))
551
+ if not matches_validation and release_current_state == "prepared" and status_main and validation_head:
552
+ ancestor = run_git(root, ("merge-base", "--is-ancestor", status_main, validation_head))
553
+ matches_validation = ancestor.returncode == 0
554
+ if not matches_validation and _is_bounded_admin_refresh_validation_head(
555
+ root,
556
+ run_git,
557
+ status_main=status_main,
558
+ validation_head=validation_head,
559
+ ):
560
+ matches_validation = True
561
+ _finding(
562
+ findings,
563
+ blockers,
564
+ "docs/STATUS.md",
565
+ "status_current_verified_main_matches_handoff_validation_head",
566
+ matches_validation,
567
+ f"status_main={status_main}, validation_head={validation_head}, release_state={release_current_state}",
568
+ )
569
+
570
+
571
+ def _audit_status_release_marker(
572
+ *,
573
+ findings: list[StatusCurrentStateFinding],
574
+ blockers: list[StatusCurrentStateFinding],
575
+ release_status: ReleaseLifecycleStatus | None,
576
+ pyproject_version: str | None,
577
+ status_release: str | None,
578
+ ) -> None:
579
+ if release_status is None:
580
+ _finding(
581
+ findings,
582
+ blockers,
583
+ "docs/STATUS.md",
584
+ "status_current_verified_release_matches_pyproject",
585
+ bool(pyproject_version and status_release == pyproject_version),
586
+ f"status_release={status_release}, pyproject={pyproject_version}",
587
+ )
588
+ return
589
+ _finding(
590
+ findings,
591
+ blockers,
592
+ "docs/STATUS.md",
593
+ "status_current_verified_release_matches_release_status",
594
+ bool(status_release and status_release == release_status.current_verified_version),
595
+ (
596
+ f"status_release={status_release}, "
597
+ f"release_status_current_verified={release_status.current_verified_version}, "
598
+ f"release_state={release_status.current_state}"
599
+ ),
600
+ )
601
+
602
+
603
+ def _unique_values(values: Sequence[str]) -> list[str]:
604
+ return sorted(set(values))
605
+
606
+
607
+ def _is_bounded_admin_refresh_validation_head(
608
+ root: Path,
609
+ run_git: GitRunner,
610
+ *,
611
+ status_main: str | None,
612
+ validation_head: str | None,
613
+ ) -> bool:
614
+ if not status_main or not validation_head:
615
+ return False
616
+ subject = run_git(root, ("log", "-1", "--pretty=%s", validation_head))
617
+ if subject.returncode != 0 or not _is_admin_refresh_merge_subject(subject.stdout.strip()):
618
+ return False
619
+ ancestor = run_git(root, ("merge-base", "--is-ancestor", status_main, validation_head))
620
+ if ancestor.returncode != 0:
621
+ return False
622
+ first_parent_count = run_git(
623
+ root,
624
+ ("rev-list", "--count", "--first-parent", f"{status_main}..{validation_head}"),
625
+ )
626
+ if first_parent_count.returncode != 0:
627
+ return False
628
+ try:
629
+ return int(first_parent_count.stdout.strip()) == 1
630
+ except ValueError:
631
+ return False
632
+
633
+
634
+ def _is_admin_refresh_merge_subject(subject: str) -> bool:
635
+ return (
636
+ subject.startswith("Refresh handoff state after PR")
637
+ or subject.startswith("Refresh successor handoff after PR")
638
+ ) and "(#" in subject
639
+
640
+
641
+ def _origin_main(root: Path, run_git: GitRunner) -> str | None:
642
+ result = run_git(root, ("rev-parse", "--verify", "origin/main"))
643
+ if result.returncode != 0:
644
+ return None
645
+ return result.stdout.strip() or None
646
+
647
+
648
+ def _audit_origin_main(
649
+ *,
650
+ root: Path,
651
+ run_git: GitRunner,
652
+ findings: list[StatusCurrentStateFinding],
653
+ blockers: list[StatusCurrentStateFinding],
654
+ warnings: list[StatusCurrentStateFinding],
655
+ validation_head: str | None,
656
+ origin_main: str | None,
657
+ release_current_state: str | None,
658
+ max_origin_lag: int,
659
+ ) -> None:
660
+ _finding(
661
+ findings,
662
+ blockers,
663
+ "origin/main",
664
+ "origin_main_resolves",
665
+ bool(origin_main),
666
+ f"origin_main={origin_main}",
667
+ )
668
+ if not validation_head or not origin_main:
669
+ return
670
+ ancestor = run_git(root, ("merge-base", "--is-ancestor", validation_head, origin_main))
671
+ if ancestor.returncode != 0 and release_current_state == "prepared":
672
+ descendant = run_git(root, ("merge-base", "--is-ancestor", origin_main, validation_head))
673
+ if descendant.returncode == 0:
674
+ _finding(
675
+ findings,
676
+ blockers,
677
+ "origin/main",
678
+ "handoff_validation_head_reachable_from_origin_main",
679
+ True,
680
+ (
681
+ f"validation_head={validation_head}, origin_main={origin_main}, "
682
+ "release_state=prepared, validation_head_descends_from_origin_main=True"
683
+ ),
684
+ )
685
+ return
686
+ _finding(
687
+ findings,
688
+ blockers,
689
+ "origin/main",
690
+ "handoff_validation_head_reachable_from_origin_main",
691
+ ancestor.returncode == 0,
692
+ f"validation_head={validation_head}, origin_main={origin_main}, returncode={ancestor.returncode}",
693
+ )
694
+ if ancestor.returncode != 0:
695
+ return
696
+ lag = run_git(root, ("rev-list", "--count", f"{validation_head}..{origin_main}"))
697
+ if lag.returncode != 0:
698
+ _warning(
699
+ findings,
700
+ warnings,
701
+ "origin/main",
702
+ "origin_lag_not_checked",
703
+ lag.stderr.strip() or "git rev-list failed",
704
+ )
705
+ return
706
+ try:
707
+ lag_count = int(lag.stdout.strip())
708
+ except ValueError:
709
+ _warning(findings, warnings, "origin/main", "origin_lag_not_numeric", f"stdout={lag.stdout.strip()}")
710
+ return
711
+ _finding(
712
+ findings,
713
+ blockers,
714
+ "origin/main",
715
+ "handoff_validation_head_not_too_far_behind_origin_main",
716
+ lag_count <= max_origin_lag,
717
+ f"lag_count={lag_count}, max_origin_lag={max_origin_lag}",
718
+ )
719
+
720
+
721
+ def _audit_release_status(
722
+ *,
723
+ findings: list[StatusCurrentStateFinding],
724
+ blockers: list[StatusCurrentStateFinding],
725
+ warnings: list[StatusCurrentStateFinding],
726
+ release_status: ReleaseLifecycleStatus | None,
727
+ pyproject_version: str | None,
728
+ status_release: str | None,
729
+ ) -> None:
730
+ if release_status is None:
731
+ _warning(
732
+ findings,
733
+ warnings,
734
+ "release-status",
735
+ "release_status_unavailable",
736
+ "release-status could not be built; release comparison skipped",
737
+ )
738
+ return
739
+ _finding(
740
+ findings,
741
+ blockers,
742
+ "release-status",
743
+ "release_status_current_or_prepared",
744
+ release_status.current_state in {"current_verified", "prepared"} and not release_status.blockers,
745
+ f"current_state={release_status.current_state}, blockers={list(release_status.blockers)}",
746
+ )
747
+ _finding(
748
+ findings,
749
+ blockers,
750
+ "release-status",
751
+ "release_status_version_matches_pyproject",
752
+ bool(pyproject_version and release_status.package_version == pyproject_version),
753
+ f"release_status_package={release_status.package_version}, pyproject={pyproject_version}",
754
+ )
755
+ _finding(
756
+ findings,
757
+ blockers,
758
+ "docs/STATUS.md",
759
+ "status_release_matches_release_status",
760
+ bool(status_release and status_release == release_status.current_verified_version),
761
+ f"status_release={status_release}, release_status_current_verified={release_status.current_verified_version}",
762
+ )