waymark-cli 0.1.0__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 (92) hide show
  1. waymark/__init__.py +3 -0
  2. waymark/__main__.py +8 -0
  3. waymark/adapters/__init__.py +102 -0
  4. waymark/adapters/claude_code.py +238 -0
  5. waymark/assets/__init__.py +43 -0
  6. waymark/assets/agents/wm-implementer.md +45 -0
  7. waymark/assets/agents/wm-reviewer.md +43 -0
  8. waymark/assets/skills/wm-apply/SKILL.md +58 -0
  9. waymark/assets/skills/wm-archive/SKILL.md +32 -0
  10. waymark/assets/skills/wm-explore/SKILL.md +34 -0
  11. waymark/assets/skills/wm-kickoff/SKILL.md +34 -0
  12. waymark/assets/skills/wm-onboard/SKILL.md +27 -0
  13. waymark/assets/skills/wm-pr/SKILL.md +24 -0
  14. waymark/assets/skills/wm-propose/SKILL.md +32 -0
  15. waymark/assets/skills/wm-update/SKILL.md +31 -0
  16. waymark/cli.py +537 -0
  17. waymark/hooks/__init__.py +6 -0
  18. waymark/hooks/commands.py +190 -0
  19. waymark/hooks/decide.py +314 -0
  20. waymark/hooks/events.py +79 -0
  21. waymark/py.typed +0 -0
  22. waymark/record/__init__.py +5 -0
  23. waymark/record/atlas.py +156 -0
  24. waymark/record/changes.py +202 -0
  25. waymark/record/charter.py +75 -0
  26. waymark/record/commits.py +78 -0
  27. waymark/record/config.py +215 -0
  28. waymark/record/deltas.py +318 -0
  29. waymark/record/design.py +80 -0
  30. waymark/record/edits.py +95 -0
  31. waymark/record/evidence.py +58 -0
  32. waymark/record/explorations.py +66 -0
  33. waymark/record/files.py +75 -0
  34. waymark/record/fingerprint.py +73 -0
  35. waymark/record/git.py +167 -0
  36. waymark/record/githooks.py +106 -0
  37. waymark/record/links.py +104 -0
  38. waymark/record/milestones.py +84 -0
  39. waymark/record/moves.py +60 -0
  40. waymark/record/names.py +39 -0
  41. waymark/record/outline.py +144 -0
  42. waymark/record/pointer.py +56 -0
  43. waymark/record/problems.py +20 -0
  44. waymark/record/project.py +118 -0
  45. waymark/record/proposal.py +171 -0
  46. waymark/record/record.py +340 -0
  47. waymark/record/registry.py +158 -0
  48. waymark/record/specs.py +227 -0
  49. waymark/record/state.py +472 -0
  50. waymark/record/store.py +88 -0
  51. waymark/record/tasks.py +415 -0
  52. waymark/record/templates/charter.md +45 -0
  53. waymark/record/templates/ci-workflow.yml +29 -0
  54. waymark/record/templates/config-atlas.toml +8 -0
  55. waymark/record/templates/config.toml +19 -0
  56. waymark/record/templates/delta.md +29 -0
  57. waymark/record/templates/design.md +20 -0
  58. waymark/record/templates/exploration.md +22 -0
  59. waymark/record/templates/goal.md +13 -0
  60. waymark/record/templates/hook-commit-msg +8 -0
  61. waymark/record/templates/hook-pre-commit +8 -0
  62. waymark/record/templates/proposal.md +18 -0
  63. waymark/record/templates/roadmap.md +4 -0
  64. waymark/record/templates/tasks.md +10 -0
  65. waymark/record/templates.py +30 -0
  66. waymark/record/terms.py +51 -0
  67. waymark/record/text.py +197 -0
  68. waymark/services/__init__.py +1 -0
  69. waymark/services/atlas.py +162 -0
  70. waymark/services/check.py +129 -0
  71. waymark/services/ci.py +44 -0
  72. waymark/services/common.py +154 -0
  73. waymark/services/context.py +296 -0
  74. waymark/services/doctor.py +367 -0
  75. waymark/services/githooks.py +132 -0
  76. waymark/services/instructions.py +304 -0
  77. waymark/services/integration.py +170 -0
  78. waymark/services/lifecycle.py +454 -0
  79. waymark/services/migrations.py +90 -0
  80. waymark/services/pr.py +177 -0
  81. waymark/services/references.py +27 -0
  82. waymark/services/setup.py +127 -0
  83. waymark/views/__init__.py +5 -0
  84. waymark/views/payloads.py +568 -0
  85. waymark/views/render.py +506 -0
  86. waymark/views/schemas.py +413 -0
  87. waymark/views/style.py +102 -0
  88. waymark_cli-0.1.0.dist-info/METADATA +313 -0
  89. waymark_cli-0.1.0.dist-info/RECORD +92 -0
  90. waymark_cli-0.1.0.dist-info/WHEEL +4 -0
  91. waymark_cli-0.1.0.dist-info/entry_points.txt +2 -0
  92. waymark_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,154 @@
