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,840 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ import json
5
+ from pathlib import Path
6
+ import re
7
+ from typing import Any, Literal
8
+
9
+ try:
10
+ import tomllib
11
+ except ModuleNotFoundError: # pragma: no cover - Python 3.10 fallback
12
+ tomllib = None # type: ignore[assignment]
13
+
14
+ import yaml
15
+
16
+ from agentic_project_kit.workspace import KitConfig, load_workspace
17
+
18
+ _DEFAULT_CONFIG = KitConfig()
19
+ PROJECT_DIRECTION_PATH = Path(_DEFAULT_CONFIG.planning_root) / _DEFAULT_CONFIG.project_direction_file
20
+ VALID_SECTIONS = ("all", "strategy", "roadmap", "plans", "ideas", "done", "discarded")
21
+ VALID_FORMATS = ("text", "markdown", "json")
22
+ ALLOWED_TOP_LEVEL_KEYS = frozenset(
23
+ {"schema_version", "meta", "strategy", "roadmap", "plans", "ideas", "done", "discarded"}
24
+ )
25
+ SECTION_STATUS_VALUES = {
26
+ "strategy": frozenset({"active", "superseded", "done", "discarded"}),
27
+ "roadmap": frozenset({"next", "planned", "blocked", "done", "discarded"}),
28
+ "plans": frozenset({"active", "planned", "blocked", "done", "discarded"}),
29
+ "ideas": frozenset({"candidate", "accepted", "rejected", "superseded"}),
30
+ }
31
+ ACTIVE_STATUSES = frozenset({"active", "next", "planned", "blocked", "candidate", "accepted"})
32
+ UPDATED_AFTER_PR_SEMANTICS = frozenset({"strategic_direction_refresh"})
33
+ PLANNING_SCAN_ROOTS = (
34
+ Path(_DEFAULT_CONFIG.docs_root) / "strategy",
35
+ Path(_DEFAULT_CONFIG.planning_root),
36
+ Path(_DEFAULT_CONFIG.docs_root) / "plans",
37
+ Path(_DEFAULT_CONFIG.docs_root) / "ideas",
38
+ Path(_DEFAULT_CONFIG.docs_root) / "roadmap",
39
+ )
40
+ CANONICAL_DIRECTION_FILES = {
41
+ "docs/planning/PROJECT_DIRECTION.yaml",
42
+ "docs/planning/PROJECT_DIRECTION.md",
43
+ }
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class ProjectDirection:
48
+ data: dict[str, Any]
49
+ path: Path
50
+ authority_path: str = PROJECT_DIRECTION_PATH.as_posix()
51
+
52
+ def validate(self) -> list[str]:
53
+ result = validate_project_direction_data(
54
+ self.data,
55
+ root=self.path.parent.parent.parent,
56
+ authority_path=self.authority_path,
57
+ )
58
+ return [finding.message for finding in result.findings]
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class DirectionFinding:
63
+ code: str
64
+ message: str
65
+ path: str = "docs/planning/PROJECT_DIRECTION.yaml"
66
+
67
+ def as_dict(self) -> dict[str, str]:
68
+ return {"code": self.code, "message": self.message, "path": self.path}
69
+
70
+
71
+ @dataclass(frozen=True)
72
+ class DirectionValidationResult:
73
+ path: str
74
+ findings: tuple[DirectionFinding, ...]
75
+
76
+ @property
77
+ def ok(self) -> bool:
78
+ return not self.findings
79
+
80
+ @property
81
+ def status(self) -> str:
82
+ return "PASS" if self.ok else "FAIL"
83
+
84
+ @property
85
+ def returncode(self) -> int:
86
+ return 0 if self.ok else 1
87
+
88
+ def as_dict(self) -> dict[str, object]:
89
+ return {
90
+ "schema_version": 1,
91
+ "kind": "project_direction_validation",
92
+ "status": self.status,
93
+ "path": self.path,
94
+ "finding_count": len(self.findings),
95
+ "findings": [finding.as_dict() for finding in self.findings],
96
+ }
97
+
98
+
99
+ @dataclass(frozen=True)
100
+ class DirectionDriftRecord:
101
+ path: str
102
+ classification: str
103
+ recommendation: str
104
+ in_source_files: bool
105
+ reference_count: int
106
+ item_id: str | None = None
107
+ item_status: str | None = None
108
+
109
+ def as_dict(self) -> dict[str, object]:
110
+ data: dict[str, object] = {
111
+ "path": self.path,
112
+ "classification": self.classification,
113
+ "recommendation": self.recommendation,
114
+ "in_source_files": self.in_source_files,
115
+ "reference_count": self.reference_count,
116
+ }
117
+ if self.item_id is not None:
118
+ data["item_id"] = self.item_id
119
+ if self.item_status is not None:
120
+ data["item_status"] = self.item_status
121
+ return data
122
+
123
+
124
+ @dataclass(frozen=True)
125
+ class DirectionDriftAuditResult:
126
+ root: str
127
+ records: tuple[DirectionDriftRecord, ...]
128
+ missing_source_files: tuple[str, ...]
129
+
130
+ @property
131
+ def ok(self) -> bool:
132
+ return True
133
+
134
+ @property
135
+ def status(self) -> str:
136
+ return "PASS"
137
+
138
+ @property
139
+ def returncode(self) -> int:
140
+ return 0
141
+
142
+ def as_dict(self) -> dict[str, object]:
143
+ return {
144
+ "schema_version": 1,
145
+ "kind": "project_direction_drift_audit",
146
+ "root": self.root,
147
+ "status": self.status,
148
+ "record_count": len(self.records),
149
+ "missing_source_file_count": len(self.missing_source_files),
150
+ "missing_source_files": list(self.missing_source_files),
151
+ "records": [record.as_dict() for record in self.records],
152
+ }
153
+
154
+
155
+ def load_project_direction(root: Path | str = ".") -> ProjectDirection:
156
+ base = Path(root)
157
+ path = load_workspace(base).project_direction_path()
158
+ raw = path.read_text(encoding="utf-8")
159
+ data = yaml.safe_load(raw)
160
+ if not isinstance(data, dict):
161
+ raise ValueError(f"{PROJECT_DIRECTION_PATH.as_posix()} must contain a YAML mapping")
162
+ try:
163
+ authority_path = path.relative_to(base).as_posix()
164
+ except ValueError:
165
+ authority_path = PROJECT_DIRECTION_PATH.as_posix()
166
+ return ProjectDirection(data=data, path=path, authority_path=authority_path)
167
+
168
+
169
+ def validate_project_direction(
170
+ root: Path | str = ".",
171
+ *,
172
+ strict_planning_files: bool = False,
173
+ ) -> DirectionValidationResult:
174
+ direction = load_project_direction(root)
175
+ return validate_project_direction_data(
176
+ direction.data,
177
+ root=Path(root),
178
+ authority_path=direction.authority_path,
179
+ strict_planning_files=strict_planning_files,
180
+ )
181
+
182
+
183
+ def validate_project_direction_data(
184
+ data: dict[str, Any],
185
+ *,
186
+ root: Path,
187
+ authority_path: str = PROJECT_DIRECTION_PATH.as_posix(),
188
+ strict_planning_files: bool = False,
189
+ ) -> DirectionValidationResult:
190
+ findings: list[DirectionFinding] = []
191
+ root = Path(root)
192
+
193
+ for key in data:
194
+ if key not in ALLOWED_TOP_LEVEL_KEYS:
195
+ findings.append(DirectionFinding("unknown-top-level-key", f"unknown top-level key: {key}"))
196
+ for key in ALLOWED_TOP_LEVEL_KEYS:
197
+ if key not in data:
198
+ findings.append(DirectionFinding("missing-required-key", f"missing required key: {key}"))
199
+ if data.get("schema_version") != 1:
200
+ findings.append(DirectionFinding("invalid-schema-version", "schema_version must be 1"))
201
+
202
+ meta = data.get("meta")
203
+ if not isinstance(meta, dict):
204
+ findings.append(DirectionFinding("invalid-meta", "meta must be a mapping"))
205
+ else:
206
+ if meta.get("status") != "active":
207
+ findings.append(DirectionFinding("invalid-meta-status", "meta.status must be active"))
208
+ if meta.get("authority") != authority_path:
209
+ findings.append(
210
+ DirectionFinding("invalid-authority", f"meta.authority must be {authority_path}")
211
+ )
212
+ if meta.get("updated_after_pr") is not None:
213
+ semantics = meta.get("updated_after_pr_semantics")
214
+ if semantics not in UPDATED_AFTER_PR_SEMANTICS:
215
+ findings.append(
216
+ DirectionFinding(
217
+ "invalid-updated-after-pr-semantics",
218
+ "meta.updated_after_pr_semantics must be strategic_direction_refresh "
219
+ "when meta.updated_after_pr is set",
220
+ )
221
+ )
222
+ if meta.get("updated_after_pr_current_main_claimed") is not False:
223
+ findings.append(
224
+ DirectionFinding(
225
+ "invalid-updated-after-pr-current-main-claim",
226
+ "meta.updated_after_pr_current_main_claimed must be false; "
227
+ "PROJECT_DIRECTION updated_after_pr is not a current-main freshness claim",
228
+ )
229
+ )
230
+
231
+ ids_by_section: dict[str, str] = {}
232
+ dependency_checks: list[tuple[str, str]] = []
233
+ source_files = _collect_source_file_entries(data)
234
+ _validate_no_private_absolute_paths(data, findings)
235
+ current_release = _read_project_version(root)
236
+
237
+ for section in ("strategy", "roadmap", "plans", "ideas", "done", "discarded"):
238
+ raw_items = data.get(section)
239
+ if not isinstance(raw_items, list):
240
+ findings.append(DirectionFinding("invalid-section", f"{section} must be a list"))
241
+ continue
242
+ for index, item in enumerate(raw_items):
243
+ path = f"{section}[{index}]"
244
+ if not isinstance(item, dict):
245
+ findings.append(DirectionFinding("invalid-item", f"{path} must be a mapping"))
246
+ continue
247
+ item_id = str(item.get("id") or "").strip()
248
+ if not item_id:
249
+ findings.append(DirectionFinding("missing-id", f"{path}.id must not be empty"))
250
+ elif item_id in ids_by_section:
251
+ findings.append(
252
+ DirectionFinding(
253
+ "duplicate-id",
254
+ f"id {item_id!r} appears in both {ids_by_section[item_id]} and {path}",
255
+ )
256
+ )
257
+ else:
258
+ ids_by_section[item_id] = path
259
+ if section in SECTION_STATUS_VALUES:
260
+ status = str(item.get("status") or "").strip()
261
+ allowed = SECTION_STATUS_VALUES[section]
262
+ if status not in allowed:
263
+ findings.append(
264
+ DirectionFinding(
265
+ "invalid-status",
266
+ f"{path}.status must be one of {', '.join(sorted(allowed))}",
267
+ )
268
+ )
269
+ if status in ACTIVE_STATUSES and not str(item.get("title") or "").strip():
270
+ findings.append(DirectionFinding("empty-active-title", f"{path}.title must not be empty"))
271
+ _validate_target_release_currency(
272
+ item,
273
+ path,
274
+ status=status,
275
+ current_release=current_release,
276
+ findings=findings,
277
+ )
278
+ if section in {"roadmap", "plans"}:
279
+ for dependency in _string_list(item.get("depends_on"), f"{path}.depends_on", findings):
280
+ dependency_checks.append((path, dependency))
281
+ if section == "done":
282
+ if item.get("completed_by_pr") is None and not str(item.get("completion_exception") or "").strip():
283
+ findings.append(
284
+ DirectionFinding(
285
+ "done-missing-completion",
286
+ f"{path} needs completed_by_pr or completion_exception",
287
+ )
288
+ )
289
+ if section == "discarded" and not str(item.get("reason") or "").strip():
290
+ findings.append(DirectionFinding("discarded-missing-reason", f"{path}.reason must not be empty"))
291
+ _validate_item_sources(item, path, root, findings)
292
+ _validate_item_evidence(item, path, root, findings)
293
+
294
+ for path, dependency in dependency_checks:
295
+ if dependency not in ids_by_section:
296
+ findings.append(
297
+ DirectionFinding("unknown-dependency", f"{path}.depends_on references unknown id {dependency!r}")
298
+ )
299
+
300
+ if strict_planning_files:
301
+ referenced = {entry for entry in source_files if isinstance(entry, str)}
302
+ for candidate in _iter_planning_files(root):
303
+ if candidate in CANONICAL_DIRECTION_FILES:
304
+ continue
305
+ if candidate.startswith("docs/planning/") and candidate not in referenced:
306
+ findings.append(
307
+ DirectionFinding(
308
+ "forbidden-free-planning-file",
309
+ f"{candidate} is not a canonical direction file or referenced source",
310
+ )
311
+ )
312
+
313
+ return DirectionValidationResult(path=authority_path, findings=tuple(findings))
314
+
315
+
316
+ def render_project_direction(
317
+ direction: ProjectDirection,
318
+ *,
319
+ section: Literal["all", "strategy", "roadmap", "plans", "ideas", "done", "discarded"] = "all",
320
+ output_format: Literal["text", "markdown", "json"] = "text",
321
+ ) -> str:
322
+ findings = direction.validate()
323
+ if findings:
324
+ raise ValueError("; ".join(findings))
325
+
326
+ if output_format == "json":
327
+ if section == "all":
328
+ payload: Any = direction.data
329
+ else:
330
+ payload = {section: direction.data[section]}
331
+ return json.dumps(payload, default=str, indent=2, sort_keys=True) + "\n"
332
+
333
+ if output_format == "markdown":
334
+ return _render_markdown(direction.data, section)
335
+
336
+ return _render_text(direction.data, section)
337
+
338
+
339
+ def audit_project_direction_drift(root: Path | str = ".") -> DirectionDriftAuditResult:
340
+ root_path = Path(root)
341
+ direction = load_project_direction(root_path)
342
+ source_files = {
343
+ entry
344
+ for entry in _collect_source_file_entries(direction.data)
345
+ if isinstance(entry, str) and entry not in CANONICAL_DIRECTION_FILES
346
+ }
347
+ existing_sources = {entry for entry in source_files if (root_path / entry).exists()}
348
+ missing_sources = tuple(sorted(entry for entry in source_files if not (root_path / entry).exists()))
349
+
350
+ records: list[DirectionDriftRecord] = []
351
+ reference_counts = _reference_counts(root_path, set(_iter_planning_files(root_path)) | source_files)
352
+ for relative in _iter_planning_files(root_path):
353
+ if relative in CANONICAL_DIRECTION_FILES:
354
+ classification = "canonical_direction"
355
+ recommendation = "keep"
356
+ elif relative in existing_sources:
357
+ classification = "listed_source"
358
+ recommendation = "migrate_or_retain_until_slice_cleanup"
359
+ elif reference_counts.get(relative, 0):
360
+ classification = "unlisted_referenced_file"
361
+ recommendation = "migrate_or_reference_clean_before_delete"
362
+ else:
363
+ classification = "unlisted_unreferenced_file"
364
+ recommendation = "safe_delete_candidate_after_review"
365
+ records.append(
366
+ DirectionDriftRecord(
367
+ path=relative,
368
+ classification=classification,
369
+ recommendation=recommendation,
370
+ in_source_files=relative in source_files,
371
+ reference_count=reference_counts.get(relative, 0),
372
+ )
373
+ )
374
+ records.extend(_closed_item_active_source_records(direction.data, root_path, reference_counts))
375
+ records.extend(_open_release_planning_drift_records(direction.data, root_path, direction.authority_path))
376
+ return DirectionDriftAuditResult(
377
+ root=root_path.resolve().as_posix(),
378
+ records=tuple(sorted(records, key=lambda record: record.path)),
379
+ missing_source_files=missing_sources,
380
+ )
381
+
382
+
383
+ def render_direction_validation(result: DirectionValidationResult) -> str:
384
+ lines = [
385
+ "PROJECT_DIRECTION_VALIDATE",
386
+ f"STATUS={result.status}",
387
+ f"FINDING_COUNT={len(result.findings)}",
388
+ ]
389
+ for finding in result.findings:
390
+ lines.append(f"FINDING={finding.code}|{finding.path}|{finding.message}")
391
+ return "\n".join(lines) + "\n"
392
+
393
+
394
+ def render_direction_drift_audit(result: DirectionDriftAuditResult) -> str:
395
+ lines = [
396
+ "PROJECT_DIRECTION_DRIFT_AUDIT",
397
+ f"STATUS={result.status}",
398
+ f"RECORD_COUNT={len(result.records)}",
399
+ f"MISSING_SOURCE_FILE_COUNT={len(result.missing_source_files)}",
400
+ ]
401
+ for missing in result.missing_source_files:
402
+ lines.append(f"MISSING_SOURCE={missing}")
403
+ for record in result.records:
404
+ item_suffix = (
405
+ f"|item={record.item_id}|item_status={record.item_status}"
406
+ if record.item_id is not None
407
+ else ""
408
+ )
409
+ lines.append(
410
+ "RECORD="
411
+ f"{record.classification}|{record.recommendation}|{record.path}|"
412
+ f"source={record.in_source_files}|refs={record.reference_count}"
413
+ f"{item_suffix}"
414
+ )
415
+ return "\n".join(lines) + "\n"
416
+
417
+
418
+ def _render_text(data: dict[str, Any], section: str) -> str:
419
+ meta = data.get("meta", {})
420
+ lines: list[str] = [
421
+ "PROJECT DIRECTION",
422
+ f"Status: {meta.get('status')}",
423
+ f"{_updated_after_pr_render_label(meta)}: {meta.get('updated_after_pr')}",
424
+ f"Authority: {meta.get('authority')}",
425
+ "",
426
+ ]
427
+ if section in {"all", "strategy"}:
428
+ _append_strategy_text(lines, data["strategy"])
429
+ if section in {"all", "roadmap"}:
430
+ _append_roadmap_text(lines, data["roadmap"])
431
+ if section in {"all", "plans"}:
432
+ _append_items_text(lines, "Plans", data["plans"])
433
+ if section in {"all", "ideas"}:
434
+ _append_items_text(lines, "Ideas", data["ideas"])
435
+ if section in {"all", "done"}:
436
+ _append_items_text(lines, "Done", data["done"])
437
+ if section in {"all", "discarded"}:
438
+ _append_items_text(lines, "Discarded", data["discarded"])
439
+ return "\n".join(lines).rstrip() + "\n"
440
+
441
+
442
+ def _render_markdown(data: dict[str, Any], section: str) -> str:
443
+ meta = data.get("meta", {})
444
+ lines: list[str] = [
445
+ "# Project Direction",
446
+ "",
447
+ f"- Status: `{meta.get('status')}`",
448
+ f"- {_updated_after_pr_render_label(meta)}: `{meta.get('updated_after_pr')}`",
449
+ f"- Authority: `{meta.get('authority')}`",
450
+ "",
451
+ ]
452
+ if section in {"all", "strategy"}:
453
+ _append_strategy_markdown(lines, data["strategy"])
454
+ if section in {"all", "roadmap"}:
455
+ _append_roadmap_markdown(lines, data["roadmap"])
456
+ if section in {"all", "plans"}:
457
+ _append_items_markdown(lines, "Plans", data["plans"])
458
+ if section in {"all", "ideas"}:
459
+ _append_items_markdown(lines, "Ideas", data["ideas"])
460
+ if section in {"all", "done"}:
461
+ _append_items_markdown(lines, "Done", data["done"])
462
+ if section in {"all", "discarded"}:
463
+ _append_items_markdown(lines, "Discarded", data["discarded"])
464
+ return "\n".join(lines).rstrip() + "\n"
465
+
466
+
467
+ def _updated_after_pr_render_label(meta: dict[str, Any]) -> str:
468
+ if meta.get("updated_after_pr_semantics") == "strategic_direction_refresh":
469
+ return "Strategic direction updated after PR"
470
+ return "Updated after PR"
471
+
472
+
473
+ def _append_strategy_text(lines: list[str], strategy: list[dict[str, Any]]) -> None:
474
+ lines.append("Strategy")
475
+ for item in strategy:
476
+ lines.append(f"- {item.get('id')}: {item.get('title')} [{item.get('status')}]")
477
+ rationale = item.get("rationale")
478
+ if rationale:
479
+ lines.append(f" {rationale}")
480
+ lines.append("")
481
+
482
+
483
+ def _append_roadmap_text(lines: list[str], roadmap: list[dict[str, Any]]) -> None:
484
+ lines.append("Roadmap")
485
+ for item in roadmap:
486
+ lines.append(
487
+ f"- {item.get('id')}: {item.get('title')} "
488
+ f"[{item.get('phase')}/{item.get('status')}]"
489
+ )
490
+ lines.append("")
491
+
492
+
493
+ def _append_items_text(lines: list[str], title: str, items: list[dict[str, Any]]) -> None:
494
+ lines.append(title)
495
+ for item in items:
496
+ detail = item.get("rationale") or item.get("reason") or item.get("title") or ""
497
+ lines.append(f"- {item.get('id')}: {item.get('title')} [{item.get('status', item.get('completed_by_pr'))}]")
498
+ if detail and detail != item.get("title"):
499
+ lines.append(f" {detail}")
500
+ lines.append("")
501
+
502
+
503
+ def _append_strategy_markdown(lines: list[str], strategy: list[dict[str, Any]]) -> None:
504
+ lines.append("## Strategy")
505
+ lines.append("")
506
+ for item in strategy:
507
+ lines.append(f"- `{item.get('id')}` - **{item.get('title')}** (`{item.get('status')}`)")
508
+ if item.get("rationale"):
509
+ lines.append(f" {item.get('rationale')}")
510
+ lines.append("")
511
+
512
+
513
+ def _append_roadmap_markdown(lines: list[str], roadmap: list[dict[str, Any]]) -> None:
514
+ lines.append("## Roadmap")
515
+ lines.append("")
516
+ for item in roadmap:
517
+ lines.append(
518
+ f"- `{item.get('id')}` - **{item.get('title')}** "
519
+ f"(`{item.get('phase')}`, `{item.get('status')}`)"
520
+ )
521
+ lines.append("")
522
+
523
+
524
+ def _append_items_markdown(lines: list[str], title: str, items: list[dict[str, Any]]) -> None:
525
+ lines.append(f"## {title}")
526
+ lines.append("")
527
+ for item in items:
528
+ status = item.get("status", item.get("completed_by_pr"))
529
+ detail = item.get("rationale") or item.get("reason") or ""
530
+ lines.append(f"- `{item.get('id')}` - **{item.get('title')}** (`{status}`)")
531
+ if detail:
532
+ lines.append(f" {detail}")
533
+ lines.append("")
534
+
535
+
536
+ def _string_list(value: object, path: str, findings: list[DirectionFinding]) -> list[str]:
537
+ if value in (None, []):
538
+ return []
539
+ if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
540
+ findings.append(DirectionFinding("invalid-string-list", f"{path} must be a list of strings"))
541
+ return []
542
+ return [item for item in value if item]
543
+
544
+
545
+ def _collect_source_file_entries(data: object) -> list[object]:
546
+ entries: list[object] = []
547
+ if isinstance(data, dict):
548
+ source_files = data.get("source_files")
549
+ if isinstance(source_files, list):
550
+ entries.extend(source_files)
551
+ for value in data.values():
552
+ entries.extend(_collect_source_file_entries(value))
553
+ elif isinstance(data, list):
554
+ for item in data:
555
+ entries.extend(_collect_source_file_entries(item))
556
+ return entries
557
+
558
+
559
+ def _closed_item_active_source_records(
560
+ data: dict[str, Any],
561
+ root: Path,
562
+ reference_counts: dict[str, int],
563
+ ) -> list[DirectionDriftRecord]:
564
+ records: list[DirectionDriftRecord] = []
565
+ for section in ("strategy", "roadmap", "plans", "ideas", "done", "discarded"):
566
+ items = data.get(section)
567
+ if not isinstance(items, list):
568
+ continue
569
+ for item in items:
570
+ if not isinstance(item, dict):
571
+ continue
572
+ item_id = item.get("id")
573
+ if not isinstance(item_id, str) or not item_id:
574
+ continue
575
+ status = _direction_item_status(section, item)
576
+ if status not in {"done", "discarded"}:
577
+ continue
578
+ source_files = item.get("source_files")
579
+ if not isinstance(source_files, list):
580
+ continue
581
+ for source in source_files:
582
+ if not isinstance(source, str) or not source.endswith(".md"):
583
+ continue
584
+ if _markdown_status(root / source) != "active":
585
+ continue
586
+ records.append(
587
+ DirectionDriftRecord(
588
+ path=source,
589
+ classification="SOURCE_OF_CLOSED_ITEM_STILL_ACTIVE",
590
+ recommendation="retire_source_header_or_reopen_direction_item",
591
+ in_source_files=True,
592
+ reference_count=reference_counts.get(source, 0),
593
+ item_id=item_id,
594
+ item_status=status,
595
+ )
596
+ )
597
+ return records
598
+
599
+
600
+ def _open_release_planning_drift_records(
601
+ data: dict[str, Any],
602
+ root: Path,
603
+ authority_path: str,
604
+ ) -> list[DirectionDriftRecord]:
605
+ current_release = _read_project_version(root)
606
+ if not current_release:
607
+ return []
608
+ current_tuple = _release_tuple(current_release)
609
+ records: list[DirectionDriftRecord] = []
610
+ for section in ("roadmap", "plans"):
611
+ items = data.get(section)
612
+ if not isinstance(items, list):
613
+ continue
614
+ for item in items:
615
+ if not isinstance(item, dict):
616
+ continue
617
+ item_id = item.get("id")
618
+ status = _direction_item_status(section, item)
619
+ if not isinstance(item_id, str) or not item_id or status not in ACTIVE_STATUSES:
620
+ continue
621
+ release_evidence_count = _current_release_evidence_count(item, current_release)
622
+ if release_evidence_count:
623
+ records.append(
624
+ DirectionDriftRecord(
625
+ path=authority_path,
626
+ classification="OPEN_ITEM_REFERENCES_CURRENT_RELEASE",
627
+ recommendation="close_item_or_explain_why_current_release_evidence_is_not_acceptance",
628
+ in_source_files=True,
629
+ reference_count=release_evidence_count,
630
+ item_id=item_id,
631
+ item_status=status,
632
+ )
633
+ )
634
+ target_release = item.get("target_release")
635
+ target_tuple = _release_tuple(target_release) if isinstance(target_release, str) else None
636
+ if current_tuple is not None and target_tuple is not None and target_tuple < current_tuple:
637
+ records.append(
638
+ DirectionDriftRecord(
639
+ path=authority_path,
640
+ classification="OPEN_ITEM_TARGET_RELEASE_PASSED",
641
+ recommendation="revalidate_target_release_or_close_item",
642
+ in_source_files=True,
643
+ reference_count=0,
644
+ item_id=item_id,
645
+ item_status=status,
646
+ )
647
+ )
648
+ return records
649
+
650
+
651
+ def _current_release_evidence_count(item: dict[str, Any], current_release: str) -> int:
652
+ evidence = item.get("evidence")
653
+ if not isinstance(evidence, list):
654
+ return 0
655
+ release_pattern = re.compile(rf"(?<![0-9A-Za-z_.-])v?{re.escape(current_release)}(?![0-9A-Za-z_.-])")
656
+ return sum(1 for entry in evidence if isinstance(entry, str) and release_pattern.search(entry))
657
+
658
+
659
+ def _direction_item_status(section: str, item: dict[str, Any]) -> str:
660
+ if section in {"done", "discarded"}:
661
+ return section
662
+ status = item.get("status")
663
+ return status if isinstance(status, str) else ""
664
+
665
+
666
+ def _markdown_status(path: Path) -> str | None:
667
+ if not path.exists() or not path.is_file():
668
+ return None
669
+ try:
670
+ text = path.read_text(encoding="utf-8")
671
+ except OSError:
672
+ return None
673
+ for line in text.splitlines():
674
+ if line.startswith("Status:"):
675
+ value = line.removeprefix("Status:").strip()
676
+ return value or None
677
+ return None
678
+
679
+
680
+ def _validate_item_sources(
681
+ item: dict[str, Any],
682
+ path: str,
683
+ root: Path,
684
+ findings: list[DirectionFinding],
685
+ ) -> None:
686
+ source_files = item.get("source_files")
687
+ if not isinstance(source_files, list) or not source_files:
688
+ findings.append(DirectionFinding("missing-source-files", f"{path}.source_files must not be empty"))
689
+ return
690
+ for index, source in enumerate(source_files):
691
+ source_path = f"{path}.source_files[{index}]"
692
+ if isinstance(source, str):
693
+ if _is_private_absolute_path(source):
694
+ findings.append(DirectionFinding("private-absolute-path", f"{source_path} is private/absolute"))
695
+ elif not (root / source).exists():
696
+ findings.append(DirectionFinding("missing-source-file", f"{source_path} does not exist: {source}"))
697
+ continue
698
+ if isinstance(source, dict) and source.get("deleted_source") is True:
699
+ deleted_path = source.get("path")
700
+ if not isinstance(deleted_path, str) or not deleted_path.strip():
701
+ findings.append(DirectionFinding("invalid-deleted-source", f"{source_path}.path must be set"))
702
+ continue
703
+ findings.append(
704
+ DirectionFinding(
705
+ "invalid-source-file",
706
+ f"{source_path} must be a repo path or a deleted_source mapping",
707
+ )
708
+ )
709
+
710
+
711
+ def _validate_item_evidence(
712
+ item: dict[str, Any],
713
+ path: str,
714
+ root: Path,
715
+ findings: list[DirectionFinding],
716
+ ) -> None:
717
+ evidence = item.get("evidence")
718
+ if evidence in (None, []):
719
+ return
720
+ if not isinstance(evidence, list):
721
+ findings.append(DirectionFinding("invalid-evidence", f"{path}.evidence must be a list"))
722
+ return
723
+ for index, entry in enumerate(evidence):
724
+ if not isinstance(entry, str):
725
+ findings.append(DirectionFinding("invalid-evidence", f"{path}.evidence[{index}] must be a string"))
726
+ continue
727
+ if _looks_like_repo_file(entry) and not (root / entry).exists():
728
+ findings.append(DirectionFinding("missing-evidence-file", f"{path}.evidence[{index}] missing: {entry}"))
729
+
730
+
731
+ def _validate_target_release_currency(
732
+ item: dict[str, Any],
733
+ path: str,
734
+ *,
735
+ status: str,
736
+ current_release: str | None,
737
+ findings: list[DirectionFinding],
738
+ ) -> None:
739
+ if status not in ACTIVE_STATUSES or not current_release:
740
+ return
741
+ target_release = item.get("target_release")
742
+ if not isinstance(target_release, str) or not target_release.strip():
743
+ return
744
+ current_tuple = _release_tuple(current_release)
745
+ target_tuple = _release_tuple(target_release)
746
+ if current_tuple is None or target_tuple is None:
747
+ return
748
+ if target_tuple < current_tuple:
749
+ findings.append(
750
+ DirectionFinding(
751
+ "stale-target-release",
752
+ f"{path}.target_release {target_release!r} has passed current release "
753
+ f"{current_release!r}; revalidate the item or remove the stale target",
754
+ )
755
+ )
756
+
757
+
758
+ def _read_project_version(root: Path) -> str | None:
759
+ pyproject = root / "pyproject.toml"
760
+ if not pyproject.exists():
761
+ return None
762
+ text = pyproject.read_text(encoding="utf-8")
763
+ if tomllib is not None:
764
+ try:
765
+ project = tomllib.loads(text).get("project")
766
+ except tomllib.TOMLDecodeError:
767
+ return None
768
+ if isinstance(project, dict):
769
+ version = project.get("version")
770
+ if isinstance(version, str) and version.strip():
771
+ return version
772
+ return None
773
+ match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
774
+ return match.group(1) if match else None
775
+
776
+
777
+ def _release_tuple(value: str) -> tuple[int, int, int] | None:
778
+ match = re.match(r"^v?(\d+)\.(\d+)(?:\.(\d+|x))?$", value.strip())
779
+ if not match:
780
+ return None
781
+ major, minor, patch = match.groups()
782
+ if patch is None:
783
+ patch_value = 0
784
+ elif patch == "x":
785
+ patch_value = 9999
786
+ else:
787
+ patch_value = int(patch)
788
+ return int(major), int(minor), patch_value
789
+
790
+
791
+ def _validate_no_private_absolute_paths(data: object, findings: list[DirectionFinding]) -> None:
792
+ if isinstance(data, dict):
793
+ for value in data.values():
794
+ _validate_no_private_absolute_paths(value, findings)
795
+ elif isinstance(data, list):
796
+ for item in data:
797
+ _validate_no_private_absolute_paths(item, findings)
798
+ elif isinstance(data, str) and _is_private_absolute_path(data):
799
+ findings.append(DirectionFinding("private-absolute-path", f"private absolute path is not allowed: {data}"))
800
+
801
+
802
+ def _is_private_absolute_path(value: str) -> bool:
803
+ return value.startswith(("/Users/", "/home/", "/private/", "C:\\", "D:\\"))
804
+
805
+
806
+ def _looks_like_repo_file(value: str) -> bool:
807
+ return value.startswith((".agentic/", "docs/", "src/", "tests/", "artifacts/"))
808
+
809
+
810
+ def _iter_planning_files(root: Path) -> list[str]:
811
+ files: list[str] = []
812
+ for base in PLANNING_SCAN_ROOTS:
813
+ absolute = root / base
814
+ if not absolute.exists():
815
+ continue
816
+ files.extend(
817
+ path.relative_to(root).as_posix()
818
+ for path in absolute.rglob("*")
819
+ if path.is_file() and path.suffix in {".md", ".yaml", ".yml"}
820
+ )
821
+ return sorted(files)
822
+
823
+
824
+ def _reference_counts(root: Path, targets: set[str]) -> dict[str, int]:
825
+ counts = {target: 0 for target in targets}
826
+ ignored_parts = {".git", ".venv", "node_modules", "__pycache__"}
827
+ for path in root.rglob("*"):
828
+ if not path.is_file() or ignored_parts & set(path.parts):
829
+ continue
830
+ try:
831
+ text = path.read_text(encoding="utf-8")
832
+ except UnicodeDecodeError:
833
+ continue
834
+ except OSError:
835
+ continue
836
+ relative = path.relative_to(root).as_posix()
837
+ for target in targets:
838
+ if target != relative and target in text:
839
+ counts[target] += 1
840
+ return counts