devague 0.4.0__tar.gz → 0.4.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. {devague-0.4.0 → devague-0.4.1}/.claude/skills/think/SKILL.md +22 -4
  2. devague-0.4.1/.devague/current_plan +1 -0
  3. devague-0.4.1/.devague/frames/devague-now-ships-a-documented-spec-contract-every.json +263 -0
  4. devague-0.4.1/.devague/plans/devague-now-ships-a-documented-spec-contract-every.json +363 -0
  5. {devague-0.4.0 → devague-0.4.1}/CHANGELOG.md +14 -0
  6. {devague-0.4.0 → devague-0.4.1}/PKG-INFO +1 -1
  7. {devague-0.4.0 → devague-0.4.1}/devague/render/frame_md.py +3 -3
  8. {devague-0.4.0 → devague-0.4.1}/devague/render/plan_md.py +11 -7
  9. {devague-0.4.0 → devague-0.4.1}/devague/render/spec_md.py +14 -12
  10. devague-0.4.1/docs/plans/devague-now-ships-a-documented-spec-contract-every.md +85 -0
  11. devague-0.4.1/docs/reviews/spec-contract-frame-review.md +150 -0
  12. devague-0.4.1/docs/specs/devague-now-ships-a-documented-spec-contract-every.md +55 -0
  13. {devague-0.4.0 → devague-0.4.1}/pyproject.toml +1 -1
  14. {devague-0.4.0 → devague-0.4.1}/tests/test_cli_plan.py +1 -1
  15. devague-0.4.1/tests/test_render.py +81 -0
  16. {devague-0.4.0 → devague-0.4.1}/tests/test_render_plan.py +7 -0
  17. {devague-0.4.0 → devague-0.4.1}/uv.lock +1 -1
  18. devague-0.4.0/tests/test_render.py +0 -41
  19. {devague-0.4.0 → devague-0.4.1}/.claude/skills/cicd/SKILL.md +0 -0
  20. {devague-0.4.0 → devague-0.4.1}/.claude/skills/cicd/scripts/_resolve-nick.sh +0 -0
  21. {devague-0.4.0 → devague-0.4.1}/.claude/skills/cicd/scripts/portability-lint.sh +0 -0
  22. {devague-0.4.0 → devague-0.4.1}/.claude/skills/cicd/scripts/pr-reply.sh +0 -0
  23. {devague-0.4.0 → devague-0.4.1}/.claude/skills/cicd/scripts/pr-status.sh +0 -0
  24. {devague-0.4.0 → devague-0.4.1}/.claude/skills/cicd/scripts/workflow.sh +0 -0
  25. {devague-0.4.0 → devague-0.4.1}/.claude/skills/communicate/SKILL.md +0 -0
  26. {devague-0.4.0 → devague-0.4.1}/.claude/skills/communicate/scripts/fetch-issues.sh +0 -0
  27. {devague-0.4.0 → devague-0.4.1}/.claude/skills/communicate/scripts/mesh-message.sh +0 -0
  28. {devague-0.4.0 → devague-0.4.1}/.claude/skills/communicate/scripts/post-comment.sh +0 -0
  29. {devague-0.4.0 → devague-0.4.1}/.claude/skills/communicate/scripts/post-issue.sh +0 -0
  30. {devague-0.4.0 → devague-0.4.1}/.claude/skills/communicate/scripts/templates/skill-update-brief.md +0 -0
  31. {devague-0.4.0 → devague-0.4.1}/.claude/skills/doc-test-alignment/SKILL.md +0 -0
  32. {devague-0.4.0 → devague-0.4.1}/.claude/skills/doc-test-alignment/scripts/check.sh +0 -0
  33. {devague-0.4.0 → devague-0.4.1}/.claude/skills/run-tests/SKILL.md +0 -0
  34. {devague-0.4.0 → devague-0.4.1}/.claude/skills/run-tests/scripts/test.sh +0 -0
  35. {devague-0.4.0 → devague-0.4.1}/.claude/skills/sonarclaude/SKILL.md +0 -0
  36. {devague-0.4.0 → devague-0.4.1}/.claude/skills/sonarclaude/scripts/sonar.sh +0 -0
  37. {devague-0.4.0 → devague-0.4.1}/.claude/skills/spec-to-plan/SKILL.md +0 -0
  38. {devague-0.4.0 → devague-0.4.1}/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh +0 -0
  39. {devague-0.4.0 → devague-0.4.1}/.claude/skills/think/scripts/think.sh +0 -0
  40. {devague-0.4.0 → devague-0.4.1}/.claude/skills/version-bump/SKILL.md +0 -0
  41. {devague-0.4.0 → devague-0.4.1}/.claude/skills/version-bump/scripts/bump.py +0 -0
  42. {devague-0.4.0 → devague-0.4.1}/.claude/skills.local.yaml.example +0 -0
  43. {devague-0.4.0 → devague-0.4.1}/.flake8 +0 -0
  44. {devague-0.4.0 → devague-0.4.1}/.github/workflows/publish.yml +0 -0
  45. {devague-0.4.0 → devague-0.4.1}/.github/workflows/security-checks.yml +0 -0
  46. {devague-0.4.0 → devague-0.4.1}/.github/workflows/tests.yml +0 -0
  47. {devague-0.4.0 → devague-0.4.1}/.gitignore +0 -0
  48. {devague-0.4.0 → devague-0.4.1}/.markdownlint-cli2.yaml +0 -0
  49. {devague-0.4.0 → devague-0.4.1}/.pre-commit-config.yaml +0 -0
  50. {devague-0.4.0 → devague-0.4.1}/CLAUDE.md +0 -0
  51. {devague-0.4.0 → devague-0.4.1}/LICENSE +0 -0
  52. {devague-0.4.0 → devague-0.4.1}/README.md +0 -0
  53. {devague-0.4.0 → devague-0.4.1}/culture.yaml +0 -0
  54. {devague-0.4.0 → devague-0.4.1}/devague/__init__.py +0 -0
  55. {devague-0.4.0 → devague-0.4.1}/devague/__main__.py +0 -0
  56. {devague-0.4.0 → devague-0.4.1}/devague/cli/__init__.py +0 -0
  57. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/__init__.py +0 -0
  58. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/capture.py +0 -0
  59. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/confirm.py +0 -0
  60. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/converge.py +0 -0
  61. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/explain.py +0 -0
  62. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/export.py +0 -0
  63. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/interrogate.py +0 -0
  64. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/learn.py +0 -0
  65. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/list_frames.py +0 -0
  66. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/new.py +0 -0
  67. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/park.py +0 -0
  68. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/plan.py +0 -0
  69. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/reject.py +0 -0
  70. {devague-0.4.0 → devague-0.4.1}/devague/cli/_commands/show.py +0 -0
  71. {devague-0.4.0 → devague-0.4.1}/devague/cli/_errors.py +0 -0
  72. {devague-0.4.0 → devague-0.4.1}/devague/cli/_frames.py +0 -0
  73. {devague-0.4.0 → devague-0.4.1}/devague/cli/_output.py +0 -0
  74. {devague-0.4.0 → devague-0.4.1}/devague/cli/_plans.py +0 -0
  75. {devague-0.4.0 → devague-0.4.1}/devague/convergence.py +0 -0
  76. {devague-0.4.0 → devague-0.4.1}/devague/frame.py +0 -0
  77. {devague-0.4.0 → devague-0.4.1}/devague/plan.py +0 -0
  78. {devague-0.4.0 → devague-0.4.1}/devague/plan_convergence.py +0 -0
  79. {devague-0.4.0 → devague-0.4.1}/devague/plan_store.py +0 -0
  80. {devague-0.4.0 → devague-0.4.1}/devague/render/__init__.py +0 -0
  81. {devague-0.4.0 → devague-0.4.1}/devague/store.py +0 -0
  82. {devague-0.4.0 → devague-0.4.1}/docs/skill-sources.md +0 -0
  83. {devague-0.4.0 → devague-0.4.1}/docs/superpowers/plans/2026-05-22-specifix-onboarding.md +0 -0
  84. {devague-0.4.0 → devague-0.4.1}/docs/superpowers/plans/2026-05-23-devague-rename.md +0 -0
  85. {devague-0.4.0 → devague-0.4.1}/docs/superpowers/plans/2026-05-23-devague-working-backwards-engine.md +0 -0
  86. {devague-0.4.0 → devague-0.4.1}/docs/superpowers/specs/2026-05-22-specifix-onboarding-design.md +0 -0
  87. {devague-0.4.0 → devague-0.4.1}/docs/superpowers/specs/2026-05-23-devague-spec-to-plan-design.md +0 -0
  88. {devague-0.4.0 → devague-0.4.1}/docs/superpowers/specs/2026-05-23-devague-working-backwards-design.md +0 -0
  89. {devague-0.4.0 → devague-0.4.1}/sonar-project.properties +0 -0
  90. {devague-0.4.0 → devague-0.4.1}/tests/__init__.py +0 -0
  91. {devague-0.4.0 → devague-0.4.1}/tests/test_cli_affordances.py +0 -0
  92. {devague-0.4.0 → devague-0.4.1}/tests/test_cli_chassis.py +0 -0
  93. {devague-0.4.0 → devague-0.4.1}/tests/test_cli_converge_export.py +0 -0
  94. {devague-0.4.0 → devague-0.4.1}/tests/test_cli_errors.py +0 -0
  95. {devague-0.4.0 → devague-0.4.1}/tests/test_cli_moves.py +0 -0
  96. {devague-0.4.0 → devague-0.4.1}/tests/test_cli_output.py +0 -0
  97. {devague-0.4.0 → devague-0.4.1}/tests/test_convergence.py +0 -0
  98. {devague-0.4.0 → devague-0.4.1}/tests/test_frame.py +0 -0
  99. {devague-0.4.0 → devague-0.4.1}/tests/test_package.py +0 -0
  100. {devague-0.4.0 → devague-0.4.1}/tests/test_plan.py +0 -0
  101. {devague-0.4.0 → devague-0.4.1}/tests/test_plan_convergence.py +0 -0
  102. {devague-0.4.0 → devague-0.4.1}/tests/test_plan_store.py +0 -0
  103. {devague-0.4.0 → devague-0.4.1}/tests/test_spec_to_plan_skill.py +0 -0
  104. {devague-0.4.0 → devague-0.4.1}/tests/test_store.py +0 -0
  105. {devague-0.4.0 → devague-0.4.1}/tests/test_think_skill.py +0 -0
