devague 0.5.1__tar.gz → 0.6.0__tar.gz

{devague-0.5.1 → devague-0.6.0}/.claude/skills/think/SKILL.md

@@ -58,7 +58,9 @@ portable resolution and the `status` helper.
 | `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.** |
+| `confirm <id> [<id>…]` / `reject <id> [<id>…]` | Resolve one or more claims (`c*`) / honesty conditions (`h*`) in one **transactional** call. **User-only decision.** Also `confirm --from-review <file>` to apply an edited review artifact. |
+| `review` | List every **proposed** (unconfirmed) claim + honesty condition with ids (`--json` too); writes a non-authoritative artifact to `.devague/reviews/<slug>.md`. Un-gated; never mutates. |
+| `question "<text>"` | Record / list / `--resolve` a pending user decision as durable working state in `.devague/questions/<slug>.md`. |
 | `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. |

{devague-0.5.1 → devague-0.6.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.6.0] - 2026-05-23
+
+### Added
+
+- **Human Review Loop (#17).** Makes the user-only confirmation step ergonomic at scale, preserving the anti-fabrication guarantee.
+  - `devague review` (+ `--json`) lists every proposed (unconfirmed) claim and honesty condition with ids — un-gated by convergence and without mutating state — and persists a non-authoritative artifact to `.devague/reviews/<slug>.md`.
+  - `confirm` / `reject` now accept multiple ids in one transactional call (any unknown id ⇒ nothing changes).
+  - `confirm --from-review <file>` applies a reviewed decision set: each item is emitted with a `pending` marker the human edits to `confirm`/`reject`; `pending` lines are never auto-confirmed (round-trippable artifact).
+  - `devague question` records / lists / resolves pending user decisions as durable working state in `.devague/questions/<slug>.md`.
+  - devague manages `.gitignore` so `.devague/reviews/` and `.devague/questions/` stay uncommitted working state by default.
+
+### Changed
+
+- `confirm --json` now emits `{confirmed, rejected}` (lists) instead of `{id, status}`, reflecting the multi-id, transactional batch.
+
 ## [0.5.1] - 2026-05-23
 
 ### Added

{devague-0.5.1 → devague-0.6.0}/CLAUDE.md

@@ -4,6 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Status
 
+**Human Review Loop landed (0.6.0, #17).** `devague review` (+ `--json`) lists
+every proposed claim + honesty condition with ids — un-gated by convergence,
+never mutating state — and writes a non-authoritative artifact to
+`.devague/reviews/<slug>.md`. `confirm` / `reject` now take multiple ids in one
+**transactional** call; `confirm --from-review <file>` applies an edited review
+artifact (`pending` lines are never auto-confirmed). `devague question` records
+pending decisions in `.devague/questions/<slug>.md`. devague manages
+`.gitignore` so `reviews/` and `questions/` stay uncommitted working state.
+
 **Spec contract landed (#5).** The entity model is documented in
 `docs/spec-contract.md` (the source of truth for kinds, the `(state × origin)`
 vocabulary, the structured convergence result, and the per-move I/O contract).
@@ -16,8 +25,9 @@ required_next_moves}` (plans: `ready_for_plan`) — a hard break from the old
 **Spec→plan engine landed (v0.4.0).** Both deterministic engines now ship.
 The **frame engine** (idea→spec) — Frame domain model, JSON store, convergence
 gate, renderer registry, and the flat moves `new` / `capture` / `interrogate` /
-`confirm` / `reject` / `park` / `converge` / `export` / `show` / `list` /
-`learn` / `explain`. The **plan engine** (spec→plan) is its structural peer:
+`confirm` / `reject` / `review` / `question` / `park` / `converge` / `export` /
+`show` / `list` / `learn` / `explain`. The **plan engine** (spec→plan) is its
+structural peer:
 `devague/plan.py`, `plan_convergence.py`, `plan_store.py`, `render/plan_md.py`,
 and the nested group `devague plan <move>` (`new` / `task` / `accept` / `depend`
 / `cover` / `confirm` / `reject` / `risk` / `converge` / `export` / `show` /

{devague-0.5.1 → devague-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devague
-Version: 0.5.1
+Version: 0.6.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
@@ -49,6 +49,50 @@ devague --version
 Run `devague learn` (or `devague plan learn`) to learn the method, and `devague
 explain <move>` for any single move.
 
+## Human Review Loop
+
+LLM-proposed claims and honesty conditions stay `proposed` until **you**
+confirm them — that anti-fabrication rule is the point of the method. The review
+loop makes that human step ergonomic at scale:
+
+```bash
+devague review                 # list every proposed (unconfirmed) item, with ids
+devague review --json          # same, structured
+devague confirm c2 h1 h3       # confirm many ids in one transactional call
+devague reject c4 c5           # reject many ids in one call
+devague confirm --from-review .devague/reviews/<slug>.md   # apply an edited review file
+```
+
+`review` is **not** gated on convergence and never mutates state. It writes a
+durable, explicitly non-authoritative artifact you can review out of band, then
+apply: each item is emitted with a `pending` marker — change it to `confirm` or
+`reject` and feed the file back with `confirm --from-review`. `pending` lines are
+never auto-confirmed; a batch is transactional (one bad id ⇒ nothing changes).
+
+Open questions / pending decisions live as durable working state too:
+
+```bash
+devague question "should batch confirm be transactional?"   # record a pending decision
+devague question --list                                     # review them
+devague question --resolve q1 --decision "yes, transactional"
+```
+
+Applying a resolved decision into the frame stays an explicit move (e.g.
+`devague capture --kind decision "…"` then `devague confirm`).
+
+### `.devague/` — what's committed vs working state
+
+| Path | Committed? |
+|------|-----------|
+| `.devague/frames/`, `.devague/plans/` | yes — the converged frame/plan state |
+| `.devague/reviews/<slug>.md` | no — local review working state |
+| `.devague/questions/<slug>.md` | no — local pending-decision working state |
+| `.devague/current`, `.devague/current_plan` | no — local pointers |
+
+devague keeps `reviews/` and `questions/` out of git for you (it manages
+`.gitignore`). Promote one into `docs/` only if you intentionally want it
+committed.
+
 ## Driving it from an agent
 
 Inside AgentCulture, an assistant drives this CLI through two operator skills —

devague-0.6.0/README.md

@@ -0,0 +1,85 @@
+# devague
+
+**`devague` is a command-line tool** that turns a vague feature idea into a
+buildable **spec**, then that spec into a buildable **plan** — by working
+backwards, then forwards. It is a small, deterministic Python CLI (no LLM calls
+inside it, fully unit-tested) — not an agent, service, or daemon. You install it
+and run `devague` from the repository you are speccing; state is plain JSON under
+`.devague/`.
+
+```text
+vague idea ──▶ buildable spec ──▶ buildable plan ──▶ build
+```
+
+## Install
+
+```bash
+uv tool install devague      # or: pipx install devague / pip install devague
+devague --version
+```
+
+## Two engines, one CLI
+
+- **Frame engine** (idea→spec) — start from the announcement ("pretend it
+  shipped"), capture and pressure-test claims, park open vagueness, and `export`
+  a spec only once the frame *converges*. Flat verbs: `devague new` /
+  `capture` / `interrogate` / `confirm` / `converge` / `export` / …
+- **Plan engine** (spec→plan) — seed a plan from a converged frame, cover every
+  target with tasks that carry acceptance criteria and an acyclic dependency
+  order, and `export` a plan only once it *converges*. Nested group:
+  `devague plan new` / `task` / `cover` / `converge` / `export` / …
+
+Run `devague learn` (or `devague plan learn`) to learn the method, and `devague
+explain <move>` for any single move.
+
+## Human Review Loop
+
+LLM-proposed claims and honesty conditions stay `proposed` until **you**
+confirm them — that anti-fabrication rule is the point of the method. The review
+loop makes that human step ergonomic at scale:
+
+```bash
+devague review                 # list every proposed (unconfirmed) item, with ids
+devague review --json          # same, structured
+devague confirm c2 h1 h3       # confirm many ids in one transactional call
+devague reject c4 c5           # reject many ids in one call
+devague confirm --from-review .devague/reviews/<slug>.md   # apply an edited review file
+```
+
+`review` is **not** gated on convergence and never mutates state. It writes a
+durable, explicitly non-authoritative artifact you can review out of band, then
+apply: each item is emitted with a `pending` marker — change it to `confirm` or
+`reject` and feed the file back with `confirm --from-review`. `pending` lines are
+never auto-confirmed; a batch is transactional (one bad id ⇒ nothing changes).
+
+Open questions / pending decisions live as durable working state too:
+
+```bash
+devague question "should batch confirm be transactional?"   # record a pending decision
+devague question --list                                     # review them
+devague question --resolve q1 --decision "yes, transactional"
+```
+
+Applying a resolved decision into the frame stays an explicit move (e.g.
+`devague capture --kind decision "…"` then `devague confirm`).
+
+### `.devague/` — what's committed vs working state
+
+| Path | Committed? |
+|------|-----------|
+| `.devague/frames/`, `.devague/plans/` | yes — the converged frame/plan state |
+| `.devague/reviews/<slug>.md` | no — local review working state |
+| `.devague/questions/<slug>.md` | no — local pending-decision working state |
+| `.devague/current`, `.devague/current_plan` | no — local pointers |
+
+devague keeps `reviews/` and `questions/` out of git for you (it manages
+`.gitignore`). Promote one into `docs/` only if you intentionally want it
+committed.
+
+## Driving it from an agent
+
+Inside AgentCulture, an assistant drives this CLI through two operator skills —
+**`/think`** (idea→spec) and **`/spec-to-plan`** (spec→plan) — which add a
+portable wrapper and a `status` next-move helper over the convergence gate. The
+CLI is the deterministic affordance; the agent decides the next move. See
+`CLAUDE.md` for that workflow and `docs/superpowers/specs/` for the design docs.

{devague-0.5.1 → devague-0.6.0}/devague/cli/__init__.py

@@ -65,7 +65,9 @@ def _build_parser() -> argparse.ArgumentParser:
     from devague.cli._commands import new as _new_cmd
     from devague.cli._commands import park as _park_cmd
     from devague.cli._commands import plan as _plan_cmd
+    from devague.cli._commands import question as _question_cmd
     from devague.cli._commands import reject as _reject_cmd
+    from devague.cli._commands import review as _review_cmd
     from devague.cli._commands import show as _show_cmd
 
     _learn_cmd.register(sub)
@@ -75,6 +77,8 @@ def _build_parser() -> argparse.ArgumentParser:
     _interrogate_cmd.register(sub)
     _confirm_cmd.register(sub)
     _reject_cmd.register(sub)
+    _review_cmd.register(sub)
+    _question_cmd.register(sub)
     _park_cmd.register(sub)
     _converge_cmd.register(sub)
     _export_cmd.register(sub)

devague-0.6.0/devague/cli/_commands/confirm.py

@@ -0,0 +1,96 @@
+"""``devague confirm`` — confirm claims/honesty conditions (user-only transition).
+
+Accepts one or more ids in a single call, or a reviewed decision set via
+``--from-review <file>`` (apply the confirm/reject markers a human edited into a
+``devague review`` artifact). Either way the batch is **transactional**: every
+id is validated first, and if any is unknown nothing is changed. Confirmation
+stays a user-only action, and ``--from-review`` applies only what the file
+explicitly marks — ``pending`` lines are never auto-confirmed. See issue #17.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from devague import store
+from devague.cli._errors import EXIT_USER_ERROR, DevagueError
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+from devague.render.review_md import parse_decisions
+
+
+def _exists(frame, item_id: str) -> bool:
+    return frame.find_claim(item_id) is not None or frame.find_honesty(item_id) is not None
+
+
+def _run(args: argparse.Namespace, confirm_ids: list[str], reject_ids: list[str]) -> int:
+    frame = resolve(args.frame)
+    all_ids = confirm_ids + reject_ids
+    if not all_ids:
+        raise DevagueError(EXIT_USER_ERROR, "no ids to resolve", "pass at least one id")
+    unknown = [i for i in all_ids if not _exists(frame, i)]
+    if unknown:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            f"no such claim or honesty condition: {', '.join(unknown)}",
+            "run 'devague show'; the batch is transactional — nothing was changed",
+        )
+    for item_id in confirm_ids:
+        frame.set_status(item_id, "confirmed")
+    for item_id in reject_ids:
+        frame.set_status(item_id, "rejected")
+    store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"confirmed": confirm_ids, "rejected": reject_ids}, json_mode=True)
+    else:
+        lines = [f"{i} -> confirmed" for i in confirm_ids]
+        lines += [f"{i} -> rejected" for i in reject_ids]
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def _from_review(path: str) -> tuple[list[str], list[str]]:
+    try:
+        text = Path(path).read_text(encoding="utf-8")
+    except OSError as err:
+        raise DevagueError(EXIT_USER_ERROR, f"cannot read review file: {path}", str(err))
+    try:
+        decisions = parse_decisions(text)
+    except ValueError as err:
+        raise DevagueError(EXIT_USER_ERROR, str(err), "fix the conflicting decision and retry")
+    confirm_ids = [i for i, d in decisions.items() if d == "confirm"]
+    reject_ids = [i for i, d in decisions.items() if d == "reject"]
+    if not confirm_ids and not reject_ids:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            "no decisions found in review file",
+            "change a line's 'pending' to 'confirm' or 'reject' first",
+        )
+    return confirm_ids, reject_ids
+
+
+def cmd_confirm(args: argparse.Namespace) -> int:
+    if args.from_review:
+        if args.ids:
+            raise DevagueError(
+                EXIT_USER_ERROR,
+                "pass ids or --from-review, not both",
+                "drop the positional ids when applying a review file",
+            )
+        confirm_ids, reject_ids = _from_review(args.from_review)
+        return _run(args, confirm_ids, reject_ids)
+    return _run(args, list(args.ids), [])
+
+
+def cmd_reject(args: argparse.Namespace) -> int:
+    return _run(args, [], list(args.ids))
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("confirm", help="Confirm claims/honesty conditions, or apply a review file.")
+    p.add_argument("ids", nargs="*", help="One or more claim ids (c*) or honesty ids (h*).")
+    p.add_argument("--from-review", help="Apply confirm/reject decisions from a review file.")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_confirm)

devague-0.6.0/devague/cli/_commands/question.py

@@ -0,0 +1,80 @@
+"""``devague question`` — record/list/resolve pending user decisions.
+
+Durable, uncommitted working state under .devague/questions/<slug>.md. The CLI
+owns the format (decision c20). Nothing here auto-resolves: ``--resolve`` only
+records a decision a human made; applying it into the frame is a separate,
+explicit move (see the file header). Issue #14/#17.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import questions_io, store
+from devague.cli._errors import EXIT_USER_ERROR, DevagueError
+from devague.cli._frames import resolve
+from devague.cli._output import emit_diagnostic, emit_result
+
+
+def _load(slug: str) -> list[dict]:
+    path = store.questions_path(slug)
+    return questions_io.parse(path.read_text(encoding="utf-8")) if path.exists() else []
+
+
+def _resolve_question(args: argparse.Namespace, slug: str, items: list[dict]) -> None:
+    target = next((i for i in items if i["id"] == args.resolve), None)
+    if target is None:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            f"no such question: {args.resolve}",
+            "run 'devague question --list'",
+        )
+    target["resolved"] = True
+    target["decision"] = args.decision
+    store.write_questions(slug, questions_io.render(slug, items))
+    if args.json:
+        emit_result({"id": args.resolve, "resolved": True}, json_mode=True)
+    else:
+        emit_result(f"{args.resolve} -> resolved", json_mode=False)
+
+
+def _add_question(args: argparse.Namespace, slug: str, items: list[dict]) -> None:
+    new_id = questions_io.next_id(items)
+    items.append({"id": new_id, "text": args.text, "resolved": False, "decision": None})
+    path = store.write_questions(slug, questions_io.render(slug, items))
+    if args.json:
+        emit_result({"id": new_id, "text": args.text, "path": str(path)}, json_mode=True)
+    else:
+        emit_result(f"recorded {new_id}", json_mode=False)
+        emit_diagnostic(f"wrote pending decision to {path} (uncommitted working state)")
+
+
+def _list_questions(args: argparse.Namespace, slug: str, items: list[dict]) -> None:
+    if args.json:
+        emit_result({"slug": slug, "questions": items}, json_mode=True)
+    else:
+        emit_result(questions_io.render(slug, items), json_mode=False)
+
+
+def cmd_question(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)  # validates the frame exists; never mutates it
+    slug = frame.slug
+    items = _load(slug)
+    if args.resolve:
+        _resolve_question(args, slug, items)
+    elif args.text:
+        _add_question(args, slug, items)
+    else:  # default / --list: show the pending-decisions state
+        _list_questions(args, slug, items)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("question", help="Record / list / resolve pending user decisions.")
+    p.add_argument("text", nargs="?", help="Question text to record (omit to list).")
+    p.add_argument("--resolve", metavar="QID", help="Mark a question id resolved.")
+    p.add_argument("--decision", help="The decision note recorded with --resolve.")
+    p.add_argument("--list", action="store_true", help="List pending decisions (default).")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_question)

devague-0.6.0/devague/cli/_commands/reject.py

@@ -0,0 +1,15 @@
+"""``devague reject`` — reject one or more claims / honesty conditions."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague.cli._commands.confirm import cmd_reject
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("reject", help="Reject one or more claims / honesty conditions.")
+    p.add_argument("ids", nargs="+", help="One or more claim ids (c*) or honesty ids (h*).")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_reject)

devague-0.6.0/devague/cli/_commands/review.py

@@ -0,0 +1,63 @@
+"""``devague review`` — surface every *proposed* (unconfirmed) item for human review.
+
+Lists proposed claims and proposed honesty conditions with their ids. It is
+deliberately NOT gated on convergence and never mutates state — it is a
+read-only view of what is awaiting a user decision (issue #17). Confirm/reject
+the listed ids with ``devague confirm`` / ``devague reject``.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import render, store
+from devague.cli._frames import resolve
+from devague.cli._output import emit_diagnostic, emit_result
+from devague.render.review_md import proposed_claims, proposed_honesty
+
+
+def _json_payload(frame) -> dict:
+    return {
+        "slug": frame.slug,
+        "proposed_claims": [
+            {"id": c.id, "kind": c.kind, "text": c.text} for c in proposed_claims(frame)
+        ],
+        "proposed_honesty": [
+            {"id": h.id, "claim_id": c.id, "claim_kind": c.kind, "text": h.text}
+            for c, h in proposed_honesty(frame)
+        ],
+    }
+
+
+def cmd_review(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)  # read-only: the frame is never saved/converged
+    artifact = render.render(frame, "review-md")
+    path = None
+    if not getattr(args, "no_write", False):
+        # Persist a durable, NON-authoritative artifact to uncommitted working
+        # state (.devague/reviews/<slug>.md) — distinct from docs/specs/.
+        path = store.write_review(frame.slug, artifact)
+    if getattr(args, "json", False):
+        payload = _json_payload(frame)
+        payload["path"] = str(path) if path else None
+        emit_result(payload, json_mode=True)
+    else:
+        emit_result(artifact, json_mode=False)
+        if path:
+            emit_diagnostic(f"wrote review artifact to {path} (unconfirmed, not authoritative)")
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "review",
+        help="List proposed (unconfirmed) claims + honesty conditions for human review.",
+    )
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.add_argument(
+        "--no-write",
+        action="store_true",
+        help="Print only; do not persist .devague/reviews/<slug>.md.",
+    )
+    p.set_defaults(func=cmd_review)

devague-0.6.0/devague/questions_io.py

@@ -0,0 +1,64 @@
+"""Pending-decision working state: ``.devague/questions/<slug>.md`` (CLI-owned).
+
+A durable, **uncommitted** list of open questions / pending user decisions raised
+while working a frame (issue #14/#17, decision c20). The CLI owns the markdown
+format so it round-trips (``parse`` ⇄ ``render``). A resolved decision is applied
+back into the frame with the normal moves (e.g. ``devague capture --kind decision
+"<the decision>"`` then ``devague confirm``); resolving here only records it.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Bounded whitespace only (single literal spaces, rest stripped in parse) so the
+# pattern is linear — no \s+…\s+…\.* shape that trips ReDoS heuristics.
+_LINE = re.compile(r"^- \[(?P<mark>[ x])\] `(?P<id>q\d+)`:(?P<rest>.*)$")
+_DECIDED = " — decided: "
+
+_BANNER = (
+    "> **Working state — not committed by default.** Open questions / pending "
+    "decisions for this frame. Apply a decision into the frame with the normal "
+    'moves (e.g. `devague capture --kind decision "…"` then `devague confirm`), '
+    "then mark it resolved here with `devague question --resolve <id>`."
+)
+
+
+def parse(text: str) -> list[dict]:
+    items: list[dict] = []
+    for line in text.splitlines():
+        m = _LINE.match(line.strip())
+        if not m:
+            continue
+        rest = m.group("rest")
+        resolved = m.group("mark") == "x"
+        decision = None
+        if resolved and _DECIDED in rest:
+            # render() appends the decided tail last, so split from the right —
+            # otherwise a question whose *text* contains the delimiter corrupts.
+            rest, decision = rest.rsplit(_DECIDED, 1)
+        items.append(
+            {"id": m.group("id"), "text": rest.strip(), "resolved": resolved, "decision": decision}
+        )
+    return items
+
+
+def next_id(items: list[dict]) -> str:
+    nums = [int(i["id"][1:]) for i in items if i["id"][1:].isdigit()]
+    return f"q{(max(nums) + 1) if nums else 1}"
+
+
+def render(slug: str, items: list[dict]) -> str:
+    out = [f"# Pending decisions — {slug}", "", _BANNER, ""]
+    open_items = [i for i in items if not i["resolved"]]
+    done_items = [i for i in items if i["resolved"]]
+    out += ["## Open", ""]
+    out += [f"- [ ] `{i['id']}`: {i['text']}" for i in open_items] or ["None."]
+    out += [""]
+    if done_items:
+        out += ["## Resolved", ""]
+        for i in done_items:
+            tail = f"{_DECIDED}{i['decision']}" if i["decision"] else ""
+            out.append(f"- [x] `{i['id']}`: {i['text']}{tail}")
+        out += [""]
+    return "\n".join(out).rstrip() + "\n"

{devague-0.5.1 → devague-0.6.0}/devague/render/__init__.py

@@ -33,7 +33,9 @@ def render(frame: Frame, fmt: str) -> str:
 
 # Register the built-in renderers (import-time side effect).
 from devague.render import frame_md as _frame_md  # noqa: E402
+from devague.render import review_md as _review_md  # noqa: E402
 from devague.render import spec_md as _spec_md  # noqa: E402
 
 register("frame-md", _frame_md.render_frame)
 register("spec-md", _spec_md.render_spec)
+register("review-md", _review_md.render_review)

devague-0.6.0/devague/render/review_md.py

@@ -0,0 +1,76 @@
+"""Renderer + parser for the human-review artifact — every *proposed* item.
+
+Explicitly NON-authoritative and distinct from spec-md: it exists so a human can
+review LLM proposals (in-terminal or out of band) before confirming any. Nothing
+here is authoritative until the user runs ``devague confirm``. See issue #17.
+
+The artifact is **round-trippable**: each proposed item is emitted with a leading
+``pending`` marker. Edit a line's marker to ``confirm`` or ``reject``, then feed
+the file to ``devague confirm --from-review <file>`` to apply exactly those
+decisions (``render_review`` ⇄ :func:`parse_decisions`).
+"""
+
+from __future__ import annotations
+
+import re
+
+from devague.frame import Frame
+
+# A decision line: "- <marker> `<id>` ...". The marker is the only editable part.
+_DECISIONS = ("pending", "confirm", "reject")
+_LINE = re.compile(r"^- (?P<decision>pending|confirm|reject)\s+`(?P<id>[ch]\d+)`")
+
+_BANNER = (
+    "> **Review artifact — nothing confirmed yet.** These are unconfirmed, "
+    "LLM-proposed items; they are NOT authoritative and NOT a buildable spec. "
+    "To apply, change a line's `pending` to `confirm` or `reject`, then run "
+    "`devague confirm --from-review <file>` (or `devague confirm <id> ...`)."
+)
+
+
+def proposed_claims(frame: Frame) -> list:
+    return [c for c in frame.claims if c.status == "proposed"]
+
+
+def proposed_honesty(frame: Frame) -> list:
+    return [(c, h) for c in frame.claims for h in c.honesty_conditions if h.status == "proposed"]
+
+
+def render_review(frame: Frame) -> str:
+    out: list[str] = [f"# Review — {frame.title}", "", _BANNER, ""]
+    claims = proposed_claims(frame)
+    pairs = proposed_honesty(frame)
+    if not claims and not pairs:
+        out += ["No proposed items — nothing awaiting review.", ""]
+        return "\n".join(out).rstrip() + "\n"
+    if claims:
+        out += ["## Proposed claims", ""]
+        out += [f"- pending `{c.id}` ({c.kind}): {c.text}" for c in claims]
+        out += [""]
+    if pairs:
+        out += ["## Proposed honesty conditions", ""]
+        out += [f"- pending `{h.id}` (on `{c.id}` {c.kind}): {h.text}" for c, h in pairs]
+        out += [""]
+    return "\n".join(out).rstrip() + "\n"
+
+
+def parse_decisions(text: str) -> dict[str, str]:
+    """Parse a (possibly edited) review artifact into ``{id: "confirm"|"reject"}``.
+
+    ``pending`` lines carry no decision and are skipped — applying a review file
+    therefore touches only what the human explicitly marked (no auto-confirm).
+    Raises ``ValueError`` on a duplicate, conflicting decision for one id.
+    """
+    decisions: dict[str, str] = {}
+    for line in text.splitlines():
+        m = _LINE.match(line.strip())
+        if not m:
+            continue
+        decision, item_id = m.group("decision"), m.group("id")
+        if decision == "pending":
+            continue
+        if item_id in decisions and decisions[item_id] != decision:
+            prior = decisions[item_id]
+            raise ValueError(f"conflicting decisions for {item_id}: {prior} vs {decision}")
+        decisions[item_id] = decision
+    return decisions