@jabworks/condux 0.15.1 → 0.17.0

package/agents/planner.md

@@ -19,6 +19,8 @@ Both can run in parallel if they don't depend on each other's output.
 
 For LARGE tasks (cross-cutting, unclear scope, multiple subsystems), `/discovery` should have already run before you are invoked — it produces the signed-off design you turn into an executable plan. That design is a saved artifact: glob `.condux/designs/*<slug>*.md` (and `specs/<slug>/` for a tech-spec) and **read it first** — it is your source of truth for scope, chosen approach, and out-of-scope items. Do not re-derive or second-guess design decisions already settled there; if the file is missing for a large task, ask whether discovery has run rather than filling in the design yourself.
 
+**Check its `status` before trusting it.** Discovery creates the design file at its first section, not at sign-off, so finding the file does not mean the design was approved. Read the frontmatter: `signed-off` (or no `status` field at all, which means the file predates the field and was therefore saved at sign-off) means the design is settled and the paragraph above applies in full. `in-progress` means discovery started and did not finish — stop and ask whether to resume discovery, and do not plan from it. An unfinished design is the one case where the file is present and still must not be treated as source of truth.
+
 ## Task Size Classification
 
 - **Large (3+ files OR any architectural change)**: ask up to 3 impact-prioritized clarifying questions in one message, then delegate to `explorer`/`researcher`, then produce the full plan with ADR.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.15.1",
+  "version": "0.17.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/blueprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: blueprint
-description: "Produce dependency-free visual clarity artifacts at design time — HTML wireframes and full renders for UI screens and flows in the house design language (surface-kit tokens), and inline-SVG system diagrams (data models, flows, architecture, state machines) for backend work. During /discovery when the feature has a UI surface or a data model, from /draft-plan task cards, or standalone on \"mock this up\", \"wireframe this screen\", \"visualize the data model\", \"sketch the architecture\", \"diagram the flow\". Not for aesthetic or brand direction, editable design canvases or Figma, charts from real data, or generating code from a mockup."
+description: "Produce dependency-free visual clarity artifacts at design time — HTML wireframes and full renders for UI screens and flows in the house design language (surface-kit tokens), and inline-SVG system diagrams (data models, flows, architecture, state machines) for backend work. During /discovery when a section turns on what entities exist, what happens in what order, what talks to what, what states are legal, or what goes where on a screen; from /draft-plan task cards; or standalone on \"mock this up\", \"wireframe this screen\", \"visualize the data model\", \"sketch the architecture\", \"diagram the flow\". Not for aesthetic or brand direction, editable design canvases or Figma, charts from real data, or generating code from a mockup."
 argument-hint: "[surface or model to visualize — optional; defaults to the current design context]"
 ---
 
@@ -26,12 +26,13 @@ product family.
 ┌──────────────────────────────────────────────────────────────────┐
 │                         BLUEPRINT                                │
 ├──────────────────────────────────────────────────────────────────┤
-│  Step 1: ASSESS SURFACES                                         │
-│  What does the feature touch?                                    │
-│    - UI screens or flows        → wireframe family               │
-│    - Data models, services,     → diagram family                 │
-│      flows, state machines                                       │
-│    - Both                       → both families                  │
+│  Step 1: ASSESS THE QUESTION                                     │
+│  What is the reader trying to answer?                            │
+│    - What goes where on a screen → wireframe family              │
+│    - What exists / what happens  → diagram family                │
+│      / what talks to what /                                      │
+│      what states are legal                                       │
+│    - Two of these               → one artifact each              │
 │                                                                  │
 │  Step 2: PRODUCE                                                 │
 │  One self-contained HTML file per screen / flow state / diagram. │
@@ -42,9 +43,13 @@ product family.
 │  No external assets, no CDN, no font files.                      │
 │                                                                  │
 │  Step 3: DELIVER                                                 │
-│  Open in the browser (xdg-open / open). If neither works         │
-│  (headless, SSH), print the absolute paths and continue —        │
-│  never fail on delivery. Always state which mode was produced    │
+│  Standalone: open in the browser (xdg-open / open). If neither   │
+│  works (headless, SSH), print the absolute paths and continue —  │
+│  never fail on delivery.                                         │
+│  Inside /discovery: open NOTHING. Link the file from the design  │
+│  doc and let the running preview reload — see Inside the         │
+│  Workflow.                                                       │
+│  Either way, always state which mode was produced                │
 │  and offer the flip: "wireframe mode — say 'promote to render'   │
 │  for the full house look" (or the reverse). The mode is never    │
 │  chosen silently.                                                │
@@ -93,9 +98,26 @@ mockup into the spec directory first and cite the committed copy.
 
 ## Inside the Workflow
 
