@hanzlaa/rcode 4.10.6 → 4.12.0

package/rcode/references/source-of-truth-grounding.md

@@ -0,0 +1,80 @@
+# Source-of-Truth Grounding
+
+Loaded by any workflow/agent that generates domain terminology, schema fields,
+enum values, or seed data — discuss-phase, roadmapper, project-researcher,
+planner, sprint-checker.
+
+## The failure this prevents
+
+A real incident: a competency-tracking app's requirements referenced an
+authoritative Excel file (the actual HR competency matrix) and a meeting
+transcript explaining it. The planner never opened the Excel — it invented
+plausible-sounding competency names (`TECH`, `DELIV`, `COLLAB`, `GROWTH`,
+`IMPACT`) and level names (`Junior`, `Associate`, `Senior I/II/III`) that
+*sounded* right for a generic engineering-competency system. The real Excel
+defined different names (`Technical Skills`, `Delivery & Quality`,
+`Communication & Collaboration`, `Leadership & Coaching`, `Strategic Impact`,
+`Innovation & Improvement`) and different levels (`Potential`, `Competency`,
+`Proficiency`, `Expertise`, `Mastery`). The invented values got baked into
+the database schema, seed data, and UI labels — an entire app built on
+plausible-sounding fiction instead of the actual source of truth, discovered
+only when the user manually re-fed the same files back in and asked for a
+gap check.
+
+This is not a hypothetical edge case. Any project with domain-specific
+terminology defined by an external document (an HR/compliance matrix, a
+partner's API spec, a legal/regulatory definition list, a brand's existing
+design system, a client's glossary) is exposed to this failure the moment a
+planner treats "sounds plausible" as good enough.
+
+## The rule
+
+**If a source document exists — the user references it, provides a file
+path, pastes its content, or it's already sitting in the project (`docs/`,
+an attached spreadsheet, a transcript, an existing spec) — and it defines
+domain terminology, categories, enum values, or a data model that the
+current work touches, that document MUST be read in full before generating
+anything that uses those concepts. Extract the actual values verbatim.**
+
+- Don't paraphrase a defined term into a shorter or "cleaner" one. If the
+  source says `Communication & Collaboration`, the schema/seed/UI say
+  `Communication & Collaboration` — not `COLLAB`, not `Comm & Collab`.
+- Don't guess the count or order. If the source defines 6 categories, use
+  the 6 it defines — don't invent 5 that seem close enough.
+- Don't treat "I've seen similar systems before" as a substitute for reading
+  this one's actual source. Training-data familiarity with how competency
+  matrices *usually* look is exactly what produces plausible-but-wrong output.
+- Excel/spreadsheet files: read the actual cell contents (via a script,
+  `openpyxl`/`pandas`-equivalent, or unzipping the `.xlsx` and parsing the
+  shared-strings XML if no library is available) — not the filename, not an
+  assumption about what a file named "Competency Matrix" probably contains.
+- Transcripts/recordings-as-text: read the whole thing, not just the first
+  few lines — the real values are often stated once, in the middle, in
+  passing ("we have six core competencies, which is technical skills,
+  delivery quality, communication, collaboration...").
+
+## Self-check before presenting or committing
+
+After generating requirements/schema/seed-data/UI copy that should be
+grounded in a source document, do one pass comparing what you generated
+against the source: does every category/level/field name match verbatim?
+If you can't point to the specific line/cell in the source for a value you
+used, that value is invented — fix it before presenting, not after the user
+catches it.
+
+## Where this applies
+
+- **discuss-phase / new-project**: when a source document is mentioned or
+  present, read it during context-gathering, before requirements get
+  drafted — not after.
+- **project-researcher / phase-researcher**: cite the source document's
+  actual terminology in STACK.md/FEATURES.md, not an approximation.
+- **roadmapper**: phase success criteria referencing domain concepts use the
+  source's exact terms.
+- **planner**: schema fields, enum values, and seed-data tasks cite the
+  source document path and use its verbatim values — a task creating seed
+  data for a domain concept with a known source document is incomplete if
+  it doesn't reference that source.
+- **sprint-checker**: if PROJECT.md/REQUIREMENTS.md reference a source
+  document, flag as a blocker any schema/seed-data task whose field/enum
+  values aren't traceable to it.

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/2-plan/rcode-create-epics-and-stories/workflow.md

@@ -2,7 +2,7 @@
 
 **Goal:** Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value, creating detailed, actionable stories with complete acceptance criteria for development teams.
 
-**Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals.
+**Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals. Ground the product-strategist half of this role in `rcode-hussain-pm`'s calibrated judgment (MoSCoW/RICE prioritization, JTBD framing, explicit scope defense) rather than generic story-writing — same reasoning as `rcode-create-prd`'s workflow: this is a live, halt-and-wait conversation, so you take on the role directly instead of spawning a subagent.
 
 ## State-sync rule (NO EXCEPTIONS)
 

package/rcode/skills/actions/2-plan/rcode-create-prd/workflow.md

@@ -7,7 +7,15 @@ outputFile: '{planning_artifacts}/prd.md'
 
 **Goal:** Create comprehensive PRDs through structured workflow facilitation.
 
-**Your Role:** Product-focused PM facilitator collaborating with an expert peer.
+**Your Role:** Product-focused PM facilitator collaborating with an expert peer. This
+is a live, menu-driven, halt-and-wait conversation — spawning a subagent here would
+break that interactivity, so you take on the role directly rather than delegating it.
+Ground that role in `rcode-hussain-pm`'s actual calibrated judgment, not a generic
+"PM" framing: MoSCoW/RICE prioritization, JTBD framing over feature lists, defend
+scope by naming what's explicitly OUT of v1 and why, defer technical feasibility
+calls to Waleed and strategic go/no-go calls to Sadiq rather than making them
+yourself. See `rcode/agents/rcode-hussain-pm.md` for the full principle set if you
+need it — the summary above is what actually changes PRD-writing behavior day to day.
 
 You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
 

package/rcode/workflows/autonomous.md

@@ -52,30 +52,51 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 ## 0. Prerequisite check (greenfield guard)
 
-Before any phase work, verify the methodology chain has run:
+rcode supports two valid project-initialization paths, and this gate must
+accept either:
+- **Full chain:** `/rcode-create-prd` → `/rcode-new-milestone` → `/rcode-create-epics-and-stories`
+- **Direct roadmap path:** `/rcode-new-project` → `rcode-roadmapper` writes
+  ROADMAP.md directly with phases, no prd.md/epics.md produced — this is a
+  first-class supported path, not an edge case, and autonomous execution
+  only actually needs a ROADMAP.md with real phases in it to do phase work.
+
+Before any phase work, verify at least one path's minimum requirement is met:
 
 ```bash
 HAS_PRD=$( ( ls .planning/prd.md .planning/PRD.md .planning/prds/*.md .planning/milestones/*/PRD.md 2>/dev/null | head -1 ) && echo true || echo false)
-HAS_ROADMAP_MILESTONES=$(grep -qE "^## Milestone\s+M[0-9]+" .planning/ROADMAP.md 2>/dev/null && echo true || echo false)
 HAS_EPICS=$( ( ls .planning/epics.md .planning/EPICS.md .planning/epics/*.md .planning/milestones/*/EPICS.md 2>/dev/null | head -1 ) && echo true || echo false)
+# Milestone marker: accepts heading style ("## Milestone M1"), bold-prose style
+# ("**Milestone:** M1 — ..."), or PROJECT.md's own style ("## Current Milestone: M3 — ...")
+# — roadmapper's actual output uses the bold-prose form, which the old heading-only
+# regex never matched, permanently failing this gate for every project that used
+# the direct roadmap path. Fixed live: confirmed against a real project's ROADMAP.md.
+HAS_ROADMAP_MILESTONES=$(grep -qEi "milestone[:*]*\s*M[0-9]" .planning/ROADMAP.md 2>/dev/null && echo true || echo false)
+# Direct roadmap path's actual minimum: a ROADMAP.md with at least one real phase.
+HAS_ROADMAP_PHASES=$(grep -qE "^##\s*Phase\s+[0-9]|^\|\s*[0-9]+\s*\|" .planning/ROADMAP.md 2>/dev/null && echo true || echo false)
 SKIP_FLAG=$(echo "$ARGUMENTS" | grep -qE "\-\-skip-prerequisites" && echo true || echo false)
+
+FULL_CHAIN_OK=$([ "$HAS_PRD" = "true" ] && [ "$HAS_ROADMAP_MILESTONES" = "true" ] && [ "$HAS_EPICS" = "true" ] && echo true || echo false)
+DIRECT_PATH_OK=$([ "$HAS_ROADMAP_PHASES" = "true" ] && echo true || echo false)
 ```
 
-If `SKIP_FLAG=false` AND any prerequisite is missing, HALT with a clear message:
+If `SKIP_FLAG=false` AND both `FULL_CHAIN_OK` and `DIRECT_PATH_OK` are false, HALT with a clear message:
 
 ```
-⚠ Cannot run autonomous: missing prerequisite — {what}.
+⚠ Cannot run autonomous: no valid project initialization found.
+
+The autonomous flow needs either:
+  A) Full chain: /rcode-create-prd → /rcode-new-milestone → /rcode-create-epics-and-stories
+  B) Direct roadmap: /rcode-new-project (produces ROADMAP.md with phases directly)
 
-The autonomous flow assumes a project that has already gone through:
-  1. /rcode-create-prd               → produces .planning/prd.md
-  2. /rcode-new-milestone         → produces ROADMAP.md with M1..Mn
-  3. /rcode-create-epics-and-stories → produces .planning/epics.md
-  4. THEN /rcode-autonomous           ← you are here
+Neither was found — no ROADMAP.md with real phases exists, and the full
+chain's artifacts (prd.md, milestone-marked ROADMAP.md, epics.md) are also
+missing.
 
-Suggested first step: /rcode-{first-missing-command}
+Suggested first step: /rcode-new-project (recommended — simpler, fully
+supported) or /rcode-create-prd if you specifically want the full chain.
 
-If you genuinely want to skip these (rare — usually inverted methodology),
-re-invoke with: /rcode-autonomous --skip-prerequisites
+If you genuinely want to skip this check, re-invoke with:
+/rcode-autonomous --skip-prerequisites
 ```
 
 If `SKIP_FLAG=true`: print a warning that downstream workflows may produce low-quality output without upstream artifacts, then proceed.
@@ -423,7 +444,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.
 
@@ -463,7 +484,7 @@ Task(
 )
 ```
 
-Store the agent task_id. The workflow can now start discussing the next phase while this phase executes in the background. Before starting post-execution routing for this phase, wait for the execute agent to complete.
+Store the agent task_id. The workflow can now start discussing the next phase while this phase executes in the background. Before starting post-execution routing for this phase, wait for the execute agent to complete, then run the mandatory reconciliation command below (same as the non-interactive path) before continuing.
 
 **If `INTERACTIVE` is NOT set (default):** Run execute inline as before.
 
@@ -471,6 +492,24 @@ Store the agent task_id. The workflow can now start discussing the next phase wh
 Skill(skill="rcode-execute", args="${PHASE_NUMBER} --no-transition")
 ```
 
+**Mandatory reconciliation (run this bash command directly, every phase, no exceptions):**
+`execute.md`'s own state-write steps (`phase set-status`/`phase complete`) are
+documented but not mechanically guaranteed — a real unattended multi-phase
+run was observed skipping them, leaving `state.json` stuck at every phase's
+planning-time status while ROADMAP.md correctly showed them complete. Don't
+rely on remembering to do this; run it as its own step, immediately after
+execute returns, before moving to post-execution routing:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" state sync --from-disk >/dev/null 2>&1 || true
+```
+
+This is idempotent and cheap — it re-derives phase status from ROADMAP.md's
+actual `**Status:**` text (never downgrades an already-advanced status), so
+running it here closes the gap even if execute.md's own inline state-write
+steps were skipped during a long run. Do this for every phase in the loop,
+not just once at the end.
+
 ### 3c.5. Code Review and Fix
 
 Auto-invoke code review and fix chain. Autonomous mode chains both review and fix.
@@ -767,7 +806,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 +816,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 +848,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 +862,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

@@ -6,6 +6,7 @@ You are a thinking partner, not an interviewer. The user is the visionary — yo
 
 <required_reading>
 @.rcode/references/universal-anti-patterns.md
+@.rcode/references/source-of-truth-grounding.md
 </required_reading>
 
 <conditional_reading>
@@ -90,7 +91,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 +427,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 +477,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}