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,381 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path
5
+ from typing import Literal
6
+
7
+ from agentic_project_kit.workspace import load_workspace
8
+ from agentic_project_kit.workspace_adopt import ProjectSuggestion, WORKSPACE_INIT_TREE
9
+ from agentic_project_kit.workspace_init import (
10
+ CI_INJECTION_TARGET,
11
+ CI_TEMPLATE_PATH,
12
+ MANAGED_CI_HEADER,
13
+ MANAGED_PRE_COMMIT_HEADER,
14
+ PRE_COMMIT_INJECTION_TARGET,
15
+ PRE_COMMIT_TEMPLATE_PATH,
16
+ workspace_init_generated_files,
17
+ workspace_init_manifest_yaml,
18
+ )
19
+ from agentic_project_kit.workspace_lock import acquire_workspace_lock
20
+
21
+
22
+ WorkspaceRemoveStatus = Literal["PASS", "BLOCKED", "NOOP"]
23
+
24
+ VOLATILE_RUNTIME_FILES = frozenset({".agentic/tmp/workspace.lock"})
25
+ GENERATED_RUNTIME_FILE_MARKERS = {
26
+ ".agentic/INITIAL_LLM_PROMPT.md": ("# Initial LLM Prompt", "Command manifest entrypoint:"),
27
+ }
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class WorkspaceRemoveFinding:
32
+ path: str
33
+ reason: str
34
+
35
+ def as_json_data(self) -> dict[str, str]:
36
+ return {"path": self.path, "reason": self.reason}
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class WorkspaceRemovePlan:
41
+ root: Path
42
+ execute: bool
43
+ result_status: WorkspaceRemoveStatus
44
+ files_to_remove: tuple[str, ...]
45
+ directories_to_prune: tuple[str, ...]
46
+ blockers: tuple[WorkspaceRemoveFinding, ...]
47
+ ignored_paths: tuple[WorkspaceRemoveFinding, ...]
48
+ message: str
49
+
50
+ @property
51
+ def ok(self) -> bool:
52
+ return self.result_status in {"PASS", "NOOP"}
53
+
54
+ def as_json_data(self, *, written: bool = False) -> dict[str, object]:
55
+ return {
56
+ "schema_version": 1,
57
+ "kind": "workspace_remove_plan",
58
+ "root": self.root.as_posix(),
59
+ "result_status": self.result_status,
60
+ "mode": "execute" if self.execute else "dry-run",
61
+ "written": written,
62
+ "message": self.message,
63
+ "files_to_remove": list(self.files_to_remove),
64
+ "directories_to_prune": list(self.directories_to_prune),
65
+ "blockers": [finding.as_json_data() for finding in self.blockers],
66
+ "ignored_paths": [finding.as_json_data() for finding in self.ignored_paths],
67
+ "safety": {
68
+ "dry_run_default": True,
69
+ "removes_only_exact_kit_generated_files": True,
70
+ "unknown_or_modified_paths_block_execute": True,
71
+ "does_not_remove_project_docs_or_source": True,
72
+ },
73
+ "final_signal": "d" if self.ok else "f",
74
+ }
75
+
76
+
77
+ class WorkspaceRemoveError(RuntimeError):
78
+ def __init__(self, message: str, *, code: str = "FAIL") -> None:
79
+ super().__init__(message)
80
+ self.code = code
81
+
82
+
83
+ def build_workspace_remove_plan(
84
+ root: Path | str = Path("."),
85
+ *,
86
+ execute: bool = False,
87
+ ) -> WorkspaceRemovePlan:
88
+ root_path = Path(root)
89
+ manifest_path = root_path / ".agentic" / "config.yaml"
90
+ agentic_path = root_path / ".agentic"
91
+ if not manifest_path.exists():
92
+ if not agentic_path.exists():
93
+ return WorkspaceRemovePlan(
94
+ root=root_path,
95
+ execute=execute,
96
+ result_status="NOOP",
97
+ files_to_remove=(),
98
+ directories_to_prune=(),
99
+ blockers=(),
100
+ ignored_paths=(),
101
+ message="no workspace manifest or .agentic directory; nothing to remove",
102
+ )
103
+ return WorkspaceRemovePlan(
104
+ root=root_path,
105
+ execute=execute,
106
+ result_status="BLOCKED",
107
+ files_to_remove=(),
108
+ directories_to_prune=(),
109
+ blockers=(
110
+ WorkspaceRemoveFinding(
111
+ ".agentic",
112
+ "foreign_agentic_without_workspace_manifest",
113
+ ),
114
+ ),
115
+ ignored_paths=(),
116
+ message="foreign .agentic directory without kit manifest; refusing workspace remove",
117
+ )
118
+
119
+ try:
120
+ workspace = load_workspace(root_path)
121
+ except RuntimeError as exc:
122
+ return WorkspaceRemovePlan(
123
+ root=root_path,
124
+ execute=execute,
125
+ result_status="BLOCKED",
126
+ files_to_remove=(),
127
+ directories_to_prune=(),
128
+ blockers=(WorkspaceRemoveFinding(".agentic/config.yaml", f"invalid_manifest: {exc}"),),
129
+ ignored_paths=(),
130
+ message="workspace manifest is invalid; fix or inspect it before removal",
131
+ )
132
+
133
+ project = ProjectSuggestion(
134
+ name=workspace.project_name or root_path.name,
135
+ type=workspace.project_type,
136
+ profile=workspace.profile,
137
+ )
138
+ expected_files = workspace_init_generated_files(
139
+ root_path,
140
+ project,
141
+ manifest_yaml=workspace_init_manifest_yaml(project),
142
+ )
143
+ expected_files = {
144
+ path: content
145
+ for path, content in expected_files.items()
146
+ if path.startswith(".agentic/")
147
+ }
148
+ generated_runtime_files = _generated_runtime_file_markers(workspace)
149
+ known_files = set(expected_files) | set(VOLATILE_RUNTIME_FILES) | set(generated_runtime_files)
150
+ known_directories = {
151
+ path.rstrip("/")
152
+ for path in WORKSPACE_INIT_TREE
153
+ if path.rstrip("/").startswith(".agentic") and path.endswith("/")
154
+ }
155
+ for relative_path in set(expected_files) | set(generated_runtime_files):
156
+ for parent in Path(relative_path).parents:
157
+ parent_text = parent.as_posix()
158
+ if parent_text == ".":
159
+ break
160
+ if parent_text.startswith(".agentic"):
161
+ known_directories.add(parent_text)
162
+
163
+ files_to_remove: list[str] = []
164
+ blockers: list[WorkspaceRemoveFinding] = []
165
+ ignored: list[WorkspaceRemoveFinding] = []
166
+
167
+ for relative_path, expected_text in sorted(expected_files.items()):
168
+ path = root_path / relative_path
169
+ if not path.exists():
170
+ continue
171
+ if not path.is_file():
172
+ blockers.append(WorkspaceRemoveFinding(relative_path, "expected_file_is_not_file"))
173
+ continue
174
+ try:
175
+ current_text = path.read_text(encoding="utf-8")
176
+ except OSError as exc:
177
+ blockers.append(WorkspaceRemoveFinding(relative_path, f"read_failed: {exc}"))
178
+ continue
179
+ if current_text == expected_text:
180
+ files_to_remove.append(relative_path)
181
+ elif _matches_generated_runtime_markers(
182
+ relative_path,
183
+ current_text,
184
+ generated_runtime_files,
185
+ ):
186
+ files_to_remove.append(relative_path)
187
+ else:
188
+ blockers.append(WorkspaceRemoveFinding(relative_path, "modified_generated_file"))
189
+
190
+ for relative_path, expected_text in _managed_injection_targets(expected_files).items():
191
+ path = root_path / relative_path
192
+ if not path.exists():
193
+ continue
194
+ if not path.is_file():
195
+ blockers.append(WorkspaceRemoveFinding(relative_path, "managed_injection_target_not_file"))
196
+ continue
197
+ try:
198
+ current_text = path.read_text(encoding="utf-8")
199
+ except OSError as exc:
200
+ blockers.append(WorkspaceRemoveFinding(relative_path, f"read_failed: {exc}"))
201
+ continue
202
+ if current_text == expected_text:
203
+ files_to_remove.append(relative_path)
204
+ elif current_text.startswith(expected_text.splitlines()[0] + "\n"):
205
+ blockers.append(WorkspaceRemoveFinding(relative_path, "modified_managed_injection"))
206
+ else:
207
+ ignored.append(WorkspaceRemoveFinding(relative_path, "not_managed_by_workspace_init"))
208
+
209
+ if agentic_path.exists():
210
+ for path in sorted(agentic_path.rglob("*")):
211
+ relative_path = path.relative_to(root_path).as_posix()
212
+ if path.is_file() and relative_path in generated_runtime_files:
213
+ try:
214
+ current_text = path.read_text(encoding="utf-8")
215
+ except OSError as exc:
216
+ blockers.append(WorkspaceRemoveFinding(relative_path, f"read_failed: {exc}"))
217
+ continue
218
+ if _matches_generated_runtime_markers(
219
+ relative_path,
220
+ current_text,
221
+ generated_runtime_files,
222
+ ):
223
+ files_to_remove.append(relative_path)
224
+ elif relative_path not in expected_files:
225
+ blockers.append(WorkspaceRemoveFinding(relative_path, "invalid_generated_runtime_file"))
226
+ elif path.is_file() and relative_path not in known_files:
227
+ blockers.append(WorkspaceRemoveFinding(relative_path, "unknown_agentic_file"))
228
+ elif path.is_dir() and relative_path not in known_directories:
229
+ blockers.append(WorkspaceRemoveFinding(relative_path, "unknown_agentic_directory"))
230
+
231
+ directories_to_prune = tuple(
232
+ sorted(
233
+ (path for path in known_directories if (root_path / path).exists()),
234
+ key=lambda value: (value.count("/"), value),
235
+ reverse=True,
236
+ )
237
+ )
238
+ result_status: WorkspaceRemoveStatus = "BLOCKED" if blockers else "PASS"
239
+ message = (
240
+ "workspace remove is ready"
241
+ if result_status == "PASS"
242
+ else "workspace remove blocked by modified or unknown workspace paths"
243
+ )
244
+ return WorkspaceRemovePlan(
245
+ root=root_path,
246
+ execute=execute,
247
+ result_status=result_status,
248
+ files_to_remove=tuple(dict.fromkeys(files_to_remove)),
249
+ directories_to_prune=directories_to_prune,
250
+ blockers=tuple(blockers),
251
+ ignored_paths=tuple(ignored),
252
+ message=message,
253
+ )
254
+
255
+
256
+ def execute_workspace_remove(plan: WorkspaceRemovePlan) -> None:
257
+ if plan.result_status == "NOOP":
258
+ return
259
+ if plan.result_status != "PASS":
260
+ raise WorkspaceRemoveError(plan.message, code="BLOCKED")
261
+ with acquire_workspace_lock(plan.root, "workspace_remove"):
262
+ current = build_workspace_remove_plan(plan.root, execute=True)
263
+ if current.result_status != "PASS":
264
+ raise WorkspaceRemoveError(current.message, code="PLAN_CHANGED")
265
+ for relative_path in current.files_to_remove:
266
+ path = current.root / relative_path
267
+ try:
268
+ path.unlink()
269
+ except FileNotFoundError:
270
+ continue
271
+ directories_to_prune = current.directories_to_prune
272
+ for relative_path in directories_to_prune:
273
+ path = plan.root / relative_path
274
+ try:
275
+ path.rmdir()
276
+ except OSError:
277
+ continue
278
+
279
+
280
+ def render_workspace_remove_plan(plan: WorkspaceRemovePlan, *, written: bool = False) -> str:
281
+ lines = [
282
+ "WORKSPACE_REMOVE",
283
+ f"STATUS={plan.result_status}",
284
+ f"MODE={'execute' if plan.execute else 'dry-run'}",
285
+ f"WRITTEN={str(written).lower()}",
286
+ f"ROOT={plan.root.as_posix()}",
287
+ f"MESSAGE={plan.message}",
288
+ "",
289
+ "Files to remove:",
290
+ ]
291
+ if plan.files_to_remove:
292
+ lines.extend(f"- {path}" for path in plan.files_to_remove)
293
+ else:
294
+ lines.append("- none")
295
+ lines.extend(["", "Directories to prune if empty:"])
296
+ if plan.directories_to_prune:
297
+ lines.extend(f"- {path}" for path in plan.directories_to_prune)
298
+ else:
299
+ lines.append("- none")
300
+ lines.extend(["", "Blockers:"])
301
+ if plan.blockers:
302
+ lines.extend(f"- {item.path}: {item.reason}" for item in plan.blockers)
303
+ else:
304
+ lines.append("- none")
305
+ lines.extend(
306
+ [
307
+ "",
308
+ "Safety:",
309
+ "- dry-run by default",
310
+ "- removes only exact Kit-generated workspace files",
311
+ "- modified or unknown .agentic paths block execution",
312
+ "- project docs and source files are preserved",
313
+ ]
314
+ )
315
+ return "\n".join(lines) + "\n"
316
+
317
+
318
+ def render_workspace_remove_error(error: WorkspaceRemoveError) -> str:
319
+ return f"WORKSPACE_REMOVE\nSTATUS=FAIL\nCODE={error.code}\nERROR={error}\n"
320
+
321
+
322
+ def _managed_injection_targets(expected_files: dict[str, str]) -> dict[str, str]:
323
+ return {
324
+ CI_INJECTION_TARGET: MANAGED_CI_HEADER + "\n" + expected_files[CI_TEMPLATE_PATH],
325
+ PRE_COMMIT_INJECTION_TARGET: (
326
+ MANAGED_PRE_COMMIT_HEADER + "\n" + expected_files[PRE_COMMIT_TEMPLATE_PATH]
327
+ ),
328
+ }
329
+
330
+
331
+ def _generated_runtime_file_markers(workspace) -> dict[str, tuple[str, ...]]:
332
+ def path_text(path: Path) -> str:
333
+ return workspace.path_text(path)
334
+
335
+ markers = dict(GENERATED_RUNTIME_FILE_MARKERS)
336
+ markers.update(
337
+ {
338
+ path_text(workspace.handoff_file("START_NEW_CHAT_PROMPT.md")): (
339
+ "artifact_type: chat_switch_prompt",
340
+ "role: start_new_chat",
341
+ ),
342
+ path_text(workspace.handoff_file("CLOSEOUT_BEFORE_CHAT_SWITCH_PROMPT.md")): (
343
+ "artifact_type: chat_switch_prompt",
344
+ "role: closeout_before_chat_switch",
345
+ ),
346
+ path_text(workspace.handoff_file("NEXT_CHAT_BOOTSTRAP.md")): (
347
+ "# NEXT CHAT BOOTSTRAP",
348
+ "successor_context.yaml",
349
+ ),
350
+ path_text(workspace.package_file("successor_context.yaml")): (
351
+ "successor_chat_context",
352
+ "generated_by",
353
+ ),
354
+ path_text(workspace.package_file("source_manifest.json")): (
355
+ "successor_source_manifest",
356
+ '"sources"',
357
+ ),
358
+ path_text(workspace.package_file("validation_report.json")): (
359
+ "successor_handoff_validation_report",
360
+ '"status"',
361
+ ),
362
+ path_text(workspace.package_file("execution_contract.json")): (
363
+ '"command_reference"',
364
+ '"bootstrap_acceptance_gate"',
365
+ ),
366
+ path_text(workspace.package_file("successor_prompt.md")): (
367
+ "Machine-readable execution contract",
368
+ "# Successor Chat Prompt",
369
+ ),
370
+ }
371
+ )
372
+ return markers
373
+
374
+
375
+ def _matches_generated_runtime_markers(
376
+ relative_path: str,
377
+ text: str,
378
+ generated_runtime_files: dict[str, tuple[str, ...]],
379
+ ) -> bool:
380
+ markers = generated_runtime_files.get(relative_path)
381
+ return bool(markers) and all(marker in text for marker in markers)
@@ -0,0 +1,324 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Callable, Mapping
4
+ from dataclasses import dataclass
5
+ import copy
6
+ import difflib
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ import yaml
11
+
12
+ from agentic_project_kit.workspace import (
13
+ KitConfig,
14
+ SUPPORTED_MANIFEST_SCHEMA_VERSION,
15
+ WORKSPACE_MANIFEST_FIX_HINT,
16
+ default_hygiene_manifest,
17
+ load_workspace,
18
+ )
19
+ from agentic_project_kit.workspace_lock import acquire_workspace_lock
20
+
21
+
22
+ Manifest = dict[str, Any]
23
+ WorkspaceUpgradeTransform = Callable[[Manifest], Manifest]
24
+ WORKSPACE_UPGRADE_STEPS: Mapping[int, WorkspaceUpgradeTransform] = {}
25
+
26
+
27
+ class WorkspaceUpgradeError(RuntimeError):
28
+ def __init__(self, message: str, *, code: str = "FAIL") -> None:
29
+ super().__init__(message)
30
+ self.code = code
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class WorkspaceUpgradeStepPreview:
35
+ from_version: int
36
+ to_version: int
37
+ before_yaml: str
38
+ after_yaml: str
39
+ diff: tuple[str, ...]
40
+
41
+ @property
42
+ def backup_path(self) -> str:
43
+ return f".agentic/config.yaml.bak.v{self.from_version}"
44
+
45
+ def as_json_data(self) -> dict[str, object]:
46
+ return {
47
+ "from_version": self.from_version,
48
+ "to_version": self.to_version,
49
+ "backup_path": self.backup_path,
50
+ "diff": list(self.diff),
51
+ }
52
+
53
+
54
+ @dataclass(frozen=True)
55
+ class WorkspaceUpgradePlan:
56
+ root: Path
57
+ manifest_path: Path
58
+ original_text: str
59
+ current_version: int
60
+ target_version: int
61
+ execute: bool
62
+ steps: tuple[WorkspaceUpgradeStepPreview, ...]
63
+ final_manifest: Manifest
64
+ final_manifest_yaml: str
65
+
66
+ @property
67
+ def requires_upgrade(self) -> bool:
68
+ return bool(self.steps)
69
+
70
+ @property
71
+ def message(self) -> str:
72
+ if not self.requires_upgrade:
73
+ return f"already at latest schema (v{self.target_version}); nothing to upgrade"
74
+ return (
75
+ f"workspace manifest upgrade planned: v{self.current_version} -> v{self.target_version}"
76
+ )
77
+
78
+ def as_json_data(self, *, written: bool = False) -> dict[str, object]:
79
+ return {
80
+ "schema_version": 1,
81
+ "kind": "workspace_upgrade_plan",
82
+ "root": self.root.as_posix(),
83
+ "manifest_path": _relative_to_root(self.root, self.manifest_path),
84
+ "result_status": "PASS",
85
+ "mode": "execute" if self.execute else "dry-run",
86
+ "written": written,
87
+ "current_version": self.current_version,
88
+ "target_version": self.target_version,
89
+ "message": self.message,
90
+ "steps": [step.as_json_data() for step in self.steps],
91
+ "final_signal": "d",
92
+ }
93
+
94
+
95
+ def build_workspace_upgrade_plan(
96
+ root: Path | str = Path("."),
97
+ *,
98
+ execute: bool = False,
99
+ ) -> WorkspaceUpgradePlan:
100
+ root_path = Path(root)
101
+ config = KitConfig()
102
+ manifest_path = root_path / config.workspace_manifest_file
103
+ if not manifest_path.exists():
104
+ raise WorkspaceUpgradeError(
105
+ "no workspace manifest; run workspace init",
106
+ code="NO_MANIFEST",
107
+ )
108
+
109
+ original_text = _read_manifest_text(manifest_path)
110
+ manifest = _load_manifest_yaml(original_text)
111
+ current_version = _manifest_schema_version(manifest)
112
+ if current_version > SUPPORTED_MANIFEST_SCHEMA_VERSION:
113
+ raise WorkspaceUpgradeError(
114
+ f"manifest schema v{current_version} is newer than this kit; upgrade the kit",
115
+ code="NEWER_SCHEMA",
116
+ )
117
+ _validate_current_manifest(root_path)
118
+ steps, final_manifest = _build_step_previews(
119
+ manifest,
120
+ current_version=current_version,
121
+ target_version=SUPPORTED_MANIFEST_SCHEMA_VERSION,
122
+ )
123
+ final_manifest_yaml = _dump_manifest(final_manifest)
124
+ return WorkspaceUpgradePlan(
125
+ root=root_path,
126
+ manifest_path=manifest_path,
127
+ original_text=original_text,
128
+ current_version=current_version,
129
+ target_version=SUPPORTED_MANIFEST_SCHEMA_VERSION,
130
+ execute=execute,
131
+ steps=steps,
132
+ final_manifest=final_manifest,
133
+ final_manifest_yaml=final_manifest_yaml,
134
+ )
135
+
136
+
137
+ def execute_workspace_upgrade(plan: WorkspaceUpgradePlan) -> None:
138
+ if not plan.requires_upgrade:
139
+ return
140
+ with acquire_workspace_lock(plan.root, "workspace_upgrade"):
141
+ current_text = _read_manifest_text(plan.manifest_path)
142
+ if current_text != plan.original_text:
143
+ raise WorkspaceUpgradeError(
144
+ "workspace manifest changed after the upgrade plan was built; rerun workspace upgrade",
145
+ code="MANIFEST_CHANGED",
146
+ )
147
+ for step in plan.steps:
148
+ backup_path = plan.root / step.backup_path
149
+ if backup_path.exists():
150
+ raise WorkspaceUpgradeError(
151
+ f"{step.backup_path} already exists; refusing to overwrite manifest backup",
152
+ code="BACKUP_EXISTS",
153
+ )
154
+ for step in plan.steps:
155
+ backup_path = plan.root / step.backup_path
156
+ backup_path.parent.mkdir(parents=True, exist_ok=True)
157
+ backup_path.write_text(current_text, encoding="utf-8")
158
+ plan.manifest_path.write_text(step.after_yaml, encoding="utf-8")
159
+ current_text = step.after_yaml
160
+ load_workspace(plan.root)
161
+
162
+
163
+ def render_workspace_upgrade_plan(
164
+ plan: WorkspaceUpgradePlan,
165
+ *,
166
+ written: bool = False,
167
+ ) -> str:
168
+ lines = [
169
+ "WORKSPACE_UPGRADE",
170
+ "STATUS=PASS",
171
+ f"MODE={'execute' if plan.execute else 'dry-run'}",
172
+ f"WRITTEN={str(written).lower()}",
173
+ f"ROOT={plan.root.as_posix()}",
174
+ f"MANIFEST={_relative_to_root(plan.root, plan.manifest_path)}",
175
+ f"CURRENT_SCHEMA_VERSION={plan.current_version}",
176
+ f"TARGET_SCHEMA_VERSION={plan.target_version}",
177
+ f"MESSAGE={plan.message}",
178
+ ]
179
+ if not plan.steps:
180
+ return "\n".join(lines) + "\n"
181
+
182
+ lines.extend(["", "Upgrade steps:"])
183
+ for step in plan.steps:
184
+ lines.append(f"- v{step.from_version} -> v{step.to_version}")
185
+ lines.append(f" backup: {step.backup_path}")
186
+ for step in plan.steps:
187
+ lines.extend(
188
+ [
189
+ "",
190
+ f"Manifest diff for v{step.from_version} -> v{step.to_version}:",
191
+ "```diff",
192
+ *step.diff,
193
+ "```",
194
+ ]
195
+ )
196
+ return "\n".join(lines) + "\n"
197
+
198
+
199
+ def render_workspace_upgrade_error(error: WorkspaceUpgradeError) -> str:
200
+ return f"WORKSPACE_UPGRADE\nSTATUS=FAIL\nCODE={error.code}\nERROR={error}\n"
201
+
202
+
203
+ def _build_step_previews(
204
+ manifest: Manifest,
205
+ *,
206
+ current_version: int,
207
+ target_version: int,
208
+ ) -> tuple[tuple[WorkspaceUpgradeStepPreview, ...], Manifest]:
209
+ working = copy.deepcopy(manifest)
210
+ steps: list[WorkspaceUpgradeStepPreview] = []
211
+ for from_version in range(current_version, target_version):
212
+ to_version = from_version + 1
213
+ transform = WORKSPACE_UPGRADE_STEPS.get(from_version)
214
+ if transform is None:
215
+ raise WorkspaceUpgradeError(
216
+ f"no workspace upgrade step registered for v{from_version} to v{to_version}",
217
+ code="MISSING_STEP",
218
+ )
219
+ before_yaml = _dump_manifest(working)
220
+ migrated = transform(copy.deepcopy(working))
221
+ if not isinstance(migrated, dict):
222
+ raise WorkspaceUpgradeError(
223
+ f"workspace upgrade step v{from_version} to v{to_version} did not return a manifest mapping",
224
+ code="INVALID_STEP_RESULT",
225
+ )
226
+ produced_version = migrated.get("kit_schema_version")
227
+ if produced_version != to_version:
228
+ raise WorkspaceUpgradeError(
229
+ f"workspace upgrade step v{from_version} to v{to_version} produced kit_schema_version {produced_version!r}",
230
+ code="INVALID_STEP_VERSION",
231
+ )
232
+ after_yaml = _dump_manifest(migrated)
233
+ diff = tuple(
234
+ difflib.unified_diff(
235
+ before_yaml.splitlines(),
236
+ after_yaml.splitlines(),
237
+ fromfile=f".agentic/config.yaml@v{from_version}",
238
+ tofile=f".agentic/config.yaml@v{to_version}",
239
+ lineterm="",
240
+ )
241
+ )
242
+ steps.append(
243
+ WorkspaceUpgradeStepPreview(
244
+ from_version=from_version,
245
+ to_version=to_version,
246
+ before_yaml=before_yaml,
247
+ after_yaml=after_yaml,
248
+ diff=diff,
249
+ )
250
+ )
251
+ working = migrated
252
+ return tuple(steps), working
253
+
254
+
255
+ def _upgrade_v1_to_v2(manifest: Manifest) -> Manifest:
256
+ migrated = copy.deepcopy(manifest)
257
+ migrated["kit_schema_version"] = 2
258
+ default_hygiene = default_hygiene_manifest()
259
+ hygiene = migrated.get("hygiene")
260
+ if hygiene is None:
261
+ migrated["hygiene"] = default_hygiene
262
+ elif isinstance(hygiene, dict):
263
+ merged_hygiene = copy.deepcopy(hygiene)
264
+ merged_hygiene.setdefault("doc_lifecycle", default_hygiene["doc_lifecycle"])
265
+ merged_hygiene.setdefault("review_budgets", default_hygiene["review_budgets"])
266
+ migrated["hygiene"] = merged_hygiene
267
+ return migrated
268
+
269
+
270
+ WORKSPACE_UPGRADE_STEPS = {1: _upgrade_v1_to_v2}
271
+
272
+
273
+ def _read_manifest_text(manifest_path: Path) -> str:
274
+ try:
275
+ return manifest_path.read_text(encoding="utf-8")
276
+ except OSError as exc:
277
+ raise WorkspaceUpgradeError(
278
+ f"cannot read workspace manifest: {exc}",
279
+ code="READ_ERROR",
280
+ ) from exc
281
+
282
+
283
+ def _validate_current_manifest(root: Path) -> None:
284
+ try:
285
+ load_workspace(root)
286
+ except RuntimeError as exc:
287
+ raise WorkspaceUpgradeError(str(exc), code="INVALID_MANIFEST") from exc
288
+
289
+
290
+ def _load_manifest_yaml(text: str) -> Manifest:
291
+ try:
292
+ loaded = yaml.safe_load(text)
293
+ except yaml.YAMLError as exc:
294
+ raise WorkspaceUpgradeError(
295
+ f"invalid workspace manifest YAML: {exc}",
296
+ code="INVALID_YAML",
297
+ ) from exc
298
+ if not isinstance(loaded, dict):
299
+ raise WorkspaceUpgradeError(
300
+ "invalid workspace manifest: expected top-level mapping",
301
+ code="INVALID_MANIFEST",
302
+ )
303
+ return loaded
304
+
305
+
306
+ def _manifest_schema_version(manifest: Manifest) -> int:
307
+ version = manifest.get("kit_schema_version")
308
+ if type(version) is not int or version < 1:
309
+ raise WorkspaceUpgradeError(
310
+ f"invalid kit_schema_version; {WORKSPACE_MANIFEST_FIX_HINT}",
311
+ code="INVALID_SCHEMA",
312
+ )
313
+ return version
314
+
315
+
316
+ def _dump_manifest(manifest: Manifest) -> str:
317
+ return yaml.safe_dump(manifest, sort_keys=False)
318
+
319
+
320
+ def _relative_to_root(root: Path, path: Path) -> str:
321
+ try:
322
+ return path.relative_to(root).as_posix()
323
+ except ValueError:
324
+ return path.as_posix()