-- **/discovery** loads this skill at the propose step when the feature has a
-  UI surface or a data model — the mockups render the proposal, and the
-  signed-off design doc links the chosen ones. Side-by-side option *picking*
+- **/discovery** loads this skill at the propose step when a section's decision
+  turns on one of the five questions below — not when the feature "has" a UI
+  surface or a data model. That noun test has a blind spot: a design whose
+  subjects are, say, a terminal output shape and a markdown file contains
+  neither, and still needs a flow diagram. A question test has no such gap,
+  because the reader asks the question regardless of what the feature is made of.
+
+  | The question the section turns on | Shape |
+  |---|---|
+  | What entities exist and how do they relate? | entity / data-model |
+  | What happens, in what order, when X occurs? | request / data flow |
+  | What services exist and what talks to what? | architecture |
+  | What states are legal and what moves between them? | state machine |
+  | What goes where on a screen, and in what order does it read? | wireframe |
+
+  **Inside discovery, deliver by linking — never by opening.** The reader
+  already has the design preview open (discovery launches it at §1 and it
+  live-reloads on every write). Add the mockup's path to the design doc and the
+  link appears there. A tab per section is the interruption this avoids;
+  standalone invocations keep opening on deliver. Side-by-side option *picking*
   stays with discovery's own mockup-picker.
 - **/draft-plan** task cards may cite mockup paths so an implementer sees the
   visual target for their task.
@@ -111,5 +133,8 @@ mockup into the spec directory first and cite the committed copy.
 ✗ External dependencies — no Mermaid CDN, no image generation, no Figma
 ✗ Code generation from the mockup (that's implementation's job, later)
 ✗ Charts of real data (that's a dataviz concern, not a design mockup)
+✗ Labels generic enough to fit another feature — see the specificity rule in
+  both kits; a box the reader can't disagree with isn't evidence
+✗ Opening a browser tab while running inside /discovery
 ✗ Editing the mockups after design sign-off without saying so
 ```

package/skills/blueprint/evals/trigger_eval.json

@@ -48,13 +48,18 @@
     "query": "show me a wireframe of both options for the onboarding screen",
     "should_trigger": true,
     "expected_skill": "blueprint",
-    "accept": ["discovery"]
+    "accept": [
+      "discovery"
+    ]
   },
   {
     "query": "before planning, can we visualize what this feature will look like",
     "should_trigger": true,
     "expected_skill": "blueprint",
-    "accept": ["discovery", "workflow"]
+    "accept": [
+      "discovery",
+      "workflow"
+    ]
   },
   {
     "query": "mock up the ER diagram for the new billing tables",
@@ -82,19 +87,29 @@
     "query": "build the settings page from the approved design",
     "should_trigger": false,
     "expected_skill": null,
-    "accept": ["workflow"],
+    "accept": [
+      "workflow"
+    ],
     "note": "Building from an approved design is an implementation request; workflow's any-implementation-request claim covers it. The case still guards blueprint against the \"design\" bait."
   },
   {
     "query": "implement this Figma design as a React component",
     "should_trigger": false,
     "expected_skill": null,
-    "accept": ["workflow"],
+    "accept": [
+      "workflow"
+    ],
     "note": "Implementing a design in code is an implementation request; workflow covers it. The case still guards blueprint against the \"Figma design\" bait."
   },
   {
     "query": "pick a color palette and typography for the marketing site",
     "should_trigger": false,
     "expected_skill": null
+  },
+  {
+    "query": "sketch how the CLI, the cache file and the background daemon hand off to each other",
+    "should_trigger": true,
+    "expected_skill": "blueprint",
+    "note": "No UI surface and no data model — the old noun-shaped trigger could not see this. The section turns on \"what talks to what\", which is a blueprint question."
   }
 ]

package/skills/blueprint/references/diagram-kit.md

@@ -34,6 +34,29 @@ of the `<style>` block, verbatim.
 - Every relationship line gets a label. An unlabeled arrow is a guess the
   reader has to make.
 
+## The Specificity Rule
+
+Every label must name something real from *this* design — a path, a command, a
+field, a state, a status value, an endpoint. **If a label would be equally true
+of a different feature, it is too vague.**
+
+A diagram is evidence for a decision. A box the reader cannot disagree with
+carries no information, so it cannot be evidence — and "generic enough to fit
+any feature" is the single most common reason a produced artifact turns out not
+to help anyone.
+
+| Too vague | Specific |
+|---|---|
+| `Design Doc` | `.condux/designs/<date>-<slug>.md` |
+| `Preview` | `plan-review --steer` |
+| `Gate` | `signed-off → plan proceeds` |
+| `Status` | `status: in-progress` |
+| `saves` | `5. append agreed §` |
+
+The rule bites hardest early, when the specifics are not settled yet — which is
+the correct time for it to bite. A diagram drawn before there is anything
+concrete to put in it is decoration, and should not be drawn.
+
 ## 1. Entity / Data-Model
 
 One `<g>` per entity: title bar + field rows. Keys marked `PK` / `FK`; edge

package/skills/blueprint/references/wireframe-kit.md

@@ -58,6 +58,16 @@ mixes both signals.
 8. **Self-contained.** All CSS inline in a `<style>` block. No external
    requests of any kind. The file must render identically from `file://`.
    The token core carries dark and light themes; the page follows the OS.
+9. **Specific enough to disagree with.** Every label names something real from
+   *this* design — a route, a field, a state, a real CTA. If a label would be
+   equally true of a different feature, it is too vague: `Submit` on a form
+   whose button says "Save and invite", a nav reading `Item · Item · Item`, a
+   panel titled `Details`. This is rule 5 pushed one step further — rule 5 asks
+   for the intended text, this asks whether the intended text distinguishes
+   anything. A wireframe is evidence for a layout decision, and an element the
+   reader cannot disagree with is not evidence. It bites hardest before the
+   specifics are settled, which is exactly when a wireframe should not be
+   drawn yet. Same rule, same reasoning as `diagram-kit.md`.
 
 ## Page Skeleton
 

package/skills/discovery/SKILL.md

@@ -21,9 +21,15 @@ Before Step 1, check for an existing design: glob `.condux/designs/*<slug>*.md`
 and both spec scopes — `<package-root>/specs/<slug>/` and
 `<git-root>/specs/<slug>/`, the workflow router's two-scope lookup (slug =
 kebab-case of the feature name). If any
