@hanzlaa/rcode 4.10.6 → 4.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.10.6",
+  "version": "4.12.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-planner.md

@@ -9,6 +9,7 @@ color: green
 @.rcode/references/karpathy-guidelines-full.md
 @.rcode/references/output-realism.md
 @.rcode/brain/best-practices/no-theoretical-suggestions.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/planner-playbook.md
 
 <role>

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

@@ -8,6 +8,7 @@ color: cyan
 
 @.rcode/references/response-style.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/researcher-shared.md
 
 <role>
@@ -89,7 +90,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-roadmapper.md

@@ -9,6 +9,7 @@ color: purple
 @.rcode/references/response-style.md
 @.rcode/references/output-realism.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/roadmapper-playbook.md
 
 <role>

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

@@ -7,6 +7,7 @@ color: green
 
 @.rcode/references/response-style.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/source-of-truth-grounding.md
 @.rcode/references/sprint-checker-playbook.md
 
 <role>

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

@@ -29,6 +29,8 @@ 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/` AND real reference sites actually looked at (not just search snippets), not invented values. WIREFRAMES.md's loading/empty/error/populated coverage per screen is Silence-kills-trust made concrete, per-screen.
+- **Variants-not-a-verdict** — visual direction is a taste-and-tradeoff decision, not a data lookup with one right answer. When asked to propose a design direction, generate genuinely distinct options and let the user pick — don't rank them or present a "recommended" one, that's the same failure as silently locking in a stack choice without asking.
 
 ## 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?
@@ -409,6 +483,61 @@ issue:
   fix_hint: "Plan was built on hallucinated findings. Re-run /rcode-debug to verify actual code state before replanning."
 ```
 
+## Dimension 12: Evidence Grounding
+
+**Question:** Is every claim in the plan traceable to something real — a codebase grep, or an external source-of-truth document — rather than plausible-sounding invention?
+
+This dimension has two halves. Both exist because agents produce fluent,
+confident, wrong output when nothing forces them to cite a real source —
+codebase claims and domain-terminology claims fail the same way, just
+against different ground truths.
+
+### 12a — Codebase Evidence (issue #649)
+
+Every task body that names a file count, component, pattern, or existing
+behavior MUST include an `<evidence>` block citing real grep hit counts,
+real `path:line` ranges, or an explicit `creates:` justification (for
+genuinely new files/symbols that can't have prior evidence). A task claiming
+"13 usages of `useAuth`" with no evidence, or citing a grep that doesn't
+actually return 13, is theoretical — reject it.
+
+**Process:**
+1. For each task with a factual claim about existing code, check for an `<evidence>` block.
+2. If present, re-run a sample of the cited greps/searches yourself. If the claimed count doesn't match reality, downgrade to blocker regardless of what the task otherwise looks like.
+3. If absent for a claim that isn't a `creates:` (brand new file/symbol), flag as blocker — the claim is unfalsifiable as written.
+
+### 12b — Source-Document Evidence
+
+If PROJECT.md/REQUIREMENTS.md/CONTEXT.md reference an external source-of-truth
+document (a spreadsheet, transcript, spec, glossary — see
+`source-of-truth-grounding.md`) that defines domain terminology, enum values,
+or a data model, any task creating schema fields, enum values, or seed data
+for that domain MUST cite the source document and use its verbatim values —
+not an invented approximation that merely sounds plausible for "this kind of
+system." This is exactly how a competency-tracking app once shipped invented
+category names (`TECH`, `DELIV`, `COLLAB`) instead of the real Excel's actual
+categories (`Technical Skills`, `Delivery & Quality`, `Communication &
+Collaboration`) — plausible, well-formatted, and wrong.
+
+**Process:**
+1. Check whether PROJECT.md/REQUIREMENTS.md mention a source document for this domain.
+2. If yes, for each schema/seed-data task touching that domain, verify the task cites the source document path and that its field/enum values are traceable to it (spot-check by reading the source yourself if it's available).
+3. A schema/seed task for a domain with a known source document, with no citation and no traceable match, is a blocker — not a style nitpick. This is exactly the class of mistake that's expensive to unwind once it's in a live database.
+
+**Severity rules:**
+- **blocker:** 12a claim with no evidence and no `creates:` justification, evidence that doesn't check out on re-run, OR 12b schema/seed task for a known-source domain with no citation/traceable match
+- **warning:** evidence present but thin (e.g. cites a grep pattern too broad to actually confirm the specific claim)
+
+**Example issue:**
+```yaml
+issue:
+  dimension: evidence_grounding
+  severity: blocker
+  description: "Task 3 seeds 'competency' enum with TECH/DELIV/COLLAB/GROWTH/IMPACT — PROJECT.md references docs/Competency-Matrix.xlsx as the source of truth for these categories, but no task reads it or cites its actual values"
+  plan: "01"
+  fix_hint: "Read docs/Competency-Matrix.xlsx (or its extracted contents) and replace the enum values with what it actually defines, verbatim"
+```
+
 </verification_dimensions>
 
 <verification_process>

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.