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,175 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path
5
+ import re
6
+ import subprocess
7
+ import time
8
+
9
+
10
+ SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
11
+
12
+
13
+ def usage() -> str:
14
+ return "usage: ./ns release-verify <version>"
15
+
16
+
17
+ def is_help_arg(value: str) -> bool:
18
+ return value in {"-h", "--help"}
19
+
20
+
21
+ def is_valid_semver(value: str) -> bool:
22
+ plain = value[1:] if value.startswith("v") else value
23
+ return bool(SEMVER_RE.fullmatch(plain))
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class CommandResult:
28
+ returncode: int
29
+ output: str
30
+
31
+
32
+ def normalize_version(version: str) -> tuple[str, str]:
33
+ raw = version.strip()
34
+ if not raw:
35
+ raise ValueError("missing version")
36
+ if raw.startswith("v"):
37
+ return raw[1:], raw
38
+ return raw, "v" + raw
39
+
40
+
41
+ def run_command(repo_root: Path, args: list[str]) -> CommandResult:
42
+ completed = subprocess.run(
43
+ args,
44
+ cwd=repo_root,
45
+ text=True,
46
+ stdout=subprocess.PIPE,
47
+ stderr=subprocess.STDOUT,
48
+ check=False,
49
+ )
50
+ return CommandResult(completed.returncode, completed.stdout.strip())
51
+
52
+
53
+ def agentic_kit_command(repo_root: Path) -> list[str]:
54
+ local = repo_root / ".venv" / "bin" / "agentic-kit"
55
+ if local.exists():
56
+ return [str(local)]
57
+ return ["agentic-kit"]
58
+
59
+
60
+ def render_header(tag: str) -> list[str]:
61
+ return [
62
+ "",
63
+ "",
64
+ "",
65
+ "-------------------------------------------------------------------------",
66
+ "-------------------------------------------------------------------------",
67
+ "-------------------------------------------------------------------------",
68
+ "",
69
+ "",
70
+ "",
71
+ f"NS RELEASE VERIFY CYCLE {tag}",
72
+ "",
73
+ "### SAFETY ###",
74
+ "Safety: verifies completed release state only; no tag, release, merge, push, or publish action.",
75
+ ]
76
+
77
+
78
+ def verify_release(version: str, repo_root: Path, release_wait_attempts: int = 24, sleep_seconds: float = 10.0) -> int:
79
+ try:
80
+ plain_version, tag = normalize_version(version)
81
+ except ValueError:
82
+ print("ERROR: usage: ./ns release-verify <version>")
83
+ print("\n### RESULT: FAIL ###")
84
+ return 2
85
+
86
+ status = 0
87
+ lines = render_header(tag)
88
+
89
+ def section(title: str) -> None:
90
+ lines.extend(["", f"### {title} ###"])
91
+
92
+ def append_command(args: list[str], fail_message: str | None = None) -> CommandResult:
93
+ nonlocal status
94
+ result = run_command(repo_root, args)
95
+ if result.output:
96
+ lines.append(result.output)
97
+ if result.returncode != 0:
98
+ if fail_message:
99
+ lines.append(fail_message)
100
+ status = 1
101
+ return result
102
+
103
+ section("BRANCH / STATUS")
104
+ append_command(["git", "branch", "--show-current"])
105
+ append_command(["git", "status", "--short"])
106
+
107
+ section("VERIFY LOCAL TAG")
108
+ local_tag = append_command(["git", "rev-parse", "-q", "--verify", f"refs/tags/{tag}"])
109
+ if local_tag.returncode != 0:
110
+ lines.append(f"ERROR: local tag missing: {tag}")
111
+
112
+ section("VERIFY REMOTE TAG")
113
+ remote_tag = append_command(["git", "ls-remote", "--tags", "origin", tag])
114
+ if remote_tag.returncode != 0 or tag not in remote_tag.output:
115
+ lines.append(f"ERROR: remote tag missing: {tag}")
116
+ status = 1
117
+
118
+ section("WAIT FOR GITHUB RELEASE")
119
+ found = False
120
+ last_release_output = ""
121
+ for attempt in range(release_wait_attempts + 1):
122
+ release = run_command(repo_root, ["gh", "release", "view", tag])
123
+ last_release_output = release.output
124
+ if release.returncode == 0:
125
+ found = True
126
+ if release.output:
127
+ lines.append(release.output)
128
+ break
129
+ if attempt < release_wait_attempts:
130
+ next_count = attempt + 1
131
+ lines.append(f"Release not visible yet for {tag}; retry {next_count}/{release_wait_attempts} after {int(sleep_seconds)}s.")
132
+ if sleep_seconds:
133
+ time.sleep(sleep_seconds)
134
+ if not found:
135
+ lines.append(f"ERROR: GitHub release still missing after wait: {tag}")
136
+ if last_release_output:
137
+ lines.append(last_release_output)
138
+ status = 1
139
+
140
+ section("RELEASE WORKFLOW STATUS")
141
+ append_command(["gh", "run", "list", "--workflow", "Release", "--limit", "8"])
142
+
143
+ section("POST RELEASE CHECK")
144
+ append_command([*agentic_kit_command(repo_root), "post-release-check", "--version", plain_version])
145
+
146
+ section("FINAL STATE")
147
+ append_command(["git", "branch", "--show-current"])
148
+ append_command(["git", "log", "--oneline", "-8"])
149
+ append_command(["git", "status", "--short"])
150
+
151
+ lines.append("\n### RESULT: PASS ###" if status == 0 else "\n### RESULT: FAIL ###")
152
+ print("\n".join(lines))
153
+ return status
154
+
155
+
156
+ def main(argv: list[str] | None = None) -> int:
157
+ args = argv if argv is not None else []
158
+ if not args:
159
+ print("ERROR: usage: ./ns release-verify <version>")
160
+ print("\n### RESULT: FAIL ###")
161
+ return 2
162
+ if is_help_arg(args[0]):
163
+ print(usage())
164
+ return 0
165
+ if not is_valid_semver(args[0]):
166
+ print(f"ERROR: invalid semantic version: {args[0]}")
167
+ print("\n### RESULT: FAIL ###")
168
+ return 2
169
+ return verify_release(args[0], Path(".").resolve())
170
+
171
+
172
+ if __name__ == "__main__":
173
+ import sys
174
+
175
+ raise SystemExit(main(sys.argv[1:]))
@@ -0,0 +1,223 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import asdict, 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 RemoteBranchInfo:
12
+ branch: str
13
+ merged_to_origin_main: bool
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class OpenPullRequestHead:
18
+ head: str
19
+ number: int
20
+ title: str
21
+ url: str
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class RemoteBranchFinding:
26
+ branch: str
27
+ short_name: str
28
+ merged_to_origin_main: bool
29
+ has_open_pr: bool
30
+ open_pr_number: int | None
31
+ proposed_action: str
32
+ safety_class: str
33
+ reason: str
34
+ delete_command: str | None = None
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class RemoteBranchHygieneReport:
39
+ findings: tuple[RemoteBranchFinding, ...]
40
+ summary: dict[str, int]
41
+
42
+
43
+ def _short_name(branch: str) -> str:
44
+ return branch.removeprefix("origin/")
45
+
46
+
47
+ def _is_protected_remote_ref(branch: str) -> bool:
48
+ return branch in {"origin", "origin/HEAD", "origin/main"} or not branch.startswith("origin/")
49
+
50
+
51
+ def analyze_remote_branch_hygiene(
52
+ remote_branches: list[RemoteBranchInfo],
53
+ open_pr_heads: list[OpenPullRequestHead],
54
+ ) -> RemoteBranchHygieneReport:
55
+ open_prs_by_head = {pr.head: pr for pr in open_pr_heads}
56
+ findings: list[RemoteBranchFinding] = []
57
+
58
+ for info in sorted(remote_branches, key=lambda item: item.branch):
59
+ if _is_protected_remote_ref(info.branch):
60
+ continue
61
+
62
+ short = _short_name(info.branch)
63
+ open_pr = open_prs_by_head.get(short)
64
+
65
+ if open_pr is not None:
66
+ finding = RemoteBranchFinding(
67
+ branch=info.branch,
68
+ short_name=short,
69
+ merged_to_origin_main=info.merged_to_origin_main,
70
+ has_open_pr=True,
71
+ open_pr_number=open_pr.number,
72
+ proposed_action="keep",
73
+ safety_class="protected-open-pr",
74
+ reason="has open PR",
75
+ )
76
+ elif info.merged_to_origin_main:
77
+ finding = RemoteBranchFinding(
78
+ branch=info.branch,
79
+ short_name=short,
80
+ merged_to_origin_main=True,
81
+ has_open_pr=False,
82
+ open_pr_number=None,
83
+ proposed_action="candidate-delete-merged-remote-branch",
84
+ safety_class="dry-run-candidate",
85
+ reason="merged into origin/main and no open PR",
86
+ )
87
+ else:
88
+ finding = RemoteBranchFinding(
89
+ branch=info.branch,
90
+ short_name=short,
91
+ merged_to_origin_main=False,
92
+ has_open_pr=False,
93
+ open_pr_number=None,
94
+ proposed_action="manual-review",
95
+ safety_class="manual-review",
96
+ reason="not merged into origin/main",
97
+ )
98
+ findings.append(finding)
99
+
100
+ summary = {
101
+ "remote_branches": len(findings),
102
+ "keep": sum(f.proposed_action == "keep" for f in findings),
103
+ "candidate_delete_merged_remote_branch": sum(
104
+ f.proposed_action == "candidate-delete-merged-remote-branch" for f in findings
105
+ ),
106
+ "manual_review": sum(f.proposed_action == "manual-review" for f in findings),
107
+ }
108
+ return RemoteBranchHygieneReport(findings=tuple(findings), summary=summary)
109
+
110
+
111
+ def report_as_json_data(report: RemoteBranchHygieneReport) -> dict[str, Any]:
112
+ return {
113
+ "schema_version": 1,
114
+ "kind": "k3_remote_branch_hygiene_report",
115
+ "mode": "dry-run",
116
+ "mutation": "none",
117
+ "result_status": "PASS",
118
+ "summary": report.summary,
119
+ "findings": [asdict(finding) for finding in report.findings],
120
+ }
121
+
122
+
123
+ def render_remote_branch_hygiene_report(report: RemoteBranchHygieneReport) -> str:
124
+ lines = [
125
+ "K3_REMOTE_BRANCH_HYGIENE",
126
+ "MODE: dry-run",
127
+ "MUTATION: none",
128
+ "DELETE: disabled",
129
+ "",
130
+ "SUMMARY",
131
+ ]
132
+ for key, value in report.summary.items():
133
+ lines.append(f"- {key}: {value}")
134
+
135
+ lines.extend(["", "FINDINGS"])
136
+ if not report.findings:
137
+ lines.append("- none")
138
+ for finding in report.findings:
139
+ pr = f" open_pr=#{finding.open_pr_number}" if finding.open_pr_number else ""
140
+ lines.append(
141
+ f"- {finding.branch}: action={finding.proposed_action} "
142
+ f"safety={finding.safety_class}{pr} reason={finding.reason}"
143
+ )
144
+ return "\n".join(lines) + "\n"
145
+
146
+
147
+ def _run(repo_root: Path, args: list[str]) -> str:
148
+ completed = subprocess.run(
149
+ args,
150
+ cwd=repo_root,
151
+ check=False,
152
+ text=True,
153
+ stdout=subprocess.PIPE,
154
+ stderr=subprocess.STDOUT,
155
+ )
156
+ if completed.returncode != 0:
157
+ raise RuntimeError(completed.stdout.strip() or f"command failed: {' '.join(args)}")
158
+ return completed.stdout
159
+
160
+
161
+ def _lines(repo_root: Path, args: list[str]) -> list[str]:
162
+ return [line.strip() for line in _run(repo_root, args).splitlines() if line.strip()]
163
+
164
+
165
+
166
+ def delete_remote_branch(repo_root: Path, branch: str) -> None:
167
+ short_name = _short_name(branch)
168
+ if _is_protected_remote_ref(branch) or short_name == branch or "," in branch:
169
+ raise ValueError(f"unsafe remote branch name: {branch}")
170
+ _run(repo_root, ["git", "push", "origin", "--delete", short_name])
171
+
172
+ def collect_remote_branch_hygiene_inputs(repo_root: Path) -> tuple[list[RemoteBranchInfo], list[OpenPullRequestHead]]:
173
+ remote_refs = _lines(repo_root, ["git", "for-each-ref", "--format=%(refname:short)", "refs/remotes/origin"])
174
+ merged_refs = set(
175
+ _lines(repo_root, ["git", "branch", "-r", "--merged", "origin/main", "--format=%(refname:short)"])
176
+ )
177
+ remote_branches = [
178
+ RemoteBranchInfo(branch=ref, merged_to_origin_main=ref in merged_refs)
179
+ for ref in remote_refs
180
+ if not _is_protected_remote_ref(ref)
181
+ ]
182
+
183
+ raw_prs = _run(
184
+ repo_root,
185
+ [
186
+ "gh",
187
+ "pr",
188
+ "list",
189
+ "--state",
190
+ "open",
191
+ "--limit",
192
+ "300",
193
+ "--json",
194
+ "number,headRefName,title,url",
195
+ ],
196
+ )
197
+ prs = []
198
+ for item in json.loads(raw_prs or "[]"):
199
+ prs.append(
200
+ OpenPullRequestHead(
201
+ head=str(item.get("headRefName") or ""),
202
+ number=int(item.get("number") or 0),
203
+ title=str(item.get("title") or ""),
204
+ url=str(item.get("url") or ""),
205
+ )
206
+ )
207
+ return remote_branches, prs
208
+
209
+ def build_remote_branch_hygiene_evidence_report_payload(report: RemoteBranchHygieneReport) -> dict[str, Any]:
210
+ return {
211
+ "schema_version": 1,
212
+ "kind": "k3_remote_branch_hygiene_evidence_report",
213
+ "mode": "dry-run",
214
+ "mutation": "none",
215
+ "result_status": "PASS",
216
+ "inventory": report_as_json_data(report),
217
+ }
218
+
219
+
220
+ def write_remote_branch_hygiene_evidence_report(path: Path, report: RemoteBranchHygieneReport) -> None:
221
+ payload = build_remote_branch_hygiene_evidence_report_payload(report)
222
+ path.parent.mkdir(parents=True, exist_ok=True)
223
+ path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
@@ -0,0 +1,89 @@
1
+ from __future__ import annotations
2
+
3
+ import dataclasses
4
+ import subprocess
5
+ from pathlib import Path
6
+
7
+ from agentic_project_kit.typed_work_order_queue import (
8
+ TypedNextResult,
9
+ run_typed_next,
10
+ typed_next_result_as_json_data,
11
+ )
12
+
13
+ STATUS_SYNC_FAIL = "sync_fail"
14
+
15
+
16
+ @dataclasses.dataclass(frozen=True)
17
+ class RemoteNextResult:
18
+ sync_status: str
19
+ returncode: int
20
+ message: str
21
+ typed_next: TypedNextResult | None = None
22
+
23
+
24
+ def _run_git(project_root: Path, argv: list[str]) -> subprocess.CompletedProcess[str]:
25
+ return subprocess.run(
26
+ argv,
27
+ cwd=project_root,
28
+ text=True,
29
+ stdout=subprocess.PIPE,
30
+ stderr=subprocess.PIPE,
31
+ check=False,
32
+ )
33
+
34
+
35
+ def _sync_main(project_root: Path) -> tuple[bool, str]:
36
+ fetch = _run_git(project_root, ["git", "fetch", "origin", "main"])
37
+ if fetch.returncode != 0:
38
+ return False, (fetch.stderr or fetch.stdout or "git fetch origin main failed").strip()
39
+ branch = _run_git(project_root, ["git", "branch", "--show-current"])
40
+ if branch.returncode != 0:
41
+ return False, (branch.stderr or branch.stdout or "git branch --show-current failed").strip()
42
+ if branch.stdout.strip() != "main":
43
+ switch = _run_git(project_root, ["git", "switch", "main"])
44
+ if switch.returncode != 0:
45
+ return False, (switch.stderr or switch.stdout or "git switch main failed").strip()
46
+ pull = _run_git(project_root, ["git", "pull", "--ff-only", "origin", "main"])
47
+ if pull.returncode != 0:
48
+ return False, (pull.stderr or pull.stdout or "git pull --ff-only origin main failed").strip()
49
+ return True, "main synced"
50
+
51
+
52
+ def run_remote_next(project_root: Path = Path(".")) -> RemoteNextResult:
53
+ root = project_root.resolve()
54
+ ok, message = _sync_main(root)
55
+ if not ok:
56
+ return RemoteNextResult(STATUS_SYNC_FAIL, 2, message)
57
+ typed_result = run_typed_next(root)
58
+ return RemoteNextResult("synced", typed_result.returncode, typed_result.message, typed_result)
59
+
60
+
61
+ def remote_next_result_as_json_data(result: RemoteNextResult) -> dict[str, object]:
62
+ return {
63
+ "schema_version": 1,
64
+ "sync_status": result.sync_status,
65
+ "returncode": result.returncode,
66
+ "message": result.message,
67
+ "typed_next": typed_next_result_as_json_data(result.typed_next) if result.typed_next else None,
68
+ }
69
+
70
+
71
+ def render_remote_next_result(result: RemoteNextResult) -> str:
72
+ lines = [
73
+ "REMOTE_NEXT_RESULT",
74
+ f"sync_status={result.sync_status}",
75
+ f"returncode={result.returncode}",
76
+ f"message={result.message}",
77
+ ]
78
+ if result.typed_next is not None:
79
+ lines.extend(
80
+ [
81
+ f"typed_queue_status={result.typed_next.queue_status}",
82
+ f"typed_result_status={result.typed_next.result_status}",
83
+ ]
84
+ )
85
+ if result.typed_next.terminal_log:
86
+ lines.append(f"terminal_log={result.typed_next.terminal_log}")
87
+ for path in result.typed_next.expected_closeout_paths:
88
+ lines.append(f"expected_closeout_path={path}")
89
+ return "\n".join(lines)
@@ -0,0 +1,101 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path
5
+ import re
6
+ import subprocess
7
+
8
+ from agentic_project_kit.evidence_commit_paths import commit_paths
9
+
10
+
11
+ @dataclass(frozen=True)
12
+ class RemoteNextCloseoutResult:
13
+ success: bool
14
+ status: str
15
+ branch: str
16
+ closeout_branch: str
17
+ commit_sha: str
18
+ paths: tuple[str, ...]
19
+ findings: tuple[str, ...]
20
+
21
+
22
+ def _run_git(root: Path, args: list[str]) -> subprocess.CompletedProcess[str]:
23
+ return subprocess.run(["git", *args], cwd=root, text=True, capture_output=True, check=False)
24
+
25
+
26
+ def _status_lines(root: Path) -> tuple[str, ...]:
27
+ result = _run_git(root, ["status", "--short", "--untracked-files=all"])
28
+ if result.returncode != 0:
29
+ return ()
30
+ return tuple(line for line in result.stdout.splitlines() if line.strip())
31
+
32
+
33
+ def _path_from_status(line: str) -> str:
34
+ if " -> " in line:
35
+ return line.split(" -> ", 1)[1]
36
+ return line[3:]
37
+
38
+
39
+ def _is_allowed_closeout_path(path: str) -> bool:
40
+ if path == ".agentic/handoff_state.yaml":
41
+ return True
42
+ if re.fullmatch(r"\.agentic/typed_work_orders/(inbox|executed)/[A-Za-z0-9_.-]+\.ya?ml", path):
43
+ return True
44
+ if re.fullmatch(r"docs/reports/terminal/[A-Za-z0-9_.-]+\.log", path):
45
+ return True
46
+ return False
47
+
48
+
49
+ def _derive_closeout_branch(paths: tuple[str, ...]) -> str:
50
+ for path in paths:
51
+ if path.startswith("docs/reports/terminal/") and path.endswith(".log"):
52
+ stem = Path(path).stem
53
+ safe = re.sub(r"[^A-Za-z0-9_.-]+", "-", stem).strip("-")
54
+ if safe:
55
+ return f"docs/{safe}-evidence"
56
+ return "docs/remote-next-closeout-evidence"
57
+
58
+
59
+ def run_remote_next_closeout(project_root: Path = Path("."), *, push: bool = True) -> RemoteNextCloseoutResult:
60
+ root = project_root.resolve()
61
+ branch_result = _run_git(root, ["branch", "--show-current"])
62
+ branch = branch_result.stdout.strip() if branch_result.returncode == 0 else "UNKNOWN"
63
+ if branch != "main":
64
+ return RemoteNextCloseoutResult(False, "fail", branch, "", "", (), (f"expected main branch, got {branch}",))
65
+
66
+ status = _status_lines(root)
67
+ if not status:
68
+ return RemoteNextCloseoutResult(False, "no_closeout", branch, "", "", (), ("no closeout paths are dirty",))
69
+
70
+ paths = tuple(dict.fromkeys(_path_from_status(line) for line in status))
71
+ unexpected = tuple(path for path in paths if not _is_allowed_closeout_path(path))
72
+ if unexpected:
73
+ return RemoteNextCloseoutResult(False, "fail", branch, "", "", paths, tuple(f"unexpected dirty path: {path}" for path in unexpected))
74
+
75
+ closeout_branch = _derive_closeout_branch(paths)
76
+ switch = _run_git(root, ["switch", "-c", closeout_branch])
77
+ if switch.returncode != 0:
78
+ return RemoteNextCloseoutResult(False, "fail", branch, closeout_branch, "", paths, ((switch.stderr or switch.stdout or "git switch failed").strip(),))
79
+
80
+ result = commit_paths(root=root, paths=paths, message=f"Record {closeout_branch.removeprefix('docs/')} evidence", push=push)
81
+ if not result.success:
82
+ return RemoteNextCloseoutResult(False, "fail", branch, closeout_branch, result.commit_sha, paths, result.findings)
83
+ return RemoteNextCloseoutResult(True, "pass", branch, closeout_branch, result.commit_sha, paths, ())
84
+
85
+
86
+ def render_remote_next_closeout_result(result: RemoteNextCloseoutResult) -> str:
87
+ lines = [
88
+ "REMOTE_NEXT_CLOSEOUT_RESULT",
89
+ f"success={'yes' if result.success else 'no'}",
90
+ f"result_status={result.status}",
91
+ f"source_branch={result.branch}",
92
+ f"closeout_branch={result.closeout_branch or 'NONE'}",
93
+ f"commit_sha={result.commit_sha or 'NONE'}",
94
+ ]
95
+ for path in result.paths:
96
+ lines.append(f"path={path}")
97
+ for finding in result.findings:
98
+ lines.append(f"finding={finding}")
99
+ result_label = "PASS" if result.success else "NO-CLOSEOUT" if result.status == "no_closeout" else "FAIL"
100
+ lines.append(f"### RESULT: {result_label} ###")
101
+ return "\n".join(lines)