@jabworks/condux 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.4.1",
+  "version": "0.5.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/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: "One-shot code review. Produces a diagnostic report categorized by severity (Critical / Important / Minor). Never fixes issues automatically. On-request only — never auto-triggers. After /finalize, ask once: \"Want a code review before merging?\" Trigger phrases: \"review this\", \"review before merge\", \"check this PR\"."
+description: "One-shot code review. Produces a diagnostic report categorized by severity (Critical / Important / Minor). Never fixes issues automatically. On-request only — never auto-triggers. At workflow CP-2 (pre-finalize, on request) or after /finalize, ask once: \"Want a code review before merging?\" Trigger phrases: \"review this\", \"review before merge\", \"check this PR\". Not for reviewing a plan or spec before implementation — that's plan-review. Not for running the change to watch it work — that's live-verification."
 argument-hint: "<PR URL, diff, branch, or file path>"
 ---
 
@@ -17,7 +17,11 @@ One review pass. Categorized findings. You decide what to action. No fixing, no
 
 ## When This Runs
 
-After `/finalize` completes, ask once:
+Two sanctioned entry points:
+
+- **Workflow CP-2** ("Implementation done") — the user picks "Code review first"
+  and this skill runs on the diff before preflight/finalize.
+- **After `/finalize` completes** — ask once:
 
 > "Want a code review before merging?"
 

package/skills/discovery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discovery
-description: "Refine a rough idea into a signed-off design. Asks goal-level questions, surfaces alternatives, then runs a post-approach detail round (contracts, mappings, edge cases) that feeds the tech spec; presents the design in sections for sign-off before any planning or code begins. Trigger for LARGE tasks, when scope is unclear, or when the user wants to brainstorm or explore a rough idea. Also when resuming or continuing an existing design or design doc — the existing-design check offers resume-or-fresh. Acts as a soft gate before /draft-plan — if discovery hasn't run, ask the user if they want to skip it consciously."
+description: "Refine a rough idea into a signed-off design. Asks goal-level questions, surfaces alternatives, then runs a post-approach detail round (contracts, mappings, edge cases) that feeds the tech spec (written via technical-spec at sign-off); presents the design in sections for sign-off before any planning or code begins. Trigger for LARGE tasks, when scope is unclear, or when the user wants to brainstorm or explore a rough idea. Also when resuming or continuing an existing design or design doc — the existing-design check offers resume-or-fresh. Acts as a soft gate before /draft-plan — if discovery hasn't run, ask the user if they want to skip it consciously."
 argument-hint: "<rough idea or feature description>"
 effort: high
 ---
@@ -18,7 +18,9 @@ Turn a rough idea into a clear, agreed-upon design. Nothing gets planned or buil
 ## How It Works
 
 Before Step 1, check for an existing design: glob `.condux/designs/*<slug>*.md`
-and `specs/<slug>/` (slug = kebab-case of the feature name). If either
+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.
@@ -182,12 +184,14 @@ 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):
 
 ```bash
-node /path/to/plan-review/references/annotate-server.js .condux/designs/<file>.md --steer
+node /path/to/plan-review/references/annotate-server.js .condux/designs/<file>.md --steer --no-reject
 ```
 
 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** — there is no Reject at this stage:
+**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** → design is signed off; proceed to `/draft-plan`, carrying any
   feedback notes into the plan.
@@ -198,64 +202,12 @@ decision is submitted) and branch on the result. Design review is
 
 ## Spec Integration (Live Preview)
 
