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,574 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ import json
5
+ from pathlib import Path
6
+ import subprocess
7
+ from typing import Any
8
+
9
+ from agentic_project_kit.workspace import load_workspace
10
+
11
+ DPA_REPO_ADOPTION_MODEL = "dpa-repo-adoption-assessment-v1"
12
+ DPA_REPO_ADOPTION_KIND = "dpa_repo_adoption_assessment"
13
+ DPA_CAPABLE_STATUS = "DPA_CAPABLE_WITH_FRESH_PER_REPO_ASSESSMENT"
14
+ READY_STATUS = "READY_FOR_DPA_REPO_ADOPTION_ADJUDICATION"
15
+ BLOCKED_STATUS = "BLOCKED_FOR_DPA_REPO_ADOPTION"
16
+ EVIDENCE_OUTPUT_ROOT_PARTS = ("evidence", "dpa", "assessment")
17
+
18
+ HIGH_AUTHORITY_CLASSIFICATIONS = frozenset(
19
+ {
20
+ "agent_instruction",
21
+ "architecture_authority",
22
+ "ci_workflow",
23
+ "command_updated_state",
24
+ "dpa_authority",
25
+ "generated_projection",
26
+ "handoff_authority",
27
+ "planning_authority",
28
+ "release_state",
29
+ "specification_authority",
30
+ "status_authority",
31
+ "workspace_manifest",
32
+ }
33
+ )
34
+
35
+ SCAN_SUFFIXES = frozenset(
36
+ {
37
+ ".cff",
38
+ ".json",
39
+ ".md",
40
+ ".toml",
41
+ ".yaml",
42
+ ".yml",
43
+ }
44
+ )
45
+
46
+ TOP_LEVEL_CANDIDATES = frozenset(
47
+ {
48
+ "AGENTS.md",
49
+ "ARCHITECTURE.md",
50
+ "CHANGELOG.md",
51
+ "CITATION.cff",
52
+ "Format-Memory.md",
53
+ "MODULARIZATION.md",
54
+ "README.md",
55
+ "codemeta.json",
56
+ "package.json",
57
+ "pyproject.toml",
58
+ }
59
+ )
60
+
61
+ SPECIFICATION_DIRS = (
62
+ "JSON",
63
+ "json",
64
+ "spec",
65
+ "specs",
66
+ )
67
+
68
+ EXCLUDED_DIRS = frozenset(
69
+ {
70
+ ".git",
71
+ ".mypy_cache",
72
+ ".pytest_cache",
73
+ ".ruff_cache",
74
+ ".venv",
75
+ "__pycache__",
76
+ "build",
77
+ "dist",
78
+ "node_modules",
79
+ }
80
+ )
81
+
82
+
83
+ @dataclass(frozen=True)
84
+ class DpaRepoAdoptionFinding:
85
+ code: str
86
+ message: str
87
+ path: str
88
+ severity: str = "blocker"
89
+
90
+ def as_dict(self) -> dict[str, str]:
91
+ return {
92
+ "code": self.code,
93
+ "message": self.message,
94
+ "path": self.path,
95
+ "severity": self.severity,
96
+ }
97
+
98
+
99
+ @dataclass(frozen=True)
100
+ class DpaRepoAdoptionSurface:
101
+ path: str
102
+ classification: str
103
+ document_form: str
104
+ source_authority: str
105
+ writer: str
106
+ reader: str
107
+ target_identity: str
108
+ dpa_600_evidence: str
109
+ dpa_700_evidence: str
110
+ recommendation: str
111
+ maintainer_adjudication_required: bool
112
+ generated_or_command_updated: bool
113
+
114
+ def as_dict(self) -> dict[str, Any]:
115
+ return {
116
+ "path": self.path,
117
+ "classification": self.classification,
118
+ "document_form": self.document_form,
119
+ "source_authority": self.source_authority,
120
+ "writer": self.writer,
121
+ "reader": self.reader,
122
+ "target_identity": self.target_identity,
123
+ "dpa_600_evidence": self.dpa_600_evidence,
124
+ "dpa_700_evidence": self.dpa_700_evidence,
125
+ "recommendation": self.recommendation,
126
+ "maintainer_adjudication_required": self.maintainer_adjudication_required,
127
+ "generated_or_command_updated": self.generated_or_command_updated,
128
+ }
129
+
130
+
131
+ @dataclass(frozen=True)
132
+ class DpaRepoAdoptionAssessment:
133
+ root: str
134
+ current_validation_ref: str
135
+ surfaces: tuple[DpaRepoAdoptionSurface, ...]
136
+ findings: tuple[DpaRepoAdoptionFinding, ...]
137
+
138
+ @property
139
+ def blocker_count(self) -> int:
140
+ return sum(1 for finding in self.findings if finding.severity == "blocker")
141
+
142
+ @property
143
+ def warning_count(self) -> int:
144
+ return sum(1 for finding in self.findings if finding.severity == "warning")
145
+
146
+ @property
147
+ def high_authority_surface_count(self) -> int:
148
+ return sum(
149
+ 1 for surface in self.surfaces if surface.classification in HIGH_AUTHORITY_CLASSIFICATIONS
150
+ )
151
+
152
+ @property
153
+ def generated_or_command_updated_surface_count(self) -> int:
154
+ return sum(1 for surface in self.surfaces if surface.generated_or_command_updated)
155
+
156
+ @property
157
+ def manual_preservation_surface_count(self) -> int:
158
+ return sum(1 for surface in self.surfaces if surface.maintainer_adjudication_required)
159
+
160
+ @property
161
+ def result_status(self) -> str:
162
+ return BLOCKED_STATUS if self.blocker_count else READY_STATUS
163
+
164
+ @property
165
+ def ok(self) -> bool:
166
+ return self.blocker_count == 0
167
+
168
+ def as_dict(self) -> dict[str, Any]:
169
+ return {
170
+ "schema_version": 1,
171
+ "kind": DPA_REPO_ADOPTION_KIND,
172
+ "assessment_model": DPA_REPO_ADOPTION_MODEL,
173
+ "result_status": self.result_status,
174
+ "root": self.root,
175
+ "current_validation_ref": self.current_validation_ref,
176
+ "surface_count": len(self.surfaces),
177
+ "high_authority_surface_count": self.high_authority_surface_count,
178
+ "manual_preservation_surface_count": self.manual_preservation_surface_count,
179
+ "generated_or_command_updated_surface_count": (
180
+ self.generated_or_command_updated_surface_count
181
+ ),
182
+ "blocker_count": self.blocker_count,
183
+ "warning_count": self.warning_count,
184
+ "findings": [finding.as_dict() for finding in self.findings],
185
+ "surfaces": [surface.as_dict() for surface in self.surfaces],
186
+ "foreign_repo_management": {
187
+ "status": DPA_CAPABLE_STATUS,
188
+ "fresh_per_repo_inventory_recorded": True,
189
+ "source_authority_inventory_recorded": True,
190
+ "target_identity_inventory_recorded": True,
191
+ "dpa_600_700_assessment_recorded": True,
192
+ "requires_maintainer_authorized_scope": True,
193
+ "automatic_external_repo_conformance_claimed": False,
194
+ },
195
+ "claims": {
196
+ "kit_wide_dpa_conformance_claimed": False,
197
+ "stable_dpa_claimed": False,
198
+ "external_repo_conformance_claimed": False,
199
+ "automatic_migration_performed": False,
200
+ "production_mutation_performed": False,
201
+ },
202
+ }
203
+
204
+
205
+ def evaluate_dpa_repo_adoption_assessment(
206
+ root: Path | str = ".",
207
+ *,
208
+ validation_ref: str | None = None,
209
+ ) -> DpaRepoAdoptionAssessment:
210
+ base = Path(root).resolve()
211
+ findings: list[DpaRepoAdoptionFinding] = []
212
+ if not base.exists() or not base.is_dir():
213
+ findings.append(
214
+ DpaRepoAdoptionFinding(
215
+ code="root-not-directory",
216
+ message="target repository root must be an existing directory",
217
+ path=base.as_posix(),
218
+ )
219
+ )
220
+ return DpaRepoAdoptionAssessment(
221
+ root=base.as_posix(),
222
+ current_validation_ref="UNKNOWN",
223
+ surfaces=(),
224
+ findings=tuple(findings),
225
+ )
226
+
227
+ current_ref = _current_validation_ref(base, validation_ref, findings)
228
+ _agentic_collision_findings(base, findings)
229
+ surfaces = tuple(_classify_surface(path, base) for path in _candidate_paths(base))
230
+ return DpaRepoAdoptionAssessment(
231
+ root=base.as_posix(),
232
+ current_validation_ref=current_ref,
233
+ surfaces=surfaces,
234
+ findings=tuple(findings),
235
+ )
236
+
237
+
238
+ def render_dpa_repo_adoption_assessment(result: DpaRepoAdoptionAssessment) -> str:
239
+ payload = result.as_dict()
240
+ lines = [
241
+ "DPA_REPO_ADOPTION_ASSESSMENT",
242
+ f"STATUS={payload['result_status']}",
243
+ f"ROOT={payload['root']}",
244
+ f"CURRENT_VALIDATION_REF={payload['current_validation_ref']}",
245
+ f"SURFACES={payload['surface_count']}",
246
+ f"HIGH_AUTHORITY_SURFACES={payload['high_authority_surface_count']}",
247
+ f"MANUAL_PRESERVATION_SURFACES={payload['manual_preservation_surface_count']}",
248
+ "GENERATED_OR_COMMAND_UPDATED_SURFACES="
249
+ f"{payload['generated_or_command_updated_surface_count']}",
250
+ f"BLOCKERS={payload['blocker_count']}",
251
+ f"WARNINGS={payload['warning_count']}",
252
+ f"FOREIGN_REPO_STATUS={payload['foreign_repo_management']['status']}",
253
+ "EXTERNAL_REPO_CONFORMANCE_CLAIMED="
254
+ f"{str(payload['claims']['external_repo_conformance_claimed']).lower()}",
255
+ "AUTOMATIC_MIGRATION_PERFORMED="
256
+ f"{str(payload['claims']['automatic_migration_performed']).lower()}",
257
+ "NEXT=maintainer-adjudicate bounded scope before migration, strict gates, or conformance claims",
258
+ ]
259
+ for classification, count in _classification_counts(result.surfaces).items():
260
+ lines.append(f"CLASSIFICATION={classification}|count={count}")
261
+ for surface in result.surfaces[:50]:
262
+ lines.append(
263
+ "SURFACE="
264
+ f"{surface.path}|class={surface.classification}|form={surface.document_form}|"
265
+ f"dpa600={surface.dpa_600_evidence}|dpa700={surface.dpa_700_evidence}"
266
+ )
267
+ if len(result.surfaces) > 50:
268
+ lines.append(f"SURFACE_TRUNCATED={len(result.surfaces) - 50}")
269
+ for finding in result.findings:
270
+ lines.append(
271
+ f"FINDING={finding.severity}|{finding.code}|path={finding.path}|{finding.message}"
272
+ )
273
+ return "\n".join(lines) + "\n"
274
+
275
+
276
+ def write_dpa_repo_adoption_assessment_json(
277
+ result: DpaRepoAdoptionAssessment,
278
+ root: Path | str,
279
+ output: Path | str,
280
+ *,
281
+ execute: bool,
282
+ ) -> dict[str, Any]:
283
+ base = Path(root).resolve()
284
+ output_path = _resolve_under_root(base, output)
285
+ try:
286
+ relative = output_path.relative_to(base)
287
+ except ValueError:
288
+ return {
289
+ "result_status": "BLOCK",
290
+ "reason": "output_outside_repository_root",
291
+ "output_path": output_path.as_posix(),
292
+ "written": False,
293
+ }
294
+ evidence_root = _evidence_output_root(base)
295
+ if evidence_root not in (output_path, *output_path.parents):
296
+ return {
297
+ "result_status": "BLOCK",
298
+ "reason": "output_outside_dpa_assessment_evidence_root",
299
+ "output_path": relative.as_posix(),
300
+ "written": False,
301
+ }
302
+ rendered = json.dumps(result.as_dict(), indent=2, sort_keys=True) + "\n"
303
+ changed = True
304
+ if output_path.exists():
305
+ changed = output_path.read_text(encoding="utf-8") != rendered
306
+ if execute:
307
+ output_path.parent.mkdir(parents=True, exist_ok=True)
308
+ output_path.write_text(rendered, encoding="utf-8")
309
+ return {
310
+ "result_status": "PASS",
311
+ "output_path": relative.as_posix(),
312
+ "changed": changed,
313
+ "written": bool(execute),
314
+ }
315
+
316
+
317
+ def dpa_repo_adoption_evidence_output_root(root: Path | str) -> Path:
318
+ return _evidence_output_root(Path(root).resolve())
319
+
320
+
321
+ def _candidate_paths(root: Path) -> tuple[Path, ...]:
322
+ candidates: set[Path] = set()
323
+ for relative in TOP_LEVEL_CANDIDATES:
324
+ path = root / relative
325
+ if path.is_file() and not path.is_symlink():
326
+ candidates.add(path)
327
+ for path in root.iterdir():
328
+ if path.is_file() and not path.is_symlink() and _is_candidate_file(path):
329
+ candidates.add(path)
330
+ for directory in ("docs", ".agentic", ".github/workflows", *SPECIFICATION_DIRS):
331
+ base = root / directory
332
+ if not base.exists():
333
+ continue
334
+ if base.is_file() and _is_candidate_file(base):
335
+ candidates.add(base)
336
+ continue
337
+ if not base.is_dir():
338
+ continue
339
+ for path in base.rglob("*"):
340
+ if not path.is_file() or path.is_symlink() or not _is_candidate_file(path):
341
+ continue
342
+ if _is_excluded(path, root):
343
+ continue
344
+ candidates.add(path)
345
+ return tuple(sorted(candidates, key=lambda path: path.relative_to(root).as_posix()))
346
+
347
+
348
+ def _is_candidate_file(path: Path) -> bool:
349
+ return path.name in TOP_LEVEL_CANDIDATES or path.suffix.lower() in SCAN_SUFFIXES
350
+
351
+
352
+ def _is_excluded(path: Path, root: Path) -> bool:
353
+ try:
354
+ parts = path.relative_to(root).parts
355
+ except ValueError:
356
+ return True
357
+ return any(part in EXCLUDED_DIRS for part in parts) or parts[:2] == (".agentic", "tmp")
358
+
359
+
360
+ def _classify_surface(path: Path, root: Path) -> DpaRepoAdoptionSurface:
361
+ relative = path.relative_to(root).as_posix()
362
+ classification = _classification(relative)
363
+ document_form = _document_form(classification, path)
364
+ generated = classification in {"command_updated_state", "generated_projection"}
365
+ return DpaRepoAdoptionSurface(
366
+ path=relative,
367
+ classification=classification,
368
+ document_form=document_form,
369
+ source_authority=_source_authority(classification),
370
+ writer=_writer(classification),
371
+ reader=_reader(classification),
372
+ target_identity=f"repo:{relative}",
373
+ dpa_600_evidence=_dpa_600_evidence(classification),
374
+ dpa_700_evidence=_dpa_700_evidence(classification),
375
+ recommendation=_recommendation(classification),
376
+ maintainer_adjudication_required=not generated,
377
+ generated_or_command_updated=generated,
378
+ )
379
+
380
+
381
+ def _classification(relative: str) -> str:
382
+ if relative == ".agentic/config.yaml":
383
+ return "workspace_manifest"
384
+ if relative in {"docs/STATUS.md", ".agentic/state/status.md"}:
385
+ return "status_authority"
386
+ if relative in {"docs/handoff/CURRENT_HANDOFF.md", ".agentic/state/handoff/README.md"}:
387
+ return "handoff_authority"
388
+ if relative.startswith(".agentic/state/handoff/packages/"):
389
+ return "generated_projection"
390
+ if relative.startswith(".agentic/state/handoff/") and relative.endswith((".json", ".yaml")):
391
+ return "generated_projection"
392
+ if relative.startswith("docs/reports/handoff-packages/"):
393
+ return "generated_projection"
394
+ if relative.startswith("docs/reports/terminal/") or relative.startswith("docs/reports/transfer_runs/"):
395
+ return "generated_projection"
396
+ if relative.startswith(".agentic/state/") or relative.startswith(".agentic/registries/"):
397
+ return "command_updated_state"
398
+ if relative.startswith(".github/workflows/"):
399
+ return "ci_workflow"
400
+ if relative == "AGENTS.md":
401
+ return "agent_instruction"
402
+ if relative in {"CHANGELOG.md", "CITATION.cff", "codemeta.json"}:
403
+ return "release_state"
404
+ if relative in {"Format-Memory.md"} or relative.startswith(
405
+ tuple(f"{directory}/" for directory in SPECIFICATION_DIRS)
406
+ ):
407
+ return "specification_authority"
408
+ if relative in {"ARCHITECTURE.md", "MODULARIZATION.md"}:
409
+ return "architecture_authority"
410
+ if relative.startswith("docs/architecture/dpa/"):
411
+ return "dpa_authority"
412
+ if relative.startswith("docs/architecture/"):
413
+ return "architecture_authority"
414
+ if relative.startswith("docs/planning/"):
415
+ return "planning_authority"
416
+ if relative == "README.md" or (
417
+ relative.startswith("README.") and relative.endswith(".md")
418
+ ):
419
+ return "onboarding_document"
420
+ if relative in {"pyproject.toml", "package.json"}:
421
+ return "project_config"
422
+ if relative.startswith("docs/"):
423
+ return "manual_document"
424
+ return "structured_or_manual_document"
425
+
426
+
427
+ def _document_form(classification: str, path: Path) -> str:
428
+ if classification == "generated_projection":
429
+ return "generated_projection"
430
+ if classification == "command_updated_state":
431
+ return "command_updated_state"
432
+ if classification == "status_authority":
433
+ return "status_authority_document"
434
+ if classification == "handoff_authority":
435
+ return "handoff_authority_document"
436
+ if classification == "ci_workflow":
437
+ return "structured_workflow"
438
+ if classification in {"workspace_manifest", "project_config", "release_state"}:
439
+ return "structured_config" if path.suffix.lower() != ".md" else "manual_document"
440
+ if classification == "specification_authority":
441
+ return "authority_document" if path.suffix.lower() == ".md" else "structured_specification"
442
+ if classification.endswith("_authority") or classification == "agent_instruction":
443
+ return "authority_document"
444
+ if path.suffix.lower() == ".md":
445
+ return "manual_document"
446
+ return "structured_config"
447
+
448
+
449
+ def _source_authority(classification: str) -> str:
450
+ if classification == "generated_projection":
451
+ return "owning generator command"
452
+ if classification == "command_updated_state":
453
+ return "agentic-kit command"
454
+ if classification == "workspace_manifest":
455
+ return "workspace manifest owner"
456
+ if classification == "ci_workflow":
457
+ return "repository CI owner"
458
+ return "maintainer"
459
+
460
+
461
+ def _writer(classification: str) -> str:
462
+ if classification == "generated_projection":
463
+ return "owning generator command only"
464
+ if classification == "command_updated_state":
465
+ return "agentic-kit command only"
466
+ if classification == "ci_workflow":
467
+ return "reviewed CI workflow change"
468
+ return "human or coding agent through reviewed change"
469
+
470
+
471
+ def _reader(classification: str) -> str:
472
+ if classification == "ci_workflow":
473
+ return "GitHub Actions"
474
+ if classification == "workspace_manifest":
475
+ return "agentic-kit workspace loader"
476
+ if classification in {"status_authority", "handoff_authority"}:
477
+ return "maintainers and coding agents"
478
+ if classification == "generated_projection":
479
+ return "handoff workflow and coding agents"
480
+ return "maintainers, users, and coding agents"
481
+
482
+
483
+ def _dpa_600_evidence(classification: str) -> str:
484
+ if classification in {"generated_projection", "command_updated_state", "workspace_manifest"}:
485
+ return "serialize with owning command, workspace lock, exact ref, and PR head"
486
+ if classification == "ci_workflow":
487
+ return "serialize branch/PR workflow changes with exact head and rollback plan"
488
+ return "serialize by branch, review, exact ref, and no concurrent authority edit"
489
+
490
+
491
+ def _dpa_700_evidence(classification: str) -> str:
492
+ if classification == "generated_projection":
493
+ return "no manual migration; regenerate from owning source"
494
+ if classification in {"command_updated_state", "workspace_manifest"}:
495
+ return "command-only migration or no-migration adjudication"
496
+ if classification == "ci_workflow":
497
+ return "bounded rollout with rollback or no-migration adjudication"
498
+ return "manual preservation adjudication before migration"
499
+
500
+
501
+ def _recommendation(classification: str) -> str:
502
+ if classification == "generated_projection":
503
+ return "preserve generator/source authority; do not patch generated output manually"
504
+ if classification == "command_updated_state":
505
+ return "use owning agentic-kit command for updates"
506
+ if classification in {"status_authority", "handoff_authority"}:
507
+ return "require maintainer-adjudicated preservation before adoption"
508
+ if classification == "ci_workflow":
509
+ return "adopt only through bounded workflow rollout with rollback"
510
+ return "review as manual source during per-repo DPA scope adjudication"
511
+
512
+
513
+ def _classification_counts(
514
+ surfaces: tuple[DpaRepoAdoptionSurface, ...],
515
+ ) -> dict[str, int]:
516
+ counts: dict[str, int] = {}
517
+ for surface in surfaces:
518
+ counts[surface.classification] = counts.get(surface.classification, 0) + 1
519
+ return dict(sorted(counts.items()))
520
+
521
+
522
+ def _current_validation_ref(
523
+ root: Path,
524
+ validation_ref: str | None,
525
+ findings: list[DpaRepoAdoptionFinding],
526
+ ) -> str:
527
+ explicit = validation_ref.strip() if isinstance(validation_ref, str) else ""
528
+ if explicit:
529
+ return explicit
530
+ completed = subprocess.run(
531
+ ["git", "rev-parse", "HEAD"],
532
+ cwd=root,
533
+ text=True,
534
+ capture_output=True,
535
+ check=False,
536
+ )
537
+ if completed.returncode == 0 and completed.stdout.strip():
538
+ return completed.stdout.strip()
539
+ findings.append(
540
+ DpaRepoAdoptionFinding(
541
+ code="exact-ref-missing",
542
+ message="DPA repo adoption assessment requires an exact current validation ref",
543
+ path=".",
544
+ )
545
+ )
546
+ return "UNKNOWN"
547
+
548
+
549
+ def _agentic_collision_findings(root: Path, findings: list[DpaRepoAdoptionFinding]) -> None:
550
+ agentic = root / ".agentic"
551
+ manifest = agentic / "config.yaml"
552
+ if agentic.exists() and not manifest.exists():
553
+ findings.append(
554
+ DpaRepoAdoptionFinding(
555
+ code="foreign-agentic-directory",
556
+ message="foreign .agentic/ directory requires maintainer diagnosis before init/adoption",
557
+ path=".agentic",
558
+ )
559
+ )
560
+
561
+
562
+ def _resolve_under_root(root: Path, path: Path | str) -> Path:
563
+ candidate = Path(path)
564
+ if candidate.is_absolute():
565
+ return candidate
566
+ return root / candidate
567
+
568
+
569
+ def _evidence_output_root(root: Path) -> Path:
570
+ try:
571
+ workspace = load_workspace(root, suppress_legacy_profile_warning=True)
572
+ except RuntimeError:
573
+ return root.joinpath("docs", "architecture", "evidence", "dpa", "assessment")
574
+ return workspace.architecture_file(Path(*EVIDENCE_OUTPUT_ROOT_PARTS)).resolve()