@hanzlaa/rcode 4.10.5 → 4.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.10.5",
+  "version": "4.11.0",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/agents/rcode-project-researcher.md

@@ -89,7 +89,7 @@ Named rules. Cite by name when applying.
 ## Workflow
 
 1. **Read `<files_to_read>` block** — mandatory before any other action.
-2. **Understand the domain** — what ecosystem is this? What are the key libraries, frameworks, competitors?
+2. **Understand the domain** — what ecosystem is this? What are the key libraries, frameworks, competitors? Also verify: what roles/permission model does this project need (single-user, multi-role, multi-tenant)? What auth mechanism/provider fits (e.g. Clerk, Auth0, NextAuth, custom JWT)? What languages/locales must the project support (single-locale, i18n from day one, RTL)? Record findings in STACK.md's Auth & Identity and Localization rows — don't let this surface only implicitly in FEATURES.md or ARCHITECTURE.md.
 3. **Verify current state** — Context7 or official docs for critical technology claims. Flag LOW confidence for training-only findings.
 4. **Select research mode** — Ecosystem (default) / Feasibility / Comparison.
 5. **Write 5 output files** in `.rcode/research/`:

package/rcode/agents/rcode-ux-designer.md

@@ -29,6 +29,7 @@ Named rules. Cite by name when applying.
 - **10th-time-user** — delight happens through invisible efficiency. Design for the person who has done this 10 times, not just the first-timer.
 - **Ship-then-layer** — recommend the simplest version that ships, then layer complexity. Perfect designs that never launch are zero value.
 - **Name-one-misconception** — for every confusing design element, name the specific misconception and design around it.
+- **Library-not-invention** — when producing UI-SPEC.md or WIREFRAMES.md, ground tokens and palette choices in `rcode/references/design-library/`, not invented values. WIREFRAMES.md's loading/empty/error/populated coverage per screen is Silence-kills-trust made concrete, per-screen.
 
 ## Anti-Patterns / Refuse List
 

package/rcode/agents/rcode-verifier.md

@@ -26,8 +26,8 @@ Goal-backward verification. Start from what the phase SHOULD deliver, verify it
 - **DO NOT assume existence = implementation** — need level 2 (substantive), 3 (wired), and 4 (data flowing) for dynamic-data artifacts.
 - **DO NOT skip key link verification** — 80% of stubs hide in wiring.
 - **Structure gaps in YAML frontmatter** for `/rcode-plan --gaps`.
-- **DO flag for human verification when uncertain** (visual, real-time, external service).
-- **Keep verification fast** — use grep/file checks, not running the app.
+- **DO flag for human verification when uncertain** (visual, real-time, external service) — but flagging is NOT a pass. A phase with unresolved human-verification items on its user-facing surface is NOT "complete" or "shippable"; say so explicitly in the summary you return to the orchestrator.
+- **Static checks (grep/file-existence) stay fast for levels 1-3 — but a UI-facing phase is not verified until Level 5 (Reachability, see `reachability-check.md`) runs.** A page component existing, importing cleanly, and rendering real data is not the goal — a real user finding and using it from the app's actual navigation is. Don't let "keep it fast" become "never open the app."
 - **DO NOT commit** — leave committing to the orchestrator.
 - **Use Write tool for VERIFICATION.md** — never `Bash(cat << 'EOF')`.
 

package/rcode/agents/rules/planner/common-patterns.md

@@ -23,11 +23,12 @@ Plan X.2 (Wave 1): API Endpoint
 Plan X.3 (Wave 2): UI Form/Component
   - Build React component
   - Wire to API endpoint
+  - Wire route into nav/menu (sidebar, header, or route table) so the feature is reachable without a direct URL
   - Integration test: form → API → database
 
 Plan X.4 (Wave 3): End-to-End Verification
   - Test full user flow (UI → API → DB → UI)
