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,379 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ import tomllib
5
+ from dataclasses import dataclass
6
+ from enum import Enum
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from agentic_project_kit.checks import check_docs, check_todo
11
+ from agentic_project_kit.doc_lifecycle import build_doc_lifecycle_report
12
+ from agentic_project_kit.standard_gates_audit_suite import evaluate_standard_gates_audit_suite
13
+ from agentic_project_kit.contract import (
14
+ CONTRACT_PATH,
15
+ contract_summary,
16
+ load_project_contract,
17
+ validate_project_contract,
18
+ )
19
+ from agentic_project_kit.workspace import (
20
+ SUPPORTED_MANIFEST_SCHEMA_VERSION,
21
+ Workspace,
22
+ load_workspace,
23
+ )
24
+
25
+
26
+ class DoctorStatus(str, Enum):
27
+ PASS = "PASS"
28
+ FAIL = "FAIL"
29
+ WARN = "WARN"
30
+ SKIP = "SKIP"
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class DoctorCheck:
35
+ name: str
36
+ status: DoctorStatus
37
+ detail: str
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class DoctorReport:
42
+ project_root: Path
43
+ checks: list[DoctorCheck]
44
+
45
+ @property
46
+ def ok(self) -> bool:
47
+ return all(check.status is not DoctorStatus.FAIL for check in self.checks)
48
+
49
+
50
+ def build_doctor_report(project_root: Path) -> DoctorReport:
51
+ """Build a compact health report for an agentic project checkout."""
52
+ root = project_root.resolve()
53
+ contract_data = _load_contract_for_doctor(root)
54
+ workspace = _load_manifest_workspace_for_doctor(root)
55
+ external_manifest_workspace = (
56
+ isinstance(workspace, Workspace)
57
+ and not _is_agentic_project_kit_development_checkout(root)
58
+ )
59
+ checks = [
60
+ _path_check(root, "pyproject.toml", required=False),
61
+ _path_check(root, "README.md", required=not external_manifest_workspace),
62
+ _path_check(root, "sentinel.yaml", required=False),
63
+ _path_check(root, ".github/workflows/ci.yml", required=False),
64
+ _workspace_manifest_check(workspace),
65
+ _workspace_schema_currency_check(workspace),
66
+ _project_contract_check(root, contract_data, external_manifest_workspace=external_manifest_workspace),
67
+ _policy_pack_check(root, contract_data, external_manifest_workspace=external_manifest_workspace),
68
+ _docs_check(root),
69
+ _doc_lifecycle_check(root),
70
+ _todo_check(root, workspace),
71
+ _standard_gates_audit_suite_check(root),
72
+ _version_drift_check(root, external_manifest_workspace=external_manifest_workspace),
73
+ ]
74
+ return DoctorReport(project_root=root, checks=checks)
75
+
76
+
77
+ def render_doctor_report(report: DoctorReport) -> str:
78
+ lines = [f"Agentic project doctor report for {report.project_root}", ""]
79
+ for check in report.checks:
80
+ lines.append(f"[{check.status.value}] {check.name}: {check.detail}")
81
+ lines.extend(["", f"Overall: {'PASS' if report.ok else 'FAIL'}"])
82
+ return "\n".join(lines)
83
+
84
+
85
+ def _path_check(project_root: Path, relative_path: str, *, required: bool) -> DoctorCheck:
86
+ path = project_root / relative_path
87
+ if path.exists():
88
+ return DoctorCheck(relative_path, DoctorStatus.PASS, "present")
89
+ if required:
90
+ return DoctorCheck(relative_path, DoctorStatus.FAIL, "missing")
91
+ return DoctorCheck(relative_path, DoctorStatus.WARN, "missing optional project file")
92
+
93
+
94
+ def _load_contract_for_doctor(project_root: Path) -> dict[str, Any] | None | ValueError:
95
+ try:
96
+ return load_project_contract(project_root)
97
+ except ValueError as exc:
98
+ return exc
99
+
100
+
101
+ def _load_manifest_workspace_for_doctor(project_root: Path) -> Workspace | None | ValueError:
102
+ if not (project_root / ".agentic/config.yaml").exists():
103
+ return None
104
+ try:
105
+ return load_workspace(project_root, suppress_legacy_profile_warning=True)
106
+ except RuntimeError as exc:
107
+ return ValueError(str(exc))
108
+
109
+
110
+ def _workspace_manifest_check(data: Workspace | None | ValueError) -> DoctorCheck:
111
+ if isinstance(data, ValueError):
112
+ return DoctorCheck("workspace manifest", DoctorStatus.FAIL, str(data))
113
+ if data is None:
114
+ return DoctorCheck("workspace manifest", DoctorStatus.WARN, ".agentic/config.yaml absent")
115
+ detail = (
116
+ f"{data.project_name or 'unnamed'}; type: {data.project_type}; "
117
+ f"profile: {data.profile}; transfer: {data.transfer_visibility}"
118
+ )
119
+ return DoctorCheck("workspace manifest", DoctorStatus.PASS, detail)
120
+
121
+
122
+ def _workspace_schema_currency_check(data: Workspace | None | ValueError) -> DoctorCheck:
123
+ if isinstance(data, ValueError):
124
+ return DoctorCheck(
125
+ "workspace schema",
126
+ DoctorStatus.WARN,
127
+ "skipped because workspace manifest is invalid",
128
+ )
129
+ if data is None:
130
+ return DoctorCheck("workspace schema", DoctorStatus.WARN, ".agentic/config.yaml absent")
131
+ if data.manifest_schema_version < SUPPORTED_MANIFEST_SCHEMA_VERSION:
132
+ return DoctorCheck(
133
+ "workspace schema",
134
+ DoctorStatus.WARN,
135
+ (
136
+ f"manifest schema v{data.manifest_schema_version} is older than "
137
+ f"supported v{SUPPORTED_MANIFEST_SCHEMA_VERSION}; run "
138
+ "`agentic-kit workspace upgrade --root PATH`"
139
+ ),
140
+ )
141
+ return DoctorCheck(
142
+ "workspace schema",
143
+ DoctorStatus.PASS,
144
+ f"manifest schema v{data.manifest_schema_version} is current",
145
+ )
146
+
147
+
148
+ def _project_contract_check(
149
+ project_root: Path,
150
+ data: dict[str, Any] | None | ValueError,
151
+ *,
152
+ external_manifest_workspace: bool = False,
153
+ ) -> DoctorCheck:
154
+ if isinstance(data, ValueError):
155
+ return DoctorCheck("project contract", DoctorStatus.FAIL, str(data))
156
+ if data is None:
157
+ if external_manifest_workspace:
158
+ return DoctorCheck(
159
+ "project contract",
160
+ DoctorStatus.SKIP,
161
+ f"{CONTRACT_PATH} absent; external workspace uses .agentic/config.yaml",
162
+ )
163
+ return DoctorCheck("project contract", DoctorStatus.WARN, f"{CONTRACT_PATH} absent")
164
+ errors = validate_project_contract(data)
165
+ if errors:
166
+ return DoctorCheck("project contract", DoctorStatus.FAIL, "; ".join(errors))
167
+ return DoctorCheck("project contract", DoctorStatus.PASS, contract_summary(data))
168
+
169
+
170
+ def _policy_pack_check(
171
+ project_root: Path,
172
+ data: dict[str, Any] | None | ValueError,
173
+ *,
174
+ external_manifest_workspace: bool = False,
175
+ ) -> DoctorCheck:
176
+ if isinstance(data, ValueError):
177
+ return DoctorCheck("policy pack checks", DoctorStatus.WARN, "skipped because project contract is invalid")
178
+ if data is None:
179
+ if external_manifest_workspace:
180
+ return DoctorCheck(
181
+ "policy pack checks",
182
+ DoctorStatus.SKIP,
183
+ f"skipped because {CONTRACT_PATH} is absent in external workspace",
184
+ )
185
+ return DoctorCheck("policy pack checks", DoctorStatus.WARN, f"skipped because {CONTRACT_PATH} is absent")
186
+
187
+ contract_errors = validate_project_contract(data)
188
+ if contract_errors:
189
+ return DoctorCheck("policy pack checks", DoctorStatus.WARN, "skipped because project contract failed validation")
190
+
191
+ policy_packs = _contract_string_list(data, "policy_packs")
192
+ failures: list[str] = []
193
+ passed: list[str] = []
194
+
195
+ for policy_pack in policy_packs:
196
+ errors = _policy_pack_errors(project_root, policy_pack)
197
+ if errors:
198
+ failures.extend(f"{policy_pack}: {error}" for error in errors)
199
+ else:
200
+ passed.append(policy_pack)
201
+
202
+ if failures:
203
+ return DoctorCheck("policy pack checks", DoctorStatus.FAIL, "; ".join(failures))
204
+ if not passed:
205
+ return DoctorCheck("policy pack checks", DoctorStatus.WARN, "no policy packs selected")
206
+ return DoctorCheck("policy pack checks", DoctorStatus.PASS, "active: " + ", ".join(passed))
207
+
208
+
209
+ def _policy_pack_errors(project_root: Path, policy_pack: str) -> list[str]:
210
+ checks: dict[str, tuple[str, ...]] = {
211
+ "starter": ("README.md", "AGENTS.md", "docs/STATUS.md"),
212
+ "prototype": ("README.md", "docs/STATUS.md"),
213
+ "solo-maintainer": (
214
+ "docs/STATUS.md",
215
+ "docs/handoff/CURRENT_HANDOFF.md",
216
+ "sentinel.yaml",
217
+ ".agentic/todo.yaml",
218
+ ),
219
+ "agentic-development": (
220
+ "AGENTS.md",
221
+ "docs/TEST_GATES.md",
222
+ "docs/handoff/CURRENT_HANDOFF.md",
223
+ "docs/architecture/ARCHITECTURE_CONTRACT.md",
224
+ ),
225
+ "release-managed": ("CHANGELOG.md", "CITATION.cff", ".zenodo.json"),
226
+ "documentation-governed": (
227
+ "docs/DOCUMENTATION_COVERAGE.yaml",
228
+ "docs/architecture/ARCHITECTURE_CONTRACT.md",
229
+ ),
230
+ }
231
+ required_paths = checks.get(policy_pack, ())
232
+ return [f"missing {path}" for path in required_paths if not (project_root / path).exists()]
233
+
234
+
235
+ def _docs_check(project_root: Path) -> DoctorCheck:
236
+ errors = check_docs(project_root)
237
+ if errors:
238
+ return DoctorCheck("documentation gates", DoctorStatus.FAIL, "; ".join(errors))
239
+ return DoctorCheck("documentation gates", DoctorStatus.PASS, "passed")
240
+
241
+
242
+ def _doc_lifecycle_check(project_root: Path) -> DoctorCheck:
243
+ report = build_doc_lifecycle_report(project_root)
244
+ blockers = [finding for finding in report.findings if finding.severity in {"FAIL", "BLOCK"}]
245
+ if blockers:
246
+ details = "; ".join(f"{finding.path}: {finding.message}" for finding in blockers)
247
+ return DoctorCheck("document lifecycle audit", DoctorStatus.FAIL, details)
248
+ if report.findings:
249
+ return DoctorCheck(
250
+ "document lifecycle audit",
251
+ DoctorStatus.WARN,
252
+ f"{len(report.findings)} report-only finding(s)",
253
+ )
254
+ return DoctorCheck("document lifecycle audit", DoctorStatus.PASS, "passed")
255
+
256
+
257
+ def _todo_check(project_root: Path, workspace: Workspace | None | ValueError = None) -> DoctorCheck:
258
+ sentinel_path = project_root / "sentinel.yaml"
259
+ if not sentinel_path.exists():
260
+ if isinstance(workspace, Workspace):
261
+ return DoctorCheck(
262
+ "todo gates",
263
+ DoctorStatus.SKIP,
264
+ "workspace manifest present; sentinel.yaml absent; skipped TODO validation",
265
+ )
266
+ return DoctorCheck("todo gates", DoctorStatus.WARN, "sentinel.yaml absent; skipped TODO validation")
267
+ errors = check_todo(project_root)
268
+ if errors:
269
+ return DoctorCheck("todo gates", DoctorStatus.FAIL, "; ".join(errors))
270
+ return DoctorCheck("todo gates", DoctorStatus.PASS, "passed")
271
+
272
+
273
+ def _version_drift_check(project_root: Path, *, external_manifest_workspace: bool = False) -> DoctorCheck:
274
+ if external_manifest_workspace:
275
+ return DoctorCheck(
276
+ "version drift",
277
+ DoctorStatus.SKIP,
278
+ "skipped for external manifest workspace; version governance remains project-owned",
279
+ )
280
+
281
+ version = _read_pyproject_version(project_root / "pyproject.toml")
282
+ if version is None:
283
+ return DoctorCheck("version drift", DoctorStatus.WARN, "pyproject.toml absent or version unavailable")
284
+
285
+ missing: list[str] = []
286
+ current_text = f"Current version: {version}"
287
+ changelog_text = f"v{version}"
288
+
289
+ if not _file_contains(project_root / "docs/STATUS.md", current_text):
290
+ missing.append("docs/STATUS.md")
291
+ if not _file_contains(project_root / "docs/handoff/CURRENT_HANDOFF.md", current_text):
292
+ missing.append("docs/handoff/CURRENT_HANDOFF.md")
293
+ if not _file_contains(project_root / "CHANGELOG.md", changelog_text):
294
+ missing.append("CHANGELOG.md")
295
+
296
+ citation_path = project_root / "CITATION.cff"
297
+ if citation_path.exists() and not _citation_version_matches(citation_path, version):
298
+ missing.append("CITATION.cff")
299
+
300
+ init_path = project_root / "src/agentic_project_kit/__init__.py"
301
+ init_version = _read_package_init_version(init_path)
302
+ if init_path.exists() and init_version != version:
303
+ missing.append("src/agentic_project_kit/__init__.py")
304
+
305
+ if missing:
306
+ return DoctorCheck("version drift", DoctorStatus.FAIL, "version mismatch in: " + ", ".join(missing))
307
+ return DoctorCheck("version drift", DoctorStatus.PASS, f"project state matches version {version}")
308
+
309
+
310
+
311
+ def _standard_gates_audit_suite_check(project_root: Path) -> DoctorCheck:
312
+ if not _is_agentic_project_kit_development_checkout(project_root):
313
+ return DoctorCheck(
314
+ "standard audit suite",
315
+ DoctorStatus.SKIP,
316
+ "skipped outside the agentic-project-kit development checkout",
317
+ )
318
+ try:
319
+ result = evaluate_standard_gates_audit_suite(project_root)
320
+ except FileNotFoundError as exc:
321
+ return DoctorCheck(
322
+ "standard audit suite",
323
+ DoctorStatus.WARN,
324
+ f"skipped because agentic-kit executable is unavailable: {exc}",
325
+ )
326
+ if result.ok:
327
+ return DoctorCheck("standard audit suite", DoctorStatus.PASS, "passed")
328
+ blockers = "; ".join(
329
+ f"{blocker.name}: {blocker.detail}" for blocker in result.blockers
330
+ )
331
+ return DoctorCheck("standard audit suite", DoctorStatus.FAIL, blockers)
332
+
333
+
334
+ def _is_agentic_project_kit_development_checkout(project_root: Path) -> bool:
335
+ return (
336
+ (project_root / "src" / "agentic_project_kit").is_dir()
337
+ and (project_root / "docs" / "reference" / "agentic-kit-commands.json").exists()
338
+ and (project_root / "pyproject.toml").exists()
339
+ )
340
+
341
+ def _read_pyproject_version(path: Path) -> str | None:
342
+ if not path.exists():
343
+ return None
344
+ data = tomllib.loads(path.read_text(encoding="utf-8"))
345
+ project = data.get("project", {})
346
+ version = project.get("version")
347
+ if isinstance(version, str) and version:
348
+ return version
349
+ return None
350
+
351
+
352
+ def _read_package_init_version(path: Path) -> str | None:
353
+ if not path.exists():
354
+ return None
355
+ match = re.search(r'^__version__\s*=\s*["\']([^"\']+)["\']', path.read_text(encoding="utf-8"), re.MULTILINE)
356
+ if match:
357
+ return match.group(1)
358
+ return None
359
+
360
+
361
+ def _file_contains(path: Path, needle: str) -> bool:
362
+ return path.exists() and needle in path.read_text(encoding="utf-8")
363
+
364
+
365
+ def _citation_version_matches(path: Path, version: str) -> bool:
366
+ text = path.read_text(encoding="utf-8")
367
+ accepted = (
368
+ f"version: {version}",
369
+ f'version: "{version}"',
370
+ f"version: '{version}'",
371
+ )
372
+ return any(item in text for item in accepted)
373
+
374
+
375
+ def _contract_string_list(data: dict[str, Any], field_name: str) -> tuple[str, ...]:
376
+ value = data.get(field_name)
377
+ if not isinstance(value, list):
378
+ return ()
379
+ return tuple(item for item in value if isinstance(item, str) and item.strip())