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,172 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path
5
+ import json
6
+ import subprocess
7
+ from typing import Any
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class PullRequestInfo:
12
+ number: int
13
+ head: str
14
+ base: str
15
+ mergeable: str
16
+ is_draft: bool
17
+ author: str
18
+ updated_at: str
19
+ title: str
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class ClassifiedPullRequest:
24
+ info: PullRequestInfo
25
+ pr_class: str
26
+ action: str
27
+
28
+
29
+ def classify_pr(pr: PullRequestInfo) -> ClassifiedPullRequest:
30
+ pr_class = "ACTIVE_FEATURE_PR"
31
+ action = "review_manually"
32
+
33
+ if pr.head.startswith("dependabot/"):
34
+ pr_class = "DEPENDABOT_PR"
35
+ action = "review_dependency_update"
36
+ elif pr.head.startswith(("docs/finalize-", "docs/record-", "docs/post-")):
37
+ pr_class = "STALE_DOCS_FINALIZATION_CANDIDATE"
38
+ action = "run_finalize_guard_before_closing_or_recreating"
39
+ elif pr.head.startswith("release/prepare-"):
40
+ pr_class = "RELEASE_PREP_PR"
41
+ action = "verify_release_state_before_merge_or_close"
42
+
43
+ if pr.mergeable == "CONFLICTING":
44
+ if pr_class == "STALE_DOCS_FINALIZATION_CANDIDATE":
45
+ pr_class = "SUPERSEDED_OR_CONFLICTING_DOCS_FINALIZATION"
46
+ action = "run_finalize_guard_then_human_decide_safe_close"
47
+ elif pr_class == "DEPENDABOT_PR":
48
+ action = "review_dependency_conflict"
49
+ else:
50
+ pr_class = "CONFLICTING_RELEVANT_PR"
51
+ action = "human_review_required"
52
+
53
+ if pr.is_draft:
54
+ action = "draft_review_required"
55
+
56
+ return ClassifiedPullRequest(pr, pr_class, action)
57
+
58
+
59
+ def _run(repo_root: Path, args: list[str]) -> tuple[int, str]:
60
+ completed = subprocess.run(
61
+ args,
62
+ cwd=repo_root,
63
+ text=True,
64
+ stdout=subprocess.PIPE,
65
+ stderr=subprocess.STDOUT,
66
+ check=False,
67
+ )
68
+ return completed.returncode, completed.stdout.strip()
69
+
70
+
71
+ def _author_login(raw_author: Any) -> str:
72
+ if isinstance(raw_author, dict):
73
+ return str(raw_author.get("login") or "")
74
+ return str(raw_author or "")
75
+
76
+
77
+ def parse_prs(payload: str) -> list[PullRequestInfo]:
78
+ data = json.loads(payload or "[]")
79
+ prs: list[PullRequestInfo] = []
80
+ for item in data:
81
+ prs.append(
82
+ PullRequestInfo(
83
+ number=int(item.get("number", 0)),
84
+ head=str(item.get("headRefName") or ""),
85
+ base=str(item.get("baseRefName") or ""),
86
+ mergeable=str(item.get("mergeable") or "UNKNOWN"),
87
+ is_draft=bool(item.get("isDraft", False)),
88
+ author=_author_login(item.get("author")),
89
+ updated_at=str(item.get("updatedAt") or ""),
90
+ title=str(item.get("title") or ""),
91
+ )
92
+ )
93
+ return prs
94
+
95
+
96
+ def list_open_prs(repo_root: Path) -> tuple[int, list[PullRequestInfo], str]:
97
+ rc, output = _run(
98
+ repo_root,
99
+ [
100
+ "gh",
101
+ "pr",
102
+ "list",
103
+ "--state",
104
+ "open",
105
+ "--limit",
106
+ "100",
107
+ "--json",
108
+ "number,headRefName,baseRefName,mergeable,isDraft,title,author,updatedAt",
109
+ ],
110
+ )
111
+ if rc != 0:
112
+ return rc, [], output
113
+ return 0, parse_prs(output), ""
114
+
115
+
116
+ def render_classification(classified: list[ClassifiedPullRequest], branch: str, status: str, ok: bool = True) -> str:
117
+ lines = [
118
+ "",
119
+ "",
120
+ "",
121
+ "-------------------------------------------------------------------------",
122
+ "-------------------------------------------------------------------------",
123
+ "-------------------------------------------------------------------------",
124
+ "",
125
+ "",
126
+ "",
127
+ "NS PR CLEANUP CLASSIFICATION",
128
+ "",
129
+ "### SAFETY ###",
130
+ "Safety: read-only PR classification; no close, merge, edit, push, delete, tag, or release action.",
131
+ "",
132
+ "### OPEN PR CLASSIFICATION ###",
133
+ f"open_pr_count={len(classified)}",
134
+ ]
135
+ if not classified:
136
+ lines.append("No open PRs found.")
137
+ for entry in classified:
138
+ pr = entry.info
139
+ draft = str(pr.is_draft).lower()
140
+ lines.append(
141
+ f"#{pr.number} class={entry.pr_class} action={entry.action} mergeable={pr.mergeable} "
142
+ f"draft={draft} head={pr.head} base={pr.base} author={pr.author} updated={pr.updated_at} title={pr.title}"
143
+ )
144
+ lines.extend(["", "### FINAL STATE ###", branch])
145
+ if status:
146
+ lines.append(status)
147
+ lines.append("" )
148
+ lines.append("### RESULT: PASS ###" if ok else "### RESULT: FAIL ###")
149
+ return "\n".join(lines)
150
+
151
+
152
+ def run_pr_cleanup(repo_root: Path) -> int:
153
+ rc, prs, error = list_open_prs(repo_root)
154
+ if rc != 0:
155
+ print("ERROR: unable to list open PRs.")
156
+ if error:
157
+ print(error)
158
+ print("\n### RESULT: FAIL ###")
159
+ return 1
160
+ branch_rc, branch = _run(repo_root, ["git", "branch", "--show-current"])
161
+ status_rc, status = _run(repo_root, ["git", "status", "--short"])
162
+ ok = branch_rc == 0 and status_rc == 0
163
+ print(render_classification([classify_pr(pr) for pr in prs], branch, status, ok=ok))
164
+ return 0 if ok else 1
165
+
166
+
167
+ def main() -> int:
168
+ return run_pr_cleanup(Path(".").resolve())
169
+
170
+
171
+ if __name__ == "__main__":
172
+ raise SystemExit(main())
@@ -0,0 +1,50 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Any
5
+
6
+ READY_TO_MERGE = "READY_TO_MERGE"
7
+ BLOCKED = "BLOCKED"
8
+
9
+ @dataclass(frozen=True)
10
+ class PrCloseoutResult:
11
+ outcome: str
12
+ reasons: tuple[str, ...]
13
+
14
+ def _check_success(entry: dict[str, Any]) -> bool:
15
+ return entry.get("status") == "COMPLETED" and entry.get("conclusion") == "SUCCESS"
16
+
17
+ def evaluate_pr_closeout(pr: dict[str, Any], expected_check_names: tuple[str, ...] = ("test",)) -> PrCloseoutResult:
18
+ reasons: list[str] = []
19
+ state = pr.get("state")
20
+ already_merged = state == "MERGED"
21
+ if state not in ("OPEN", "MERGED"):
22
+ reasons.append("state is not OPEN or MERGED")
23
+ if not already_merged and pr.get("mergeStateStatus") != "CLEAN":
24
+ reasons.append("mergeStateStatus is not CLEAN")
25
+ if not already_merged and pr.get("mergeable") not in ("MERGEABLE", True):
26
+ reasons.append("PR is not mergeable")
27
+ checks = pr.get("statusCheckRollup") or []
28
+ if not checks:
29
+ reasons.append("no status checks reported")
30
+ names = {str(item.get("name", "")) for item in checks if isinstance(item, dict)}
31
+ for expected in expected_check_names:
32
+ if expected not in names:
33
+ reasons.append(f"expected check missing: {expected}")
34
+ for item in checks:
35
+ if isinstance(item, dict) and not _check_success(item):
36
+ name = item.get("name", "<unknown>")
37
+ status = item.get("status", "<unknown>")
38
+ conclusion = item.get("conclusion", "<unknown>")
39
+ reasons.append(f"check not successful: {name} status={status} conclusion={conclusion}")
40
+ if reasons:
41
+ return PrCloseoutResult(BLOCKED, tuple(reasons))
42
+ if already_merged:
43
+ return PrCloseoutResult(READY_TO_MERGE, ())
44
+ return PrCloseoutResult(READY_TO_MERGE, ("merge required; do not continue without merge or explicit block",))
45
+
46
+ def render_pr_closeout(result: PrCloseoutResult) -> str:
47
+ lines = [f"PR closeout outcome: {result.outcome}"]
48
+ for reason in result.reasons:
49
+ lines.append(f"- {reason}")
50
+ return "\n".join(lines)
@@ -0,0 +1,344 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import subprocess
5
+ from dataclasses import asdict, dataclass, field
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from agentic_project_kit.transfer_post_merge_lifecycle import post_merge_complete
10
+ from agentic_project_kit.transfer_repo_actions import (
11
+ RepoActionResult,
12
+ pr_merge_safe,
13
+ pr_wait_ci,
14
+ repo_status,
15
+ )
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class PrCloseoutStep:
20
+ name: str
21
+ result_status: str
22
+ returncode: int
23
+ next_action: str
24
+ stdout: str = ""
25
+ stderr: str = ""
26
+
27
+ def as_json_data(self) -> dict[str, object]:
28
+ return asdict(self)
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class PrCloseoutCompleteResult:
33
+ after_pr: int
34
+ result_status: str
35
+ returncode: int
36
+ lifecycle_state: str
37
+ next_action: str
38
+ merged_pr: bool
39
+ refresh_pr: int | None = None
40
+ steps: tuple[PrCloseoutStep, ...] = field(default_factory=tuple)
41
+
42
+ def as_json_data(self) -> dict[str, object]:
43
+ data = asdict(self)
44
+ data["steps"] = [step.as_json_data() for step in self.steps]
45
+ return data
46
+
47
+
48
+ def _run_command(command: list[str], *, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
49
+ return subprocess.run(
50
+ command,
51
+ cwd=cwd,
52
+ check=False,
53
+ text=True,
54
+ stdout=subprocess.PIPE,
55
+ stderr=subprocess.PIPE,
56
+ )
57
+
58
+
59
+ def _completed_step(name: str, completed: subprocess.CompletedProcess[str], next_action: str) -> PrCloseoutStep:
60
+ return PrCloseoutStep(
61
+ name=name,
62
+ result_status="PASS" if completed.returncode == 0 else "FAIL",
63
+ returncode=completed.returncode,
64
+ next_action=next_action,
65
+ stdout=completed.stdout,
66
+ stderr=completed.stderr,
67
+ )
68
+
69
+
70
+ def _repo_step(name: str, result: RepoActionResult) -> PrCloseoutStep:
71
+ return PrCloseoutStep(
72
+ name=name,
73
+ result_status=result.result_status,
74
+ returncode=result.returncode,
75
+ next_action=result.next_action,
76
+ stdout=result.stdout,
77
+ stderr=result.stderr,
78
+ )
79
+
80
+
81
+ def _lifecycle_step(name: str, result: Any) -> PrCloseoutStep:
82
+ payload = result.as_json_data() if hasattr(result, "as_json_data") else {}
83
+ stdout = json.dumps(payload, indent=2, sort_keys=True)
84
+ return PrCloseoutStep(
85
+ name=name,
86
+ result_status=str(getattr(result, "result_status", "UNKNOWN")),
87
+ returncode=int(getattr(result, "returncode", 2)),
88
+ next_action=str(getattr(result, "next_action", "Inspect lifecycle result.")),
89
+ stdout=stdout,
90
+ stderr="",
91
+ )
92
+
93
+
94
+ def _finish(
95
+ *,
96
+ after_pr: int,
97
+ result_status: str,
98
+ returncode: int,
99
+ lifecycle_state: str,
100
+ next_action: str,
101
+ merged_pr: bool,
102
+ steps: list[PrCloseoutStep],
103
+ refresh_pr: int | None = None,
104
+ ) -> PrCloseoutCompleteResult:
105
+ return PrCloseoutCompleteResult(
106
+ after_pr=after_pr,
107
+ result_status=result_status,
108
+ returncode=returncode,
109
+ lifecycle_state=lifecycle_state,
110
+ next_action=next_action,
111
+ merged_pr=merged_pr,
112
+ refresh_pr=refresh_pr,
113
+ steps=tuple(steps),
114
+ )
115
+
116
+
117
+ def _load_pr_info(after_pr: int) -> tuple[dict[str, Any], subprocess.CompletedProcess[str]]:
118
+ command = [
119
+ "gh",
120
+ "pr",
121
+ "view",
122
+ str(after_pr),
123
+ "--json",
124
+ "number,state,mergedAt,headRefOid,url,title",
125
+ ]
126
+ completed = _run_command(command)
127
+ if completed.returncode != 0:
128
+ return {}, completed
129
+ try:
130
+ parsed = json.loads(completed.stdout or "{}")
131
+ except json.JSONDecodeError as exc:
132
+ bad = subprocess.CompletedProcess(
133
+ command,
134
+ 2,
135
+ completed.stdout,
136
+ f"Could not parse PR info JSON: {exc}\n",
137
+ )
138
+ return {}, bad
139
+ if not isinstance(parsed, dict):
140
+ bad = subprocess.CompletedProcess(command, 2, completed.stdout, "PR info did not return an object.\n")
141
+ return {}, bad
142
+ return parsed, completed
143
+
144
+
145
+ def _is_worktree_clean() -> tuple[bool, subprocess.CompletedProcess[str]]:
146
+ completed = _run_command(["git", "status", "--porcelain"])
147
+ return completed.returncode == 0 and not completed.stdout.strip(), completed
148
+
149
+
150
+ def pr_closeout_complete(
151
+ after_pr: int,
152
+ *,
153
+ main_branch: str = "main",
154
+ merge_method: str = "squash",
155
+ timeout_seconds: int = 300,
156
+ poll_seconds: int = 10,
157
+ merge_state_timeout_seconds: int = 60,
158
+ merge_state_poll_seconds: int = 5,
159
+ ) -> PrCloseoutCompleteResult:
160
+ """Complete a substantive PR and its post-merge handoff lifecycle.
161
+
162
+ This is the high-level wrapper that LLM-facing command composition should
163
+ prefer over manually chaining PR wait, merge, main sync, post-merge-check,
164
+ post-merge-complete, and repo-status commands.
165
+
166
+ The function is intentionally idempotent:
167
+ - if the PR is already merged, it resumes at post-merge closeout;
168
+ - if the handoff refresh is already complete, post_merge_complete returns NOOP;
169
+ - if a refresh PR already exists, the lower lifecycle handles the recovery path.
170
+ """
171
+
172
+ steps: list[PrCloseoutStep] = []
173
+
174
+ clean, status = _is_worktree_clean()
175
+ steps.append(_completed_step("local-clean-preflight", status, "Clean the worktree before PR closeout."))
176
+ if not clean:
177
+ return _finish(
178
+ after_pr=after_pr,
179
+ result_status="BLOCKED",
180
+ returncode=2,
181
+ lifecycle_state="DIRTY_WORKTREE",
182
+ next_action="Clean or commit local changes before running pr-closeout-complete.",
183
+ merged_pr=False,
184
+ steps=steps,
185
+ )
186
+
187
+ switch = _run_command(["git", "switch", main_branch])
188
+ steps.append(_completed_step("switch-main", switch, "Switch to main before PR closeout."))
189
+ if switch.returncode != 0:
190
+ return _finish(
191
+ after_pr=after_pr,
192
+ result_status="BLOCKED",
193
+ returncode=2,
194
+ lifecycle_state="MAIN_SWITCH_BLOCKED",
195
+ next_action="Inspect main branch switch failure.",
196
+ merged_pr=False,
197
+ steps=steps,
198
+ )
199
+
200
+ pull = _run_command(["git", "pull", "--ff-only", "origin", main_branch])
201
+ steps.append(_completed_step("sync-main-before-pr-closeout", pull, "Synchronize main before PR closeout."))
202
+ if pull.returncode != 0:
203
+ return _finish(
204
+ after_pr=after_pr,
205
+ result_status="BLOCKED",
206
+ returncode=2,
207
+ lifecycle_state="MAIN_SYNC_BLOCKED",
208
+ next_action="Inspect main pull failure before PR closeout.",
209
+ merged_pr=False,
210
+ steps=steps,
211
+ )
212
+
213
+ pr_info, pr_lookup = _load_pr_info(after_pr)
214
+ steps.append(_completed_step("pr-state-lookup", pr_lookup, "Inspect PR state lookup failure."))
215
+ if pr_lookup.returncode != 0:
216
+ return _finish(
217
+ after_pr=after_pr,
218
+ result_status="BLOCKED",
219
+ returncode=2,
220
+ lifecycle_state="PR_STATE_LOOKUP_BLOCKED",
221
+ next_action="Inspect PR state lookup before continuing.",
222
+ merged_pr=False,
223
+ steps=steps,
224
+ )
225
+
226
+ state = str(pr_info.get("state") or "").upper()
227
+ merged_at = str(pr_info.get("mergedAt") or "")
228
+ merged = state == "MERGED" or bool(merged_at)
229
+ expected_head_sha = str(pr_info.get("headRefOid") or "")
230
+
231
+ if not merged:
232
+ wait_ci = pr_wait_ci(
233
+ after_pr,
234
+ expected_head_sha=expected_head_sha,
235
+ timeout_seconds=timeout_seconds,
236
+ poll_seconds=poll_seconds,
237
+ )
238
+ steps.append(_repo_step("pr-wait-ci", wait_ci))
239
+ if wait_ci.returncode != 0 or wait_ci.result_status != "PASS":
240
+ return _finish(
241
+ after_pr=after_pr,
242
+ result_status="BLOCKED",
243
+ returncode=2,
244
+ lifecycle_state="PR_CI_BLOCKED",
245
+ next_action="Inspect PR CI before merging.",
246
+ merged_pr=False,
247
+ steps=steps,
248
+ )
249
+
250
+ merge = pr_merge_safe(
251
+ after_pr,
252
+ expected_head_sha=expected_head_sha,
253
+ main_branch=main_branch,
254
+ merge_method=merge_method,
255
+ merge_state_timeout_seconds=merge_state_timeout_seconds,
256
+ merge_state_poll_seconds=merge_state_poll_seconds,
257
+ )
258
+ steps.append(_repo_step("pr-merge-safe", merge))
259
+ if merge.returncode != 0 or merge.result_status != "PASS":
260
+ return _finish(
261
+ after_pr=after_pr,
262
+ result_status="BLOCKED",
263
+ returncode=2,
264
+ lifecycle_state="PR_MERGE_BLOCKED",
265
+ next_action="Inspect guarded PR merge before post-merge closeout.",
266
+ merged_pr=False,
267
+ steps=steps,
268
+ )
269
+ merged = True
270
+
271
+ sync_after_merge = _run_command(["git", "switch", main_branch])
272
+ steps.append(_completed_step("switch-main-after-pr-merge", sync_after_merge, "Switch to main after PR merge."))
273
+ if sync_after_merge.returncode != 0:
274
+ return _finish(
275
+ after_pr=after_pr,
276
+ result_status="BLOCKED",
277
+ returncode=2,
278
+ lifecycle_state="MAIN_SWITCH_AFTER_MERGE_BLOCKED",
279
+ next_action="Inspect main switch after merge.",
280
+ merged_pr=merged,
281
+ steps=steps,
282
+ )
283
+
284
+ pull_after_merge = _run_command(["git", "pull", "--ff-only", "origin", main_branch])
285
+ steps.append(_completed_step("sync-main-after-pr-merge", pull_after_merge, "Synchronize main after PR merge."))
286
+ if pull_after_merge.returncode != 0:
287
+ return _finish(
288
+ after_pr=after_pr,
289
+ result_status="BLOCKED",
290
+ returncode=2,
291
+ lifecycle_state="MAIN_SYNC_AFTER_MERGE_BLOCKED",
292
+ next_action="Inspect main pull after PR merge.",
293
+ merged_pr=merged,
294
+ steps=steps,
295
+ )
296
+
297
+ closeout = post_merge_complete(
298
+ after_pr,
299
+ main_branch=main_branch,
300
+ merge_method=merge_method,
301
+ ci_timeout_seconds=timeout_seconds,
302
+ ci_poll_seconds=poll_seconds,
303
+ merge_state_timeout_seconds=merge_state_timeout_seconds,
304
+ merge_state_poll_seconds=merge_state_poll_seconds,
305
+ )
306
+ steps.append(_lifecycle_step("post-merge-complete", closeout))
307
+
308
+ refresh_pr = getattr(closeout, "refresh_pr", None)
309
+ if int(getattr(closeout, "returncode", 2)) != 0 or str(getattr(closeout, "result_status", "")) != "PASS":
310
+ return _finish(
311
+ after_pr=after_pr,
312
+ result_status="BLOCKED",
313
+ returncode=2,
314
+ lifecycle_state=str(getattr(closeout, "lifecycle_state", "POST_MERGE_CLOSEOUT_BLOCKED")),
315
+ next_action=str(getattr(closeout, "next_action", "Inspect post-merge closeout result.")),
316
+ merged_pr=merged,
317
+ refresh_pr=refresh_pr,
318
+ steps=steps,
319
+ )
320
+
321
+ final_status = repo_status()
322
+ steps.append(_repo_step("repo-status", final_status))
323
+ if final_status.returncode != 0 or final_status.stdout.strip():
324
+ return _finish(
325
+ after_pr=after_pr,
326
+ result_status="BLOCKED",
327
+ returncode=2,
328
+ lifecycle_state="FINAL_REPO_STATUS_BLOCKED",
329
+ next_action="Inspect final repo status after PR closeout.",
330
+ merged_pr=merged,
331
+ refresh_pr=refresh_pr,
332
+ steps=steps,
333
+ )
334
+
335
+ return _finish(
336
+ after_pr=after_pr,
337
+ result_status="PASS",
338
+ returncode=0,
339
+ lifecycle_state="COMPLETE",
340
+ next_action="PR closeout complete; continue with the next governed slice.",
341
+ merged_pr=merged,
342
+ refresh_pr=refresh_pr,
343
+ steps=steps,
344
+ )
@@ -0,0 +1,71 @@
1
+ from __future__ import annotations
2
+
3
+ import subprocess
4
+ import sys
5
+
6
+ def run(cmd: list[str], *, capture: bool = False) -> subprocess.CompletedProcess[str]:
7
+ return subprocess.run(cmd, text=True, capture_output=capture, check=False)
8
+
9
+ def emit_result(status: int) -> int:
10
+ if status == 0:
11
+ print("\n### RESULT: PASS ###")
12
+ else:
13
+ print("\n### RESULT: FAIL ###")
14
+ return status
15
+
16
+ def main(argv: list[str] | None = None) -> int:
17
+ args = list(sys.argv[1:] if argv is None else argv)
18
+ title = args[0] if len(args) >= 1 else ""
19
+ body = args[1] if len(args) >= 2 else ""
20
+ base = args[2] if len(args) >= 3 else "main"
21
+ print("\n\n\n" + "-" * 80)
22
+ print("-" * 79)
23
+ print("-" * 80)
24
+ print("\n\n\nNS PR CREATE OR SKIP\n")
25
+ if not title:
26
+ print("ERROR: missing title argument.")
27
+ print("Usage: python -m agentic_project_kit.pr_create_or_skip TITLE BODY [BASE]")
28
+ return emit_result(1)
29
+ status = 0
30
+ branch_result = run(["git", "branch", "--show-current"], capture=True)
31
+ if branch_result.returncode != 0:
32
+ status = 1
33
+ branch = branch_result.stdout.strip()
34
+ print("\n### BRANCH / STATUS ###")
35
+ print(f"branch={branch}")
36
+ if run(["git", "status", "--short"]).returncode != 0:
37
+ status = 1
38
+ if branch == base:
39
+ print(f"No PR needed: current branch is base branch {base}.")
40
+ return emit_result(0)
41
+ print("\n### CHECK BRANCH DELTA ###")
42
+ if run(["git", "fetch", "origin", base]).returncode != 0:
43
+ status = 1
44
+ delta_result = run(["git", "rev-list", "--count", f"origin/{base}..HEAD"], capture=True)
45
+ if delta_result.returncode != 0:
46
+ status = 1
47
+ delta = delta_result.stdout.strip() if delta_result.stdout.strip() else "0"
48
+ print(f"commits_ahead_of_{base}={delta}")
49
+ if status == 0 and delta == "0":
50
+ print(f"No PR needed: branch has no commits ahead of origin/{base}.")
51
+ print("This is an idempotent already-completed state, not a failure.")
52
+ return emit_result(0)
53
+ print("\n### EXISTING PR CHECK ###")
54
+ existing = run(["gh", "pr", "view", "--json", "number,title,state,url"])
55
+ if existing.returncode == 0:
56
+ print("Existing PR found for current branch.")
57
+ else:
58
+ print("\n### CREATE PR ###")
59
+ if run(["gh", "pr", "create", "--base", base, "--title", title, "--body", body]).returncode != 0:
60
+ status = 1
61
+ print("\n### PR STATUS ###")
62
+ if run(["gh", "pr", "status"]).returncode != 0:
63
+ status = 1
64
+ print("\n### FINAL STATE ###")
65
+ for cmd in (["git", "branch", "--show-current"], ["git", "log", "--oneline", "-6"], ["git", "status", "--short"]):
66
+ if run(cmd).returncode != 0:
67
+ status = 1
68
+ return emit_result(status)
69
+
70
+ if __name__ == "__main__":
71
+ raise SystemExit(main())