-  - Checkpoint: Visual/functional review
+  - Checkpoint: Visual/functional review — can you reach this feature from the main nav without a direct URL?
 ```
 
 **Dependencies:** 1.3 → {1.1, 1.2}, 1.4 → 1.3

package/rcode/agents/rules/planner/goal-backward-thinking.md

@@ -38,6 +38,37 @@ Must be TRUE:
 
 **Test:** Each truth verifiable by a human using the application without reading code.
 
+**UI goals — add a reachability truth.** If any artifact for this goal is a page, route, or screen a user navigates to, one of the truths must be that the user can reach it through existing navigation, not just that it works once they're on it:
+- "User can reach {feature} from existing navigation without typing the URL directly"
+
+This must carry through to Step 3 (a nav component — header, sidebar, menu — is a required artifact alongside the new page) and Step 5 (a key link from that nav component to the new route). A feature that functions perfectly at an orphan route with no menu entry or link pointing to it does not satisfy the goal.
+
+**Nav artifact precondition.** "Nav/menu component updated with a link" is not itself a valid artifact — it is single-role and structure-agnostic, and satisfying it by bolting one more top-level `<a>` onto whatever markup exists guarantees IA drift across phases. Before writing that artifact line:
+- Reference the existing IA decision (the ROADMAP-level nav/IA plan) that this route slots into. If no IA doc exists yet — this is genuinely the first UI phase — this phase must produce one (containers, nesting levels, role visibility) before the nav artifact can be written; do not defer it to a later phase.
+- State which nav container the link belongs in (e.g. sidebar primary, topbar, settings submenu), not just "the nav."
+- State the nesting depth (top-level vs. nested under an existing section).
+- State which roles see it, if the app has more than one role.
+
+**Multi-role goals — add a role-visibility truth.** If the project has more than one user role/permission level (per REQUIREMENTS.md/PROJECT.md), one of the truths must state what that role sees or cannot see on screen — nav items, dashboard content, visible/hidden fields, enabled/disabled actions — not only what API calls it can or cannot make:
+- "Employee sees only their own timesheet in nav; Manager additionally sees a Team Approvals nav item; Admin additionally sees a Users/Roles admin screen."
+
+A truth like "User can't access protected pages without logging in" covers the route gate but not RBAC — it says nothing about what an authenticated Employee vs Manager vs Admin actually sees. RBAC = each role has a different UI, not just a blocked route.
+
+**Example: Settings Page Goal**
+
+Must be TRUE:
+- User can view and edit their profile settings
+- Changes save and persist
+- User can reach the settings page from existing navigation without typing the URL directly
+
+Artifacts:
+- Settings page component
+- Settings API route
+- Nav/menu component updated with a link to the settings route, per existing IA plan: sidebar primary nav, top-level, visible to all authenticated roles
+
+Key link:
+- Nav component → `/settings` route link → if broken: page works but is undiscoverable
+
 ---
 
 ## Step 3: Derive Required Artifacts
@@ -161,6 +192,7 @@ must_haves:
 5. User stays logged in after page refresh
 6. User can log out
 7. User can't access protected pages without logging in
+8. Each role sees a different UI: Employee's nav shows only their own timesheet; Manager's nav additionally shows Team Approvals; Admin's nav additionally shows a Users/Roles admin screen
 
 ### Artifacts Needed
 - Login form component
@@ -169,6 +201,7 @@ must_haves:
 - User database model
 - Session/JWT infrastructure
 - Protected route wrapper
+- Role-aware nav component (renders nav items conditionally per role)
 
 ### Wiring
 - Form → API endpoint

package/rcode/agents/rules/planner/sprint-verification.md

@@ -41,6 +41,7 @@ Before outputting a SPRINT.md file, run this self-check to catch common planning
 - [ ] No references to files that don't exist
 - [ ] Every task references concrete, existing file paths
 - [ ] Context bloat < 50% (if context section > 300 lines, trim it)
+- [ ] If any artifact is a new page/route/screen, at least one truth/key_link covers reachability from existing navigation (or explicitly notes it is intentionally direct-link-only)
 
 ### Objective & Output
 

package/rcode/agents/rules/planner/task-templates.md

@@ -181,17 +181,36 @@ Use for unavoidable manual steps (1% of checkpoints).
     5. Success behavior: call onSubmit({ email, password })
     6. Use Sonner toast on error (not alert())
     7. Disabled state during submission (no double-click)
+    8. Navigation wiring: add entry to nav/menu component so page is reachable
+       without direct URL (skip only if this task does not introduce a new
+       route/page)
   </action>
   <verify>
     <automated>npm test -- --filter=LoginForm</automated>
+    <automated>grep -r "login" src/components/nav/ src/config/routes*</automated>
   </verify>
   <done>
     Component renders, accepts input, calls onSubmit, disables during submission,
-    shows errors with toast notification
+    shows errors with toast notification, page is reachable from nav/menu
+    (not just direct URL)
   </done>
 </task>
 ```
 