-Integrates with the `technical-spec` skill to persist the design and render it live while discovery runs.
-
-### At discovery start
-
-Infer the feature slug (kebab-case from `$ARGUMENTS`). Specs live under
-`<git-root>/specs/`, mirroring the repo structure: check
-`<git-root>/specs/<pkg-relpath>/<feature-slug>/` (pkg-relpath = the nearest
-package root's path relative to the git root, empty at the root) and
-`<git-root>/specs/<feature-slug>/` for an existing spec.
-
-If found, offer:
-
-> "Found an existing spec for this feature. Open live preview while we refine the design? [y/n]"
-
-If yes, go straight to **Launch preview** below (skip scaffold + write — spec already exists).
-
-### At sign-off
-
-The Markdown design doc (Step 7) is always written. The spec write-back is
-**default-on** — announce it rather than ask:
-
-> "Saving this as a tech spec too (decisions + the concern files from the
-> detail round) and opening the live preview — say no to skip."
-
-Unless the user opts out (the spec directory then becomes the target for the
-Design Review Loop above, in directory mode):
-
-1. **Find scripts** — the scaffold from technical-spec, the preview from
-   plan-review (its annotate server renders spec directories):
-   ```bash
-   SCAFFOLD=$(find ~/.claude ~/.codex ~/.agents -name "scaffold.sh" -path "*technical-spec*" 2>/dev/null | head -1)
-   PREVIEW=$(find ~/.claude ~/.codex ~/.agents -name "annotate-server.js" -path "*plan-review*" 2>/dev/null | head -1)
-   ```
-   If either is missing, tell the user: "the `technical-spec` / `plan-review` skills weren't found — install the condux plugin to enable spec integration."
-
-2. **Scaffold** the spec dir and capture the output:
-   ```bash
-   SCAFFOLD_OUT=$(bash "$SCAFFOLD" "<FeatureName>")
-   SPEC_PATH=$(echo "$SCAFFOLD_OUT" | sed 's/^[^:]*://; s/ .*//')
-   ```
-   `SPEC_PATH` is an absolute path (e.g. `/repo/specs/apps/web/wan-config`).
-   The scaffold script places specs under `<git-root>/specs/`, mirroring the
-   repo structure, automatically.
-
-3. **Write initial spec files** from the design into `$SPEC_PATH/`.
-   `decisions.md` always (chosen approach + rationale). Then every concern
-   the detail round produced answers for gets its file: `api.md`,
-   `fields.md`, `quirks.md`, `implementation.md`. A detail-round answer
-   that never lands in a spec file is a bug in the flow, not a judgment call.
-
-4. **Launch preview** in the background, pointing at the absolute spec path:
-   ```bash
-   node "$PREVIEW" "$SPEC_PATH"
-   ```
-   Tell user: "Preview is live. The browser updates automatically as spec files change, and you can annotate any file and submit a decision. Ctrl+C in the terminal to stop."
-
-### Keeping the spec current
-
-As discovery continues and design details shift, update the relevant spec files — the preview re-renders on every save. This is the main benefit: the spec stays in sync with the conversation instead of being written once at the end.
-
-If the user submits a decision in the preview, read `$SPEC_PATH/review.feedback.md` (notes grouped by file) and action it. Spec review is accept-or-fix (directory mode has no Reject): **Approve** = design is signed off, proceed; **Request Revisions** = fix the spec files, then continue the loop.
+Integrates with `technical-spec` to persist the design and render it live while
+discovery runs. At sign-off (Step 7), unless the user opts out: run
+`technical-spec`'s scaffold script to create the spec directory, write the
+design's decisions/contracts/mappings/edge-cases into its concern files
+(`decisions.md`, `api.md`, `fields.md`, `quirks.md`, `implementation.md`), then
+launch `plan-review`'s directory-mode preview against that spec path so it
+live-reloads as the conversation refines the design. Full commands, the
+existing-spec check, and how to action a submitted review decision:
+`references/spec-integration.md`.

package/skills/discovery/references/spec-integration.md

