devague 0.7.0__tar.gz → 0.9.0__tar.gz

{devague-0.7.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.7.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.7.0 → devague-0.9.0}/CHANGELOG.md

@@ -5,6 +5,20 @@ 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
+
+- **Portable LLM guidance contract (#19).** New `docs/llm-guidance.md` — a runtime-agnostic operating contract for any assisting model driving Devague (not just Claude Code): the move-driven mental model, the (state × origin) vocabulary, the anti-fabrication hard rules, adaptive-not-scripted ordering, good/bad operator examples, and the forward (plan) leg. Distilled from the `/think` and `/spec-to-plan` skill contracts; it complements, and does not replace, an agent runtime's own main instruction file (`AGENTS.md`, `CLAUDE.md`, a system prompt).
+- `devague learn` (text and `--json`) now always surfaces the operating rules: a `devague is NOT` framing (not a wizard / questionnaire / PRD generator), the anti-fabrication rules, and a pointer to `docs/llm-guidance.md`. JSON gains `not_a`, `operating_rules`, `guidance_doc` (a portable canonical URL — `docs/` is not shipped in the wheel), and `guidance_doc_repo_path` keys.
+
 ## [0.7.0] - 2026-05-23
 
 ### Added

{devague-0.7.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.
 
@@ -50,7 +50,9 @@ itself. The workflow:
    shipped successfully — what would you announce to users, teammates, or
    yourself?"). Creates a Frame seeded with the announcement claim
    (auto-confirmed, since it comes from the user). `devague learn` documents the
-   full ten-stage guided sequence.
+   full ten-stage guided sequence plus the always-on **operating rules** (the
+   anti-fabrication contract); the portable, agent-agnostic version of that
+   contract lives in `docs/llm-guidance.md` (#19).
 2. `devague capture --kind <kind> "<text>"` — add claims; LLM-proposed ones
    (`--origin llm`) land as `proposed` and require explicit user `confirm`.
 3. `devague interrogate <claim-id>` — attach honesty conditions and hard
@@ -84,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.7.0 → devague-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devague
-Version: 0.7.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.7.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.7.0 → devague-0.9.0}/devague/cli/_commands/learn.py

@@ -26,6 +26,40 @@ SUPPORTING_PROMPT = (
     "teammates, or yourself?"
 )
 
+# The portable, runtime-agnostic operating contract for any assisting model
+# (devague#19). The full version lives in the guidance doc; this is the core
+# surfaced in every `learn`. These rules are what make convergence mean something.
+#
+# `docs/` is not shipped in the wheel (only the `devague` package is), and an
+# installed devague is operated from an arbitrary repo — so a bare relative path
+# wouldn't resolve for most consumers. The portable, always-resolvable reference
+# is the canonical URL; the in-repo path is kept for contributors.
+GUIDANCE_DOC_URL = "https://github.com/agentculture/devague/blob/main/docs/llm-guidance.md"
+GUIDANCE_DOC_REPO_PATH = "docs/llm-guidance.md"
+
+# What devague is NOT — the framing that keeps it from degrading into a form.
+NOT_A = (
+    "a wizard (no fixed prompt sequence)",
+    "a scripted questionnaire (you don't read questions off a form)",
+    "a PRD generator (it never invents content to fill a template)",
+)
+
+# The anti-fabrication rules. Agent-agnostic: repo-specific agreements live in
+# your agent's main instruction file (AGENTS.md, CLAUDE.md, a system prompt, …),
+# not here.
+OPERATING_RULES = (
+    "LLM proposals stay proposed — capture your own ideas with --origin llm; "
+    "never confirm your own proposal. Confirmation is a user-only decision.",
+    "Honesty conditions route through the user — propose freely with "
+    "'interrogate --honesty'; the user owns whether each one holds.",
+    "Park real unknowns instead of papering over them — 'park' a genuine "
+    "unknown rather than writing confident prose that hides the gap.",
+    "Converge, don't vibe — 'export' is gated on 'converge'; resolve every "
+    "listed gap instead of declaring readiness on a hunch.",
+    "Order is adaptive — the ten stages are an artifact shape, not a mandatory "
+    "conversation order; capture what the user gives you and circle back.",
+)
+
 # The canonical guided sequence (devague#4). The engine is move-driven, not a
 # rigid wizard — this is the recommended arc, with the move that advances each.
 STAGES = [
@@ -57,6 +91,15 @@ _TEXT = (
     )
     + "\n\nMoves:\n"
     + "\n".join(f"  {name:<11} {desc}" for name, desc in MOVES.items())
+    + "\n\ndevague is NOT:\n"
+    + "\n".join(f"  - {n}" for n in NOT_A)
+    + "\n\nOperating rules (the anti-fabrication contract — do not violate):\n"
+    + "\n".join(f"  - {r}" for r in OPERATING_RULES)
+    + "\n\nFull portable guidance for any assisting model:\n"
+    f"  {GUIDANCE_DOC_URL}\n"
+    f"  (in the devague repo: {GUIDANCE_DOC_REPO_PATH})\n"
+    "Agent-agnostic; your repo-specific agreements live in your agent's main\n"
+    "instruction file — AGENTS.md, CLAUDE.md, a system prompt — not there."
 )
 
 
@@ -73,6 +116,10 @@ def cmd_learn(args: argparse.Namespace) -> int:
                     for i, (name, prompt, move) in enumerate(STAGES, 1)
                 ],
                 "moves": list(MOVES),
+                "not_a": list(NOT_A),
+                "operating_rules": list(OPERATING_RULES),
+                "guidance_doc": GUIDANCE_DOC_URL,
+                "guidance_doc_repo_path": GUIDANCE_DOC_REPO_PATH,
                 "summary": _TEXT,
             },
             json_mode=True,

