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,124 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from typing import Any, Iterable
5
+
6
+ import yaml
7
+
8
+ DEFAULT_OPERATIONAL_HANDOFF_STATE = Path(".agentic/operational_handoff_state.yaml")
9
+
10
+ GENERATED_BLOCK_BEGIN = "<!-- agentic:generated operational-handoff-state begin -->"
11
+ GENERATED_BLOCK_END = "<!-- agentic:generated operational-handoff-state end -->"
12
+
13
+
14
+ def load_operational_handoff_state(
15
+ root: Path | str = ".",
16
+ *,
17
+ path: Path | str = DEFAULT_OPERATIONAL_HANDOFF_STATE,
18
+ ) -> dict[str, Any]:
19
+ state_path = Path(root) / path
20
+ data = yaml.safe_load(state_path.read_text(encoding="utf-8"))
21
+ if not isinstance(data, dict):
22
+ raise ValueError("operational handoff state must be a YAML mapping")
23
+ if data.get("schema_version") != 1:
24
+ raise ValueError("operational handoff state schema_version must be 1")
25
+ return data
26
+
27
+
28
+ def _commit_line(label: str, section: dict[str, Any]) -> str:
29
+ full = str(section.get("full", "")).strip()
30
+ short = str(section.get("short", "")).strip() or full[:8]
31
+ subject = str(section.get("subject", "")).strip()
32
+ if not full or not subject:
33
+ raise ValueError(f"{label} requires full commit and subject")
34
+ return f"{label} is `{full}` (`{short}`), after `{subject}`."
35
+
36
+
37
+ def replace_generated_operational_handoff_block(
38
+ document_text: str,
39
+ replacement_lines: Iterable[str],
40
+ ) -> str:
41
+ lines = document_text.splitlines()
42
+ begin_indices = [index for index, line in enumerate(lines) if line.strip() == GENERATED_BLOCK_BEGIN]
43
+ end_indices = [index for index, line in enumerate(lines) if line.strip() == GENERATED_BLOCK_END]
44
+
45
+ if len(begin_indices) != 1 or len(end_indices) != 1:
46
+ raise ValueError("document must contain exactly one generated operational handoff block")
47
+ begin = begin_indices[0]
48
+ end = end_indices[0]
49
+ if begin >= end:
50
+ raise ValueError("generated operational handoff block markers are out of order")
51
+
52
+ replacement = list(replacement_lines)
53
+ if not replacement or replacement[0] != GENERATED_BLOCK_BEGIN or GENERATED_BLOCK_END not in replacement:
54
+ raise ValueError("replacement must include generated operational handoff block markers")
55
+ replacement_end = replacement.index(GENERATED_BLOCK_END)
56
+ if replacement_end == 0:
57
+ raise ValueError("replacement generated operational handoff block is empty")
58
+
59
+ new_lines = lines[:begin] + replacement[: replacement_end + 1] + lines[end + 1 :]
60
+ trailing_newline = "\n" if document_text.endswith("\n") else ""
61
+ return "\n".join(new_lines) + trailing_newline
62
+
63
+
64
+ def ensure_generated_operational_handoff_block(
65
+ document_text: str,
66
+ replacement_lines: Iterable[str],
67
+ ) -> str:
68
+ """Insert or replace the operational handoff generated block."""
69
+
70
+ lines = document_text.splitlines()
71
+ begin_count = sum(1 for line in lines if line.strip() == GENERATED_BLOCK_BEGIN)
72
+ end_count = sum(1 for line in lines if line.strip() == GENERATED_BLOCK_END)
73
+ if begin_count == 1 and end_count == 1:
74
+ return replace_generated_operational_handoff_block(document_text, replacement_lines)
75
+ if begin_count or end_count:
76
+ raise ValueError("document must contain both generated operational handoff block markers or none")
77
+
78
+ replacement = list(replacement_lines)
79
+ if not replacement or replacement[0] != GENERATED_BLOCK_BEGIN or GENERATED_BLOCK_END not in replacement:
80
+ raise ValueError("replacement must include generated operational handoff block markers")
81
+
82
+ block = "\n".join(replacement).rstrip() + "\n\n"
83
+ return block + document_text
84
+
85
+
86
+ def render_current_operational_handoff_state(
87
+ root: Path | str = ".",
88
+ *,
89
+ path: Path | str = DEFAULT_OPERATIONAL_HANDOFF_STATE,
90
+ ) -> tuple[str, ...]:
91
+ data = load_operational_handoff_state(root, path=path)
92
+ current_head = data.get("current_head")
93
+ safe_state = data.get("last_substantive_work_state")
94
+ if not isinstance(current_head, dict):
95
+ raise ValueError("current_head must be a mapping")
96
+ if not isinstance(safe_state, dict):
97
+ raise ValueError("last_substantive_work_state must be a mapping")
98
+
99
+ lines = [
100
+ GENERATED_BLOCK_BEGIN,
101
+ "## Current Operational Handoff State",
102
+ "",
103
+ _commit_line("Current verified main/admin HEAD", current_head),
104
+ _commit_line("Last substantive work state", safe_state),
105
+ "",
106
+ ]
107
+
108
+ administrative_context = data.get("administrative_context", [])
109
+ if not isinstance(administrative_context, list):
110
+ raise ValueError("administrative_context must be a list")
111
+ lines.extend(str(item) for item in administrative_context)
112
+ if administrative_context:
113
+ lines.append("")
114
+
115
+ freshness_policy = data.get("freshness_policy", {})
116
+ if isinstance(freshness_policy, dict) and freshness_policy.get("text"):
117
+ lines.append(str(freshness_policy["text"]))
118
+
119
+ next_slice = data.get("next_safe_substantive_slice", {})
120
+ if isinstance(next_slice, dict) and next_slice.get("text"):
121
+ lines.append(str(next_slice["text"]))
122
+
123
+ lines.extend(["", GENERATED_BLOCK_END, ""])
124
+ return tuple(lines)
@@ -0,0 +1,80 @@
1
+ """Machine-readable output contract primitives.
2
+
3
+ This module defines the first deliberately small output-contract format. It is
4
+ limited to required literal section markers so it can reuse the existing runtime
5
+ validator without pretending to validate semantic correctness.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+ import yaml
15
+
16
+ from agentic_project_kit.runtime_validator import ValidationReport, validate_required_sections
17
+
18
+
19
+ @dataclass(frozen=True)
20
+ class OutputContract:
21
+ """Minimal machine-readable output contract."""
22
+
23
+ version: int
24
+ name: str
25
+ required_sections: tuple[str, ...]
26
+
27
+
28
+ def load_output_contract(path: Path) -> OutputContract:
29
+ """Load a minimal output contract from YAML."""
30
+ data = yaml.safe_load(path.read_text(encoding="utf-8"))
31
+ return parse_output_contract(data)
32
+
33
+
34
+ def parse_output_contract(data: Any) -> OutputContract:
35
+ """Parse raw YAML data into an OutputContract.
36
+
37
+ Raises ValueError with deterministic messages for invalid contract shapes.
38
+ """
39
+ if not isinstance(data, dict):
40
+ raise ValueError("output contract must be a mapping")
41
+
42
+ version = data.get("version")
43
+ name = data.get("name")
44
+ required_sections = data.get("required_sections")
45
+
46
+ if version != 1:
47
+ raise ValueError("output contract version must be 1")
48
+ if not isinstance(name, str) or not name.strip():
49
+ raise ValueError("output contract name is required")
50
+ if not isinstance(required_sections, list) or not required_sections:
51
+ raise ValueError("required_sections must be a non-empty list")
52
+ if not all(isinstance(section, str) and section.strip() for section in required_sections):
53
+ raise ValueError("required_sections must contain non-empty strings")
54
+
55
+ return OutputContract(
56
+ version=version,
57
+ name=name,
58
+ required_sections=tuple(required_sections),
59
+ )
60
+
61
+
62
+ def validate_output_against_contract(text: str, contract: OutputContract) -> ValidationReport:
63
+ """Validate output text against a minimal OutputContract.
64
+
65
+ The current contract format only defines required literal section markers.
66
+ Semantic validation remains intentionally out of scope.
67
+ """
68
+ return validate_required_sections(text, contract.required_sections)
69
+
70
+
71
+ def render_output_contract_yaml(contract: OutputContract) -> str:
72
+ """Render an OutputContract as stable YAML."""
73
+ return yaml.safe_dump(
74
+ {
75
+ "version": contract.version,
76
+ "name": contract.name,
77
+ "required_sections": list(contract.required_sections),
78
+ },
79
+ sort_keys=False,
80
+ )
@@ -0,0 +1,61 @@
1
+ """Minimal deterministic output repair primitives.
2
+
3
+ This module only performs bounded structural repair for literal required section
4
+ markers. It does not invent semantic content and does not call a model.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass
10
+
11
+ from agentic_project_kit.output_contract import OutputContract, validate_output_against_contract
12
+ from agentic_project_kit.repair_report import RepairOperation, RepairReport, repair_report_from_validation
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class OutputRepairResult:
17
+ text: str
18
+ report: RepairReport
19
+
20
+
21
+ def missing_required_sections(text: str, contract: OutputContract) -> tuple[str, ...]:
22
+ """Return required literal section markers that are absent from text."""
23
+ return tuple(section for section in contract.required_sections if section not in text)
24
+
25
+
26
+ def append_missing_required_sections(text: str, contract: OutputContract) -> OutputRepairResult:
27
+ """Append missing required section markers with explicit empty placeholders.
28
+
29
+ This is intentionally structural only. The placeholder makes the repair visible
30
+ and avoids pretending that semantic content was generated.
31
+ """
32
+ original_validation = validate_output_against_contract(text, contract)
33
+ original_findings = original_validation.to_dict()["findings"]
34
+ missing_sections = missing_required_sections(text, contract)
35
+ if not missing_sections:
36
+ report = repair_report_from_validation(
37
+ original_findings=original_findings,
38
+ final_ok=original_validation.ok,
39
+ final_findings=original_findings,
40
+ )
41
+ return OutputRepairResult(text=text, report=report)
42
+ repaired = text.rstrip()
43
+ operations: list[RepairOperation] = []
44
+ for section in missing_sections:
45
+ repaired = f"{repaired}\n\n{section}\nTODO: fill this section."
46
+ operations.append(
47
+ RepairOperation(
48
+ kind="append_missing_required_section",
49
+ status="applied",
50
+ target=section,
51
+ message="Appended missing required section marker with explicit placeholder.",
52
+ )
53
+ )
54
+ final_validation = validate_output_against_contract(repaired, contract)
55
+ report = repair_report_from_validation(
56
+ original_findings=original_findings,
57
+ final_ok=final_validation.ok,
58
+ final_findings=final_validation.to_dict()["findings"],
59
+ operations=operations,
60
+ )
61
+ return OutputRepairResult(text=repaired, report=report)
@@ -0,0 +1,216 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import json
5
+ from dataclasses import dataclass
6
+ from enum import Enum
7
+ from pathlib import Path
8
+ from typing import Literal
9
+
10
+
11
+ class CompletionOutcome(str, Enum):
12
+ PASS = "PASS"
13
+ PASS_ALREADY_DONE = "PASS_ALREADY_DONE"
14
+ FAIL = "FAIL"
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class CompletionClassification:
19
+ outcome: CompletionOutcome
20
+ reason: str
21
+ matched_phrase: str | None = None
22
+ target_state: str | None = None
23
+
24
+ @property
25
+ def success(self) -> bool:
26
+ return self.outcome in {CompletionOutcome.PASS, CompletionOutcome.PASS_ALREADY_DONE}
27
+
28
+
29
+ TargetState = Literal["git-clean", "remote-sync", "pull-request-exists", "branch-exists"]
30
+
31
+ SUPPORTED_TARGET_STATES: frozenset[str] = frozenset({
32
+ "git-clean",
33
+ "remote-sync",
34
+ "pull-request-exists",
35
+ "branch-exists",
36
+ })
37
+
38
+ DEFAULT_TARGET_STATES: frozenset[str] = frozenset({
39
+ "git-clean",
40
+ "remote-sync",
41
+ "pull-request-exists",
42
+ })
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class NoOpSuccessPattern:
47
+ phrase: str
48
+ reason: str
49
+ target_states: frozenset[str]
50
+
51
+
52
+ NO_OP_SUCCESS_PATTERNS: tuple[NoOpSuccessPattern, ...] = (
53
+ NoOpSuccessPattern("nothing to commit, working tree clean", "git commit target state already clean", frozenset({"git-clean"})),
54
+ NoOpSuccessPattern("nothing to commit", "git commit target state already clean", frozenset({"git-clean"})),
55
+ NoOpSuccessPattern("working tree clean", "worktree already clean", frozenset({"git-clean"})),
56
+ NoOpSuccessPattern("no changes to commit", "no changes to commit", frozenset({"git-clean"})),
57
+ NoOpSuccessPattern("everything up-to-date", "remote already up to date", frozenset({"remote-sync"})),
58
+ NoOpSuccessPattern("already up to date", "local branch already up to date", frozenset({"remote-sync"})),
59
+ NoOpSuccessPattern("a pull request for branch", "pull request already exists", frozenset({"pull-request-exists"})),
60
+ NoOpSuccessPattern("pull request already exists", "pull request already exists", frozenset({"pull-request-exists"})),
61
+ NoOpSuccessPattern("a branch named", "branch already exists", frozenset({"branch-exists"})),
62
+ )
63
+
64
+ HARD_FAIL_PATTERNS: tuple[tuple[str, str], ...] = (
65
+ ("traceback", "python traceback"),
66
+ ("syntaxerror", "python syntax error"),
67
+ )
68
+
69
+ FAIL_PATTERNS: tuple[tuple[str, str], ...] = (
70
+ ("error:", "command reported error"),
71
+ ("fatal:", "command reported fatal error"),
72
+ ("failed", "command reported failure"),
73
+ )
74
+
75
+
76
+ def _normalize_target_state(target_state: str | None) -> str | None:
77
+ if target_state is None:
78
+ return None
79
+ normalized = target_state.strip().lower().replace("_", "-")
80
+ return normalized or None
81
+
82
+
83
+ def _allowed_target_states(target_state: str | None) -> frozenset[str]:
84
+ normalized = _normalize_target_state(target_state)
85
+ if normalized is None:
86
+ return DEFAULT_TARGET_STATES
87
+ if normalized not in SUPPORTED_TARGET_STATES:
88
+ return frozenset()
89
+ return frozenset({normalized})
90
+
91
+
92
+ def classify_completion(
93
+ *,
94
+ exit_code: int,
95
+ output: str,
96
+ target_verified: bool = False,
97
+ target_state: str | None = None,
98
+ ) -> CompletionClassification:
99
+ normalized = output.lower()
100
+ if exit_code == 0:
101
+ return CompletionClassification(
102
+ CompletionOutcome.PASS,
103
+ "command exited successfully",
104
+ target_state=_normalize_target_state(target_state),
105
+ )
106
+ for phrase, reason in HARD_FAIL_PATTERNS:
107
+ if phrase in normalized:
108
+ return CompletionClassification(
109
+ CompletionOutcome.FAIL,
110
+ reason,
111
+ phrase,
112
+ target_state=_normalize_target_state(target_state),
113
+ )
114
+ if target_verified:
115
+ allowed_target_states = _allowed_target_states(target_state)
116
+ if not allowed_target_states:
117
+ return CompletionClassification(
118
+ CompletionOutcome.FAIL,
119
+ f"unsupported already-done target state: {target_state}",
120
+ target_state=_normalize_target_state(target_state),
121
+ )
122
+ for pattern in NO_OP_SUCCESS_PATTERNS:
123
+ if pattern.phrase in normalized and pattern.target_states & allowed_target_states:
124
+ return CompletionClassification(
125
+ CompletionOutcome.PASS_ALREADY_DONE,
126
+ pattern.reason,
127
+ pattern.phrase,
128
+ target_state=_normalize_target_state(target_state),
129
+ )
130
+ for phrase, reason in FAIL_PATTERNS:
131
+ if phrase in normalized:
132
+ return CompletionClassification(
133
+ CompletionOutcome.FAIL,
134
+ reason,
135
+ phrase,
136
+ target_state=_normalize_target_state(target_state),
137
+ )
138
+ return CompletionClassification(
139
+ CompletionOutcome.FAIL,
140
+ "non-zero exit without verified already-done target state",
141
+ target_state=_normalize_target_state(target_state),
142
+ )
143
+
144
+
145
+ def render_classification(classification: CompletionClassification) -> str:
146
+ lines = [
147
+ "PASS_ALREADY_DONE_CLASSIFICATION",
148
+ f"outcome: {classification.outcome.value}",
149
+ f"success: {'yes' if classification.success else 'no'}",
150
+ f"reason: {classification.reason}",
151
+ ]
152
+ if classification.target_state:
153
+ lines.append(f"target_state: {classification.target_state}")
154
+ if classification.matched_phrase:
155
+ lines.append(f"matched_phrase: {classification.matched_phrase}")
156
+ lines.append(f"### RESULT: {'PASS' if classification.success else 'FAIL'} ###")
157
+ return "\n".join(lines)
158
+
159
+
160
+
161
+ def classification_to_dict(classification: CompletionClassification) -> dict[str, object]:
162
+ return {
163
+ "outcome": classification.outcome.value,
164
+ "success": classification.success,
165
+ "reason": classification.reason,
166
+ "target_state": classification.target_state,
167
+ "matched_phrase": classification.matched_phrase,
168
+ }
169
+
170
+
171
+ def render_classification_json(classification: CompletionClassification) -> str:
172
+ return json.dumps(classification_to_dict(classification), sort_keys=True)
173
+
174
+
175
+ def classify_file(
176
+ path: Path,
177
+ *,
178
+ exit_code: int,
179
+ target_verified: bool = False,
180
+ target_state: str | None = None,
181
+ ) -> CompletionClassification:
182
+ return classify_completion(
183
+ exit_code=exit_code,
184
+ output=path.read_text(encoding="utf-8"),
185
+ target_verified=target_verified,
186
+ target_state=target_state,
187
+ )
188
+
189
+
190
+ def build_parser() -> argparse.ArgumentParser:
191
+ parser = argparse.ArgumentParser(prog="pass-already-done")
192
+ parser.add_argument("path", type=Path)
193
+ parser.add_argument("--exit-code", type=int, required=True)
194
+ parser.add_argument("--target-verified", action="store_true")
195
+ parser.add_argument("--target-state", choices=sorted(SUPPORTED_TARGET_STATES))
196
+ parser.add_argument("--json", action="store_true", dest="json_output")
197
+ return parser
198
+
199
+
200
+ def main(argv: list[str] | None = None) -> int:
201
+ args = build_parser().parse_args(argv)
202
+ classification = classify_file(
203
+ args.path,
204
+ exit_code=args.exit_code,
205
+ target_verified=args.target_verified,
206
+ target_state=args.target_state,
207
+ )
208
+ if args.json_output:
209
+ print(render_classification_json(classification))
210
+ else:
211
+ print(render_classification(classification))
212
+ return 0 if classification.success else 1
213
+
214
+
215
+ if __name__ == "__main__":
216
+ raise SystemExit(main())
@@ -0,0 +1,147 @@
1
+ from __future__ import annotations
2
+
3
+ import py_compile
4
+ from collections.abc import Callable
5
+ from pathlib import Path
6
+
7
+ import typer
8
+ import yaml
9
+
10
+ from agentic_project_kit import slice_gate
11
+ from agentic_project_kit.run_summary_renderer import validate_rendered_summary_text
12
+ from agentic_project_kit.rule_registry_validator import validate_rule_registry
13
+ from agentic_project_kit.workflow_guard import run_workflow_guard
14
+
15
+ FORBIDDEN_TEXT_PATTERNS = (
16
+ ("heredoc", "<" + "<"),
17
+ ("multiline-python-c", "python " + "-c"),
18
+ ("shell-pipestatus", "PIPE" + "STATUS"),
19
+ ("interactive-exit", "exit " + "0"),
20
+ ("interactive-exit", "exit " + "1"),
21
+ )
22
+
23
+ GOVERNANCE_YAML_FILES = (
24
+ ".agentic/handoff_state.yaml",
25
+ ".agentic/no_copy_terminal_policy.yaml",
26
+ ".agentic/rule_mechanism_inventory.yaml",
27
+ ".agentic/rule_migrations.yaml",
28
+ ".agentic/rule_test_coverage.yaml",
29
+ "docs/DOCUMENTATION_COVERAGE.yaml",
30
+ )
31
+
32
+ SliceGateRunner = Callable[[str, Path], slice_gate.SliceGateReport]
33
+
34
+
35
+ def existing_paths(paths: list[str]) -> list[Path]:
36
+ return [Path(path) for path in paths if Path(path).exists()]
37
+
38
+
39
+ def check_yaml_files(paths: list[str]) -> list[str]:
40
+ errors: list[str] = []
41
+ for path in existing_paths(paths):
42
+ try:
43
+ yaml.safe_load(path.read_text(encoding="utf-8"))
44
+ except Exception as exc:
45
+ errors.append(f"{path}: YAML parse failed: {exc}")
46
+ return errors
47
+
48
+
49
+ def check_python_files(paths: list[str]) -> list[str]:
50
+ errors: list[str] = []
51
+ for path in existing_paths(paths):
52
+ if path.suffix != ".py":
53
+ continue
54
+ try:
55
+ py_compile.compile(str(path), doraise=True)
56
+ except py_compile.PyCompileError as exc:
57
+ errors.append(f"{path}: Python compile failed: {exc.msg}")
58
+ return errors
59
+
60
+
61
+ def check_text_patterns(paths: list[str]) -> list[str]:
62
+ errors: list[str] = []
63
+ for path in existing_paths(paths):
64
+ if path.is_dir():
65
+ continue
66
+ try:
67
+ text = path.read_text(encoding="utf-8")
68
+ except UnicodeDecodeError:
69
+ continue
70
+ for name, pattern in FORBIDDEN_TEXT_PATTERNS:
71
+ if pattern in text:
72
+ errors.append(f"{path}: forbidden pattern {name}: {pattern}")
73
+ return errors
74
+
75
+
76
+ def check_final_summary_logs(paths: list[str]) -> list[str]:
77
+ errors: list[str] = []
78
+ for path in existing_paths(paths):
79
+ if path.suffix != ".log":
80
+ continue
81
+ text = path.read_text(encoding="utf-8")
82
+ if "SUMMARY" not in text:
83
+ continue
84
+ for error in validate_rendered_summary_text(text):
85
+ errors.append(f"{path}: {error}")
86
+ return errors
87
+
88
+
89
+ def check_rule_registry_files() -> list[str]:
90
+ return [
91
+ f"{finding.path}: {finding.message}"
92
+ for finding in validate_rule_registry()
93
+ ]
94
+
95
+
96
+ def _run_slice_gate(kind: str, project_root: Path) -> slice_gate.SliceGateReport:
97
+ return slice_gate.run_slice_gate(kind, project_root=project_root)
98
+
99
+
100
+ def check_required_slice_gate(
101
+ kind: str,
102
+ *,
103
+ project_root: Path = Path("."),
104
+ runner: SliceGateRunner | None = None,
105
+ ) -> list[str]:
106
+ report = (runner or _run_slice_gate)(kind, project_root)
107
+ errors: list[str] = []
108
+ if report.slice_result != "PASS":
109
+ errors.append(f"slice gate {kind}: slice_result={report.slice_result}")
110
+ if report.dirty_state.state != "CLEAN":
111
+ errors.append(f"slice gate {kind}: dirty_state={report.dirty_state.state}")
112
+ if errors:
113
+ rendered = slice_gate.render_slice_gate_report(report).splitlines()
114
+ errors.extend(f"slice gate {kind}: {line}" for line in rendered)
115
+ return errors
116
+
117
+
118
+ def run_preflight(paths: list[str], *, require_slice_gate: str | None = None, slice_gate_runner: SliceGateRunner | None = None) -> list[str]:
119
+ checked = list(dict.fromkeys([*paths, *GOVERNANCE_YAML_FILES]))
120
+ errors: list[str] = []
121
+ errors.extend(check_yaml_files([path for path in checked if path.endswith((".yaml", ".yml"))]))
122
+ errors.extend(check_python_files(checked))
123
+ errors.extend(check_text_patterns(paths))
124
+ errors.extend(check_final_summary_logs(paths))
125
+ errors.extend(check_rule_registry_files())
126
+ for finding in run_workflow_guard(paths):
127
+ errors.append(finding.line())
128
+ if require_slice_gate:
129
+ errors.extend(check_required_slice_gate(require_slice_gate, project_root=Path("."), runner=slice_gate_runner))
130
+ return errors
131
+
132
+
133
+ def patch_preflight(paths: list[str] = typer.Argument(None), require_slice_gate: str | None = typer.Option(None, "--require-slice-gate", help="Require a clean passing slice gate before accepting preflight.")) -> None:
134
+ requested = paths or []
135
+ errors = run_preflight(requested, require_slice_gate=require_slice_gate)
136
+ if errors:
137
+ typer.echo("Patch artifact preflight failed")
138
+ for error in errors:
139
+ typer.echo(f"[FAIL] {error}")
140
+ raise typer.Exit(1)
141
+ typer.echo("Patch artifact preflight passed")
142
+ if require_slice_gate:
143
+ typer.echo(f"Required slice gate passed: {require_slice_gate}")
144
+
145
+
146
+ def register_patch_preflight_command(app: typer.Typer) -> None:
147
+ app.command("patch-preflight")(patch_preflight)