@hanzlaa/rcode 4.10.6 → 4.11.0

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,12 +50,33 @@ 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 2'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)
 
+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, skip Step 1b (don't override what's already decided) and go straight to Step 2.
+
+## 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 2's
+prompt calls `DESIGN_LOOKUP_RESULT` below — assemble them into one text block
+before spawning the agent.
+
 ## Step 2 — Spawn UI Designer
 
 Spawn `rcode-ux-designer` subagent:
@@ -62,34 +84,80 @@ Spawn `rcode-ux-designer` subagent:
 ```
 Task tool call:
   subagent_type: "rcode-ux-designer"
-  description: "Generate UI-SPEC.md"
+  description: "Generate UI-SPEC.md and WIREFRAMES.md"
   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 choice below 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 2b — 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 +165,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 +221,19 @@ Run /rcode-ui-phase, then return to /rcode-plan
 
 ## Success Criteria
 
-- UI-SPEC.md created with all 6 sections
+- UI-SPEC.md created with all 7 sections, design direction grounded in `design-library/` lookup (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 2b 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) ----