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,88 @@
1
+ """Writing the record: several files and a folder move as one step.
2
+
3
+ A transaction collects the files to write and the folder to move, then applies
4
+ them together. If anything fails, every file is put back and the move undone,
5
+ so a multi-file operation either completes or leaves the record as it was.
6
+ """
7
+
8
+ from pathlib import Path
9
+
10
+ from waymark.record.files import RecordFiles
11
+
12
+
13
+ class StoreError(Exception):
14
+ """The record could not be written; it has been left as it was."""
15
+
16
+
17
+ class Transaction:
18
+ """Staged writes under one record root. Paths are record-relative, with forward slashes."""
19
+
20
+ def __init__(self, files: RecordFiles) -> None:
21
+ self._files = files
22
+ self._writes: dict[str, str] = {}
23
+ self._moves: list[tuple[str, str]] = []
24
+
25
+ def write(self, relative: str, text: str) -> None:
26
+ """Stage a file's new text. Files are written as UTF-8, exactly as given."""
27
+ self._writes[relative] = text
28
+
29
+ def move(self, source: str, target: str) -> None:
30
+ """Stage a folder move. It happens after the writes, which use the old paths."""
31
+ self._moves.append((source, target))
32
+
33
+ def staged(self, relative: str) -> str | None:
34
+ """The text staged for a file, if any."""
35
+ return self._writes.get(relative)
36
+
37
+ @property
38
+ def paths(self) -> tuple[str, ...]:
39
+ """Every file staged for writing, in order."""
40
+ return tuple(sorted(self._writes))
41
+
42
+ def commit(self) -> None:
43
+ """Apply everything, or nothing."""
44
+ originals: dict[Path, bytes | None] = {}
45
+ moved: list[tuple[Path, Path]] = []
46
+ try:
47
+ for relative, text in sorted(self._writes.items()):
48
+ path = self._files.path(relative)
49
+ if path not in originals:
50
+ originals[path] = path.read_bytes() if path.is_file() else None
51
+ path.parent.mkdir(parents=True, exist_ok=True)
52
+ _replace(path, text.encode("utf-8"))
53
+ for source, target in self._moves:
54
+ origin, destination = self._files.path(source), self._files.path(target)
55
+ if destination.exists():
56
+ raise FileExistsError(f"{target} already exists")
57
+ destination.parent.mkdir(parents=True, exist_ok=True)
58
+ origin.rename(destination)
59
+ moved.append((origin, destination))
60
+ except OSError as error:
61
+ _roll_back(originals, moved)
62
+ raise StoreError(
63
+ f"The record could not be written ({error}). Nothing was changed. "
64
+ "Check the folder's permissions and that no other program has the files open."
65
+ ) from error
66
+
67
+
68
+ def _replace(path: Path, data: bytes) -> None:
69
+ """Write a file through a temporary neighbor, so a crash never leaves it half written."""
70
+ temporary = path.with_name(f"{path.name}.wm-tmp")
71
+ temporary.write_bytes(data)
72
+ temporary.replace(path)
73
+
74
+
75
+ def _roll_back(originals: dict[Path, bytes | None], moved: list[tuple[Path, Path]]) -> None:
76
+ for origin, destination in reversed(moved):
77
+ try:
78
+ destination.rename(origin)
79
+ except OSError:
80
+ continue
81
+ for path, data in originals.items():
82
+ try:
83
+ if data is None:
84
+ path.unlink(missing_ok=True)
85
+ else:
86
+ path.write_bytes(data)
87
+ except OSError:
88
+ continue
@@ -0,0 +1,415 @@
1
+ """Task lists: numbered sections of checkbox items, with the evidence under each item.
2
+
3
+ An item's definition is its number, title, review level, criteria, verification
4
+ and repo. Its evidence is its tick, its blocker, its spec gap and its review
5
+ records.
6
+ """
7
+
8
+ import datetime
9
+ import re
10
+ from collections.abc import Mapping
11
+ from dataclasses import dataclass, field
12
+ from enum import StrEnum
13
+
14
+ from waymark.record.problems import Problem
15
+ from waymark.record.terms import ReviewLevel, Verdict
16
+ from waymark.record.text import Document, Section
17
+
18
+ BLOCKED = "Blocked"
19
+ SPEC_GAP = "Spec gap"
20
+
21
+ _SECTION = re.compile(r"^(\d+)\.\s+(\S.*)$")
22
+ _ITEM = re.compile(r"^- \[([ xX])\] (\d+)\.(\d+)\s+(\S.*?)\s*$")
23
+ _LEVEL_TAG = re.compile(r"\s+`review:\s*([A-Za-z-]+)`$")
24
+ _LIST_LINE = re.compile(r"^(?:[-*+]|\d+[.)])(?:\s|$)")
25
+ _FIELD = re.compile(r"^ [-*] (\S.*)$")
26
+ _LABELED = re.compile(r"^(Criteria|Verify|Repo|Blocked|Spec gap|Note):(?:\s+(.*))?$")
27
+ _EVIDENCE = re.compile(r"^\((review|self-review|reopened|resolved)\)")
28
+ _REVIEW = re.compile(r"^\(review\) (\d{4}-\d{2}-\d{2}) (pass|changes|spec-gap): (\S.*)$")
29
+ _SELF_REVIEW = re.compile(r"^\(self-review\) (\d{4}-\d{2}-\d{2}): (\S.*)$")
30
+ _REOPENED = re.compile(r"^\(reopened\) (\d{4}-\d{2}-\d{2})$")
31
+ _RESOLVED = re.compile(r"^\(resolved\) (\d{4}-\d{2}-\d{2}): (\S.*)$")
32
+
33
+ _FORMATS = (
34
+ '"(review) YYYY-MM-DD pass|changes|spec-gap: <reasons>", '
35
+ '"(self-review) YYYY-MM-DD: <summary>", "(reopened) YYYY-MM-DD" or '
36
+ '"(resolved) YYYY-MM-DD: <what was decided>"'
37
+ )
38
+
39
+
40
+ class RecordKind(StrEnum):
41
+ """The kinds of review record under an item."""
42
+
43
+ REVIEW = "review"
44
+ SELF_REVIEW = "self-review"
45
+ REOPENED = "reopened"
46
+ RESOLVED = "resolved"
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class ReviewRecord:
51
+ """One record: a reviewer's verdict, a self-review, a reopening or a resolution."""
52
+
53
+ kind: RecordKind
54
+ date: datetime.date
55
+ verdict: Verdict | None
56
+ text: str
57
+ index: int
58
+
59
+
60
+ @dataclass(frozen=True)
61
+ class Item:
62
+ """One task item, with what is written under it.
63
+
64
+ ``end`` is the index after the item's last line. ``spans`` gives the line
65
+ range of each labeled line under the item.
66
+ """
67
+
68
+ number: str
69
+ section: int
70
+ title: str
71
+ ticked: bool
72
+ level_tag: ReviewLevel | None
73
+ criteria: str | None
74
+ verify: str | None
75
+ repo: str | None
76
+ blocked: str | None
77
+ spec_gap: str | None
78
+ notes: tuple[str, ...]
79
+ records: tuple[ReviewRecord, ...]
80
+ index: int
81
+ end: int
82
+ spans: Mapping[str, tuple[int, int]]
83
+
84
+ def level(self, default: ReviewLevel) -> ReviewLevel:
85
+ """The item's review level: its tag, or the project default."""
86
+ return self.level_tag or default
87
+
88
+
89
+ @dataclass(frozen=True)
90
+ class TaskSection:
91
+ """A numbered section of a task list."""
92
+
93
+ number: int
94
+ title: str
95
+ index: int
96
+
97
+
98
+ @dataclass(frozen=True)
99
+ class Tasks:
100
+ """A change's task list."""
101
+
102
+ doc: Document
103
+ sections: tuple[TaskSection, ...]
104
+ items: tuple[Item, ...]
105
+ problems: tuple[Problem, ...]
106
+
107
+ def item(self, number: str) -> Item | None:
108
+ return next((item for item in self.items if item.number == number), None)
109
+
110
+
111
+ @dataclass
112
+ class _Draft:
113
+ """An item while its lines are still being read."""
114
+
115
+ number: str
116
+ section: int
117
+ title: str
118
+ ticked: bool
119
+ level_tag: ReviewLevel | None
120
+ index: int
121
+ end: int
122
+ fields: dict[str, list[str]] = field(default_factory=dict)
123
+ spans: dict[str, tuple[int, int]] = field(default_factory=dict)
124
+ notes: list[list[str]] = field(default_factory=list)
125
+ records: list[ReviewRecord] = field(default_factory=list)
126
+ open_text: list[str] | None = None
127
+ open_label: str | None = None
128
+
129
+ def extend(self, index: int, text: str) -> None:
130
+ """Add a continuation line to the field that is still open."""
131
+ assert self.open_text is not None
132
+ self.open_text.append(text)
133
+ self.end = index + 1
134
+ if self.open_label is not None:
135
+ self.spans[self.open_label] = (self.spans[self.open_label][0], index + 1)
136
+
137
+ def finish(self) -> Item:
138
+ def single(label: str) -> str | None:
139
+ return "\n".join(self.fields[label]).strip() if label in self.fields else None
140
+
141
+ return Item(
142
+ number=self.number,
143
+ section=self.section,
144
+ title=self.title,
145
+ ticked=self.ticked,
146
+ level_tag=self.level_tag,
147
+ criteria=single("Criteria"),
148
+ verify=single("Verify"),
149
+ repo=single("Repo"),
150
+ blocked=single(BLOCKED),
151
+ spec_gap=single(SPEC_GAP),
152
+ notes=tuple("\n".join(note).strip() for note in self.notes),
153
+ records=tuple(self.records),
154
+ index=self.index,
155
+ end=self.end,
156
+ spans=dict(self.spans),
157
+ )
158
+
159
+
160
+ class _Parser:
161
+ def __init__(self, doc: Document) -> None:
162
+ self.doc = doc
163
+ self.problems: list[Problem] = []
164
+ self.sections: list[TaskSection] = []
165
+ self.items: list[Item] = []
166
+ self.draft: _Draft | None = None
167
+
168
+ def problem(self, index: int, code: str, message: str) -> None:
169
+ self.problems.append(Problem(self.doc.path, index + 1, code, message))
170
+
171
+ def close_item(self) -> None:
172
+ if self.draft is not None:
173
+ self.items.append(self.draft.finish())
174
+ self.draft = None
175
+
176
+ def date(self, index: int, text: str) -> datetime.date | None:
177
+ try:
178
+ return datetime.date.fromisoformat(text)
179
+ except ValueError:
180
+ self.problem(
181
+ index, "malformed-evidence", f'"{text}" is not a date. Write it as YYYY-MM-DD.'
182
+ )
183
+ return None
184
+
185
+ def evidence(self, index: int, text: str) -> None:
186
+ draft = self.draft
187
+ assert draft is not None
188
+ review = _REVIEW.match(text)
189
+ self_review = _SELF_REVIEW.match(text)
190
+ resolved = _RESOLVED.match(text)
191
+ match = review or self_review or resolved or _REOPENED.match(text)
192
+ if match is None:
193
+ self.problem(
194
+ index,
195
+ "malformed-evidence",
196
+ f"This review record doesn't follow the format. Write it as {_FORMATS}.",
197
+ )
198
+ return
199
+ date = self.date(index, match.group(1))
200
+ if date is None:
201
+ return
202
+ if review:
203
+ record = ReviewRecord(
204
+ RecordKind.REVIEW, date, Verdict(review.group(2)), review.group(3).strip(), index
205
+ )
206
+ elif self_review:
207
+ record = ReviewRecord(
208
+ RecordKind.SELF_REVIEW, date, None, self_review.group(2).strip(), index
209
+ )
210
+ elif resolved:
211
+ record = ReviewRecord(RecordKind.RESOLVED, date, None, resolved.group(2).strip(), index)
212
+ else:
213
+ record = ReviewRecord(RecordKind.REOPENED, date, None, "", index)
214
+ draft.records.append(record)
215
+
216
+ def labeled(self, index: int, label: str, value: str) -> None:
217
+ draft = self.draft
218
+ assert draft is not None
219
+ if label == "Note":
220
+ draft.notes.append([value])
221
+ draft.open_text = draft.notes[-1]
222
+ elif label in draft.fields:
223
+ self.problem(
224
+ index, "duplicate-field", f'"{label}:" appears twice under this item. Keep one.'
225
+ )
226
+ else:
227
+ draft.fields[label] = [value]
228
+ draft.spans[label] = (index, index + 1)
229
+ draft.open_text = draft.fields[label]
230
+ draft.open_label = label
231
+
232
+ def field_line(self, index: int, text: str) -> None:
233
+ draft = self.draft
234
+ assert draft is not None
235
+ draft.open_text = None
236
+ draft.open_label = None
237
+ draft.end = index + 1
238
+ labeled = _LABELED.match(text)
239
+ if labeled:
240
+ self.labeled(index, labeled.group(1), (labeled.group(2) or "").strip())
241
+ elif _EVIDENCE.match(text):
242
+ self.evidence(index, text)
243
+ else:
244
+ self.problem(
245
+ index,
246
+ "unrecognized-item-line",
247
+ 'A line under an item starts with "Criteria:", "Verify:", "Repo:", "Blocked:", '
248
+ '"Spec gap:" or "Note:", or is a review record. Label this line, or make it '
249
+ 'a "Note:".',
250
+ )
251
+
252
+ def item_line(self, index: int, section: TaskSection | None, text: str) -> bool:
253
+ match = _ITEM.match(text)
254
+ if match is None:
255
+ return False
256
+ self.close_item()
257
+ title = match.group(4)
258
+ level_tag: ReviewLevel | None = None
259
+ tag = _LEVEL_TAG.search(title)
260
+ if tag:
261
+ title = title[: tag.start()].rstrip()
262
+ if tag.group(1) in set(ReviewLevel):
263
+ level_tag = ReviewLevel(tag.group(1))
264
+ else:
265
+ levels = ", ".join(level.value for level in ReviewLevel)
266
+ self.problem(
267
+ index,
268
+ "unknown-review-level",
269
+ f'"{tag.group(1)}" is not a review level. Use one of: {levels}.',
270
+ )
271
+ number = f"{match.group(2)}.{match.group(3)}"
272
+ if section is None:
273
+ self.problem(
274
+ index,
275
+ "item-outside-section",
276
+ f'Item {number} is not under a numbered section. Put it under "## <n>. <title>".',
277
+ )
278
+ elif int(match.group(2)) != section.number:
279
+ self.problem(
280
+ index,
281
+ "item-number",
282
+ f"Item {number} sits in section {section.number}. "
283
+ f"Number it {section.number}.<n>, or move it to its own section.",
284
+ )
285
+ self.draft = _Draft(
286
+ number=number,
287
+ section=int(match.group(2)),
288
+ title=title,
289
+ ticked=match.group(1) != " ",
290
+ level_tag=level_tag,
291
+ index=index,
292
+ end=index + 1,
293
+ )
294
+ return True
295
+
296
+ def body_line(self, index: int, section: TaskSection | None) -> None:
297
+ line = self.doc.lines[index]
298
+ text = line.text
299
+ draft = self.draft
300
+ if line.in_fence or line.is_blank:
301
+ if draft is not None and draft.open_text is not None and line.in_fence:
302
+ draft.extend(index, text.strip())
303
+ return
304
+ if not text.startswith(" "):
305
+ if self.item_line(index, section, text):
306
+ return
307
+ self.close_item()
308
+ if _LIST_LINE.match(text):
309
+ self.problem(
310
+ index,
311
+ "malformed-item",
312
+ 'An item is written "- [ ] <section>.<n> <title>", for example '
313
+ '"- [ ] 1.1 Add the endpoint". Fix this line, or indent it under an item.',
314
+ )
315
+ return
316
+ if draft is None:
317
+ return
318
+ field_match = _FIELD.match(text)
319
+ if field_match:
320
+ self.field_line(index, field_match.group(1).strip())
321
+ elif draft.open_text is not None:
322
+ draft.extend(index, text.strip())
323
+ else:
324
+ self.problem(
325
+ index,
326
+ "unrecognized-item-line",
327
+ 'Lines under an item are a list indented by two spaces, such as " - Criteria: '
328
+ '...". Fix the indentation, or label the line.',
329
+ )
330
+
331
+ def section(self, section: Section) -> TaskSection | None:
332
+ match = _SECTION.match(section.title)
333
+ if match is None:
334
+ self.problem(
335
+ section.start,
336
+ "task-section-format",
337
+ f'"{section.title}" is not a task section. Write it as "## <n>. <title>".',
338
+ )
339
+ return None
340
+ task_section = TaskSection(int(match.group(1)), match.group(2).strip(), section.start)
341
+ self.sections.append(task_section)
342
+ return task_section
343
+
344
+ def check_numbering(self) -> None:
345
+ last_section = 0
346
+ for task_section in self.sections:
347
+ if task_section.number <= last_section:
348
+ self.problem(
349
+ task_section.index,
350
+ "section-number",
351
+ f"Section {task_section.number} is out of order or used twice. "
352
+ "Section numbers go up and are never reused.",
353
+ )
354
+ last_section = max(last_section, task_section.number)
355
+ last_item: dict[int, int] = {}
356
+ for item in self.items:
357
+ position = int(item.number.split(".")[1])
358
+ if position <= last_item.get(item.section, 0):
359
+ self.problem(
360
+ item.index,
361
+ "item-number",
362
+ f"Item {item.number} is out of order or used twice. Item numbers go up "
363
+ "within a section and are never reused; append new items at the end.",
364
+ )
365
+ last_item[item.section] = max(last_item.get(item.section, 0), position)
366
+
367
+ def check_fields(self) -> None:
368
+ for item in self.items:
369
+ values = {
370
+ "Criteria": item.criteria,
371
+ "Verify": item.verify,
372
+ "Repo": item.repo,
373
+ BLOCKED: item.blocked,
374
+ SPEC_GAP: item.spec_gap,
375
+ }
376
+ for label, value in values.items():
377
+ if value is not None and not value:
378
+ self.problem(
379
+ item.index,
380
+ "empty-field",
381
+ f'"{label}:" under item {item.number} is empty. '
382
+ "Write it, or remove the line.",
383
+ )
384
+
385
+ def parse(self) -> Tasks:
386
+ doc = self.doc
387
+ sections = doc.sections(2)
388
+ first = sections[0].start if sections else len(doc.lines)
389
+ for index in range(first):
390
+ self.body_line(index, None)
391
+ self.close_item()
392
+ for section in sections:
393
+ task_section = self.section(section)
394
+ for index in range(section.body_start, section.end):
395
+ self.body_line(index, task_section)
396
+ self.close_item()
397
+ self.check_numbering()
398
+ self.check_fields()
399
+ return Tasks(doc, tuple(self.sections), tuple(self.items), tuple(self.problems))
400
+
401
+
402
+ def parse_tasks(doc: Document) -> Tasks:
403
+ """Read a task list."""
404
+ return _Parser(doc).parse()
405
+
406
+
407
+ def is_evidence_line(text: str) -> bool:
408
+ """Whether a line under an item is gate evidence: a blocker, a spec gap or a record."""
409
+ match = _FIELD.match(text)
410
+ if match is None:
411
+ return False
412
+ content = match.group(1)
413
+ return (
414
+ content.startswith((f"{BLOCKED}:", f"{SPEC_GAP}:")) or _EVIDENCE.match(content) is not None
415
+ )
@@ -0,0 +1,45 @@
1
+ # {{title}}
2
+
3
+ ## Vision
4
+
5
+ <!-- What this project is, and for whom, in a few sentences. -->
6
+
7
+ ## Goals
8
+
9
+ <!-- What it must achieve. -->
10
+
11
+ ## Non-goals
12
+
13
+ <!-- What it deliberately leaves out. -->
14
+
15
+ ## Constraints
16
+
17
+ <!-- Limits every change must respect: platforms, dependencies, budgets. -->
18
+
19
+ ## Glossary
20
+
21
+ <!-- The project's own terms, one per line: "Term: meaning". -->
22
+
23
+ ## Context
24
+
25
+ <!-- Facts every agent needs: where things live, how to run and test, who owns what. -->
26
+
27
+ ## Rules
28
+
29
+ <!-- Project-specific rules for each workflow step. Each agent gets only its step's rules. -->
30
+
31
+ ### explore
32
+
33
+ ### propose
34
+
35
+ ### specs
36
+
37
+ ### design
38
+
39
+ ### tasks
40
+
41
+ ### apply
42
+
43
+ ### review
44
+
45
+ ### archive
@@ -0,0 +1,29 @@
1
+ # Written by wm (Waymark): checks the record on every push and pull request.
2
+ # "wm update" keeps it current. It installs the wm version pinned in
3
+ # waymark/config.toml, so bumping the pin needs no change here.
4
+ name: Waymark
5
+
6
+ on:
7
+ push:
8
+ pull_request:
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ jobs:
14
+ check:
15
+ name: wm check
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - uses: actions/checkout@v7
19
+ with:
20
+ fetch-depth: 0
21
+ - uses: actions/setup-python@v7
22
+ with:
23
+ python-version: "3.x"
24
+ - name: Install the pinned wm
25
+ run: |
26
+ version=$(python -c "import tomllib; print(tomllib.load(open('waymark/config.toml', 'rb'))['wm_version'])")
27
+ python -m pip install "waymark-cli==$version"
28
+ - name: Check the record
29
+ run: wm check
@@ -0,0 +1,8 @@
1
+
2
+ [atlas]
3
+ # The atlas's name. Each machine finds the atlas by it.
4
+ name = "{{atlas_name}}"
5
+
6
+ # One table per code repo, with an optional relative-path hint:
7
+ # [atlas.repos.backend]
8
+ # path = "../backend"
@@ -0,0 +1,19 @@
1
+ # Waymark settings. wm reads this file; edit the values and keep the keys.
2
+
3
+ # The exact wm version this project uses. Any version can read the record;
4
+ # only this one may write it.
5
+ wm_version = "{{wm_version}}"
6
+
7
+ # The record's format. "wm update" advances it; don't edit it by hand.
8
+ record_format = {{record_format}}
9
+
10
+ # How a task item is reviewed unless it says otherwise:
11
+ # "self", "independent" or "none".
12
+ default_review = "self"
13
+
14
+ # The agent tools this project uses.
15
+ agent_tools = [{{agent_tools}}]
16
+
17
+ # Optional: the scopes commit messages may use. Without a list, any scope is
18
+ # accepted.
19
+ # commit_scopes = ["api", "docs"]
@@ -0,0 +1,29 @@
1
+ # <Spec title>
2
+
3
+ <!-- One file per spec this change touches: specs/<domain>.md inside the change.
4
+ Keep only the sections you need. A requirement's heading is its key. -->
5
+
6
+ ## Purpose
7
+
8
+ <!-- Only when this delta creates the spec, or changes what the spec is for.
9
+ Otherwise remove this section. -->
10
+
11
+ ## Added requirements
12
+
13
+ ### Requirement: <name>
14
+ <What the system SHALL do, in one statement.>
15
+
16
+ #### Scenario: <name>
17
+ - GIVEN <a starting state>
18
+ - WHEN <something happens>
19
+ - THEN <the outcome that can be checked>
20
+
21
+ ## Modified requirements
22
+
23
+ <!-- Write each requirement out in full, as it should read afterwards, under the
24
+ same heading it has in the spec. -->
25
+
26
+ ## Removed requirements
27
+
28
+ ### Requirement: <name>
29
+ Reason: <why it goes>
@@ -0,0 +1,20 @@
1
+ # <Change title>: design
2
+
3
+ ## Context
4
+
5
+ <!-- What the code looks like today where this change lands, and what limits it. -->
6
+
7
+ ## Approach
8
+
9
+ <!-- How the change will be built, in enough detail to split into task items. -->
10
+
11
+ ## Decisions
12
+
13
+ ### Decision: <name>
14
+ - Options: <the options considered>
15
+ - Choice: <the one taken>
16
+ - Why: <the reason>
17
+
18
+ ## Risks and trade-offs
19
+
20
+ <!-- What could go wrong, and what was given up. -->
@@ -0,0 +1,22 @@
1
+ # {{title}}
2
+
3
+ ## Context
4
+
5
+ <!-- What prompted this, and what is already known. -->
6
+
7
+ ## Questions
8
+
9
+ <!-- The open questions, one per line. -->
10
+
11
+ ## Approaches
12
+
13
+ <!-- The options considered, with what speaks for and against each. -->
14
+
15
+ ## Conclusion
16
+
17
+ <!-- Leave empty while open. Otherwise "Parked: <reason>", or a link to the change or
18
+ milestone this led to. -->
19
+
20
+ ## Related
21
+
22
+ <!-- Links to specs, changes and other explorations. -->
@@ -0,0 +1,13 @@
1
+ # {{title}}
2
+
3
+ ## Goal
4
+
5
+ <!-- What this milestone achieves. -->
6
+
7
+ ## Done when
8
+
9
+ <!-- How anyone can tell it has been reached. -->
10
+
11
+ ## Non-goals
12
+
13
+ <!-- What it leaves out. -->