Repository navigation
wavecoord 0.2.0
The spec tree: requirements and plans as typed Markdown records in your repo, merge-friendly, checked by scripts, planned in waves, with live status in git (docs/specs.md, docs/design/spec-layer.md). Phases S0 to S5.
Added
- Spec tree, phase S1 (
docs/design/spec-layer.md,docs/specs.md): typed Markdown records for capabilities, features, requirements, tasks and decisions underspecs/(spec.dir).wavecoord spec tree|show|query|check|lint|fmt|fp: read the tree from the working tree or a git ref (--ref, two git processes for any number of files), query it (kind=task status=planned outputs~src/*), check each record (layout, frame, schema, sections, artifacts, EARS, canonical form), format it canonically, and print a requirement's fingerprint.schemas/spec-record.schema.json, and thespec.dirconfig key.
- Spec tree, phase S2: the rules across records and the writes.
checknow also proves references (with aliases), blockers (needson any node expands to its subtree and is inherited; no cycles; no needs on an ancestor or descendant), alignment rules A1-A7 between inputs, outputs andneeds, and predicate P (two tasks that may run at the same time do not write the same paths); suspect tasks are warnings.- New reads:
waves(what can run together, the critical path, the width),ready,trace,artifacts,suspect. - Writes through one op API (
schemas/spec-ops.schema.json):new,set,status,section,add,rm,artifact,artifact-rm,scenario,mv(rewrites references, keeps the old id as an alias),rebase-basis,supersede,delete, andapplyfor a JSON list of ops. A change that would add an error writes nothing;--dry-runprints the diff. migrate-planmovesplan/tasksinto the tree.- Tests: real
git mergeof random edits on two branches (no conflict, the result checks clean), sorted inserts, genuine conflicts, status against other keys, races; parallel safety of the computed waves; injected misalignments; seeded defects S01-S06 and S09-S11.
- Spec tree, phase S3: the tree in the lead.
- The spec tree is the plan store when the config has no
plankey andspec.dirhas records on the default branch, or with"plan": {"adapter": "specs"}:plan_ready,plan_get,dispatch,dispatch_waveand the dispatcher loop read tasks from it. A task's coordinator id is its path with.for/. The coordinator's states (live attempts, parked leases, merges) count over the status in the files. - The worker's prompt gets the requirement (statement, scenarios), the task's inputs and outputs with their contracts, and the requirement's Verify commands.
- MCP tools
spec_tree,spec_get,spec_query,spec_waves,spec_trace,spec_checkandspec_edit(ops on aplan/<n>branch, moves asgit mv, one PR; several calls with one branch build one PR), and the REST routes under/api/spec/. plan/edit.pysplit intoplan_branch,commit_filesandread_at, shared byplan_editandspec_edit.
- The spec tree is the plan store when the config has no
- Spec tree, phase S4: status commits, the merge rule, verify at merge.
- The coordinator writes task status into the spec tree:
in_progress,in_review,done, and back toplanned, by reconciling the files with its state and committing only thestatus:lines that differ (wavecoord: status (<n> tasks),Wavecoord-Status:lines), everyspec.status_flush_sand at once after a merge. When the default branch refuses the push, the commit goes through awavecoord/statusPR merged withmerge_cmd. Eventsspec.statusandspec.status_blocked;wavecoord spec status-syncand thespec_status_synctool. - A task PR may not change the spec tree: gate-check reports
spec_change, the refinery blocks (edit-fence.md section 8.1, predicate S, seeded defect D25).specandplanjoined the config keys that a task PR may not change. spec.verify_at_merge(on by default): the refinery runs the task's Acceptance and its requirement's Verify, from the default branch, aftercheck_cmd; a failure blocks withverify_failed;refinery.mergerecords the requirement and its fingerprint.- The PR body of a tree task ends with the trailers
Spec-Task:andSpec-Basis:. - Config keys
spec.require_approved,suspect,verify_at_merge,status_commits,status_flush_s,status_author. - Seeded defects S07 and S08.
- The coordinator writes task status into the spec tree:
- Spec tree, phase S5: the workflow.
/wavecoord:specbuilds and revises the tree with the user (referencesears.md,spec-templates.md) and opens one plan PR withspec_edit.wave-planplans tasks under requirements (outputs cover the requirement's promises, inputs from needs, Acceptance includes Verify,spec_wavesin the PR body);revisehandles suspect tasks and the proposal kindsrequirement_gapandspec_change;wave-runusesspec_waves;triagehandlesverify_failed,spec_changeandspec.status_blocked;coord-statusshows the tree's progress.- The planner and reviewer subagents read the tree (
spec_get,spec_query,spec_trace,spec_check); the reviewer has a spec mode. - Report proposals
requirement_gapandspec_change. scripts/smoke-live.py --checks spec: a two-task requirement through the coordinator with a realclaude.
- Block lists in the YAML subset:
key:followed by- itemlines, in task specs too, and block lists of flat maps for the spec tree's inputs and outputs. Every file that parsed before parses to the same value.
Fixed
- A too-large request could reset the connection instead of answering 413. The server refused a body over
REQ_MAX_BYTESbefore reading it, so a client still writing it gotConnection reset by peer(seen in CI on macOS with Python 3.12). It now reads and drops up to 1 MiB of the body first, then answers 413 and closes the connection. - A launched worker's
SessionEndhook released its own lease before the launcher pushed. Real Claude Code runsSessionEndwhen a worker ends; the hook sentfinishwithpushed: false, so the server released the lease, the attempt went to the refinery with no parked lease (blocked asstale_lease), and a task never showed as in review. The fake claude runs noSessionEndhook, so only the live smoke test found it. The hook now leaves the finish to the launcher whenWAVECOORD_ATTEMPT_DIRis set. - Verify at merge on a requirement with several tasks. The requirement's Verify describes the finished requirement, so it now runs with the merge of the last open task under it; earlier merges run the task's Acceptance and record the tasks still pending (
requirement_pending).