devague 0.6.1__tar.gz → 0.8.0__tar.gz

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

@@ -5,6 +5,28 @@ 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.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
+
+- **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.8.0}/CLAUDE.md

@@ -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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devague
-Version: 0.6.1
+Version: 0.8.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.8.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.6.1 → devague-0.8.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.8.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.8.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.8.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.8.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.8.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.6.1 → devague-0.8.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
@@ -153,8 +157,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 +183,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.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devague"
-version = "0.6.1"
+version = "0.8.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/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()

{devague-0.6.1 → devague-0.8.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.8.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")