@@ -155,10 +155,28 @@ d converge # gate; resolve any listed gaps
155
155
  d export # writes docs/specs/<slug>.md once converged
156
156
  ```
157
157
 
158
- The exported spec-md is a buildable artifact. The next leg is the sibling
159
- **`/spec-to-plan`** skill: `devague plan new --frame <slug>` seeds a plan from the
160
- converged frame and works it forward into a buildable plan (it can equally feed
161
- `superpowers:writing-plans` or a normal implementation PR).
158
+ The exported spec-md is a buildable artifact.
159
+
160
+ ## After export commit, then hand off
161
+
162
+ Once `export` writes the spec **and the user has reviewed it**, close the
163
+ idea→spec leg cleanly before moving on:
164
+
165
+ 1. **Commit the spec.** Commit the exported `docs/specs/<slug>.md` (along with
166
+ the `.devague/<slug>.json` frame state and any review artifact under
167
+ `docs/reviews/`) so the converged frame is durable in history, not just on
168
+ disk. Use a focused message, e.g. `git commit -m "spec: <slug> (devague
169
+ /think)"`. The frame and the spec are the evidence trail for every confirmed
170
+ claim — keep them together. (Per the repo's standing convention this normally
171
+ becomes a branch + PR via the `cicd` skill; commit-only is fine when the user
172
+ asks for it.)
173
+ 2. **Hand off to `/spec-to-plan`.** The forward leg is the sibling skill:
174
+ `devague plan new --frame <slug>` seeds a plan from the converged frame and
175
+ works it forward into a buildable plan (it can equally feed
176
+ `superpowers:writing-plans` or a normal implementation PR).
177
+
178
+ Don't pause for a "what next?" menu after a reviewed export — the standing flow
179
+ is **commit, then `/spec-to-plan`**.
162
180
 
