devague 0.3.2__tar.gz → 0.3.3__tar.gz

devague-0.3.3/.claude/skills/devague/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: devague
+description: >
+  Operate the devague working-backwards spec tool: turn a vague feature idea
+  into a buildable, pressure-tested spec by starting from the announcement
+  ("pretend it shipped"), capturing and classifying claims, interrogating them
+  with honesty conditions and hard questions, parking open vagueness as a
+  first-class object, and exporting a spec only once the frame *converges*. Use
+  when the user says "spec this", "work backwards", "turn this idea into a
+  spec", "announcement frame", or "devague", or when a feature request is too
+  vague to build yet. Authored and maintained in agentculture/devague (origin =
+  devague); steward pulls this skill from here and broadcasts it to the
+  AgentCulture mesh — it is NOT vendored from steward like the other skills here.
+---
+
+# devague — work an idea backwards into a buildable spec
+
+`devague` turns a vague feature idea into a buildable spec by **working
+backwards**: you start from the announcement you'd make if it had already
+shipped, then build an **Announcement Frame** by capturing claims, pressure
+-testing them, parking what's still genuinely unknown, and only exporting once
+the frame converges.
+
+The CLI is **deterministic and move-driven** — it is *not* a wizard. There is no
+fixed sequence of prompts. **You (the agent) choose the next move; the CLI just
+tracks state and tells you what's still missing.** Run `devague learn` for the
+canonical ten-stage arc and `devague explain <move>` for any single move.
+
+This skill is the operator: a portable wrapper plus one helper (`status`) that
+reads the convergence gate and tells you the recommended next move.
+
+## How to run
+
+The entry point is `scripts/devague.sh`. Invoke it from the repository you are
+speccing (frames persist under `.devague/` in the current directory):
+
+```bash
+bash .claude/skills/devague/scripts/devague.sh <move> [args...]
+bash .claude/skills/devague/scripts/devague.sh status
+```
+
+It resolves the CLI portably — an installed `devague` on `PATH` (the normal
+case), falling back to `uv run devague` when you are inside the devague checkout.
+If neither resolves it prints an install hint (`uv tool install devague`). Every
+move except `status` is forwarded verbatim, so you can equally call the CLI
+directly (`devague <move> …`) when it is installed; the wrapper exists for
+portable resolution and the `status` helper.
+
+### Moves
+
+| Move | What it does |
+|------|--------------|
+| `new "<announcement>"` | Start a frame from the announcement (the first move). Seeds an auto-confirmed `announcement` claim. |
+| `capture --kind <kind> "<text>"` | Record + classify a claim. `--origin llm` lands it as `proposed`. |
+| `interrogate <id> --honesty "…"` | Attach an honesty condition (what must be true). Also `--hard-question`, `--risk`, `--contradicts`, `--blocking`. |
+| `confirm <id>` / `reject <id>` | Resolve a claim (`c*`) or honesty condition (`h*`). **User-only decision.** |
+| `park "<text>" --kind <kind>` | Move uncertainty into first-class open vagueness instead of forcing an answer. |
+| `converge` | Evaluate the gate; list remaining gaps. |
+| `export` | Write the buildable spec to `docs/specs/` — only after `converge` passes. |
+| `show` / `list` | Render a frame / list frames (`--json` for raw state). |
+| `learn` / `explain <move>` | Teach the method / explain one move. |
+
+Claim kinds: `announcement`, `audience`, `after_state`, `before_state`,
+`why_it_matters`, `boundary`, `success_signal`, `open_question`. Vagueness kinds:
+`unknown_nonblocking`, `unknown_blocking`, `out_of_scope`, `follow_up`.
+
+These are exactly the kinds the **shipped CLI enforces** (`CLAIM_KINDS` /
+`VAGUENESS_KINDS` in `devague/frame.py`) — the skill documents the surface as
+built, so every command here passes the CLI's `choices=` validation. A fuller
+proposed type/state set, plus the formal per-move input/output/transition
+contract, is tracked on the CLI side in
+[#5](https://github.com/agentculture/devague/issues/5); for the authoritative
+live shape of any move, run it with `--json` (or `devague learn --json` /
+`devague explain <move>`). When the CLI's contract grows, re-sync this list.
+
+### `status` — the next-move helper
+
+`status` is a wrapper-only verb (the CLI has no `status`). It reads
+`converge --json` + `list --json` and prints where the current frame stands, the
+remaining gaps, and the recommended next move derived from the first gap.
+`converge --json` currently emits `{passed, missing}`, which is what the helper
+consumes; if [#5](https://github.com/agentculture/devague/issues/5) enriches that
+payload (e.g. structured `blockers` / `warnings` / `required_next_moves`),
+`status` will surface the richer fields then.
+
+```text
+frame: my-feature    (1 frame total)
+convergence: NOT passed — 2 gap(s):
+  - missing a 'boundary' / non-goal claim
+  - claim c2 has no confirmed honesty condition
+
+recommended next move (first gap):
+  devague capture --kind boundary "<text>"
+```
+
+Run it whenever you're unsure what to do next.
+
+## Hard rules (do not violate)
+
+These are the point of the method — convergence must mean something.
+
+- **LLM proposals stay proposed.** A claim captured with `--origin llm`, and any
+  honesty condition you (the agent) propose, lands 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 not
+  silently become an authoritative requirement.
+- **Honesty conditions route through the user.** Propose them freely with
+  `interrogate --honesty`; the user owns whether they hold.
+- **Converge, don't vibe.** `export` is gated on `converge` passing. Never claim
+  the frame is ready on a hunch — run `converge` (or `status`) and resolve every
+  listed gap. The gate requires confirmed `announcement` / `audience` /
+  `after_state`, a `before_state` or `why_it_matters`, a `boundary`, a
+  `success_signal`, a confirmed honesty condition on every spec-affecting claim,
+  and no unresolved blocking vagueness or hard question.
+- **Park real unknowns; don't paper over them.** If something is genuinely
+  unknown, `park` it (blocking or non-blocking) rather than fabricating an
+  answer. Blocking vagueness holds back convergence — by design.
+
+## Output contract
+
+Results go to **stdout**, diagnostics and errors to **stderr** — a strict split
+you can rely on when parsing. Pass `--json` to any move for a structured payload
+on the same stream. Exit code `0` on success, non-zero on user error (with a
+`hint:` line). Frames live under `.devague/` in the current directory.
+
+## Worked example
+
+A short end-to-end session (the kind you'd run to spec a feature like
+[devague#5](https://github.com/agentculture/devague/issues/5)):
+
+```bash
+d() { bash .claude/skills/devague/scripts/devague.sh "$@"; }
+
+d new "Devague ships a documented spec contract"
+d capture --kind audience "devague + the assisting LLM"
+d capture --kind after_state "a vague idea becomes a buildable, pressure-tested spec"
+d capture --kind why_it_matters "specs converge on evidence, not vibes"
+d capture --kind boundary "not a full PRD generator; no fixed wizard"
+d capture --kind success_signal "a frame exports only after the gate passes"
+
+# Pressure-test a claim, then let the USER confirm the condition:
+d interrogate c1 --honesty "the contract round-trips: save -> load -> identical frame"
+# ...user reviews and runs: d confirm h1
+
+# Park a genuine unknown instead of guessing:
+d park "exact JSON schema versioning policy" --kind unknown_nonblocking
+
+d status        # what's left + the next move
+d converge      # gate; resolve any listed gaps
+d export        # writes docs/specs/<slug>.md once converged
+```
+
+The exported spec-md is a buildable artifact; it can feed directly into
+`superpowers:writing-plans` or a normal implementation PR.
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, where the
+devague agent maintains it alongside the tool it operates (dogfooding). It is the
+*inverse* of the other skills under `.claude/skills/`, which devague vendors
+**from** steward. When this skill is ready, steward pulls it **from** devague and
+broadcasts it to the rest of the AgentCulture mesh. The `cite, don't import`
+policy still holds: downstream repos copy it, they don't symlink or depend on it.
+See `docs/skill-sources.md`.

devague-0.3.3/.claude/skills/devague/scripts/devague.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# devague.sh — operate the devague working-backwards spec tool.
+#
+# devague turns a vague feature idea into a buildable spec by working backwards.
+# This wrapper is the agent-facing operator for the deterministic devague CLI:
+# it resolves the CLI portably, forwards every move verbatim, and adds one
+# value-add subcommand — `status` — that reads the convergence gate and names
+# the recommended next move.
+#
+# Origin: authored and maintained in agentculture/devague. steward pulls this
+# skill from here and broadcasts it to the rest of the AgentCulture mesh, so it
+# is written to run anywhere — portable bash, no devague-checkout assumptions.
+#
+# Frames persist under .devague/ in the current directory, so run from the repo
+# you are speccing.
+
+set -euo pipefail
+
+# ── resolve the devague CLI (mesh-first, then local-dev fallback) ───────────
+DEVAGUE=()
+resolve_devague() {
+    if command -v devague >/dev/null 2>&1; then
+        DEVAGUE=(devague)            # installed tool — the normal mesh case
+        return 0
+    fi
+    # Local-dev fallback: inside the devague checkout, run via uv.
+    local dir="$PWD"
+    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+        if [ -f "$dir/pyproject.toml" ] \
+            && grep -q '^name = "devague"' "$dir/pyproject.toml" 2>/dev/null; then
+            if command -v uv >/dev/null 2>&1; then
+                DEVAGUE=(uv run devague)
+                return 0
+            fi
+            break
+        fi
+        dir=$(dirname "$dir")
+    done
+    cat >&2 <<'EOF'
+error: devague CLI not found.
+hint: install it with `uv tool install devague` (or `pipx install devague`),
+      or run from inside the devague checkout with `uv` available.
+      https://github.com/agentculture/devague
+EOF
+    return 1
+}
+
+usage() {
+    cat <<'EOF'
+devague.sh — operate the devague working-backwards spec tool.
+
+Usage:
+  devague.sh <move> [args...]    forward a devague move
+  devague.sh status [--frame S]  where the frame stands + the next move
+  devague.sh help                this help
+
+Moves (forwarded to the devague CLI; run `devague learn` for the full method):
+  new          start a frame from the announcement ("pretend it shipped")
+  capture      record + classify a claim (--kind audience|after_state|...)
+  interrogate  pressure-test a claim (--honesty / --hard-question / --risk)
+  confirm      confirm a claim or honesty condition  (USER-only decision)
+  reject       reject a claim or honesty condition
+  park         record open vagueness instead of forcing an answer
+  converge     check whether the frame can export a spec
+  export       write the buildable spec (only after converge passes)
+  show / list  render a frame / list frames
+  learn        teach the method   |   explain <move>  explain one move
+
+Frames persist under .devague/ in the current directory — run from the repo
+you are speccing. Results go to stdout, diagnostics to stderr; pass --json to
+any move for structured output.
+
+Note: `status` is a wrapper-only verb (the CLI has no `status`); everything
+else is forwarded verbatim, so new devague moves work without editing this
+script.
+EOF
+}
+
+# ── status: read the convergence gate and recommend the next move ──────────
+cmd_status() {
+    local list_json conv_out conv_err conv_rc req_frame="" prev="" tmp_err
+
+    # Pull the requested --frame (if any) so the header names the same frame
+    # that convergence is evaluated for; converge still receives it via "$@".
+    for arg in "$@"; do
+        case "$prev" in --frame) req_frame="$arg" ;; esac
+        case "$arg" in --frame=*) req_frame="${arg#--frame=}" ;; esac
+        prev="$arg"
+    done
+
+    list_json="$("${DEVAGUE[@]}" list --json 2>/dev/null || true)"
+
+    # Capture converge's stdout, stderr, and exit code separately. converge
+    # exits 0 even when "not passed", so a non-zero code is a *real* error
+    # (bad/missing --frame, corrupt frame) we must surface, not swallow.
+    tmp_err="$(mktemp)"
+    set +e
+    conv_out="$("${DEVAGUE[@]}" converge --json "$@" 2>"$tmp_err")"
+    conv_rc=$?
+    set -e
+    conv_err="$(cat "$tmp_err")"
+    rm -f "$tmp_err"
+
+    DEVAGUE_LIST_JSON="$list_json" \
+        DEVAGUE_CONV_JSON="$conv_out" \
+        DEVAGUE_CONV_ERR="$conv_err" \
+        DEVAGUE_CONV_RC="$conv_rc" \
+        DEVAGUE_REQ_FRAME="$req_frame" \
+        python3 - <<'PY'
+import json
+import os
+import re
+import sys
+
+
+def load(name):
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+lst = load("DEVAGUE_LIST_JSON") or {}
+conv = load("DEVAGUE_CONV_JSON")
+conv_err = os.environ.get("DEVAGUE_CONV_ERR", "").strip()
+req_frame = os.environ.get("DEVAGUE_REQ_FRAME", "").strip()
+try:
+    conv_rc = int(os.environ.get("DEVAGUE_CONV_RC", "0") or "0")
+except ValueError:
+    conv_rc = 0
+
+frames = lst.get("frames") or []
+current = lst.get("current")
+
+if not frames:
+    print("no frames yet — start one:")
+    print('  devague new "<announcement>"')
+    print('  first question: "What\'s the announcement? Pretend this shipped'
+          ' successfully — what would you announce?"')
+    sys.exit(0)
+
+shown = req_frame or current or "(none selected)"
+total = len(frames)
+print(f"frame: {shown}    ({total} frame{'s' if total != 1 else ''} total)")
+
+if conv is None:
+    # A non-zero converge exit on an existing frame is a genuine error —
+    # relay devague's own error:/hint: lines to stderr instead of masking it.
+    if conv_rc != 0 and conv_err:
+        sys.stderr.write(conv_err + "\n")
+        sys.exit(conv_rc)
+    print("convergence: unknown (could not evaluate the frame)")
+    print("next move: devague show     # inspect the frame")
+    sys.exit(0)
+
+if conv.get("passed"):
+    print("convergence: PASSED ✓")
+    print("next move: devague export   # write the buildable spec")
+    sys.exit(0)
+
+missing = conv.get("missing") or []
+print(f"convergence: NOT passed — {len(missing)} gap(s):")
+for gap in missing:
+    print(f"  - {gap}")
+
+
+def suggest(gap):
+    # Confirmation is a USER-only transition; a plain (user-origin) capture
+    # is already confirmed, so never imply the agent should confirm its own
+    # work. Spell out who confirms wherever a confirm is in play.
+    m = re.search(r"missing confirmed '([a-z_]+)' claim", gap)
+    if m:
+        kind = m.group(1)
+        return (f'devague capture --kind {kind} "<text>"'
+                f'   (a user capture auto-confirms; an --origin llm capture'
+                f' then needs the USER to confirm it)')
+    if "before_state" in gap and "why_it_matters" in gap:
+        return 'devague capture --kind why_it_matters "<text>"'
+    if "boundary" in gap:
+        return 'devague capture --kind boundary "<text>"'
+    if "success_signal" in gap:
+        return 'devague capture --kind success_signal "<text>"'
+    m = re.search(r"claim (c\d+) still proposed", gap)
+    if m:
+        cid = m.group(1)
+        return (f'this is an LLM proposal — the USER decides:'
+                f' devague confirm {cid}   (or: devague reject {cid})')
+    m = re.search(r"claim (c\d+) has no confirmed honesty condition", gap)
+    if m:
+        cid = m.group(1)
+        return (f'devague interrogate {cid} --honesty "<what must be true>"'
+                f'   then the USER runs: devague confirm <hN>')
+    m = re.search(r"blocking vagueness (v\d+)", gap)
+    if m:
+        return (f"resolve {m.group(1)}: capture+confirm the answer, "
+                f"or re-park it as non-blocking")
+    m = re.search(r"blocking hard question (q\d+) on (c\d+)", gap)
+    if m:
+        return (f"resolve {m.group(1)} on {m.group(2)}: answer it, then "
+                f"capture/confirm the resulting claim")
+    return "devague show     # inspect and decide"
+
+
+if missing:
+    print()
+    print("recommended next move (first gap):")
+    print(f"  {suggest(missing[0])}")
+PY
+}
+
+main() {
+    case "${1:-help}" in
+        help | -h | --help)
+            usage
+            return 0
+            ;;
+        status)
+            shift
+            resolve_devague
+            cmd_status "$@"
+            ;;
+        *)
+            # Forward everything else to the CLI verbatim (including --version,
+            # and any future devague move), so its own parser owns the surface.
+            resolve_devague
+            exec "${DEVAGUE[@]}" "$@"
+            ;;
+    esac
+}
+
+main "$@"

