@jabworks/condux 0.3.1 → 0.4.1

package/package.json

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

@@ -84,6 +84,24 @@ as any other soft gate in this skill.
 └──────────────────────────────────────────────────────────────────┘
 ```
 
+## Scope Lock (part of Step 1)
+
+The scope check runs in both directions. Decomposition catches a request that
+is secretly several features; the scope lock catches the opposite failure —
+quietly discovering against a wider surface than the one asked about, e.g.
+auditing a whole repo when one plugin was named.
+
+Before Step 2, state the target surface back in one line:
+
+> "Reading this as scoped to `<the named package / plugin / directory>` — the
+> rest of the repo is out of scope unless you say otherwise."
+
+Then hold it. If the design starts to need something outside that surface,
+name the crossing and get agreement before widening — do not widen silently
+because the adjacent thing looked related. Narrowing works the same way: if
+the user names a narrower target mid-discovery, that is the new surface, and
+work already done against the wider one is dropped, not folded in.
+
 ## Clarifying Questions — Good vs Bad
 
 ```
@@ -124,6 +142,7 @@ Accept either answer. Never block. Never lecture.
 ✗ Asking questions one at a time in a long back-and-forth
 ✗ 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
 ```
 
 ## Output

package/skills/finalize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finalize
-description: "End-of-task quality gate — typecheck → lint → format → tests. Runs in order, once. Stops on first failure and fixes before continuing. Run after all implementation is complete. Called automatically by /workflow, or standalone. Check AGENTS.md for the project's actual commands. Not for auditing whether requirements and plan steps are complete; use preflight first."
+description: "End-of-task quality gate — typecheck → lint → format → tests. Runs in order, once. Stops on first failure and fixes before continuing. Run after all implementation is complete. Called automatically by /workflow, or standalone. Check AGENTS.md for the project's actual commands. Not for auditing whether requirements and plan steps are complete (preflight, first); not for running the change and watching it work (live-verification, after)."
 argument-hint: "[package or path to scope — optional]"
 ---
 
@@ -86,6 +86,7 @@ Typecheck  ✓ clean
 Lint       ✓ clean  (2 warnings — not blocking)
 Format     ✓ 2 files auto-fixed (Button.tsx, invoice.router.ts)
 Tests      ✓ 18 passed, 0 failed
+Env        ✓ 1 new var → .env.example updated (STRIPE_WEBHOOK_SECRET)
 Plan       (none found for this task — treating as standalone scope)
 
 Ready to commit.
@@ -107,6 +108,18 @@ Format     ✓ clean
 Tests      ✓ 18 passed
 ```
 