163
181
  ## Provenance
164
182
 
@@ -0,0 +1 @@
1
+ devague-now-ships-a-documented-spec-contract-every
@@ -0,0 +1,263 @@
1
+ {
2
+ "slug": "devague-now-ships-a-documented-spec-contract-every",
3
+ "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",
4
+ "status": "exported",
5
+ "created": "2026-05-23T08:08:13Z",
6
+ "updated": "2026-05-23T09:17:12Z",
7
+ "claims": [
8
+ {
9
+ "id": "c1",
10
+ "kind": "announcement",
11
+ "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",
12
+ "origin": "user",
13
+ "status": "confirmed",
14
+ "honesty_conditions": [
15
+ {
16
+ "id": "h1",
17
+ "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",
18
+ "status": "confirmed"
19
+ }
20
+ ],
21
+ "hard_questions": [],
22
+ "links": []
23
+ },
24
+ {
25
+ "id": "c2",
26
+ "kind": "audience",
27
+ "text": "Devague and the assisting LLM that drives it \u2014 they coordinate around structured feature-framing state without a rigid wizard",
28
+ "origin": "user",
29
+ "status": "confirmed",
30
+ "honesty_conditions": [
31
+ {
32
+ "id": "h2",
33
+ "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",
34
+ "status": "confirmed"
35
+ }
36
+ ],
37
+ "hard_questions": [],
38
+ "links": []
39
+ },
40
+ {
41
+ "id": "c3",
42
+ "kind": "after_state",
43
+ "text": "A vague idea becomes a claim-based, pressure-tested, buildable spec held in a durable, reloadable artifact whose entities are validated",
44
+ "origin": "user",
45
+ "status": "confirmed",
46
+ "honesty_conditions": [
47
+ {
48
+ "id": "h3",
49
+ "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)",
50
+ "status": "confirmed"
51
+ }
52
+ ],
53
+ "hard_questions": [],
54
+ "links": []
55
+ },
56
+ {
57
+ "id": "c4",
58
+ "kind": "before_state",
59
+ "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",
60
+ "origin": "user",
61
+ "status": "confirmed",
62
+ "honesty_conditions": [
63
+ {
64
+ "id": "h4",
65
+ "text": "The contract is enforced by validation on load: a schema-violating frame is rejected with a clear, actionable error rather than silently accepted",
66
+ "status": "confirmed"
67
+ }
68
+ ],
69
+ "hard_questions": [],
70
+ "links": []
71
+ },
72
+ {
73
+ "id": "c5",
74
+ "kind": "why_it_matters",
75
+ "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",
76
+ "origin": "user",
77
+ "status": "confirmed",
78
+ "honesty_conditions": [
79
+ {
80
+ "id": "h5",
81
+ "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",
82
+ "status": "confirmed"
83
+ }
84
+ ],
85
+ "hard_questions": [],
86
+ "links": []
87
+ },
88
+ {
89
+ "id": "c6",
90
+ "kind": "boundary",
91
+ "text": "Not a full PRD generator and not a fixed wizard; the move-driven, deterministic model stays",
92
+ "origin": "user",
93
+ "status": "confirmed",
94
+ "honesty_conditions": [
95
+ {
96
+ "id": "h6",
97
+ "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",
98
+ "status": "confirmed"
99
+ }
100
+ ],
101
+ "hard_questions": [],
102
+ "links": []
103
+ },
104
+ {
105
+ "id": "c7",
106
+ "kind": "boundary",
107
+ "text": "The local contract requires no GitHub, agents, or external services",
108
+ "origin": "user",
109
+ "status": "confirmed",
110
+ "honesty_conditions": [
111
+ {
112
+ "id": "h7",
113
+ "text": "Every contract operation (create / load / mutate / show / converge / export) runs fully offline against local .devague/ state with zero network calls",
114
+ "status": "confirmed"
115
+ }
116
+ ],
117
+ "hard_questions": [],
118
+ "links": []
119
+ },
120
+ {
121
+ "id": "c8",
122
+ "kind": "boundary",
123
+ "text": "Convergence is never claimed on vibes, and LLM-proposed content is never silently promoted to confirmed truth",
124
+ "origin": "user",
125
+ "status": "confirmed",
126
+ "honesty_conditions": [
127
+ {
128
+ "id": "h8",
129
+ "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",
130
+ "status": "confirmed"
131
+ }
132
+ ],
133
+ "hard_questions": [],
134
+ "links": []
135
+ },
136
+ {
137
+ "id": "c9",
138
+ "kind": "success_signal",
139
+ "text": "converge returns a structured result (ready_for_spec, blockers, warnings, parked_items, required_next_moves) with blockers instead of prose-only advice",
140
+ "origin": "user",
141
+ "status": "confirmed",
142
+ "honesty_conditions": [
143
+ {
144
+ "id": "h9",
145
+ "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",
146
+ "status": "confirmed"
147
+ }
148
+ ],
149
+ "hard_questions": [],
150
+ "links": []
151
+ },
152
+ {
153
+ "id": "c10",
154
+ "kind": "success_signal",
155
+ "text": "A documented spec contract exists in the repo, with worked contract examples for at least one feature frame",
156
+ "origin": "user",
157
+ "status": "confirmed",
158
+ "honesty_conditions": [
159
+ {
160
+ "id": "h10",
161
+ "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",
162
+ "status": "confirmed"
163
+ }
164
+ ],
165
+ "hard_questions": [],
166
+ "links": []
167
+ },
168
+ {
169
+ "id": "c11",
170
+ "kind": "success_signal",
171
+ "text": "The CLI can create, load, mutate, and display a frame locally; core entities are validated",
172
+ "origin": "user",
173
+ "status": "confirmed",
174
+ "honesty_conditions": [
175
+ {
176
+ "id": "h11",
177
+ "text": "create / load / mutate / show round-trip through the JSON store under validation, and the demonstrated operations are covered by passing tests",
178
+ "status": "confirmed"
179
+ }
180
+ ],
181
+ "hard_questions": [],
182
+ "links": []
183
+ },
184
+ {
185
+ "id": "c12",
186
+ "kind": "success_signal",
187
+ "text": "Tests cover claim provenance, honesty-condition confirmation, parking vagueness, and convergence failure",
188
+ "origin": "user",
189
+ "status": "confirmed",
190
+ "honesty_conditions": [
191
+ {
192
+ "id": "h12",
193
+ "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",
194
+ "status": "confirmed"
195
+ }
196
+ ],
197
+ "hard_questions": [],
198
+ "links": []
199
+ },
200
+ {
201
+ "id": "c13",
202
+ "kind": "boundary",
203
+ "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",
204
+ "origin": "user",
205
+ "status": "confirmed",
206
+ "honesty_conditions": [
207
+ {
208
+ "id": "h13",
209
+ "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",
210
+ "status": "confirmed"
211
+ }
212
+ ],
213
+ "hard_questions": [],
214
+ "links": []
215
+ },
216
+ {
217
+ "id": "c14",
218
+ "kind": "success_signal",
219
+ "text": "The claim-type vocabulary adds non_goal, requirement, assumption, and decision to the shipped set, each with a documented convergence-gate impact",
220
+ "origin": "user",
221
+ "status": "confirmed",
222
+ "honesty_conditions": [
223
+ {
224
+ "id": "h14",
225
+ "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",
226
+ "status": "confirmed"
227
+ }
228
+ ],
229
+ "hard_questions": [],
230
+ "links": []
231
+ },
232
+ {
233
+ "id": "c15",
234
+ "kind": "success_signal",
235
+ "text": "Every frame carries a schema_version field; load validates by version so existing frames keep loading as the schema grows",
236
+ "origin": "user",
237
+ "status": "confirmed",
238
+ "honesty_conditions": [
239
+ {
240
+ "id": "h15",
241
+ "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",
242
+ "status": "confirmed"
243
+ }
244
+ ],
245
+ "hard_questions": [],
246
+ "links": []
247
+ }
248
+ ],
249
+ "open_vagueness": [
250
+ {
251
+ "id": "v1",
252
+ "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",
253
+ "kind": "follow_up",
254
+ "claim_id": null
255
+ },
256
+ {
257
+ "id": "v2",
258
+ "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",
259
+ "kind": "follow_up",
260
+ "claim_id": null
261
+ }
262
+ ]
263
+ }
@@ -0,0 +1,363 @@
1
+ {
2
+ "slug": "devague-now-ships-a-documented-spec-contract-every",
3
+ "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",
4
+ "frame_slug": "devague-now-ships-a-documented-spec-contract-every",
5
+ "status": "exported",
6
+ "created": "2026-05-23T08:33:18Z",
7
+ "updated": "2026-05-23T09:17:12Z",
8
+ "targets": [
9
+ {
10
+ "id": "c1",
11
+ "kind": "announcement",
12
+ "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"
13
+ },
14
+ {
15
+ "id": "h1",
16
+ "kind": "honesty",
17
+ "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"
18
+ },
19
+ {
20
+ "id": "c2",
21
+ "kind": "audience",
22
+ "text": "Devague and the assisting LLM that drives it \u2014 they coordinate around structured feature-framing state without a rigid wizard"
23
+ },
24
+ {
25
+ "id": "h2",
26
+ "kind": "honesty",
27
+ "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"
28
+ },
29
+ {
30
+ "id": "c3",
31
+ "kind": "after_state",
32
+ "text": "A vague idea becomes a claim-based, pressure-tested, buildable spec held in a durable, reloadable artifact whose entities are validated"
33
+ },
34
+ {
35
+ "id": "h3",
36
+ "kind": "honesty",
37
+ "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)"
38
+ },
39
+ {
40
+ "id": "c4",
41
+ "kind": "before_state",
42
+ "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"
43
+ },
44
+ {
45
+ "id": "h4",
46
+ "kind": "honesty",
47
+ "text": "The contract is enforced by validation on load: a schema-violating frame is rejected with a clear, actionable error rather than silently accepted"
48
+ },
49
+ {
50
+ "id": "c5",
51
+ "kind": "why_it_matters",
52
+ "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"
53
+ },
54
+ {
55
+ "id": "h5",
56
+ "kind": "honesty",
57
+ "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"
58
+ },
59
+ {
60
+ "id": "c6",
61
+ "kind": "boundary",
62
+ "text": "Not a full PRD generator and not a fixed wizard; the move-driven, deterministic model stays"
63
+ },
64
+ {
65
+ "id": "h6",
66
+ "kind": "honesty",
67
+ "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"
68
+ },
69
+ {
70
+ "id": "c7",
71
+ "kind": "boundary",
72
+ "text": "The local contract requires no GitHub, agents, or external services"
73
+ },
74
+ {
75
+ "id": "h7",
76
+ "kind": "honesty",
77
+ "text": "Every contract operation (create / load / mutate / show / converge / export) runs fully offline against local .devague/ state with zero network calls"
78
+ },
79
+ {
80
+ "id": "c8",
81
+ "kind": "boundary",
82
+ "text": "Convergence is never claimed on vibes, and LLM-proposed content is never silently promoted to confirmed truth"
83
+ },
84
+ {
85
+ "id": "h8",
86
+ "kind": "honesty",
87
+ "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"
88
+ },
89
+ {
90
+ "id": "c9",
91
+ "kind": "success_signal",
92
+ "text": "converge returns a structured result (ready_for_spec, blockers, warnings, parked_items, required_next_moves) with blockers instead of prose-only advice"
93
+ },
94
+ {
95
+ "id": "h9",
96
+ "kind": "honesty",
97
+ "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"
98
+ },
99
+ {
100
+ "id": "c10",
101
+ "kind": "success_signal",
102
+ "text": "A documented spec contract exists in the repo, with worked contract examples for at least one feature frame"
103
+ },
104
+ {
105
+ "id": "h10",
106
+ "kind": "honesty",
107
+ "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"
108
+ },
109
+ {
110
+ "id": "c11",
111
+ "kind": "success_signal",
112
+ "text": "The CLI can create, load, mutate, and display a frame locally; core entities are validated"
113
+ },
114
+ {
115
+ "id": "h11",
116
+ "kind": "honesty",
117
+ "text": "create / load / mutate / show round-trip through the JSON store under validation, and the demonstrated operations are covered by passing tests"
118
+ },
119
+ {
120
+ "id": "c12",
121
+ "kind": "success_signal",
122
+ "text": "Tests cover claim provenance, honesty-condition confirmation, parking vagueness, and convergence failure"
123
+ },
124
+ {
125
+ "id": "h12",
126
+ "kind": "honesty",
127
+ "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"
128
+ },
129
+ {
130
+ "id": "c13",
131
+ "kind": "boundary",
132
+ "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"
133
+ },
134
+ {
135
+ "id": "h13",
136
+ "kind": "honesty",
137
+ "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"
138
+ },
139
+ {
140
+ "id": "c14",
141
+ "kind": "success_signal",
142
+ "text": "The claim-type vocabulary adds non_goal, requirement, assumption, and decision to the shipped set, each with a documented convergence-gate impact"
143
+ },
144
+ {
145
+ "id": "h14",
146
+ "kind": "honesty",
147
+ "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"
148
+ },
149
+ {
150
+ "id": "c15",
151
+ "kind": "success_signal",
152
+ "text": "Every frame carries a schema_version field; load validates by version so existing frames keep loading as the schema grows"
153
+ },
154
+ {
155
+ "id": "h15",
156
+ "kind": "honesty",
157
+ "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"
158
+ }
159
+ ],
160
+ "tasks": [
161
+ {
162
+ "id": "t1",
163
+ "summary": "Define the contract entity model: add claim types non_goal/requirement/assumption/decision and a schema_version field",
164
+ "origin": "llm",
165
+ "status": "confirmed",
166
+ "acceptance_criteria": [
167
+ "CLAIM_KINDS gains non_goal, requirement, assumption, decision; Frame carries schema_version; dataclasses validate kind/state/origin against their enums"
168
+ ],
169
+ "deps": [],
170
+ "covers": [
171
+ "c13",
172
+ "c14",
173
+ "c15"
174
+ ]
175
+ },
176
+ {
177
+ "id": "t2",
178
+ "summary": "Implement schema_version write-on-save + validate-on-load with fail-closed versioning and lossless round-trip",
179
+ "origin": "llm",
180
+ "status": "confirmed",
181
+ "acceptance_criteria": [
182
+ "save writes schema_version; load rejects unknown/newer version with a clear error; save then load yields an identical frame including new types + schema_version; existing 0.4.0 frames still load"
183
+ ],
184
+ "deps": [
185
+ "t1"
186
+ ],
187
+ "covers": [
188
+ "h1",
189
+ "h4",
190
+ "h15"
191
+ ]
192
+ },
193
+ {
194
+ "id": "t3",
195
+ "summary": "Add load-time validation that rejects schema-violating frames with clear, actionable errors",
196
+ "origin": "llm",
197
+ "status": "confirmed",
198
+ "acceptance_criteria": [
199
+ "a malformed or enum-violating frame raises a DevagueError with an actionable message on load (no silent accept); create/load/mutate/show round-trip under validation"
200
+ ],
201
+ "deps": [
202
+ "t1"
203
+ ],
204
+ "covers": [
205
+ "c3",
206
+ "c11"
207
+ ]
208
+ },
209
+ {
210
+ "id": "t4",
211
+ "summary": "Replace converge output with the structured result (ready_for_spec, blockers, warnings, parked_items, required_next_moves) as a hard break",
212
+ "origin": "llm",
213
+ "status": "confirmed",
214
+ "acceptance_criteria": [
215
+ "converge --json emits only the new structured shape; ready_for_spec gates export; blockers block convergence and warnings do not; the gate is computed only from confirmed claims and conditions; required_next_moves is derived from blockers"
216
+ ],
217
+ "deps": [
218
+ "t1"
219
+ ],
220
+ "covers": [
221
+ "c9",
222
+ "h9",
223
+ "c5",
224
+ "h5"
225
+ ]
226
+ },
227
+ {
228
+ "id": "t5",
229
+ "summary": "Implement convergence-gate semantics for the new claim types",
230
+ "origin": "llm",
231
+ "status": "confirmed",
232
+ "acceptance_criteria": [
233
+ "requirement is spec-affecting (needs a confirmed honesty condition); non_goal and decision are descriptive (non-blocking); an unconfirmed assumption surfaces as a warning, not a blocker; each rule has a test"
234
+ ],
235
+ "deps": [
236
+ "t4"
237
+ ],
238
+ "covers": [
239
+ "c14",
240
+ "h14"
241
+ ]
242
+ },
243
+ {
244
+ "id": "t6",
245
+ "summary": "Update the /think and /spec-to-plan status helpers to consume the new structured converge payload",
246
+ "origin": "llm",
247
+ "status": "confirmed",
248
+ "acceptance_criteria": [
249
+ "both status helpers read ready_for_spec/blockers/warnings/required_next_moves and no longer depend on {passed, missing}; status output distinguishes blockers from warnings"
250
+ ],
251
+ "deps": [
252
+ "t4"
253
+ ],
254
+ "covers": [
255
+ "h9"
256
+ ]
257
+ },
258
+ {
259
+ "id": "t7",
260
+ "summary": "Give every move a documented JSON I/O contract (input, output, state transition, validation errors)",
261
+ "origin": "llm",
262
+ "status": "confirmed",
263
+ "acceptance_criteria": [
264
+ "each move supports --json with a documented input/output/state-transition/validation-error shape; the strict stdout/stderr split holds; an LLM can drive devague from JSON without guessing internal state"
265
+ ],
266
+ "deps": [],
267
+ "covers": [
268
+ "c2",
269
+ "h2"
270
+ ]
271
+ },
272
+ {
273
+ "id": "t8",
274
+ "summary": "Guarantee all contract operations run fully offline",
275
+ "origin": "llm",
276
+ "status": "confirmed",
277
+ "acceptance_criteria": [
278
+ "create/load/mutate/show/converge/export perform zero network calls; a test asserts no network or socket access"
279
+ ],
280
+ "deps": [],
281
+ "covers": [
282
+ "c7",
283
+ "h7"
284
+ ]
285
+ },
286
+ {
287
+ "id": "t9",
288
+ "summary": "Enforce and preserve anti-fabrication and the move-driven model",
289
+ "origin": "llm",
290
+ "status": "confirmed",
291
+ "acceptance_criteria": [
292
+ "claims/conditions with origin=llm persist as proposed; confirm is the only transition to confirmed; no code path auto-confirms; no fixed prompt sequence is added (the CLI stays a move-driven state tracker)"
293
+ ],
294
+ "deps": [],
295
+ "covers": [
296
+ "c8",
297
+ "h8",
298
+ "c6",
299
+ "h6"
300
+ ]
301
+ },
302
+ {
303
+ "id": "t10",
304
+ "summary": "Write the documented spec contract with a worked, round-trippable frame example",
305
+ "origin": "llm",
306
+ "status": "confirmed",
307
+ "acceptance_criteria": [
308
+ "a committed contract doc is the source of truth for kinds/states/fields/transitions and per-move I/O; it documents the shipped (state x origin) vocabulary and maps the issue's proposed names onto it; it states the current 0.4.0 reality (passed/missing, no prior doc); it includes at least one worked frame example the CLI round-trips"
309
+ ],
310
+ "deps": [
311
+ "t1",
312
+ "t2",
313
+ "t4",
314
+ "t7"
315
+ ],
316
+ "covers": [
317
+ "c1",
318
+ "c4",
319
+ "h3",
320
+ "c10",
321
+ "h10",
322
+ "h13"
323
+ ]
324
+ },
325
+ {
326
+ "id": "t11",
327
+ "summary": "Add the contract test suite",
328
+ "origin": "llm",
329
+ "status": "confirmed",
330
+ "acceptance_criteria": [
331
+ "tests cover claim provenance, honesty-condition confirmation, parking vagueness, and convergence failure; plus lossless round-trip, multi-version load, and the structured-result fields; all green in CI"
332
+ ],
333
+ "deps": [
334
+ "t1",
335
+ "t2",
336
+ "t3",
337
+ "t4",
338
+ "t5",
339
+ "t9"
340
+ ],
341
+ "covers": [
342
+ "c11",
343
+ "h11",
344
+ "c12",
345
+ "h12"
346
+ ]
347
+ }
348
+ ],
349
+ "risks": [
350
+ {
351
+ "id": "r1",
352
+ "text": "Whether to also ship a formal machine-readable JSON Schema file alongside the dataclasses (frame follow-up v1) \u2014 affects the doc scope in t10",
353
+ "kind": "unknown_nonblocking",
354
+ "task_id": null
355
+ },
356
+ {
357
+ "id": "r2",
358
+ "text": "Whether requirement-type claims should carry acceptance criteria like plan tasks (frame follow-up v2) \u2014 overlaps the spec-to-plan leg",
359
+ "kind": "unknown_nonblocking",
360
+ "task_id": null
361
+ }
362
+ ]
363
+ }