devague 0.4.0__tar.gz → 0.5.0__tar.gz

{devague-0.4.0 → devague-0.5.0}/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh

@@ -108,7 +108,6 @@ cmd_status() {
         python3 - <<'PY'
 import json
 import os
-import re
 import sys
 
 
@@ -154,52 +153,25 @@ if conv is None:
     print("next move: devague plan show     # inspect the plan")
     sys.exit(0)
 
-if conv.get("passed"):
+if conv.get("ready_for_plan"):
     print("convergence: PASSED ✓")
+    for w in conv.get("warnings") or []:
+        print(f"  ⚠ {w}")
     print("next move: devague plan export   # write the buildable plan")
     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):
-    if "no tasks yet" in gap:
-        return 'devague plan task "<summary>" --covers <c*/h*> --accept "<criterion>"'
-    m = re.search(r"coverage target (\w+) ", gap)
-    if m:
-        tid = m.group(1)
-        return (
-            f'cover {tid}: devague plan task "<summary>" --covers {tid} --accept "<...>"'
-            f"   (or: devague plan cover <tN> --target {tid})"
-        )
-    m = re.search(r"task (t\d+) has no acceptance", gap)
-    if m:
-        return f'devague plan accept {m.group(1)} "<acceptance criterion>"'
-    m = re.search(r"task (t\d+) still proposed", gap)
-    if m:
-        tid = m.group(1)
-        return (
-            f"this is an LLM proposal — the USER decides:"
-            f" devague plan confirm {tid}   (or: devague plan reject {tid})"
-        )
-    m = re.search(r"task (t\d+) depends on unknown task (t\d+)", gap)
-    if m:
-        return f"fix {m.group(1)}'s dependency on missing {m.group(2)} (add it, or drop the dep)"
-    if "dependency cycle" in gap:
-        return "break the dependency cycle: re-point one task's --dep so the graph is acyclic"
-    m = re.search(r"blocking risk (r\d+)", gap)
-    if m:
-        return f"resolve {m.group(1)}: cover it with a task, or re-record it as non-blocking"
-    return "devague plan show     # inspect and decide"
-
-
-if missing:
+blockers = conv.get("blockers") or []
+print(f"convergence: NOT passed — {len(blockers)} gap(s):")
+for b in blockers:
+    print(f"  - {b}")
+for w in conv.get("warnings") or []:
+    print(f"  ⚠ {w}")
+
+moves = conv.get("required_next_moves") or []
+if moves:
     print()
     print("recommended next move (first gap):")
-    print(f"  {suggest(missing[0])}")
+    print(f"  {moves[0]}")
 PY
 }
 

{devague-0.4.0 → devague-0.5.0}/.claude/skills/think/SKILL.md

@@ -66,27 +66,31 @@ portable resolution and the `status` helper.
 | `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`.
