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,704 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ import yaml
8
+
9
+ INVENTORY_PATH = Path(".agentic/rule_mechanism_inventory.yaml")
10
+ MIGRATIONS_PATH = Path(".agentic/rule_migrations.yaml")
11
+ COVERAGE_PATH = Path(".agentic/rule_test_coverage.yaml")
12
+ DIRECT_TEST_PLAN_PATH = Path(".agentic/rule_direct_test_plan.yaml")
13
+ VALID_MECHANISM_CATEGORIES = {"communication", "execution", "governance", "workflow", "preflight"}
14
+ VALID_ENFORCEMENT_PHASES = {"runtime", "guard", "preflight"}
15
+ VALID_CATEGORY_PHASES = {
16
+ ("communication", "runtime"),
17
+ ("execution", "runtime"),
18
+ ("governance", "guard"),
19
+ ("workflow", "guard"),
20
+ ("preflight", "preflight"),
21
+ }
22
+ VALID_MIGRATION_STATUSES = {"migrated", "archived", "rejected"}
23
+ VALID_TEST_COVERAGE = {"direct", "indirect", "documented"}
24
+ VALID_ASSERTION_KINDS = {"anchor", "artifact", "behavior", "evidence", "guard", "negative-case", "release", "workflow"}
25
+ VALID_EVIDENCE_REF_KINDS = {"source", "test"}
26
+ VALID_DIRECT_TEST_PLAN_STATUSES = {"planned", "in-progress", "deferred"}
27
+ TERMINAL_MIGRATION_STATUSES = {"archived", "rejected"}
28
+ MIN_PRIORITY = 1
29
+ MAX_PRIORITY = 5
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class RuleRegistryFinding:
34
+ path: str
35
+ message: str
36
+
37
+
38
+ def _load_yaml(path: Path) -> Any:
39
+ if not path.exists():
40
+ raise FileNotFoundError(path)
41
+ return yaml.safe_load(path.read_text(encoding="utf-8"))
42
+
43
+
44
+ def _as_list(value: Any) -> list[Any]:
45
+ return value if isinstance(value, list) else []
46
+
47
+
48
+ def _validate_string_list(
49
+ *,
50
+ value: Any,
51
+ label: str,
52
+ mechanism_id: str,
53
+ required_non_empty: bool,
54
+ findings: list[RuleRegistryFinding],
55
+ ) -> list[str]:
56
+ if not isinstance(value, list):
57
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mechanism_id}: {label} must be a list"))
58
+ return []
59
+ if required_non_empty and not value:
60
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mechanism_id}: {label} must list at least one entry"))
61
+ entries: list[str] = []
62
+ for item in value:
63
+ text = str(item).strip()
64
+ if not text:
65
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mechanism_id}: {label} entries must be non-empty strings"))
66
+ continue
67
+ entries.append(text)
68
+ return entries
69
+
70
+
71
+ def _validate_evidence_refs(
72
+ *,
73
+ value: Any,
74
+ mechanism_id: str,
75
+ source_paths: set[str],
76
+ test_paths: set[str],
77
+ findings: list[RuleRegistryFinding],
78
+ ) -> None:
79
+ if not isinstance(value, list):
80
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion missing evidence_refs list"))
81
+ return
82
+ if not value:
83
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion evidence_refs must list at least one entry"))
84
+ return
85
+ for ref in value:
86
+ if not isinstance(ref, dict):
87
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: evidence_refs entries must be mappings"))
88
+ continue
89
+ kind = str(ref.get("kind", "")).strip()
90
+ path = str(ref.get("path", "")).strip()
91
+ if kind not in VALID_EVIDENCE_REF_KINDS:
92
+ findings.append(
93
+ RuleRegistryFinding(
94
+ str(COVERAGE_PATH),
95
+ f"{mechanism_id}: evidence_refs kind must be one of: {', '.join(sorted(VALID_EVIDENCE_REF_KINDS))}",
96
+ )
97
+ )
98
+ if not path:
99
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: evidence_refs entry missing path"))
100
+ continue
101
+ if kind == "source" and path not in source_paths:
102
+ findings.append(
103
+ RuleRegistryFinding(
104
+ str(COVERAGE_PATH),
105
+ f"{mechanism_id}: evidence_refs source path is not registered in mechanism sources: {path}",
106
+ )
107
+ )
108
+ if kind == "test" and path not in test_paths:
109
+ findings.append(
110
+ RuleRegistryFinding(
111
+ str(COVERAGE_PATH),
112
+ f"{mechanism_id}: evidence_refs test path is not registered in mechanism tests: {path}",
113
+ )
114
+ )
115
+
116
+
117
+ def _validate_assertions(
118
+ *,
119
+ value: Any,
120
+ mechanism_id: str,
121
+ surfaces: set[str],
122
+ source_paths: set[str],
123
+ test_paths: set[str],
124
+ global_assertion_ids: dict[str, str],
125
+ findings: list[RuleRegistryFinding],
126
+ ) -> None:
127
+ if not isinstance(value, list):
128
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertions must be a list"))
129
+ return
130
+ if not value:
131
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertions must list at least one entry"))
132
+ return
133
+ seen_ids: set[str] = set()
134
+ required_prefix = f"{mechanism_id}-"
135
+ for assertion in value:
136
+ if not isinstance(assertion, dict):
137
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion entries must be mappings"))
138
+ continue
139
+ assertion_id = str(assertion.get("assertion_id", "")).strip()
140
+ if not assertion_id:
141
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion missing assertion_id"))
142
+ else:
143
+ if not assertion_id.startswith(required_prefix):
144
+ findings.append(
145
+ RuleRegistryFinding(
146
+ str(COVERAGE_PATH),
147
+ f"{mechanism_id}: assertion_id must start with {required_prefix}: {assertion_id}",
148
+ )
149
+ )
150
+ if assertion_id in seen_ids:
151
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: duplicate assertion_id: {assertion_id}"))
152
+ seen_ids.add(assertion_id)
153
+ previous_mechanism = global_assertion_ids.get(assertion_id)
154
+ if previous_mechanism is not None and previous_mechanism != mechanism_id:
155
+ findings.append(
156
+ RuleRegistryFinding(
157
+ str(COVERAGE_PATH),
158
+ f"{mechanism_id}: assertion_id already used by {previous_mechanism}: {assertion_id}",
159
+ )
160
+ )
161
+ else:
162
+ global_assertion_ids[assertion_id] = mechanism_id
163
+ kind = assertion.get("kind")
164
+ if kind not in VALID_ASSERTION_KINDS:
165
+ findings.append(
166
+ RuleRegistryFinding(
167
+ str(COVERAGE_PATH),
168
+ f"{mechanism_id}: assertion kind must be one of: {', '.join(sorted(VALID_ASSERTION_KINDS))}",
169
+ )
170
+ )
171
+ statement = str(assertion.get("statement", "")).strip()
172
+ if not statement:
173
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion missing statement"))
174
+ _validate_evidence_refs(
175
+ value=assertion.get("evidence_refs"),
176
+ mechanism_id=mechanism_id,
177
+ source_paths=source_paths,
178
+ test_paths=test_paths,
179
+ findings=findings,
180
+ )
181
+ covered_surfaces = assertion.get("covered_surfaces")
182
+ if not isinstance(covered_surfaces, list):
183
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion missing covered_surfaces list"))
184
+ continue
185
+ if not covered_surfaces:
186
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion covered_surfaces must list at least one entry"))
187
+ continue
188
+ for surface in covered_surfaces:
189
+ surface_text = str(surface).strip()
190
+ if not surface_text:
191
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"{mechanism_id}: assertion covered_surfaces entries must be non-empty strings"))
192
+ elif surface_text not in surfaces:
193
+ findings.append(
194
+ RuleRegistryFinding(
195
+ str(COVERAGE_PATH),
196
+ f"{mechanism_id}: assertion references unknown covered_surface: {surface_text}",
197
+ )
198
+ )
199
+
200
+
201
+ def _validate_mechanism_metadata(
202
+ mechanism: dict[str, Any], mechanism_id: str, findings: list[RuleRegistryFinding]
203
+ ) -> None:
204
+ owner = mechanism.get("owner")
205
+ if not isinstance(owner, str) or not owner.strip():
206
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mechanism_id}: owner must be a non-empty string"))
207
+ category = mechanism.get("category")
208
+ if category not in VALID_MECHANISM_CATEGORIES:
209
+ findings.append(
210
+ RuleRegistryFinding(
211
+ str(INVENTORY_PATH),
212
+ f"{mechanism_id}: category must be one of: {', '.join(sorted(VALID_MECHANISM_CATEGORIES))}",
213
+ )
214
+ )
215
+ priority = mechanism.get("priority")
216
+ if not isinstance(priority, int) or not MIN_PRIORITY <= priority <= MAX_PRIORITY:
217
+ findings.append(
218
+ RuleRegistryFinding(
219
+ str(INVENTORY_PATH),
220
+ f"{mechanism_id}: priority must be an integer from {MIN_PRIORITY} to {MAX_PRIORITY}",
221
+ )
222
+ )
223
+ enforcement_phase = mechanism.get("enforcement_phase")
224
+ if enforcement_phase not in VALID_ENFORCEMENT_PHASES:
225
+ findings.append(
226
+ RuleRegistryFinding(
227
+ str(INVENTORY_PATH),
228
+ f"{mechanism_id}: enforcement_phase must be one of: {', '.join(sorted(VALID_ENFORCEMENT_PHASES))}",
229
+ )
230
+ )
231
+ if (
232
+ category in VALID_MECHANISM_CATEGORIES
233
+ and enforcement_phase in VALID_ENFORCEMENT_PHASES
234
+ and (category, enforcement_phase) not in VALID_CATEGORY_PHASES
235
+ ):
236
+ findings.append(
237
+ RuleRegistryFinding(
238
+ str(INVENTORY_PATH),
239
+ f"{mechanism_id}: incompatible category/enforcement_phase combination: {category}/{enforcement_phase}",
240
+ )
241
+ )
242
+
243
+
244
+ def _load_test_coverage_metadata(base: Path, findings: list[RuleRegistryFinding]) -> dict[str, dict[str, Any]]:
245
+ coverage_path = base / COVERAGE_PATH
246
+ if not coverage_path.exists():
247
+ return {}
248
+ try:
249
+ data = _load_yaml(coverage_path)
250
+ except Exception as exc:
251
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"cannot load test coverage metadata: {exc}"))
252
+ return {}
253
+ if not isinstance(data, dict):
254
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), "coverage metadata must be a mapping"))
255
+ return {}
256
+ if data.get("schema_version") != 1:
257
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), "schema_version must be 1"))
258
+ coverage_entries = data.get("coverage")
259
+ if not isinstance(coverage_entries, list):
260
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), "coverage must be a list"))
261
+ return {}
262
+ by_mechanism: dict[str, dict[str, Any]] = {}
263
+ for entry in coverage_entries:
264
+ if not isinstance(entry, dict):
265
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), "coverage entry must be a mapping"))
266
+ continue
267
+ mechanism_id = str(entry.get("mechanism_id", "")).strip()
268
+ if not mechanism_id:
269
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), "coverage entry missing mechanism_id"))
270
+ continue
271
+ if mechanism_id in by_mechanism:
272
+ findings.append(RuleRegistryFinding(str(COVERAGE_PATH), f"duplicate coverage entry: {mechanism_id}"))
273
+ by_mechanism[mechanism_id] = entry
274
+ return by_mechanism
275
+
276
+
277
+ def _validate_test_coverage(
278
+ mechanism: dict[str, Any],
279
+ mechanism_id: str,
280
+ tests: list[str],
281
+ surfaces: set[str],
282
+ source_paths: set[str],
283
+ global_assertion_ids: dict[str, str],
284
+ findings: list[RuleRegistryFinding],
285
+ ) -> None:
286
+ coverage = mechanism.get("test_coverage")
287
+ if coverage not in VALID_TEST_COVERAGE:
288
+ findings.append(
289
+ RuleRegistryFinding(
290
+ str(INVENTORY_PATH),
291
+ f"{mechanism_id}: test_coverage must be one of: {', '.join(sorted(VALID_TEST_COVERAGE))}",
292
+ )
293
+ )
294
+ return
295
+ _validate_assertions(
296
+ value=mechanism.get("assertions"),
297
+ mechanism_id=mechanism_id,
298
+ surfaces=surfaces,
299
+ source_paths=source_paths,
300
+ test_paths=set(tests),
301
+ global_assertion_ids=global_assertion_ids,
302
+ findings=findings,
303
+ )
304
+ rationale = str(mechanism.get("coverage_rationale", "")).strip()
305
+ if tests and coverage != "direct":
306
+ findings.append(
307
+ RuleRegistryFinding(
308
+ str(INVENTORY_PATH),
309
+ f"{mechanism_id}: test_coverage must be direct when tests are listed",
310
+ )
311
+ )
312
+ if not tests and coverage == "direct":
313
+ findings.append(
314
+ RuleRegistryFinding(
315
+ str(INVENTORY_PATH),
316
+ f"{mechanism_id}: direct test_coverage requires at least one test path",
317
+ )
318
+ )
319
+ if not tests and not rationale:
320
+ findings.append(
321
+ RuleRegistryFinding(
322
+ str(INVENTORY_PATH),
323
+ f"{mechanism_id}: coverage_rationale is required when no direct tests are listed",
324
+ )
325
+ )
326
+
327
+
328
+ def _mechanism_requires_direct_test_plan(
329
+ mechanism: dict[str, Any], coverage_by_mechanism: dict[str, dict[str, Any]]
330
+ ) -> bool:
331
+ tests = [str(item).strip() for item in _as_list(mechanism.get("tests")) if str(item).strip()]
332
+ if tests:
333
+ return False
334
+ mechanism_id = str(mechanism.get("id", "")).strip()
335
+ coverage_entry = coverage_by_mechanism.get(mechanism_id, {})
336
+ coverage = mechanism.get("test_coverage", coverage_entry.get("test_coverage"))
337
+ return coverage != "direct"
338
+
339
+
340
+ def _validate_direct_test_plan_entry(
341
+ *,
342
+ entry: dict[str, Any],
343
+ active_mechanisms: dict[str, dict[str, Any]],
344
+ findings: list[RuleRegistryFinding],
345
+ ) -> str | None:
346
+ mechanism_id = str(entry.get("mechanism_id", "")).strip()
347
+ if not mechanism_id:
348
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), "direct test followup entry missing mechanism_id"))
349
+ return None
350
+ mechanism = active_mechanisms.get(mechanism_id)
351
+ if mechanism is None:
352
+ findings.append(
353
+ RuleRegistryFinding(
354
+ str(DIRECT_TEST_PLAN_PATH),
355
+ f"direct test followup references unknown active mechanism: {mechanism_id}",
356
+ )
357
+ )
358
+ status = entry.get("status")
359
+ if status not in VALID_DIRECT_TEST_PLAN_STATUSES:
360
+ findings.append(
361
+ RuleRegistryFinding(
362
+ str(DIRECT_TEST_PLAN_PATH),
363
+ f"{mechanism_id}: direct test followup status must be one of: {', '.join(sorted(VALID_DIRECT_TEST_PLAN_STATUSES))}",
364
+ )
365
+ )
366
+ priority_order = entry.get("priority_order")
367
+ if not isinstance(priority_order, int) or priority_order < 1:
368
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"{mechanism_id}: priority_order must be a positive integer"))
369
+ target_test_path = str(entry.get("target_test_path", "")).strip()
370
+ if not target_test_path:
371
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"{mechanism_id}: target_test_path is required"))
372
+ target_surface = str(entry.get("target_surface", "")).strip()
373
+ if not target_surface:
374
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"{mechanism_id}: target_surface is required"))
375
+ elif mechanism is not None:
376
+ surfaces = {str(surface).strip() for surface in _as_list(mechanism.get("surfaces"))}
377
+ if target_surface not in surfaces:
378
+ findings.append(
379
+ RuleRegistryFinding(
380
+ str(DIRECT_TEST_PLAN_PATH),
381
+ f"{mechanism_id}: target_surface must reference a registered mechanism surface: {target_surface}",
382
+ )
383
+ )
384
+ rationale = str(entry.get("rationale", "")).strip()
385
+ if not rationale:
386
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"{mechanism_id}: rationale is required"))
387
+ exit_criteria = entry.get("exit_criteria")
388
+ if not isinstance(exit_criteria, list) or not exit_criteria:
389
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"{mechanism_id}: exit_criteria must list at least one item"))
390
+ elif not all(str(item).strip() for item in exit_criteria):
391
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"{mechanism_id}: exit_criteria entries must be non-empty strings"))
392
+ return mechanism_id
393
+
394
+
395
+ def _validate_direct_test_followup_plan(
396
+ *,
397
+ base: Path,
398
+ mechanisms: list[Any],
399
+ coverage_by_mechanism: dict[str, dict[str, Any]],
400
+ coverage_metadata_present: bool,
401
+ findings: list[RuleRegistryFinding],
402
+ ) -> None:
403
+ if not coverage_metadata_present:
404
+ return
405
+ active_mechanisms = {
406
+ str(mechanism.get("id", "")).strip(): mechanism
407
+ for mechanism in mechanisms
408
+ if isinstance(mechanism, dict) and mechanism.get("status") == "active" and str(mechanism.get("id", "")).strip()
409
+ }
410
+ required_ids = {
411
+ mechanism_id
412
+ for mechanism_id, mechanism in active_mechanisms.items()
413
+ if _mechanism_requires_direct_test_plan(mechanism, coverage_by_mechanism)
414
+ }
415
+ plan_path = base / DIRECT_TEST_PLAN_PATH
416
+ if not required_ids and not plan_path.exists():
417
+ return
418
+ if required_ids and not plan_path.exists():
419
+ findings.append(
420
+ RuleRegistryFinding(
421
+ str(DIRECT_TEST_PLAN_PATH),
422
+ "missing direct test followup plan for mechanisms without direct tests",
423
+ )
424
+ )
425
+ return
426
+ try:
427
+ data = _load_yaml(plan_path)
428
+ except Exception as exc:
429
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"cannot load direct test followup plan: {exc}"))
430
+ return
431
+ if not isinstance(data, dict):
432
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), "direct test followup plan must be a mapping"))
433
+ return
434
+ if data.get("schema_version") != 1:
435
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), "schema_version must be 1"))
436
+ entries = data.get("direct_test_followups")
437
+ if not isinstance(entries, list):
438
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), "direct_test_followups must be a list"))
439
+ return
440
+ planned_ids: set[str] = set()
441
+ for entry in entries:
442
+ if not isinstance(entry, dict):
443
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), "direct test followup entries must be mappings"))
444
+ continue
445
+ mechanism_id = _validate_direct_test_plan_entry(
446
+ entry=entry,
447
+ active_mechanisms=active_mechanisms,
448
+ findings=findings,
449
+ )
450
+ if mechanism_id is None:
451
+ continue
452
+ if mechanism_id in planned_ids:
453
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"duplicate direct test followup plan entry: {mechanism_id}"))
454
+ planned_ids.add(mechanism_id)
455
+ for missing_id in sorted(required_ids - planned_ids):
456
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"missing direct test followup plan entry: {missing_id}"))
457
+ for stale_id in sorted(planned_ids - required_ids):
458
+ findings.append(RuleRegistryFinding(str(DIRECT_TEST_PLAN_PATH), f"stale direct test followup plan entry: {stale_id}"))
459
+
460
+
461
+ def _validate_mechanism_conflicts(mechanisms: list[Any], findings: list[RuleRegistryFinding]) -> None:
462
+ seen: dict[tuple[str, int, str], str] = {}
463
+ for mechanism in mechanisms:
464
+ if not isinstance(mechanism, dict) or mechanism.get("status") != "active":
465
+ continue
466
+ mechanism_id = str(mechanism.get("id", ""))
467
+ priority = mechanism.get("priority")
468
+ enforcement_phase = mechanism.get("enforcement_phase")
469
+ conflict_domains = _as_list(mechanism.get("conflict_domains"))
470
+ if (
471
+ not isinstance(priority, int)
472
+ or not MIN_PRIORITY <= priority <= MAX_PRIORITY
473
+ or enforcement_phase not in VALID_ENFORCEMENT_PHASES
474
+ ):
475
+ continue
476
+ for domain in conflict_domains:
477
+ domain_text = str(domain).strip()
478
+ if not domain_text:
479
+ continue
480
+ key = (domain_text, priority, str(enforcement_phase))
481
+ previous = seen.get(key)
482
+ if previous is not None:
483
+ findings.append(
484
+ RuleRegistryFinding(
485
+ str(INVENTORY_PATH),
486
+ f"ambiguous enforcement order: {previous} and {mechanism_id} share conflict_domain={domain_text}, priority={priority}, enforcement_phase={enforcement_phase}",
487
+ )
488
+ )
489
+ else:
490
+ seen[key] = mechanism_id
491
+
492
+
493
+ def _validate_migration_completeness(
494
+ migrations: dict[str, Any], legacy_ids: set[str], findings: list[RuleRegistryFinding]
495
+ ) -> None:
496
+ known_legacy_rule_ids = {str(item) for item in _as_list(migrations.get("known_legacy_rule_ids"))}
497
+ if not known_legacy_rule_ids:
498
+ findings.append(
499
+ RuleRegistryFinding(
500
+ str(MIGRATIONS_PATH),
501
+ "known_legacy_rule_ids must list every known legacy rule id",
502
+ )
503
+ )
504
+ return
505
+ missing = sorted(known_legacy_rule_ids - legacy_ids)
506
+ extra = sorted(legacy_ids - known_legacy_rule_ids)
507
+ for legacy_id in missing:
508
+ findings.append(
509
+ RuleRegistryFinding(
510
+ str(MIGRATIONS_PATH),
511
+ f"known legacy rule missing migration entry: {legacy_id}",
512
+ )
513
+ )
514
+ for legacy_id in extra:
515
+ findings.append(
516
+ RuleRegistryFinding(
517
+ str(MIGRATIONS_PATH),
518
+ f"migration entry missing from known legacy rule index: {legacy_id}",
519
+ )
520
+ )
521
+
522
+
523
+ def validate_rule_registry(root: Path | str = ".") -> list[RuleRegistryFinding]:
524
+ base = Path(root)
525
+ inventory_path = base / INVENTORY_PATH
526
+ migrations_path = base / MIGRATIONS_PATH
527
+ coverage_path = base / COVERAGE_PATH
528
+ coverage_metadata_present = coverage_path.exists()
529
+ findings: list[RuleRegistryFinding] = []
530
+ try:
531
+ inventory = _load_yaml(inventory_path)
532
+ except Exception as exc:
533
+ return [RuleRegistryFinding(str(INVENTORY_PATH), f"cannot load inventory: {exc}")]
534
+ try:
535
+ migrations = _load_yaml(migrations_path)
536
+ except Exception as exc:
537
+ return [RuleRegistryFinding(str(MIGRATIONS_PATH), f"cannot load migrations: {exc}")]
538
+ coverage_by_mechanism = _load_test_coverage_metadata(base, findings)
539
+ if inventory.get("schema_version") != 1:
540
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), "schema_version must be 1"))
541
+ if migrations.get("schema_version") != 1:
542
+ findings.append(RuleRegistryFinding(str(MIGRATIONS_PATH), "schema_version must be 1"))
543
+ mechanisms = _as_list(inventory.get("mechanisms"))
544
+ mechanism_ids: set[str] = set()
545
+ global_assertion_ids: dict[str, str] = {}
546
+ for mechanism in mechanisms:
547
+ mid = str(mechanism.get("id", ""))
548
+ if not mid:
549
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), "mechanism missing id"))
550
+ continue
551
+ if mid in mechanism_ids:
552
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"duplicate mechanism id: {mid}"))
553
+ mechanism_ids.add(mid)
554
+ if mechanism.get("status") != "active":
555
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mid}: status must be active"))
556
+ _validate_mechanism_metadata(mechanism, mid, findings)
557
+ _validate_string_list(
558
+ value=mechanism.get("conflict_domains"),
559
+ label="conflict_domains",
560
+ mechanism_id=mid,
561
+ required_non_empty=True,
562
+ findings=findings,
563
+ )
564
+ surfaces = _validate_string_list(
565
+ value=mechanism.get("surfaces"),
566
+ label="surfaces",
567
+ mechanism_id=mid,
568
+ required_non_empty=True,
569
+ findings=findings,
570
+ )
571
+ tests = _validate_string_list(
572
+ value=mechanism.get("tests"),
573
+ label="tests",
574
+ mechanism_id=mid,
575
+ required_non_empty=False,
576
+ findings=findings,
577
+ )
578
+ sources = _as_list(mechanism.get("sources"))
579
+ source_paths = {
580
+ str(source.get("path", "")).strip()
581
+ for source in sources
582
+ if isinstance(source, dict) and str(source.get("path", "")).strip()
583
+ }
584
+ coverage_entry = coverage_by_mechanism.get(mid, {})
585
+ coverage_view = dict(mechanism)
586
+ if "test_coverage" not in coverage_view and "test_coverage" in coverage_entry:
587
+ coverage_view["test_coverage"] = coverage_entry.get("test_coverage")
588
+ if "coverage_rationale" not in coverage_view and "coverage_rationale" in coverage_entry:
589
+ coverage_view["coverage_rationale"] = coverage_entry.get("coverage_rationale")
590
+ if "assertions" not in coverage_view and "assertions" in coverage_entry:
591
+ coverage_view["assertions"] = coverage_entry.get("assertions")
592
+ if coverage_metadata_present and mid not in coverage_by_mechanism and "test_coverage" not in mechanism:
593
+ pass
594
+ elif coverage_metadata_present or "test_coverage" in mechanism:
595
+ _validate_test_coverage(
596
+ coverage_view,
597
+ mid,
598
+ tests,
599
+ set(surfaces),
600
+ source_paths,
601
+ global_assertion_ids,
602
+ findings,
603
+ )
604
+ for test_path in tests:
605
+ if not (base / test_path).exists():
606
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mid}: missing test path: {test_path}"))
607
+ if not str(mechanism.get("protected_rule_intent", "")).strip():
608
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mid}: missing protected_rule_intent"))
609
+ if not sources:
610
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mid}: sources must list at least one source"))
611
+ for source in sources:
612
+ if not isinstance(source, dict):
613
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mid}: source entry must be a mapping"))
614
+ continue
615
+ rel = str(source.get("path", ""))
616
+ required_terms = _as_list(source.get("required_terms"))
617
+ if not required_terms:
618
+ label = rel if rel else "<missing path>"
619
+ findings.append(
620
+ RuleRegistryFinding(
621
+ str(INVENTORY_PATH),
622
+ f"{mid}: source {label} must list at least one required_terms entry",
623
+ )
624
+ )
625
+ source_path = base / rel
626
+ if not rel or not source_path.exists():
627
+ findings.append(RuleRegistryFinding(str(INVENTORY_PATH), f"{mid}: missing source path: {rel}"))
628
+ continue
629
+ text = source_path.read_text(encoding="utf-8")
630
+ for term in required_terms:
631
+ if str(term) not in text:
632
+ findings.append(RuleRegistryFinding(rel, f"{mid}: required term missing: {term}"))
633
+ _validate_mechanism_conflicts(mechanisms, findings)
634
+ if coverage_metadata_present:
635
+ for missing_id in sorted(mechanism_ids - set(coverage_by_mechanism)):
636
+ findings.append(
637
+ RuleRegistryFinding(
638
+ str(COVERAGE_PATH),
639
+ f"missing coverage entry for active mechanism: {missing_id}",
640
+ )
641
+ )
642
+ for coverage_id in sorted(set(coverage_by_mechanism) - mechanism_ids):
643
+ findings.append(
644
+ RuleRegistryFinding(
645
+ str(COVERAGE_PATH),
646
+ f"coverage entry references unknown mechanism: {coverage_id}",
647
+ )
648
+ )
649
+ _validate_direct_test_followup_plan(
650
+ base=base,
651
+ mechanisms=mechanisms,
652
+ coverage_by_mechanism=coverage_by_mechanism,
653
+ coverage_metadata_present=coverage_metadata_present,
654
+ findings=findings,
655
+ )
656
+ legacy_ids: set[str] = set()
657
+ for migration in _as_list(migrations.get("migrations")):
658
+ legacy_id = str(migration.get("legacy_id", ""))
659
+ if not legacy_id:
660
+ findings.append(RuleRegistryFinding(str(MIGRATIONS_PATH), "migration missing legacy_id"))
661
+ continue
662
+ if legacy_id in legacy_ids:
663
+ findings.append(RuleRegistryFinding(str(MIGRATIONS_PATH), f"duplicate legacy_id: {legacy_id}"))
664
+ legacy_ids.add(legacy_id)
665
+ status = migration.get("status")
666
+ if status not in VALID_MIGRATION_STATUSES:
667
+ findings.append(
668
+ RuleRegistryFinding(
669
+ str(MIGRATIONS_PATH),
670
+ f"{legacy_id}: status must be one of: {', '.join(sorted(VALID_MIGRATION_STATUSES))}",
671
+ )
672
+ )
673
+ if status == "migrated" and migration.get("replaced_by") not in mechanism_ids:
674
+ findings.append(RuleRegistryFinding(str(MIGRATIONS_PATH), f"{legacy_id}: replaced_by must reference an active mechanism"))
675
+ if status in TERMINAL_MIGRATION_STATUSES and migration.get("replaced_by"):
676
+ findings.append(
677
+ RuleRegistryFinding(
678
+ str(MIGRATIONS_PATH),
679
+ f"{legacy_id}: terminal migration status must not set replaced_by",
680
+ )
681
+ )
682
+ if not str(migration.get("migration_reason", "")).strip():
683
+ findings.append(RuleRegistryFinding(str(MIGRATIONS_PATH), f"{legacy_id}: missing migration_reason"))
684
+ evidence_entries = _as_list(migration.get("evidence"))
685
+ if not evidence_entries:
686
+ findings.append(
687
+ RuleRegistryFinding(
688
+ str(MIGRATIONS_PATH),
689
+ f"{legacy_id}: evidence must list at least one evidence path",
690
+ )
691
+ )
692
+ for evidence in evidence_entries:
693
+ if not (base / str(evidence)).exists():
694
+ findings.append(RuleRegistryFinding(str(MIGRATIONS_PATH), f"{legacy_id}: missing evidence path: {evidence}"))
695
+ _validate_migration_completeness(migrations, legacy_ids, findings)
696
+ return findings
697
+
698
+
699
+ def render_rule_registry_findings(findings: list[RuleRegistryFinding]) -> str:
700
+ if not findings:
701
+ return "Rule registry validation passed"
702
+ lines = ["Rule registry validation failed"]
703
+ lines.extend(f"[HARD-FAIL] {finding.path}: {finding.message}" for finding in findings)
704
+ return "\n".join(lines)