Skip to content

wavecoord 0.2.0

Choose a tag to compare

@jellologic jellologic released this 19 Oct 03:02
61955b0

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 under specs/ (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 the spec.dir config key.
  • Spec tree, phase S2: the rules across records and the writes.
    • check now also proves references (with aliases), blockers (needs on 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 and needs, 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, and apply for a JSON list of ops. A change that would add an error writes nothing; --dry-run prints the diff.
    • migrate-plan moves plan/tasks into the tree.
    • Tests: real git merge of 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 plan key and spec.dir has records on the default branch, or with "plan": {"adapter": "specs"}: plan_ready, plan_get, dispatch, dispatch_wave and 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_check and spec_edit (ops on a plan/<n> branch, moves as git mv, one PR; several calls with one branch build one PR), and the REST routes under /api/spec/.
    • plan/edit.py split into plan_branch, commit_files and read_at, shared by plan_edit and spec_edit.
  • 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 to planned, by reconciling the files with its state and committing only the status: lines that differ (wavecoord: status (<n> tasks), Wavecoord-Status: lines), every spec.status_flush_s and at once after a merge. When the default branch refuses the push, the commit goes through a wavecoord/status PR merged with merge_cmd. Events spec.status and spec.status_blocked; wavecoord spec status-sync and the spec_status_sync tool.
    • 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). spec and plan joined 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, after check_cmd; a failure blocks with verify_failed; refinery.merge records the requirement and its fingerprint.
    • The PR body of a tree task ends with the trailers Spec-Task: and Spec-Basis:.
    • Config keys spec.require_approved, suspect, verify_at_merge, status_commits, status_flush_s, status_author.
    • Seeded defects S07 and S08.
  • Spec tree, phase S5: the workflow.
    • /wavecoord:spec builds and revises the tree with the user (references ears.md, spec-templates.md) and opens one plan PR with spec_edit.
    • wave-plan plans tasks under requirements (outputs cover the requirement's promises, inputs from needs, Acceptance includes Verify, spec_waves in the PR body); revise handles suspect tasks and the proposal kinds requirement_gap and spec_change; wave-run uses spec_waves; triage handles verify_failed, spec_change and spec.status_blocked; coord-status shows 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_gap and spec_change.
    • scripts/smoke-live.py --checks spec: a two-task requirement through the coordinator with a real claude.
  • Block lists in the YAML subset: key: followed by - item lines, 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_BYTES before reading it, so a client still writing it got Connection 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 SessionEnd hook released its own lease before the launcher pushed. Real Claude Code runs SessionEnd when a worker ends; the hook sent finish with pushed: false, so the server released the lease, the attempt went to the refinery with no parked lease (blocked as stale_lease), and a task never showed as in review. The fake claude runs no SessionEnd hook, so only the live smoke test found it. The hook now leaves the finish to the launcher when WAVECOORD_ATTEMPT_DIR is 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).