@jabworks/condux 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.19.0",
+  "version": "0.20.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

@@ -46,19 +46,19 @@ product family.
 │  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. Cite the file's path in the    │
-│  design doc as inline code and let the running preview reload —  │
-│  see Inside the Workflow.                                        │
+│  Inside /discovery: open NOTHING. Link the file from the design  │
+│  doc (label = href = its served-root-relative path) 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.                                                │
 │                                                                  │
-│  Step 4: CITE                                                    │
-│  Cite the files' paths (inline code, git-root-relative) in the   │
-│  design doc or task card that motivated them, so the visual      │
-│  target travels with the design. Never a clickable relative      │
-│  link — those 404 in the review preview.                         │
+│  Step 4: LINK                                                    │
+│  Link the files from the design doc or task card that motivated  │
+│  them — a markdown link whose href and label are the same        │
+│  served-root-relative path — so the visual target travels with   │
+│  the design and the click opens it in the review preview.        │
 └──────────────────────────────────────────────────────────────────┘
 ```
 
@@ -115,17 +115,18 @@ mockup into the spec directory first and cite the committed copy.
   | 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 citing — never by opening.** The reader
+  **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 git-root-relative path to the
-  design doc as inline code and the citation appears there; the reader opens
-  the file from the editor or filesystem. Never a clickable relative link —
-  the annotate server serves only the review page and `/api/*`, so relative
-  links 404 in the preview. And never an inlined copy of the diagram beside
-  the artifact: one fact, two homes is how the copies drift. 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.
+  live-reloads on every write). Add a markdown link whose href and label are
+  the same served-root-relative path — `[mockups/flow.html](mockups/flow.html)`
+  — and the link appears in the doc; the preview serves enumerated sibling
+  `.html`/`.svg` files script-dead, so clicking opens the artifact. An older
+  preview shows the path as the label and loses nothing. Never a
+  git-root-relative href (it cannot resolve against the served root), and
+  never an inlined copy of the diagram beside the artifact: one fact, two
+  homes is how the copies drift. 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.
 - Standalone asks ("mock this up", "visualize the data model") run the same

package/skills/discovery/SKILL.md

@@ -59,8 +59,9 @@ Accept either answer, same as any other soft gate in this skill.
 │  §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 path is cited      │
-│  in the design doc as inline code, not opened in a new tab.    │
+│  questions? Load `blueprint` — the artifact is linked from     │
+│  the design doc (label = href = the served-root-relative       │
+│  path), not opened in a new tab.                                │
 │                                                                  │
 │  Step 4: DETAIL ROUND — feed the spec                           │
 │  With the approach chosen, ask ONE more batch, grouped by      │
@@ -180,7 +181,7 @@ before they are inside it. Then create the design file and open the preview
 ## §n of N · <name>                    ← position, always
 <one line: what this section decides>
 
-<the evidence — table, list, or a cited artifact path. Never a wall.>
+<the evidence — table, list, or a linked artifact path. Never a wall.>
 
 **Recommendation:** <X>, because <one sentence>.
 <the decision, as named options>
@@ -201,12 +202,14 @@ the design existed only as scrollback, so the thread was lost between them. The
 **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's git-root-relative path is *cited in the design doc as inline
-code* (e.g. `.condux/designs/assets/checkout-flow.html`), never opened in its
-own tab and never written as a clickable relative link — the annotate server
-serves only the review page and `/api/*`, so a relative link 404s in the
-preview. The preview reloads and shows the citation; the reader opens the
-file from the editor or filesystem.
+the artifact is *linked from the design doc*, never opened in its own tab: a
+markdown link whose href and label are the same served-root-relative path —
+`[mockups/checkout-flow.html](mockups/checkout-flow.html)` — one string, no
+drift. The preview serves enumerated sibling `.html`/`.svg` files
+script-dead, so the click opens the artifact; an older preview simply shows
+the path as the label, and nothing degrades without a server. Never write a
+git-root-relative href (it cannot resolve against the served root), and
+never inline a copy of the diagram beside the artifact.
 
 ## The Design File and the Live Preview (Step 3 onward)
 
@@ -287,15 +290,16 @@ 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 cites the paths of the files it produces as inline
-code, and the running preview shows the citation rather than a new tab
-opening. At sign-off, offer to promote the chosen wireframes to render mode
-(a style-block swap). If the spec references a blueprint artifact, promote
-the file too: copy it into the spec directory and cite the committed path —
-a committed spec may never point into `.condux/`, which is gone on any other
-clone (workflow's citation-direction rule). For *picking between*
-side-by-side options in the browser, see `references/mockup-picker.md` (it
-can point at blueprint's files).
+skill; the design doc links the files it produces (served-root-relative
+markdown links, label = href), and the running preview serves the artifact
+on click rather than a new tab opening on deliver. At sign-off, offer to
+promote the chosen wireframes to render mode (a style-block swap). If the
+spec references a blueprint artifact, promote the file too: copy it into
+the spec directory and link the committed path — a committed spec may never
+point into `.condux/`, which is gone on any other clone (workflow's
+citation-direction rule). 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
 

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

@@ -31,7 +31,7 @@ feature: <slug>
 |---|---|
 | <alternative> | <one line> |
 
-<evidence — table, list, or a cited blueprint artifact path. Never a wall.>
+<evidence — table, list, or a linked blueprint artifact (served-root-relative, label = href). Never a wall.>
 
 ## Constraints & out of scope                [accumulates — rows added any time]
 

package/skills/plan-review/references/annotate-server.js

@@ -131,6 +131,35 @@ function readPlan(doc) {
   } catch (e) { return ''; }
 }
 
+// Artifact serving: sibling *.html / *.svg files (blueprint mockups and
+// diagrams), enumerated with the same walk rules as listDocs(). Membership in
+// this list is the only door — the request URL is never path-resolved, so
+// traversal shapes can't reach the filesystem. Stdin-mode plans live in
+// os.tmpdir() (see main), where a sibling walk would enumerate unrelated
+// files; artifact serving is off there.
+function artifactRoot() {
+  if (tmpPlanFile) return null;
+  return DIR_MODE ? planFile : path.dirname(planFile);
+}
+
+function listArtifacts() {
+  const root = artifactRoot();
+  if (!root) return [];
+  const out = [];
+  (function walk(rel) {
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, rel || '.'), { withFileTypes: true }); }
+    catch (e) { return; }
+    entries.forEach(function (e) {
+      if (e.name[0] === '.') return;
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) walk(r);
+      else if (/\.(html|svg)$/i.test(e.name) && !/\.feedback\./i.test(e.name)) out.push(r);
+    });
+  })('');
+  return out;
+}
+
 function watchPlan() {
   try {
     if (DIR_MODE) {
@@ -318,7 +347,13 @@ function handler(req, res) {
 
   if (req.method === 'GET' && p === '/') {
     res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-    return res.end(TEMPLATE.replace(/\{\{PLAN_NAME\}\}/g, escapeHtml(path.basename(planFile))));
+    return res.end(TEMPLATE
+      .replace(/\{\{PLAN_NAME\}\}/g, escapeHtml(path.basename(planFile)))
+      // Decision-bar affordance: manual mode defers the decision to a file the
+      // agent reads at its next checkpoint; every other mode (steer, hook,
+      // codex) has a live listener blocked on the decision, so only true
+      // manual may carry the deferred copy.
+      .replace(/\{\{MODE\}\}/g, CODEX_STOP_MODE ? 'codex' : HOOK_MODE ? 'hook' : STEER_MODE ? 'steer' : 'manual'));
   }
   if (req.method === 'GET' && p === '/api/plan') {
     res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
@@ -383,6 +418,23 @@ function handler(req, res) {
     });
     return;
   }
+  if (req.method === 'GET' && p !== '/' && p.indexOf('/api/') !== 0) {
+    // Enumerated artifacts only (see listArtifacts). Served script-dead:
+    // CSP sandbox gives the document an opaque origin and disables script
+    // execution, so an agent-authored artifact can never reach /api/*.
+    let rel = null;
+    try { rel = decodeURIComponent(p.slice(1)); } catch (e) { /* malformed → 404 */ }
+    if (rel && listArtifacts().indexOf(rel) >= 0) {
+      try {
+        const body = fs.readFileSync(path.join.apply(path, [artifactRoot()].concat(rel.split('/'))));
+        res.writeHead(200, {
+          'Content-Type': /\.svg$/i.test(rel) ? 'image/svg+xml' : 'text/html; charset=utf-8',
+          'Content-Security-Policy': 'sandbox',
+        });
+        return res.end(body);
+      } catch (e) { /* deleted between walk and read → 404 */ }
+    }
+  }
   res.writeHead(404);
   res.end();
 }

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

