@jabworks/condux 0.17.2 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/discovery/SKILL.md

@@ -207,18 +207,16 @@ running preview reloads and shows the link, so the reader stays where they are.
 ## The Design File and the Live Preview (Step 3 onward)
 
 **The file is created at §1, not at sign-off.** Write
-`.condux/designs/YYYY-MM-DD-<feature>.md` with frontmatter
-`status: in-progress` when Step 3 opens, and append each section to it as it is
-agreed. This is the whole mechanism behind the card contract: the card can stay
-small precisely because the design has somewhere else to live.
+`.condux/designs/YYYY-MM-DD-<feature>.md` when Step 3 opens, and append each
+section to it as it is agreed. This is the whole mechanism behind the card
+contract: the card can stay small precisely because the design has somewhere
+else to live.
 
-```markdown
----
-status: in-progress
-date: YYYY-MM-DD
-feature: <slug>
----
-```
+**The file's shape lives in `references/design-template.md`** — the canonical
+home of the frontmatter contract (`status` / `date` / `feature`), the section
+set, and the lifecycle stamp saying when each part gets written. Copy its
+at-creation parts when the file is created; append each agreed section in its
+§-entry shape (the section card's presentation twin — same four facts).
 
 At Step 7, flip `status` to `signed-off`. `/draft-plan` and the `planner` agent
 both read that value; **a design file with `status: in-progress` does not
@@ -274,7 +272,8 @@ Detail-round answers (Step 4) belong in the spec concern files, not the
 summary — the summary stays short; the spec carries the detail.
 
 Lives at: `.condux/designs/YYYY-MM-DD-<feature>.md`, created at §1 and
-appended to per section (see The Design File and the Live Preview). Step 7
+appended to per section, in the shape of `references/design-template.md`
+(see The Design File and the Live Preview). Step 7
 does not write it — it flips its `status` to `signed-off`, and that flip is
 what `/draft-plan`'s gate check reads. A design that lives only in
 conversation doesn't count as signed off, and neither does one still marked

package/skills/discovery/references/design-template.md

@@ -0,0 +1,66 @@
+# Design Doc Template
+
+The shape of `.condux/designs/YYYY-MM-DD-<feature>.md`. This file is the
+canonical home of the design file's frontmatter contract and section set —
+SKILL.md points here rather than restating it.
+
+The template formalizes **accumulation**: the file is built by discovery's own
+flow, never restructured afterwards. Every part carries a lifecycle stamp
+saying when it gets written, so an agent mid-discovery always has a home for
+what it is holding. The mid-flow file and the sign-off file are one artifact
+with one shape.
+
+```markdown
+---
+status: in-progress        <!-- → signed-off at Step 7; /draft-plan's gate reads this -->
+date: YYYY-MM-DD
+feature: <slug>
+---
+
+# <feature> — <one line>                     [at creation]
+
+<what we're building and why — ≤3 lines>     [at creation]
+
+**Sections:** N — <names, in order>          [at creation]
+
+## §n · <name> — AGREED <date>               [appended per agreement]
+
+**Decided:** <the choice>, because <one line>.
+
+| Rejected | Why not |
+|---|---|
+| <alternative> | <one line> |
+
+<evidence — table, list, or a linked blueprint artifact. Never a wall.>
+
+## Constraints & out of scope                [accumulates — rows added any time]
+
+| Constraint / exclusion | Why |
+|---|---|
+| <rule or exclusion> | <one line> |
+
+## Open questions                            [finalized at sign-off; "none" is valid]
+
+- <question still open after sign-off, or "none">
+```
+
+## The rules
+
+| Rule | Why |
+|---|---|
+| Every agreed § carries the four facts a `decisions.md` entry carries — title+date, choice, alternatives with one-line why-nots, consequence | Step 7's spec write-back becomes transcription, not authorship; the design doc and `decisions.md` cannot disagree on shape because they share one |
+| Sections are appended as agreed, never drafted ahead | The file records the conversation's actual state; a pre-drafted section reads as agreed when it isn't |
+| Constraints discovered mid-flow go straight into their table | The section exists from creation precisely so mid-flow findings have a home other than an invented heading |
+| `status` flips to `signed-off` only at Step 7, and nothing else edits the frontmatter | `/draft-plan` and the `planner` agent gate on this value |
+
+## Lifecycle stamps, spelled out
+
+| Stamp | When written | Parts |
+|---|---|---|
+| `[at creation]` | Step 3 opens, before §1 is presented | frontmatter, title, why-line, section list |
+| `[appended per agreement]` | each section, at the moment it is agreed | the § entries |
+| `[accumulates]` | any time | `Constraints & out of scope` rows |
+| `[finalized at sign-off]` | Step 7 | `Open questions`, the `status` flip |
+
+A design file with no `status` field predates this contract and reads as
+`signed-off` — see SKILL.md's existing-design check.

package/skills/live-verification/SKILL.md

@@ -76,14 +76,22 @@ Order of checks, because this is where the defects were:
 
 One artifact per claim that has a visual or observable outcome — screenshot,
 response body, console excerpt. Store under
-`<git-root>/.condux/verification/<YYYY-MM-DD>-<slug>/` and reference the file
-in the report. Console errors and failed network requests seen along the way
+`<git-root>/.condux/verification/<YYYY-MM-DD>-<slug>/` — everything a run
+produces lives inside that dir, nothing at the verification root. Name each
+evidence file for the claim it supports and reference it from the report's
+claim table. Console errors and failed network requests seen along the way
 get reported even when they belong to another feature.
 
+Then write `report.md` into the same dir, in the shape of
+`references/report-template.md` — every run writes one, including runs where
+nothing could be driven (the template carries the fallback shape).
+
 ### Step 5 — Report and stop
 
-One pass. Fix what you found, re-verify only the claims that failed, then
-stop. This skill does not loop.
+The terminal report **is** `report.md`: print the file's content — never a
+second shape that can drift from the persisted one. One pass. Fix what you
+found, re-verify only the claims that failed, update `report.md` to match,
+then stop. This skill does not loop.
 
 ## Failure Handling
 
@@ -112,31 +120,13 @@ Two failed attempts on the same claim is the ceiling. Report and move on.
 
 ## Output Format
 
-```
-## Live verification: <change>
-
-Target     http://localhost:3000 (pnpm dev — started by this run)
-Themes     light ✓  dark ✓
-
-Claim                                          Evidence            Verdict
-Save disabled while mutation in flight         save-pending.png    ✓
-Failed save shows server message inline        save-error.png      ✓
-Escape closes dialog, focus returns to trigger —                   ✗ focus lands on body
-Empty list renders the empty state             empty-state.png     ✓
-
-Also seen: 2 console errors on mount (pre-existing, unrelated to this change)
-
-1 claim failed. Fixed focus return in dialog.tsx:44 — re-verified ✓
-```
-
-When nothing could be driven:
-
-```
-## Live verification: <change>
-
-Target     none — no dev/start/storybook script and nothing on the usual ports
-Verdict    NOT VERIFIED — 3 claims unchecked, listed below
-```
+The report shape — the fixed header table (Date / Target / Diff / Themes),
+the claim table (Claim | Evidence | Verdict), "Also seen", and the outcome
+line — lives in `references/report-template.md`, the canonical home. It also
+carries the fallback shape for when nothing could be driven; that run still
+writes `report.md`, because an absent report is indistinguishable from a run
+that never happened. Fixed header keys and a fixed claim-table shape are what
+make two runs of the same surface comparable.
 
 ## What Does NOT Happen
 

package/skills/live-verification/references/report-template.md

@@ -0,0 +1,54 @@
+# Verification Report Template
+
+The shape of `report.md` — one per run, at
+`<git-root>/.condux/verification/<YYYY-MM-DD>-<slug>/report.md`. This file is
+the canonical home of the report shape; SKILL.md's Output Format points here.
+
+The terminal report **is** this file: write `report.md` first, then print its
+content as the report. One fact, one home — a separate terminal shape and file
+shape would drift.
+
+```markdown
+# Live verification: <change>
+
+| | |
+|---|---|
+| Date | YYYY-MM-DD |
+| Target | <url or command> (<how it was started>) |
+| Diff | <branch or commit under test> |
+| Themes | light ✓ dark ✓ |
+
+| Claim | Evidence | Verdict |
+|---|---|---|
+| <behavior asserted, one line> | <file in this dir, or —> | ✓ / ✗ <what actually happened> |
+
+Also seen: <console errors, failed requests, off-feature breakage — or "nothing">
+
+<n> claims failed. <fix + re-verify note, or "all green">
+```
+
+When nothing could be driven, the report is still written — an absent
+`report.md` is indistinguishable from a run that never happened:
+
+```markdown
+# Live verification: <change>
+
+| | |
+|---|---|
+| Date | YYYY-MM-DD |
+| Target | none — <what was tried, what blocked it> |
+| Verdict | NOT VERIFIED — <n> claims unchecked, listed below |
+
+| Claim | Evidence | Verdict |
+|---|---|---|
+| <each enumerated claim> | — | unchecked |
+```
+
+## The rules
+
+| Rule | Why |
+|---|---|
+| Everything a run produces lives inside its run dir — nothing at the verification root | Root-level orphans belonging to no run were observed in the wild; the dir is the unit of a run |
+| Evidence files are named for the claim they support and referenced from the claim table | The table is the index — an evidence file it doesn't reference is uncontextualized in a week |
+| Header keys are fixed: Date, Target, Diff, Themes (Themes only for UI surfaces) | Two runs of the same surface are diffable only when their headers line up |
+| Every run writes `report.md`, including runs where nothing could be driven | Absence of a report must mean absence of a run, nothing else |