-exists, offer: "Found an existing design for this feature at `<path>` —
-resume from there, or start a fresh discovery?" Accept either answer, same
-as any other soft gate in this skill.
+exists, read its frontmatter `status` and offer accordingly:
+
+- `signed-off`, or no `status` field at all (the file predates the field, so
+  it was saved at sign-off): "Found a signed-off design for this feature at
+  `<path>` — resume from there, or start a fresh discovery?"
+- `in-progress`: "Found a discovery that stopped partway at `<path>`
+  (`<n>` sections agreed) — pick up where it left off, or start fresh?"
+
+Accept either answer, same as any other soft gate in this skill.
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
@@ -46,12 +52,15 @@ as any other soft gate in this skill.
 │  No implementation detail yet — that's Step 4's job.           │
 │                                                                  │
 │  Step 3: PROPOSE                                                │
-│  Present 2-3 approaches with tradeoffs.                        │
-│  Show design in sections — get acknowledgment per section      │
-│  before moving on.                                              │
-│  UI surface or data model involved? Load `blueprint` to        │
-│  render the proposal visually — wireframes and diagrams        │
-│  become part of what gets signed off.                           │
+│  Announce the section list, then create the design file        │
+│  (status: in-progress) and open the live preview.              │
+│  Present one section at a time in the card shape, get          │
+│  acknowledgment, append the agreed section to the file.        │
+│  §1 is approaches-and-tradeoffs; the rest follow the design.   │
+│  Full contract: The Section Card, below.                        │
+│  Does a section's decision turn on one of blueprint's five     │
+│  questions? Load `blueprint` — the artifact is linked from     │
+│  the design doc, not opened in a new tab.                       │
 │                                                                  │
 │  Step 4: DETAIL ROUND — feed the spec                           │
 │  With the approach chosen, ask ONE more batch, grouped by      │
@@ -79,13 +88,15 @@ as any other soft gate in this skill.
 │  Get explicit approval: "Looks good, proceed to planning"      │
 │  Do not proceed to /draft-plan without this.                    │
 │                                                                  │
-│  Step 7: SAVE DESIGN + SPEC (mandatory)                         │
-│  Write the design summary to                                    │
-│  .condux/designs/YYYY-MM-DD-<feature>.md — this is the         │
-│  artifact /draft-plan's gate check globs for.                   │
+│  Step 7: SIGN OFF THE FILE + SPEC (mandatory)                   │
+│  The design file already exists — Step 3 created it and        │
+│  every agreed section is in it. Flip its frontmatter            │
+│  status: in-progress → signed-off. That flip is what           │
+│  /draft-plan's gate check reads.                                │
 │  Spec write-back is default-on: persist the concern files       │
 │  too (Spec Integration below) unless the user opts out.         │
