waymark-cli 0.2.0__tar.gz → 0.3.0__tar.gz

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 (192) hide show
  1. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/CHANGELOG.md +78 -2
  2. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/PKG-INFO +28 -16
  3. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/README.md +27 -15
  4. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/cli.md +59 -8
  5. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/concepts.md +60 -11
  6. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/getting-started.md +15 -20
  7. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/json.md +402 -4
  8. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/multi-repo.md +0 -6
  9. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/record.md +133 -16
  10. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/skills.md +45 -51
  11. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/smoke-test.md +13 -5
  12. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/pyproject.toml +3 -1
  13. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/__init__.py +1 -1
  14. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/adapters/__init__.py +2 -0
  15. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/adapters/claude_code.py +2 -1
  16. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/__init__.py +0 -1
  17. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/agents/wm-implementer.md +1 -1
  18. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/agents/wm-reviewer.md +3 -2
  19. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/skills/wm-apply/SKILL.md +6 -4
  20. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/skills/wm-archive/SKILL.md +2 -2
  21. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/skills/wm-explore/SKILL.md +6 -7
  22. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/skills/wm-kickoff/SKILL.md +1 -1
  23. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/skills/wm-onboard/SKILL.md +3 -3
  24. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/skills/wm-pr/SKILL.md +3 -3
  25. waymark_cli-0.3.0/src/waymark/assets/skills/wm-propose/SKILL.md +97 -0
  26. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/assets/skills/wm-update/SKILL.md +1 -1
  27. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/cli.py +83 -7
  28. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/hooks/decide.py +10 -3
  29. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/atlas.py +3 -10
  30. waymark_cli-0.3.0/src/waymark/record/branches.py +83 -0
  31. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/changes.py +0 -22
  32. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/charter.py +7 -50
  33. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/config.py +10 -1
  34. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/deltas.py +59 -12
  35. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/edits.py +0 -7
  36. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/evidence.py +35 -2
  37. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/files.py +10 -0
  38. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/git.py +48 -0
  39. waymark_cli-0.3.0/src/waymark/record/milestones.py +204 -0
  40. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/outline.py +2 -5
  41. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/pointer.py +16 -27
  42. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/project.py +12 -20
  43. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/proposal.py +24 -13
  44. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/record.py +27 -24
  45. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/records.py +125 -15
  46. waymark_cli-0.3.0/src/waymark/record/resources.py +191 -0
  47. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/specs.py +21 -2
  48. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/state.py +74 -14
  49. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/store.py +25 -1
  50. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/tasks.py +19 -35
  51. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/charter.md +5 -18
  52. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/config.toml +1 -1
  53. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/delta.md +9 -0
  54. waymark_cli-0.3.0/src/waymark/record/templates/resource.md +48 -0
  55. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates.py +1 -0
  56. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/atlas.py +1 -18
  57. waymark_cli-0.3.0/src/waymark/services/check.py +291 -0
  58. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/common.py +2 -5
  59. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/context.py +86 -11
  60. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/doctor.py +5 -28
  61. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/instructions.py +35 -5
  62. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/integration.py +57 -16
  63. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/lifecycle.py +39 -11
  64. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/pr.py +11 -3
  65. waymark_cli-0.3.0/src/waymark/services/roadmap.py +191 -0
  66. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/setup.py +86 -27
  67. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/views/payloads.py +61 -8
  68. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/views/render.py +94 -13
  69. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/views/schemas.py +54 -0
  70. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/adapters/snapshots/wm-implementer.md +1 -1
  71. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/adapters/snapshots/wm-reviewer.md +3 -2
  72. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/adapters/test_claude_code.py +6 -3
  73. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/adapters/test_integration.py +156 -21
  74. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/hooks/test_commands.py +1 -0
  75. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/hooks/test_decide.py +126 -5
  76. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_artifacts.py +62 -15
  77. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_atlas.py +1 -72
  78. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_authored_formats.py +55 -2
  79. waymark_cli-0.3.0/tests/record/test_branches.py +156 -0
  80. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_config.py +3 -3
  81. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_deltas.py +66 -1
  82. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_evidence.py +33 -1
  83. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_git.py +11 -1
  84. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_project.py +6 -9
  85. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_records.py +91 -4
  86. waymark_cli-0.3.0/tests/record/test_resources.py +114 -0
  87. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_state.py +0 -10
  88. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_store.py +21 -0
  89. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_tasks.py +3 -10
  90. waymark_cli-0.2.0/tests/record/test_tasks_format2.py → waymark_cli-0.3.0/tests/record/test_tasks_records.py +9 -23
  91. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_agent_interface.py +327 -12
  92. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_archive.py +37 -0
  93. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_atlas.py +19 -45
  94. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_check.py +170 -21
  95. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_ci_and_pr.py +40 -5
  96. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_doctor.py +9 -52
  97. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_fix.py +4 -3
  98. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_lifecycle.py +7 -4
  99. waymark_cli-0.2.0/tests/services/test_lifecycle_format2.py → waymark_cli-0.3.0/tests/services/test_lifecycle_records.py +9 -7
  100. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_milestones.py +12 -5
  101. waymark_cli-0.3.0/tests/services/test_review_added_items.py +121 -0
  102. waymark_cli-0.3.0/tests/services/test_roadmap.py +127 -0
  103. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/test_setup.py +187 -18
  104. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/support.py +3 -8
  105. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_atlas_cli.py +9 -11
  106. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_cli.py +66 -0
  107. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_docs.py +1 -0
  108. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_skills.py +38 -3
  109. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_views_cli.py +55 -1
  110. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/views/test_views.py +91 -3
  111. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/docs.py +1 -0
  112. waymark_cli-0.2.0/src/waymark/assets/skills/wm-fix/SKILL.md +0 -60
  113. waymark_cli-0.2.0/src/waymark/assets/skills/wm-propose/SKILL.md +0 -80
  114. waymark_cli-0.2.0/src/waymark/record/milestones.py +0 -105
  115. waymark_cli-0.2.0/src/waymark/services/check.py +0 -148
  116. waymark_cli-0.2.0/src/waymark/services/migrations.py +0 -99
  117. waymark_cli-0.2.0/tests/services/test_migrations.py +0 -122
  118. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/.gitignore +0 -0
  119. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/LICENSE +0 -0
  120. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/architecture.md +0 -0
  121. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/assets/banner-dark.svg +0 -0
  122. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/assets/banner-light.svg +0 -0
  123. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/assets/trail-dark.svg +0 -0
  124. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/docs/assets/trail-light.svg +0 -0
  125. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/__main__.py +0 -0
  126. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/hooks/__init__.py +0 -0
  127. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/hooks/commands.py +0 -0
  128. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/hooks/events.py +0 -0
  129. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/py.typed +0 -0
  130. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/__init__.py +0 -0
  131. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/agents.py +0 -0
  132. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/commits.py +0 -0
  133. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/design.py +0 -0
  134. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/explorations.py +0 -0
  135. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/fingerprint.py +0 -0
  136. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/ignore.py +0 -0
  137. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/layout.py +0 -0
  138. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/links.py +0 -0
  139. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/moves.py +0 -0
  140. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/names.py +0 -0
  141. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/problems.py +0 -0
  142. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/registry.py +0 -0
  143. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/ci-workflow.yml +0 -0
  144. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/config-atlas.toml +0 -0
  145. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/design.md +0 -0
  146. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/exploration.md +0 -0
  147. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/milestone.md +0 -0
  148. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/proposal.md +0 -0
  149. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/templates/tasks.md +0 -0
  150. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/terms.py +0 -0
  151. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/record/text.py +0 -0
  152. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/__init__.py +0 -0
  153. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/ci.py +0 -0
  154. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/fix.py +0 -0
  155. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/guidance.py +0 -0
  156. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/services/references.py +0 -0
  157. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/views/__init__.py +0 -0
  158. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/src/waymark/views/style.py +0 -0
  159. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/__init__.py +0 -0
  160. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/adapters/__init__.py +0 -0
  161. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/adapters/snapshots/settings.json +0 -0
  162. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/conftest.py +0 -0
  163. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/hooks/__init__.py +0 -0
  164. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/hooks/test_repo_limits.py +0 -0
  165. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/__init__.py +0 -0
  166. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_agents.py +0 -0
  167. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_commits.py +0 -0
  168. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_fingerprint.py +0 -0
  169. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_ignore.py +0 -0
  170. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_layout.py +0 -0
  171. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_links.py +0 -0
  172. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_names.py +0 -0
  173. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_platforms.py +0 -0
  174. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_registry.py +0 -0
  175. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_specs.py +0 -0
  176. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/record/test_text.py +0 -0
  177. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/services/__init__.py +0 -0
  178. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_agent_cli.py +0 -0
  179. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_constraints.py +0 -0
  180. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_install_skills.py +0 -0
  181. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/test_lifecycle_cli.py +0 -0
  182. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/views/__init__.py +0 -0
  183. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/views/test_branches.py +0 -0
  184. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/views/test_style.py +0 -0
  185. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tests/views/validator.py +0 -0
  186. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/__init__.py +0 -0
  187. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/install_skills.py +0 -0
  188. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/release.py +0 -0
  189. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/skills/waymark-check-docs/SKILL.md +0 -0
  190. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/skills/waymark-draft-docs/SKILL.md +0 -0
  191. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/skills/waymark-release/SKILL.md +0 -0
  192. {waymark_cli-0.2.0 → waymark_cli-0.3.0}/tools/skills/waymark-write-docs/SKILL.md +0 -0