{devague-0.3.2 → devague-0.3.3}/.flake8

@@ -14,4 +14,4 @@ exclude =
     build
 per-file-ignores =
     # Bandit S-rules are noisy in tests (assert, subprocess, etc.) — mute them.
-    tests/*:S101,S404,S603
+    tests/*:S101,S404,S603,S607

{devague-0.3.2 → devague-0.3.3}/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.3.3] - 2026-05-23
+
+### Added
+
+- First-party `devague` skill (`.claude/skills/devague/`): a portable wrapper (`scripts/devague.sh`) that operates the working-backwards CLI, forwards every move, and adds a `status` next-move helper over the convergence gate; plus `tests/test_devague_skill.py` and an outbound-origin note in `docs/skill-sources.md`. Origin = devague; steward pulls it from here and broadcasts to the AgentCulture mesh.
+
 ## [0.3.2] - 2026-05-23
 
 ### Security

{devague-0.3.2 → devague-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devague
-Version: 0.3.2
+Version: 0.3.3
 Summary: devague — turns a vague feature idea into a buildable spec by working backwards.
 Project-URL: Homepage, https://github.com/agentculture/devague
 Project-URL: Issues, https://github.com/agentculture/devague/issues

{devague-0.3.2 → devague-0.3.3}/docs/skill-sources.md

@@ -25,6 +25,17 @@ rows.
 | `sonarclaude` | `steward` (`../steward/.claude/skills/sonarclaude/`) | 2026-05-22 | None — portable verbatim. Project key resolves from `$SONAR_PROJECT` / `--project` (here: `agentculture_devague`). |
 | `doc-test-alignment` | `steward` (`../steward/.claude/skills/doc-test-alignment/`) | 2026-05-22 | **Stub upstream** — `scripts/check.sh` exits with a not-yet-implemented error today; the contract for what it will do lives in its `SKILL.md`. Vendored verbatim to carry the contract. |
 
+## Origin skills (outbound)
+
+Not every skill here is inbound. The `devague` skill is **authored and
+maintained in this repo** — devague is its origin/upstream, not a downstream
+consumer. The devague agent dogfoods it to operate the devague CLI while
+improving the tool. The flow runs the *opposite* direction of the table above.
+
+| Skill | Origin | Downstream | Notes |
+|-------|--------|------------|-------|
+| `devague` | **devague** (here: `.claude/skills/devague/`) | `steward`, then the AgentCulture mesh | Operator for the deterministic devague CLI: portable resolution + a `status` next-move helper over the convergence gate. When ready, `steward` re-vendors it from `../devague/.claude/skills/devague/` and broadcasts it to the mesh. `cite, don't import` still applies — downstream copies it, no symlink/dependency. Written portable-first so it passes steward's `portability-lint.sh`. |
+
 ## Vendoring policy
 
 - **Cite, don't import.** Skills are copied, not symlinked or installed as

{devague-0.3.2 → devague-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devague"
-version = "0.3.2"
+version = "0.3.3"
 description = "devague — turns a vague feature idea into a buildable spec by working backwards."
 readme = "README.md"
 license = "MIT"

devague-0.3.3/tests/test_devague_skill.py

@@ -0,0 +1,143 @@
+"""Smoke tests for the first-party ``devague`` skill wrapper.
+
+These drive ``.claude/skills/devague/scripts/devague.sh`` via subprocess in a
+sandboxed ``tmp_path`` cwd (so ``.devague/`` never touches the repo). They pin
+the contract steward relies on when it pulls this skill into the mesh: the
+wrapper forwards moves verbatim, ``status`` reads the convergence gate and names
+the next move, and ``export`` stays blocked until the frame converges.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCRIPT = REPO_ROOT / ".claude" / "skills" / "devague" / "scripts" / "devague.sh"
+
+
+def run(*args: str, cwd: Path, env: dict | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["bash", str(SCRIPT), *args],
+        cwd=str(cwd),
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _drive(cwd: Path, *args: str) -> subprocess.CompletedProcess:
+    proc = run(*args, cwd=cwd)
+    assert proc.returncode == 0, f"{args} failed: {proc.stderr}"
+    return proc
+
+
+def test_script_is_executable_and_valid_bash() -> None:
+    assert SCRIPT.exists(), f"missing wrapper at {SCRIPT}"
+    assert os.access(SCRIPT, os.X_OK), "wrapper should be executable"
+    # `bash -n` parses without running.
+    assert subprocess.run(["bash", "-n", str(SCRIPT)]).returncode == 0
+
+
+def test_help_lists_moves(tmp_path: Path) -> None:
+    proc = _drive(tmp_path, "help")
+    assert "operate the devague" in proc.stdout
+    for move in ("new", "capture", "interrogate", "converge", "export", "status"):
+        assert move in proc.stdout
+
+
+def test_forwards_learn_verbatim(tmp_path: Path) -> None:
+    proc = _drive(tmp_path, "learn")
+    assert "What's the announcement?" in proc.stdout
+
+
+def test_status_reports_no_frames(tmp_path: Path) -> None:
+    proc = _drive(tmp_path, "status")
+    assert "no frames yet" in proc.stdout
+
+
+def test_status_names_gaps_and_next_move(tmp_path: Path) -> None:
+    _drive(tmp_path, "new", "Devague ships a documented spec contract")
+    proc = _drive(tmp_path, "status")
+    assert "NOT passed" in proc.stdout
+    assert "missing confirmed 'audience' claim" in proc.stdout
+    # first gap -> capture the audience claim
+    assert "devague capture --kind audience" in proc.stdout
+
+
+def test_status_suggestion_does_not_imply_agent_confirm(tmp_path: Path) -> None:
+    # A user-origin capture auto-confirms; the suggestion must not imply the
+    # agent should run a follow-up `confirm` (the user-only-confirm hard rule).
+    _drive(tmp_path, "new", "Devague ships a documented spec contract")
+    proc = _drive(tmp_path, "status")
+    assert "auto-confirm" in proc.stdout
+    assert "then: devague confirm" not in proc.stdout
+
+
+def test_status_header_reflects_frame_flag(tmp_path: Path) -> None:
+    _drive(tmp_path, "new", "First frame")
+    second = _drive(tmp_path, "new", "Second frame", "--json")
+    slug = json.loads(second.stdout)["slug"]
+    # current pointer is now the second frame; ask about the first explicitly.
+    proc = _drive(tmp_path, "status", "--frame", "first-frame")
+    assert "frame: first-frame" in proc.stdout
+    assert slug != "first-frame"  # guards the test against a no-op
+
+
+def test_status_surfaces_real_frame_errors(tmp_path: Path) -> None:
+    # A bad --frame must surface devague's error, not a misleading fallback.
+    _drive(tmp_path, "new", "A real frame")
+    proc = run("status", "--frame", "ghost", cwd=tmp_path)
+    assert proc.returncode != 0
+    assert "no such frame" in proc.stderr
+    assert "no frames yet" not in proc.stdout
+    assert "unknown" not in proc.stdout
+
+
+def test_export_blocked_until_converged(tmp_path: Path) -> None:
+    _drive(tmp_path, "new", "Devague ships a documented spec contract")
+    proc = run("export", cwd=tmp_path)
+    assert proc.returncode != 0
+    assert "has not converged" in proc.stderr
+
+
+def test_full_session_converges_and_exports(tmp_path: Path) -> None:
+    _drive(tmp_path, "new", "Devague ships a documented spec contract")
+    _drive(tmp_path, "capture", "--kind", "audience", "devague + the assisting LLM")
+    _drive(tmp_path, "capture", "--kind", "after_state", "a vague idea becomes a buildable spec")
+    _drive(tmp_path, "capture", "--kind", "why_it_matters", "specs converge on evidence not vibes")
+    _drive(tmp_path, "capture", "--kind", "boundary", "not a full PRD generator")
+    _drive(tmp_path, "capture", "--kind", "success_signal", "exports only after the gate passes")
+
+    # Every confirmed spec-affecting claim needs a confirmed honesty condition.
+    for cid in ("c1", "c2", "c3", "c4", "c5", "c6"):
+        out = _drive(tmp_path, "interrogate", cid, "--honesty", f"{cid} is testable", "--json")
+        hid = json.loads(out.stdout)["added"][0]["id"]
+        _drive(tmp_path, "confirm", hid)
+
+    status = _drive(tmp_path, "status")
+    assert "PASSED" in status.stdout
+    assert "devague export" in status.stdout
+
+    _drive(tmp_path, "converge")
+    exported = _drive(tmp_path, "export")
+    assert "exported spec" in exported.stdout
+    specs = list((tmp_path / "docs" / "specs").glob("*.md"))
+    assert specs, "export should write a spec file"
+
+
+def test_missing_cli_emits_install_hint(tmp_path: Path) -> None:
+    """With no resolvable ``devague``/``uv`` and no checkout, the wrapper hints."""
+    minimal_path = "/usr/bin:/bin"
+    env = {**os.environ, "PATH": minimal_path}
+    # Skip if this environment still resolves the tools under the minimal PATH.
+    if shutil.which("devague", path=minimal_path) or shutil.which("uv", path=minimal_path):
+        pytest.skip("devague/uv resolvable under minimal PATH; cannot test hint path")
+    proc = run("show", cwd=tmp_path, env=env)
+    assert proc.returncode != 0
+    assert "devague CLI not found" in proc.stderr

{devague-0.3.2 → devague-0.3.3}/uv.lock

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