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.
- waymark/__init__.py +3 -0
- waymark/__main__.py +8 -0
- waymark/adapters/__init__.py +102 -0
- waymark/adapters/claude_code.py +238 -0
- waymark/assets/__init__.py +43 -0
- waymark/assets/agents/wm-implementer.md +45 -0
- waymark/assets/agents/wm-reviewer.md +43 -0
- waymark/assets/skills/wm-apply/SKILL.md +58 -0
- waymark/assets/skills/wm-archive/SKILL.md +32 -0
- waymark/assets/skills/wm-explore/SKILL.md +34 -0
- waymark/assets/skills/wm-kickoff/SKILL.md +34 -0
- waymark/assets/skills/wm-onboard/SKILL.md +27 -0
- waymark/assets/skills/wm-pr/SKILL.md +24 -0
- waymark/assets/skills/wm-propose/SKILL.md +32 -0
- waymark/assets/skills/wm-update/SKILL.md +31 -0
- waymark/cli.py +537 -0
- waymark/hooks/__init__.py +6 -0
- waymark/hooks/commands.py +190 -0
- waymark/hooks/decide.py +314 -0
- waymark/hooks/events.py +79 -0
- waymark/py.typed +0 -0
- waymark/record/__init__.py +5 -0
- waymark/record/atlas.py +156 -0
- waymark/record/changes.py +202 -0
- waymark/record/charter.py +75 -0
- waymark/record/commits.py +78 -0
- waymark/record/config.py +215 -0
- waymark/record/deltas.py +318 -0
- waymark/record/design.py +80 -0
- waymark/record/edits.py +95 -0
- waymark/record/evidence.py +58 -0
- waymark/record/explorations.py +66 -0
- waymark/record/files.py +75 -0
- waymark/record/fingerprint.py +73 -0
- waymark/record/git.py +167 -0
- waymark/record/githooks.py +106 -0
- waymark/record/links.py +104 -0
- waymark/record/milestones.py +84 -0
- waymark/record/moves.py +60 -0
- waymark/record/names.py +39 -0
- waymark/record/outline.py +144 -0
- waymark/record/pointer.py +56 -0
- waymark/record/problems.py +20 -0
- waymark/record/project.py +118 -0
- waymark/record/proposal.py +171 -0
- waymark/record/record.py +340 -0
- waymark/record/registry.py +158 -0
- waymark/record/specs.py +227 -0
- waymark/record/state.py +472 -0
- waymark/record/store.py +88 -0
- waymark/record/tasks.py +415 -0
- waymark/record/templates/charter.md +45 -0
- waymark/record/templates/ci-workflow.yml +29 -0
- waymark/record/templates/config-atlas.toml +8 -0
- waymark/record/templates/config.toml +19 -0
- waymark/record/templates/delta.md +29 -0
- waymark/record/templates/design.md +20 -0
- waymark/record/templates/exploration.md +22 -0
- waymark/record/templates/goal.md +13 -0
- waymark/record/templates/hook-commit-msg +8 -0
- waymark/record/templates/hook-pre-commit +8 -0
- waymark/record/templates/proposal.md +18 -0
- waymark/record/templates/roadmap.md +4 -0
- waymark/record/templates/tasks.md +10 -0
- waymark/record/templates.py +30 -0
- waymark/record/terms.py +51 -0
- waymark/record/text.py +197 -0
- waymark/services/__init__.py +1 -0
- waymark/services/atlas.py +162 -0
- waymark/services/check.py +129 -0
- waymark/services/ci.py +44 -0
- waymark/services/common.py +154 -0
- waymark/services/context.py +296 -0
- waymark/services/doctor.py +367 -0
- waymark/services/githooks.py +132 -0
- waymark/services/instructions.py +304 -0
- waymark/services/integration.py +170 -0
- waymark/services/lifecycle.py +454 -0
- waymark/services/migrations.py +90 -0
- waymark/services/pr.py +177 -0
- waymark/services/references.py +27 -0
- waymark/services/setup.py +127 -0
- waymark/views/__init__.py +5 -0
- waymark/views/payloads.py +568 -0
- waymark/views/render.py +506 -0
- waymark/views/schemas.py +413 -0
- waymark/views/style.py +102 -0
- waymark_cli-0.1.0.dist-info/METADATA +313 -0
- waymark_cli-0.1.0.dist-info/RECORD +92 -0
- waymark_cli-0.1.0.dist-info/WHEEL +4 -0
- waymark_cli-0.1.0.dist-info/entry_points.txt +2 -0
- waymark_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
waymark/record/store.py
ADDED
|
@@ -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
|
waymark/record/tasks.py
ADDED
|
@@ -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,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. -->
|