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,210 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ import json
5
+ import re
6
+ import subprocess
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+
11
+ @dataclass(frozen=True)
12
+ class PullRequestInfo:
13
+ number: int
14
+ title: str
15
+ head_ref: str
16
+ base_ref: str = "main"
17
+ url: str | None = None
18
+ commits_ahead: int | None = None
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class BranchInfo:
23
+ name: str
24
+ gone: bool = False
25
+ merged: bool = False
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class HygieneFinding:
30
+ code: str
31
+ severity: str
32
+ summary: str
33
+ details: tuple[str, ...]
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class HygieneReport:
38
+ findings: tuple[HygieneFinding, ...]
39
+ open_pr_count: int
40
+ local_branch_count: int
41
+
42
+ @property
43
+ def ok(self) -> bool:
44
+ return not self.findings
45
+
46
+
47
+ def normalize_slice_prefix(value: str) -> str:
48
+ text = value.strip().lower()
49
+ text = re.sub(r"^(feature|fix|docs|release|chore|temp)/", "", text)
50
+ text = re.sub(r"^#+\\d+[-_ ]*", "", text)
51
+ text = re.sub(r"\\([^)]*\\)", "", text)
52
+ text = re.sub(r"[^a-z0-9]+", "-", text).strip("-")
53
+ parts = [part for part in text.split("-") if part]
54
+ return "-".join(parts[:3]) if parts else "unknown"
55
+
56
+
57
+
58
+ def similar_pr_group_key(pr: PullRequestInfo) -> str:
59
+ if pr.head_ref.startswith("dependabot/"):
60
+ parts = pr.head_ref.split("/")
61
+ if len(parts) >= 4:
62
+ dependency = "/".join(parts[2:])
63
+ dependency = re.sub(r"-[0-9][a-zA-Z0-9._-]*$", "", dependency)
64
+ return f"dependabot:{parts[1]}:{dependency}"
65
+ return f"dependabot:{pr.head_ref}"
66
+ return normalize_slice_prefix(pr.head_ref or pr.title)
67
+
68
+
69
+ def analyze_pr_hygiene(open_prs: list[PullRequestInfo], local_branches: list[BranchInfo]) -> HygieneReport:
70
+ findings: list[HygieneFinding] = []
71
+ by_prefix: dict[str, list[PullRequestInfo]] = {}
72
+ for pr in open_prs:
73
+ prefix = similar_pr_group_key(pr)
74
+ by_prefix.setdefault(prefix, []).append(pr)
75
+ if pr.commits_ahead == 0:
76
+ findings.append(HygieneFinding(
77
+ "open-pr-without-main-delta",
78
+ "warning",
79
+ f"Open PR #{pr.number} has no commits ahead of {pr.base_ref}.",
80
+ (f"title={pr.title}", f"head_ref={pr.head_ref}"),
81
+ ))
82
+ for prefix, prs in sorted(by_prefix.items()):
83
+ if prefix != "unknown" and len(prs) > 1:
84
+ details = tuple(f"#{pr.number} {pr.head_ref}: {pr.title}" for pr in prs)
85
+ findings.append(HygieneFinding(
86
+ "similar-open-prs",
87
+ "warning",
88
+ f"{len(prs)} open PRs share slice prefix {prefix}.",
89
+ details,
90
+ ))
91
+ gone = [branch for branch in local_branches if branch.gone]
92
+ if gone:
93
+ findings.append(HygieneFinding(
94
+ "local-branch-gone-upstream",
95
+ "info",
96
+ f"{len(gone)} local branches track deleted upstream branches.",
97
+ tuple(branch.name for branch in gone),
98
+ ))
99
+ merged_prefixes = {normalize_slice_prefix(branch.name) for branch in local_branches if branch.merged}
100
+ for pr in open_prs:
101
+ prefix = normalize_slice_prefix(pr.head_ref)
102
+ if prefix in merged_prefixes and pr.commits_ahead == 0:
103
+ findings.append(HygieneFinding(
104
+ "stale-sibling-after-merged-branch",
105
+ "warning",
106
+ f"Open PR #{pr.number} looks stale because a sibling branch with prefix {prefix} is already merged.",
107
+ (f"title={pr.title}", f"head_ref={pr.head_ref}"),
108
+ ))
109
+ return HygieneReport(tuple(findings), len(open_prs), len(local_branches))
110
+
111
+
112
+ def report_as_json_data(report: HygieneReport) -> dict[str, Any]:
113
+ return {
114
+ "schema_version": 1,
115
+ "ok": report.ok,
116
+ "open_pr_count": report.open_pr_count,
117
+ "local_branch_count": report.local_branch_count,
118
+ "findings": [
119
+ {
120
+ "code": finding.code,
121
+ "severity": finding.severity,
122
+ "summary": finding.summary,
123
+ "details": list(finding.details),
124
+ }
125
+ for finding in report.findings
126
+ ],
127
+ }
128
+
129
+
130
+ def render_pr_hygiene_report(report: HygieneReport) -> str:
131
+ lines = [
132
+ "PR hygiene report",
133
+ "Safety: read-only diagnosis; no branches, PRs, tags, releases, or files are changed.",
134
+ f"open_pr_count={report.open_pr_count}",
135
+ f"local_branch_count={report.local_branch_count}",
136
+ f"ok={str(report.ok).lower()}",
137
+ ]
138
+ if not report.findings:
139
+ lines.extend(["", "Findings:", "- none"])
140
+ return "\n".join(lines)
141
+ lines.extend(["", "Findings:"])
142
+ for finding in report.findings:
143
+ lines.append(f"- [{finding.severity}] {finding.code}: {finding.summary}")
144
+ for detail in finding.details:
145
+ lines.append(f" - {detail}")
146
+ lines.extend(["", "Next:", "- Review findings manually before closing PRs or deleting branches."])
147
+ return "\n".join(lines)
148
+
149
+
150
+ def collect_pr_hygiene_inputs(project_root: Path) -> tuple[list[PullRequestInfo], list[BranchInfo]]:
151
+ root = project_root.resolve()
152
+ open_prs = _collect_open_prs(root)
153
+ branches = _collect_local_branches(root)
154
+ prs_with_delta = [_with_commits_ahead(root, pr) for pr in open_prs]
155
+ return prs_with_delta, branches
156
+
157
+
158
+ def _collect_open_prs(root: Path) -> list[PullRequestInfo]:
159
+ completed = subprocess.run([
160
+ "gh", "pr", "list", "--state", "open", "--json", "number,title,headRefName,baseRefName,url"
161
+ ], cwd=root, text=True, capture_output=True, check=False)
162
+ if completed.returncode != 0 or not completed.stdout.strip():
163
+ return []
164
+ data = json.loads(completed.stdout)
165
+ return [
166
+ PullRequestInfo(
167
+ number=int(item["number"]),
168
+ title=str(item.get("title", "")),
169
+ head_ref=str(item.get("headRefName", "")),
170
+ base_ref=str(item.get("baseRefName", "main") or "main"),
171
+ url=item.get("url"),
172
+ )
173
+ for item in data
174
+ ]
175
+
176
+
177
+ def _collect_local_branches(root: Path) -> list[BranchInfo]:
178
+ completed = subprocess.run([
179
+ "git", "branch", "--format", "%(refname:short)|%(upstream:track)|%(if)%(HEAD)%(then)current%(end)"
180
+ ], cwd=root, text=True, capture_output=True, check=False)
181
+ if completed.returncode != 0:
182
+ return []
183
+ merged = _merged_branches(root)
184
+ branches = []
185
+ for line in completed.stdout.splitlines():
186
+ name, track, *_rest = (line.split("|") + ["", ""])[:3]
187
+ if not name:
188
+ continue
189
+ branches.append(BranchInfo(name=name, gone="[gone]" in track, merged=name in merged))
190
+ return branches
191
+
192
+
193
+ def _merged_branches(root: Path) -> set[str]:
194
+ completed = subprocess.run(["git", "branch", "--merged"], cwd=root, text=True, capture_output=True, check=False)
195
+ if completed.returncode != 0:
196
+ return set()
197
+ return {line.replace("*", "").strip() for line in completed.stdout.splitlines() if line.strip()}
198
+
199
+
200
+ def _with_commits_ahead(root: Path, pr: PullRequestInfo) -> PullRequestInfo:
201
+ completed = subprocess.run([
202
+ "git", "rev-list", "--count", f"{pr.base_ref}..{pr.head_ref}"
203
+ ], cwd=root, text=True, capture_output=True, check=False)
204
+ if completed.returncode != 0:
205
+ return pr
206
+ try:
207
+ count = int(completed.stdout.strip())
208
+ except ValueError:
209
+ return pr
210
+ return PullRequestInfo(pr.number, pr.title, pr.head_ref, pr.base_ref, pr.url, count)
@@ -0,0 +1,251 @@
1
+ from __future__ import annotations
2
+
3
+ from collections import Counter
4
+ from dataclasses import asdict, dataclass
5
+ from pathlib import Path
6
+ import ast
7
+ import re
8
+
9
+
10
+ SOURCE_ROOTS = (
11
+ "src/agentic_project_kit",
12
+ "tools",
13
+ )
14
+
15
+ SKIP_DIR_PARTS = {
16
+ ".git",
17
+ ".venv",
18
+ "__pycache__",
19
+ ".pytest_cache",
20
+ ".ruff_cache",
21
+ ".mypy_cache",
22
+ "tmp",
23
+ "dist",
24
+ "build",
25
+ }
26
+
27
+ TEXT_SUFFIXES = {".py"}
28
+
29
+ AUDIT_IMPLEMENTATION_PATHS = {
30
+ "src/agentic_project_kit/program_redundancy_audit.py",
31
+ "src/agentic_project_kit/work_order_validator.py",
32
+ }
33
+
34
+ ALLOWED_REPEATED_FUNCTION_NAMES = {
35
+ # Small standalone scripts intentionally keep these local helpers instead of
36
+ # coupling old workflow tools to a shared runtime module.
37
+ "current_branch",
38
+ "run",
39
+ }
40
+
41
+
42
+ RISK_PATTERNS = (
43
+ ("shell_true", re.compile(r"\bshell\s*=\s*True\b"), "subprocess shell=True should be justified or avoided"),
44
+ ("os_system", re.compile(r"\bos\.system\s*\("), "os.system should be replaced by subprocess/wrapper logic"),
45
+ ("eval_exec", re.compile(r"\b(eval|exec)\s*\("), "eval/exec requires strong justification"),
46
+ ("bare_except", re.compile(r"^\s*except\s*:\s*$"), "bare except hides failures"),
47
+ ("broad_except_exception", re.compile(r"^\s*except\s+Exception\b"), "broad Exception handler should preserve evidence"),
48
+ ("pass_in_exception", re.compile(r"^\s*pass\s*(#.*)?$"), "pass directly inside exception handling may hide failure"),
49
+ ("todo_fixme", re.compile(r"\b(TODO|FIXME|XXX)\b"), "TODO/FIXME marker in production source needs triage"),
50
+ )
51
+
52
+
53
+ @dataclass(frozen=True)
54
+ class ProgramFinding:
55
+ path: str
56
+ line: int
57
+ kind: str
58
+ severity: str
59
+ text: str
60
+ reason: str
61
+
62
+ def as_dict(self) -> dict[str, object]:
63
+ return asdict(self)
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class ProgramRedundancyAuditResult:
68
+ root: str
69
+ findings: tuple[ProgramFinding, ...]
70
+ blockers: tuple[ProgramFinding, ...]
71
+
72
+ @property
73
+ def ok(self) -> bool:
74
+ return not self.blockers
75
+
76
+ @property
77
+ def status(self) -> str:
78
+ return "PASS" if self.ok else "FAIL"
79
+
80
+ @property
81
+ def returncode(self) -> int:
82
+ return 0 if self.ok else 1
83
+
84
+ def as_dict(self) -> dict[str, object]:
85
+ return {
86
+ "schema_version": 1,
87
+ "kind": "program_redundancy_audit",
88
+ "root": self.root,
89
+ "status": self.status,
90
+ "finding_count": len(self.findings),
91
+ "blocker_count": len(self.blockers),
92
+ "findings": [item.as_dict() for item in self.findings],
93
+ "blockers": [item.as_dict() for item in self.blockers],
94
+ }
95
+
96
+
97
+ def _iter_source_files(root: Path) -> list[Path]:
98
+ files: list[Path] = []
99
+ for source_root in SOURCE_ROOTS:
100
+ base = root / source_root
101
+ if not base.exists():
102
+ continue
103
+ for path in base.rglob("*.py"):
104
+ if not path.is_file():
105
+ continue
106
+ parts = path.relative_to(root).parts
107
+ if any(part in SKIP_DIR_PARTS for part in parts):
108
+ continue
109
+ if path.suffix not in TEXT_SUFFIXES:
110
+ continue
111
+ files.append(path)
112
+ return sorted(files)
113
+
114
+
115
+ def _line_findings(root: Path, path: Path) -> list[ProgramFinding]:
116
+ relative = path.relative_to(root).as_posix()
117
+ lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
118
+ findings: list[ProgramFinding] = []
119
+
120
+ for index, line in enumerate(lines, start=1):
121
+ for kind, pattern, reason in RISK_PATTERNS:
122
+ if pattern.search(line):
123
+ severity = "review"
124
+ if relative in AUDIT_IMPLEMENTATION_PATHS:
125
+ severity = "review"
126
+ reason = "risk token appears in an audit/validator implementation pattern"
127
+ elif kind in {"shell_true", "os_system", "eval_exec", "bare_except"}:
128
+ severity = "blocker"
129
+ elif kind == "pass_in_exception":
130
+ window = "\n".join(lines[max(0, index - 4):index])
131
+ if "except" in window:
132
+ severity = "blocker"
133
+ else:
134
+ continue
135
+ elif kind == "broad_except_exception":
136
+ severity = "review"
137
+ findings.append(
138
+ ProgramFinding(
139
+ path=relative,
140
+ line=index,
141
+ kind=kind,
142
+ severity=severity,
143
+ text=line.strip(),
144
+ reason=reason,
145
+ )
146
+ )
147
+ return findings
148
+
149
+
150
+ def _duplicate_function_findings(root: Path, files: list[Path]) -> list[ProgramFinding]:
151
+ names: list[tuple[str, str, int]] = []
152
+ for path in files:
153
+ relative = path.relative_to(root).as_posix()
154
+ try:
155
+ tree = ast.parse(path.read_text(encoding="utf-8"), filename=relative)
156
+ except SyntaxError:
157
+ continue
158
+ for node in ast.walk(tree):
159
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
160
+ names.append((node.name, relative, node.lineno))
161
+
162
+ counts = Counter(name for name, _, _ in names)
163
+ findings: list[ProgramFinding] = []
164
+ for name, relative, line in names:
165
+ if counts[name] < 4:
166
+ continue
167
+ if name.startswith("_") or name in {"main", "as_dict", "returncode", "status"}:
168
+ continue
169
+ if name in ALLOWED_REPEATED_FUNCTION_NAMES:
170
+ continue
171
+ findings.append(
172
+ ProgramFinding(
173
+ path=relative,
174
+ line=line,
175
+ kind="repeated_function_name",
176
+ severity="review",
177
+ text=name,
178
+ reason=f"function name appears {counts[name]} times across source; check for duplicated logic",
179
+ )
180
+ )
181
+ return findings
182
+
183
+
184
+ def _duplicate_command_findings(root: Path, files: list[Path]) -> list[ProgramFinding]:
185
+ command_pattern = re.compile(r'(?:(\w+)\.)?command\(["\']([^"\']+)["\']\)')
186
+ occurrences: list[tuple[str, str, str, int, str]] = []
187
+ for path in files:
188
+ relative = path.relative_to(root).as_posix()
189
+ for index, line in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), start=1):
190
+ match = command_pattern.search(line)
191
+ if match:
192
+ app_name = match.group(1) or "app"
193
+ command_name = match.group(2)
194
+ occurrences.append((app_name, command_name, relative, index, line.strip()))
195
+
196
+ counts = Counter((app_name, command_name, relative) for app_name, command_name, relative, _, _ in occurrences)
197
+ findings: list[ProgramFinding] = []
198
+ for app_name, command_name, relative, line, text in occurrences:
199
+ count = counts[(app_name, command_name, relative)]
200
+ if count <= 1:
201
+ continue
202
+ findings.append(
203
+ ProgramFinding(
204
+ path=relative,
205
+ line=line,
206
+ kind="duplicate_cli_command_name",
207
+ severity="blocker",
208
+ text=text,
209
+ reason=(
210
+ f"CLI command name {command_name!r} is registered {count} times "
211
+ f"on {app_name!r} in {relative}"
212
+ ),
213
+ )
214
+ )
215
+ return findings
216
+
217
+
218
+ def audit_program_redundancy(root: Path = Path(".")) -> ProgramRedundancyAuditResult:
219
+ root = root.resolve()
220
+ files = _iter_source_files(root)
221
+
222
+ findings: list[ProgramFinding] = []
223
+ for path in files:
224
+ findings.extend(_line_findings(root, path))
225
+ findings.extend(_duplicate_function_findings(root, files))
226
+ findings.extend(_duplicate_command_findings(root, files))
227
+
228
+ blockers = tuple(item for item in findings if item.severity == "blocker")
229
+ return ProgramRedundancyAuditResult(
230
+ root=root.as_posix(),
231
+ findings=tuple(findings),
232
+ blockers=blockers,
233
+ )
234
+
235
+
236
+ def render_program_redundancy_audit(result: ProgramRedundancyAuditResult) -> str:
237
+ lines = [
238
+ "PROGRAM_REDUNDANCY_AUDIT",
239
+ f"STATUS={result.status}",
240
+ f"FINDING_COUNT={len(result.findings)}",
241
+ f"BLOCKER_COUNT={len(result.blockers)}",
242
+ ]
243
+ for item in result.blockers:
244
+ lines.append(
245
+ f"BLOCKER={item.kind}|{item.path}:{item.line}|{item.text}|{item.reason}"
246
+ )
247
+ for item in result.findings:
248
+ lines.append(
249
+ f"FINDING={item.severity}|{item.kind}|{item.path}:{item.line}|{item.text}|{item.reason}"
250
+ )
251
+ return "\n".join(lines) + "\n"