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,430 @@
1
+ from __future__ import annotations
2
+
3
+ from datetime import date as date_cls
4
+ import hashlib
5
+ import json
6
+ from pathlib import Path
7
+ import subprocess
8
+
9
+ import typer
10
+
11
+ from agentic_project_kit.doc_lifecycle import build_doc_lifecycle_release_blockers
12
+ from agentic_project_kit.release_metadata_authority_gate import release_anchor_changes
13
+ from agentic_project_kit.work_discard_changes import discard_all_changes
14
+ from agentic_project_kit.workspace import load_workspace
15
+
16
+ work_app = typer.Typer(help="Human-friendly meta commands for patch, PR, and recovery workflows.")
17
+ release_flow_app = typer.Typer(help="Human-friendly meta commands for release readiness and preparation.")
18
+
19
+
20
+ def _run_step(name: str, argv: list[str], *, allowed_returncodes: set[int] | None = None) -> dict[str, object]:
21
+ allowed = allowed_returncodes or {0}
22
+ completed = subprocess.run(argv, text=True, capture_output=True)
23
+ return {
24
+ "name": name,
25
+ "argv": argv,
26
+ "returncode": completed.returncode,
27
+ "ok": completed.returncode in allowed,
28
+ "allowed_returncodes": sorted(allowed),
29
+ "stdout": completed.stdout,
30
+ "stderr": completed.stderr,
31
+ }
32
+
33
+
34
+ def _payload(action: str, steps: list[dict[str, object]], *, dry_run: bool = False, extra: dict[str, object] | None = None) -> dict[str, object]:
35
+ blockers = [str(step["name"]) for step in steps if not step["ok"]]
36
+ result_status = "PASS" if not blockers else "BLOCKED"
37
+ payload: dict[str, object] = {
38
+ "schema_version": 1,
39
+ "kind": f"human_{action.replace('-', '_')}_result",
40
+ "action": action,
41
+ "result_status": result_status,
42
+ "returncode": 0 if result_status == "PASS" else 2,
43
+ "dry_run": dry_run,
44
+ "blockers": blockers,
45
+ "steps": steps,
46
+ "next_action": "Workflow completed." if result_status == "PASS" else "Inspect and fix blocked workflow steps.",
47
+ }
48
+ if extra:
49
+ payload.update(extra)
50
+ return payload
51
+
52
+
53
+ def _emit(payload: dict[str, object], *, json_output: bool) -> None:
54
+ if json_output:
55
+ typer.echo(json.dumps(payload, indent=2, sort_keys=True))
56
+ return
57
+ typer.echo(f"STATE={payload['result_status']}")
58
+ typer.echo(f"RETURNCODE={payload['returncode']}")
59
+ if payload["blockers"]:
60
+ typer.echo("BLOCKERS=" + ",".join(str(item) for item in payload["blockers"]))
61
+ typer.echo(f"NEXT={payload['next_action']}")
62
+
63
+
64
+ def _exit_if_blocked(payload: dict[str, object]) -> None:
65
+ if payload["result_status"] != "PASS":
66
+ raise typer.Exit(code=int(payload["returncode"]))
67
+
68
+
69
+ def _agentic(*parts: str) -> list[str]:
70
+ return ["./.venv/bin/agentic-kit", *parts]
71
+
72
+
73
+ def _python(*parts: str) -> list[str]:
74
+ return ["./.venv/bin/python", *parts]
75
+
76
+
77
+ def _latest_release_tag() -> str:
78
+ completed = subprocess.run(["git", "tag", "--sort=-creatordate"], text=True, capture_output=True)
79
+ if completed.returncode != 0:
80
+ return ""
81
+ for line in completed.stdout.splitlines():
82
+ tag = line.strip()
83
+ if tag.startswith("v"):
84
+ return tag
85
+ return ""
86
+
87
+
88
+ def _path_args(paths: list[Path]) -> list[str]:
89
+ args: list[str] = []
90
+ for path in paths:
91
+ args.extend(["--path", str(path)])
92
+ return args
93
+
94
+
95
+ def _changed_paths_against(base_ref: str) -> list[str]:
96
+ completed = subprocess.run(
97
+ ["git", "diff", "--name-only", base_ref],
98
+ text=True,
99
+ stdout=subprocess.PIPE,
100
+ stderr=subprocess.STDOUT,
101
+ )
102
+ if completed.returncode != 0:
103
+ raise RuntimeError(completed.stdout.strip() or f"git diff failed for {base_ref}")
104
+ return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
105
+
106
+
107
+ def _compact_step_for_report(step: dict[str, object]) -> dict[str, object]:
108
+ stdout = str(step.get("stdout") or "")
109
+ stderr = str(step.get("stderr") or "")
110
+ stdout_lines = [line for line in stdout.splitlines() if line.strip()]
111
+ stderr_lines = [line for line in stderr.splitlines() if line.strip()]
112
+ return {
113
+ "name": step.get("name"),
114
+ "argv": step.get("argv"),
115
+ "returncode": step.get("returncode"),
116
+ "ok": step.get("ok"),
117
+ "allowed_returncodes": step.get("allowed_returncodes"),
118
+ "stdout_length": len(stdout),
119
+ "stdout_sha256": hashlib.sha256(stdout.encode("utf-8")).hexdigest(),
120
+ "stdout_last_line": stdout_lines[-1][:500] if stdout_lines else "",
121
+ "stderr_length": len(stderr),
122
+ "stderr_sha256": hashlib.sha256(stderr.encode("utf-8")).hexdigest(),
123
+ "stderr_last_line": stderr_lines[-1][:500] if stderr_lines else "",
124
+ }
125
+
126
+
127
+ def _write_release_prepare_report_step(
128
+ *,
129
+ version: str,
130
+ release_date: str,
131
+ from_tag: str,
132
+ to_ref: str,
133
+ summary_lines_path: Path,
134
+ prior_steps: list[dict[str, object]],
135
+ base_ref: str = "origin/main",
136
+ ) -> dict[str, object]:
137
+ workspace = load_workspace(Path("."), suppress_legacy_profile_warning=True)
138
+ report_path = workspace.reports_dir() / "release" / f"release-prepare-{version}.json"
139
+ try:
140
+ changed_paths = _changed_paths_against(base_ref)
141
+ payload = {
142
+ "schema_version": 1,
143
+ "kind": "release_prepare_evidence",
144
+ "version": version,
145
+ "date": release_date,
146
+ "from_tag": from_tag,
147
+ "to_ref": to_ref,
148
+ "base_ref": base_ref,
149
+ "summary_lines_path": str(summary_lines_path),
150
+ "authorized_route": "agentic-kit release-prep",
151
+ "changed_paths_against_base": changed_paths,
152
+ "release_metadata_anchor_paths": release_anchor_changes(changed_paths),
153
+ "steps": [_compact_step_for_report(step) for step in prior_steps],
154
+ }
155
+ report_path.parent.mkdir(parents=True, exist_ok=True)
156
+ report_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
157
+ except (OSError, RuntimeError) as exc:
158
+ return {
159
+ "name": "release-prepare-report",
160
+ "argv": ["agentic-kit", "release", "prepare", "--write", "--json"],
161
+ "returncode": 2,
162
+ "ok": False,
163
+ "allowed_returncodes": [0],
164
+ "stdout": "",
165
+ "stderr": str(exc),
166
+ }
167
+ return {
168
+ "name": "release-prepare-report",
169
+ "argv": ["agentic-kit", "release", "prepare", "--write", "--json"],
170
+ "returncode": 0,
171
+ "ok": True,
172
+ "allowed_returncodes": [0],
173
+ "stdout": workspace.path_text(report_path) + "\n",
174
+ "stderr": "",
175
+ }
176
+
177
+
178
+ def _doc_lifecycle_release_review_step(version: str) -> dict[str, object]:
179
+ blockers = build_doc_lifecycle_release_blockers(Path("."), version=version)
180
+ lines = [
181
+ "DOC_LIFECYCLE_RELEASE_REVIEW",
182
+ f"STATUS={'BLOCKED' if blockers else 'PASS'}",
183
+ f"BLOCKER_COUNT={len(blockers)}",
184
+ ]
185
+ for finding in blockers:
186
+ lines.append(f"BLOCKER={finding.code}|{finding.path}|{finding.message}")
187
+ if blockers:
188
+ lines.append("NEXT=Run docs lifecycle sweep before release readiness.")
189
+ return {
190
+ "name": "doc-lifecycle-release-review",
191
+ "argv": ["agentic-kit", "doc-lifecycle-audit", "--json", "--current-version", version],
192
+ "returncode": 2 if blockers else 0,
193
+ "ok": not blockers,
194
+ "allowed_returncodes": [0],
195
+ "stdout": "\n".join(lines) + "\n",
196
+ "stderr": "",
197
+ }
198
+
199
+
200
+ @work_app.command("start")
201
+ def work_start_command(
202
+ branch: str = typer.Option(..., "--branch", help="Feature branch to create or switch to."),
203
+ kind: str = typer.Option("patch", "--kind", help="Human label for the work kind."),
204
+ from_ref: str = typer.Option("main", "--from-ref", help="Start new work from this tag or branch ref."),
205
+ json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
206
+ ) -> None:
207
+ """Start a human patch/slice workflow with the safe standard startup sequence."""
208
+ base_ref = from_ref.strip() or "main"
209
+ steps = [
210
+ _run_step("sync-main", _agentic("transfer", "sync-main")),
211
+ _run_step("rules-acknowledge", _agentic("rules", "acknowledge")),
212
+ _run_step("post-merge-check", _agentic("transfer", "post-merge-check")),
213
+ _run_step("repo-status", _agentic("transfer", "repo-status")),
214
+ ]
215
+ if all(step["ok"] for step in steps):
216
+ exists = subprocess.run(["git", "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"])
217
+ if exists.returncode == 0:
218
+ steps.append(_run_step("git-switch-branch", ["git", "switch", branch]))
219
+ else:
220
+ steps.append(
221
+ _run_step(
222
+ "branch-create",
223
+ _agentic("transfer", "branch-create", branch, "--start-point", base_ref),
224
+ )
225
+ )
226
+ payload = _payload("work-start", steps, extra={"branch": branch, "from_ref": base_ref, "work_kind": kind})
227
+ _emit(payload, json_output=json_output)
228
+ _exit_if_blocked(payload)
229
+
230
+
231
+ @work_app.command("check")
232
+ def work_check_command(
233
+ profile: str = typer.Option("code", "--profile", help="Check profile: minimal, code, docs, or release."),
234
+ json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
235
+ ) -> None:
236
+ """Run common human workflow gates without committing or pushing."""
237
+ steps: list[dict[str, object]] = [
238
+ _run_step("repo-status", _agentic("transfer", "repo-status")),
239
+ _run_step("command-reference-check", _agentic("transfer", "command-reference-check", "--json")),
240
+ ]
241
+ if profile in {"code", "release"}:
242
+ steps.extend(
243
+ [
244
+ _run_step("ruff", _python("-m", "ruff", "check", ".")),
245
+ _run_step("pytest-core", _python("-m", "pytest", "tests/test_transfer_startup_hardening_commands.py", "tests/test_agentic_kit_command_reference_is_current.py", "-q")),
246
+ ]
247
+ )
248
+ if profile in {"docs", "release"}:
249
+ steps.extend(
250
+ [
251
+ _run_step("docs-audit", _agentic("docs-audit")),
252
+ _run_step("audit-doc-currency", _agentic("audit-doc-currency")),
253
+ _run_step("audit-ns-legacy-references", _agentic("audit-ns-legacy-references")),
254
+ ]
255
+ )
256
+ if profile == "release":
257
+ steps.append(_run_step("standard-error-scan", _agentic("transfer", "standard-error-scan", "--json"), allowed_returncodes={0}))
258
+ payload = _payload("work-check", steps, extra={"profile": profile})
259
+ _emit(payload, json_output=json_output)
260
+ _exit_if_blocked(payload)
261
+
262
+
263
+ @work_app.command("finish")
264
+ def work_finish_command(
265
+ branch: str = typer.Option(..., "--branch", help="Feature branch to finish."),
266
+ title: str = typer.Option(..., "--title", help="Pull request title."),
267
+ message: str = typer.Option(..., "--message", help="Commit message."),
268
+ paths: list[Path] | None = typer.Option(None, "--path", help="Path to include in the commit. Repeatable."),
269
+ merge_method: str = typer.Option("squash", "--merge-method", help="PR merge method."),
270
+ dry_run: bool = typer.Option(True, "--dry-run/--execute", help="Plan by default. Use --execute to commit, push, and merge."),
271
+ json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
272
+ ) -> None:
273
+ """Finish a human work slice by planning or executing commit, push, PR, merge, and post-merge checks."""
274
+ selected_paths = paths or []
275
+ steps: list[dict[str, object]] = [
276
+ _run_step("repo-status", _agentic("transfer", "repo-status")),
277
+ _run_step("protected-diff-plan", _agentic("transfer", "protected-diff-plan", "--label", branch.replace("/", "-"))),
278
+ ]
279
+ if not selected_paths:
280
+ steps.append({"name": "path-selection", "argv": [], "returncode": 2, "ok": False, "allowed_returncodes": [0], "stdout": "", "stderr": "At least one --path is required for work finish."})
281
+ if not dry_run and all(step["ok"] for step in steps):
282
+ steps.extend(
283
+ [
284
+ _run_step("commit", _agentic("transfer", "commit", "--branch", branch, "--message", message, *_path_args(selected_paths))),
285
+ _run_step("rules-acknowledge", _agentic("rules", "acknowledge")),
286
+ _run_step("push-current", _agentic("transfer", "push-current", "--branch", branch)),
287
+ _run_step("pr-create-complete", _agentic("transfer", "pr-create-complete", "--title", title, "--body", f"Human workflow finish: {title}", "--base", "main", "--head", branch, "--merge-method", merge_method, "--post-merge-complete", "--skip-llm-context-gate", "--timeout-seconds", "300", "--interval-seconds", "10", "--json")),
288
+ _run_step("sync-main", _agentic("transfer", "sync-main")),
289
+ _run_step("post-merge-check", _agentic("transfer", "post-merge-check")),
290
+ _run_step("repo-status", _agentic("transfer", "repo-status")),
291
+ ]
292
+ )
293
+ payload = _payload("work-finish", steps, dry_run=dry_run, extra={"branch": branch, "paths": [str(path) for path in selected_paths], "title": title})
294
+ _emit(payload, json_output=json_output)
295
+ _exit_if_blocked(payload)
296
+
297
+
298
+ @work_app.command("recover")
299
+ def work_recover_command(json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON.")) -> None:
300
+ """Run safe recovery/status commands after interrupted work."""
301
+ steps = [
302
+ _run_step("restore-known-volatile", _agentic("transfer", "restore-known-volatile", "--json")),
303
+ _run_step("normalize-session", _agentic("transfer", "normalize-session", "--repair-known-volatile")),
304
+ _run_step("repo-status", _agentic("transfer", "repo-status")),
305
+ _run_step("conflict-status", _agentic("transfer", "conflict-status", "--json"), allowed_returncodes={0, 2}),
306
+ _run_step("patch-cycle-status", _agentic("transfer", "patch-cycle-status", "--include-ci", "--json"), allowed_returncodes={0, 2}),
307
+ ]
308
+ payload = _payload(
309
+ "work-recover",
310
+ steps,
311
+ extra={
312
+ "destructive_actions_allowed": False,
313
+ "discard_all_available": False,
314
+ "discard_all_next_action": (
315
+ "Use a separate explicitly destructive workflow; work recover never "
316
+ "runs reset, clean, checkout, or broad restore over product files."
317
+ ),
318
+ },
319
+ )
320
+ _emit(payload, json_output=json_output)
321
+ _exit_if_blocked(payload)
322
+
323
+
324
+ @work_app.command("discard-changes")
325
+ def work_discard_changes_command(
326
+ execute: bool = typer.Option(False, "--execute", help="Discard all feature-branch changes. Dry-run is the default."),
327
+ expected_signature: str = typer.Option(
328
+ "",
329
+ "--expected-signature",
330
+ help="Optional dry-run signature that must match before execute.",
331
+ ),
332
+ json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
333
+ ) -> None:
334
+ """Preview or execute the explicit destructive discard-all workflow."""
335
+ payload = discard_all_changes(
336
+ Path("."),
337
+ execute=execute,
338
+ expected_signature=expected_signature,
339
+ )
340
+ _emit(payload, json_output=json_output)
341
+ _exit_if_blocked(payload)
342
+
343
+
344
+ @release_flow_app.command("ready")
345
+ def release_ready_command(
346
+ version: str = typer.Option(..., "--version", help="Target release version."),
347
+ from_tag: str = typer.Option("", "--from-tag", help="Previous release tag. Defaults to latest local v* git tag."),
348
+ to_ref: str = typer.Option("main", "--to-ref", help="Target ref."),
349
+ date: str = typer.Option("", "--date", help="Release date. Defaults to today."),
350
+ json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
351
+ ) -> None:
352
+ """Run release readiness through the standard-error scan wrapper."""
353
+ release_date = date or date_cls.today().isoformat()
354
+ effective_from_tag = from_tag or _latest_release_tag()
355
+ steps = [
356
+ _run_step("sync-main", _agentic("transfer", "sync-main")),
357
+ _run_step("standard-error-scan", _agentic("transfer", "standard-error-scan", "--before-release", "--version", version, "--from-tag", effective_from_tag, "--to-ref", to_ref, "--date", release_date, "--json"), allowed_returncodes={0}),
358
+ _doc_lifecycle_release_review_step(version),
359
+ _run_step("release-status", _agentic("release-status", "--include-remote", "--json"), allowed_returncodes={0, 2}),
360
+ ]
361
+ payload = _payload("release-ready", steps, extra={"version": version, "from_tag": effective_from_tag, "to_ref": to_ref, "date": release_date})
362
+ _emit(payload, json_output=json_output)
363
+ _exit_if_blocked(payload)
364
+
365
+
366
+ @release_flow_app.command("prepare")
367
+ def release_prepare_command(
368
+ version: str = typer.Option(..., "--version", help="Target release version."),
369
+ from_tag: str = typer.Option("", "--from-tag", help="Previous release tag. Defaults to latest local v* git tag."),
370
+ to_ref: str = typer.Option("main", "--to-ref", help="Target ref."),
371
+ date: str = typer.Option("", "--date", help="Release date. Defaults to today."),
372
+ dry_run: bool = typer.Option(True, "--dry-run/--write", help="Dry-run by default. Use --write to update release metadata."),
373
+ json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
374
+ ) -> None:
375
+ """Generate release summary evidence and run release-prep safely."""
376
+ release_date = date or date_cls.today().isoformat()
377
+ effective_from_tag = from_tag or _latest_release_tag()
378
+ summary_lines_path = load_workspace(Path(".")).tmp_file(f"release-{version.replace('.', '')}-summary-lines.json")
379
+ steps = [
380
+ _run_step("release-notes-generate", _agentic("release-notes-generate", "--version", version, "--from-tag", effective_from_tag, "--to-ref", to_ref, "--include-github-metadata", "--summary-lines-json", str(summary_lines_path), "--json"))
381
+ ]
382
+ if all(step["ok"] for step in steps):
383
+ release_prep_argv = _agentic(
384
+ "release-prep",
385
+ "--version",
386
+ version,
387
+ "--date",
388
+ release_date,
389
+ "--summary-lines-from",
390
+ str(summary_lines_path),
391
+ "--json",
392
+ )
393
+ if dry_run:
394
+ release_prep_argv.insert(-1, "--dry-run")
395
+ steps.append(_run_step("release-prep", release_prep_argv))
396
+ if not dry_run and all(step["ok"] for step in steps):
397
+ steps.append(
398
+ _run_step(
399
+ "commands-sync-entrypoints",
400
+ _agentic("commands", "sync-entrypoints", "--execute", "--json"),
401
+ )
402
+ )
403
+ evidence_path = ""
404
+ if not dry_run and all(step["ok"] for step in steps):
405
+ report_step = _write_release_prepare_report_step(
406
+ version=version,
407
+ release_date=release_date,
408
+ from_tag=effective_from_tag,
409
+ to_ref=to_ref,
410
+ summary_lines_path=summary_lines_path,
411
+ prior_steps=list(steps),
412
+ )
413
+ if report_step["ok"]:
414
+ evidence_path = str(report_step["stdout"]).strip()
415
+ steps.append(report_step)
416
+ payload = _payload(
417
+ "release-prepare",
418
+ steps,
419
+ dry_run=dry_run,
420
+ extra={
421
+ "version": version,
422
+ "from_tag": effective_from_tag,
423
+ "to_ref": to_ref,
424
+ "date": release_date,
425
+ "summary_lines_path": str(summary_lines_path),
426
+ "evidence_path": evidence_path,
427
+ },
428
+ )
429
+ _emit(payload, json_output=json_output)
430
+ _exit_if_blocked(payload)
@@ -0,0 +1,132 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ import subprocess
5
+
6
+ import typer
7
+ from rich.console import Console
8
+ from rich.prompt import Confirm, Prompt
9
+
10
+ from agentic_project_kit.contract import (
11
+ PROFILE_DEFINITIONS,
12
+ POLICY_PACK_DEFINITIONS,
13
+ default_profiles,
14
+ recommended_policy_packs,
15
+ validate_ids,
16
+ )
17
+ from agentic_project_kit.github import create_github_repo
18
+ from agentic_project_kit.models import ProjectOptions
19
+ from agentic_project_kit.templates import create_project
20
+
21
+ console = Console()
22
+
23
+
24
+ def register_init_command(app: typer.Typer) -> None:
25
+ app.command(
26
+ "init",
27
+ help="Create a governed project skeleton with selected profiles and policy packs.",
28
+ )(init_command)
29
+
30
+
31
+ def init_command(
32
+ name: str | None = typer.Argument(None, help="Project directory/name."),
33
+ project_type: str = typer.Option("python-cli", "--type", help="python-cli, python-lib, generic, governance-wrapper"),
34
+ description: str | None = typer.Option(None, "--description"),
35
+ license_name: str = typer.Option("MIT", "--license"),
36
+ github_actions: bool = typer.Option(True, "--github-actions/--no-github-actions"),
37
+ pre_commit: bool = typer.Option(True, "--pre-commit/--no-pre-commit"),
38
+ agent_docs: bool = typer.Option(True, "--agent-docs/--no-agent-docs"),
39
+ logging_evidence: bool = typer.Option(True, "--logging-evidence/--no-logging-evidence"),
40
+ profiles: str | None = typer.Option(
41
+ None,
42
+ "--profiles",
43
+ help="Comma-separated profile ids. Defaults are recommended from project type.",
44
+ ),
45
+ policy_packs: str | None = typer.Option(
46
+ None,
47
+ "--policy-packs",
48
+ help="Comma-separated policy pack ids. Defaults are recommended from project type.",
49
+ ),
50
+ github: bool = typer.Option(False, "--github/--no-github"),
51
+ github_owner: str | None = typer.Option(None, "--owner"),
52
+ visibility: str = typer.Option("private", "--visibility", help="private or public"),
53
+ kit_source: str = typer.Option(
54
+ "pypi",
55
+ "--kit-source",
56
+ help="agentic-kit install source for generated CI: pypi, testpypi, or none",
57
+ ),
58
+ ) -> None:
59
+ if name is None:
60
+ name = Prompt.ask("Project name")
61
+ if description is None:
62
+ description = Prompt.ask("Project description", default=f"{name} project")
63
+ if project_type not in {"python-cli", "python-lib", "generic", "governance-wrapper"}:
64
+ raise typer.BadParameter("project type must be python-cli, python-lib, generic, or governance-wrapper")
65
+ if visibility not in {"private", "public"}:
66
+ raise typer.BadParameter("visibility must be private or public")
67
+ if kit_source not in {"pypi", "testpypi", "none"}:
68
+ raise typer.BadParameter("kit source must be pypi, testpypi, or none")
69
+
70
+ selected_profiles = _parse_csv(profiles) or default_profiles(
71
+ project_type,
72
+ github_actions=github_actions,
73
+ )
74
+ selected_policy_packs = _parse_csv(policy_packs) or recommended_policy_packs(
75
+ project_type,
76
+ github_actions=github_actions,
77
+ logging_evidence=logging_evidence,
78
+ )
79
+ errors = validate_ids("profile", selected_profiles, PROFILE_DEFINITIONS)
80
+ errors.extend(validate_ids("policy pack", selected_policy_packs, POLICY_PACK_DEFINITIONS))
81
+ if errors:
82
+ raise typer.BadParameter("; ".join(errors))
83
+
84
+ target = Path(name).resolve()
85
+ options = ProjectOptions(
86
+ name=name,
87
+ description=description,
88
+ project_type=project_type,
89
+ license_name=license_name,
90
+ github_actions=github_actions,
91
+ pre_commit=pre_commit,
92
+ agent_docs=agent_docs,
93
+ logging_evidence=logging_evidence,
94
+ target_dir=target,
95
+ kit_source=kit_source,
96
+ profiles=selected_profiles,
97
+ policy_packs=selected_policy_packs,
98
+ )
99
+
100
+ create_project(options)
101
+ console.print(f"[green]Created project:[/green] {target}")
102
+ console.print("Recommended profiles: " + ", ".join(selected_profiles))
103
+ console.print("Recommended policy packs: " + ", ".join(selected_policy_packs))
104
+
105
+ subprocess.run(["git", "add", "."], cwd=target, check=False)
106
+ subprocess.run(["git", "commit", "-m", "Initialize agentic project"], cwd=target, check=False)
107
+
108
+ if github:
109
+ if visibility == "public":
110
+ console.print("[bold yellow]Public repository selected. Check for secrets before continuing.[/bold yellow]")
111
+ if not Confirm.ask("Continue with public GitHub repository creation?", default=False):
112
+ raise typer.Exit(code=1)
113
+ create_github_repo(target, owner=github_owner, visibility=visibility, push=True)
114
+ console.print("[green]GitHub repository created and pushed.[/green]")
115
+
116
+ console.print("Next:")
117
+ console.print(f" cd {target}")
118
+ if project_type in {"python-cli", "python-lib"}:
119
+ console.print(" python -m venv .venv")
120
+ console.print(" source .venv/bin/activate")
121
+ console.print(' pip install -e ".[dev]"', markup=False)
122
+ console.print(" pytest -q")
123
+ else:
124
+ console.print(" agentic-kit check-docs")
125
+ console.print(" agentic-kit check")
126
+ console.print(" agentic-kit doctor")
127
+
128
+
129
+ def _parse_csv(value: str | None) -> tuple[str, ...]:
130
+ if value is None:
131
+ return ()
132
+ return tuple(item.strip() for item in value.split(",") if item.strip())
@@ -0,0 +1,75 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import sys
5
+ from pathlib import Path
6
+
7
+ import typer
8
+
9
+ from agentic_project_kit.command_manifest import load_manifest
10
+ from agentic_project_kit.instruction_lint import (
11
+ lint_instruction_file,
12
+ lint_instruction_text,
13
+ render_instruction_lint_result,
14
+ unreadable_instruction_result,
15
+ )
16
+
17
+ instruction_app = typer.Typer(help="Lint LLM instruction text before applying it.")
18
+
19
+
20
+ @instruction_app.command("lint")
21
+ def instruction_lint_command(
22
+ file_path: Path | None = typer.Option(None, "--file", help="Instruction text file to lint."),
23
+ stdin_input: bool = typer.Option(False, "--stdin", help="Read instruction text from stdin."),
24
+ require_ack: bool = typer.Option(
25
+ True,
26
+ "--require-ack/--no-require-ack",
27
+ help="Require the current COMMAND_MANIFEST_ACK line.",
28
+ ),
29
+ strict_unknown: bool = typer.Option(
30
+ False,
31
+ "--strict-unknown",
32
+ help="Treat unknown raw git/gh commands as blocking.",
33
+ ),
34
+ root: Path = typer.Option(Path("."), "--root", help="Repository root."),
35
+ json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
36
+ ) -> None:
37
+ """Lint instruction text against the current command manifest."""
38
+ if (file_path is None) == (not stdin_input):
39
+ typer.echo("Provide exactly one of --file or --stdin.", err=True)
40
+ raise typer.Exit(code=2)
41
+ checked_path = "<stdin>"
42
+ if stdin_input:
43
+ try:
44
+ text = sys.stdin.read()
45
+ except Exception as exc:
46
+ result = unreadable_instruction_result(
47
+ checked_path=checked_path,
48
+ message=str(exc),
49
+ )
50
+ if json_output:
51
+ typer.echo(json.dumps(result.to_dict(), indent=2, sort_keys=True))
52
+ else:
53
+ typer.echo(render_instruction_lint_result(result), nl=False)
54
+ raise typer.Exit(code=result.returncode) from exc
55
+ result = lint_instruction_text(
56
+ text,
57
+ manifest=load_manifest(root.resolve()),
58
+ checked_path=checked_path,
59
+ require_ack=require_ack,
60
+ strict_unknown=strict_unknown,
61
+ )
62
+ else:
63
+ assert file_path is not None
64
+ result = lint_instruction_file(
65
+ file_path,
66
+ root=root,
67
+ require_ack=require_ack,
68
+ strict_unknown=strict_unknown,
69
+ )
70
+ if json_output:
71
+ typer.echo(json.dumps(result.to_dict(), indent=2, sort_keys=True))
72
+ else:
73
+ typer.echo(render_instruction_lint_result(result), nl=False)
74
+ if result.returncode:
75
+ raise typer.Exit(code=result.returncode)
@@ -0,0 +1,24 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+
5
+ import typer
6
+
7
+ from agentic_project_kit.mutation_lock_audit import (
8
+ audit_mutation_lock_coverage,
9
+ render_mutation_lock_coverage_audit,
10
+ )
11
+
12
+
13
+ def register_mutation_lock_audit_command(app: typer.Typer) -> None:
14
+ @app.command("audit-mutation-lock-coverage")
15
+ def audit_mutation_lock_coverage_command(
16
+ json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
17
+ ) -> None:
18
+ """Audit mutating entrypoints for workspace mutation-lock coverage."""
19
+ result = audit_mutation_lock_coverage(".")
20
+ if json_output:
21
+ typer.echo(json.dumps(result.to_dict(), indent=2, sort_keys=True))
22
+ else:
23
+ typer.echo(render_mutation_lock_coverage_audit(result), nl=False)
24
+ raise typer.Exit(result.returncode)