@@ -0,0 +1,63 @@
+# Spec Integration (Live Preview)
+
+Integrates with the `technical-spec` skill to persist the design and render it live while discovery runs.
+
+### At discovery start
+
+Infer the feature slug (kebab-case from `$ARGUMENTS`). Specs live under
+`<git-root>/specs/`, mirroring the repo structure: check
+`<git-root>/specs/<pkg-relpath>/<feature-slug>/` (pkg-relpath = the nearest
+package root's path relative to the git root, empty at the root) and
+`<git-root>/specs/<feature-slug>/` for an existing spec.
+
+If found, offer:
+
+> "Found an existing spec for this feature. Open live preview while we refine the design? [y/n]"
+
+If yes, go straight to **Launch preview** below (skip scaffold + write — spec already exists).
+
+### At sign-off
+
+The Markdown design doc (Step 7) is always written. The spec write-back is
+**default-on** — announce it rather than ask:
+
+> "Saving this as a tech spec too (decisions + the concern files from the
+> detail round) and opening the live preview — say no to skip."
+
+Unless the user opts out (the spec directory then becomes the target for the
+Design Review Loop above, in directory mode):
+
+1. **Find scripts** — the scaffold from technical-spec, the preview from
+   plan-review (its annotate server renders spec directories):
+   ```bash
+   SCAFFOLD=$(find ~/.claude ~/.codex ~/.agents -name "scaffold.sh" -path "*technical-spec*" 2>/dev/null | head -1)
+   PREVIEW=$(find ~/.claude ~/.codex ~/.agents -name "annotate-server.js" -path "*plan-review*" 2>/dev/null | head -1)
+   ```
+   If either is missing, tell the user: "the `technical-spec` / `plan-review` skills weren't found — install the condux plugin to enable spec integration."
+
+2. **Scaffold** the spec dir and capture the output:
+   ```bash
+   SCAFFOLD_OUT=$(bash "$SCAFFOLD" "<FeatureName>")
+   SPEC_PATH=$(echo "$SCAFFOLD_OUT" | sed 's/^[^:]*://; s/ .*//')
+   ```
+   `SPEC_PATH` is an absolute path (e.g. `/repo/specs/apps/web/wan-config`).
+   The scaffold script places specs under `<git-root>/specs/`, mirroring the
+   repo structure, automatically.
+
+3. **Write initial spec files** from the design into `$SPEC_PATH/`.
+   `decisions.md` always (chosen approach + rationale). Then every concern
+   the detail round produced answers for gets its file: `api.md`,
+   `fields.md`, `quirks.md`, `implementation.md`. A detail-round answer
+   that never lands in a spec file is a bug in the flow, not a judgment call.
+
+4. **Launch preview** in the background, pointing at the absolute spec path:
+   ```bash
+   node "$PREVIEW" "$SPEC_PATH"
+   ```
+   Tell user: "Preview is live. The browser updates automatically as spec files change, and you can annotate any file and submit a decision. Ctrl+C in the terminal to stop."
+
+### Keeping the spec current
+
+As discovery continues and design details shift, update the relevant spec files — the preview re-renders on every save. This is the main benefit: the spec stays in sync with the conversation instead of being written once at the end.
+
+If the user submits a decision in the preview, read `$SPEC_PATH/review.feedback.md` (notes grouped by file) and action it. Spec review is accept-or-fix (directory mode has no Reject): **Approve** = design is signed off, proceed; **Request Revisions** = fix the spec files, then continue the loop.

package/skills/draft-plan/SKILL.md

@@ -18,8 +18,10 @@ Turn a signed-off design into a clear, executable plan. Lean task cards, not mic
 ## Before Writing
 
 1. Confirm discovery has run and design is signed off. First glob
-   `.condux/designs/*<slug>*.md` and `specs/<slug>/` (slug = kebab-case
-   of the feature name) for an existing signed-off design — if found,
+   `.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
    haven't aligned on the design yet — run /discovery first, or confirm
    you want to skip it."

package/skills/live-verification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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)."
+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, pushing, or merging 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\", \"verify on preview\", \"check the preview env then merge\", \"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]"
 ---
 
@@ -156,18 +156,7 @@ 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.
+**Bootstrap.** Same contract as every condux skill — run the `.condux/`
+bootstrap from `/workflow` → Artifacts (check `git check-ignore -q .condux/`,
+offer the `.gitignore` line once, `AGENTS.md` override wins) before the first
+write.

package/skills/live-verification/evals/trigger_eval.json

@@ -0,0 +1,25 @@
+[
+  { "query": "verify it live", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "did this actually work in the browser", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "verify on preview then merge", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "does it render right", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "check the preview env before pushing", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "check it in the browser before we ship", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "live verify before pushing", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "click through the flow and confirm it works", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "hit the endpoint and check the response before we push", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "does dark mode actually look right", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "run it and watch it work before I commit", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "confirm the component actually renders now", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "spin up the app and check the change before pushing", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "did the button actually fix itself, go look", "should_trigger": true, "expected_skill": "live-verification" },
+  { "query": "run typecheck and lint before I commit", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "run the full test suite", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "am I actually done, did I miss anything", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "are all the plan steps covered", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "review this diff before merge", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "review the code quality here", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "let's review the plan before we build", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "walk me through the plan and annotate it", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "what does the CSS overflow property do", "should_trigger": false, "expected_skill": null }
+]

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. 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."
+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. Not for the implemented diff; use code-review."
 ---
 
 # /plan-review
@@ -19,85 +19,18 @@ network calls** — safe for strict environments.
 
 ### Auto — ExitPlanMode hook (the real workflow)
 
-When installed as part of the **condux plugin**, this hook ships in the plugin
-(`hooks/hooks.json`) and is auto-registered — no setup. Every time the agent
-exits plan mode, the plan is captured and the review UI opens automatically. The
-hook blocks until you decide. The plugin entry is:
-
-```json
-// dist/plugins/condux/hooks/hooks.json (shipped — for reference)
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "ExitPlanMode",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/condux/plan-review/references/annotate-server.js\" --hook"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-**Standalone (no plugin)?** Wire the same hook by hand in your
-`settings.json` (project `.claude/settings.json` or `~/.claude/settings.json`),
-swapping `${CLAUDE_PLUGIN_ROOT}/skills/condux/plan-review` for the absolute path:
-
-```bash
-find ~/.claude ~/.codex ~/.agents -name annotate-server.js -path '*plan-review*' 2>/dev/null | head -1
-```
-
-What the hook returns to the agent:
-
-| Your decision | Hook output | Agent behavior |
-|---|---|---|
-| **Approve** | `permissionDecision: "allow"` (+ notes as `additionalContext` if any) | proceeds to implement |
-| **Request Revisions** | `permissionDecision: "deny"`, reason = *revise this plan* + feedback | revises the plan, re-enters plan mode (re-triggers the hook) |
-| **Reject** | `permissionDecision: "deny"`, reason = *do not implement, reconsider* + feedback | stops; reconsiders whether the feature should be built, or proposes a different approach |
+Ships with the condux plugin, auto-registered — every `ExitPlanMode` opens the
+review UI and blocks until you decide (Approve / Request Revisions / Reject).
+Standalone installs wire the same hook by hand.
+Full install + troubleshooting: `references/hooks-install.md`.
 
 ### Auto — Codex Stop hook
 