+## Companion Files
+
+One cheap scan of the diff, reported alongside the gate. It never blocks — it
+exists because a new env var that never reaches the example file is invisible
+until it breaks someone else's checkout.
+
+- A new env var anywhere in the diff (`process.env.X`, `import.meta.env.X`, a
+  new key in an env schema, a new `docker-compose`/CI variable) ⇒ the project's
+  example file (`.env.example`, `.env.sample`, or whatever it uses) gains the
+  same key in the same change — placeholder value only, never a real secret.
+- Report `Env  ✓ n/a` when the diff adds none, so the check is visibly running.
+
 ## What Does NOT Happen
 
 ```

package/skills/live-verification/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: live-verification
+description: "Verify a change by actually running it — drive the real UI or endpoint, check each claim against observed behaviour, and capture evidence before pushing. Detects what's runnable, checks light mode then dark, and reports claim → evidence → verdict with unverifiable claims named rather than hidden. After /finalize, before committing or pushing a change that has a runnable surface — UI, page, component, endpoint, CLI. Triggers include \"verify it live\", \"did this actually work\", \"check it in the browser\", \"live verify before pushing\", \"does it render right\". Not for typecheck/lint/test (that's finalize), not for auditing plan completeness (preflight), not for reading code to judge it (code-review)."
+argument-hint: "[what to verify — optional; defaults to the current diff]"
+---
+
+# /live-verification
+
+Green tests are not evidence that the thing works. This skill closes the gap
+between "the pipeline passed" and "I watched it do the thing".
+
+## Usage
+
+```
+/live-verification                    # verify the current diff
+/live-verification the upload dialog  # verify a named surface
+```
+
+## When It Applies
+
+| Change touches | Run this? |
+|---|---|
+| A rendered surface — page, component, story, dialog | **Yes** |
+| An endpoint, procedure, or CLI a human will call | **Yes** |
+| Behaviour behind a flag or a state the tests don't reach | **Yes** |
+| Types, docs, comments, config with no runtime effect | No — say so and skip |
+| Code fully covered by a test that genuinely exercises it | Judgment: skip, and name the test you're leaning on |
+
+Skipping is a legitimate outcome. Skipping *silently* is not.
+
+## How It Works
+
+### Step 1 — Resolve the run target
+
+Do not assume a dev server. In order:
+
+1. Something already running? Check the project's usual port before starting
+   anything (`ss -tlnp` / `lsof -i` / the URL in `README` or `AGENTS.md`).
+2. `AGENTS.md` — if it names the command to run the app, that command wins.
+3. `package.json` scripts — `dev`, `storybook`, `start`, `preview`.
+4. Nothing runnable → stop here and report that. Do not scaffold a harness.
+
+Start it in the background, wait for it to actually serve (poll the URL — do
+not `sleep` and hope), and note the URL in the report.
+
+### Step 2 — Enumerate the claims
+
+Before touching the UI, write down what the change claims to do — one line
+each, from the diff and the task description. These are the only things you
+verify. A change that claims four things needs four verdicts.
+
+Bad: "the dialog works." Good: "Save is disabled while the mutation is in
+flight", "a failed save shows the server's message inline", "Escape closes
+the dialog and returns focus to the trigger".
+
+### Step 3 — Drive it
+
+Use whatever driving tool this environment actually has — a browser MCP, a
+headless script the repo already ships, `curl` for an endpoint, or the CLI
+itself. **Nothing is assumed installed.** If no driving tool exists, degrade
+honestly: report what could not be driven rather than inventing a result.
+
+Order of checks, because this is where the defects were:
+
+1. **Light mode first.** Then dark. A themed change is not verified until it
+   has been seen in both — that part is the gate, not the order.
+2. **The interactive states**, not just the resting one — hover, focus,
+   disabled, selected, and the in-flight state of every mutation.
+3. **The failure path.** Make the thing fail on purpose if you can (offline,
+   bad input, forced error) and confirm the error is surfaced where the user
+   acted.
+4. **Keyboard.** Tab to it, Escape out of it, confirm focus lands somewhere
+   sensible.
+
+### Step 4 — Capture evidence
+
+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
+get reported even when they belong to another feature.
+
+### 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.
+
+## Failure Handling
+
+The recurring failures here are environmental, not logical — treat them as
+results, not as things to retry into the ground:
+
+```
+Server won't start / port already in use
+  → Report it. Do not kill a process you did not start.
+
+Out of memory, model won't load, dependency missing
+  → Not your bug. Report "could not verify — <reason>" and stop.
+     "Let's do live verify later" is a valid user answer.
+
+Selector not found / element no longer exists
+  → Re-read the current DOM once and retry with what's actually there.
+     Second miss: report the claim as unverified, don't keep guessing.
+
+Wait timed out
+  → Poll for the condition, never a fixed sleep. On a real timeout, report
+     it as a finding — a surface that takes longer than the timeout to
+     appear is itself a defect worth naming.
+```
+
+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
+```
+
+## What Does NOT Happen
+
+```
+✗ Reporting a claim as verified because the code looks right
+✗ Inventing a screenshot, a response, or a result that wasn't observed
+✗ Installing a browser driver or scaffolding a test harness to get a result
+✗ sleep-then-check instead of polling for the condition
+✗ Retrying the same selector more than twice
+✗ Killing processes the run didn't start
+✗ Re-running typecheck/lint/tests — that was finalize's job
+```
+
+## Artifacts
+
+Evidence is **working state**: `<git-root>/.condux/verification/`, gitignored,
+alongside condux's `designs/` and `plans/`. Never the repo root, never the
+project's `docs/`.
+
+**Bootstrap.** `.condux/` is created on demand at the git root by the first
+skill that writes there. Before the first write, check it's ignored:
+
+```bash
+git check-ignore -q .condux/ || echo "not ignored"
+```
+
+If it isn't, offer once: "condux keeps its working files in `.condux/` — add
+it to `.gitignore` so they stay out of your commits?" On yes, append
+`.condux/` to the repo's `.gitignore`. If the user would rather not touch a
+tracked file, write it to `.git/info/exclude` instead. Never edit either file
+without asking. Not a git repo → fall back to CWD and say so once.
+
+**Override.** A project can relocate this in `AGENTS.md`; an explicit
+override always wins.