1
+ """What every service shares: refusals, results, and opening the record."""
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path
5
+
6
+ from waymark import __version__
7
+ from waymark.record.atlas import Found, Location, locate_repo
8
+ from waymark.record.changes import Change
9
+ from waymark.record.config import CONFIG_FILE, RECORD_FORMAT
10
+ from waymark.record.project import RECORD_DIR, ProjectNotFoundError, find_project
11
+ from waymark.record.record import Record, load_record
12
+ from waymark.record.registry import Registry, load_registry
13
+ from waymark.record.state import ChangeState, change_state, overlaps
14
+ from waymark.record.store import StoreError, Transaction
15
+ from waymark.record.tasks import Item
16
+
17
+
18
+ class Refusal(Exception): # noqa: N818 - a refusal is an answer, not a fault
19
+ """A command was refused. The message says what is wrong and what to do next."""
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class Done:
24
+ """What a command did, in a sentence, and the record files it wrote."""
25
+
26
+ message: str
27
+ paths: tuple[str, ...] = ()
28
+
29
+
30
+ _NOTICES: list[str] = []
31
+
32
+
33
+ def notice(text: str) -> None:
34
+ """Something to tell the person running the command, beside its output."""
35
+ if text not in _NOTICES:
36
+ _NOTICES.append(text)
37
+
38
+
39
+ def take_notices() -> tuple[str, ...]:
40
+ """The notices gathered so far; the list starts again empty."""
41
+ found = tuple(_NOTICES)
42
+ _NOTICES.clear()
43
+ return found
44
+
45
+
46
+ def install_hint(version: str) -> str:
47
+ """The commands that install one exact version of wm."""
48
+ return (
49
+ f"pipx install --force waymark-cli=={version}"
50
+ f" (or: uv tool install --force waymark-cli=={version})"
51
+ )
52
+
53
+
54
+ def require_pinned(record: Record) -> None:
55
+ """Refuse to write unless the settings are readable and this wm is the pinned version."""
56
+ config = record.config
57
+ if config is None:
58
+ problems = [p for p in record.problems if p.path == CONFIG_FILE]
59
+ detail = problems[0].message if problems else "It could not be read."
60
+ raise Refusal(f"{RECORD_DIR}/{CONFIG_FILE} has problems. {detail}")
61
+ if config.wm_version != __version__:
62
+ raise Refusal(
63
+ f"This project is pinned to wm {config.wm_version}, and this is wm {__version__}. "
64
+ "Reading works with any version, but only the pinned one may write the record. "
65
+ f"Install it with: {install_hint(config.wm_version)}"
66
+ )
67
+
68
+
69
+ def require_writable(record: Record) -> None:
70
+ """Refuse to write unless this wm is the pinned one and the record is in its format."""
71
+ require_pinned(record)
72
+ config = record.config
73
+ assert config is not None
74
+ if config.record_format != RECORD_FORMAT:
75
+ raise Refusal(
76
+ f"The record is in format {config.record_format}, and this wm writes format "
77
+ f'{RECORD_FORMAT}. Run "wm update" to migrate the record.'
78
+ )
79
+
80
+
81
+ def open_record(start: Path, *, writing: bool = False) -> Record:
82
+ """Find and read the record around a folder; with ``writing``, check it may be written."""
83
+ try:
84
+ project = find_project(start)
85
+ except ProjectNotFoundError as error:
86
+ raise Refusal(str(error)) from error
87
+ for note in project.notes:
88
+ notice(note)
89
+ record = load_record(project)
90
+ if writing:
91
+ require_writable(record)
92
+ return record
93
+
94
+
95
+ def repo_locations(record: Record, registry: Registry | None = None) -> dict[str, Location]:
96
+ """Where each of the atlas's code repos is on this machine; empty outside an atlas.
97
+
98
+ A repo found only through its path hint is used, with a notice that says
99
+ how to register it.
100
+ """
101
+ config = record.config
102
+ if config is None or config.atlas_name is None:
103
+ return {}
104
+ known = load_registry() if registry is None else registry
105
+ found = {
106
+ repo.name: locate_repo(config.atlas_name, record.project.root, repo, known)
107
+ for repo in config.repos
108
+ }
109
+ for location in found.values():
110
+ if location.found is Found.HINT:
111
+ notice(f"{location.detail} ({location.folder})")
112
+ return found
113
+
114
+
115
+ def find_change(record: Record, name: str) -> Change:
116
+ """An active change by name."""
117
+ change = record.changes.get(name)
118
+ if change is None:
119
+ active = ", ".join(sorted(record.changes)) or "none"
120
+ raise Refusal(f'There is no active change "{name}". Active changes: {active}.')
121
+ return change
122
+
123
+
124
+ def find_item(change: Change, number: str) -> Item:
125
+ """One of a change's task items by number."""
126
+ item = change.tasks.item(number) if change.tasks else None
127
+ if item is None:
128
+ numbers = ", ".join(i.number for i in change.tasks.items) if change.tasks else ""
129
+ raise Refusal(
130
+ f'The change "{change.name}" has no item {number}. Its items: {numbers or "none"}.'
131
+ )
132
+ return item
133
+
134
+
135
+ def state_of(record: Record, change: Change) -> ChangeState:
136
+ """A change's derived state."""
137
+ return change_state(record, change, overlaps(record))
138
+
139
+
140
+ def commit(transaction: Transaction) -> tuple[str, ...]:
141
+ """Apply a transaction; a failed write becomes a refusal, with the record untouched."""
142
+ try:
143
+ transaction.commit()
144
+ except StoreError as error:
145
+ raise Refusal(str(error)) from error
146
+ return transaction.paths
147
+
148
+
149
+ def one_line(text: str, what: str) -> str:
150
+ """Text for a single evidence line: whitespace collapsed, and not empty."""
151
+ collapsed = " ".join(text.split())
152
+ if not collapsed:
153
+ raise Refusal(f"Give {what}; it is written into the record.")
154
+ return collapsed
@@ -0,0 +1,296 @@
1
+ """Context packs: the excerpts of the record one job gets, and nothing else.
2
+
3
+ An implementer gets its item, the change's proposal, deltas and design, the
4
+ requirements those deltas touch, and the project's context and apply rules. A
5
+ reviewer gets the item with its criteria and verification, the deltas and
6
+ their scenarios, and the project's context and review rules; it does not get
7
+ the implementer's notes, the proposal or the design.
8
+
9
+ Building a pack for an implementer or reviewer is also the delegation gate:
10
+ it is refused unless the change is accepted, the item has criteria and the
11
+ record around it has no problems.
12
+ """
13
+
14
+ from typing import Any
15
+
16
+ from waymark.record.atlas import Location
17
+ from waymark.record.changes import Change
18
+ from waymark.record.links import LinkChecker
19
+ from waymark.record.record import Record
20
+ from waymark.record.state import (
21
+ AcceptanceState,
22
+ ChangeState,
23
+ ConflictKind,
24
+ ExplorationStatus,
25
+ ItemState,
26
+ derive_state,
27
+ )
28
+ from waymark.record.tasks import Item, RecordKind
29
+ from waymark.record.terms import Layout, ReviewLevel, Step
30
+ from waymark.record.text import Document
31
+ from waymark.services.common import Refusal, find_change, find_item, repo_locations, state_of
32
+ from waymark.services.references import reference_record
33
+
34
+ CONTEXT_VERSION = 1
35
+ EXPLORE = "explore"
36
+ IMPLEMENT = "implement"
37
+ REVIEW = "review"
38
+ ROLES = (EXPLORE, IMPLEMENT, REVIEW)
39
+
40
+ RESULT_LINE = "RESULT: done | partial | spec-gap | blocked"
41
+ VERDICT_LINE = "VERDICT: pass | changes | spec-gap"
42
+
43
+ _ENDINGS = {
44
+ IMPLEMENT: (
45
+ f'End your reply with one line, "{RESULT_LINE}", followed by a short note. '
46
+ "Use spec-gap when the record isn't enough to build the item; don't guess."
47
+ ),
48
+ REVIEW: (
49
+ f'End your reply with one line, "{VERDICT_LINE}", followed by your reasons. '
50
+ "Use spec-gap when the record isn't enough to judge the item."
51
+ ),
52
+ }
53
+
54
+
55
+ def _text(doc: Document) -> str:
56
+ """A document's text with line feeds, whatever the file uses."""
57
+ return "\n".join(line.text for line in doc.lines).strip("\n")
58
+
59
+
60
+ def _documents(change: Change) -> list[Document]:
61
+ docs = [change.proposal.doc] if change.proposal else []
62
+ docs += [delta.doc for _, delta in sorted(change.deltas.items())]
63
+ docs += [change.design.doc] if change.design else []
64
+ docs += [change.tasks.doc] if change.tasks else []
65
+ return docs
66
+
67
+
68
+ def record_warnings(record: Record, change: Change, state: ChangeState) -> list[str]:
69
+ """What is wrong in the record around a change: format problems, broken links, conflicts."""
70
+ warnings = [f"{p.path}:{p.line}: {p.message}" for p in change.problems]
71
+ checker = LinkChecker(record.project.record_root)
72
+ for doc in _documents(change):
73
+ warnings += [f"{p.path}:{p.line}: {p.message}" for p in checker.problems(doc)]
74
+ warnings += [c.message for c in state.conflicts if c.kind is ConflictKind.MISMATCH]
75
+ return warnings
76
+
77
+
78
+ def _acceptance_problem(state: ChangeState) -> str | None:
79
+ if state.acceptance is AcceptanceState.MISSING:
80
+ return (
81
+ f'The change "{state.name}" is not accepted, so none of its items can be '
82
+ f'delegated. The human accepts it with "wm accept {state.name}".'
83
+ )
84
+ if state.acceptance is AcceptanceState.WITHDRAWN:
85
+ return (
86
+ f'The acceptance of "{state.name}" was withdrawn, so none of its items can be '
87
+ f'delegated. The human accepts it again with "wm accept {state.name}".'
88
+ )
89
+ return None
90
+
91
+
92
+ def _item_problem( # noqa: PLR0911 - one return per reason an item can't be delegated
93
+ name: str, item: Item, item_state: ItemState, role: str
94
+ ) -> str | None:
95
+ number = item.number
96
+ resolve = f'"wm resolve {name} {number} "<what was decided>""'
97
+ if item_state.escalated or (item.blocked and not item.ticked):
98
+ why = item_state.escalated or f"it is blocked: {item.blocked}"
99
+ return f"Item {number} waits on the human: {why}. Once that is settled, run {resolve}."
100
+ if item_state.redo:
101
+ return (
102
+ f"A review asked for changes to item {number}. Reopen it first with "
103
+ f'"wm reopen {name} {number}".'
104
+ )
105
+ if not item.criteria:
106
+ return (
107
+ f"Item {number} has no criteria, so there is nothing to build or review against. "
108
+ 'Add a "Criteria:" line under it; that edits the change, so it needs accepting again.'
109
+ )
110
+ if role == IMPLEMENT and item.ticked:
111
+ return f"Item {number} is already ticked. Pick an item that is still to apply."
112
+ if role == REVIEW and not item.ticked:
113
+ return f"Item {number} isn't ticked yet, so there is nothing to review."
114
+ if role == REVIEW and item_state.level is ReviewLevel.NONE:
115
+ return f"Item {number} is at review level none and needs no review."
116
+ if role == REVIEW and item_state.reviewed:
117
+ return f"Item {number} already has the review record it needs."
118
+ return None
119
+
120
+
121
+ def item_location(record: Record, item: Item) -> Location | None:
122
+ """Where the code repo an item names is on this machine; None when it names none."""
123
+ if record.layout is not Layout.ATLAS or not item.repo:
124
+ return None
125
+ return repo_locations(record).get(item.repo)
126
+
127
+
128
+ def delegation_problems(record: Record, change: Change, item: Item, role: str) -> list[str]:
129
+ """Why an implementer or reviewer may not be started on an item; empty when it may."""
130
+ state = state_of(record, change)
131
+ item_state = next(i for i in state.items if i.number == item.number)
132
+ first = _acceptance_problem(state) or _item_problem(change.name, item, item_state, role)
133
+ if first:
134
+ return [first]
135
+ warnings = record_warnings(record, change, state)
136
+ location = item_location(record, item)
137
+ if location is not None and location.folder is None:
138
+ warnings.append(f"Item {item.number} works in a repo that isn't here. {location.detail}")
139
+ return warnings
140
+
141
+
142
+ def _item(
143
+ item: Item, item_state: ItemState, role: str, location: Location | None
144
+ ) -> dict[str, Any]:
145
+ reviews = [
146
+ {
147
+ "date": r.date.isoformat(),
148
+ "verdict": r.verdict.value if r.verdict else None,
149
+ "text": r.text,
150
+ }
151
+ for r in item.records
152
+ if r.kind is RecordKind.REVIEW
153
+ ]
154
+ resolutions = [r.text for r in item.records if r.kind is RecordKind.RESOLVED]
155
+ return {
156
+ "number": item.number,
157
+ "title": item.title,
158
+ "criteria": item.criteria,
159
+ "verify": item.verify,
160
+ "repo": item.repo,
161
+ "repo_found": None if location is None else location.folder is not None,
162
+ "_local": {"repo_folder": str(location.folder) if location and location.folder else None},
163
+ "review_level": item_state.level.value,
164
+ "notes": list(item.notes) if role == IMPLEMENT else [],
165
+ "reviews": reviews,
166
+ "resolutions": resolutions,
167
+ }
168
+
169
+
170
+ def _deltas(change: Change) -> list[dict[str, Any]]:
171
+ return [
172
+ {"spec": domain, "text": _text(delta.doc)}
173
+ for domain, delta in sorted(change.deltas.items())
174
+ ]
175
+
176
+
177
+ def _touched_requirements(record: Record, change: Change) -> list[dict[str, Any]]:
178
+ """The living text of every requirement the change modifies or removes."""
179
+ touched: list[dict[str, Any]] = []
180
+ for domain, delta in sorted(change.deltas.items()):
181
+ spec = record.specs.get(domain)
182
+ names = [r.name for r in delta.modified] + [r.name for r in delta.removed]
183
+ for name in names:
184
+ living = spec.requirement(name) if spec else None
185
+ if living is not None:
186
+ touched.append(
187
+ {"spec": domain, "name": living.name, "text": "\n".join(living.block)}
188
+ )
189
+ return touched
190
+
191
+
192
+ def _delegated_pack(record: Record, role: str, change_name: str, number: str) -> dict[str, Any]:
193
+ change = find_change(record, change_name)
194
+ item = find_item(change, number)
195
+ problems = delegation_problems(record, change, item, role)
196
+ if problems:
197
+ more = f" ({len(problems) - 1} more; see wm check)" if len(problems) > 1 else ""
198
+ raise Refusal(f"No {role} context pack for {change_name} {number}: {problems[0]}{more}")
199
+ state = state_of(record, change)
200
+ item_state = next(i for i in state.items if i.number == item.number)
201
+ charter = record.charter
202
+ step = Step.APPLY if role == IMPLEMENT else Step.REVIEW
203
+ implementing = role == IMPLEMENT
204
+ proposal = change.proposal
205
+ return {
206
+ "schema": f"wm.context.{role}",
207
+ "version": CONTEXT_VERSION,
208
+ "for": role,
209
+ "change": change.name,
210
+ "item": _item(item, item_state, role, item_location(record, item)),
211
+ "context": charter.context if charter else "",
212
+ "rules": charter.rules.get(step, "") if charter else "",
213
+ "proposal": dict(proposal.sections) if proposal and implementing else None,
214
+ "deltas": _deltas(change),
215
+ "requirements": _touched_requirements(record, change) if implementing else [],
216
+ "design": _text(change.design.doc) if change.design and implementing else None,
217
+ "ends_with": _ENDINGS[role],
218
+ }
219
+
220
+
221
+ def _references(record: Record) -> list[dict[str, Any]]:
222
+ """An index of every referenced atlas's specs. Their text is fetched on request."""
223
+ index: list[dict[str, Any]] = []
224
+ for reference in record.config.references if record.config else ():
225
+ try:
226
+ other = reference_record(record, reference.atlas)
227
+ except Refusal:
228
+ index.append({"atlas": reference.atlas, "found": False, "specs": []})
229
+ continue
230
+ specs = [
231
+ {"name": name, "title": spec.title, "purpose": spec.purpose}
232
+ for name, spec in sorted(other.specs.items())
233
+ ]
234
+ index.append({"atlas": reference.atlas, "found": True, "specs": specs})
235
+ return index
236
+
237
+
238
+ def _explore_pack(record: Record) -> dict[str, Any]:
239
+ state = derive_state(record)
240
+ charter = record.charter
241
+ return {
242
+ "schema": "wm.context.explore",
243
+ "version": CONTEXT_VERSION,
244
+ "for": EXPLORE,
245
+ "charter": dict(charter.sections) if charter else {},
246
+ "rules": charter.rules.get(Step.EXPLORE, "") if charter else "",
247
+ "specs": [
248
+ {
249
+ "name": name,
250
+ "title": spec.title,
251
+ "purpose": spec.purpose,
252
+ "requirements": [requirement.name for requirement in spec.requirements],
253
+ }
254
+ for name, spec in sorted(record.specs.items())
255
+ ],
256
+ "changes": [
257
+ {
258
+ "name": name,
259
+ "title": change.proposal.title if change.proposal else "",
260
+ "phase": state.changes[name].phase.value,
261
+ }
262
+ for name, change in sorted(record.changes.items())
263
+ ],
264
+ "milestones": [
265
+ {"name": name, "archived": milestone.archived, "total": milestone.total}
266
+ for name, milestone in sorted(state.milestones.items())
267
+ ],
268
+ "explorations": [
269
+ {
270
+ "name": name,
271
+ "title": record.explorations[name].title,
272
+ "status": exploration.status.value,
273
+ "detail": exploration.detail
274
+ if exploration.status is not ExplorationStatus.UNREADABLE
275
+ else None,
276
+ }
277
+ for name, exploration in sorted(state.explorations.items())
278
+ ],
279
+ "references": _references(record),
280
+ }
281
+
282
+
283
+ def context_pack(
284
+ record: Record, role: str, change_name: str | None = None, number: str | None = None
285
+ ) -> dict[str, Any]:
286
+ """The context pack for one job. For an implementer or reviewer this is the delegation gate."""
287
+ if role == EXPLORE:
288
+ if change_name or number:
289
+ raise Refusal("An explore context pack takes no change or item.")
290
+ return _explore_pack(record)
291
+ if not change_name or not number:
292
+ raise Refusal(
293
+ f"A context pack for {role} names exactly one change and one item: "
294
+ f"wm context <change> <item> --for {role}"
295
+ )
296
+ return _delegated_pack(record, role, change_name, number)