@hanzlaa/rcode 4.10.5 → 4.11.0

package/rcode/references/roadmapper-playbook.md

@@ -43,6 +43,95 @@ NEVER include phases for:
 
 If it sounds like corporate PM theater, delete it.
 
+### UI Projects Need a Shell Phase — Not an Assumption
+
+**If the project has any user-facing UI, an early phase MUST explicitly cover
+the app shell: navigation (nav bar/sidebar), layout, and auth entry (login
+screen) if auth exists.** Do not assume this "comes for free" alongside a
+domain/feature phase — it doesn't. A roadmap built entirely from
+domain-sliced phases (e.g. "Org graph," "Evidence ledger," "Attainment
+engine," "Authorization," "Audit trail") can ship every one of those phases
+individually verified and working, while the app itself has no way for a real
+user to navigate between them — every page only reachable by typing its exact
+URL. That is a real, observed failure mode, not a hypothetical.
+
+Concretely: the roadmap's Phase 1 (or the first UI-touching phase) success
+criteria must include something like "user can log in and see navigation to
+every top-level area the project will eventually have" — even if most of
+those areas are placeholder links until their own phase lands. Every later
+phase that adds a new user-facing route must include "linked from the app's
+navigation" as one of its own success criteria, not just "the page renders."
+
+This is what `rcode-verifier`'s Level-5 Reachability check enforces at
+verification time — but it can only enforce what the roadmap and plan
+actually asked for. If no phase ever planned the nav, no plan ever built it,
+and the verifier is left checking pages that are correct in isolation but
+orphaned from the UI. Plan the shell so verification has something to check.
+
+**Run `/rcode-ui-phase` before planning the shell phase's sprints, not after.**
+It produces UI-SPEC.md (design tokens grounded in `rcode/references/design-library/`,
+not invented) and WIREFRAMES.md (every screen from the IA decision in step 3b
+of the Workflow section below, with role visibility and required
+loading/empty/error/success states). Planning the
+shell phase's tasks without these means the planner is guessing at what to
+build — the shell phase's success criteria should reference both artifacts as
+existing, not just "nav exists."
+
+### Enterprise Projects Need Auth Strategy and Role Mapping Decided Up Front
+
+**If the project is multi-role, SSO-integrated, or compliance-sensitive, an
+early phase MUST explicitly decide auth strategy (SSO/SAML/OIDC vs local
+auth, session/tenant model) and produce a role-to-screen mapping — not defer
+either to whichever phase happens to touch auth first.** Do not assume these
+"come for free" alongside the shell phase — they don't. A roadmap that plans
+navigation and a login screen but never decides which roles can reach which
+screens can ship every phase individually verified and working, while an
+Auditor role sees write actions it should never have access to, or SSO gets
+retrofitted in a later phase and breaks every session model earlier phases
+assumed. That is a real, observed failure mode, not a hypothetical.
+
+Concretely: for multi-role/SSO/compliance-sensitive projects, the roadmap's
+foundation phase (the same phase that plans the shell) success criteria must
+also include something like "auth strategy (SSO provider or local auth) is
+decided and documented" and "each role in scope is mapped to the
+screens/actions it can access" — even if some roles' full permission sets are
+refined in later phases. Every later phase that adds a new user-facing route
+must include "role access defined for this route" as one of its own success
+criteria, not just "linked from the app's navigation."
+
+This is what `rcode-verifier`'s Level-5 Reachability check does NOT enforce —
+it verifies a page is linked from nav, not that it's linked only for the
+correct roles. If no phase ever planned the role mapping, no plan ever built
+access control, and the verifier passes pages that are reachable but
+reachable by everyone.
+
+### Multi-Role Projects Need Role-Differentiated UI Success Criteria
+
+**If the project has more than one user role/permission level, at least one
+phase's success criteria MUST include an observable statement of what each
+role sees differently on screen** (e.g. "Employee sees own-record views only;
+Manager sees a Team Approvals screen; Admin sees a Users/Roles management
+screen") — not just "RBAC enforced at the API" or "permissions checked on the
+backend." A roadmap can cleanly plan and ship Auth, RBAC-enforcement, and
+Audit-trail phases, all individually verified and working, while never
+producing a phase whose success criteria mentions what a Manager's screen has
+that an Employee's doesn't. That is the same class of orphan-feature failure
+the Shell Phase rule above exists to prevent, just for role visibility instead
+of nav reachability: backend permission checks shipped, zero
+role-differentiated UI ever asked about.
+
+This applies to the nav itself, not just screen content: the Shell Phase's
+success criteria must state which roles see which top-level nav
+sections/menu items, not only "user can log in and see navigation to every
+top-level area." Showing every role an identical full nav and relying on
+route-level auth to 403 the sections they can't use is a common but bad
+pattern — it leaks the existence of features a role shouldn't know about and
+is worse UX than a nav that's filtered per role. For 2+-role projects, the
+IA decision in step 3b below must include a `{top-level section -> roles
+that see it}` mapping, and the Shell Phase success criteria must include an
+observable statement like "user logged in as role X sees only the nav
+sections role X is entitled to."
+
 ### On-Demand Rule Files
 
 | When you need... | Read |
@@ -58,6 +147,7 @@ Read only when the current task needs the detail. Don't preemptively load.
 1. **Read context** — REQUIREMENTS.md, FEATURES.md, ARCHITECTURE.md, STACK.md, RESEARCH.md (per `<files_to_read>`).
 2. **Cluster requirements** — group related requirements into natural delivery units.
 3. **Derive phases** — name each phase by what the user can DO after it, not what was built.
+3b. **Declare the Information Architecture** (UI projects only) — before phases are finalized, explicitly decide the app's eventual final-state IA, not per-phase: enumerate the top-level sections (e.g. Dashboard / Operations / Reports / Admin), pick sidebar vs topbar vs tabs, state max nesting depth (e.g. 2 levels: section > subsection), and group every planned phase's screens under one of those sections. Persist this as an `IA.md` (or a "## Information Architecture" section in ROADMAP.md). A flat list of nav links that grows by one item per phase is not an IA decision — it's the failure mode this step exists to prevent. Later phases must slot new routes under an existing top-level section or explicitly propose adding one, never silently append a new sidebar item.
 4. **Map 100% of requirements** — every req maps to exactly one phase. Verify coverage.
 5. **Write success criteria** — 2-5 observable behaviors per phase. Goal-backward.
 6. **Assign dependencies** — which phases must complete before others can start?

package/rcode/references/sprint-checker-playbook.md

@@ -108,8 +108,22 @@ issues:           # always emit, even if empty (issues: [])
 verified_files:   # list every file actually read during verification
   - path: <relative path>
     bytes: <int>
+
+dimension_status:  # REQUIRED — one entry for all 12 dimensions (7 only if CONTEXT.md present), no omissions
+  - dimension: <1-12 name from verification_dimensions>
+    status: pass | partial | fail | skipped
+    reason: <required if status is skipped — e.g. "no CONTEXT.md present">
 ```
 
+`issues: []` alone is NOT sufficient to pass the malfunction guard. The guard also
+requires `dimension_status` to list all 12 dimensions (dimension 7 may be
+`skipped` with reason "no CONTEXT.md present" — no other dimension may be
+`skipped`), and requires `verified_files` to include, at minimum, every
+`*-SPRINT.md` in the phase, `ROADMAP.md`, and `CONTEXT.md` (if it exists). A
+return with fewer `verified_files` entries than the known set of phase files,
+or a `dimension_status` list shorter than 12 (11 when CONTEXT.md is absent),
+is rejected as malfunction — regardless of whether `issues:` is present.
+
 If you have not invoked `Read`, `Bash`, `Grep`, or `Glob` during execution, do NOT return — instead, report the failure and stop. Empty narrative output is treated as malfunction, not pass.
 
 ## On-Demand Rule Files

package/rcode/references/verifier-playbook.md

@@ -31,17 +31,19 @@ Before verifying, discover project context:
 ## Verification Flow (Slim)
 
 1. **Check for previous VERIFICATION.md** — if exists with gaps, enter RE-VERIFICATION MODE (skip to Step 3).
-2. **Load context** — SPRINT.md, SUMMARY.md, ROADMAP.md goal, REQUIREMENTS.md.
-3. **Establish must-haves** — from PLAN frontmatter (Option A), ROADMAP success criteria (Option B), or derive from goal (Option C).
+2. **Load context** — SPRINT.md, SUMMARY.md, ROADMAP.md goal, REQUIREMENTS.md. If CONTEXT.md exists for this phase, read its `## Claude's Discretion` section — each item there is a decision `/rcode-discuss-phase` deferred to implementation time (e.g. "entry point left to Claude's judgment"). Nothing downstream currently checks these were actually resolved as claimed; Step 3 below folds each one into must-haves instead of letting it silently disappear.
+3. **Establish must-haves** — from PLAN frontmatter (Option A), ROADMAP success criteria (Option B), or derive from goal (Option C). **Also fold in CONTEXT.md's discretion items (if any from Step 2):** each one becomes its own must-have truth to verify (e.g. "entry point left to Claude's judgment" → truth: "the feature has a real, working entry point — check what was actually built, not just that something exists"). A deferred decision that never got checked isn't verified, it's forgotten.
 4. **Verify observable truths** — for each truth, status ✓ VERIFIED / ✗ FAILED / ? UNCERTAIN.
-5. **Verify artifacts (3 levels)** — exists, substantive, wired. Use `rcode-tools.cjs verify artifacts`.
+5. **Verify artifacts (4 levels)** — exists, substantive, wired, data-flows. Use `rcode-tools.cjs verify artifacts`.
 6. **Data-flow trace (Level 4)** — for wired artifacts rendering dynamic data, trace upstream to confirm real data source.
+6b. **Reachability (Level 5)** — for any artifact that is a user-facing route/page/screen: is it linked from the app's actual navigation (nav bar, sidebar, a button/link a real user would click), not just directly URL-addressable? See `reachability-check.md`. A page that only a developer typing its exact URL can reach is NOT reachable.
 7. **Verify key links** — component→API, API→DB, form→handler, state→render. Use `rcode-tools.cjs verify key-links`.
 8. **Requirements coverage** — cross-reference PLAN `requirements:` against REQUIREMENTS.md. Flag ORPHANED.
 9. **Anti-pattern scan** — TODO/FIXME/placeholder/empty-return/hardcoded-empty. Classify Blocker/Warning/Info.
 10. **Behavioral spot-checks** — run 2-4 quick commands (<10s each) against runnable code. Skip if no runnable entry points.
-11. **Human verification needs** — visual, real-time, external service, uncertain wiring.
-12. **Determine status** — passed | gaps_found | human_needed. Score = verified_truths / total_truths.
+10b. **Live UI smoke check (UI-facing phases only)** — start the dev server if not already running, hit the phase's actual entry point (the URL a real user would land on, e.g. `/`, not just the new route directly), and confirm the delivered feature is reachable from there. See `reachability-check.md`. Skip only for phases with no user-facing route.
+11. **Human verification needs** — visual, real-time, external service, uncertain wiring. Flagging an item here does NOT mean it passed — it means a human still needs to look before this phase can be called done.
+12. **Determine status** — passed | gaps_found | human_needed. Score = verified_truths / total_truths. **`human_needed` and `gaps_found` are NOT "complete" or "shippable"** — say that plainly in the summary handed back to the orchestrator so it isn't rounded up to a checkmark.
 13. **Structure gap output** — YAML frontmatter for `/rcode-plan --gaps`.
 14. **Create VERIFICATION.md** — use Write tool (never heredoc). Return to orchestrator. DO NOT COMMIT.
 
@@ -59,12 +61,21 @@ Before verifying, discover project context:
 | ✓ | ✗ | - | - | ✗ STUB |
 | ✗ | - | - | - | ✗ MISSING |
 
+**For user-facing routes/pages, add a 5th column — Reachable (linked from the app's real navigation, confirmed by a live smoke check):**
+
+| ...Levels 1-4 | Reachable | Status |
+| --- | --- | --- |
+| all ✓ | ✓ | ✓ VERIFIED |
+| all ✓ | ✗ | ⚠️ ORPHANED-FROM-UI — code works, no real user can find it |
+
 **Overall status decision:**
 
-- **passed** — All truths VERIFIED, all artifacts pass 1-3, all key links WIRED, no blocker anti-patterns.
-- **gaps_found** — Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker anti-patterns found.
+- **passed** — All truths VERIFIED, all artifacts pass levels 1-4 (and level 5 Reachable for UI-facing artifacts), all key links WIRED, no blocker anti-patterns.
+- **gaps_found** — Any truth FAILED, artifact MISSING/STUB/ORPHANED-FROM-UI, key link NOT_WIRED, or blocker anti-patterns found.
 - **human_needed** — All automated checks pass but items flagged for human verification.
 
+**None of these three statuses means "done" or "shippable" on their own except `passed` with zero open human-verification items.** Never let a phase get summarized to the user as complete/closed/shippable while `gaps_found` or unresolved `human_needed` items exist — say what's actually still open.
+
 ---
 
 ## On-Demand Rule Files
@@ -74,6 +85,7 @@ Before verifying, discover project context:
 | Previous-verification check + load context + establish must-haves (Steps 0-2) | `.rcode/agents-rules/verifier/context-loading.md` |
 | Observable truths + 3-level artifact verification (Steps 3-4) | `.rcode/agents-rules/verifier/artifact-verification.md` |
 | Level-4 data-flow trace patterns (Step 4b) | `.rcode/agents-rules/verifier/data-flow-trace.md` |
+| Level-5 reachability + live UI smoke check (Steps 6b, 10b) | `.rcode/agents-rules/verifier/reachability-check.md` |
 | Key link wiring fallback patterns (Step 5) | `.rcode/agents-rules/verifier/key-links.md` |
 | Requirements coverage + orphaned detection (Step 6) | `.rcode/agents-rules/verifier/requirements-coverage.md` |
 | Anti-pattern grep commands + stub reference patterns (Step 7) | `.rcode/agents-rules/verifier/anti-patterns.md` |
@@ -92,6 +104,7 @@ Read these ONLY when the current step needs them. Don't preemptively load.
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at levels 1-3 (exists, substantive, wired)
 - [ ] Data-flow trace (Level 4) run on wired artifacts that render dynamic data
+- [ ] Reachability (Level 5) checked for every user-facing route/page — linked from real nav, confirmed by a live smoke check, not just directly URL-addressable
 - [ ] All key links verified
 - [ ] Requirements coverage assessed (if applicable)
 - [ ] Anti-patterns scanned and categorized

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/SKILL.md

@@ -54,6 +54,14 @@ independent agents.
    fires when `/loop` is active — clarify the heartbeat path with the user first.
 6. **Ignore stray buffer text in panes.** Leftover user text at an idle prompt is NOT
    an agent question — do not Enter it.
+7. **First message to every newly spawned agent starts with `/rcode-do`.** After `cld`
+   launches in a pane and the agent is ready, the very first line sent via
+   `herdr pane send-text` must be the literal `/rcode-do <task description>`, followed by
+   the rest of the task context (worktree path, branch, scope). This routes the agent's
+   first action through rcode's command picker instead of a hand-rolled instruction, so
+   ad-hoc orchestration prompts stay consistent with the rest of the toolset. Applies to
+   both Mode 1 (single-shot) and Mode 2 (wave) dispatch — not to follow-up messages sent
+   later in the same pane.
 
 ---
 
@@ -95,7 +103,8 @@ Use when work is bounded and can finish in one batch.
 2. Create worktrees: `git worktree add ../sm-worktrees/$A -b audit-$A master` for each area.
 3. Create tab + split panes, one per worktree.
 4. Launch `cld` in every pane (`send-text "cld"` + `send-keys Enter`). Sleep 7s after.
-5. Send each agent a self-contained prompt with worktree path, branch, and task.
+5. Send each agent a self-contained prompt with worktree path, branch, and task —
+   the first line must be the literal `/rcode-do <task description>` (Golden rule 7).
    - Audits: diagnose-only first. Fixes: incremental edits, no rewrites, commit each fix.
 6. Monitor: `herdr pane list` every ~2 min. Unblock stuck panes via `send-keys`/`send-text`.
 7. Merge back: `git add -f .planning/audits/*.md && git commit` inside each worktree, then

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/templates/wave-prompt.md

@@ -5,6 +5,8 @@ Use this as the body of `herdr pane send-text` when dispatching each agent in a
 ---
 
 ```
+/rcode-do fix top pending items from <AUDIT_DOC_PATH> on branch <BRANCH_NAME>
+
 You are in an isolated worktree at <WORKTREE_PATH> on branch <BRANCH_NAME>. <REPO_NAME> repo.
 
 YOUR PARENT BRANCH IS <INTEGRATION_BRANCH> (NOT master). Your branch was forked from <INTEGRATION_BRANCH>. When you finish, the orchestrator will merge your branch INTO <INTEGRATION_BRANCH> (not master). Master stays untouched throughout the campaign.

package/rcode/workflows/autonomous.md

@@ -423,7 +423,7 @@ Phase ${PHASE_NUMBER}: Frontend phase detected — generating UI design contract
 Skill(skill="rcode-ui-phase", args="${PHASE_NUMBER}")
 ```
 
-Verify UI-SPEC was created. If still empty after ui-phase, display a non-blocking warning and proceed to 3b.
+Verify UI-SPEC was created (rcode-ui-phase produces WIREFRAMES.md alongside it in the same run). If still empty after ui-phase, display a non-blocking warning and proceed to 3b.
 
 **Otherwise:** Skip silently to 3b.
 
@@ -767,7 +767,7 @@ Read the gaps summary from the audit file. Display:
 - **options:** "Continue anyway — accept gaps" / "Stop — fix gaps manually"
 - On "Stop": Go to handle_blocker.
 
-**Otherwise (autonomous):** Display `Audit ⏭ Gaps accepted — continuing` and proceed to 5b.
+**Otherwise (autonomous):** Display the gaps summary inline (not just a reference to the audit file), then display `Audit ⏭ Gaps accepted — continuing`, set `AUDIT_HAD_GAPS="true"`, and proceed to 5b.
 
 **If `tech_debt`:**
 
@@ -777,10 +777,16 @@ Show the summary, then:
 - **options:** "Continue with tech debt" / "Stop — address debt first"
 - On "Stop": Go to handle_blocker.
 
-**Otherwise (autonomous):** Display `Tech debt noted — continuing` and proceed to 5b.
+**Otherwise (autonomous):** Display the tech debt summary inline (not just a reference to the audit file), then display `Tech debt noted — continuing`, set `AUDIT_HAD_GAPS="true"`, and proceed to 5b.
 
 ### 5b. Complete Milestone
 
+**If `AUDIT_HAD_GAPS` is set:** Display before invoking the skill:
+
+```
+⚠ Marking milestone complete with known gaps/tech debt (see summary above).
+```
+
 ```
 Skill(skill="rcode-complete-milestone", args="${milestone_version}")
 ```
@@ -803,6 +809,8 @@ Cleanup shows its own dry-run and asks user for approval internally — this is
 
 ### 5d. Final Completion
 
+**If `AUDIT_HAD_GAPS` is NOT set:**
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  rcode ► AUTONOMOUS ▸ COMPLETE 🎉
@@ -815,6 +823,21 @@ Cleanup shows its own dry-run and asks user for approval internally — this is
  Ship it! 🚀
 ```
 
+**If `AUDIT_HAD_GAPS` is set:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► AUTONOMOUS ▸ COMPLETE — WITH KNOWN GAPS ⚠
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Milestone: {milestone_version} — {milestone_name}
+ Status: NOT audit-clean — gaps/tech debt accepted, not verified passed
+ Lifecycle: audit ⚠ → complete ✓ → cleanup ✓
+
+ This is not the same as "shippable." Review the gaps summary above and
+ resolve or explicitly accept each item before treating this as done.
+```
+
 **If autonomous created a branch** (i.e., `BRANCH_NAME` was set in the prepare_branch step):
 
 Display:

package/rcode/workflows/complete-milestone.md

@@ -40,7 +40,7 @@ When a milestone completes:
 4. Delete REQUIREMENTS.md (fresh one for next milestone)
 5. Perform full PROJECT.md evolution review
 6. Offer to create next milestone inline
-7. Archive UI artifacts (`*-UI-SPEC.md`, `*-UI-REVIEW.md`) alongside other phase documents
+7. Archive UI artifacts (`*-UI-SPEC.md`, `*-WIREFRAMES.md`, `*-UI-REVIEW.md`) alongside other phase documents
 8. Clean up `.planning/ui-reviews/` screenshot files (binary assets, never archived)
 
 **Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.

package/rcode/workflows/council.md

@@ -395,10 +395,22 @@ Spawn all at once (same pattern as Round 1).
    `performance`, `release`, `ml`, `frontend` (concrete technical categories).
 4. **User requested deliberation** — `$ARGUMENTS` contains `--debate`, `--round-2`,
    or `--deep` flag.
+5. **Hedge/uncertainty** — A panelist's Round 1 response never states a firm
+   position: "could work but I'd want to validate X first", "not enough
+   context to say", "depends on {unresolved factor}", or an explicit
+   low-confidence marker. This is not a contradiction with another panelist,
+   so it won't trip trigger 1 — check for it separately. A hedge is not
+   silent convergence; it means the panel hasn't actually landed on an answer.
 
 If NONE of these fire, skip Round 2 and proceed to Step 5 (presentation).
 Print one line: `✓ Round 2 skipped — {reason: "agents aligned" / "concrete technical question" / etc.}`.
 
+**If trigger 5 fired but Round 2 still resolves nothing** (the hedging panelist
+still can't commit after cross-talk), do not fold the hedge into "consensus."
+Carry it forward as a caveat: Step 5's synthesis and Step 6's decision record
+must flag which panelist(s) hedged and on what, so the session artifact
+doesn't read as unanimous agreement when it wasn't.
+
 **Rationale:** Round 2 doubles token cost and wall-clock. For concrete technical
 questions (fix latency, add feature, debug bug), Round 1 responses grounded in
 the codebase are enough. Cross-talk adds value only when there's genuine tension
@@ -455,7 +467,8 @@ Format:
 
 Rules for compact mode:
 - Each one-liner ≤ 25 words. Paraphrase, don't quote.
-- Convergence table: 2-5 rows, only axes where panelists take a stance. Cells ≤ 6 words.
+- **If a panelist's position is conditional or hedged, the one-liner must keep a caveat marker** (e.g. "token-based auth *if* redis is available, else cookies") — never collapse a conditional answer to the unconditional recommendation.
+- Convergence table: 2-5 rows, only axes where panelists take a stance. Cells ≤ 6 words. When a cell reflects a conditional/hedged stance, keep the condition in the cell (e.g. "token-based *if* redis") rather than the bare recommendation.
 - Round 2 deltas: ≤ 15 words each. "Held position" is a valid delta.
 - No section headers beyond the four above. No numbered story breakdowns. No tables from panelists verbatim.
 - **Data freshness footer is mandatory on every synthesis**, not just research-typed questions. Count claims across all panelist responses: a claim is "live-verified" if it cites a source found via WebSearch/WebFetch in this session (Step 2's research file, or a panelist's own in-session lookup); everything else — including anything tagged `[unverified — training data]` by a panelist — counts toward "from model knowledge". For non-research question types with no external claims, use `0 claims live-verified / 0 from model knowledge — no external claims made`.
@@ -492,12 +505,32 @@ Before presenting, load the commit format reference:
 
 **Either mode:** the artifact file saved in Step 6 always contains full verbatim text — the compact/verbose flag only controls inline presentation.
 
+## Step 5a — Completeness check (MANDATORY before presenting)
+
+Before presenting Round 1/2 as a synthesis, check: does at least one
+panelist response directly address the literal question asked — not just
+a sub-part or an adjacent concern? (e.g. user asks "should we ship v2 now"
+and every panelist answers "the code quality is fine" — that's convergence
+on a narrower question, not an answer to the one asked.)
+
+If no panelist response directly addresses the question, do NOT present
+it as a clean verdict. Print this banner in place of the usual verdict line:
+
+```
+⚠ Panel did not directly address: {original question}
+```
+
+Then treat this the same as a disagreement for Step 5b purposes — route to
+AskUserQuestion (either to re-ask the panel with the gap named, or to ask
+the user how to proceed) rather than synthesizing false consensus.
+
 ## Step 5b — Drill-down question (MANDATORY when disagreement exists)
 
 If Round 1 (or Round 2) surfaced a concrete disagreement between panelists,
-you MUST use AskUserQuestion to force resolution before proceeding. Do NOT
-just list "Next Up" options and leave — a disagreement with no decision
-means nothing shipped.
+or Step 5a found no panelist directly addressed the question, you MUST use
+AskUserQuestion to force resolution before proceeding. Do NOT just list
+"Next Up" options and leave — a disagreement (or an unanswered question)
+with no decision means nothing shipped.
 
 Format the question as the specific tension the user needs to resolve,
 with 2-4 concrete options reflecting the panelists' positions:
@@ -521,8 +554,16 @@ After the user picks, emit a one-line decision record and proceed to
 Save step. The chosen path is what goes into the "Next Up" block —
 the options list is no longer needed once a decision is made.
 
-**Skip Step 5b only if:** there was genuine consensus (all agents aligned)
-or user passed `--no-followup` flag.
+If instead a panelist hedged (Step 4's trigger 5 — "not sure", "depends on X",
+"would need to validate") without ever landing on a firm, contradicting
+position, there's nothing to put in front of the user as an A-vs-B choice —
+skip the AskUserQuestion format. But the hedge still cannot pass through as
+silent consensus: the decision record in Step 6 must carry a one-line caveat
+naming the panelist and the unresolved point.
+
+**Skip Step 5b only if:** there was genuine consensus (all agents aligned,
+none hedged, AND at least one directly addressed the literal question per
+Step 5a) or user passed `--no-followup` flag.
 
 ## Step 6 — Save the session
 
@@ -610,6 +651,10 @@ node .rcode/bin/rcode-tools.cjs state add-decision "{one-line consensus decision
 
 If the council reached no real consensus (pure disagreement, or panelists only asked clarifying questions), skip this call — don't manufacture a decision that wasn't made.
 
+**Hedged/conditional consensus is not clean consensus.** If panelists agree on a direction but each attaches an unmet prerequisite or caveat (e.g. Waleed: "assuming budget approval"; Fatima: "assuming the test-coverage gap is closed first"), do NOT write it as an unqualified one-liner — the dashboard's ADR view has no field for caveats, so an unqualified line reads as a resolved decision. Instead, either:
+- fold the caveat into the summary itself (`"{decision}, conditional on {caveat}"`), or
+- skip `add-decision` entirely and record the caveat as a Follow-up item in the session artifact (Step 5) so it surfaces as unresolved work, not a done decision.
+
 > **Note:** If `rcode-tools.cjs` state commands fail (e.g. state.json missing or not yet initialized), continue without error — state tracking is optional, the session artifact saved in Step 5 is mandatory.
 
 ## Success Criteria

package/rcode/workflows/discuss-phase.md

@@ -90,7 +90,7 @@ Gray areas are **implementation decisions the user cares about** — things that
 
 ```
 Phase: "User authentication"
-→ Session handling, Error responses, Multi-device policy, Recovery flow
+→ Auth strategy (SSO/Entra/OAuth vs local accounts vs magic link), Session handling, Error responses, Multi-device policy, Recovery flow
 
 Phase: "Organize photo library"
 → Grouping criteria, Duplicate handling, Naming convention, Folder structure
@@ -426,7 +426,13 @@ Analyze the phase to identify gray areas worth discussing. **Use both `prior_dec
    - These are **pre-answered** — don't re-ask unless this phase has conflicting needs
    - Note applicable prior decisions for use in presentation
 
-3. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation. **Annotate with code context where relevant** (e.g., "You already have a Card component" or "No existing pattern for this").
+3. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content, Roles/Permissions), identify 1-2 specific ambiguities that would change implementation. **Annotate with code context where relevant** (e.g., "You already have a Card component" or "No existing pattern for this").
+
+3b. **Entry-point consideration (standing — re-check here, don't trust the upstream grep alone)** — `conditional_reading`'s `HAS_PRODUCT_SIGNALS` grep runs once over the ROADMAP heading and is keyword-fragile (misses "panel", "modal", "view", "settings screen", etc.), so don't let it silently gate this. At this point in the analysis, consider: **did step 3 surface any UI/UX-category gray area, or does the phase add/change anything a user would navigate to?** If so, think through how the feature is reached — new nav entry, existing menu, route-only, deep link, permission-gated. Use judgment: if the answer is genuinely obvious from context (e.g. the project's existing convention is "every new page gets a sidebar entry," or the roadmap's IA section already settled this), just note the default taken and move on — don't interrupt with a question for something already decided. Only surface it as a gray area in `present_gray_areas` when it's a real ambiguity that would change implementation. This exists to catch built-but-unreachable UI before research/planning, not to force a question on every phase regardless of whether one's needed.
+
+3c. **Auth-strategy consideration (standing — re-check here, keyword generation alone is not enough)** — Gray-area generation in step 3 can surface "Session handling" or "Error responses" for an auth-flavored phase while never considering which production auth strategy is being built against. At this point, consider: **did step 3 surface any auth/login/session-category gray area, or does the phase goal contain auth/login/session/SSO/account signals?** If so, think through what the production authentication strategy is and whether a temporary/dev-only bypass needs its own tracked follow-up. Use judgment: if a prior phase or CONTEXT.md already settled the auth strategy, or the codebase already has a clear, singular auth pattern in place, don't re-ask — just confirm it still applies and move on. Only surface it as a gray area when the strategy is genuinely undecided. This exists to catch a dev-only bypass shipping as if it were the real strategy, not to force a question every time auth is touched.
+
+3d. **Roles/permissions consideration (standing — for any phase or project with >1 user role)** — If the phase or project involves more than one user role, don't assume a single shared UI is safe by default without at least considering it: what does each role see differently, which screens exist for one role but not another, what does the no-permission state look like. See `domain-probes.md`'s Roles & Permissions section for the question bank. Use judgment: if the project already has an established role-visibility pattern (documented in CONTEXT.md, an IA doc, or consistently applied in the existing codebase) and this phase clearly follows it, note that and move on rather than re-litigating it. Only surface it as a gray area in `present_gray_areas` when it's a genuine open question for this phase. This is about not silently defaulting to "same UI for everyone" without ever having considered the alternative — not about forcing a question on every multi-role phase.
 
 4. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation, or all already decided in prior phases), the phase may not need discussion.
 
@@ -470,6 +476,7 @@ Gray areas:
 - Behavior: Loading pattern — ALREADY DECIDED: infinite scroll (Phase 4)
 - Empty State: What shows when no posts exist — EmptyState component exists in ui/
 - Content: What metadata displays (time, author, reactions count)
+- Entry point: How users reach the feed — new sidebar link, existing nav tab, or route only?
 ```
 </step>
 

package/rcode/workflows/execute-sprint.md

@@ -183,11 +183,12 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
    - Subagent route: spawn rcode-executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
    - Main route: execute tasks using standard flow (step name="execute")
 3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
-   - Verify key-files.created exist on disk with `[ -f ]`
+   - Re-run each task's `<verify><automated>` block (from SPRINT.md, across all segments) now that all segments have landed. Only proceed to PASSED if every one exits 0.
    - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
-   - Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to SUMMARY
+   - Append `## Self-Check: PASSED` only if both the verify commands and the commit check succeed; otherwise `## Self-Check: FAILED`
+   - **State-sync (dashboard):** Segment subagents run with NO SUMMARY/commit per task, so `task_commit`'s state-sync block (5.5, above) never fires for individual tasks inside a segment — unlike Pattern A, Pattern B only registers/moves state.json stories here, once, after all segments land. Run the same `state sprint start` / `state story add` / `state story move --status done` loop from `task_commit` step 5.5 for every task across every segment before marking the sprint complete. If execution is interrupted mid-segment (checkpoint pause, crash, manual stop), the tasks already completed in landed segments will have NO state.json story yet — resuming this plan MUST run this same reconciliation loop for those already-done tasks before continuing to the next segment, not just at final aggregation.
 
-   **Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.
+   **Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Re-run the failed segment's task-level `<verify><automated>` commands directly. Only reclassify as successful if those commands exit 0 — the runtime-bug explanation alone is not sufficient to mark the task done.
 
 
 
@@ -534,7 +535,7 @@ within a budget of `workflow.node_repair_budget` (default: 2). Track:
 Repair strategies:
 - **RETRY** — re-run the same task with the failure context as added input.
 - **DECOMPOSE** — split into smaller subtasks (only if the original was L/XL).
-- **PRUNE** — drop the task from the sprint scope and record under "Issues Encountered" in SUMMARY.
+- **PRUNE** — drop the task from the sprint scope and record under "Issues Encountered" in SUMMARY, prefixed with the literal marker `PRUNED:` (e.g. `PRUNED: Task 4 "X" dropped after repair budget exhausted — not implemented.`). This marker is required so `offer_next` can detect incomplete plans and block false "Phase complete"/"Milestone done" routing.
 
 If the budget is exhausted without success: ESCALATE.
 
@@ -638,7 +639,31 @@ Keep STATE.md under 150 lines.
 </step>
 
 <step name="issues_review_gate">
-If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interactive → present issues, wait for acknowledgment.
+If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interactive → present issues, wait for acknowledgment. If any issue is prefixed `PRUNED:` (a repair-budget-exhausted task dropped from scope), this is a blocking gate regardless of yolo/interactive mode: the plan is not fully complete. `offer_next` must not route to Phase/Milestone done for this phase until the pruned task is resolved.
+</step>
+
+<step name="phase_status_gate">
+`state advance-plan` / `state update-progress` only ever touch `state.current_plan` — never `state.phases[i].status`. Without this step, `state.json` would show every phase stuck at its planning-time status forever, no matter how many plans finish.
+
+Recompute the same summaries-vs-plans/PRUNED check used in `offer_next` here, since phase status must be set before `update_roadmap` runs:
+
+```bash
+PLAN_COUNT=$(ls -1 .planning/phases/[current-phase-dir]/*-SPRINT.md 2>/dev/null | wc -l)
+SUMMARY_COUNT=$(ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l)
+PRUNED=$(grep -l "PRUNED:" .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null)
+```
+
+- If `SUMMARY_COUNT < PLAN_COUNT`, or any current-phase SUMMARY has `PRUNED:`: skip this step — the phase is not done, leave its status untouched.
+- Otherwise (all plans summarized, no `PRUNED:` markers): check for a passing VERIFICATION.md the same way `execute.md`'s `uat_gate` does:
+  ```bash
+  VERIFICATION_FILE=$(ls .planning/phases/[current-phase-dir]/*-VERIFICATION.md 2>/dev/null | head -1)
+  if [ -n "$VERIFICATION_FILE" ] && grep -qE "^status:[[:space:]]*passed" "$VERIFICATION_FILE" 2>/dev/null; then
+    node ".rcode/bin/rcode-tools.cjs" phase complete "${PHASE}"
+  else
+    node ".rcode/bin/rcode-tools.cjs" phase set-status "${PHASE}" executed
+  fi
+  ```
+  `phase complete` only when a passing VERIFICATION.md already exists; otherwise `phase set-status executed` (work done, awaiting `/rcode-verify-work`) — never leave the phase's status un-advanced when its plans are actually finished.
 </step>
 
 <step name="update_roadmap">
@@ -689,11 +714,14 @@ If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + e
 (ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null || true) | wc -l
 ```
 
+**Pruned-task check (required before routing B or C):** `grep -l "PRUNED:" .planning/phases/[current-phase-dir]/*-SUMMARY.md`. A file-count match (summaries = plans) is not the same as a complete phase — a plan can have a SUMMARY.md and still contain a task that was silently dropped by the PRUNE repair strategy. If any current-phase SUMMARY matches, do not use Route B/C wording; use Route A wording instead: "Plan {X} has an incomplete task — resolve before continuing" (name the pruned task from the SUMMARY's "Issues Encountered"), and suggest `/rcode-plan` to re-scope the dropped task before proceeding.
+
 | Condition | Route | Action |
 |-----------|-------|--------|
 | summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/rcode-execute {phase}` + `/rcode-verify-work`. STOP here. |
-| summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/rcode-plan {Z+1}` + `/rcode-verify-work {Z}` + `/rcode-discuss-phase {Z+1}` |
-| summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/rcode-complete-milestone` + `/rcode-verify-work` + `/rcode-add-phase` |
+| summaries = plans, any current-phase SUMMARY has `PRUNED:` | **A: Incomplete task** | Do not declare phase/milestone done. Show "Plan {X} has an incomplete task — resolve before continuing", suggest `/rcode-plan {phase}` to re-scope the pruned task. STOP here. |
+| summaries = plans, no `PRUNED:` markers, current < highest phase | **B: Phase done** | Show completion, suggest `/rcode-plan {Z+1}` + `/rcode-verify-work {Z}` + `/rcode-discuss-phase {Z+1}` |
+| summaries = plans, no `PRUNED:` markers, current = highest phase | **C: Milestone done** | Show banner, suggest `/rcode-complete-milestone` + `/rcode-verify-work` + `/rcode-add-phase` |
 
 All routes: `/clear` first for fresh context.
 </step>

package/rcode/workflows/execute-waves.md

@@ -450,10 +450,10 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
    If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
-   If pass:
+   If pass — these spot-checks confirm artifacts exist and were committed, not that the wave's goal was achieved. The self-check marker is the executor's own report, not an independent verification. Label the banner accordingly:
    ```
    ---
-   ## Wave {N} Complete
+   ## Wave {N} Artifacts Produced (pending verify/review gates)
 
    **{Plan ID}: {Plan Name}**
    {What was built — from SUMMARY.md}

package/rcode/workflows/execute.md

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

package/rcode/workflows/help.md

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

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

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