-│  Then offer the browser review loop (Design Review Loop).       │
+│  The preview is already running — reuse it (Design Review       │
+│  Loop); never launch a second server or open a second tab.      │
 └──────────────────────────────────────────────────────────────────┘
 ```
 
@@ -148,8 +159,105 @@ Accept either answer. Never block. Never lecture.
 ✗ Proceeding to planning without explicit sign-off
 ✗ Treating a well-defined ticket as needing full discovery
 ✗ Widening past the named target surface without saying so
+✗ A section card that runs past one screen, or a paragraph past three lines
+✗ Launching a second preview server, or opening a tab the user didn't ask for
+```
+
+## The Section Card (Step 3)
+
+Step 3 used to say "show design in sections" and stop, which left the shape to
+be reinvented every time — and what came out was prose. The shape is now fixed.
+
+**Before §1, announce the section list.** Name every section you intend to
+present, in order: *"4 sections: approach · section shape · blueprint trigger ·
+rollout."* Three lines, and the reader knows the shape of the conversation
+before they are inside it. Then create the design file and open the preview
+(next section), and begin.
+
+**Every card, same skeleton:**
+
+```
+## §n of N · <name>                    ← position, always
+<one line: what this section decides>
+
+<the evidence — table, list, or a linked artifact. Never a wall.>
+
+**Recommendation:** <X>, because <one sentence>.
+<the decision, as named options>
+```
+
+**Three rules underneath it:**
+
+| Rule | Why |
+|---|---|
+| The card fits one screen — about 25 lines. Overflow goes into the design file, and the card links it. | Without a number this is advice, not a contract, and advice is what produced the walls. |
+| No paragraph runs past three lines. Longer means it is a table or a list. | Prose is the failure mode. A table cannot sprawl. |
+| Rejected alternatives get one line each with a why-not; the full reasoning lives in the file. | Alternatives are why the recommendation can be trusted, and are also what bloats the card. |
+
+The per-section stops stay. They were never the problem — the problem was that
+the design existed only as scrollback, so the thread was lost between them. The
+`§n of N` marker and the live file are what hold it.
+
+**Visuals.** Load `blueprint` when a section's decision turns on one of its five
+questions — what entities exist · what happens in what order · what talks to
+what · what states are legal · what goes where on a screen. Inside discovery
+the artifact is *linked from the design doc*, never opened in its own tab: the
+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.
+
+```markdown
+---
+status: in-progress
+date: YYYY-MM-DD
+feature: <slug>
+---
+```
+
+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
+satisfy their gate**, which is what keeps an abandoned discovery from being
+planned against. (A file with no `status` field at all predates this contract
+and was only ever written at sign-off, so absence means `signed-off`.)
+
+**The preview runs from §1, by default.** Launch it with the design file, in
+manual mode — no `--steer`, which would block on a decision:
+
+```bash
+node /path/to/plan-review/references/annotate-server.js .condux/designs/<file>.md --no-reject
 ```
 
+Manual mode renders, watches the directory and live-reloads over SSE without
+blocking, so every appended section appears in the tab the reader already has
+open. It still accepts a submitted decision, which means **one server covers
+the whole of discovery** — launched at §1, still serving at sign-off. Never
+start a second one.
+
+Announce it and move on — do not ask first:
+
+> "Design preview running at http://127.0.0.1:7777 — it updates as we go. Say
+> the word if you'd rather I close it."
+
+The preview's purpose is to help make the *next* decision, so gating it behind
+an opt-in defeats what it is for; and discovery only runs on the LARGE tier, so
+there is no small case to protect from the ceremony. The default is visible and
+reversible, never silent.
+
+**Fail open.** No Node, no browser, headless, port taken — say so once in a
+single line and continue terminal-only. The design file is still written and
+still appended to; only the preview is missing. Never block discovery on it,
+and never retry in a loop. `--no-open` exists for the headless case.
+
+`.condux/` is gitignored working state, created on demand at the git root (see
+`/workflow` → Artifacts). The bootstrap check now happens at §1 rather than at
+sign-off — still ask only once.
+
 ## Output
 
 A short design summary covering:
@@ -162,51 +270,50 @@ A short design summary covering:
 Detail-round answers (Step 4) belong in the spec concern files, not the
 summary — the summary stays short; the spec carries the detail.
 
-Save to: `.condux/designs/YYYY-MM-DD-<feature>.md` — always, at sign-off
-(Step 7). The saved file is what `/draft-plan`'s gate check globs for; a
-design that lives only in conversation doesn't count as signed off.
+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
+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
+`in-progress`.
 
-`.condux/` is gitignored working state, created on demand at the git root
-(see `/workflow` → Artifacts). Before the first write, make sure it's
-ignored — see the bootstrap step there. Honour an `AGENTS.md` path override
-if the project defines one.
+Honour an `AGENTS.md` path override if the project defines one.
 
 For full design mockups — UI wireframes and renders in the house token
 language, data-model / flow / architecture diagrams — load the `blueprint`