package/skills/plan-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-review
-description: "Render a plan in a local browser for inline annotation, then return an approve / request-revisions / deny decision to the agent. Auto-captures the plan via a Claude Code ExitPlanMode hook or a Codex Stop hook, or runs manually on any markdown file or spec directory. Self-contained — no network egress, no third-party runtime deps. When the agent finishes planning (Claude Code ExitPlanMode, or a Codex planning turn) and you want to review/annotate before it implements, or when you invoke /plan-review on a markdown plan or spec directory. Also owns its own machinery — steer-mode review loops, the live spec preview, and installing or troubleshooting the ExitPlanMode / Codex Stop hooks. Not for cataloging a whole specs tree; use spec-browser."
+description: "Render a plan in a local browser for inline annotation, then return an approve / request-revisions / deny decision to the agent. Auto-captures the plan via a Claude Code ExitPlanMode hook or a Codex Stop hook, or runs manually on any markdown file or spec directory. Self-contained — no network egress, no third-party runtime deps. When the agent finishes planning (Claude Code ExitPlanMode, or a Codex planning turn) and you want to review/annotate before it implements, or when you invoke /plan-review on a markdown plan or spec directory. Also owns its own machinery — steer-mode review loops, the live spec preview, and installing or troubleshooting the ExitPlanMode / Codex Stop hooks. Phrases include \"let's review the plan\", \"walk me through the plan before we build\", \"annotate the plan\" — use these when the ExitPlanMode or Codex Stop hook doesn't fire. Not for cataloging a whole specs tree; use spec-browser."
 ---
 
 # /plan-review

package/skills/preflight/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: preflight
-description: "Lightweight \"am I actually done?\" checklist before calling /finalize. Prevents premature completion — catches skipped steps, missing behavior, and silent regressions. Runs before /finalize at the end of every /workflow tier (automatic on SMALL; the recommended CP-2 choice on MEDIUM/LARGE). Also trigger standalone on \"verify this\", \"am I done?\", or \"preflight\". Not for executing typecheck, lint, format, and tests; use finalize."
+description: "Lightweight \"am I actually done?\" checklist before calling /finalize. Prevents premature completion — catches skipped steps, missing behavior, and silent regressions. Runs before /finalize at the end of every /workflow tier (automatic on SMALL; the recommended CP-2 choice on MEDIUM/LARGE). Also trigger standalone on \"verify this\", \"am I done?\", or \"preflight\". Not for executing typecheck, lint, format, and tests; use finalize. Not for actually running the change and observing it work in a browser or CLI; that's live-verification, after finalize."
 argument-hint: "[task or feature name]"
 ---
 

package/skills/root-cause-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: root-cause-analysis
-description: "Enforces root-cause-first bug investigation — read the error, reproduce it, trace the data flow backward. Never propose a solution before the investigation phase completes. Trigger the moment debugging starts — never proactively — and always before any fix is proposed or any change is made."
+description: "Enforces root-cause-first bug investigation — read the error, reproduce it, trace the data flow backward. Never propose a solution before the investigation phase completes. Trigger the moment debugging starts — never proactively — and always before any fix is proposed or any change is made. Phrases include \"why is this failing\", \"this bug\", \"unexpected behavior\", \"error when I…\". Not for a jabworks/agentic-toolkit skill or plugin misbehaving (won't trigger, won't show up, dist drift); that's toolkit-debugging-playbook."
 argument-hint: "<error message or bug description>"
 effort: high
 ---

package/skills/workflow/SKILL.md

@@ -130,6 +130,7 @@ happened (or was declined) in draft-plan's own save step — don't re-offer it.*
 
 | Option | What it does |
 |---|---|
+| **Verify it live** *(recommended when the change has a runnable surface)* | Load `live-verification` — drive the real UI or endpoint and check each claim against observed behaviour |
 | **Code review** *(recommended)* | `/code-review` the diff before merging |
 | **Commit** | Load the `git-commit` skill if installed (conventional message from the diff, safe staging); otherwise follow the repo's commit conventions |
 | **Cut a release** | Load the `release` skill if installed — machinery detection, dry-run plan, then tag → push → GitHub release; otherwise follow the repo's release conventions |
@@ -148,6 +149,7 @@ Load each only when its step is reached.
 | `subagent-deployment` | 2+ independent tasks, no shared files/deps | ad-hoc work, not ordered plans |
 | `preflight` | end of every tier, before finalize | automatic on SMALL; recommended CP-2 choice |
 | `finalize` | after all implementation | runs in order, once, stops on first failure; check AGENTS.md for the real commands |
+| `live-verification` | after finalize, when the change has a runnable surface | offer at CP-3; one pass, no loop; skipping is fine, silent skipping is not |
 | `code-review` | on request only | never auto-triggers, never fixes; after finalize you may ask ONCE |
 | `root-cause-analysis` | any bug investigation | load when debugging starts, not proactively; investigation before fixes |
 | `plan-review` | plan/spec annotation in the browser | via ExitPlanMode/Stop hook, draft-plan's save step, or manually |