@@ -1,7 +1,83 @@
1
1
  # Changelog
2
2
 
3
- All notable changes to Waymark, one entry per release. A release that changes
4
- the record's format says whether `wm update` migrates an older record.
3
+ All notable changes to Waymark, one entry per release.
4
+
5
+ ## [0.3.0] - 2026-11-18
6
+
7
+ Context beyond the code: resources, a spec's Background and one list of project
8
+ rules give every fact an agent needs one place. Milestones link their changes and
9
+ keep a log, changes have branches and bases, and the record format resets to 1.
10
+
11
+ - **Behavior change: record format 1, with no migration.** `wm` reads and writes
12
+ only format 1, and this release's record is format 1. A record in any other
13
+ format, including the format 3 that 0.2.0 writes, is refused with one reason:
14
+ install the `wm` version that wrote it. `wm update` migrates nothing. It
15
+ regenerates the files `wm` owns and adds missing `.gitkeep` files. `wm check`
16
+ no longer reports older layouts on their own; such a line fails the check
17
+ that applies to it. `.waymark/atlas.toml` is no longer read as an atlas
18
+ pointer, and `wm doctor` no longer looks for `.waymark/hooks/`.
19
+ - **Behavior change: `wm-fix` is gone; `/wm-propose` does work of any size.**
20
+ It reads the specs and the code and picks the path itself: tiny, built after
21
+ your yes; short, a change with no design; or full, a change with a design,
22
+ with any open question blocking acceptance. `wm init` and `wm update` remove
23
+ the `wm-*` skill folders `wm` no longer ships, and print `removed:` for each.
24
+ - **Record folders stay in git.** `wm init` writes an empty `.gitkeep` into
25
+ `specs/`, `changes/`, `changes/archive/`, `explorations/`, `milestones/` and
26
+ `milestones/archive/`, and `wm update` adds any that are missing.
27
+ - **Behavior change: an item added after a review is reviewed on its own.**
28
+ `(review)` and `(self-review)` records now name the items they cover, as
29
+ `covers <item>...`; a record without it covers every item. Once an item added
30
+ after a passing review is ticked, the next step is a review of the items no
31
+ passing review covers, and the reviewer's pack holds only those. `wm archive`
32
+ refuses a change with such an item unless you override it with a reason.
33
+ `wm show` and the JSON payloads give what each review covers.
34
+ - **A change names its milestone.** A proposal may have a `- Milestone: <name>`
35
+ line. For an active change, `wm check` reports an error when that line and the
36
+ milestones' roadmaps disagree, including a roadmap that links a change whose
37
+ proposal has no such line. `wm new change <name> --milestone <milestone>`
38
+ writes the line and links the change from the roadmap. The implement and
39
+ review context packs carry the milestone's Goal and Non-goals, in a new
40
+ `milestone` field.
41
+ - **A milestone keeps a log, and its roadmap changes only through `wm`.**
42
+ `wm roadmap add`, `wm roadmap drop --reason` and `wm roadmap move --after|--first`
43
+ change the roadmap, and each writes a record in a `## Log` at the end of
44
+ `milestone.md`, as do `wm new change --milestone` and `wm archive`. An agent's
45
+ hand edit to a roadmap line or the Log is refused.
46
+ - **Behavior change: `wm close` needs every roadmap line archived.** A planned
47
+ line that was never proposed now keeps a milestone open, until it is proposed
48
+ or dropped with `wm roadmap drop`.
49
+ - **Each change has a branch and a base.** A proposal may say which change it
50
+ comes after, in an `- After: <change>` line written by
51
+ `wm new change <name> --after <change>`. `wm instructions`, `wm pr` and
52
+ `wm status` show each change's branch and base, `wm pr`'s JSON has a `base` for
53
+ the pull request to target, and `wm check` warns when the change it comes after
54
+ has merged. The default branch comes from the `origin` remote's HEAD, or is
55
+ `main`. The skills open a plan pull request for a new milestone and create
56
+ each change's branch from its base.
57
+ - **Resources.** A new kind of note, `waymark/resources/<name>.md`, holds the
58
+ facts about one thing outside the repo: its kind, the specs it serves, its
59
+ status, the day it was verified, and six sections. `wm new resource <name>
60
+ <kind>`, `wm ls resources` and `wm show <name> --kind resource` work with them,
61
+ and `wm check` holds them to their layout. The explore context pack gains a
62
+ `resources` index, and the implement and review packs a `resources` field with
63
+ the resources serving the change's specs. An implementer may edit resources,
64
+ and `wm init` and `wm update` keep `resources/` in git.
65
+ - **A spec may have a Background.** A `## Background` section, between Purpose
66
+ and Requirements, holds the facts about the spec's area that aren't
67
+ requirements. A delta's `## Background` replaces the spec's whole at archive or
68
+ sync. `wm check` reports an empty one. The implement and review packs gain a
69
+ `backgrounds` field with the Background of each spec the change has a delta
70
+ for, the delta's when it has one. The delta template and the specs step's
71
+ guidance say where a fact goes.
72
+ - **Behavior change: the charter's Rules are one numbered list.** `## Rules`
73
+ holds `1. <rule>` lines, like Goals and Constraints, and every agent gets the
74
+ whole list at every step: `wm instructions` and every `wm context` pack show
75
+ it under "Project rules", and `rules` in their JSON holds all of it. A step
76
+ heading or a bullet under Rules is a `numbered-list-format` error, and the
77
+ `unknown-step` problem is gone. A charter with step headings must be rewritten
78
+ by hand. `wm init` writes Rules without step headings.
79
+
80
+ Smoke test: passed on 2026-11-18 with Claude Code 2.1.327 on Windows.
5
81
 