-skill; the design doc links the files it produces. At sign-off, offer to
+skill; the design doc links the files it produces, and the running preview
+shows the link rather than a new tab opening. At sign-off, offer to
 promote the chosen wireframes to render mode (a style-block swap). For
 *picking between* side-by-side options in the browser, see
 `references/mockup-picker.md` (it can point at blueprint's files).
 
 ## Design Review Loop
 
-After saving, always offer — mirroring `/draft-plan`'s post-save review:
+At Step 7, after the status flip, always offer — mirroring `/draft-plan`'s
+post-save review:
 
-> "Design saved to `<path>`. Want to review it in the browser before we plan,
-> or go straight to /draft-plan?"
+> "Design signed off at `<path>`. Want a pass over it in the browser before we
+> plan, or go straight to /draft-plan?"
 
-**If review chosen:** locate `annotate-server.js` from the installed
-`plan-review` skill (`find ~/.claude ~/.codex ~/.agents -name
-annotate-server.js -path '*plan-review*' 2>/dev/null | head -1`) and launch
-it in `--steer` mode against the saved design file (or the spec directory,
-if the design was saved as a tech spec — see Spec Integration below):
+**The server is already running** — it has been since §1, and the reader has
+been watching the design accumulate in it. Do not launch another and do not
+open another tab. `--no-reject` is independent of `--steer`, so the design
+stage's **accept-or-fix** semantics (no Reject verdict — that belongs to plan
+review) are already in force from the §1 launch.
 
-```bash
-node /path/to/plan-review/references/annotate-server.js .condux/designs/<file>.md --steer --no-reject
-```
+**If a review pass is chosen:** point the reader at the tab they already have,
+ask them to annotate and submit a decision, and read the result — the submitted
+decision lands in the feedback file in manual mode rather than being long-polled:
 
-Poll `GET http://127.0.0.1:7777/api/decision` (long-poll — blocks until a
-decision is submitted) and branch on the result. Design review is
-**accept-or-fix** — `--no-reject` hides the Reject verdict, which belongs to
-plan review, not the design stage (directory/spec review hides it on its own;
-the flag matters for single-file design review):
+- **Approve** → proceed to `/draft-plan`, carrying any feedback notes into the plan.
+- **Request Revisions** → revise the design file in place per the feedback (the
+  open tab live-reloads over SSE), then ask again.
 
-- **Approve** → design is signed off; proceed to `/draft-plan`, carrying any
-  feedback notes into the plan.
-- **Request Revisions** → revise the design file in place per the feedback
-  (the open tab live-reloads over SSE), then poll again.
+**If the preview failed open at §1** (no Node, no browser, headless) there is no
+tab to point at. Say so in one line and go straight to planning; do not retry
+the launch here.
 
-**If straight to planning chosen:** proceed directly, no server launch.
+**If straight to planning chosen:** proceed directly.
 
 ## Spec Integration (Live Preview)
 

package/skills/draft-plan/SKILL.md

@@ -21,11 +21,27 @@ Turn a signed-off design into a clear, executable plan. Lean task cards, not mic
    `.condux/designs/*<slug>*.md` and both spec scopes —
    `<package-root>/specs/<slug>/` and `<git-root>/specs/<slug>/`, same
    two-scope lookup as the workflow router (slug = kebab-case of the
-   feature name) — for an existing signed-off design; if found,
-   treat this check as satisfied without asking. Otherwise ask: "We
+   feature name) — for an existing signed-off design; if found, **read
+   its `status`** (see below) and treat this check as satisfied without
+   asking only when it is `signed-off`. Otherwise ask: "We
    haven't aligned on the design yet — run /discovery first, or confirm
    you want to skip it."
 
+**Reading `status`.** Discovery creates the design file at its first
+section, not at sign-off, so the file existing no longer means the design
+was approved. Its frontmatter carries the answer:
+
+| `status` | Means | Gate |
+|---|---|---|
+| `signed-off` | discovery reached sign-off | satisfied |
+| `in-progress` | discovery started and did not finish | **not** satisfied — ask |
+| *absent* | written before this field existed | satisfied |
+
+A missing `status` means `signed-off`. Every design file written before
+this field existed was only ever saved at sign-off, so absence is a
+positive signal, not an unknown — reading it the other way retroactively
+invalidates every design already on disk.
+
 The plan is written as Markdown — optimized for AI agent consumption during
 execution. To read it in the browser, use `plan-review` (see After Saving);
 no separate HTML file is produced.

package/skills/plan-review/references/plan-review-template.html

@@ -1345,11 +1345,23 @@
       let DIRMODE=false, docs=[], activeDoc=null;
       const docState={}; // name -> { md, pane, scroll, key, headings }
 