-Codex has **no `ExitPlanMode`** interception point, so plan review runs off
-Codex's experimental **`Stop` hook**. When a planning turn ends
-(`permission_mode === "plan"`), `annotate-server.js --codex-stop` reads the plan
-from the Stop payload (`last_assistant_message`, falling back to
-`transcript_path`) and opens the same review UI. On any other turn it emits `{}`
-and exits, leaving the turn untouched.
-
-**Installed via the condux plugin?** The `Stop` hook ships with it. The Codex
-manifest (`.codex-plugin/plugin.json`) sets `"hooks": "./hooks/codex-hooks.json"`,
-which Codex loads **instead of** the default `hooks/hooks.json` (that one is
-Claude's `ExitPlanMode` hook, inert on Codex). Just enable `[features] hooks =
-true` in `$CODEX_HOME/config.toml`, then **restart Codex** and **trust the hook**
-when prompted — no installer needed.
-
-**Standalone (no plugin)?** Run the installer once — it writes `~/.codex/hooks.json`
-+ sets the feature flag, then restart Codex and trust the hook:
-
-```bash
-bash /PATH/TO/plan-review/references/install-codex-hook.sh
-# or, after a plugin install:
-find ~/.codex ~/.claude -name install-codex-hook.sh -path '*plan-review*' 2>/dev/null | head -1 | xargs bash
-```
-
-| Your decision | Hook output | Codex behavior |
-|---|---|---|
-| **Approve** (no notes) | `{}` (turn completes) | plan accepted, turn ends |
-| **Approve** (with notes) | `{"decision":"block","reason":<approved + notes>}` | continues the turn; agent implements while addressing the notes |
-| **Request Revisions** | `{"decision":"block","reason":<revise + feedback>}` | revises the plan in the same turn (re-triggers on next stop) |
-| **Reject** | `{"decision":"block","reason":<do not implement, reconsider + feedback>}` | stops; reconsiders whether the feature should be built, or proposes a different approach |
-
-Caveats: Codex hooks are **experimental and disabled on Windows**; the review is
-**post-render** (after Codex prints the plan), not a pre-interception like Claude
-Code. The plugin hook invokes bare `node` (resolved via `${PLUGIN_ROOT}`, the
-variable Codex substitutes in plugin hook commands — it does **not** set Claude's
-`${CLAUDE_PLUGIN_ROOT}`, so never use that in `codex-hooks.json`) — if Codex
-Desktop can't find `node` on `PATH`, fall back to the installer, which bakes in
-an **absolute** node path.
+Codex has no `ExitPlanMode` interception point, so review runs off Codex's
+experimental `Stop` hook instead — same review UI, same three decisions.
+Ships with the condux plugin's Codex manifest; standalone installs run
+`install-codex-hook.sh` once.
+Full install + troubleshooting + decision tables: `references/hooks-install.md`.
 
 ### Manual — on any file or spec directory
 
@@ -152,60 +85,19 @@ reflects every revision** — no new tab per round. The decision is also written
 
 ## The review surface
 
-A three-pane layout over a **decision bar**: a left sidebar with two tabs —
-**Contents** (heading outline with per-section note counts; in directory mode,
-each document is a top-level node with its headings nested, click to switch
-docs) and **Files** (paths the plan touches, parsed from inline code and
-fences, badged **exists**/**new** against the repo; click jumps to the first
-mention, repeat clicks cycle) — the centered rendered plan (middle), and a
-**Review** rail (right) holding your notes and messages. The decisions live in
-a fixed bar along the bottom — `[Reject] ——— [Request revisions] [Approve]` —
-with a live summary of what rides along ("3 notes · 1 message will be sent").
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│  Step 1  RENDER     Plan renders centered in the browser, w/ TOC. │
-│  Step 2  ANNOTATE   Select text → a toolbar opens above it. Pick  │
-│                     a category (Comment / Issue / Question /       │
-│                     Suggestion / Nitpick) → the note input opens.  │
-│                     Or message the agent in the Review rail.       │
-│  Step 3  DECIDE     Bottom bar: Approve / Request Revisions /     │
-│                     Reject — with a note/message count summary.    │
-│  Step 4  RETURN     Decision + notes (each tagged with its        │
-│                     category and quoting its anchor) go back.     │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-Selecting text opens a floating **annotation toolbar** anchored above the
-selection (it flips below when there's no room). It starts as a category
-**menubar**; choosing a category expands it to reveal the note input and
-Save/Cancel. Saving highlights the text and anchors the note; clicking a
-highlight or a note cross-links the two. The page live-reloads when the plan
-file changes on disk (SSE + `fs.watch`).
-
-When the agent **revises** the plan, the tab doesn't silently swap the text: a
-banner reports the change (`+adds / -dels lines`) with a **View changes** toggle
-that shows a unified line diff (old vs. new, folding long unchanged runs), and
-the now-orphaned notes clear so the next round starts clean. Submitting a
-decision **clears your notes immediately** and replaces the decision bar's
-content with a confirmation that states what the agent does next
-(implement / revise / rework).
-
-## Guarantees (why it passes review)
-
-- **No egress.** Server binds `127.0.0.1` only; the HTML template embeds its own
-  markdown renderer and uses a system monospace font — no CDN, no web fonts, no
-  paste/share service. Audit: `grep -rE 'https?://' references/*.html` returns nothing.
-- **No dependencies.** `annotate-server.js` is Node stdlib only.
-- **Auditable.** One stdlib server + one self-contained HTML file. The UI is
-  styled after the **Terminus UI** design system (Button, Badge, Card, Textarea,
-  Popover) — adapted as vanilla CSS tokens + classes, no React, no bundle.
+Three-pane layout over a decision bar: sidebar (Contents outline + Files list)
+on the left, the rendered plan centered, and a Review rail on the right for
+notes/messages. Select text to annotate (category + note), or message the
+agent directly; decide via `[Reject] ——— [Request revisions] [Approve]` at the
+bottom. Revisions live-reload with a diff banner; no third-party deps or
+network egress (Node stdlib server + self-contained HTML).
+Full UI walkthrough + guarantees: `references/ui.md`.
 
 ## Files
 
 | File | Role |
 |---|---|
-| `references/annotate-server.js` | Local server. `--hook` (Claude ExitPlanMode), `--codex-stop` (Codex Stop), `<file> --steer` (agent-invoked blocking loop), or `<file|dir>` alone for manual mode. A directory argument reviews every top-level `*.md` in it. |
+| `references/annotate-server.js` | Local server. `--hook` (Claude ExitPlanMode), `--codex-stop` (Codex Stop), `<file> --steer` (agent-invoked blocking loop), or `<file|dir>` alone for manual mode. A directory argument reviews every top-level `*.md` in it. `--no-reject` hides the Reject verdict for accept-or-fix reviews (discovery's design stage passes it; directory mode implies it). |
 | `references/install-codex-hook.sh` | Registers the Codex `Stop` hook in `~/.codex` and enables the hooks feature flag. |
 | `references/plan-review-template.html` | Self-contained review UI (renderer + annotation surface). |
 

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

@@ -53,6 +53,7 @@ const HOOK_MODE = process.argv.includes('--hook');
 const CODEX_STOP_MODE = process.argv.includes('--codex-stop');
 const STEER_MODE = process.argv.includes('--steer');
 const NO_OPEN = process.argv.includes('--no-open'); // don't launch the browser (tests, headless)
+const NO_REJECT = process.argv.includes('--no-reject'); // accept-or-fix review (design stage) — hide the Reject verdict
 const STDOUT_JSON = HOOK_MODE || CODEX_STOP_MODE || STEER_MODE; // these modes emit JSON on stdout
 const log = STDOUT_JSON ? console.error : console.log; // keep stdout clean for hooks
 const sseClients = new Set();
@@ -309,8 +310,8 @@ function handler(req, res) {
     // Document manifest. Single-file reviews report dir:false so the client
     // keeps the classic one-document layout.
     return sendJson(res, 200, DIR_MODE
-      ? { dir: true, docs: listDocs() }
-      : { dir: false, docs: [path.basename(planFile)] });
+      ? { dir: true, docs: listDocs(), noReject: true }
+      : { dir: false, docs: [path.basename(planFile)], noReject: NO_REJECT });
   }
   if (req.method === 'POST' && p === '/api/verify-paths') {
     // Files tab: check which mentioned paths exist in the repo under review.

package/skills/plan-review/references/hooks-install.md

@@ -0,0 +1,83 @@
+# Hook Install + Troubleshooting
+
+### Auto — ExitPlanMode hook (the real workflow)
+
+When installed as part of the **condux plugin**, this hook ships in the plugin
+(`hooks/hooks.json`) and is auto-registered — no setup. Every time the agent
+exits plan mode, the plan is captured and the review UI opens automatically. The
+hook blocks until you decide. The plugin entry is:
+
+```json
+// dist/plugins/condux/hooks/hooks.json (shipped — for reference)
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/condux/plan-review/references/annotate-server.js\" --hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Standalone (no plugin)?** Wire the same hook by hand in your
+`settings.json` (project `.claude/settings.json` or `~/.claude/settings.json`),
+swapping `${CLAUDE_PLUGIN_ROOT}/skills/condux/plan-review` for the absolute path:
+
+```bash
+find ~/.claude ~/.codex ~/.agents -name annotate-server.js -path '*plan-review*' 2>/dev/null | head -1
+```
+
+What the hook returns to the agent:
+
+| Your decision | Hook output | Agent behavior |
+|---|---|---|
+| **Approve** | `permissionDecision: "allow"` (+ notes as `additionalContext` if any) | proceeds to implement |
+| **Request Revisions** | `permissionDecision: "deny"`, reason = *revise this plan* + feedback | revises the plan, re-enters plan mode (re-triggers the hook) |
+| **Reject** | `permissionDecision: "deny"`, reason = *do not implement, reconsider* + feedback | stops; reconsiders whether the feature should be built, or proposes a different approach |
+
+### Auto — Codex Stop hook
+
+Codex has **no `ExitPlanMode`** interception point, so plan review runs off
+Codex's experimental **`Stop` hook**. When a planning turn ends
+(`permission_mode === "plan"`), `annotate-server.js --codex-stop` reads the plan
+from the Stop payload (`last_assistant_message`, falling back to
+`transcript_path`) and opens the same review UI. On any other turn it emits `{}`
+and exits, leaving the turn untouched.
+
+**Installed via the condux plugin?** The `Stop` hook ships with it. The Codex
+manifest (`.codex-plugin/plugin.json`) sets `"hooks": "./hooks/codex-hooks.json"`,
+which Codex loads **instead of** the default `hooks/hooks.json` (that one is
+Claude's `ExitPlanMode` hook, inert on Codex). Just enable `[features] hooks =
+true` in `$CODEX_HOME/config.toml`, then **restart Codex** and **trust the hook**
+when prompted — no installer needed.
+
+**Standalone (no plugin)?** Run the installer once — it writes `~/.codex/hooks.json`
++ sets the feature flag, then restart Codex and trust the hook:
+
+```bash
+bash /PATH/TO/plan-review/references/install-codex-hook.sh
+# or, after a plugin install:
+find ~/.codex ~/.claude -name install-codex-hook.sh -path '*plan-review*' 2>/dev/null | head -1 | xargs bash
+```
+
+| Your decision | Hook output | Codex behavior |
+|---|---|---|
+| **Approve** (no notes) | `{}` (turn completes) | plan accepted, turn ends |
+| **Approve** (with notes) | `{"decision":"block","reason":<approved + notes>}` | continues the turn; agent implements while addressing the notes |
+| **Request Revisions** | `{"decision":"block","reason":<revise + feedback>}` | revises the plan in the same turn (re-triggers on next stop) |
+| **Reject** | `{"decision":"block","reason":<do not implement, reconsider + feedback>}` | stops; reconsiders whether the feature should be built, or proposes a different approach |
+
+Caveats: Codex hooks are **experimental and disabled on Windows**; the review is
+**post-render** (after Codex prints the plan), not a pre-interception like Claude
+Code. The plugin hook invokes bare `node` (resolved via `${PLUGIN_ROOT}`, the
+variable Codex substitutes in plugin hook commands — it does **not** set Claude's
+`${CLAUDE_PLUGIN_ROOT}`, so never use that in `codex-hooks.json`) — if Codex
+Desktop can't find `node` on `PATH`, fall back to the installer, which bakes in
+an **absolute** node path.

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

@@ -706,9 +706,11 @@
         let meta={dir:false,docs:['plan']};
         try{ meta=await (await fetch('/api/docs')).json(); }catch(e){}
         DIRMODE=!!meta.dir; docs=meta.docs||[];
-        // Directory (spec) review is accept-or-fix — a spec documents work already
-        // decided, so the plan-only "Reject / don't build it" verdict doesn't apply.
-        if(DIRMODE){ const rj=document.getElementById('btn-reject'); if(rj)rj.style.display='none'; }
+        // Accept-or-fix reviews hide the plan-only "Reject / don't build it"
+        // verdict: directory (spec) review always — a spec documents work already
+        // decided — and single-file review when the server was started with
+        // --no-reject (discovery's design stage).
+        if(DIRMODE||meta.noReject){ const rj=document.getElementById('btn-reject'); if(rj)rj.style.display='none'; }
         planEl.innerHTML='';
         docs.forEach(function(d,i){
           const pane=document.createElement('div'); pane.className='docpane'; pane.style.display='none';

package/skills/plan-review/references/ui.md

@@ -0,0 +1,52 @@
+# Review Surface UI
+
+## The review surface
+
+A three-pane layout over a **decision bar**: a left sidebar with two tabs —
+**Contents** (heading outline with per-section note counts; in directory mode,
+each document is a top-level node with its headings nested, click to switch
+docs) and **Files** (paths the plan touches, parsed from inline code and
+fences, badged **exists**/**new** against the repo; click jumps to the first
+mention, repeat clicks cycle) — the centered rendered plan (middle), and a
+**Review** rail (right) holding your notes and messages. The decisions live in
+a fixed bar along the bottom — `[Reject] ——— [Request revisions] [Approve]` —
+with a live summary of what rides along ("3 notes · 1 message will be sent").
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Step 1  RENDER     Plan renders centered in the browser, w/ TOC. │
+│  Step 2  ANNOTATE   Select text → a toolbar opens above it. Pick  │
+│                     a category (Comment / Issue / Question /       │
+│                     Suggestion / Nitpick) → the note input opens.  │
+│                     Or message the agent in the Review rail.       │
+│  Step 3  DECIDE     Bottom bar: Approve / Request Revisions /     │
+│                     Reject — with a note/message count summary.    │
+│  Step 4  RETURN     Decision + notes (each tagged with its        │
+│                     category and quoting its anchor) go back.     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Selecting text opens a floating **annotation toolbar** anchored above the
+selection (it flips below when there's no room). It starts as a category
+**menubar**; choosing a category expands it to reveal the note input and
+Save/Cancel. Saving highlights the text and anchors the note; clicking a
+highlight or a note cross-links the two. The page live-reloads when the plan
+file changes on disk (SSE + `fs.watch`).
+
+When the agent **revises** the plan, the tab doesn't silently swap the text: a
+banner reports the change (`+adds / -dels lines`) with a **View changes** toggle
+that shows a unified line diff (old vs. new, folding long unchanged runs), and
+the now-orphaned notes clear so the next round starts clean. Submitting a
+decision **clears your notes immediately** and replaces the decision bar's
+content with a confirmation that states what the agent does next
+(implement / revise / rework).
+
+## Guarantees (why it passes review)
+
+- **No egress.** Server binds `127.0.0.1` only; the HTML template embeds its own
+  markdown renderer and uses a system monospace font — no CDN, no web fonts, no
+  paste/share service. Audit: `grep -rE 'https?://' references/*.html` returns nothing.
+- **No dependencies.** `annotate-server.js` is Node stdlib only.
+- **Auditable.** One stdlib server + one self-contained HTML file. The UI is
+  styled after the **Terminus UI** design system (Button, Badge, Card, Textarea,
+  Popover) — adapted as vanilla CSS tokens + classes, no React, no bundle.

package/skills/subagent-execution/SKILL.md

@@ -77,7 +77,7 @@ Before Step 1, check the **Progress Ledger** (above) for already-completed tasks
 │                                                                  │
 │  Step 3: GROUP INTO A WAVE                                      │
 │  Among this round's unblocked tasks needing an agent, check     │
-│  references/safety-checklist.md (subagent-deployment skill);    │
+│  subagent-deployment/references/safety-checklist.md;            │
 │  tasks that clear it form one wave.                             │
 │                                                                  │
 │  Step 4: DISPATCH THE WAVE                                      │

package/skills/technical-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-spec
-description: Use when a feature plan, design session, or implementation milestone is complete and the decisions, API contracts, implementation details, and quirks should be persisted for future reference. Also use when the user says "save spec", "document this", "write up what we decided", or "spec this out".
+description: "Persists feature decisions, API contracts, implementation details, and quirks into a structured, queryable spec tree — one folder per feature, one file per concern. Invoke-only — discovery runs it at design sign-off and preflight's drift check reads its output; the user runs it via /technical-spec when they say \"save spec\", \"document this\", \"write up what we decided\", or \"spec this out\". Not for turning a rough idea into a design first — that's discovery."
 disable-model-invocation: true
 ---
 
@@ -46,42 +46,10 @@ Only create files that have actual content. Don't create empty files.
 
 ## Workflow
 
-```dot
-digraph save_spec {
-    rankdir=TB;
-    "Infer feature name from context" [shape=box];
-    "Feature name clear?" [shape=diamond];
-    "Ask user for feature name" [shape=box];
-    "Notify user — confirm before writing" [shape=box];
-    "User approves?" [shape=diamond];
-    "Stop" [shape=box];
-    "Run scaffold.sh <feature>" [shape=box];
-    "Output: exists or created?" [shape=diamond];
-    "Write content files, update index.md Contents" [shape=box];
-    "Read index.md, update changed files only" [shape=box];
-    "Ask: open live HTML preview?" [shape=diamond];
-    "Locate + run plan-review annotate-server.js on the spec dir" [shape=box];
-    "Tell user: Ctrl+C when done reviewing" [shape=box];
-    "Done" [shape=doublecircle];
-
-    "Infer feature name from context" -> "Feature name clear?";
-    "Feature name clear?" -> "Notify user — confirm before writing" [label="yes"];
-    "Feature name clear?" -> "Ask user for feature name" [label="no"];
-    "Ask user for feature name" -> "Notify user — confirm before writing";
-    "Notify user — confirm before writing" -> "User approves?";
-    "User approves?" -> "Stop" [label="no"];
-    "User approves?" -> "Run scaffold.sh <feature>" [label="yes"];
-    "Run scaffold.sh <feature>" -> "Output: exists or created?";
-    "Output: exists or created?" -> "Write content files, update index.md Contents" [label="created"];
-    "Output: exists or created?" -> "Read index.md, update changed files only" [label="exists"];
-    "Write content files, update index.md Contents" -> "Ask: open live HTML preview?";
-    "Read index.md, update changed files only" -> "Ask: open live HTML preview?";
-    "Ask: open live HTML preview?" -> "Locate + run plan-review annotate-server.js on the spec dir" [label="yes"];
-    "Ask: open live HTML preview?" -> "Done" [label="no"];
-    "Locate + run plan-review annotate-server.js on the spec dir" -> "Tell user: Ctrl+C when done reviewing";
-    "Tell user: Ctrl+C when done reviewing" -> "Done";
-}
-```
+Infer the feature name (ask if unclear) → confirm with the user before
+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.
 
 ## Required Notifications
 

package/skills/workflow/SKILL.md

@@ -170,7 +170,7 @@ Two tiers, split by durability — not by which skill produced them.
 | Tier | Where | Contents | Git |
 |---|---|---|---|
 | **Durable** | `<git-root>/specs/` | tech specs (`technical-spec`), browsable via `spec-browser` | committed |
-| **Working state** | `<git-root>/.condux/` | `designs/` · `plans/` · `progress/` · `scratch/` | gitignored |
+| **Working state** | `<git-root>/.condux/` | `designs/` · `plans/` · `progress/` · `scratch/` · `verification/` (live-verification evidence) | gitignored |
 
 The spec is what you keep; the design and plan are scaffolding for building
 it. Don't promote working state into `docs/` or the repo root — a project's