6
82
  ## [0.2.0] - 2026-11-16
7
83
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: waymark-cli
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Spec-driven development for developers who stay in charge of their project while agents write the code.
5
5
  Project-URL: Repository, https://github.com/noahnkr/waymark
6
6
  Project-URL: Documentation, https://github.com/noahnkr/waymark/tree/main/docs
@@ -61,23 +61,25 @@ command-line tool, `wm`, keeps track of where everything stands.
61
61
 
62
62
  ## How it works
63
63
 
64
- Not every piece of work needs the whole trail. What decides it is whether the
65
- work changes what the specs say, not how big it is:
64
+ Everything starts with `/wm-propose`. A typo fix and a new feature go through
65
+ the same door, but they don't take the same amount of work:
66
66
 
67
- | Path | When | What gets written | Run |
68
- |---|---|---|---|
69
- | **Tiny** | Nothing in the specs changes: a typo, a docs fix, a bug, a refactor | Nothing. You say yes, the agent makes the fix, you review the pull request. | `/wm-fix` |
70
- | **Short** | A small change that doesn't need a design | A short plan: what's changing and why, the spec edits, and a task list. | `/wm-propose` |
71
- | **Full** | A change that needs a design | The same plan plus a design, with every decision agreed before work starts. | `/wm-propose` |
67
+ | Path | When | What gets written |
68
+ |---|---|---|
69
+ | **Tiny** | The specs don't change: a typo, a docs fix, a bug, a refactor | Nothing. You say yes, the agent fixes it, you review the pull request. |
70
+ | **Short** | The specs change, but there's nothing to design | A short plan: what's changing and why, the spec edits, and a task list. |
71
+ | **Full** | The specs change and there are decisions to make | The same plan plus a design, and you agree every decision before anything gets built. |
72
72
 
73
- Here's what happens along the way:
73
+ Here's how a change goes:
74
74
 
75
75
  - **Explore**, if you're not sure yet. `/wm-explore` talks the idea through with
76
76
  you, using what the specs already say, and writes nothing unless you ask. It
77
77
  can save your thinking for later, or turn it into a change or a milestone.
78
- - **Propose.** `/wm-propose` asks you whatever the plan needs, then writes it:
79
- why the change is wanted, the edits to the specs, a design if it needs one,
80
- and a task list where every task says how you'll know it's done.
78
+ - **Propose.** `/wm-propose` looks at your specs and code to see what the work
79
+ involves. If it's tiny, it tells you in one line what it'll change and does it
80
+ once you say yes. Otherwise it asks what it needs to know, then writes the
81
+ plan: why, the spec edits, a design if there is one, and a task list where
82
+ every task says how you'll know it's done.
81
83
  - **Accept.** You read a short summary and run `wm accept`. Nothing is built
