@hanzlaa/rcode 4.10.6 → 4.12.0

package/rcode/workflows/execute.md

@@ -202,7 +202,12 @@ Per-agent completion:
 ✓ rcode-executor complete: {plan-id} → SUMMARY.md ({N} commits)
 ```
 
-Closure:
+Closure: this banner is NOT printed here, right after the wave loop. It is
+gated behind `uat_gate` — see that step's "Only when `VERIFICATION_STATUS`
+is `pass`" branch, which is the only point in `<process>` where phase
+completion is actually confirmed (after code_review_gate, run_verify_commands,
+close_parent_artifacts, the regression gate, and verify_phase_goal have all
+passed):
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  rcode ► PHASE {NN} COMPLETE ✓
@@ -514,13 +519,15 @@ After all waves:
 ```markdown
 ## Phase {X}: {Name} Execution Complete
 
-**Waves:** {N} | **Plans:** {M}/{total} complete
+**Waves:** {N} | **Plans:** {M}/{total} executed
+
+Verification gates (run_verify_commands, code_review_gate, regression gate, uat_gate) have not run yet — this table reflects agent execution only, not verification.
 
 | Wave | Plans | Status |
 |------|-------|--------|
-| 1 | plan-01, plan-02 | ✓ Complete |
-| CP | plan-03 | ✓ Verified |
-| 2 | plan-04 | ✓ Complete |
+| 1 | plan-01, plan-02 | ✓ Executed |
+| CP | plan-03 | ✓ Checkpoint passed |
+| 2 | plan-04 | ✓ Executed |
 
 ### Plan Details
 1. **03-01**: [one-liner from SUMMARY.md]
@@ -823,7 +830,15 @@ fi
 2. Surface the tasks whose `<done>` criteria failed human verification.
 3. STOP. Don't mark complete on a failing verification.
 
-**Only when `VERIFICATION_STATUS` is `pass`** — proceed to `update_roadmap` below.
+**Only when `VERIFICATION_STATUS` is `pass`** — print the closure banner, then proceed to `update_roadmap` below:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► PHASE {NN} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+This is the only point in `<process>` where the banner may be emitted — never
+print it right after the wave loop finishes, and never before this gate
+resolves to `pass`.
 
 The previous behaviour (printing "Next Up: /rcode-verify-work" without state-gating) caused phases to reach `status: complete` without any human-verified UAT.
 </step>

package/rcode/workflows/help.md

@@ -198,7 +198,7 @@ init → new-project → plan → execute → next → status → ship
 | `/rcode-check-implementation-readiness` | Verify a feature is fully ready to implement before writing code. |
 | `/rcode-review-edge-case-hunter` | Hunt for edge cases and boundary conditions before execution. |
 | `/rcode-diagnose-issues` | Triage and diagnose systemic issues before a debug session. |
-| `/rcode-ui-phase <n>` | Generate UI design contract (UI-SPEC.md) for frontend phases. |
+| `/rcode-ui-phase <n>` | Generate UI design contract (UI-SPEC.md) and screen inventory (WIREFRAMES.md) for frontend phases. |
 | `/rcode-ui-review` | Retroactive 6-pillar visual audit of completed UI work. |
 | `/rcode-review --attack` | Hostile-perspective report — vulnerabilities, race conditions, abuse. |
 | `/rcode-review --edge-cases` | Enumerate edge cases by category and severity. |

package/rcode/workflows/new-milestone.md

@@ -541,7 +541,11 @@ Write files first, then return.
 
 **If `## ROADMAP BLOCKED`:** present the blocker, collect resolution from user, re-spawn the roadmapper with revision context.
 
