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,192 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import asdict, dataclass
4
+ import json
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ from agentic_project_kit.chat_entrypoint_contract import (
9
+ COMMAND_REFERENCE_JSON,
10
+ COMMAND_REFERENCE_MARKDOWN,
11
+ command_manifest_ack_line,
12
+ load_command_manifest,
13
+ mandatory_entrypoint_line,
14
+ )
15
+
16
+ TEXT_COMMAND_AUTHORITY_SURFACES: tuple[str, ...] = (
17
+ "AGENTS.md",
18
+ "docs/handoff/START_NEW_CHAT_PROMPT.md",
19
+ "docs/handoff/NEXT_CHAT_BOOTSTRAP.md",
20
+ "docs/handoff/CLOSEOUT_BEFORE_CHAT_SWITCH_PROMPT.md",
21
+ "docs/reports/handoff-packages/latest/successor_prompt.md",
22
+ )
23
+
24
+ EXECUTION_CONTRACT_SURFACE = "docs/reports/handoff-packages/latest/execution_contract.json"
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class CommandAuthorityFinding:
29
+ severity: str
30
+ code: str
31
+ path: str
32
+ message: str
33
+
34
+ def as_dict(self) -> dict[str, str]:
35
+ return asdict(self)
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class CommandAuthorityAudit:
40
+ root: str
41
+ manifest_sha: str
42
+ findings: tuple[CommandAuthorityFinding, ...]
43
+
44
+ @property
45
+ def blockers(self) -> tuple[CommandAuthorityFinding, ...]:
46
+ return tuple(finding for finding in self.findings if finding.severity == "BLOCK")
47
+
48
+ @property
49
+ def ok(self) -> bool:
50
+ return not self.blockers
51
+
52
+ @property
53
+ def status(self) -> str:
54
+ return "PASS" if self.ok else "BLOCK"
55
+
56
+ @property
57
+ def returncode(self) -> int:
58
+ return 0 if self.ok else 2
59
+
60
+ def as_dict(self) -> dict[str, Any]:
61
+ return {
62
+ "schema_version": 1,
63
+ "kind": "command_authority_audit",
64
+ "root": self.root,
65
+ "manifest_sha": self.manifest_sha,
66
+ "status": self.status,
67
+ "finding_count": len(self.findings),
68
+ "blocker_count": len(self.blockers),
69
+ "findings": [finding.as_dict() for finding in self.findings],
70
+ }
71
+
72
+
73
+ def _manifest_sha(manifest: dict[str, Any]) -> str:
74
+ meta = manifest.get("meta") if isinstance(manifest.get("meta"), dict) else {}
75
+ return str(meta.get("manifest_sha") or "UNKNOWN")
76
+
77
+
78
+ def _finding(code: str, path: str, message: str) -> CommandAuthorityFinding:
79
+ return CommandAuthorityFinding("BLOCK", code, path, message)
80
+
81
+
82
+ def _required_text_terms(path: str, manifest: dict[str, Any]) -> tuple[str, ...]:
83
+ ack = command_manifest_ack_line(manifest)
84
+ if path == "AGENTS.md":
85
+ return (
86
+ mandatory_entrypoint_line(manifest),
87
+ "agentic-kit command-for",
88
+ ack,
89
+ )
90
+ return (
91
+ ack,
92
+ COMMAND_REFERENCE_JSON,
93
+ COMMAND_REFERENCE_MARKDOWN,
94
+ "agentic-kit command-for",
95
+ "must_not_reconstruct_commands_from_memory",
96
+ "most specific available Kit workflow command",
97
+ "raw git/gh commands with a mapped wrapper are rejected by instruction lint",
98
+ )
99
+
100
+
101
+ def _audit_text_surface(root: Path, path: str, manifest: dict[str, Any]) -> list[CommandAuthorityFinding]:
102
+ target = root / path
103
+ if not target.exists():
104
+ return [_finding("COMMAND_AUTHORITY_SURFACE_MISSING", path, "required command authority surface is missing")]
105
+ text = target.read_text(encoding="utf-8")
106
+ findings: list[CommandAuthorityFinding] = []
107
+ for term in _required_text_terms(path, manifest):
108
+ if term not in text:
109
+ findings.append(
110
+ _finding(
111
+ "COMMAND_AUTHORITY_TERM_MISSING",
112
+ path,
113
+ f"required command authority term is missing: {term}",
114
+ )
115
+ )
116
+ return findings
117
+
118
+
119
+ def _audit_execution_contract(root: Path, manifest: dict[str, Any]) -> list[CommandAuthorityFinding]:
120
+ path = EXECUTION_CONTRACT_SURFACE
121
+ target = root / path
122
+ if not target.exists():
123
+ return [_finding("COMMAND_AUTHORITY_SURFACE_MISSING", path, "execution contract is missing")]
124
+ try:
125
+ payload = json.loads(target.read_text(encoding="utf-8"))
126
+ except json.JSONDecodeError as exc:
127
+ return [_finding("COMMAND_AUTHORITY_JSON_INVALID", path, f"execution contract is invalid JSON: {exc}")]
128
+
129
+ context = payload.get("llm_execution_context") if isinstance(payload.get("llm_execution_context"), dict) else payload
130
+ command_reference = (
131
+ context.get("command_reference")
132
+ if isinstance(context, dict) and isinstance(context.get("command_reference"), dict)
133
+ else {}
134
+ )
135
+ expected_sha = _manifest_sha(manifest)
136
+ expected_ack = command_manifest_ack_line(manifest)
137
+ required_values = {
138
+ "json": COMMAND_REFERENCE_JSON,
139
+ "markdown": COMMAND_REFERENCE_MARKDOWN,
140
+ "manifest_sha": expected_sha,
141
+ "ack": expected_ack,
142
+ "must_not_reconstruct_commands_from_memory": True,
143
+ }
144
+ findings: list[CommandAuthorityFinding] = []
145
+ for key, expected in required_values.items():
146
+ if command_reference.get(key) != expected:
147
+ findings.append(
148
+ _finding(
149
+ "COMMAND_AUTHORITY_CONTRACT_MISMATCH",
150
+ path,
151
+ f"command_reference.{key} must be {expected!r}",
152
+ )
153
+ )
154
+ source_hashes = command_reference.get("source_hashes")
155
+ if not isinstance(source_hashes, dict):
156
+ findings.append(
157
+ _finding("COMMAND_AUTHORITY_SOURCE_HASHES_MISSING", path, "command_reference.source_hashes must be present")
158
+ )
159
+ else:
160
+ for source in (COMMAND_REFERENCE_JSON, COMMAND_REFERENCE_MARKDOWN):
161
+ if source not in source_hashes:
162
+ findings.append(
163
+ _finding("COMMAND_AUTHORITY_SOURCE_HASH_MISSING", path, f"missing source hash for {source}")
164
+ )
165
+ return findings
166
+
167
+
168
+ def evaluate_command_authority(root: Path = Path(".")) -> CommandAuthorityAudit:
169
+ root = root.resolve()
170
+ manifest = load_command_manifest(root)
171
+ findings: list[CommandAuthorityFinding] = []
172
+ for path in TEXT_COMMAND_AUTHORITY_SURFACES:
173
+ findings.extend(_audit_text_surface(root, path, manifest))
174
+ findings.extend(_audit_execution_contract(root, manifest))
175
+ return CommandAuthorityAudit(
176
+ root=root.as_posix(),
177
+ manifest_sha=_manifest_sha(manifest),
178
+ findings=tuple(findings),
179
+ )
180
+
181
+
182
+ def render_command_authority_audit(audit: CommandAuthorityAudit) -> str:
183
+ lines = [
184
+ "COMMAND_AUTHORITY_AUDIT",
185
+ f"STATUS={audit.status}",
186
+ f"MANIFEST_SHA={audit.manifest_sha}",
187
+ f"FINDING_COUNT={len(audit.findings)}",
188
+ f"BLOCKER_COUNT={len(audit.blockers)}",
189
+ ]
190
+ for finding in audit.findings:
191
+ lines.append(f"FINDING={finding.severity}|{finding.code}|{finding.path}|{finding.message}")
192
+ return "\n".join(lines) + "\n"
@@ -0,0 +1,103 @@
1
+ from __future__ import annotations
2
+
3
+ import subprocess
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+
7
+ from agentic_project_kit.agent_command_runner import ALLOWED_SAFETY_CLASSES, EXECUTED_JSONL, INBOX_DIR, REPORT_DIR, _parse_simple_yaml, normalize_safety_class
8
+
9
+ FORBIDDEN_SCRIPT_FRAGMENTS = (
10
+ "<<",
11
+ "git switch ",
12
+ "git checkout ",
13
+ "git pull ",
14
+ "logout",
15
+ "kill ",
16
+ "exec ",
17
+ )
18
+
19
+ @dataclass(frozen=True)
20
+ class InboxCheckResult:
21
+ ok: bool
22
+ findings: tuple[str, ...]
23
+
24
+ def _pending_files(inbox_dir: Path) -> tuple[list[Path], list[Path]]:
25
+ if not inbox_dir.exists():
26
+ return [], []
27
+ return sorted(inbox_dir.glob("*.yaml")), sorted(inbox_dir.glob("*.sh"))
28
+
29
+ def completed_command_ids(report_dir: Path = REPORT_DIR, executed_jsonl: Path = EXECUTED_JSONL) -> set[str]:
30
+ ids: set[str] = set()
31
+ if report_dir.exists():
32
+ for path in report_dir.glob("*.md"):
33
+ if path.name != "LATEST_COMMAND_RUN.txt":
34
+ ids.add(path.stem)
35
+ if executed_jsonl.exists():
36
+ for line in executed_jsonl.read_text(encoding="utf-8").splitlines():
37
+ if "\"command_id\"" not in line:
38
+ continue
39
+ _, _, after = line.partition("\"command_id\"")
40
+ _, _, tail = after.partition(":")
41
+ value = tail.strip().lstrip("\"").split("\"", 1)[0]
42
+ if value:
43
+ ids.add(value)
44
+ return ids
45
+
46
+ def check_command_inbox(inbox_dir: Path = INBOX_DIR) -> InboxCheckResult:
47
+ findings: list[str] = []
48
+ yaml_files, script_files = _pending_files(inbox_dir)
49
+ yaml_stems = {path.stem for path in yaml_files}
50
+ script_stems = {path.stem for path in script_files}
51
+ for stem in sorted(yaml_stems - script_stems):
52
+ findings.append(f"orphan metadata without script: {stem}.yaml")
53
+ for stem in sorted(script_stems - yaml_stems):
54
+ findings.append(f"orphan script without metadata: {stem}.sh")
55
+ complete = sorted(yaml_stems & script_stems)
56
+ if len(complete) > 1:
57
+ findings.append("multiple complete pending commands: " + ", ".join(complete))
58
+ completed_ids = completed_command_ids(report_dir=REPORT_DIR, executed_jsonl=EXECUTED_JSONL)
59
+ seen_ids: set[str] = set()
60
+ for stem in complete:
61
+ yaml_path = inbox_dir / f"{stem}.yaml"
62
+ script_path = inbox_dir / f"{stem}.sh"
63
+ try:
64
+ data = _parse_simple_yaml(yaml_path)
65
+ except ValueError as exc:
66
+ findings.append(f"{yaml_path.as_posix()}: invalid metadata: {exc}")
67
+ continue
68
+ command_id = data.get("command_id", "")
69
+ if not command_id:
70
+ findings.append(f"{yaml_path.as_posix()}: missing command_id")
71
+ elif command_id in seen_ids:
72
+ findings.append(f"duplicate command_id: {command_id}")
73
+ else:
74
+ seen_ids.add(command_id)
75
+ if command_id in completed_ids:
76
+ findings.append(f"completed command still pending: {command_id}")
77
+ if not data.get("title", ""):
78
+ findings.append(f"{yaml_path.as_posix()}: missing title")
79
+ safety_class = normalize_safety_class(data.get("safety_class", ""))
80
+ if safety_class not in ALLOWED_SAFETY_CLASSES:
81
+ findings.append(f"{yaml_path.as_posix()}: unsupported safety_class: {safety_class}")
82
+ syntax = subprocess.run(["sh", "-n", script_path.as_posix()], text=True, capture_output=True, check=False)
83
+ if syntax.returncode != 0:
84
+ detail = syntax.stderr.strip() or syntax.stdout.strip()
85
+ findings.append(f"{script_path.as_posix()}: shell syntax failed: {detail}")
86
+ script_text = script_path.read_text(encoding="utf-8")
87
+ for fragment in FORBIDDEN_SCRIPT_FRAGMENTS:
88
+ if fragment in script_text:
89
+ findings.append(f"{script_path.as_posix()}: forbidden fragment: {fragment}")
90
+ return InboxCheckResult(ok=not findings, findings=tuple(findings))
91
+
92
+ def main() -> int:
93
+ result = check_command_inbox()
94
+ if result.ok:
95
+ print("PASS_COMMAND_INBOX_CHECK")
96
+ return 0
97
+ print("FAIL_COMMAND_INBOX_CHECK")
98
+ for finding in result.findings:
99
+ print(finding)
100
+ return 1
101
+
102
+ if __name__ == "__main__":
103
+ raise SystemExit(main())