devague 0.6.1__tar.gz → 0.7.0__tar.gz

{devague-0.6.1 → devague-0.7.0}/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.7.0] - 2026-05-23
+
+### Added
+
+- **Plan persistence hardening (#18).** Plans now carry an integer `schema_version` (`PLAN_SCHEMA_VERSION = 1`), written on save and checked on load — the plan-engine peer of the frame `schema_version` contract (#5). `plan_store.load` fails closed with a clean `DevagueError` (exit 1 + upgrade hint) when a plan declares a newer unsupported schema; pre-0.7.0 plans without the key load silently as the current schema.
+- Loaded-object validation for plans: `Task.origin` / `Task.status` and `PlanRisk.kind` are now validated at construction (via `__post_init__`), so a hand-edited or corrupted plan file surfaces an actionable "malformed plan" `DevagueError` instead of a traceback. (Task/dep/cover *id* cross-references are deliberately not validated at load — coverage and acyclic-dependency checks already run against the live frame in `plan converge`.)
+
+### Changed
+
+- `devague/cli/_plans.py` `resolve_plan` now distinguishes an invalid `--plan` slug, a newer-schema plan, a missing plan, and a malformed plan file — each with its own remediation hint (mirroring the frame `resolve`).
+
+### Fixed
+
+- **Persistence integrity, both engines (PR #25 review).** `store.load` / `plan_store.load` now reject a file whose embedded `slug` disagrees with the requested slug (previously a tampered file could redirect a later `save` onto a different frame/plan). And `schema_version` is now parsed strictly via the shared `frame.parse_schema_version` — a non-integer value (`1.9`, `true`, `"1"`, `null`) is rejected instead of being silently coerced by `int()` (which truncated `1.9`→`1` and accepted `True`→`1`). Both guards were applied symmetrically to the frame engine to keep the persistence twins aligned.
+
 ## [0.6.1] - 2026-05-23
 
 ### Fixed

{devague-0.6.1 → devague-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devague
-Version: 0.6.1
+Version: 0.7.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.6.1 → devague-0.7.0}/devague/cli/_plans.py

@@ -16,14 +16,29 @@ def resolve_plan(slug: str | None) -> Plan:
             "run 'devague plan new --frame <slug>' or pass --plan <slug>",
         )
     try:
-        return plan_store.load(slug)
+        plan_store.validate_slug(slug)
     except ValueError as exc:
         raise DevagueError(
             EXIT_USER_ERROR,
             f"invalid plan slug: {slug!r}",
             "slugs are lowercase letters, digits, and hyphens — no path separators",
         ) from exc
+    try:
+        return plan_store.load(slug)
+    except plan_store.IncompatiblePlanSchemaError as exc:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            str(exc),
+            "this plan was written by a newer devague — upgrade: 'uv tool install -U devague'",
+        ) from exc
     except FileNotFoundError:
         raise DevagueError(
             EXIT_USER_ERROR, f"no such plan: {slug}", "run 'devague plan list' to see plans"
         ) from None
+    except ValueError as exc:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            f"plan {slug!r} is malformed: {exc}",
+            "the plan file was hand-edited or corrupted — "
+            "fix .devague/plans/<slug>.json or recreate the plan",
+        ) from exc

{devague-0.6.1 → devague-0.7.0}/devague/frame.py

@@ -200,6 +200,24 @@ def to_dict(frame: Frame) -> dict:
     return dataclasses.asdict(frame)
 
 
