devague 0.7.0__tar.gz → 0.8.0__tar.gz

{devague-0.7.0 → devague-0.8.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.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.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.7.0 → devague-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devague
-Version: 0.7.0
+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.7.0 → 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.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.7.0 → 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

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

@@ -1,6 +1,6 @@
 [project]
 name = "devague"
-version = "0.7.0"
+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.7.0 → devague-0.8.0}/uv.lock

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

devague-0.7.0/tests/test_cli_affordances.py

@@ -1,64 +0,0 @@
-"""Tests for the agent-affordance verbs: learn / explain."""
-
-from __future__ import annotations
-
-import json
-
-import pytest
-
-from devague.cli import main
-
-
-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_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()