+`why_it_matters`, `boundary`, `success_signal`, `open_question`, `non_goal`,
+`requirement`, `assumption`, `decision`. 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
+built, so every command here passes the CLI's `choices=` validation. `requirement`
+is spec-affecting (needs a confirmed honesty condition); `non_goal` / `decision`
+are descriptive; an unconfirmed `assumption` is a convergence *warning*, not a
+blocker. The formal entity model, the `(state × origin)` vocabulary, and the
+per-move input/output/transition/error contract are documented in
+[`docs/spec-contract.md`](../../../docs/spec-contract.md) (issue
+[#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.
+`devague explain <move>`).
 
 ### `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.
+remaining gaps, and the recommended next move. `converge --json` emits the
+structured result `{ready_for_spec, blockers, warnings, parked_items,
+required_next_moves}` (issue [#5](https://github.com/agentculture/devague/issues/5));
+the helper reads `ready_for_spec`, lists the `blockers` and `warnings`, and shows
+`required_next_moves[0]` as the recommended move — no longer deriving it itself.
 
 ```text
 frame: my-feature    (1 frame total)
@@ -155,10 +159,28 @@ d converge      # gate; resolve any listed gaps
 d export        # writes docs/specs/<slug>.md once converged
 ```
 
-The exported spec-md is a buildable artifact. The next leg is the sibling
-**`/spec-to-plan`** skill: `devague plan new --frame <slug>` seeds a plan from the
-converged frame and works it forward into a buildable plan (it can equally feed
-`superpowers:writing-plans` or a normal implementation PR).
+The exported spec-md is a buildable artifact.
+
+## After export — commit, then hand off
+
+Once `export` writes the spec **and the user has reviewed it**, close the
+idea→spec leg cleanly before moving on:
+
+1. **Commit the spec.** Commit the exported `docs/specs/<slug>.md` (along with
+   the `.devague/<slug>.json` frame state and any review artifact under
+   `docs/reviews/`) so the converged frame is durable in history, not just on
+   disk. Use a focused message, e.g. `git commit -m "spec: <slug> (devague
+   /think)"`. The frame and the spec are the evidence trail for every confirmed
+   claim — keep them together. (Per the repo's standing convention this normally
+   becomes a branch + PR via the `cicd` skill; commit-only is fine when the user
+   asks for it.)
+2. **Hand off to `/spec-to-plan`.** The forward leg is the sibling skill:
+   `devague plan new --frame <slug>` seeds a plan from the converged frame and
+   works it forward into a buildable plan (it can equally feed
+   `superpowers:writing-plans` or a normal implementation PR).
+
+Don't pause for a "what next?" menu after a reviewed export — the standing flow
+is **commit, then `/spec-to-plan`**.
 
 ## Provenance
 

{devague-0.4.0 → devague-0.5.0}/.claude/skills/think/scripts/think.sh

@@ -114,7 +114,6 @@ cmd_status() {
         python3 - <<'PY'
 import json
 import os
-import re
 import sys
 
 
@@ -161,58 +160,25 @@ if conv is None:
     print("next move: devague show     # inspect the frame")
     sys.exit(0)
 
-if conv.get("passed"):
+if conv.get("ready_for_spec"):
     print("convergence: PASSED ✓")
+    for w in conv.get("warnings") or []:
+        print(f"  ⚠ {w}")
     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:
+blockers = conv.get("blockers") or []
+print(f"convergence: NOT passed — {len(blockers)} gap(s):")
+for b in blockers:
+    print(f"  - {b}")
+for w in conv.get("warnings") or []:
+    print(f"  ⚠ {w}")
+
+moves = conv.get("required_next_moves") or []
+if moves:
     print()
     print("recommended next move (first gap):")
-    print(f"  {suggest(missing[0])}")
+    print(f"  {moves[0]}")
 PY
 }
 

devague-0.5.0/.devague/current_plan

@@ -0,0 +1 @@
+devague-now-ships-a-documented-spec-contract-every

devague-0.5.0/.devague/frames/devague-now-ships-a-documented-spec-contract-every.json

@@ -0,0 +1,263 @@
+{
+  "slug": "devague-now-ships-a-documented-spec-contract-every",
+  "title": "Devague now ships a documented spec contract: every frame is a durable, reloadable artifact, and converge returns a structured result (ready_for_spec, blockers, warnings, parked_items, required_next_moves) instead of prose-only advice",
+  "status": "exported",
+  "created": "2026-05-23T08:08:13Z",
+  "updated": "2026-05-23T09:17:12Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "Devague now ships a documented spec contract: every frame is a durable, reloadable artifact, and converge returns a structured result (ready_for_spec, blockers, warnings, parked_items, required_next_moves) instead of prose-only advice",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "A frame round-trips losslessly (save then load yields an identical frame) including schema_version, the new claim types, and the structured convergence payload; existing 0.4.0 frames still load",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "Devague and the assisting LLM that drives it \u2014 they coordinate around structured feature-framing state without a rigid wizard",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "Every move accepts and emits documented JSON, and the contract spells out per-move input / output / state-transition / validation-errors so an LLM can drive devague without guessing internal state",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "after_state",
+      "text": "A vague idea becomes a claim-based, pressure-tested, buildable spec held in a durable, reloadable artifact whose entities are validated",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "Matches shipped 0.4.0 reality \u2014 converge --json emits {passed, missing} today and no contract doc is committed (verifiable in the repo before relying on it)",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "before_state",
+      "text": "Framing state is partly implicit and undocumented; converge returns prose-only advice ({passed, missing}); there is no documented contract an LLM can rely on",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "The contract is enforced by validation on load: a schema-violating frame is rejected with a clear, actionable error rather than silently accepted",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "An LLM and devague can only coordinate reliably around a contract that is documented, validated, and machine-readable \u2014 convergence must mean something, not vibes",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "Convergence stays evidence-based and export stays gated on converge passing; the gate is computed only from confirmed claims and confirmed honesty conditions, never a hunch",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "Not a full PRD generator and not a fixed wizard; the move-driven, deterministic model stays",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "The deterministic move-driven model is preserved: no fixed prompt sequence is added; the CLI stays a state tracker and the LLM still chooses the next move",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "boundary",
+      "text": "The local contract requires no GitHub, agents, or external services",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "Every contract operation (create / load / mutate / show / converge / export) runs fully offline against local .devague/ state with zero network calls",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "boundary",
+      "text": "Convergence is never claimed on vibes, and LLM-proposed content is never silently promoted to confirmed truth",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "LLM-proposed claims and honesty conditions persist as proposed (origin=llm) and require an explicit user confirm before they affect convergence \u2014 nothing auto-confirms",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "success_signal",
+      "text": "converge returns a structured result (ready_for_spec, blockers, warnings, parked_items, required_next_moves) with blockers instead of prose-only advice",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "converge --json emits ONLY the new structured shape {ready_for_spec, blockers, warnings, parked_items, required_next_moves} (hard break); the skill's status helper is updated in the same change; blockers block convergence and warnings do not",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "success_signal",
+      "text": "A documented spec contract exists in the repo, with worked contract examples for at least one feature frame",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "The committed contract doc is the source of truth for kinds / states / fields / transitions and includes at least one worked frame example the CLI can actually round-trip",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "success_signal",
+      "text": "The CLI can create, load, mutate, and display a frame locally; core entities are validated",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h11",
+          "text": "create / load / mutate / show round-trip through the JSON store under validation, and the demonstrated operations are covered by passing tests",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "success_signal",
+      "text": "Tests cover claim provenance, honesty-condition confirmation, parking vagueness, and convergence failure",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h12",
+          "text": "Each of the four areas (provenance, honesty-condition confirmation, parking vagueness, convergence failure) has at least one test asserting the contract behavior, all green in CI",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "boundary",
+      "text": "The contract formalizes 0.4.0's shipped vocabulary as canonical \u2014 state in {proposed,confirmed,rejected,parked} x origin in {user,llm}; no rename and no migration of existing frames",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h13",
+          "text": "The doc maps the issue's proposed names (llm_proposed, user_confirmed, intentionally_out_of_scope, ...) onto the shipped (state x origin) model so no information is lost and no rename is required",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "success_signal",
+      "text": "The claim-type vocabulary adds non_goal, requirement, assumption, and decision to the shipped set, each with a documented convergence-gate impact",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h14",
+          "text": "Each new type's gate impact is documented and tested: requirement is spec-affecting (needs a confirmed honesty condition like other claims); non_goal and decision are descriptive (non-blocking); an unconfirmed assumption surfaces as a warning, not a blocker",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c15",
+      "kind": "success_signal",
+      "text": "Every frame carries a schema_version field; load validates by version so existing frames keep loading as the schema grows",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h15",
+          "text": "schema_version is written on every save and checked on load; an unknown or newer version fails closed with a clear error rather than corrupting state",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": [
+    {
+      "id": "v1",
+      "text": "Whether to also publish a formal machine-readable JSON Schema file alongside the prose contract doc + dataclasses, or treat the dataclasses as the schema of record",
+      "kind": "follow_up",
+      "claim_id": null
+    },
+    {
+      "id": "v2",
+      "text": "Whether requirement-type claims should eventually carry acceptance criteria like plan tasks do (overlaps the spec-to-plan leg), or stay prose-only in the frame",
+      "kind": "follow_up",
+      "claim_id": null
+    }
+  ]
+}