@@ -1648,14 +1648,21 @@
         });
         updateBadges(); updateSummary();
       }
+      // Server mode, injected at render. 'manual' = no live listener: the
+      // decision lands in the feedback file and the agent reads it at its next
+      // checkpoint. Anything else (steer, or an unreplaced literal from an
+      // older server) keeps the live-submission copy.
+      const SERVER_MODE='{{MODE}}';
+      const MANUAL=SERVER_MODE==='manual';
       // Live summary in the decision bar — what rides along with the decision.
       function updateSummary(){
         const n=annotations.filter(function(a){return a.kind==='note';}).length;
         const m=annotations.filter(function(a){return a.kind==='chat';}).length;
         const parts=[];
         if(n)parts.push(n+' note'+(n>1?'s':'')); if(m)parts.push(m+' message'+(m>1?'s':''));
-        document.getElementById('dbar-summary').textContent=
-          parts.length?parts.join(' · ')+' will be sent with your decision':'No notes or messages yet — a decision sends on its own';
+        document.getElementById('dbar-summary').textContent=MANUAL
+          ?(parts.length?parts.join(' · ')+' will be recorded with your decision — the agent reads it at its next checkpoint':'Decisions are recorded for the agent — it reads them at its next checkpoint')
+          :(parts.length?parts.join(' · ')+' will be sent with your decision':'No notes or messages yet — a decision sends on its own');
       }
       function updateBadges(){
         const counts={}, docCounts={};
@@ -1680,18 +1687,29 @@
       }
 
       // Per-decision confirmation copy — what the agent does with each verdict.