82
84
  before that.
83
85
  - **Apply.** `/wm-apply` builds the tasks one at a time and commits each one.
@@ -140,8 +142,7 @@ You work through skills, as slash commands in Claude Code:
140
142
  | `/wm-kickoff` | Write the project's charter with you, once per project |
141
143
  | `/wm-onboard` | Take a first change all the way through, explaining each step |
142
144
  | `/wm-explore` | Think a fuzzy idea through, without writing anything |
143
- | `/wm-fix` | Make a small fix that changes nothing in the specs |
144
- | `/wm-propose` | Write the plan for a change |
145
+ | `/wm-propose` | Do any piece of work: a small fix after your yes, or the plan for a change |
145
146
  | `/wm-update` | Revise a plan, settle a decision, or fill a gap |
146
147
  | `/wm-apply` | Build an approved change, then check it |
147
148
  | `/wm-archive` | Finish a change and update the specs |
@@ -198,14 +199,25 @@ waymark/
198
199
  charter.md what the project is, its goals and its rules
199
200
  config.toml settings, and the pinned wm version
200
201
  changes/
202
+ .gitkeep
201
203
  archive/
204
+ .gitkeep
202
205
  2026-01-15-add-dark-mode/
203
206
  design.md how it's built, and the decisions
204
207
  proposal.md why, what changes, and the outcome
205
208
  tasks.md the tasks, and what wm recorded
206
209
  specs/
207
210
  appearance.md the change to the spec
211
+ explorations/
212
+ .gitkeep
213
+ milestones/
214
+ .gitkeep
215
+ archive/
216
+ .gitkeep
217
+ resources/
218
+ .gitkeep
208
219
  specs/
220
+ .gitkeep
209
221
  appearance.md the living spec, now with dark mode
210
222
  ```
211
223
 
@@ -335,7 +347,7 @@ setting until the person picks one.
335
347
  ## Log
336
348
 
337
349
  - (accepted) 2026-01-15 fingerprint 01204aef70272f6b items 1.1 1.2 1.3 by Alex Example
338
- - (self-review) 2026-01-15 by Alex Example: every criterion holds, and both scenarios have a test
350
+ - (self-review) 2026-01-15 covers 1.1 1.2 1.3 by Alex Example: every criterion holds, and both scenarios have a test
339
351
  ```
340
352
 
341
353
  </details>
@@ -476,7 +488,7 @@ is caught once both are in the same branch, not before.
476
488
  - **[Architecture](docs/architecture.md)**: how `wm` is built, and how to add an agent tool
477
489
  - **[Smoke test](docs/smoke-test.md)**: the manual walk-through before a release
478
490
 
479
- Works with Claude Code. Version last verified: **2.1.326**, on Windows.
491
+ Works with Claude Code. Version last verified: **2.1.327**, on Windows.
480
492
 
481
493
  ## License
482
494
 
@@ -32,23 +32,25 @@ command-line tool, `wm`, keeps track of where everything stands.
32
32
 
33
33
  ## How it works
34
34
 
35
- Not every piece of work needs the whole trail. What decides it is whether the
36
- work changes what the specs say, not how big it is:
35
+ Everything starts with `/wm-propose`. A typo fix and a new feature go through
36
+ the same door, but they don't take the same amount of work:
37
37
 
38
- | Path | When | What gets written | Run |
39
- |---|---|---|---|
40
- | **Tiny** | Nothing in the specs changes: a typo, a docs fix, a bug, a refactor | Nothing. You say yes, the agent makes the fix, you review the pull request. | `/wm-fix` |
41
- | **Short** | A small change that doesn't need a design | A short plan: what's changing and why, the spec edits, and a task list. | `/wm-propose` |
42
- | **Full** | A change that needs a design | The same plan plus a design, with every decision agreed before work starts. | `/wm-propose` |
38
+ | Path | When | What gets written |
39
+ |---|---|---|
40
+ | **Tiny** | The specs don't change: a typo, a docs fix, a bug, a refactor | Nothing. You say yes, the agent fixes it, you review the pull request. |
41
+ | **Short** | The specs change, but there's nothing to design | A short plan: what's changing and why, the spec edits, and a task list. |
42
+ | **Full** | The specs change and there are decisions to make | The same plan plus a design, and you agree every decision before anything gets built. |
43
43
 
44
- Here's what happens along the way:
44
+ Here's how a change goes:
45
45
 
46
46
  - **Explore**, if you're not sure yet. `/wm-explore` talks the idea through with
47
47
  you, using what the specs already say, and writes nothing unless you ask. It
48
48
  can save your thinking for later, or turn it into a change or a milestone.
49
- - **Propose.** `/wm-propose` asks you whatever the plan needs, then writes it:
50
- why the change is wanted, the edits to the specs, a design if it needs one,
51
- and a task list where every task says how you'll know it's done.
49
+ - **Propose.** `/wm-propose` looks at your specs and code to see what the work
50
+ involves. If it's tiny, it tells you in one line what it'll change and does it
51
+ once you say yes. Otherwise it asks what it needs to know, then writes the
52
+ plan: why, the spec edits, a design if there is one, and a task list where
53
+ every task says how you'll know it's done.
52
54
  - **Accept.** You read a short summary and run `wm accept`. Nothing is built
53
55
  before that.
54
56
  - **Apply.** `/wm-apply` builds the tasks one at a time and commits each one.
@@ -111,8 +113,7 @@ You work through skills, as slash commands in Claude Code:
111
113
  | `/wm-kickoff` | Write the project's charter with you, once per project |
112
114
  | `/wm-onboard` | Take a first change all the way through, explaining each step |
113
115
  | `/wm-explore` | Think a fuzzy idea through, without writing anything |