-**If `## ROADMAP CREATED`:** read ROADMAP.md, present inline:
+**If `## ROADMAP CREATED`:**
+
+**Team review pass (once per roadmap draft; skip in auto/yolo mode — see `new-project-roadmap.md`'s identical step for the full rationale):** spawn `rcode-waleed` and `rcode-fatima` in parallel, same prompts as `new-project-roadmap.md`'s team review pass (feasibility sanity check / release-risk sanity check, 3 bullets max or "no concerns" in one line). Fold genuine concerns into a **Team Review Notes** section in the presentation below, before the phase table — skip the section if both say no concerns.
+
+Read ROADMAP.md, present inline:
 
 ```
 ## Proposed Roadmap

package/rcode/workflows/new-project-research.md

@@ -310,6 +310,28 @@ Display research complete banner and key findings:
 Files: `.planning/research/`
 ```
 
+**Mandatory stack-choice confirmation (before proceeding to roadmap):**
+Tech stack is the single most foundational, hardest-to-reverse decision in
+the project — every phase gets built on top of it, and un-picking it later
+means rework, not a config change. Do not let it get silently locked in.
+
+Check `.planning/research/STACK.md` for language indicating this was a
+judgment call, not a forced single-option pick — phrases like "judgment
+call," "flagging explicitly," a comparison table between 2+ named
+platforms/frameworks, or an explicit confidence caveat on the top-level
+choice. (A stack choice with genuinely no alternative — e.g. "must integrate
+with the client's existing Salesforce" — doesn't need this; skip only in
+that case, and say why.)
+
+If it's a judgment call, use AskUserQuestion before continuing:
+- **question:** "Research recommends {stack} over {alternative(s)} for {one-line reason}. Confirm, or pick differently?"
+- **options:** "Confirm {stack}" / "Use {alternative}" / "Something else — I'll specify"
+
+If the user picks differently, note the override as a decision and don't
+silently keep researching the original recommendation — the chosen stack
+from here on is whatever the user picked, not STACK.md's original
+recommendation, and downstream phases/roadmap should reflect that.
+
 **If "Skip research":** Continue to Step 7.
 
 

package/rcode/workflows/new-project-roadmap.md

@@ -215,6 +215,25 @@ Write files first, then return. This ensures artifacts persist even if context i
 
 **If `## ROADMAP CREATED`:**
 
+**Team review pass (once per roadmap draft, not per phase — keep this cheap; skip entirely in auto/yolo mode — an unattended loop shouldn't pay this round-trip on every roadmap, and there's no user present to read the notes anyway):**
+Before presenting the roadmap for approval, spawn two focused reviewers in
+parallel against the freshly-written ROADMAP.md — a single async round, not a
+council debate, so this adds one round-trip, not multiple:
+
+```
+Task(prompt="Read .planning/ROADMAP.md and .planning/PROJECT.md. As Waleed (CTO/architect), flag ONLY real feasibility/scalability concerns you'd actually block a real project over — a phase sequencing a schema-breaking change after the API that depends on it, a scale ceiling the phase structure doesn't account for, a missing foundational/shell phase for a UI project. If there are none, say so in one line. Keep it to 3 bullets max — this is a sanity check, not a full architecture review.", subagent_type="rcode-waleed", model="{roadmapper_model}", description="Architecture sanity check")
+
+Task(prompt="Read .planning/ROADMAP.md and .planning/PROJECT.md. As Fatima (QA Lead), flag ONLY real release-risk concerns — a phase with no way to verify its success criteria, a security/compliance-sensitive area with no phase covering it, a dependency ordering that makes a phase unverifiable until a later one lands. If there are none, say so in one line. Keep it to 3 bullets max — this is a sanity check, not a full QA strategy doc.", subagent_type="rcode-fatima", model="{roadmapper_model}", description="Release-risk sanity check")
+```
+
+Run both, collect their one-line-or-3-bullets responses. If either flags a
+concern that would make the roadmap actually wrong (not a nitpick), add a
+**Team Review Notes** section to the presentation below, before the phase
+table, so the user sees it as part of deciding whether to approve — don't
+silently drop it, and don't block on it either; the approval gate right
+after this is where the user decides what to do with it. If both reviewers
+say "no concerns," skip the section entirely — don't manufacture filler.
+
 Read the created ROADMAP.md and present it nicely inline:
 
 ```

package/rcode/workflows/plan-research-validation.md

@@ -204,7 +204,7 @@ HAS_UI=$?
 
 **If `HAS_UI` is 0 (frontend indicators found):**
 
-Check for existing UI-SPEC:
+Check for existing UI-SPEC (rcode-ui-phase produces this alongside WIREFRAMES.md as a pair, so its presence is a reliable proxy for both):
 ```bash
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```

package/rcode/workflows/plan.md

@@ -86,6 +86,37 @@ Project not initialized for planning. Run /rcode-new-project (full roadmap) or /
 
 Stop. Do not proceed until `project-status` returns `real`.
 
+## 0.6. Detect Frontend Keywords and Suggest UI Safety Gate
+
+```bash
+FRONTEND_KEYWORDS=$(node .rcode/bin/rcode-tools.cjs classify-tech --keywords "react,next.js,vue,tailwind,css,ui,component,design,frontend" "$ARGUMENTS")
+```
+
+**If `FRONTEND_KEYWORDS.has_frontend == true` AND `.rcode/UI-SPEC.md` is missing:**
+
+Check `config.yaml` for `workflow.ui_safety_gate` (default `true`). If enabled, print:
+
+```
+⚠ Frontend project detected. Before planning, create a design contract:
+
+/rcode-ui-phase
+
+This ensures consistent UI patterns, accessibility, and design tokens across all components.
+```
+
+Offer via AskUserQuestion:
+```
+header: "UI Safety Gate"
+question: "Should we define UI-SPEC.md before planning component development?"
+options:
+  - "Yes, run /rcode-ui-phase first"
+  - "Skip for now, continue planning"
+```
+
+If "Yes, run /rcode-ui-phase first": run `/rcode-ui-phase`, then return here and continue at Step 1. If skipped, or `ui_safety_gate` is disabled, or no frontend keywords detected: proceed directly to Step 1.
+
+See `rcode/workflows/ui-phase.md` Step 4 for the source of this step — this is the applied instance of that one-time setup instruction.
+
 ## 1. Initialize
 
 Load all context in one call (paths only to minimize orchestrator context):
@@ -594,12 +625,27 @@ Task(
 - **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
 - **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
 
-**Thinking partner for architectural tradeoffs (conditional):**
+**Thinking partner for architectural tradeoffs (default ON in guided mode, OFF in yolo/autonomous):**
 ```bash
-THINKING_PARTNER_ENABLED=$(node ".rcode/bin/rcode-tools.cjs" config-get features.thinking_partner 2>/dev/null || echo "false")
+THINKING_PARTNER_CONFIG=$(node ".rcode/bin/rcode-tools.cjs" config-get features.thinking_partner 2>/dev/null || echo "")
+if [ -n "$THINKING_PARTNER_CONFIG" ]; then
+  THINKING_PARTNER_ENABLED="$THINKING_PARTNER_CONFIG"
+elif [ "$MODE" = "yolo" ] || [ -n "$AUTONOMOUS" ]; then
+  THINKING_PARTNER_ENABLED="false"
+else
+  THINKING_PARTNER_ENABLED="true"
+fi
 ```
 ${THINKING_PARTNER_ENABLED === 'true' ? '@.rcode/references/plan-thinking-partner.md' : ''}
-If `features.thinking_partner` is disabled: skip this block entirely.
+If `THINKING_PARTNER_ENABLED` is `false`: skip this block entirely. An explicit
+`features.thinking_partner` in config.yaml always wins over the mode-based
+default (set it `false` to silence even in guided mode, or `true` to keep it
+on during autonomous runs if you want that). The check itself is cheap — a
+keyword scan over the checker's existing issues, not a new agent spawn —
+which is why it defaults on for guided/interactive planning: a second-opinion
+sanity check on architectural tradeoffs is exactly the kind of thing "does
+this actually get built right" needs, and it only activates when the checker
+already flagged a tradeoff-shaped issue.
 
 ## 12. Revision Loop (Max 3 Iterations, 1 in autonomous/yolo mode)
 

package/rcode/workflows/ship.md

@@ -121,6 +121,17 @@ Verify the work is ready to ship:
    Check for `status: passed` or `status: human_needed` (with human approval).
    If no VERIFICATION.md or status is `gaps_found`: warn and ask user to confirm.
 
+   **If proceeding with anything other than a clean `status: passed`** (i.e.
+   `human_needed` or a user-confirmed `gaps_found`): the generated PR body
+   (step below) MUST include a `## Known Gaps` section listing every
+   unresolved human-verification item or gap from VERIFICATION.md — mirroring
+   `complete-milestone.md`'s `### Known Gaps` pattern. This is not optional
+   cosmetic detail: a PR shipped on `human_needed`/`gaps_found` without this
+   section reads to a reviewer as fully verified when it isn't. Do not rely on
+   the `## Verification` section's item list alone (below) to carry this —
+   that section is easy to skim past; `## Known Gaps` must be its own
+   clearly-labeled heading.
+
 2. **Clean working tree?**
    ```bash
    git status --short
@@ -215,6 +226,17 @@ For each SUMMARY.md in the phase directory:
 - {human verification items from VERIFICATION.md, if any}
 ```
 
+**5b. Known Gaps section (only when VERIFICATION.md status is not a clean `passed`):**
+```markdown
+## Known Gaps
+
+This PR ships with `status: {human_needed|gaps_found}` per VERIFICATION.md, confirmed by the user in preflight.
+
+- {gap/human-verification item 1 — file/truth + what's unconfirmed}
+- {gap/human-verification item 2}
+```
+Omit this section entirely when VERIFICATION.md status is a clean `passed` with zero open items.
+
 **6. Decisions section:**
 ```markdown
 ## Key Decisions

package/rcode/workflows/ui-phase.md

@@ -1,11 +1,11 @@
 # Workflow: rcode-ui-phase
 
 <purpose>
-Produce UI-SPEC.md with formalized design contract: color tokens, typography system, component inventory, interaction states, accessibility requirements. Detects frontend keywords (React, Next.js, Vue, Tailwind, CSS, UI) and suggests this workflow early if UI-SPEC.md is absent.
+Produce two artifacts before any UI code gets written: UI-SPEC.md (formalized design contract — color tokens, typography, component inventory, interaction states, accessibility requirements) and WIREFRAMES.md (per-role screen inventory — what exists, who sees it, loading/empty/error states for each). Grounds design choices in `rcode/references/design-library/` (vendored style/palette/typography/UX-rules data — see that directory's README) instead of an agent inventing tokens from nothing. Detects frontend keywords (React, Next.js, Vue, Tailwind, CSS, UI) and suggests this workflow early if UI-SPEC.md is absent.
 </purpose>
 
 
-## Step 0 — Usage check
+## Step 0a — Usage check
 
 If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 
@@ -25,7 +25,7 @@ STOP — do not proceed.
 - `rcode-ux-designer` — UI specification generator
 </available_agent_types>
 
-## Step 0 — Initialize
+## Step 0b — Initialize
 
 ```bash
 INIT=$(node .rcode/bin/rcode-tools.cjs init ui-phase "$ARGUMENTS" 2>/dev/null)
@@ -41,6 +41,7 @@ Parse:
 - `flags.existing_ui` — path to existing design system or Figma export
 - `flags.design_system` — path to design tokens file
 - `ui_spec_path` — `.rcode/UI-SPEC.md` (output location)
+- `wireframes_path` — `.rcode/WIREFRAMES.md` (output location)
 
 ## Step 1 — Detect Existing UI Assets
 
@@ -49,47 +50,194 @@ If `flags.existing_ui` or `flags.design_system` provided:
 EXISTING=$(node .rcode/bin/rcode-tools.cjs find-files --type=design-tokens)
 ```
 
-Load existing design system, extract:
+Load existing design system, extract into `EXISTING_DESIGN_SYSTEM_DATA` (a text block passed verbatim into Step 2b's prompt):
 - Color palette (hex, variable names)
 - Typography scales (font family, sizes, weights, line heights)
 - Component list (buttons, forms, layouts, modals, etc.)
 - Interaction patterns (hover, focus, active, disabled states)
 
-## Step 2 — Spawn UI Designer
+If `$EXISTING` is empty or extraction finds nothing usable, treat this the
+same as "no existing system found" and fall through to Step 1b — don't leave
+`EXISTING_DESIGN_SYSTEM_DATA` half-populated.
+
+If an existing design system was found and `EXISTING_DESIGN_SYSTEM_DATA` is
+populated, there's nothing to choose between — skip Step 1b, Step 1c, AND
+Step 2 (variant generation + user confirmation) entirely, and go straight to
+Step 2b using `EXISTING_DESIGN_SYSTEM_DATA` as the chosen direction.
+
+## Step 1b — Ground the design in the reference library (no existing system found)
+
+Don't let the agent invent a palette/style from nothing. If PROJECT.md and
+ROADMAP.md are both missing, stop here and say so: "No PROJECT.md/ROADMAP.md
+found — run `/rcode-new-project-research` or `/rcode-new-project-roadmap`
+first so there's a project category to ground the design in." Otherwise look up:
+
+1. **Category match** — grep the project's category (from PROJECT.md/ROADMAP.md — e.g. "B2B SaaS Enterprise", "Analytics Dashboard", "Fintech (Banking)") against `rcode/references/design-library/ui-reasoning.csv`'s `UI_Category` column. This returns a recommended style/color-mood/typography-mood and explicit anti-patterns to avoid — read the row, don't guess a category if none matches closely; fall back to the closest match and say so. Capture the result as `CATEGORY_MATCH`.
+2. **Style detail** — take the recommended style name from step 1 and look it up in `styles.csv` for concrete hex values, effects, accessibility rating, and an implementation checklist. Capture as `STYLE_DETAIL`.
+3. **UX rules** — grep `ux-guidelines.csv` for the categories relevant to this project's screens (Navigation, Forms, etc.) for concrete do/don't rules with code examples. Capture as `UX_RULES`.
+
+`CATEGORY_MATCH` + `STYLE_DETAIL` + `UX_RULES` together are what Step 1c and
+Step 2 below call `DESIGN_LOOKUP_RESULT` — assemble them into one text block.
+
+## Step 1c — Look at real reference sites (skip only if Step 1 found an existing system)
+
+A CSV row is a starting hypothesis, not a substitute for actually looking at
+what real sites in this space look like. A style-data table can't tell you
+that every competitor uses a specific hero-image treatment, or that the
+category's "expected" look has drifted since the data was written. Do this
+before committing to a direction:
+
+1. **Find real reference sites.** WebSearch for the project's actual
+   industry/niche (from PROJECT.md — e.g. "best interior design websites
+   Pakistan", "top mobile repair shop websites", not a generic "SaaS
+   landing page examples" search unrelated to the real domain). Aim for
+   3-5 real, currently-live sites — direct competitors if findable, strong
+   examples in the same category otherwise.
+2. **Actually look at them**, don't just read search-result snippets. If a
+   browser tool is available in this session, navigate to each and take a
+   screenshot. If not, WebFetch each URL and read the rendered content/
+   structure description it returns. Note concretely, per site: layout
+   pattern (hero style, nav placement, content density), color mood, type
+   feel (serif/sans, weight, size), imagery style (photography vs.
+   illustration vs. none), and anything that reads as dated or as a
+   red flag to avoid repeating.
+3. Capture this as `REFERENCE_SITE_FINDINGS` — a short per-site note, not a
+   full audit. This feeds variant generation next, not a standalone report.
+
+If WebSearch/WebFetch/browser tools are genuinely unavailable in this
+session, skip with an explicit note ("Step 1c skipped — no web/browser
+tools available; design-library data only") rather than silently omitting
+real-site grounding — this is a real reduction in design quality and should
+be visible, not silent.
+
+## Step 2 — Generate design variants, get user confirmation (mandatory — do not skip to a single locked-in direction)
+
+Visual design direction is the same class of decision as tech-stack choice:
+foundational, expensive to redo once screens are built against it, and a
+matter of taste as much as data — it must not get silently locked in by an
+agent picking "the" recommended style. Generate 2-3 concrete, genuinely
+distinct variants (not the same direction with a different accent color),
+each grounded in `DESIGN_LOOKUP_RESULT` (Step 1b) and `REFERENCE_SITE_FINDINGS`
+(Step 1c), before writing anything to UI-SPEC.md:
 
 Spawn `rcode-ux-designer` subagent:
 
 ```
 Task tool call:
   subagent_type: "rcode-ux-designer"
-  description: "Generate UI-SPEC.md"
+  description: "Generate design variants"
   prompt: |
-    Generate a UI-SPEC.md file with the following structure:
-    
-    1. **Color Tokens** — semantic variable names, hex values, accessibility contrast ratios
-    2. **Typography** — font family, scales (12px, 14px, 16px, 18px, 20px, 24px, etc.), weights, line heights
-    3. **Component Inventory** — list of UI components with property variants (size, color, state, disabled)
-    4. **Interaction States** — hover, focus, active, disabled, loading for interactive elements
-    5. **Accessibility** — WCAG 2.1 AA compliance checklist, color contrast requirements, keyboard navigation rules
-    6. **Responsive Breakpoints** — mobile, tablet, desktop breakpoints and stacking rules
-    
-    {existing_design_system_data_if_provided}
-    
+    Ground every variant in {EXISTING_DESIGN_SYSTEM_DATA if Step 1 found one, else DESIGN_LOOKUP_RESULT + REFERENCE_SITE_FINDINGS} —
+    do not invent a palette/style from nothing when reference data or real
+    reference sites were found.
+
+    Propose 2-3 genuinely distinct design variants for this project. For each:
+    - **Name** (short, e.g. "Warm Editorial", "Minimal Trust", "Bold Craft")
+    - **One-paragraph description** — mood, layout approach, what it borrows from
+      the reference sites found (name which one(s)) vs. the design-library data
+    - **Color direction** — 2-3 representative hex values, not a full token system yet
+    - **Typography direction** — font pairing feel (serif/sans, weight)
+    - **Best for / worst for** — one line each, honest tradeoffs
+
+    Do NOT pick a winner or rank them — present as genuine options. Do NOT
+    write UI-SPEC.md yet.
+
+    Return the variants as your response text (not a file write).
+```
+
+Present the variants to the user via AskUserQuestion:
+- **question:** "Which design direction fits this project?"
+- **options:** one per variant (label = variant name, description = the one-paragraph summary), plus the tool's built-in "Other" for a custom direction
+- If the user picks "Other" and describes something different, treat their description as the chosen direction instead of any generated variant.
+
+Only after the user picks does Step 2b below proceed — using the chosen
+variant's color/typography direction as the seed for the full spec, not
+re-deriving from scratch.
+
+## Step 2b — Spawn UI Designer (full spec, chosen direction)
+
+Spawn `rcode-ux-designer` subagent:
+
+```
+Task tool call:
+  subagent_type: "rcode-ux-designer"
+  description: "Generate UI-SPEC.md and WIREFRAMES.md"
+  prompt: |
+    Build out the full spec from {EXISTING_DESIGN_SYSTEM_DATA if Step 1 found
+    one, else the user-chosen variant's full description, color direction,
+    and typography direction from Step 2}.
+    Ground every choice in {EXISTING_DESIGN_SYSTEM_DATA if Step 1 found one, else DESIGN_LOOKUP_RESULT from Step 1b} —
+    do not invent a palette/style from nothing when reference data or an existing system exists.
+
+    Write UI-SPEC.md with:
+    1. **Design Direction** — which style/category this follows (from the reference library lookup) and why, one paragraph
+    2. **Color Tokens** — semantic variable names, hex values, accessibility contrast ratios
+    3. **Typography** — font family, scales (12px, 14px, 16px, 18px, 20px, 24px, etc.), weights, line heights
+    4. **Component Inventory** — list of UI components with property variants (size, color, state, disabled)
+    5. **Interaction States** — hover, focus, active, disabled, loading for interactive elements
+    6. **Accessibility** — WCAG 2.1 AA compliance checklist, color contrast requirements, keyboard navigation rules
+    7. **Responsive Breakpoints** — mobile, tablet, desktop breakpoints and stacking rules
+
     Write to: {ui_spec_path}
 ```
 
+## Step 2c — Spawn Wireframes (per-role screen inventory)
+
+Read REQUIREMENTS.md/PROJECT.md for the project's user roles (if any) and the
+IA decision — `roadmapper-playbook.md`'s Information Architecture step (Workflow
+step 3b) says this is persisted as either a standalone `.planning/IA.md` or a
+`## Information Architecture` section in ROADMAP.md, so check both locations,
+not just ROADMAP.md. If neither has an IA decision, this step cannot produce a
+real result — stop and say so: "No Information Architecture decision found in
+ROADMAP.md or IA.md — the roadmapper needs to produce one first
+(`/rcode-new-project-roadmap` for a brand-new project, `/rcode-new-milestone`
+to regenerate the roadmap for an existing one — both invoke rcode-roadmapper,
+which owns the IA step)."
+
+Spawn `rcode-ux-designer` subagent (same agent, second artifact):
+
+```
+Task tool call:
+  subagent_type: "rcode-ux-designer"
+  description: "Generate WIREFRAMES.md"
+  prompt: |
+    For each top-level IA section and each screen it contains, write one entry:
+
+    ### {Screen name} — {route/path}
+    **Roles that see it:** {role list, or "all authenticated users"}
+    **Purpose:** {one line — what the user accomplishes here}
+    **Layout:** {ASCII or textual wireframe — header/nav placement, primary content
+    area, key actions, not a pixel-perfect mockup}
+    **Required states** (do not omit any that apply):
+    - Loading: {what renders while data is fetching}
+    - Empty: {what renders when there's no data yet — never a blank screen}
+    - Error: {what renders on fetch/action failure — never a silent failure}
+    - Success/populated: {the normal case}
+    **Primary actions:** {buttons/links a user takes from here, and where they go}
+
+    Cover EVERY screen implied by the roadmap's phases, not just Phase 1's.
+    A screen with no role that can see it, or with only a "populated" state and
+    no loading/empty/error state defined, is an incomplete entry — fix it before
+    writing, don't ship the gap.
+
+    Write to: {wireframes_path}
+```
+
 ## Step 3 — Store Reference in State
 
-Update state with UI-SPEC.md location:
+Update state with both artifact locations:
 ```bash
 node .rcode/bin/rcode-tools.cjs state set --ui-spec-path ".rcode/UI-SPEC.md"
+node .rcode/bin/rcode-tools.cjs state set --wireframes-path ".rcode/WIREFRAMES.md"
 ```
 
 Print:
 ```
 ✓ UI-SPEC.md generated: {ui_spec_path}
+✓ WIREFRAMES.md generated: {wireframes_path}
 
-Contains:
+UI-SPEC.md contains:
+  • Design Direction (grounded in design-library lookup, not invented)
   • Color Tokens
   • Typography System
   • Component Inventory
@@ -97,10 +245,22 @@ Contains:
   • Accessibility Checklist
   • Responsive Breakpoints
 
-This spec will guide component development and design consistency.
+WIREFRAMES.md contains:
+  • Every screen from the roadmap's IA, with role visibility
+  • Loading/empty/error/success state for each screen — no screen ships
+    without all four defined
+
+These specs guide component development, design consistency, and give
+sprint-checker something concrete to verify state-completeness against.
 ```
 
-## Step 4 — Modify plan.md Detection (referenced in plan workflow)
+## Step 4 — Modify plan.md Detection (one-time setup, not per-invocation)
+
+This step is setup documentation for `plan.md`, not part of `/rcode-ui-phase`'s
+own run sequence — it does not re-run every time `/rcode-ui-phase` is
+invoked. Before applying it, check whether `plan.md` already has this
+detection step (grep for "ui_safety_gate" or "Detect frontend keywords");
+skip if present.
 
 In plan.md workflow, add Step 0.6 — **Detect frontend keywords and suggest UI safety gate**
 
@@ -141,17 +301,21 @@ Run /rcode-ui-phase, then return to /rcode-plan
 
 ## Success Criteria
 
-- UI-SPEC.md created with all 6 sections
+- Real reference sites looked at (Step 1c), not just design-library data alone — or explicitly noted as skipped with a reason
+- 2-3 genuinely distinct design variants presented and the user explicitly picked one via AskUserQuestion — no direction silently locked in (skipped only when Step 1 found an existing design system, where there's nothing to choose between)
+- UI-SPEC.md created with all 7 sections, design direction grounded in the chosen variant / `design-library/` lookup / real reference sites (or an existing design system), not invented
 - Color tokens documented with contrast ratios
 - Component inventory complete with variants
 - Accessibility checklist included
-- State updated with UI-SPEC.md path
+- WIREFRAMES.md created covering every screen implied by the roadmap's IA, each with role visibility and all four states (loading/empty/error/success) defined
+- State updated with both UI-SPEC.md and WIREFRAMES.md paths
 
 ## On Error
 
 - If subagent fails: provide template UI-SPEC.md
 - If frontend detection fails: skip suggestion
 - If config.yaml missing ui_safety_gate: default to true (suggest)
+- If no IA decision exists in ROADMAP.md or IA.md yet: WIREFRAMES.md cannot be produced meaningfully — stop Step 2c and say so rather than writing a screen list with no basis
 
 ## Next Up
 

package/rcode/workflows/ui-review.md

@@ -1,7 +1,7 @@
 # Workflow: rcode-ui-review
 
 <purpose>
-Retroactively audit completed UI work against the UI-SPEC.md contract. Validates across 6 pillars: color consistency, typography compliance, component inventory coverage, accessibility requirements, responsive behavior, and design coherence. Produces audit report with pass/fail per pillar.
+Retroactively audit completed UI work against the UI-SPEC.md contract (and WIREFRAMES.md, when present, for per-screen state coverage). Validates across 6 pillars: color consistency, typography compliance, component inventory coverage, accessibility requirements, responsive behavior, and design coherence. Produces audit report with pass/fail per pillar.
 </purpose>
 
 
@@ -41,6 +41,7 @@ Parse:
 - `flags.phase` — audit specific phase (optional, default: all completed phases)
 - `flags.detailed` — include detailed findings per component
 - `spec_path` — load UI-SPEC.md if exists
+- `wireframes_path` — load WIREFRAMES.md if exists (optional; used for per-screen state coverage)
 - `phase_name` — phase to audit
 
 ## Step 1 — Validate UI-SPEC.md Exists
@@ -65,6 +66,10 @@ Read UI-SPEC.md for:
 - Accessibility requirements
 - Responsive breakpoints
 
+If `.rcode/WIREFRAMES.md` exists, also read it for the per-role screen inventory and
+required states (loading/empty/error/success) — missing states become findings under
+Component Inventory or Design Coherence.
+
 Scan phase/codebase for:
 - Component files (*.tsx, *.jsx, *.vue)
 - CSS/styling files (*.css, *.module.css, tailwind.config.js, etc.)
@@ -85,6 +90,9 @@ Task tool call:
     **UI-SPEC.md Reference:**
     {contents_of_ui_spec_md}
     
+    **WIREFRAMES.md Reference (if present):**
+    {contents_of_wireframes_md}
+    
     **Codebase to Audit:**
     {component_files_list}
     {styling_rules}

package/rcode/workflows/verify-work.md

@@ -117,7 +117,7 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 **If Playwright-MCP tools are available in this session (`mcp__playwright__*` tools
 respond to tool calls) AND (`UI_PHASE_FLAG` is `true` OR `UI_SPEC_FILE` is non-empty):**
 
-For each UI checkpoint listed in the phase's UI-SPEC.md (or inferred from SUMMARY.md):
+For each UI checkpoint listed in the phase's UI-SPEC.md and WIREFRAMES.md (screen states — loading/empty/error/success), or inferred from SUMMARY.md if neither exists:
 
 1. Use `mcp__playwright__navigate` (or equivalent) to open the component's URL.
 2. Use `mcp__playwright__screenshot` to capture a screenshot.

package/server/lib/scanner.js

@@ -133,6 +133,16 @@ function buildPhaseTree(projectDir, rawPhases, listCached, overrides) {
     if (!sprintFiles.length) return p;
 
     const phaseComplete = /complete|done/i.test(p.status || '');
+    // Story status must not cascade blindly from the phase's self-reported
+    // status (#gap: dashboard-truthfulness). A phase marked 'complete' in
+    // state.json is unverified until its own VERIFICATION.md says so — only
+    // then do we let stories inherit 'done'. Otherwise stories stay 'todo'
+    // even if the phase claims completion, so the board never shows a green
+    // checkmark with zero independent evidence behind it.
+    const verificationFile = files.find(f => /-VERIFICATION\.md$/i.test(f));
+    const verificationText = verificationFile ? (safeReadText(path.join(phasesDir, dir.name, verificationFile)) || '') : '';
+    const phaseVerified = phaseComplete && /status:\s*passed/i.test(verificationText);
+    const storyStatus = phaseVerified ? 'done' : 'todo';
     const sprints = sprintFiles.map(f => {
       const m   = f.match(/^(\d+)-(\d+)-SPRINT\.md$/i);
       const num = m ? parseInt(m[2], 10) : 0;
@@ -163,7 +173,7 @@ function buildPhaseTree(projectDir, rawPhases, listCached, overrides) {
         const story = {
           id:     idM ? idM[1] : `${sid}-task-${stories.length + 1}`,
           title:  (titleAttrM && titleAttrM[1].trim()) || (titleTagM && titleTagM[1].trim()) || `Task ${stories.length + 1}`,
-          status: phaseComplete ? 'done' : 'todo',
+          status: storyStatus,
         };
         if (ov[story.id]) story.status = ov[story.id].status;
         if (acM && acM[1].trim()) story.acceptance = acM[1].trim();
@@ -187,7 +197,7 @@ function buildPhaseTree(projectDir, rawPhases, listCached, overrides) {
           stories.push({
             id:     hId,
             title:  hm[2].trim(),
-            status: ov[hId] ? ov[hId].status : (phaseComplete ? 'done' : 'todo'),
+            status: ov[hId] ? ov[hId].status : storyStatus,
           });
         }
       }
@@ -217,7 +227,11 @@ function buildPhaseTree(projectDir, rawPhases, listCached, overrides) {
       }).filter(depId => depId !== null && depId !== intId)
     )];
 
-    return { ...p, sprints, dependsOn: phaseDependsOn };
+    // Surface the same verification check at the phase level so consumers of
+    // the tree (phases list, progress %, currentPhase, milestones) can also
+    // avoid trusting a self-reported 'complete' status blindly — not just the
+    // per-story cascade above. null when the phase doesn't claim completion.
+    return { ...p, sprints, dependsOn: phaseDependsOn, verified: phaseComplete ? phaseVerified : null };
   });
 }
 
@@ -278,7 +292,14 @@ function buildDashboard(state) {
     const range = started || completed
       ? [fmtShort(started), fmtShort(completed)].filter(Boolean).join(' – ')
       : '';
-    return { ...p, name: p.name || p.slug || String(p.id || ''), range, state: toState(p.status) };
+    // A phase self-reporting 'complete' without a passing *-VERIFICATION.md
+    // (p.verified === false, set by buildPhaseTree) is downgraded to 'active'
+    // rather than shown as 'done' — the dashboard must not render a green
+    // checkmark, fill the progress bar, or skip a phase as currentPhase on
+    // an unconfirmed status alone (same drift class as the sprint-level check).
+    let phaseState = toState(p.status);
+    if (phaseState === 'done' && p.verified === false) phaseState = 'active';
+    return { ...p, name: p.name || p.slug || String(p.id || ''), range, state: phaseState };
   }).sort((a, b) => (parseFloat(a.id ?? a.number) || 0) - (parseFloat(b.id ?? b.number) || 0));
 
   // ---- progress (prefer story counts; fall back to phase-level counts) ----