devague 0.8.0__tar.gz → 0.9.0__tar.gz

{devague-0.8.0 → devague-0.9.0}/.claude/skills/spec-to-plan/SKILL.md

@@ -57,6 +57,7 @@ install hint. Every move except `status` is forwarded verbatim as `devague plan
 | `risk "<text>" --kind <kind>` | Record a first-class plan risk (`--task <tN>` to attach). |
 | `converge` | Evaluate the gate against the **live** source frame; list remaining gaps. |
 | `export` | Write the buildable plan to `docs/plans/` — only after `converge` passes. |
+| `waves` | Emit deterministic dependency waves (`{plan, waves}`) — scheduling metadata only, *not* orchestration. Read-only, works on an in-progress plan; refuses a cyclic/dangling graph. Devague describes the graph; an operator decides how to run it (#20). |
 | `show` / `list` | Render a plan / list plans (`--json` for raw state). |
 | `learn` / `explain <move>` | Teach the method / explain one move. |
 

{devague-0.8.0 → devague-0.9.0}/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh

@@ -66,6 +66,7 @@ Moves (forwarded to `devague plan`; run `devague plan learn` for the method):
   risk         record a first-class plan risk
   converge     check whether the plan can export
   export       write the buildable plan (only after converge passes)
+  waves        emit deterministic dependency waves (scheduling metadata, not orchestration)
   show / list  render a plan / list plans
   learn        teach the method   |   explain <move>  explain one move
 

{devague-0.8.0 → devague-0.9.0}/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-05-23
+
+### Added
+
+- **Plan dependency waves (#20).** New `devague plan waves [--json]` move emits the plan's task dependency graph as deterministic, machine-readable scheduling metadata (`{plan, waves}` — ordered batches of task ids where wave 0 has no unsatisfied dependency and each later wave depends only on earlier ones). Read-only and convergence-agnostic, so it works on an in-progress plan. Rejected tasks are excluded; a cycle or a dependency on a missing/rejected task is refused by reusing the plan-convergence dependency blockers (`dependency_blockers`). This is the small deterministic primitive behind #13: Devague *describes* the parallelizable graph; it does not spawn subagents, manage worktrees, mark tasks done, or pick a backend.
+- **Dated export filenames (#12).** `devague export` and `devague plan export` now prefix the written file with the frame/plan creation date — `docs/specs/<YYYY-MM-DD>-<slug>.md` and `docs/plans/<YYYY-MM-DD>-<slug>.md`. The date comes from the object's `created` timestamp (not today), so re-exporting an unchanged artifact overwrites the same file rather than spawning a dated duplicate. Existing exported docs were renamed to match.
+
 ## [0.8.0] - 2026-05-23
 
 ### Added

{devague-0.8.0 → devague-0.9.0}/CLAUDE.md

@@ -30,8 +30,8 @@ gate, renderer registry, and the flat moves `new` / `capture` / `interrogate` /
 structural peer:
 `devague/plan.py`, `plan_convergence.py`, `plan_store.py`, `render/plan_md.py`,
 and the nested group `devague plan <move>` (`new` / `task` / `accept` / `depend`
-/ `cover` / `confirm` / `reject` / `risk` / `converge` / `export` / `show` /
-`list` / `learn` / `explain`). The two operator skills are `/think` (idea→spec,
+/ `cover` / `confirm` / `reject` / `risk` / `converge` / `export` / `waves` /
+`show` / `list` / `learn` / `explain`). The two operator skills are `/think` (idea→spec,
 renamed from `/devague`) and `/spec-to-plan` (spec→plan). Coverage ≥ 95 %; all
 linters pass. Run `git ls-files` to see the real surface.
 
@@ -86,7 +86,18 @@ verbs). The workflow:
    covered by a confirmed task, every confirmed task has acceptance criteria, the
    dependency graph is acyclic, and no blocking risk remains.
 5. `devague plan export` — only after `converge` passes; writes a buildable
-   plan-md (topologically ordered) to `docs/plans/`.
+   plan-md (topologically ordered) to `docs/plans/<created-date>-<slug>.md`.
+6. `devague plan waves [--json]` — emit the plan's dependency graph as
+   deterministic **scheduling metadata** (`{plan, waves}`): ordered batches of
+   task ids that an external operator *could* fan out. Read-only,
+   convergence-agnostic (works on an in-progress plan), and explicitly **not
+   orchestration** — Devague describes the graph; it does not spawn subagents,
+   manage worktrees, mark tasks done, or pick a backend (#20). A cyclic or
+   dangling graph is refused via the plan-convergence dependency blockers.
+
+Both `devague export` and `devague plan export` prefix the written file with the
+frame/plan creation date (`<YYYY-MM-DD>-<slug>.md`, #12), so re-exporting an
+unchanged artifact overwrites the same file rather than spawning a duplicate.
 
 Full design: `docs/superpowers/specs/2026-05-23-devague-spec-to-plan-design.md`.
 

{devague-0.8.0 → devague-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devague
-Version: 0.8.0
+Version: 0.9.0
 Summary: devague — turns a vague feature idea into a buildable spec, then a buildable plan.
 Project-URL: Homepage, https://github.com/agentculture/devague
 Project-URL: Issues, https://github.com/agentculture/devague/issues

{devague-0.8.0 → devague-0.9.0}/devague/cli/_commands/export.py

@@ -9,6 +9,7 @@ from devague import render, store
 from devague.cli._errors import EXIT_USER_ERROR, DevagueError
 from devague.cli._frames import resolve
 from devague.cli._output import emit_result
+from devague.cli._paths import dated_name
 from devague.convergence import evaluate
 
 SPECS_DIR = Path("docs/specs")
@@ -25,7 +26,7 @@ def cmd_export(args: argparse.Namespace) -> int:
         )
     text = render.render(frame, args.format)
     SPECS_DIR.mkdir(parents=True, exist_ok=True)
-    out_path = SPECS_DIR / f"{frame.slug}.md"
+    out_path = SPECS_DIR / dated_name(frame.created, frame.slug)
     out_path.write_text(text, encoding="utf-8")
     frame.status = "exported"
     store.save(frame)

{devague-0.8.0 → devague-0.9.0}/devague/cli/_commands/plan.py

@@ -19,10 +19,12 @@ from devague import plan_store, store
 from devague.cli._errors import EXIT_USER_ERROR, DevagueError
 from devague.cli._frames import resolve as resolve_frame
 from devague.cli._output import emit_result
+from devague.cli._paths import dated_name
 from devague.cli._plans import resolve_plan
 from devague.convergence import evaluate as evaluate_frame
 from devague.frame import Frame
-from devague.plan import RISK_KINDS, Plan, targets_from_frame, to_dict
+from devague.plan import RISK_KINDS, Plan, dependency_waves, targets_from_frame, to_dict
+from devague.plan_convergence import dependency_blockers
 from devague.plan_convergence import evaluate as evaluate_plan
 from devague.render import plan_md
 
@@ -30,6 +32,7 @@ PLANS_OUT_DIR = Path("docs/plans")
 
 _JSON_HELP = "Emit structured JSON."
 _TASK_ID_HELP = "Task id."
+_RESOLVE_HINT = "resolve: "  # prefix for a "; "-joined blocker remediation hint
 
 PLAN_MOVES = {
     "new": "Start a plan from a converged frame (derives coverage targets).",
@@ -42,6 +45,7 @@ PLAN_MOVES = {
     "risk": "Record a first-class plan risk instead of papering over it.",
     "converge": "Check whether the plan can export, against the live frame.",
     "export": "Write the buildable plan — only once the plan converges.",
+    "waves": "Emit deterministic dependency waves (scheduling metadata, not orchestration).",
     "show": "Render the plan.",
     "list": "List plans.",
 }
@@ -102,7 +106,7 @@ def cmd_plan_new(args: argparse.Namespace) -> int:
         raise DevagueError(
             EXIT_USER_ERROR,
             f"frame '{frame.slug}' has not converged; cannot start a plan",
-            "resolve: " + "; ".join(result.blockers),
+            _RESOLVE_HINT + "; ".join(result.blockers),
         )
     if plan_store.path_for(frame.slug).exists():
         raise DevagueError(
@@ -267,12 +271,12 @@ def cmd_plan_export(args: argparse.Namespace) -> int:
         raise DevagueError(
             EXIT_USER_ERROR,
             "plan has not converged; cannot export",
-            "resolve: " + "; ".join(result.blockers),
+            _RESOLVE_HINT + "; ".join(result.blockers),
         )
     plan.status = "exported"
     text = plan_md.render_plan(plan, frame)
     PLANS_OUT_DIR.mkdir(parents=True, exist_ok=True)
-    out_path = PLANS_OUT_DIR / f"{plan.slug}.md"
+    out_path = PLANS_OUT_DIR / dated_name(plan.created, plan.slug)
     out_path.write_text(text, encoding="utf-8")
     plan_store.save(plan)
     if getattr(args, "json", False):
@@ -282,6 +286,34 @@ def cmd_plan_export(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_plan_waves(args: argparse.Namespace) -> int:
+    """Emit the plan's dependency waves — deterministic scheduling metadata only.
+
+    Read-only and convergence-agnostic: waves derive purely from the task dependency
+    graph, so they work on an in-progress plan. Devague describes the graph; an
+    external operator (Culture, codexd, …) decides how to execute it — see #20. A cycle
+    or a dep on a missing/rejected task is refused by reusing the plan-convergence
+    integrity blockers.
+    """
+    plan = resolve_plan(args.plan)
+    blockers = dependency_blockers(plan)
+    if blockers:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            "cannot derive waves: the dependency graph is not sound",
+            _RESOLVE_HINT + "; ".join(blockers),
+        )
+    waves = dependency_waves(plan.tasks)
+    if getattr(args, "json", False):
+        emit_result({"plan": plan.slug, "waves": waves}, json_mode=True)
+    elif not waves:
+        emit_result("no tasks to schedule", json_mode=False)
+    else:
+        lines = [f"wave {i}: {', '.join(w)}" for i, w in enumerate(waves)]
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
 def cmd_plan_show(args: argparse.Namespace) -> int:
     plan = resolve_plan(args.plan)
     if getattr(args, "json", False):
@@ -424,6 +456,10 @@ def register(sub: argparse._SubParsersAction) -> None:
     _plan_opt(pex)
     pex.set_defaults(func=cmd_plan_export)
 
+    pwv = psub.add_parser("waves", help="Emit deterministic dependency waves (metadata only).")
+    _plan_opt(pwv)
+    pwv.set_defaults(func=cmd_plan_waves)
+
     psh = psub.add_parser("show", help="Render the plan.")
     _plan_opt(psh)
     psh.set_defaults(func=cmd_plan_show)

devague-0.9.0/devague/cli/_paths.py

@@ -0,0 +1,39 @@
+"""Filesystem naming for exported artifacts (specs and plans)."""
+
+from __future__ import annotations
+
+import time
+
+# Stable, date-shaped sentinel used when ``created`` is absent or malformed. It must
+# not vary by run (e.g. today's date) or idempotence would break for that edge — see
+# the rationale in ``dated_name``.
+UNDATED_PREFIX = "0000-00-00"
+
+
+def dated_name(created: str, slug: str) -> str:
+    """Return ``<YYYY-MM-DD>-<slug>.md`` — the export filename with a date prefix (#12).
+
+    The date is taken from ``created`` (the object's persisted ISO timestamp,
+    ``2026-05-23T…``) rather than today, so re-exporting an unchanged object is
+    idempotent — it overwrites the same file instead of spawning a dated duplicate. An
+    object is always saved (creation stamped) before it can converge and export, so a
+    real date is the normal case.
+
+    If ``created`` is somehow absent or malformed (only reachable via a hand-corrupted
+    store file — ``store.save`` repopulates an *empty* stamp but not an *invalid* one),
+    we fall back to the constant :data:`UNDATED_PREFIX` rather than today's date: a
+    run-varying fallback would itself break the idempotence this prefix exists to
+    provide.
+    """
+    date = (created or "")[:10]
+    if not _is_iso_date(date):
+        date = UNDATED_PREFIX
+    return f"{date}-{slug}.md"
+
+
+def _is_iso_date(value: str) -> bool:
+    try:
+        time.strptime(value, "%Y-%m-%d")
+        return True
+    except ValueError:
+        return False

{devague-0.8.0 → devague-0.9.0}/devague/plan.py

@@ -169,6 +169,44 @@ def targets_from_frame(frame: Frame) -> list[CoverageTarget]:
     return targets
 
 
+def dependency_waves(tasks: list[Task]) -> list[list[str]]:
+    """Layer active (non-rejected) tasks into deterministic dependency waves.
+
+    Wave 0 is every active task with no unsatisfied dependency; each later wave is the
+    tasks whose deps are all satisfied by earlier waves — the parallel batches an
+    external operator *could* fan out (Devague describes the graph; it does not run it).
+    Within a wave ids keep stored order, so the layering is deterministic for a given
+    plan.
+
+    Rejected tasks are excluded entirely. A dependency on a task outside the active set
+    (unknown, or rejected) is treated as already satisfied here so the function stays
+    **total**: those dangling edges are integrity failures surfaced separately by the
+    plan-convergence gate (:func:`devague.plan_convergence.dependency_blockers`), not
+    scheduling facts. The graph is assumed acyclic; any tasks left unplaceable by a
+    cycle are appended as a final wave so this never loops forever.
+
+    This is the wave-grouped peer of ``render.plan_md._topo_order`` (which flattens a
+    *greedy* topological order for the exported plan); the two intentionally differ in
+    grouping, so they are kept as separate functions.
+    """
+    active = [t for t in tasks if t.status != "rejected"]
+    by_id = {t.id: t for t in active}
+    placed: set[str] = set()
+    remaining = list(active)
+    waves: list[list[str]] = []
+    progress = True
+    while remaining and progress:
+        ready = [t for t in remaining if all(d in placed or d not in by_id for d in t.deps)]
+        progress = bool(ready)
+        if ready:
+            waves.append([t.id for t in ready])
+            placed.update(t.id for t in ready)
+            remaining = [t for t in remaining if t.id not in placed]
+    if remaining:  # cycle leftover — the caller should have blocked this
+        waves.append([t.id for t in remaining])
+    return waves
+
+
 def to_dict(plan: Plan) -> dict:
     return dataclasses.asdict(plan)
 

{devague-0.8.0 → devague-0.9.0}/devague/plan_convergence.py

@@ -121,6 +121,17 @@ def _missing_dep_integrity(plan: Plan) -> list[str]:
     return missing
 
 
+def dependency_blockers(plan: Plan) -> list[str]:
+    """Public view of just the dependency-graph integrity blockers.
+
+    The dangling-dep / rejected-dep / cycle subset of the full gate — without the
+    coverage, acceptance, or resolution checks. ``devague plan waves`` uses this to
+    refuse an unsound graph (a cycle or a dep on a missing/rejected task) while still
+    emitting waves for an otherwise in-progress, not-yet-converged plan.
+    """
+    return _missing_dep_integrity(plan)
+
+
 def _missing_risks(plan: Plan) -> list[str]:
     return [f"blocking risk {r.id} unresolved" for r in plan.risks if r.kind == "unknown_blocking"]
 

{devague-0.8.0 → devague-0.9.0}/docs/spec-contract.md

@@ -184,6 +184,17 @@ plus `deps`, `covers`, `acceptance_criteria`), and PlanRisks. It reuses the same
 structured convergence result, serialized under `ready_for_plan`. See
 `docs/superpowers/specs/2026-05-23-devague-spec-to-plan-design.md`.
 
+`plan waves` emits the plan's dependency graph as deterministic, machine-readable
+scheduling metadata — `{plan, waves}`, where `waves` is an ordered list of task-id
+batches (wave 0 has no unsatisfied dependency; each later wave depends only on
+earlier ones). It is **read-only**, never mutates state, and is **not** gated on
+convergence, so it works on an in-progress plan. Rejected tasks are excluded; a
+cycle or a dependency on a missing/rejected task is refused by reusing the
+plan-convergence dependency blockers. The boundary is deliberate (issue #20):
+Devague *describes* the parallelizable graph; an external operator (Culture,
+codexd, …) decides how — or whether — to execute it. Devague does not spawn
+subagents, manage worktrees, mark tasks done, or choose a backend.
+
 Plans carry the same persistence contract as frames. Every plan has an integer
 `schema_version` (currently `1`, `PLAN_SCHEMA_VERSION`), written on save and
 checked on load: `plan_store.load` **fails closed** with a clean `DevagueError`

{devague-0.8.0 → devague-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devague"
-version = "0.8.0"
+version = "0.9.0"
 description = "devague — turns a vague feature idea into a buildable spec, then a buildable plan."
 readme = "README.md"
 license = "MIT"

{devague-0.8.0 → devague-0.9.0}/tests/test_cli_converge_export.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 
 import pytest
@@ -51,10 +52,13 @@ def test_export_writes_spec_when_converged(tmp_path, monkeypatch) -> None:
     _converged(monkeypatch, tmp_path)
     rc = main(["export"])
     assert rc == 0
-    out = Path("docs/specs") / f"{store.current_slug()}.md"
+    frame = store.load(store.current_slug())
+    # #12: exported docs carry a YYYY-MM-DD prefix from the frame's creation date.
+    out = Path("docs/specs") / f"{frame.created[:10]}-{frame.slug}.md"
     assert out.exists()
+    assert re.fullmatch(r"\d{4}-\d{2}-\d{2}-.+\.md", out.name)
     assert out.read_text(encoding="utf-8").startswith("# Specs in minutes")
-    assert store.load(store.current_slug()).status == "exported"
+    assert frame.status == "exported"
 
 
 def test_converge_demotes_converged_frame_when_gate_fails(tmp_path, monkeypatch, capsys) -> None:

devague-0.9.0/tests/test_cli_paths.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from devague.cli._paths import UNDATED_PREFIX, dated_name
+
+
+def test_dated_name_uses_created_date_prefix() -> None:
+    assert dated_name("2026-05-23T11:29:36Z", "my-slug") == "2026-05-23-my-slug.md"
+
+
+def test_dated_name_falls_back_to_stable_sentinel_when_created_missing() -> None:
+    # A run-varying fallback (e.g. today) would break idempotence; the sentinel is
+    # constant, so re-exporting always lands on the same file. (Qodo #27 review.)
+    assert dated_name("", "my-slug") == f"{UNDATED_PREFIX}-my-slug.md"
+
+
+def test_dated_name_falls_back_to_stable_sentinel_when_created_malformed() -> None:
+    assert dated_name("not-a-date", "my-slug") == f"{UNDATED_PREFIX}-my-slug.md"
+
+
+def test_dated_name_fallback_is_idempotent_across_calls() -> None:
+    assert dated_name("garbage", "my-slug") == dated_name("garbage", "my-slug")

{devague-0.8.0 → devague-0.9.0}/tests/test_cli_plan.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 
 import pytest
@@ -198,8 +199,11 @@ def test_export_writes_plan_md(tmp_path, monkeypatch, capsys) -> None:
     slug = _converged_plan(monkeypatch, tmp_path, capsys)
     rc = main(["plan", "export"])
     assert rc == 0
-    out = Path("docs/plans") / f"{slug}.md"
+    plan = plan_store.load(slug)
+    # #12: exported docs carry a YYYY-MM-DD prefix from the plan's creation date.
+    out = Path("docs/plans") / f"{plan.created[:10]}-{slug}.md"
     assert out.exists()
+    assert re.fullmatch(r"\d{4}-\d{2}-\d{2}-.+\.md", out.name)
     text = out.read_text(encoding="utf-8")
     assert text.startswith("# Build Plan — Ship the plan engine")
     assert "status: `exported`" in text
@@ -301,13 +305,93 @@ def test_resolve_plan_rejects_malformed_value(tmp_path, monkeypatch, capsys) ->
     assert "malformed" in capsys.readouterr().err
 
 
+# ── waves (#20) ───────────────────────────────────────────────────────────────
+def _plan_with_deps(monkeypatch, tmp_path, capsys, deps: list[list[str]]) -> str:
+    """Seed an in-progress plan whose task i depends on the ids in ``deps[i-1]``."""
+    slug = _converged_frame(monkeypatch, tmp_path)
+    main(["plan", "new", "--frame", slug])
+    for i, d in enumerate(deps, start=1):
+        argv = ["plan", "task", f"task {i}"]
+        for dep in d:
+            argv += ["--dep", dep]
+        main(argv)
+    capsys.readouterr()
+    return slug
+
+
+def test_waves_json_linear(tmp_path, monkeypatch, capsys) -> None:
+    slug = _plan_with_deps(monkeypatch, tmp_path, capsys, [[], ["t1"], ["t2"]])
+    assert main(["plan", "waves", "--json"]) == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["plan"] == slug
+    assert payload["waves"] == [["t1"], ["t2"], ["t3"]]
+
+
+def test_waves_text_mode_lists_each_wave(tmp_path, monkeypatch, capsys) -> None:
+    _plan_with_deps(monkeypatch, tmp_path, capsys, [[], ["t1"]])
+    assert main(["plan", "waves"]) == 0
+    out = capsys.readouterr().out
+    assert "t1" in out and "t2" in out
+
+
+def test_waves_emit_on_unconverged_plan(tmp_path, monkeypatch, capsys) -> None:
+    # No coverage / acceptance => the plan has not converged, but waves still emit:
+    # waves are scheduling metadata derived from the graph, not gated on convergence.
+    _plan_with_deps(monkeypatch, tmp_path, capsys, [[], ["t1"]])
+    assert main(["plan", "converge", "--json"]) == 0
+    assert json.loads(capsys.readouterr().out)["ready_for_plan"] is False
+    assert main(["plan", "waves", "--json"]) == 0
+    assert json.loads(capsys.readouterr().out)["waves"] == [["t1"], ["t2"]]
+
+
+def test_waves_excludes_rejected_tasks(tmp_path, monkeypatch, capsys) -> None:
+    _plan_with_deps(monkeypatch, tmp_path, capsys, [[], [], ["t1"]])
+    main(["plan", "reject", "t2"])
+    capsys.readouterr()
+    assert main(["plan", "waves", "--json"]) == 0
+    flat = [tid for w in json.loads(capsys.readouterr().out)["waves"] for tid in w]
+    assert "t2" not in flat and {"t1", "t3"} <= set(flat)
+
+
+def test_waves_does_not_mutate_plan_state(tmp_path, monkeypatch, capsys) -> None:
+    slug = _plan_with_deps(monkeypatch, tmp_path, capsys, [[], ["t1"]])
+    before = plan_store.path_for(slug).read_text(encoding="utf-8")
+    assert main(["plan", "waves", "--json"]) == 0
+    assert plan_store.path_for(slug).read_text(encoding="utf-8") == before
+
+
+def test_waves_dangling_dep_errors(tmp_path, monkeypatch, capsys) -> None:
+    _plan_with_deps(monkeypatch, tmp_path, capsys, [["t99"]])
+    assert main(["plan", "waves", "--json"]) == 1
+    assert "unknown task" in capsys.readouterr().err
+
+
+def test_waves_cycle_errors(tmp_path, monkeypatch, capsys) -> None:
+    _plan_with_deps(monkeypatch, tmp_path, capsys, [[], ["t1"]])
+    main(["plan", "depend", "t1", "--on", "t2"])  # t1 -> t2 -> t1
+    capsys.readouterr()
+    assert main(["plan", "waves"]) == 1
+    assert "cycle" in capsys.readouterr().err
+
+
+def test_waves_dep_on_rejected_errors(tmp_path, monkeypatch, capsys) -> None:
+    _plan_with_deps(monkeypatch, tmp_path, capsys, [[], ["t1"]])
+    main(["plan", "reject", "t1"])  # t2 still depends on the now-rejected t1
+    capsys.readouterr()
+    assert main(["plan", "waves"]) == 1
+    assert "rejected task" in capsys.readouterr().err
+
+
 # ── learn / explain ───────────────────────────────────────────────────────────
 def test_learn_and_explain(tmp_path, monkeypatch, capsys) -> None:
     monkeypatch.chdir(tmp_path)
     assert main(["plan", "learn"]) == 0
     assert "spec into a buildable plan" in capsys.readouterr().out
     assert main(["plan", "learn", "--json"]) == 0
-    assert "converge" in json.loads(capsys.readouterr().out)["moves"]
+    moves = json.loads(capsys.readouterr().out)["moves"]
+    assert "converge" in moves and "waves" in moves
+    assert main(["plan", "explain", "waves", "--json"]) == 0
+    assert json.loads(capsys.readouterr().out)["move"] == "waves"
     assert main(["plan", "explain", "task", "--json"]) == 0
     assert json.loads(capsys.readouterr().out)["move"] == "task"
     assert main(["plan", "explain", "bogus"]) == 1

{devague-0.8.0 → devague-0.9.0}/tests/test_plan.py

@@ -8,6 +8,7 @@ from devague.plan import (
     Plan,
     PlanRisk,
     Task,
+    dependency_waves,
     from_dict,
     targets_from_frame,
     to_dict,
@@ -150,3 +151,78 @@ def test_targets_from_frame_includes_only_confirmed_spec_elements() -> None:
     assert "c3" not in by_id
     assert "c4" not in by_id
     assert "h2" not in by_id
+
+
+# ── dependency waves (#20) ────────────────────────────────────────────────────
+def _waves_plan(specs: list[tuple[str, list[str], str]]) -> Plan:
+    """Build a plan from ``(summary, deps, status)`` rows; ids are t1.. in order."""
+    p = Plan(slug="w", title="W", frame_slug="w")
+    for summary, deps, status in specs:
+        t = p.add_task(summary)
+        t.deps = list(deps)
+        t.status = status
+    return p
+
+
+def test_waves_linear_chain() -> None:
+    p = _waves_plan(
+        [("a", [], "confirmed"), ("b", ["t1"], "confirmed"), ("c", ["t2"], "confirmed")]
+    )
+    assert dependency_waves(p.tasks) == [["t1"], ["t2"], ["t3"]]
+
+
+def test_waves_parallel_fan_out() -> None:
+    p = _waves_plan(
+        [
+            ("root", [], "confirmed"),
+            ("a", ["t1"], "confirmed"),
+            ("b", ["t1"], "confirmed"),
+            ("c", ["t1"], "confirmed"),
+        ]
+    )
+    assert dependency_waves(p.tasks) == [["t1"], ["t2", "t3", "t4"]]
+
+
+def test_waves_join() -> None:
+    p = _waves_plan(
+        [("a", [], "confirmed"), ("b", [], "confirmed"), ("join", ["t1", "t2"], "confirmed")]
+    )
+    assert dependency_waves(p.tasks) == [["t1", "t2"], ["t3"]]
+
+
+def test_waves_independent_tasks_share_one_wave_in_stored_order() -> None:
+    p = _waves_plan([("a", [], "confirmed"), ("b", [], "confirmed"), ("c", [], "confirmed")])
+    assert dependency_waves(p.tasks) == [["t1", "t2", "t3"]]
+
+
+def test_waves_exclude_rejected_tasks() -> None:
+    p = _waves_plan([("a", [], "confirmed"), ("dead", [], "rejected"), ("b", ["t1"], "confirmed")])
+    waves = dependency_waves(p.tasks)
+    assert waves == [["t1"], ["t3"]]
+    assert "t2" not in [tid for w in waves for tid in w]
+
+
+def test_waves_deterministic_across_calls() -> None:
+    p = _waves_plan(
+        [("root", [], "confirmed"), ("a", ["t1"], "confirmed"), ("b", ["t1"], "confirmed")]
+    )
+    assert dependency_waves(p.tasks) == dependency_waves(p.tasks)
+
+
+def test_waves_empty_plan_is_empty() -> None:
+    assert dependency_waves(Plan(slug="w", title="W", frame_slug="w").tasks) == []
+
+
+def test_waves_dep_on_rejected_is_ignored_by_pure_layering() -> None:
+    # The pure function treats a dep outside the active set as satisfied (it is total);
+    # the *integrity error* for that dangling edge is the CLI/gate's job, not here.
+    p = _waves_plan([("dead", [], "rejected"), ("b", ["t1"], "confirmed")])
+    assert dependency_waves(p.tasks) == [["t2"]]
+
+
+def test_waves_cycle_leftover_appended_without_hanging() -> None:
+    # Callers gate cycles via convergence blockers; the pure fn must stay total and
+    # surface the unplaceable tasks as a trailing wave rather than loop forever.
+    p = _waves_plan([("a", ["t2"], "confirmed"), ("b", ["t1"], "confirmed")])
+    waves = dependency_waves(p.tasks)
+    assert [tid for w in waves for tid in w] == ["t1", "t2"]

{devague-0.8.0 → devague-0.9.0}/uv.lock

@@ -183,7 +183,7 @@ wheels = [
 
 [[package]]
 name = "devague"
-version = "0.8.0"
+version = "0.9.0"
 source = { editable = "." }
 
 [package.dev-dependencies]