114
- | `/wm-fix` | Make a small fix that changes nothing in the specs |
115
- | `/wm-propose` | Write the plan for a change |
116
+ | `/wm-propose` | Do any piece of work: a small fix after your yes, or the plan for a change |
116
117
  | `/wm-update` | Revise a plan, settle a decision, or fill a gap |
117
118
  | `/wm-apply` | Build an approved change, then check it |
118
119
  | `/wm-archive` | Finish a change and update the specs |
@@ -169,14 +170,25 @@ waymark/
169
170
  charter.md what the project is, its goals and its rules
170
171
  config.toml settings, and the pinned wm version
171
172
  changes/
173
+ .gitkeep
172
174
  archive/
175
+ .gitkeep
173
176
  2026-01-15-add-dark-mode/
174
177
  design.md how it's built, and the decisions
175
178
  proposal.md why, what changes, and the outcome
176
179
  tasks.md the tasks, and what wm recorded
177
180
  specs/
178
181
  appearance.md the change to the spec
182
+ explorations/
183
+ .gitkeep
184
+ milestones/
185
+ .gitkeep
186
+ archive/
187
+ .gitkeep
188
+ resources/
189
+ .gitkeep
179
190
  specs/
191
+ .gitkeep
180
192
  appearance.md the living spec, now with dark mode
181
193
  ```
182
194
 
@@ -306,7 +318,7 @@ setting until the person picks one.
306
318
  ## Log
307
319
 
308
320
  - (accepted) 2026-01-15 fingerprint 01204aef70272f6b items 1.1 1.2 1.3 by Alex Example
309
- - (self-review) 2026-01-15 by Alex Example: every criterion holds, and both scenarios have a test
321
+ - (self-review) 2026-01-15 covers 1.1 1.2 1.3 by Alex Example: every criterion holds, and both scenarios have a test
310
322
  ```
311
323
 
312
324
  </details>
@@ -447,7 +459,7 @@ is caught once both are in the same branch, not before.
447
459
  - **[Architecture](docs/architecture.md)**: how `wm` is built, and how to add an agent tool
448
460
  - **[Smoke test](docs/smoke-test.md)**: the manual walk-through before a release
449
461
 
450
- Works with Claude Code. Version last verified: **2.1.326**, on Windows.
462
+ Works with Claude Code. Version last verified: **2.1.327**, on Windows.
451
463
 
452
464
  ## License
453
465
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- Generated by tools/docs.py from the code. Don't edit it by hand. -->
4
4
 
5
- Every command of `wm` 0.2.0. Read commands take `--json`; their payloads are described in the [JSON schema reference](json.md).
5
+ Every command of `wm` 0.3.0. Read commands take `--json`; their payloads are described in the [JSON schema reference](json.md).
6
6
 
7
7
  Exit codes: `0` success; `1` refused, or problems found; `2` usage error.
8
8
 
@@ -19,7 +19,7 @@ wm init [--atlas NAME] [--tool NAME]
19
19
 
20
20
  ## wm update
21
21
 
22
- Migrate the record to this version and regenerate the files Waymark owns.
22
+ Regenerate the files Waymark owns, and add any missing record folders.
23
23
 
24
24
  ```
25
25
  wm update
@@ -108,16 +108,19 @@ wm hook <tool> <event>
108
108
 
109
109
  ## wm new
110
110
 
111
- Create a change, milestone or exploration from the built-in template.
111
+ Create a change, milestone, exploration or resource from the built-in template.
112
112
 
113
113
  ```
114
- wm new <change|milestone|exploration> <name> [--short] [--owner NAME]
114
+ wm new <change|milestone|exploration|resource> <name> [resource-kind] [--short] [--owner NAME] [--milestone MILESTONE] [--after CHANGE]
115
115
  ```
116
116
 
117
- - `kind`: one of `change`, `milestone`, `exploration`
117
+ - `kind`: one of `change`, `milestone`, `exploration`, `resource`
118
118
  - `name`: a kebab-case name, for example add-search-limit
119
+ - `resource_kind`: for a resource only: service, platform, account, database, dataset or document
119
120
  - `--short`: put a change on the short path
120
121
  - `--owner`: a change's owner (default: your git name)
122
+ - `--milestone`: the milestone a change belongs to; links it from the milestone's roadmap
123
+ - `--after`: the change this one comes after; its unmerged branch is this one's base
121
124
 
122
125
  ## wm accept
123
126
 
@@ -268,6 +271,54 @@ wm close <milestone>
268
271
 
269
272
  - `milestone`: the milestone's name
270
273
 
274
+ ## wm roadmap
275
+
276
+ Change a milestone's roadmap: add, drop or move a change's line, with a record.
277
+
278
+ ```
279
+ wm roadmap <command>
280
+ ```
281
+
282
+ ## wm roadmap add
283
+
284
+ Add a planned line for a change at the end of a milestone's roadmap.
285
+
286
+ ```
287
+ wm roadmap add <milestone> <change> <description> [--by NAME]
288
+ ```
289
+
290
+ - `milestone`: the milestone's name
291
+ - `change`: the change's name, for example add-search-limit
292
+ - `description`: what the change delivers toward the goal
293
+ - `--by`: who the record names as its writer (default: your git name)
294
+
295
+ ## wm roadmap drop
296
+
297
+ Take a change's line off a milestone's roadmap, with the reason.
298
+
299
+ ```
300
+ wm roadmap drop <milestone> <change> --reason REASON [--by NAME]
301
+ ```
302
+
303
+ - `milestone`: the milestone's name
304
+ - `change`: the change's name
305
+ - `--reason`: why the change is dropped (required)
306
+ - `--by`: who the record names as its writer (default: your git name)
307
+
308
+ ## wm roadmap move
309
+
310
+ Move a change's line on a milestone's roadmap.
311
+
312
+ ```
313
+ wm roadmap move <milestone> <change> [--after CHANGE] [--first] [--by NAME]
314
+ ```
315
+
316
+ - `milestone`: the milestone's name
317
+ - `change`: the change's name
318
+ - `--after`: put it right after this change's line
319
+ - `--first`: put it at the top of the roadmap
320
+ - `--by`: who the record names as its writer (default: your git name)
321
+
271
322
  ## wm status
272
323
 
273
324
  Show where things stand: changes, milestones, what needs you.
@@ -298,7 +349,7 @@ wm show [--json] <name> [--kind KIND] [--from ATLAS]
298
349
 
299
350
  - `--json`: print the view as JSON, with its schema version
300
351
  - `name`: its name; an archived change also by its dated folder name
301
- - `--kind`: which kind, if the name is shared; one of `change`, `spec`, `milestone`, `exploration`
352
+ - `--kind`: which kind, if the name is shared; one of `change`, `spec`, `milestone`, `exploration`, `resource`
302
353
  - `--from`: read a spec from an atlas this project references
303
354
 
304
355
  ## wm ls
@@ -306,11 +357,11 @@ wm show [--json] <name> [--kind KIND] [--from ATLAS]
306
357
  List changes, specs, milestones or explorations.
307
358
 
308
359
  ```