+      // A design file carries its sign-off state in frontmatter, and renderBlocks
+      // maps a bare `---` to <hr> — so without this the reader sees a rule, a
+      // stray `status: …` paragraph and a second rule above every design. Only a
+      // block at position 0 counts; the `---` separators these documents use
+      // between sections must still render as horizontal rules. st.md keeps the
+      // raw text, because the revision diff and scanDocPaths both read it and a
+      // frontmatter-only change has to stay visible there.
+      function stripFrontmatter(md){
+        const m=/^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(md);
+        return m?md.slice(m[0].length):md;
+      }
+
       function renderDocPane(doc, md){
         const st=docState[doc];
         st.md=md; st.pane.innerHTML=''; st.headings=[];
         let section='(top)';
-        renderBlocks(md).forEach(function(b,idx){
+        renderBlocks(stripFrontmatter(md)).forEach(function(b,idx){
           const id=st.key+'-blk-'+idx;
           const wrap=document.createElement('div'); wrap.className='blk'; wrap.id=id; wrap.innerHTML=b.html;
           if(b.heading){ section=id; st.headings.push({id:id,level:b.heading.level,text:b.heading.text}); }

package/skills/subagent-execution/agents/planner.md

@@ -22,6 +22,8 @@ Both can run in parallel if they don't depend on each other's output.
 
 For LARGE tasks (cross-cutting, unclear scope, multiple subsystems), `/discovery` should have already run before you are invoked — it produces the signed-off design you turn into an executable plan. That design is a saved artifact: glob `.condux/designs/*<slug>*.md` (and `specs/<slug>/` for a tech-spec) and **read it first** — it is your source of truth for scope, chosen approach, and out-of-scope items. Do not re-derive or second-guess design decisions already settled there; if the file is missing for a large task, ask whether discovery has run rather than filling in the design yourself.
 
+**Check its `status` before trusting it.** Discovery creates the design file at its first section, not at sign-off, so finding the file does not mean the design was approved. Read the frontmatter: `signed-off` (or no `status` field at all, which means the file predates the field and was therefore saved at sign-off) means the design is settled and the paragraph above applies in full. `in-progress` means discovery started and did not finish — stop and ask whether to resume discovery, and do not plan from it. An unfinished design is the one case where the file is present and still must not be treated as source of truth.
+
 ## Task Size Classification
 
 - **Large (3+ files OR any architectural change)**: ask up to 3 impact-prioritized clarifying questions in one message, then delegate to `explorer`/`researcher`, then produce the full plan with ADR.

package/skills/technical-spec/SKILL.md

@@ -51,6 +51,15 @@ writing → run the scaffold script → write or update the concern files and
 `index.md` → offer the live HTML preview. Each step is specified in the
 sections below.
 
+**When `discovery` calls this at sign-off**, the design document already
+exists and has since the design's first section — discovery creates it at §1
+and appends to it as each section is agreed. So the input here is a finished
+file on disk, not a summary reconstructed from the conversation: read
+`.condux/designs/YYYY-MM-DD-<feature>.md` and map its sections into the
+concern files. Discovery's own preview server is already running against that
+file, so the live-preview offer below applies to the *spec directory* only —
+never start a second server for the design.
+
 ## Required Notifications
 
 Always announce and confirm before writing or editing. Never silently modify files.
@@ -86,8 +95,24 @@ Parse `commit`, `date`, and the **absolute spec path** from the output — use t
 
 Read [references/templates.md](references/templates.md) for the structure of each file.
 
+**The layering rule.** Every concern file opens with its summary table; the
+reasoning sits underneath; prose appears only where it earns its keep — the
+reasoning a future reader must be able to follow. Fill the table layer first:
+it is what a scanning human, `preflight`'s drift check, and an agent loading
+the spec all read, so write each row as a claim someone could check.
+
+**The two-homes rule.** A type in `api.md` says what each field *means* —
+trailing `//` per field, JSDoc only when a line won't do. `fields.md` says
+what *happens to it* — mapping and transformation only. One fact never lives
+in both places: a fact with two homes goes missing from the one being read.
+
+**Quirk headings are `## Q<n> — Title`.** The `Q<n>` anchors are a citation
+contract (`durable-citations.test.mjs` resolves them), so numbers are unique,
+ascending, and never renumbered.
+
 - Write only files that have real content
-- After writing, update the `## Contents` section in `index.md` with links to the files you created
+- After writing, update the `## Contents` table in `index.md` — one row per
+  file created, the `Answers` cell saying what a reader comes to it for
 - Replace the HTML comment the scaffold left below the title with a one-line
   `> …` note saying what the spec is for. That note is what `spec-browser`'s
   catalog shows for the spec; leave it and the spec is listed with nothing to
@@ -168,3 +193,5 @@ feedback file, if a decision is submitted).
 | Vague decisions | Each decision needs context + rationale + consequences |
 | Creating empty placeholder files | Only create a file when it has real content |
 | Forgetting to update index.md Contents | Always link to files you create |
+| Prose blob where the template has a table | Fill the table layer first; prose only for reasoning the table can't carry |
+| Bare interface with the field meanings in fields.md | Meaning goes on the type (`//` per field); fields.md carries only the journey |

package/skills/technical-spec/references/scaffold.sh

@@ -101,6 +101,11 @@ cat > "$SPEC_DIR/index.md" <<EOF
 
 ## Contents
 
+| File | Answers |
+|---|---|
+<!-- One row per concern file you actually create — link + what a reader
+     comes to it for. Files that don't exist get no row. -->
+
 ## Changelog
 - $DATE ($COMMIT): Initial spec
 EOF

package/skills/technical-spec/references/templates.md

@@ -2,6 +2,13 @@
 
 Copy-paste templates for each spec file. Omit sections that don't apply — don't leave empty headings.
 
+**The layering rule, which every template below follows:** a concern file opens
+with a scannable table and carries its reasoning underneath. The table serves
+the reader scanning for one thing, `preflight`'s drift check, and an agent
+loading the spec as context — all three read the same rows. Prose is reserved
+for the one job that needs it: reasoning a future reader must be able to
+follow. Write each table row as a claim someone could check, not a label.
+
 ---
 
 ## index.md
@@ -17,16 +24,20 @@ Copy-paste templates for each spec file. Omit sections that don't apply — don'
 **Status:** draft | review | stable
 
 ## Contents
-- [Decisions](decisions.md) — why we built it this way
-- [API](api.md) — contracts, endpoints, types
-- [Fields](fields.md) — field mappings: BE/3rd-party → UI
-- [Implementation](implementation.md) — how it works, key files
-- [Quirks](quirks.md) — edge cases and gotchas
+
+| File | Answers |
+|---|---|
+| [Decisions](decisions.md) | why it works this way, and what was rejected |
+| [Quirks](quirks.md) | what will bite you, and whether it is mitigated |
 
 ## Changelog
 - {YYYY-MM-DD} ({short-hash}): Initial spec
 ```
 
+The Contents table answers *which file do I open* — one row per concern file
+that actually exists, each `Answers` cell saying what a reader comes to it
+for. Files that don't exist get no row.
+
 **Cite committed paths only.** A spec is durable; the design and plan it came
 from are working state under `.condux/`, gitignored and gone on any other
 machine. If the changelog or body needs to point at a design or a verification
@@ -41,24 +52,35 @@ rule existed and two were already dead when they were found.
 ```markdown
 # Decisions — {Feature Name}
 
-## {Decision Title}
+| # | Decision | Because | Status |
+|---|---|---|---|
+| 1 | {what was decided, as a claim} | {why, one line} | accepted |
 
-**Date:** {YYYY-MM-DD}
-**Status:** accepted | superseded | deprecated
+## 1. {Decision Title} — {YYYY-MM-DD}
 
-### Context
-Why this decision needed to be made. What constraints or requirements drove it.
+**Decided:** one sentence, stated as a claim.
+**Because:** one sentence — why this option won.
 
-### Decision
-What was decided, stated clearly.
+| Alternative | Why not |
+|---|---|
+| {option considered} | {one line} |
 
-### Rationale
-Why this over the alternatives. Include alternatives considered and why they were rejected.
+**Consequences**
+- {what changes as a result — and where it costs, named}
 
-### Consequences
-What changes as a result — positive and negative trade-offs.
+**Context** *(only when the question's origin is not obvious)*
+{prose — why a decision was needed at all, when the feature doesn't make
+that self-evident}
 ```
 
+The summary table is mandatory and answers "which decisions exist" without
+reading the file. The alternatives table is mandatory too — an empty one is
+visible in a way missing prose is not, and a decision recorded without its
+rejected alternatives is assertion, not rationale. `Context` is the one
+conditional block: `Because` covers why *this* option won; `Context` covers
+why the question arose, which is frequently self-evident. Statuses:
+`accepted | superseded | deprecated`.
+
 ---
 
 ## api.md
@@ -75,9 +97,12 @@ What changes as a result — positive and negative trade-offs.
 ## Key Types / Schemas
 
 \`\`\`typescript
-interface ExampleType {
-  id: string;
-  // ...
+// The type says what a field MEANS; fields.md says what HAPPENS to it.
+interface Invoice {
+  id: string;               // Stripe invoice id, `in_`-prefixed
+  amountDue: number;        // minor units (cents) — never format directly
+  status: InvoiceStatus;    // drives the badge; `draft` is hidden in the list
+  voidedAt: string | null;  // ISO 8601; null unless voided
 }
 \`\`\`
 
@@ -88,6 +113,12 @@ interface ExampleType {
 | {Service} | {What we use it for} | {Rate limits, quirks} |
 ```
 
+**Every field carries its meaning inline** — trailing `//` by default; a JSDoc
+block only when a line won't do (units, constraints, nullability semantics).
+This is the two-homes rule: a fact with two homes goes missing from the one
+you are reading, and the un-annotated type is the home readers actually open.
+`fields.md` keeps only what a type cannot express — the journey.
+
 ---
 
 ## fields.md
@@ -95,18 +126,20 @@ interface ExampleType {
 ```markdown
 # Fields — {Feature Name}
 
-Document which fields flow from source (BE or 3rd-party API) to destination (UI or your BE),
-with descriptions so you can glance at the spec instead of traversing the codebase.
+Document which fields flow from source (BE or 3rd-party API) to destination
+(UI or your BE). The Description column is about the TRANSFORMATION — what
+happens to the field on the way — never about what the field means; meaning
+lives on the type in api.md.
 
 ## Response Fields — {Endpoint or Source Name}
 
 > Source: `GET /api/...` or `{ThirdParty} → BE → FE`
 
-| Source Field | UI Label / FE Key | Type | Nullable | Description |
+| Source Field | UI Label / FE Key | Type | Nullable | Transformation |
 |---|---|---|---|---|
-| `user_full_name` | Full Name | `string` | no | Display name shown in profile card |
-| `created_at` | Created | `string (ISO 8601)` | no | Formatted to `MMM D, YYYY` in UI |
-| `metadata.region` | Region | `string` | yes | Omitted from UI when null |
+| `user_full_name` | Full Name | `string` | no | rendered as-is in profile card |
+| `created_at` | Created | `string (ISO 8601)` | no | formatted to `MMM D, YYYY` in UI |
+| `metadata.region` | Region | `string` | yes | omitted from UI when null |
 
 ### Forwarding Chain (3rd-party → BE → FE)
 
@@ -121,10 +154,10 @@ Use this sub-section when your BE proxies a 3rd-party API and renames fields.
 
 > Sent from FE to `POST /api/...`
 
-| FE Key | BE Field | Type | Required | Description |
+| FE Key | BE Field | Type | Required | Transformation |
 |---|---|---|---|---|
-| `email` | `email` | `string` | yes | Validated client-side before send |
-| `preferredName` | `preferred_name` | `string` | no | Optional; omitted if empty |
+| `email` | `email` | `string` | yes | validated client-side before send |
+| `preferredName` | `preferred_name` | `string` | no | omitted from payload if empty |
 ```
 
 ---
@@ -134,25 +167,35 @@ Use this sub-section when your BE proxies a 3rd-party API and renames fields.
 ```markdown
 # Implementation — {Feature Name}
 
-## Overview
-One paragraph on how the feature works end-to-end.
-
-## Key Files
-
 | File | Role |
 |------|------|
 | `src/...` | ... |
 
-## Data Flow
-Step-by-step description of how data moves through the system.
+## Data flow
+
+1. {step} — {what happens}
+2. {step} — {what happens}
 
-## Patterns Used
-Non-obvious patterns, abstractions, or conventions introduced.
+## Patterns
+
+| Pattern | Where | Why not the obvious thing |
+|---|---|---|
+| {pattern used} | {file or layer} | {what it displaced, one line} |
 
 ## Dependencies
+
 Internal modules or external packages this feature leans on heavily.
+
+## Overview *(only when the file table does not already tell the story)*
+
+{prose — the end-to-end narrative, when the table and data flow leave it
+untold}
 ```
 
+Data flow is a numbered list — it is step-by-step by definition and was never
+prose. The Patterns table's third column is mandatory: a pattern recorded
+without the alternative it displaced is trivia, not guidance.
+
 ---
 
 ## quirks.md
@@ -160,10 +203,25 @@ Internal modules or external packages this feature leans on heavily.
 ```markdown
 # Quirks — {Feature Name}
 
-## {Quirk Title}
+| # | Quirk | Trigger | Severity | Mitigated |
+|---|---|---|---|---|
+| Q1 | {symptom, one line} | {what sets it off} | low / medium / high | yes / no / partial |
+
+## Q1 — {Quirk Title}
 
-**Severity:** low | medium | high
 **Discovered:** {date or commit}
 
-Description of the edge case, gotcha, or known issue. Include what triggers it and how it's handled or worked around.
+**Symptom:** what a reader will observe.
+**Trigger:** what sets it off.
+**Cause:** why it happens.
+**Mitigation:** what to do — or "none", said plainly.
+
+{prose — only the part that genuinely needs explaining}
 ```
+
+Quirk headings are `## Q<n> — Title`, always — `durable-citations.test.mjs`
+resolves every `Q<n>` a spec cites against these headings, so the format is a
+contract, not a style. Numbers are unique and ascending, never reused and
+never renumbered (citations from other specs may point at them). The
+`Mitigated` column is a checkable claim: `yes / no / partial`, with `partial`
+explained in the body's **Mitigation** field.