{devague-0.7.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.7.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.7.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.9.0/docs/llm-guidance.md

@@ -0,0 +1,130 @@
+# Operating Devague — portable guidance for assisting models
+
+This is the **portable, runtime-agnostic contract** for any LLM or agent that
+operates Devague. It does not assume a particular agent runtime (Claude Code,
+a Codex/`AGENTS.md` agent, Copilot, an ACP host, a bare system prompt, …). It
+complements — it does **not** replace — your agent's own main instruction file
+(`AGENTS.md`, `CLAUDE.md`, a system prompt, or equivalent), which carries the
+repo-specific working agreements. Where the two overlap, this document is the
+authority on *how Devague itself must be driven*.
+
+The authoritative entity model and the per-move input/output/transition
+contract live in [`spec-contract.md`](spec-contract.md). For the live shape of
+any move, run it with `--json`, or run `devague learn` / `devague explain
+<move>`.
+
+## 1. What Devague is — and is not
+
+Devague is a **deterministic, move-driven state machine** over claims, honesty
+conditions, open vagueness, and a convergence gate. There are **no LLM calls
+inside the CLI** — it only records moves and reports what is still missing. The
+intelligence is *you*, the operating model.
+
+It is **not**:
+
+- **not a wizard** — there is no fixed sequence of prompts to march through;
+- **not a scripted questionnaire** — you do not read questions off a form;
+- **not a PRD generator** — it will not invent content to fill a template.
+
+You choose each move from the live state; the CLI tracks state and tells you
+what remains before a spec (or plan) can be exported.
+
+## 2. The state you operate on
+
+Two legs share one chassis:
+
+- **Frame (idea → spec).** Claims (each with a *kind* — `announcement`,
+  `audience`, `after_state`, `before_state`, `why_it_matters`, `boundary`,
+  `success_signal`, `open_question`, `non_goal`, `requirement`, `assumption`,
+  `decision`); honesty conditions and hard questions attached to claims; and
+  **open vagueness** (parked unknowns, kinds `unknown_nonblocking` /
+  `unknown_blocking` / `out_of_scope` / `follow_up`).
+- **Plan (spec → plan).** Coverage targets (derived from a converged frame),
+  tasks (with acceptance criteria, dependencies, and the targets they cover),
+  and first-class plan risks.
+
+Every element carries two orthogonal axes:
+
+- **origin** — `user` or `llm` (who proposed it);
+- **status** — `proposed`, `confirmed`, or `rejected`.
+
+`origin` and `status` are independent. An `llm`-proposed claim is *proposed*
+until a human acts on it; a `user`-provided claim is *confirmed* on arrival.
+Keeping these distinct is the whole point of the tool — see §4.
+
+## 3. You choose the move; order is adaptive
+
+The moves are `new`, `capture`, `interrogate`, `confirm`, `reject`, `review`,
+`question`, `park`, `converge`, `export`, `show`, `list` (plus the `plan …`
+moves for the forward leg). Pick the move that fits the live state — not a
+predetermined script.
+
+When unsure what to do next, ask the gate, don't guess: run `converge --json`
+(it returns `{ready_for_spec, blockers, warnings, parked_items,
+required_next_moves}`; plans return `ready_for_plan`) and act on the first
+blocker.
+
+The canonical **ten-stage arc** (announcement → audience → after → matter →
+before → honest → FAQ → boundaries → success → spec) that `devague learn`
+prints is an **artifact shape and a recommended arc — not a mandatory
+conversation order**. If the user hands you the audience and the success signal
+before the announcement is crisp, capture those now and circle back. Drive
+toward the shape; do not impose a sequence on the user.
+
+## 4. Hard rules — the anti-fabrication contract
+
+These are not style preferences. Convergence is only meaningful if these hold.
+
+- **LLM proposals stay proposed.** Capture your own ideas freely with `--origin
+  llm` (claims) or by attaching honesty conditions; they land as `proposed`.
+  **Never `confirm` your own proposal.** Confirmation is a **user-only**
+  decision. Surface the proposal and let the user confirm or reject it — proposed
+  content must never silently become an authoritative requirement.
+- **Honesty conditions route through the user.** Propose them generously with
+  `interrogate --honesty`; the user owns whether each one actually holds.
+- **Park real unknowns; do not paper over them.** If something is genuinely
+  unknown, `park` it (blocking or non-blocking) instead of writing confident
+  prose that hides the gap. Blocking vagueness holds back convergence by design.
+- **Converge, don't vibe.** `export` is gated on `converge` passing. Never
+  declare a frame or plan "ready" on a hunch — run `converge` and resolve every
+  listed gap first.
+
+## 5. Good vs. bad operator behavior
+
+| Situation | ❌ Bad (fabricating) | ✅ Good (honest) |
+|-----------|---------------------|------------------|
+| You have a strong guess at the audience | `capture --kind audience … --origin user` (passing your guess off as the user's) | `capture --kind audience … --origin llm`, then ask the user to `confirm` |
+| You proposed an honesty condition | `confirm h3` yourself so the gate passes | leave `h3` proposed; surface it for the user to confirm |
+| A key detail is genuinely unknown | invent a plausible answer to keep momentum | `park "<the unknown>" --kind unknown_blocking` |
+| User asks "is this ready?" | "Yes, looks solid." | run `converge`; report the actual blockers/warnings |
+| The user skipped a stage | march through the stages in order anyway | capture what they gave you; let the arc fill in adaptively |
+| Plan: a task has no clear acceptance test | mark it confirmed and move on | leave it without criteria (the gate blocks it) or `park` the risk |
+
+## 6. The forward leg (spec → plan), in brief
+
+The plan engine is the structural peer of the frame engine and obeys the same
+spirit:
+
+- **Seed from a converged spec only** — `plan new` refuses an unconverged frame.
+- **LLM-proposed tasks stay proposed**; the user confirms them.
+- **Cover every target, criteria on every task** — the gate requires it.
+- **Keep the dependency graph honest** — real task ids, acyclic.
+- **Park genuine unknowns as risks** (`unknown_blocking` holds convergence back).
+- **Converge against the live frame** — `converge`/`export` re-load the source
+  frame; if it regressed below convergence, re-converge the spec first.
+
+## 7. Output contract
+
+Results go to **stdout**; diagnostics and errors go to **stderr** — a strict
+split you can parse. Pass `--json` to any move for a structured payload on the
+same stream. Exit code is `0` on success, non-zero on user error (with a
+`hint:` line and no Python traceback). Frames and plans persist under
+`.devague/` in the current directory.
+
+## 8. Where authority lives
+
+- **Entity model + per-move contract:** [`spec-contract.md`](spec-contract.md).
+- **Live shape of any move:** run it with `--json`, or `devague learn` /
+  `devague explain <move>`.
+- **Repo-specific working agreements:** your agent's main instruction file
+  (`AGENTS.md`, `CLAUDE.md`, system prompt, …) — not this document.

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

@@ -11,6 +11,10 @@ CLI tracks state. Every move accepts and emits JSON (`--json`), with a strict
 without guessing internal state. All operations run fully offline against local
 `.devague/` state.
 
+For the portable, runtime-agnostic contract on *how* an assisting model should
+operate Devague — the move-driven mental model and the anti-fabrication rules —
+see [`llm-guidance.md`](llm-guidance.md) (also surfaced in `devague learn`).
+
 ## Versioning
 
 Every frame carries an integer `schema_version` (currently `1`). It is written
@@ -180,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.7.0 → devague-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devague"
-version = "0.7.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.9.0/tests/test_cli_affordances.py

@@ -0,0 +1,111 @@
+"""Tests for the agent-affordance verbs: learn / explain."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from devague.cli import main
+
+_GUIDANCE_DOC = Path(__file__).resolve().parents[1] / "docs" / "llm-guidance.md"
+
+
+def test_learn_describes_moves(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["learn"])
+    assert rc == 0
+    out = capsys.readouterr().out.lower()
+    assert "working backwards" in out
+    assert "capture" in out and "converge" in out
+
+
+def test_learn_teaches_first_question_and_guided_stages(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    rc = main(["learn"])
+    assert rc == 0
+    out = capsys.readouterr().out.lower()
+    # Issue #4's mandated entry point and supporting framing.
+    assert "what's the announcement?" in out
+    assert "users, teammates, or yourself" in out
+    # The canonical 10-step guided sequence is documented.
+    for stage in (
+        "announcement",
+        "audience",
+        "after",
+        "matter",
+        "before",
+        "honest",
+        "faq",
+        "boundaries",
+        "success",
+        "spec",
+    ):
+        assert stage in out
+
+
+def test_learn_json_lists_moves_and_stages(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["learn", "--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["tool"] == "devague"
+    assert "capture" in payload["moves"]
+    assert len(payload["stages"]) == 10
+    assert payload["first_question"] == "What's the announcement?"
+
+
+def test_learn_surfaces_operating_rules(capsys: pytest.CaptureFixture[str]) -> None:
+    # devague#19: the anti-fabrication contract is always-on in `learn` output.
+    rc = main(["learn"])
+    assert rc == 0
+    out = capsys.readouterr().out.lower()
+    assert "operating rules" in out
+    assert "anti-fabrication" in out
+    # The core rules and the not-a framing.
+    assert "stay proposed" in out and "user-only" in out
+    assert "not a mandatory conversation order" in out  # order is adaptive
+    assert "questionnaire" in out and "prd generator" in out
+    # Agent-agnostic pointer — not hardcoded to one runtime.
+    assert "agents.md" in out and "claude.md" in out
+    # A portable, always-resolvable URL (the wheel doesn't ship docs/) plus the
+    # in-repo path for contributors.
+    assert "https://github.com/agentculture/devague" in out
+    assert "docs/llm-guidance.md" in out
+
+
+def test_learn_json_exposes_operating_contract(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["learn", "--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    # guidance_doc is a portable, always-resolvable URL (docs/ isn't shipped in
+    # the wheel); the in-repo source path is exposed separately for contributors.
+    assert payload["guidance_doc"].startswith("https://")
+    assert payload["guidance_doc"].endswith("docs/llm-guidance.md")
+    assert payload["guidance_doc_repo_path"] == "docs/llm-guidance.md"
+    assert len(payload["operating_rules"]) >= 4
+    assert len(payload["not_a"]) == 3
+    assert any("proposed" in r.lower() for r in payload["operating_rules"])
+
+
+def test_guidance_doc_exists_and_documents_the_contract() -> None:
+    # The CLI points agents at this doc, so it must exist and carry the contract.
+    assert _GUIDANCE_DOC.is_file()
+    text = _GUIDANCE_DOC.read_text(encoding="utf-8").lower()
+    assert "anti-fabrication" in text
+    assert "never `confirm` your own proposal" in text or "never confirm your own proposal" in text
+    assert "not a mandatory" in text  # adaptive order
+    # Agent-agnostic, not Claude-specific.
+    assert "agents.md" in text
+
+
+def test_explain_a_move(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["explain", "converge"])
+    assert rc == 0
+    assert "converge" in capsys.readouterr().out.lower()
+
+
+def test_explain_unknown_move_errors(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["explain", "nope"])
+    assert rc == 1
+    assert "unknown" in capsys.readouterr().err.lower()