309
- wm ls [--json] <changes|specs|milestones|explorations> [--archived] [--from ATLAS]
360
+ wm ls [--json] <changes|specs|milestones|explorations|resources> [--archived] [--from ATLAS]
310
361
  ```
311
362
 
312
363
  - `--json`: print the view as JSON, with its schema version
313
- - `kind`: one of `changes`, `specs`, `milestones`, `explorations`
364
+ - `kind`: one of `changes`, `specs`, `milestones`, `explorations`, `resources`
314
365
  - `--archived`: include archived changes or milestones
315
366
  - `--from`: list the specs of an atlas this project references
316
367
 
@@ -35,17 +35,41 @@ If the pull request needs more work, the archive commit is reverted and the
35
35
  change archived again. Specs come before design: first agree on what the system does, then
36
36
  on how.
37
37
 
38
+ ## Branches
39
+
40
+ Each change lives on a branch named after it, and merges on its own.
41
+
42
+ - **Base:** a change branches from the default branch, the `origin` remote's HEAD
43
+ or `main`. A change that needs another change not merged yet says so with an
44
+ `- After: <change>` line, written by `wm new change <name> --after <change>`,
45
+ and branches from that change's branch instead.
46
+ - **Shown:** `wm instructions` and `wm pr` give a change's branch and base, and
47
+ its pull request goes into the base. `wm status` adds an `on <base>` line under
48
+ a change whose base isn't the default branch.
49
+ - **Merged base:** once the change it comes after is archived or merged, `wm
50
+ check` warns: rebase onto the default branch, retarget the pull request, and
51
+ take the `- After:` line off.
52
+ - **Milestones:** a new milestone goes on a `plan-<milestone>` branch and lands
53
+ on the default branch in a plan pull request before its changes are proposed.
54
+
55
+ `wm` names branches; it never creates, switches, rebases or pushes them. The
56
+ skills do that with git. In an atlas, a change uses the same branch name in every
57
+ repo.
58
+
38
59
  ## Paths
39
60
 
40
61
  | Path | For | What it takes |
41
62
  |---|---|---|
42
- | **Tiny** | work that adds, changes or removes no requirement: a typo, a docs fix, a bug where the code disagrees with a spec, a refactor, a dependency bump | no change folder: the agent says why it is tiny and builds after your yes, then commits and offers a pull request (`/wm-fix`). Nothing is written to the record; your merge is the second approval |
63
+ | **Tiny** | work that adds, changes or removes no requirement: a typo, a docs fix, a bug where the code disagrees with a spec, a refactor, a dependency bump | no change folder: `/wm-propose` says in one line what it will change and the requirement it keeps to, builds after your yes, then commits and offers a pull request. Nothing is written to the record; your merge is the second approval |
43
64
  | **Short** | a small change | a change with a proposal, deltas and a task list, but no design (a `- Path: short` line); review level `self` or `none` |
44
65
  | **Full** | anything bigger | a change with a design, and an independent review when it is risky |
45
66
 
46
67
  The test for tiny is the specs, not the size: if every requirement still holds
47
- as written, the work is tiny. If tiny work turns out to change a requirement, it
48
- stops and becomes a change. Specs can't be edited by hand on any path.
68
+ as written, the work is tiny. `/wm-propose` finds out which it is by reading
69
+ the specs and the code. A change with a question still open takes the full
70
+ path, where the design's open questions hold it until you answer. If tiny work
71
+ turns out to change a requirement, it stops and becomes a change. Specs can't
72
+ be edited by hand on any path.
49
73
 
50
74
  **Changing what was accepted withdraws the acceptance.** That covers the
51
75
  proposal (its `- Review:` line included), the deltas, the design and the
@@ -84,6 +108,7 @@ waymark/
84
108
  changes/archive/ archived changes, each in a dated folder
85
109
  milestones/<name>/ optional: milestone.md, a goal and a roadmap of changes
86
110
  explorations/ saved thinking
111
+ resources/<name>.md facts about one thing outside the repo: a service, a platform, ...
87
112
  ```
88
113
 
89
114
  There is no stored status and no frontmatter. What you write uses
@@ -122,6 +147,18 @@ A search SHALL return at most fifty results.
122
147
  - THEN fifty results come back