+def parse_schema_version(d: dict, default: int) -> int:
+    """Read a persisted ``schema_version`` strictly.
+
+    A missing key means a pre-field artifact → treat as ``default`` (back-compat).
+    A present value must be a real ``int`` — ``bool`` and non-int types (float,
+    str, ``None``) are rejected rather than silently coerced (e.g. plain
+    ``int(1.9)`` would truncate to ``1`` and ``int(True)`` would yield ``1``), so
+    a malformed version surfaces as a clean error instead of loading as current.
+    Shared by the frame and plan engines (the persistence twins).
+    """
+    if "schema_version" not in d:
+        return default
+    v = d["schema_version"]
+    if isinstance(v, bool) or not isinstance(v, int):
+        raise ValueError(f"schema_version must be an integer, got {v!r}")
+    return v
+
+
 def from_dict(d: dict) -> Frame:
     claims = [
         Claim(
@@ -219,7 +237,7 @@ def from_dict(d: dict) -> Frame:
         slug=d["slug"],
         title=d["title"],
         # A 0.4.0 frame predates the field; treat it as the current schema.
-        schema_version=int(d.get("schema_version", SCHEMA_VERSION)),
+        schema_version=parse_schema_version(d, SCHEMA_VERSION),
         status=d.get("status", "drafting"),
         created=d.get("created", ""),
         updated=d.get("updated", ""),

{devague-0.6.1 → devague-0.7.0}/devague/plan.py

@@ -16,7 +16,18 @@ import dataclasses
 from dataclasses import dataclass, field
 from typing import Optional
 
-from devague.frame import SPEC_AFFECTING_KINDS, VAGUENESS_KINDS, Frame
+from devague.frame import (
+    ORIGINS,
+    SPEC_AFFECTING_KINDS,
+    VAGUENESS_KINDS,
+    Frame,
+    parse_schema_version,
+)
+
+# Bump when the persisted plan shape changes incompatibly. `plan_store.load`
+# fails closed on a plan whose schema_version is newer/unknown (see #18; the
+# plan-engine peer of frame.SCHEMA_VERSION).
+PLAN_SCHEMA_VERSION = 1
 
 TASK_STATUSES = ("proposed", "confirmed", "rejected")
 # Risks reuse the frame's open-vagueness kinds: a plan risk is the task-level peer of
@@ -35,6 +46,12 @@ class Task:
     deps: list[str] = field(default_factory=list)  # task ids this task depends on
     covers: list[str] = field(default_factory=list)  # frame claim/honesty ids (c*/h*)
 
+    def __post_init__(self) -> None:
+        if self.origin not in ORIGINS:
+            raise ValueError(f"unknown task origin: {self.origin!r}")
+        if self.status not in TASK_STATUSES:
+            raise ValueError(f"unknown task status: {self.status!r}")
+
 
 @dataclass
 class PlanRisk:
@@ -43,6 +60,10 @@ class PlanRisk:
     kind: str  # one of RISK_KINDS
     task_id: Optional[str] = None
 
+    def __post_init__(self) -> None:
+        if self.kind not in RISK_KINDS:
+            raise ValueError(f"unknown plan risk kind: {self.kind!r}")
+
 
 @dataclass
 class CoverageTarget:
@@ -62,6 +83,7 @@ class Plan:
     slug: str
     title: str
     frame_slug: str
+    schema_version: int = PLAN_SCHEMA_VERSION
     status: str = "drafting"  # drafting | converged | exported
     created: str = ""
     updated: str = ""
@@ -170,6 +192,8 @@ def from_dict(d: dict) -> Plan:
         slug=d["slug"],
         title=d["title"],
         frame_slug=d["frame_slug"],
+        # A pre-0.7.0 plan predates the field; treat it as the current schema.
+        schema_version=parse_schema_version(d, PLAN_SCHEMA_VERSION),
         status=d.get("status", "drafting"),
         created=d.get("created", ""),
         updated=d.get("updated", ""),

{devague-0.6.1 → devague-0.7.0}/devague/plan_store.py

@@ -12,13 +12,17 @@ import json
 import time
 from pathlib import Path
 
-from devague.plan import Plan, from_dict, to_dict
+from devague.plan import PLAN_SCHEMA_VERSION, Plan, from_dict, to_dict
 from devague.store import validate_slug
 
 PLANS_DIR = Path(".devague/plans")
 CURRENT_PLAN = Path(".devague/current_plan")
 
 
+class IncompatiblePlanSchemaError(ValueError):
+    """A persisted plan declares a schema_version this devague cannot read."""
+
+
 def _now() -> str:
     return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
 
@@ -45,6 +49,16 @@ def load(slug: str) -> Plan:
     plan = from_dict(json.loads(p.read_text(encoding="utf-8")))
     validate_slug(plan.slug)  # reject a tampered file whose internal slug escapes
     validate_slug(plan.frame_slug)  # the linked frame slug must be safe to load too
+    if plan.slug != slug:
+        # The embedded slug drives save() and the current-plan pointer; a file
+        # whose internal slug disagrees with its filename could silently redirect
+        # a later save onto a different plan, so reject it.
+        raise ValueError(f"plan slug mismatch: file {slug!r} declares slug {plan.slug!r}")
+    if plan.schema_version > PLAN_SCHEMA_VERSION:
+        raise IncompatiblePlanSchemaError(
+            f"plan {slug!r} uses schema_version {plan.schema_version}, but this "
+            f"devague supports up to {PLAN_SCHEMA_VERSION}; upgrade devague to read it"
+        )
     return plan
 
 

{devague-0.6.1 → devague-0.7.0}/devague/store.py

@@ -130,6 +130,11 @@ def load(slug: str) -> Frame:
         raise FileNotFoundError(slug)
     frame = from_dict(json.loads(p.read_text(encoding="utf-8")))
     validate_slug(frame.slug)  # reject a tampered file whose internal slug escapes
+    if frame.slug != slug:
+        # The embedded slug drives save() and the current-frame pointer; a file
+        # whose internal slug disagrees with its filename could silently redirect
+        # a later save onto a different frame, so reject it.
+        raise ValueError(f"frame slug mismatch: file {slug!r} declares slug {frame.slug!r}")
     if frame.schema_version > SCHEMA_VERSION:
         raise IncompatibleSchemaError(
             f"frame {slug!r} uses schema_version {frame.schema_version}, but this "

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

@@ -153,8 +153,9 @@ the exit code is non-zero and `stderr` carries a `hint:` line.
 **Validation errors** (all raise a clean `DevagueError`, exit code 1): unknown
 claim kind / origin / status or vagueness kind (rejected at construction);
 unknown claim or honesty id on `confirm`/`reject`; an invalid `--frame` slug; a
-missing frame; a malformed or hand-edited frame file; a frame whose
-`schema_version` is too new.
+missing frame; a malformed or hand-edited frame file (including one whose
+embedded slug doesn't match the requested slug, or whose `schema_version` is not
+an integer); a frame whose `schema_version` is too new.
 
 ## Anti-fabrication guarantee
 
@@ -178,3 +179,20 @@ targets derived from a converged frame, Tasks (`origin`/`status` like claims,
 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`.
+
+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`
+(exit code 1, upgrade hint) when a plan declares a `schema_version` newer than
+this devague supports. A pre-0.7.0 plan with no `schema_version` key loads
+silently as the current schema. Loaded `Task.origin` / `Task.status` and
+`PlanRisk.kind` are validated at construction; an invalid value surfaces as a
+"malformed plan" `DevagueError` rather than a traceback. (Task/dep/cover **id**
+cross-references are deliberately *not* validated at load — coverage and acyclic
+dependency checks already run against the live frame in `plan converge`.)
+
+Both `load`s also reject a file whose embedded slug disagrees with the requested
+slug (so a tampered file can't silently redirect a later `save`), and parse
+`schema_version` strictly via the shared `frame.parse_schema_version` — a
+non-integer value is rejected rather than coerced. These guards are symmetric
+across the frame and plan persistence twins.

{devague-0.6.1 → devague-0.7.0}/pyproject.toml

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

{devague-0.6.1 → devague-0.7.0}/tests/test_cli_plan.py

@@ -278,6 +278,29 @@ def test_resolve_plan_invalid_slug(tmp_path, monkeypatch, capsys) -> None:
     assert "invalid plan slug" in capsys.readouterr().err
 
 
+def test_resolve_plan_rejects_newer_schema(tmp_path, monkeypatch, capsys) -> None:
+    slug = _converged_plan(monkeypatch, tmp_path, capsys)
+    p = plan_store.path_for(slug)
+    raw = json.loads(p.read_text(encoding="utf-8"))
+    raw["schema_version"] = raw["schema_version"] + 99
+    p.write_text(json.dumps(raw), encoding="utf-8")
+    rc = main(["plan", "show", "--plan", slug])
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "schema_version" in err and "upgrade" in err
+
+
+def test_resolve_plan_rejects_malformed_value(tmp_path, monkeypatch, capsys) -> None:
+    slug = _converged_plan(monkeypatch, tmp_path, capsys)
+    p = plan_store.path_for(slug)
+    raw = json.loads(p.read_text(encoding="utf-8"))
+    raw["tasks"][0]["origin"] = "alien"
+    p.write_text(json.dumps(raw), encoding="utf-8")
+    rc = main(["plan", "show", "--plan", slug])
+    assert rc == 1
+    assert "malformed" in capsys.readouterr().err
+
+
 # ── learn / explain ───────────────────────────────────────────────────────────
 def test_learn_and_explain(tmp_path, monkeypatch, capsys) -> None:
     monkeypatch.chdir(tmp_path)

{devague-0.6.1 → devague-0.7.0}/tests/test_frame.py

@@ -98,6 +98,13 @@ def test_legacy_frame_without_schema_version_loads() -> None:
     assert f.schema_version == SCHEMA_VERSION
 
 
+@pytest.mark.parametrize("bad", [1.9, True, "1", None])
+def test_from_dict_rejects_non_integer_schema_version(bad) -> None:
+    # int() would silently coerce 1.9->1 / True->1; a malformed type must raise.
+    with pytest.raises(ValueError, match="schema_version"):
+        from_dict({"slug": "s", "title": "t", "schema_version": bad})
+
+
 def test_dataclasses_validate_enums() -> None:
     with pytest.raises(ValueError):
         Claim(id="c1", kind="bogus", text="x")

{devague-0.6.1 → devague-0.7.0}/tests/test_plan.py

@@ -3,7 +3,15 @@ from __future__ import annotations
 import pytest
 
 from devague.frame import Frame
-from devague.plan import Plan, from_dict, targets_from_frame, to_dict
+from devague.plan import (
+    PLAN_SCHEMA_VERSION,
+    Plan,
+    PlanRisk,
+    Task,
+    from_dict,
+    targets_from_frame,
+    to_dict,
+)
 
 
 def _plan() -> Plan:
@@ -60,6 +68,48 @@ def test_set_status_transitions_and_reports_unknown() -> None:
     assert p.set_status("tX", "confirmed") is False
 
 
+def test_plan_carries_schema_version() -> None:
+    p = _plan()
+    assert p.schema_version == PLAN_SCHEMA_VERSION
+    assert to_dict(p)["schema_version"] == PLAN_SCHEMA_VERSION
+    assert from_dict(to_dict(p)).schema_version == PLAN_SCHEMA_VERSION
+
+
+def test_legacy_plan_without_schema_version_loads() -> None:
+    # A pre-0.7.0 plan has no schema_version key — it must still load.
+    p = from_dict({"slug": "s", "title": "t", "frame_slug": "s", "tasks": []})
+    assert p.schema_version == PLAN_SCHEMA_VERSION
+
+
+def test_dataclasses_validate_enums() -> None:
+    with pytest.raises(ValueError):
+        Task(id="t1", summary="x", origin="alien")
+    with pytest.raises(ValueError):
+        Task(id="t1", summary="x", status="weird")
+    with pytest.raises(ValueError):
+        PlanRisk(id="r1", text="x", kind="nope")
+
+
+def test_from_dict_rejects_malformed_enum_values() -> None:
+    # The load path reconstructs via from_dict, so a hand-edited bad value is caught.
+    with pytest.raises(ValueError):
+        from_dict(
+            {
+                "slug": "s",
+                "title": "t",
+                "frame_slug": "s",
+                "tasks": [{"id": "t1", "summary": "x", "origin": "alien"}],
+            }
+        )
+
+
+@pytest.mark.parametrize("bad", [1.9, True, "1", None])
+def test_from_dict_rejects_non_integer_schema_version(bad) -> None:
+    # int() would silently coerce 1.9->1 / True->1; a malformed type must raise.
+    with pytest.raises(ValueError, match="schema_version"):
+        from_dict({"slug": "s", "title": "t", "frame_slug": "s", "schema_version": bad})
+
+
 def test_roundtrip_preserves_nested_fields() -> None:
     p = _plan()
     t = p.add_task("core", origin="llm")

{devague-0.6.1 → devague-0.7.0}/tests/test_plan_store.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+import json
+
 import pytest
 
 from devague import plan_store, store
 from devague.frame import Frame
-from devague.plan import Plan
+from devague.plan import PLAN_SCHEMA_VERSION, Plan
 
 
 def _plan() -> Plan:
@@ -65,3 +67,43 @@ def test_plan_coexists_with_same_slug_frame(tmp_path, monkeypatch) -> None:
     # Both persist independently in their own directories.
     assert store.list_slugs() == ["demo"]
     assert plan_store.list_slugs() == ["demo"]
+
+
+def test_save_writes_schema_version(tmp_path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    plan_store.save(_plan())
+    raw = json.loads(plan_store.path_for("demo").read_text(encoding="utf-8"))
+    assert raw["schema_version"] == PLAN_SCHEMA_VERSION
+    assert plan_store.load("demo").schema_version == PLAN_SCHEMA_VERSION
+
+
+def test_load_rejects_newer_schema_version(tmp_path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    plan_store.save(_plan())
+    p = plan_store.path_for("demo")
+    raw = json.loads(p.read_text(encoding="utf-8"))
+    raw["schema_version"] = PLAN_SCHEMA_VERSION + 99
+    p.write_text(json.dumps(raw), encoding="utf-8")
+    with pytest.raises(plan_store.IncompatiblePlanSchemaError, match="schema_version"):
+        plan_store.load("demo")
+
+
+def test_load_legacy_plan_without_schema_version(tmp_path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    plan_store.PLANS_DIR.mkdir(parents=True, exist_ok=True)
+    legacy = {"slug": "demo", "title": "Demo", "frame_slug": "demo", "tasks": []}
+    plan_store.path_for("demo").write_text(json.dumps(legacy), encoding="utf-8")
+    assert plan_store.load("demo").schema_version == PLAN_SCHEMA_VERSION
+
+
+def test_load_rejects_slug_mismatch(tmp_path, monkeypatch) -> None:
+    # A file under demo.json whose internal slug is a *different* valid slug must
+    # be rejected, so a later save() can't be redirected onto another plan.
+    monkeypatch.chdir(tmp_path)
+    plan_store.save(_plan())
+    p = plan_store.path_for("demo")
+    raw = json.loads(p.read_text(encoding="utf-8"))
+    raw["slug"] = "other"
+    p.write_text(json.dumps(raw), encoding="utf-8")
+    with pytest.raises(ValueError, match="slug mismatch"):
+        plan_store.load("demo")

{devague-0.6.1 → devague-0.7.0}/tests/test_store.py

@@ -106,3 +106,16 @@ def test_load_legacy_frame_without_schema_version(tmp_path, monkeypatch) -> None
     legacy = {"slug": "demo", "title": "Demo", "claims": [], "open_vagueness": []}
     store.path_for("demo").write_text(json.dumps(legacy), encoding="utf-8")
     assert store.load("demo").schema_version == SCHEMA_VERSION
+
+
+def test_load_rejects_slug_mismatch(tmp_path, monkeypatch) -> None:
+    # A file under demo.json whose internal slug is a *different* valid slug must
+    # be rejected, so a later save() can't be redirected onto another frame.
+    monkeypatch.chdir(tmp_path)
+    store.save(Frame(slug="demo", title="Demo"))
+    p = store.path_for("demo")
+    raw = json.loads(p.read_text(encoding="utf-8"))
+    raw["slug"] = "other"
+    p.write_text(json.dumps(raw), encoding="utf-8")
+    with pytest.raises(ValueError, match="slug mismatch"):
+        store.load("demo")

{devague-0.6.1 → devague-0.7.0}/uv.lock

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