+**Required states for any component that fetches or displays dynamic data**
+(list views, dashboards, detail pages — not static content): the `<action>`
+and `<done>` must each name all four, not just the happy path:
+- **Loading** — what renders while data is in flight (skeleton, spinner — not a blank screen)
+- **Empty** — what renders when the fetch succeeds but returns nothing (a message + next action, not a blank screen)
+- **Error** — what renders when the fetch/action fails (specific, not a generic "something went wrong")
+- **Populated** — the normal case
+
+A task whose `<done>` only describes the populated case ("shows the list of
+items") is incomplete for any component with a real data dependency — sprint-
+checker's Dimension 2 now flags this (see `sprint-checker/dimensions.md`).
+If WIREFRAMES.md exists for this screen (`/rcode-ui-phase` output), copy its
+per-state description here rather than re-deriving it.
+
 ---
 
 ## Configuration Task Template

package/rcode/agents/rules/project-researcher/detailed-guide.md

@@ -207,6 +207,16 @@ Based on research, suggested phase structure:
 |------------|---------|---------|-----|
 | [tech] | [ver] | [what] | [rationale] |
 
+### Auth & Identity
+| Technology | Version | Purpose | Why |
+|------------|---------|---------|-----|
+| [tech] | [ver] | [roles/auth mechanism] | [rationale] |
+
+### Localization
+| Technology | Version | Purpose | Why |
+|------------|---------|---------|-----|
+| [tech] | [ver] | [locales/i18n mechanism] | [rationale] |
+
 ### Supporting Libraries
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|

package/rcode/agents/rules/sprint-checker/dimensions.md

@@ -47,6 +47,24 @@ issue:
 - Missing `<done>` — no acceptance criteria
 - Vague `<action>` — "implement auth" instead of specific steps
 - Empty `<files>` — what gets created?
+- `<verify>` present but not semantically capable of proving the task's claim — see check below
+
+**Check — Verify Semantically Matches Claim (links to Dimension 6):**
+Presence of `<verify>` is not enough. Cross-check it against the must_haves truth the task claims to satisfy (Dimension 6):
+- If the task's `<action>` implements user-observable behavior (login, checkout, search, any flow a user drives), a `<verify>` consisting only of build/lint/typecheck commands (`npm run build`, `tsc --noEmit`, `eslint`, `echo done`) does **not** satisfy this dimension — it proves the code compiles, not that the behavior works.
+- Require instead an assertion against actual output/behavior: a curl/HTTP call checking status/body, a test that exercises the route or flow, or an explicit manual-verification checkpoint (`checkpoint:*` task type).
+- Flag as blocker: "Task N's <verify> only compiles/lints but action implements user-facing behavior X — no assertion on actual behavior."
+
+**Check — Required States for Dynamic-Data Components:**
+If a task's `<action>` creates or modifies a component that fetches or
+displays dynamic data (a list, dashboard, detail page — check for
+fetch/query/API-call language in the action), its `<action>` and `<done>`
+must each name all four states: loading, empty, error, populated. A task
+whose `<done>` only describes the populated case ("shows the list of items")
+is incomplete — flag as blocker, not warning, since a missing empty/error
+state is a real UX gap a user will hit, not a style nitpick.
+- Flag as blocker: "Task N's component fetches/displays dynamic data but `<action>`/`<done>` only cover the populated case — no loading/empty/error state defined."
+- Exception: if WIREFRAMES.md exists (`/rcode-ui-phase` output) and already defines the four states for this screen, a task that references WIREFRAMES.md instead of re-listing them inline is fine — check WIREFRAMES.md's entry for this screen before flagging.
 
 **Example issue:**
 ```yaml
@@ -59,6 +77,17 @@ issue:
   fix_hint: "Add verification command for build output"
 ```
 
+**Example issue — verify doesn't prove the claim:**
+```yaml
+issue:
+  dimension: task_completeness
+  severity: blocker
+  description: "Task 3 implements login flow but <verify> only runs `npm run build`"
+  plan: "16-01"
+  task: 3
+  fix_hint: "Replace with a curl against /api/login checking 200 + session cookie, or a test exercising the login route"
+```
+
 ## Dimension 3: Dependency Correctness
 
 **Question:** Are plan dependencies valid and acyclic?
@@ -103,6 +132,7 @@ issue:
 - API route created but component doesn't call it
 - Database model created but API doesn't query it
 - Form created but submit handler is missing or stub
+- New page/component has no task adding it to the router, nav, or an existing page's imports — unreachable by any user
 
 **What to check:**
 ```
@@ -110,8 +140,27 @@ Component -> API: Does action mention fetch/axios call?
 API -> Database: Does action mention Prisma/query?
 Form -> Handler: Does action mention onSubmit implementation?
 State -> Render: Does action mention displaying state?
+Nav -> Route: For any new page/route/component in must_haves.artifacts, does a task action mention adding it to the router config, nav/sidebar, or an existing page's import?
 ```
 
+A top-level UI artifact (page/route/component) with no Nav -> Route reference anywhere in the sprint's tasks is a blocker — internal wiring can be perfect while the feature stays unreachable by any user.
+
+**Check — Role Access Defined (multi-role/SSO/compliance projects only):**
+`roadmapper-playbook.md`'s "Enterprise Projects Need Auth Strategy and Role
+Mapping Decided Up Front" rule requires every later phase adding a
+user-facing route to include "role access defined for this route" as a
+success criterion — explicitly NOT covered by `rcode-verifier`'s Level-5
+Reachability check (which only confirms a page is linked from nav, not that
+it's linked/gated correctly per role). If PROJECT.md/REQUIREMENTS.md show
+more than one user role, cross-reference each new route in
+`must_haves.artifacts` against the roadmap's role-to-screen mapping (IA.md or
+ROADMAP.md's IA section — see roadmapper-playbook.md step 3b): does a task
+state which roles can/cannot reach this route, or is role access left
+undefined? A new route with no role-access statement anywhere in the sprint's
+tasks is a blocker for multi-role projects — the same orphan-feature failure
+as unreachable nav, just for authorization instead of discoverability.
+- Flag as blocker: "Route {path} added with no role-access statement — roadmap's role mapping shows N roles but no task defines who can/cannot reach this route."
+
 **Example issue:**
 ```yaml
 issue:
@@ -167,12 +216,26 @@ issue:
 2. Verify truths are user-observable (not implementation details)
 3. Verify artifacts support the truths
 4. Verify key_links connect artifacts to functionality
+5. Cross-reference each truth to a falsifiable `<verify>` command: for each `must_haves.truths` entry, search every task's `<verify>` block (across all plans in the sprint) for a command that could actually falsify that truth — a curl/HTTP assertion, a UI interaction test (playwright/cypress selector + assertion), or an explicit manual checkpoint script tied to the same feature. Wording alone (the truth "sounds" user-facing) does not count as a check.
+6. If no task's `<verify>` traces to a truth, flag it as unverifiable — do not accept the phrasing as proof the behavior is tested.
+
+**Check — Truth-to-Verify Traceability (do not rely on wording alone):**
+Judging "user-observable" from phrasing is not a check — a planner can trivially write `"The auth system is secure"` without any task exercising login. Treat this the same way Dimension 12 cross-references evidence claims to grep hit counts:
+1. For each `must_haves.truths` entry, extract the subject/action it claims (e.g., "user can log in", "search returns results").
+2. Scan every task's `<verify>` block across the sprint's plans for a command whose target matches that subject — a route/endpoint the truth implies (`/api/login`, `/search`), a selector the truth implies (login form, search box), or a checkpoint script named for the same feature.
+3. A match requires the `<verify>` command to actually exercise real input against the feature and assert on real output (status code, response body, rendered DOM state) — not just that the words in the truth and the `<verify>` block resemble each other.
+4. No match found → the truth is **unverifiable**, regardless of how user-facing its wording sounds. Flag it; do not accept the phrasing as proof.
 
 **Red flags:**
 - Missing `must_haves` entirely
 - Truths are implementation-focused ("bcrypt installed") not user-observable ("passwords are secure")
 - Artifacts don't map to truths
 - Key links missing for critical wiring
+- Truth uses user-facing wording but no task's `<verify>` exercises the corresponding user path (e.g., "The auth system is secure" with no login/reject-bad-credentials check anywhere in the sprint) — unfalsifiable marketing language, not a verified outcome
+
+**Severity rules:**
+- **blocker:** a `must_haves.truths` entry has zero traceable `<verify>` command in any task across the sprint's plans
+- **warning:** the traced `<verify>` command exists but only checks an implementation detail (e.g., process exits 0) rather than the user-observable behavior the truth claims
 
 **Example issue:**
 ```yaml
@@ -187,6 +250,17 @@ issue:
   fix_hint: "Reframe as user-observable: 'User can log in', 'Session persists'"
 ```
 
+**Example issue — untraceable truth:**
+```yaml
+issue:
+  dimension: verification_derivation
+  severity: blocker
+  description: "Truth 'The auth system is secure' has no task <verify> that exercises login or rejects bad credentials"
+  plan: "02"
+  truth: "The auth system is secure"
+  fix_hint: "Add a <verify> with a curl/HTTP assertion (e.g. POST /login with wrong password returns 401) or a UI test that logs in and confirms session state, then reference it from this truth"
+```
+
 ## Dimension 7: Context Compliance (if CONTEXT.md exists)
 
 **Question:** Do plans honor user decisions from /rcode-discuss-phase?

package/rcode/agents/rules/sprint-checker/process.md

@@ -84,6 +84,18 @@ Session persists     | 01    | 3     | COVERED
 
 For each requirement: find covering task(s), verify action is specific, flag gaps.
 
+**Sub-behavior check (concrete, not eyeballed):** A task ID in the `Tasks` column is not proof of coverage by itself. For each requirement:
+1. Split the requirement's acceptance-criteria text (from ROADMAP.md/PRD, or the `must_haves.truths` derived from it) into discrete sub-behaviors — each verb phrase is one sub-behavior (e.g. "user can reset password" -> ["request reset email", "receive token", "verify token", "set new password"]).
+2. For each sub-behavior, check the covering task's `<action>` and `<verify>` text contains a concrete reference to it (a matching noun/verb, file, or endpoint) — not just the requirement's headline phrase.
+3. If one task covers a multi-sub-behavior requirement, list which sub-behaviors its action/verify actually address. Any sub-behavior with zero matching action/verify text is **unaddressed**.
+4. Status is `COVERED` only if every sub-behavior maps to at least one action/verify pair. If any sub-behavior is unaddressed, status is `PARTIAL` and is a **blocker**, not a note — list the specific missing sub-behavior(s), not a generic "may be incomplete" remark.
+
+```
+Requirement          | Plans | Tasks | Status  | Missing sub-behaviors
+----------------------|-------|-------|---------|----------------------
+User can reset password | 01  | 4     | PARTIAL | token verification, email send
+```
+
 **Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
 
 ## Step 5: Validate Task Structure

package/rcode/agents/rules/verifier/behavioral-spot-checks.md

@@ -44,6 +44,10 @@ Record pass/fail:
 ## Constraints
 
 - Each check must complete in under 10 seconds
-- Do not start servers or services — only test what's already runnable
+- Do not start servers or services for these checks specifically — only test
+  what's already runnable. (This does NOT apply to the Level-5 reachability
+  live smoke check in `reachability-check.md`, which exists precisely because
+  UI-facing phases need a running server to verify — see that file for when
+  and how to start one.)
 - Do not modify state (no writes, no mutations, no side effects)
 - If the project has no runnable entry points yet, skip with: "Step 7b: SKIPPED (no runnable entry points)"

package/rcode/agents/rules/verifier/gap-output.md

@@ -2,6 +2,11 @@
 
 ## Step 8: Identify Human Verification Needs
 
+A flagged item here is an open item, not a pass. Do not describe a phase with
+unresolved human-verification items as "complete," "closed," "passed," or
+"shippable" anywhere in the summary handed back to the orchestrator — say
+what's still unconfirmed and by whom (the user, not another agent).
+
 **Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance feel, error message clarity.
 
 **Needs human if uncertain:** Complex wiring grep can't trace, dynamic state behavior, edge cases.

package/rcode/agents/rules/verifier/reachability-check.md

@@ -0,0 +1,69 @@
+# Verifier — Reachability + Live UI Smoke Check (Steps 6b, 10b)
+
+Levels 1-4 (exists, substantive, wired, data-flows) verify an artifact works in
+isolation. None of them verify that a real user, starting from the app's actual
+entry point, can ever land on it. That gap is how a phase gets marked "passed"
+while the delivered page has no nav link, no sidebar entry, and no way in
+except typing its exact URL — code-complete, unusable.
+
+**When to run:** Any phase whose must-haves include a user-facing route, page,
+or screen (not API-only, not CLI-only, not backend/schema-only phases).
+
+## Step 6b — Reachability (static)
+
+For each user-facing route delivered by this phase:
+
+1. Find the app's navigation surface — the layout/shell component(s) that
+   render on every page (e.g. `layout.tsx`, `Nav.tsx`, `Sidebar.tsx`,
+   `AppShell.tsx` — whatever this project actually uses).
+2. Grep it for a link to the route:
+   ```bash
+   grep -rn "$ROUTE_PATH" src/app/layout.tsx src/components/Nav* src/components/*Sidebar* 2>/dev/null
+   ```
+3. If found → Reachable ✓. If not found → Reachable ✗, classify as
+   **ORPHANED-FROM-UI**: the code works but no real user can find it without
+   the URL bar.
+
+**If the project has no shell/nav component at all yet** — that is itself a
+gap, not a reason to skip this check. A phase that ships pages with nowhere to
+click from IS the gap. Report it as: "No app shell/navigation exists — every
+delivered page is orphaned from UI by definition."
+
+## Step 10b — Live smoke check (dynamic)
+
+Static reachability (6b) can be fooled by a nav link that renders but is
+broken, hidden, or dead. Confirm it live:
+
+1. Start the dev server if one isn't already running (check first —
+   `curl -s -o /dev/null -w '%{http_code}' $BASE_URL` — don't start a
+   duplicate). Note the port and PID so it can be left running or killed
+   depending on project convention.
+2. Fetch the app's real entry point — the URL a user actually opens first
+   (usually `/`, or the post-login landing page), not the new route directly:
+   ```bash
+   curl -s $BASE_URL/ | grep -o "$ROUTE_PATH" | head -1
+   ```
+   A hit means the entry point's rendered HTML contains a link to the route.
+   No hit means either the link isn't there, it's client-rendered (acceptable
+   — note it and move to a browser check if available), or the entry point
+   itself is broken.
+3. If a browser automation tool is available in this session, prefer it over
+   curl: open the entry point, look for the nav element, click through to the
+   route, confirm the expected content renders. This catches what curl can't
+   (JS-rendered nav, auth redirects, broken client routing).
+4. If neither curl nor a browser tool can settle it, route to human
+   verification (Step 8) — but say explicitly what's unconfirmed ("nav link
+   renders in JS, could not click through without a browser tool") rather than
+   silently passing it.
+
+## Constraints
+
+- Time-box this to the phase's own routes — don't crawl the whole app.
+- If starting the dev server fails (missing DB, missing env vars, port
+  conflict) — that is itself a finding. Report it, don't silently skip
+  reachability and mark the phase passed.
+- Kill any dev server this check started, unless the project's own workflow
+  expects it to stay up (check for an existing `pnpm dev` process first).
+- This step existing does not replace a human actually looking at the app.
+  It catches the mechanical case (no link exists at all). Visual/UX quality
+  still routes to human verification per Step 8.

package/rcode/bin/rcode-tools.cjs

@@ -1366,8 +1366,16 @@ function cmdState(subArgs) {
       const state = readState() || defaultState();
       state.milestone = val;
       return writeState(state);
+    } else if (key === '--ui-spec-path' && val) {
+      const state = readState() || defaultState();
+      state.ui_spec_path = val;
+      return writeState(state);
+    } else if (key === '--wireframes-path' && val) {
+      const state = readState() || defaultState();
+      state.wireframes_path = val;
+      return writeState(state);
     } else {
-      throw new Error(`Unknown state set key: ${key}. Use: set-phase <N>, or state set project|milestone <value>`);
+      throw new Error(`Unknown state set key: ${key}. Use: set-phase <N>, or state set project|milestone|--ui-spec-path|--wireframes-path <value>`);
     }
   }
 
@@ -3211,6 +3219,11 @@ function cmdState(subArgs) {
     return { updated: true, phase: phaseKey, status: 'executing', previous_status: previousStatus };
   }
 
+  // DEPRECATED (#gap: state-sync audit): no workflow calls this — every
+  // completion path uses the top-level `phase complete <N>` subcommand
+  // instead. Its stale-executing-phase hygiene warning was ported there.
+  // Kept only for backward compatibility with anyone scripting against it
+  // directly; do not wire new callers to this — use `phase complete`.
   if (sub === 'complete-phase') {
     const flags = parseFlags(1);
     if (!flags.phase) throw new Error('complete-phase requires --phase <N>');
@@ -3946,6 +3959,29 @@ function cmdPhase(subArgs) {
       throw new Error(`Phase "${phaseRef}" not found in state.phases (looked up by number, id, and name)`);
     }
     const previous = state.phases[idx].status || null;
+
+    // State-hygiene gate (#955): if an earlier-numbered phase is still stuck
+    // 'executing' while this later phase gets marked complete, that's exactly
+    // the drift that misorients resolveActivePhase() / the SessionStart greeter.
+    // Warn rather than block — completing out of order is sometimes correct
+    // (parallel workstreams), but it must never happen silently. (Ported from
+    // the unused `state complete-phase` twin — this is the code path every
+    // workflow actually calls.)
+    const thisNum = parseInt(String(state.phases[idx].number || phaseRef), 10);
+    const stalePhases = Number.isNaN(thisNum) ? [] : state.phases.filter((p) => {
+      if (!p || p.status !== 'executing') return false;
+      const n = parseInt(String(p.number ?? p.id), 10);
+      return !Number.isNaN(n) && n < thisNum;
+    });
+    const warnings = [];
+    if (stalePhases.length > 0) {
+      const staleList = stalePhases.map((p) => p.number ?? p.id).join(', ');
+      warnings.push(
+        `Phase ${phaseRef} marked complete while earlier phase(s) ${staleList} are still 'executing'. ` +
+        `Close out the stale phase(s) or confirm this is an intentional parallel workstream.`
+      );
+    }
+
     state.phases[idx].status = 'complete';
     state.phases[idx].status_updated = new Date().toISOString();
     state.phases[idx].completed_at = state.phases[idx].completed_at || new Date().toISOString().slice(0, 10);
@@ -3979,8 +4015,8 @@ function cmdPhase(subArgs) {
       is_last_phase: !next,
       open_phases_remaining: openRemaining,
       ...(nudge ? { nudge } : {}),
-      warnings: [],
-      has_warnings: false,
+      warnings,
+      has_warnings: warnings.length > 0,
     };
   }
 

package/rcode/commands/ui-phase.md

@@ -1,6 +1,6 @@
 ---
 name: rcode-ui-phase
-description: Produce UI-SPEC.md with color tokens, typography, component inventory, interaction states, and accessibility guidelines. Detects frontend keywords and suggests this command early in plan.md if UI-SPEC.md is absent.
+description: Produce UI-SPEC.md (color tokens, typography, component inventory, interaction states, accessibility guidelines) and WIREFRAMES.md (per-role screen inventory with loading/empty/error states). Detects frontend keywords and suggests this command early in plan.md if UI-SPEC.md is absent.
 argument-hint: "[--existing-ui <path>] [--design-system <path>]"
 allowed-tools: Agent, Read, Glob, Grep, Write
 ---

package/rcode/references/design-library/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Next Level Builder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/rcode/references/design-library/README.md

@@ -0,0 +1,37 @@
+# Design Library
+
+Reference data consulted by `rcode-ux-designer` and `/rcode-ui-phase` when
+producing UI-SPEC.md and WIREFRAMES.md — style/palette/typography options with
+concrete values, UX do/don't rules per interface pattern, and category→pattern
+decision rules for picking a design direction that fits the project, instead
+of an agent inventing tokens from scratch.
+
+## Source and license
+
+Vendored from [ui-ux-pro-max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)
+by Next Level Builder, MIT licensed. Copyright (c) 2024 Next Level Builder.
+Full license text: `LICENSE` in this directory. Data only — the upstream
+project's Python CLI/scripts are not vendored; rcode agents read these CSVs
+directly via Read/Grep, no Python dependency required.
+
+## Files
+
+| File | Contents |
+|---|---|
+| `styles.csv` | 67 UI style categories (Minimalism, Neumorphism, Glassmorphism, Brutalism, etc.) — keywords, color palette, effects, best-for/avoid-for, accessibility rating, framework compatibility, implementation checklist |
+| `colors.csv` | Palette options with hex values and mood/use-case |
+| `typography.csv` | Font pairings with scale, weight, and use-case |
+| `ux-guidelines.csv` | Do/don't rules by category (Navigation, Forms, etc.) with good/bad code examples and severity |
+| `ui-reasoning.csv` | Project-category → recommended pattern/style/color-mood/typography-mood decision rules, with anti-patterns to avoid |
+| `web-interface.csv` | Web-specific interface pattern guidance |
+| `icons.csv` | Icon system/library options |
+| `charts.csv` | Chart/data-viz pattern options |
+
+## How to use
+
+Don't dump these into a prompt wholesale — they're too large. Grep for the
+project's category/type in `ui-reasoning.csv` first to get a recommended
+style + color mood + typography mood, then look up the specific style's row
+in `styles.csv` for concrete values, then check `ux-guidelines.csv` for the
+do/don't rules relevant to the screens being designed (Navigation, Forms,
+etc.). See `rcode/workflows/ui-phase.md` for the concrete lookup sequence.

package/rcode/references/design-library/charts.csv

@@ -0,0 +1,26 @@
+No,Data Type,Keywords,Best Chart Type,Secondary Options,Color Guidance,Performance Impact,Accessibility Notes,Library Recommendation,Interactive Level
+1,Trend Over Time,"trend, time-series, line, growth, timeline, progress",Line Chart,"Area Chart, Smooth Area",Primary: #0080FF. Multiple series: use distinct colors. Fill: 20% opacity,⚡ Excellent (optimized),✓ Clear line patterns for colorblind users. Add pattern overlays.,"Chart.js, Recharts, ApexCharts",Hover + Zoom
+2,Compare Categories,"compare, categories, bar, comparison, ranking",Bar Chart (Horizontal or Vertical),"Column Chart, Grouped Bar",Each bar: distinct color. Category: grouped same color. Sorted: descending order,⚡ Excellent,✓ Easy to compare. Add value labels on bars for clarity.,"Chart.js, Recharts, D3.js",Hover + Sort
+3,Part-to-Whole,"part-to-whole, pie, donut, percentage, proportion, share",Pie Chart or Donut,"Stacked Bar, Treemap",Colors: 5-6 max. Contrasting palette. Large slices first. Use labels.,⚡ Good (limit 6 slices),⚠ Hard for accessibility. Better: Stacked bar with legend. Avoid pie if >5 items.,"Chart.js, Recharts, D3.js",Hover + Drill
+4,Correlation/Distribution,"correlation, distribution, scatter, relationship, pattern",Scatter Plot or Bubble Chart,"Heat Map, Matrix",Color axis: gradient (blue-red). Size: relative. Opacity: 0.6-0.8 to show density,⚠ Moderate (many points),⚠ Provide data table alternative. Use pattern + color distinction.,"D3.js, Plotly, Recharts",Hover + Brush
+5,Heatmap/Intensity,"heatmap, heat-map, intensity, density, matrix",Heat Map or Choropleth,"Grid Heat Map, Bubble Heat",Gradient: Cool (blue) to Hot (red). Scale: clear legend. Divergent for ±data,⚡ Excellent (color CSS),⚠ Colorblind: Use pattern overlay. Provide numerical legend.,"D3.js, Plotly, ApexCharts",Hover + Zoom
+6,Geographic Data,"geographic, map, location, region, geo, spatial","Choropleth Map, Bubble Map",Geographic Heat Map,Regional: single color gradient or categorized colors. Legend: clear scale,⚠ Moderate (rendering),⚠ Include text labels for regions. Provide data table alternative.,"D3.js, Mapbox, Leaflet",Pan + Zoom + Drill
+7,Funnel/Flow,funnel/flow,"Funnel Chart, Sankey",Waterfall (for flows),Stages: gradient (starting color → ending color). Show conversion %,⚡ Good,✓ Clear stage labels + percentages. Good for accessibility if labeled.,"D3.js, Recharts, Custom SVG",Hover + Drill
+8,Performance vs Target,performance-vs-target,Gauge Chart or Bullet Chart,"Dial, Thermometer",Performance: Red→Yellow→Green gradient. Target: marker line. Threshold colors,⚡ Good,✓ Add numerical value + percentage label beside gauge.,"D3.js, ApexCharts, Custom SVG",Hover
+9,Time-Series Forecast,time-series-forecast,Line with Confidence Band,Ribbon Chart,Actual: solid line #0080FF. Forecast: dashed #FF9500. Band: light shading,⚡ Good,✓ Clearly distinguish actual vs forecast. Add legend.,"Chart.js, ApexCharts, Plotly",Hover + Toggle
+10,Anomaly Detection,anomaly-detection,Line Chart with Highlights,Scatter with Alert,Normal: blue #0080FF. Anomaly: red #FF0000 circle/square marker + alert,⚡ Good,✓ Circle/marker for anomalies. Add text alert annotation.,"D3.js, Plotly, ApexCharts",Hover + Alert
+11,Hierarchical/Nested Data,hierarchical/nested-data,Treemap,"Sunburst, Nested Donut, Icicle",Parent: distinct hues. Children: lighter shades. White borders 2-3px.,⚠ Moderate,⚠ Poor - provide table alternative. Label large areas.,"D3.js, Recharts, ApexCharts",Hover + Drilldown
+12,Flow/Process Data,flow/process-data,Sankey Diagram,"Alluvial, Chord Diagram",Gradient from source to target. Opacity 0.4-0.6 for flows.,⚠ Moderate,⚠ Poor - provide flow table alternative.,"D3.js (d3-sankey), Plotly",Hover + Drilldown
+13,Cumulative Changes,cumulative-changes,Waterfall Chart,"Stacked Bar, Cascade",Increases: #4CAF50. Decreases: #F44336. Start: #2196F3. End: #0D47A1.,⚡ Good,✓ Good - clear directional colors with labels.,"ApexCharts, Highcharts, Plotly",Hover
+14,Multi-Variable Comparison,multi-variable-comparison,Radar/Spider Chart,"Parallel Coordinates, Grouped Bar",Single: #0080FF 20% fill. Multiple: distinct colors per dataset.,⚡ Good,⚠ Moderate - limit 5-8 axes. Add data table.,"Chart.js, Recharts, ApexCharts",Hover + Toggle
+15,Stock/Trading OHLC,stock/trading-ohlc,Candlestick Chart,"OHLC Bar, Heikin-Ashi",Bullish: #26A69A. Bearish: #EF5350. Volume: 40% opacity below.,⚡ Good,⚠ Moderate - provide OHLC data table.,"Lightweight Charts (TradingView), ApexCharts",Real-time + Hover + Zoom
+16,Relationship/Connection Data,relationship/connection-data,Network Graph,"Hierarchical Tree, Adjacency Matrix",Node types: categorical colors. Edges: #90A4AE 60% opacity.,❌ Poor (500+ nodes struggles),❌ Very Poor - provide adjacency list alternative.,"D3.js (d3-force), Vis.js, Cytoscape.js",Drilldown + Hover + Drag
+17,Distribution/Statistical,distribution/statistical,Box Plot,"Violin Plot, Beeswarm",Box: #BBDEFB. Border: #1976D2. Median: #D32F2F. Outliers: #F44336.,⚡ Excellent,"✓ Good - include stats table (min, Q1, median, Q3, max).","Plotly, D3.js, Chart.js (plugin)",Hover
+18,Performance vs Target (Compact),performance-vs-target-(compact),Bullet Chart,"Gauge, Progress Bar","Ranges: #FFCDD2, #FFF9C4, #C8E6C9. Performance: #1976D2. Target: black 3px.",⚡ Excellent,✓ Excellent - compact with clear values.,"D3.js, Plotly, Custom SVG",Hover
+19,Proportional/Percentage,proportional/percentage,Waffle Chart,"Pictogram, Stacked Bar 100%",10x10 grid. 3-5 categories max. 2-3px spacing between squares.,⚡ Good,✓ Good - better than pie for accessibility.,"D3.js, React-Waffle, Custom CSS Grid",Hover
+20,Hierarchical Proportional,hierarchical-proportional,Sunburst Chart,"Treemap, Icicle, Circle Packing",Center to outer: darker to lighter. 15-20% lighter per level.,⚠ Moderate,⚠ Poor - provide hierarchy table alternative.,"D3.js (d3-hierarchy), Recharts, ApexCharts",Drilldown + Hover
+21,Root Cause Analysis,"root cause, decomposition, tree, hierarchy, drill-down, ai-split",Decomposition Tree,"Decision Tree, Flow Chart",Nodes: #2563EB (Primary) vs #EF4444 (Negative impact). Connectors: Neutral grey.,⚠ Moderate (calculation heavy),✓ clear hierarchy. Allow keyboard navigation for nodes.,"Power BI (native), React-Flow, Custom D3.js",Drill + Expand
+22,3D Spatial Data,"3d, spatial, immersive, terrain, molecular, volumetric",3D Scatter/Surface Plot,"Volumetric Rendering, Point Cloud",Depth cues: lighting/shading. Z-axis: color gradient (cool to warm).,❌ Heavy (WebGL required),❌ Poor - requires alternative 2D view or data table.,"Three.js, Deck.gl, Plotly 3D",Rotate + Zoom + VR
+23,Real-Time Streaming,"streaming, real-time, ticker, live, velocity, pulse",Streaming Area Chart,"Ticker Tape, Moving Gauge",Current: Bright Pulse (#00FF00). History: Fading opacity. Grid: Dark.,⚡ Optimized (canvas/webgl),⚠ Flashing elements - provide pause button. High contrast.,Smoothed D3.js, CanvasJS
+24,Sentiment/Emotion,"sentiment, emotion, nlp, opinion, feeling",Word Cloud with Sentiment,"Sentiment Arc, Radar Chart",Positive: #22C55E. Negative: #EF4444. Neutral: #94A3B8. Size = Frequency.,⚡ Good,⚠ Word clouds poor for screen readers. Use list view.,"D3-cloud, Highcharts, Nivo",Hover + Filter
+25,Process Mining,"process, mining, variants, path, bottleneck, log",Process Map / Graph,"Directed Acyclic Graph (DAG), Petri Net",Happy path: #10B981 (Thick). Deviations: #F59E0B (Thin). Bottlenecks: #EF4444.,⚠ Moderate to Heavy,⚠ Complex graphs hard to navigate. Provide path summary.,"React-Flow, Cytoscape.js, Recharts",Drag + Node-Click