123
148
  ```
124
149
 
150
+ Each fact has one place to go:
151
+
152
+ | The fact | Where it goes |
153
+ |---|---|
154
+ | What the system does | A requirement in the area's spec. |
155
+ | A fact about one area that isn't a requirement, such as where its data comes from | The spec's `## Background`, set through a delta. |
156
+ | A fact about something outside the repo, such as a service or a platform | A resource, `resources/<name>.md`. |
157
+ | A fact every agent needs on every change | The charter's Context. |
158
+
159
+ A spec's Background reaches only the agents working on a change with a delta for
160
+ that spec. See [Spec](record.md#spec-specsareamd).
161
+
125
162
  A task item carries what an agent needs to build it, and the records `wm`
126
163
  writes about it. The records about the whole change sit in a `## Log` section at
127
164
  the end of the task list:
@@ -139,7 +176,7 @@ the end of the task list:
139
176
  ## Log
140
177
 
141
178
  - (accepted) 2026-01-15 fingerprint 6cec39a287bf99f2 items 1.1 by Sam Doe
142
- - (review) 2026-01-16 pass by wm-reviewer: the boundary is covered
179
+ - (review) 2026-01-16 pass covers 1.1 by wm-reviewer: the boundary is covered
143
180
  - suggestion `docs/search.md`: name the limit in the help text
144
181
  ```
145
182
 
@@ -175,6 +212,9 @@ Every line `wm` writes is a dated record of one shape:
175
212
  a `(resolved)` record and the blocker stays.
176
213
  - **Notes:** `wm note <change> <item> "<text>"` writes one under an unticked
177
214
  item.
215
+ - **Covers:** a `(review)` or `(self-review)` record names the items it covers,
216
+ as `covers <item>...` before `by`. A record without `covers`, written before
217
+ Waymark had it, covers every item.
178
218
  - **Layout:** `wm check --fix` puts the record in its standard layout: list
179
219
  markers, blank lines before headings, trailing spaces, the final line break
180
220
  and the records' own shape. It never changes wording, fenced code, comments
@@ -185,7 +225,7 @@ Every line `wm` writes is a dated record of one shape:
185
225
  | | Planner | Implementer | Reviewer |
186
226
  |---|---|---|---|
187
227
  | Is | the main agent session, working with you | a fresh agent, started for an item with a `- Build: delegate` line, with `<change> <item>` and nothing else | a fresh agent, started for a change at review level `independent` with `<change>` and nothing else |
188
- | Sees | the charter, `wm status`, whatever you bring in | its item, the proposal, deltas, design, the requirements they touch, the project's context and apply rules, and when to stop | every item's criteria, the deltas and their scenarios, the design, earlier reviews, the severity rubric, the code; **not** how it was built |
228
+ | Sees | the charter, `wm status`, whatever you bring in | its item, the proposal, deltas, design, the requirements they touch and their specs' Background, the project's context and rules, its milestone's Goal and Non-goals, and when to stop | the criteria of the items to review, the deltas and their scenarios, their specs' Background, the design, earlier reviews and what each covers, its milestone's Goal and Non-goals, the severity rubric, the code; **not** how it was built |
189
229
  | May | explore, draft and edit artifacts, build items and make tiny fixes (in an atlas, in any code repo), delegate, record results and self-reviews, archive | edit code (in an atlas, only in its item's repo) and leave notes on its item with `wm note` | read code and the record; run tests and other read-only commands |
190
230
  | Ends with | | `ITEM: <change> <item>` then `RESULT: done / partial / spec-gap / blocked` | `FINDING:` lines, then `CHANGE: <change>` then `VERDICT: pass / changes <items> / spec-gap` |
191
231
 
@@ -246,8 +286,14 @@ The change's level is the `- Review:` line in its proposal, or the project's
246
286
  ``<severity> `<place>`: <text>``. A place that holds `: ` is given in
247
287
  backticks. A `pass` or a self-review with a critical finding is refused.
248
288
  - **Changes:** a `changes` verdict names the items to rebuild, such as
249
- `(review) 2026-01-15 changes 1.2 2.1 by wm-reviewer: <reasons>`. Those items are reopened
250
- and built again, and the change then needs an independent review.
289
+ `(review) 2026-01-15 changes 1.2 2.1 covers 1.1 1.2 2.1 by wm-reviewer: <reasons>`. Those
290
+ items are reopened and built again, and the change then needs an independent review.
291
+ - **Added items:** an item added after a passing review is reviewed on its own.
292
+ Once it is ticked, the next step is a review of the items no passing review
293
+ covers, at the change's level. The reviewer's pack holds only those items, and
294
+ the record covers just them, such as
295
+ `(review) 2026-01-20 pass covers 1.3 by wm-reviewer: <reasons>`. The items the
296
+ earlier review passed aren't reviewed again.
251
297
  - **To you:** a second `changes` verdict, or a `spec-gap`, goes to you. You
252
298
  record your decision with `wm resolve <change> review "<what was decided>"`.
253
299
  - **Warning:** `wm check` warns when a change modifies or removes a requirement
@@ -260,9 +306,11 @@ The change's level is the `- Review:` line in its proposal, or the project's
260
306
  |---|---|---|
261
307
  | **Accept** | applying any item of a change that isn't accepted, or whose acceptance was withdrawn | only you, with `wm accept` |
262
308
  | **Delegation** | starting an implementer unless the prompt names exactly one item that has criteria; starting a reviewer unless the prompt names one change whose items are all ticked and which needs an independent review it lacks; either while the record around it isn't sound | no one; fix the record |
263
- | **Archive** | archiving a change that isn't accepted, has unbuilt items, isn't reviewed, or has a delta that no longer applies | only a missing review can be overridden, by you, with a reason that is recorded |
309
+ | **Archive** | archiving a change that isn't accepted, has unbuilt items, isn't reviewed, has an item no passing review covers, or has a delta that no longer applies | only a missing review can be overridden, by you, with a reason that is recorded |
264
310
 
265
- **Evidence is written only by `wm`**: ticks and records. The planner records
311
+ **Evidence is written only by `wm`**: ticks and records, and in a milestone its
312
+ roadmap lines and its Log, which change only through `wm roadmap`,
313
+ `wm new change --milestone` and `wm archive`. The planner records
266
314
  its own results with `wm tick`, `wm block`, `wm gap`, `wm note` and
267
315
  `wm review`. Implementers and reviewers report theirs in their last lines, and
268
316
  `wm`'s hooks write the records from them. An implementer edits nothing in the
@@ -287,7 +335,7 @@ and pull request, through the workflow `wm ci` writes.
287
335
  | Term | Meaning |
288
336
  |---|---|
289
337
  | **Record** | Everything Waymark keeps in plain markdown: the charter, specs, changes, milestones and explorations. The single source of truth agents work from. |
290
- | **Charter** | What the project is: vision, goals, non-goals, constraints and glossary, plus the facts every agent must know (Context) and project rules for each workflow step (Rules). |
338
+ | **Charter** | What the project is: vision, goals, non-goals, constraints and glossary, plus the facts every agent must know (Context) and the project's rules, one numbered list every agent gets at every step (Rules). |
291
339
  | **Spec** | The living description of what one area of the system does. It changes only when a change is archived or synced. |
292
340
  | **Requirement** | One statement in a spec of what the system SHALL do, with at least one scenario. Its heading is its key. |
293
341
  | **Scenario** | A GIVEN / WHEN / THEN example of a requirement. Reviews check work against scenarios. |
@@ -305,7 +353,8 @@ and pull request, through the workflow `wm ci` writes.
305
353
  | **Archive** | Finishing a change: its deltas merged into the specs, its outcome written, and its folder moved to a dated archive. |
306
354
  | **Owner** | The one person responsible for a change. |
307
355
  | **Exploration** | Saved thinking on a topic (questions, approaches, a conclusion) that may lead to a change or be parked. |
308
- | **Milestone** | An optional goal that several changes work toward, with a roadmap listing them, both in one `milestone.md`. |
356
+ | **Resource** | The as-built facts about one thing outside the repo that the project depends on, such as a service, a platform or a dataset, in `resources/<name>.md`. A spec says what the system does and changes only through a change; a resource says what the outside world is, and is edited by hand when that world changes. See [the record](record.md#resource). |
357
+ | **Milestone** | An optional goal that several changes work toward, with a roadmap listing them, both in one `milestone.md`. A member change names it in a `- Milestone:` line that `wm check` holds to the roadmap, is created with `wm new change <name> --milestone <milestone>`, and its agents see the milestone's Goal and Non-goals. The roadmap changes only through `wm roadmap add`, `drop` and `move`, each recorded in the milestone's Log, and `wm close` needs every line archived. See [the record](record.md#milestone). |
309
358
  | **Planner** | The main agent session, working with you: it explores, drafts, builds items or delegates them, and archives. |
310
359
  | **Implementer** | A fresh agent that builds one task item with a `- Build: delegate` line, from the record alone. |
311
360
  | **Reviewer** | A fresh, read-only agent that checks one whole change against its scenarios, design and criteria, without seeing how it was built. |
@@ -72,7 +72,8 @@ adds the `.gitignore` block if it is missing. It doesn't change anything in
72
72
 
73
73
  `wm init` is refused in a clone when the installed `wm` isn't the pinned
74
74
  version; the message gives the command that installs it. It is also refused
75
- when the record needs migrating; run `wm update` for that.
75
+ when the record is in another format than the installed `wm` reads; the message
76
+ says to install the `wm` version that wrote it.
76
77
 
77
78
  ## 3. Write the charter: the `wm-kickoff` skill
78
79
 
@@ -92,8 +93,8 @@ and explains each one as it happens:
92
93
  impact (the specs it touches, what users will see change, and the code), and
93
94
  the change's review level when it isn't the project default. A
94
95
  small change takes the short path: proposal and tasks, no design. Work that
95
- changes no requirement needs no change at all: `/wm-fix` takes it on the
96
- [tiny path](concepts.md#paths).
96
+ changes no requirement needs no change at all: `/wm-propose` takes it on
97
+ the [tiny path](concepts.md#paths).
97
98
  2. **Specs.** It writes the change's deltas against the living specs. On an
98
99
  existing codebase, this is where the first spec for that area is born.
99
100
  3. **Tasks.** It writes the task list: each item with criteria and how to
@@ -142,23 +143,17 @@ version installed, reading works and writing is refused, with the command that
142
143
  installs the pinned one. To upgrade a project: change the pin, install that
143
144
  version, and run `wm update`. When it changes the record, `.gitignore` or the CI
144
145
  workflow, it names them and asks you to review and commit the changes. It never
145
- asks you to commit the agent tool files. A release that changes the record's
146
- format says in the [changelog](../CHANGELOG.md) whether `wm update` migrates an
147
- older record. When it doesn't, `wm update` refuses the record, names its format,
148
- and changes nothing.
149
-
150
- A project set up with `wm` 0.1.0 committed the agent tool files and its git
151
- hooks. `wm update` adds the `.gitignore` block, but git keeps tracking files it
152
- already tracks. `wm doctor` warns about them, and gives the `git rm -r --cached`
153
- command that stops tracking them and keeps your copies. Run it, then commit.
154
-
155
- `wm` no longer has git hooks, and `wm run-hook` is gone. A clone that `wm`
156
- 0.1.0 or 0.1.1 set up still points git at the old hooks, which call
157
- `wm run-hook`, so its commits fail. In each such clone, run
158
- `git config --unset core.hooksPath`, then delete the hooks folder that setting
159
- named. `wm update` doesn't do this for you. If a hook manager such as husky,
160
- lefthook or pre-commit calls `wm run-hook`, remove those two lines from its
161
- settings.
146
+ asks you to commit the agent tool files. `wm update` and `wm init` also delete
147
+ any skill folder named `wm-*` that the installed `wm` doesn't ship, and list
148
+ each file as `removed:`. Folders with other names are left
149
+ alone, so don't name your own skills `wm-*`. `wm update` never changes the
150
+ record's format. A record in another format than the installed `wm` reads is
151
+ refused, its format named, and nothing changes.
152
+
153
+ If the agent tool files were ever committed, git keeps tracking them even with
154
+ the `.gitignore` block in place. `wm doctor` warns about them, and gives the
155
+ `git rm -r --cached` command that stops tracking them and keeps your copies. Run
156
+ it, then commit.
162
157
 
163
158
  ## Next
164
159