+      // Two tables: live (steer) and deferred (manual). Manual copy never
+      // implies a listener, and never pulses a waiting dot — nothing is waiting.
       const SENT={
         'Approve':          {cls:'approve',ico:'✓',wait:false,title:'Approved',sub:'Sent to the agent — it will proceed and implement the plan.'},
         'Request Revisions':{cls:'revise', ico:'',wait:true, title:'Revisions requested',sub:'Your notes are on their way. The agent will revise the plan; the updated version reloads here when it’s ready.'},
         'Reject':           {cls:'deny',   ico:'✕',wait:false,title:'Rejected',sub:'Sent to the agent — it will not implement this. It steps back to reconsider whether the feature should be built at all.'},
       };
+      const SENT_MANUAL={
+        'Approve':          {cls:'approve',ico:'✓',wait:false,title:'Approval recorded',sub:'Saved to the feedback file — the agent reads it at its next checkpoint. Nothing is watching live.'},
+        'Request Revisions':{cls:'revise', ico:'',wait:false,title:'Revisions recorded',sub:'Saved to the feedback file — the agent picks your notes up at its next checkpoint. Nothing is watching live.'},
+        'Reject':           {cls:'deny',   ico:'✕',wait:false,title:'Rejection recorded',sub:'Saved to the feedback file — the agent reads it at its next checkpoint. Nothing is watching live.'},
+      };
       let submitting=false, decisionSent=false;
       function clearAllNotes(){
         annotations.slice().forEach(function(a){ if(a.kind==='note') unhighlight(a.id); });
         annotations.length=0; nextId=1; paint();
       }
-      function showSent(decision){
-        const cfg=SENT[decision]||SENT['Request Revisions'];
+      function showSent(decision,mode){
+        // The toast follows the mode /api/feedback reports; the injected
+        // constant is the fallback when the response carried none.
+        const manual=(mode||SERVER_MODE)==='manual';
+        const table=manual?SENT_MANUAL:SENT;
+        const cfg=table[decision]||table['Request Revisions'];
         document.getElementById('dbar-live').style.display='none';
         const ico=document.getElementById('sent-ico');
         ico.className='ico'+(cfg.wait?' dot':''); ico.textContent=cfg.wait?'':cfg.ico;
@@ -1715,11 +1733,13 @@
           // conversation would mean two different notes.
           const r=await fetch('/api/feedback',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({decision:decision,thread:threadOrder()})});
           if(!r.ok) throw new Error('status '+r.status);
+          let mode=SERVER_MODE;
+          try{ mode=(await r.json()).mode||mode; }catch(e){}
           hideApiError();
           decisionSent=true;    // a terminal decision makes the server exit —
                                  // the SSE drop that follows is expected, not a fault
           clearAllNotes();      // notes clear the moment the decision is sent
-          showSent(decision);
+          showSent(decision,mode);
         }catch(e){
           showApiError('Could not send your decision — the review server may be unreachable. Nothing was sent; try again.');
           document.querySelectorAll('.dbar button').forEach(function(b){b.disabled=false;});
@@ -1729,6 +1749,13 @@
       document.getElementById('send').onclick=sendChat;
       document.getElementById('input').addEventListener('keydown',function(e){if((e.metaKey||e.ctrlKey)&&e.key==='Enter')sendChat();});
       document.querySelectorAll('.dbar button[data-decision]').forEach(function(b){b.onclick=function(){submit(b.dataset.decision);};});
+      // Manual mode: the buttons record, they don't transmit — say so.
+      if(MANUAL){
+        const RECORD={'Approve':'Record approval','Request Revisions':'Record revisions','Reject':'Record rejection'};
+        document.querySelectorAll('.dbar button[data-decision]').forEach(function(b){
+          if(RECORD[b.dataset.decision]) b.textContent=RECORD[b.dataset.decision];
+        });
+      }
 
       // ---- Revision diff (self-contained line-level LCS, no deps) ----
       function lineDiff(a,b){