@hanzlaa/rcode 3.4.4 → 3.4.6

package/rihal/workflows/plan.md

@@ -44,12 +44,14 @@ End with Next Up routing to /rihal-execute.
 @.rihal/references/output-format.md
 Read all files referenced by the invoking prompt's execution_context before starting.
 
-@.rihal/references/ui-brand.md
+<!-- ui-brand.md (254 lines): only load when phase goal/CONTEXT.md contains UI signals (frontend|ui|component|design|style|brand) -->
+${PHASE_GOAL_HAS_UI ? '@.rihal/references/ui-brand.md' : ''}
 @.rihal/references/revision-loop.md
 @.rihal/references/gate-prompts.md
 @.rihal/references/agent-contracts.md
 @.rihal/references/gates.md
 @.rihal/references/karpathy-guidelines.md
+@.rihal/references/thinking-models-planning.md
 </required_reading>
 
 <available_agent_types>
@@ -68,15 +70,20 @@ Load all context in one call (paths only to minimize orchestrator context):
 ```bash
 INIT=$(node ".rihal/bin/rihal-tools.cjs" init sprint-plan "$PHASE")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_RESEARCHER=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-researcher 2>/dev/null)
+AGENT_SKILLS_RESEARCHER=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-phase-researcher 2>/dev/null)
 AGENT_SKILLS_PLANNER=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-planner 2>/dev/null)
-AGENT_SKILLS_CHECKER=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-checker 2>/dev/null)
+AGENT_SKILLS_CHECKER=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-sprint-checker 2>/dev/null)
 CONTEXT_WINDOW=$(node ".rihal/bin/rihal-tools.cjs" config-get context_window 2>/dev/null || echo "200000")
+
+# Detect UI signals in phase goal + CONTEXT.md to decide whether to load ui-brand.md (254 lines)
+PHASE_GOAL_HAS_UI=$(grep -iEl "frontend|ui|component|design|style|brand" \
+  .planning/phases/*${PHASE_NUMBER}*/*-CONTEXT.md \
+  .planning/ROADMAP.md 2>/dev/null | head -1)
 ```
 
 When `CONTEXT_WINDOW >= 500000`, the planner prompt includes prior phase CONTEXT.md files so cross-phase decisions are consistent (e.g., "use library X for all data fetching" from Phase 2 is visible to Phase 5's planner).
 
-Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
+Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status`, `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
 
 **If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
 
@@ -101,7 +108,7 @@ else
 fi
 ```
 
-When `GAPS_MODE=true`, the workflow switches to **gap-closure planning**: read the phase's VERIFICATION.md, extract verification gaps classified `gap_found` or `partial`, and produce a single new numbered plan file (`NNN-NN-PLAN.md`) that closes them. Research, CONTEXT.md gating, and VALIDATION.md creation are skipped — gaps are grounded in already-shipped code, not new design work.
+When `GAPS_MODE=true`, the workflow switches to **gap-closure planning**: read the phase's VERIFICATION.md, extract verification gaps classified `gap_found` or `partial`, and produce a single new numbered plan file (`NNN-NN-SPRINT.md`) that closes them. Research, CONTEXT.md gating, and VALIDATION.md creation are skipped — gaps are grounded in already-shipped code, not new design work.
 
 **If no phase number:** Detect next unplanned phase from roadmap.
 
@@ -150,109 +157,9 @@ PHASE_INFO=$(node ".rihal/bin/rihal-tools.cjs" roadmap get-phase "${PHASE}")
 
 **If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
 
-## 3.5. Handle PRD Express Path
-
-**Skip if:** No `--prd` flag in arguments.
-
-**If `--prd <filepath>` provided:**
-
-1. Read the PRD file:
-```bash
-PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null)
-if [ -z "$PRD_CONTENT" ]; then
-  echo "Error: PRD file not found: $PRD_FILE"
-  exit 1
-fi
-```
-
-2. Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Rihal ► PRD EXPRESS PATH
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Using PRD: {PRD_FILE}
-Generating CONTEXT.md from requirements...
-```
-
-3. Parse the PRD content and generate CONTEXT.md. The orchestrator should:
-   - Extract all requirements, user stories, acceptance criteria, and constraints from the PRD
-   - Map each to a locked decision (everything in the PRD is treated as a locked decision)
-   - Identify any areas the PRD doesn't cover and mark as "Claude's Discretion"
-   - **Extract canonical refs** from ROADMAP.md for this phase, plus any specs/ADRs referenced in the PRD — expand to full file paths (MANDATORY)
-   - Create CONTEXT.md in the phase directory
-
-4. Write CONTEXT.md:
-```markdown
-# Phase [X]: [Name] - Context
-
-**Gathered:** [date]
-**Status:** Ready for planning
-**Source:** PRD Express Path ({PRD_FILE})
-
-<domain>
-## Phase Boundary
-
-[Extracted from PRD — what this phase delivers]
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-{For each requirement/story/criterion in the PRD:}
-### [Category derived from content]
-- [Requirement as locked decision]
-
-### Claude's Discretion
-[Areas not covered by PRD — implementation details, technical choices]
-
-</decisions>
-
-<canonical_refs>
-## Canonical References
-
-**Downstream agents MUST read these before planning or implementing.**
-
-[MANDATORY. Extract from ROADMAP.md and any docs referenced in the PRD.
-Use full relative paths. Group by topic area.]
 
-### [Topic area]
-- `path/to/spec-or-adr.md` — [What it decides/defines]
+@rihal/workflows/plan-prd-express.md
 
-[If no external specs: "No external specs — requirements fully captured in decisions above"]
-
-</canonical_refs>
-
-<specifics>
-## Specific Ideas
-
-[Any specific references, examples, or concrete requirements from PRD]
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-[Items in PRD explicitly marked as future/v2/out-of-scope]
-[If none: "None — PRD covers phase scope"]
-
-</deferred>
-
----
-
-*Phase: XX-name*
-*Context gathered: [date] via PRD Express Path*
-```
-
-5. Commit:
-```bash
-node ".rihal/bin/rihal-tools.cjs" commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
-```
-
-6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).
-
-**Effect:** This completely bypasses step 4 (Load CONTEXT.md) since we just created it. The rest of the workflow (research, planning, verification) proceeds normally with the PRD-derived context.
 
 ## 3.6. Handle `--gaps` Mode
 
@@ -300,10 +207,10 @@ Exit workflow.
 **Step 3: Determine next plan number**
 
 ```bash
-EXISTING_PLAN_COUNT=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null | wc -l | tr -d ' ')
+EXISTING_PLAN_COUNT=$(ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null | wc -l | tr -d ' ')
 NEXT_PLAN_NUMBER=$(printf "%02d" $((EXISTING_PLAN_COUNT + 1)))
 PADDED_PHASE=$(printf "%02d" "${PHASE}")
-GAP_PLAN_FILENAME="${PADDED_PHASE}-${NEXT_PLAN_NUMBER}-PLAN.md"
+GAP_PLAN_FILENAME="${PADDED_PHASE}-${NEXT_PLAN_NUMBER}-SPRINT.md"
 GAP_PLAN_PATH="${PHASE_DIR}/${GAP_PLAN_FILENAME}"
 ```
 
@@ -312,7 +219,7 @@ If `EXISTING_PLAN_COUNT == 0`, there is no prior execution to reference. Display
 **Step 4: Gather prior plans for planner context**
 
 ```bash
-EXISTING_PLAN_FILES=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null | tr '\n' ' ')
+EXISTING_PLAN_FILES=$(ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null | tr '\n' ' ')
 EXISTING_SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null | tr '\n' ' ')
 ```
 
@@ -391,302 +298,64 @@ If "Run discuss-phase first":
   ```
   **Exit the sprint-plan workflow. Do not continue.**
 
-## 5. Handle Research
-
-**Skip if:** `--gaps` flag or `--skip-research` flag or `--reviews` flag.
-
-**If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
-
-**If RESEARCH.md missing OR `--research` flag:**
-
-**If no explicit flag (`--research` or `--skip-research`) and not `--auto`:**
-Ask the user whether to research, with a contextual recommendation based on the phase:
-
-If `TEXT_MODE` is true, present as a plain-text numbered list:
-```
-Research before planning Phase {X}: {phase_name}?
-
-1. Research first (Recommended) — Investigate domain, patterns, and dependencies before planning. Best for new features, unfamiliar integrations, or architectural changes.
-2. Skip research — Plan directly from context and requirements. Best for bug fixes, simple refactors, or well-understood tasks.
-
-Enter number:
-```
-
-Otherwise use AskUserQuestion:
-```
-AskUserQuestion([
-  {
-    question: "Research before planning Phase {X}: {phase_name}?",
-    header: "Research",
-    multiSelect: false,
-    options: [
-      { label: "Research first (Recommended)", description: "Investigate domain, patterns, and dependencies before planning. Best for new features, unfamiliar integrations, or architectural changes." },
-      { label: "Skip research", description: "Plan directly from context and requirements. Best for bug fixes, simple refactors, or well-understood tasks." }
-    ]
-  }
-])
-```
-
-If user selects "Skip research": skip to step 6.
-
-**If `--auto` and `research_enabled` is false:** Skip research silently (preserves automated behavior).
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Rihal ► RESEARCHING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning researcher...
-```
-
-### Spawn rihal-phase-researcher
-
-```bash
-PHASE_DESC=$(node ".rihal/bin/rihal-tools.cjs" roadmap get-phase "${PHASE}" --pick section)
-```
-
-Research prompt:
-
-```markdown
-<objective>
-Research how to implement Phase {phase_number}: {phase_name}
-Answer: "What do I need to know to PLAN this phase well?"
-</objective>
-
-<files_to_read>
-- {context_path} (USER DECISIONS from /rihal-discuss-phase)
-- {requirements_path} (Project requirements)
-- {state_path} (Project decisions and history)
-</files_to_read>
-
-${AGENT_SKILLS_RESEARCHER}
-
-<additional_context>
-**Phase description:** {phase_description}
-**Phase requirement IDs (MUST address):** {phase_req_ids}
-
-**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines
-**Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, research should account for project skill patterns
-</additional_context>
-
-<output>
-Write to: {phase_dir}/{phase_num}-RESEARCH.md
-</output>
-```
-
-```
-Task(
-  prompt=research_prompt,
-  subagent_type="rihal-phase-researcher",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
-```
-
-### Handle Researcher Return
 
-- **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
-- **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
+@rihal/workflows/plan-research-validation.md
 
-## 5.5. Create Validation Strategy
-
-Skip if `nyquist_validation_enabled` is false OR `research_enabled` is false.
-
-If `research_enabled` is false and `nyquist_validation_enabled` is true: warn "Nyquist validation enabled but research disabled — VALIDATION.md cannot be created without RESEARCH.md. Plans will lack validation requirements (Dimension 8)." Continue to step 6.
-
-**But Nyquist is not applicable for this run** when all of the following are true:
-- `research_enabled` is false
-- `has_research` is false
-- no `--research` flag was provided
-
-In that case: **skip validation-strategy creation entirely**. Do **not** expect `RESEARCH.md` or `VALIDATION.md` for this run, and continue to Step 6.
-
-```bash
-grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null || true
-```
-
-**If found:**
-1. Read template: `.rihal/templates/VALIDATION.md`
-2. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md` (use Write tool)
-3. Fill frontmatter: `{N}` → phase number, `{phase-slug}` → slug, `{date}` → current date
-4. Verify:
-```bash
-test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED=true" || echo "VALIDATION_CREATED=false"
-```
-5. If `VALIDATION_CREATED=false`: STOP — do not proceed to Step 6
-6. If `commit_docs`: `commit "docs(phase-${PHASE}): add validation strategy"`
-
-**If not found:** Warn and continue — plans may fail Dimension 8.
-
-## 5.55. Security Threat Model Gate
-
-> Skip if `workflow.security_enforcement` is explicitly `false`. Absent = enabled.
-
-```bash
-SECURITY_CFG=$(node ".rihal/bin/rihal-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
-SECURITY_ASVS=$(node ".rihal/bin/rihal-tools.cjs" config-get workflow.security_asvs_level --raw 2>/dev/null || echo "1")
-SECURITY_BLOCK=$(node ".rihal/bin/rihal-tools.cjs" config-get workflow.security_block_on --raw 2>/dev/null || echo "high")
-```
 
-**If `SECURITY_CFG` is `false`:** Skip to step 5.6.
-
-**If `SECURITY_CFG` is `true`:** Display banner:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Rihal ► SECURITY THREAT MODEL REQUIRED (ASVS L{SECURITY_ASVS})
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Each SPRINT.md must include a <threat_model> block.
-Block on: {SECURITY_BLOCK} severity threats.
-Opt out: set security_enforcement: false in .planning/config.json
-```
-
-Continue to step 5.6. Security config is passed to the planner in step 8.
-
-## 5.6. UI Design Contract Gate
-
-> Skip if `workflow.ui_phase` is explicitly `false` AND `workflow.ui_safety_gate` is explicitly `false` in `.planning/config.json`. If keys are absent, treat as enabled.
-
-```bash
-UI_PHASE_CFG=$(node ".rihal/bin/rihal-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
-UI_GATE_CFG=$(node ".rihal/bin/rihal-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true")
-```
-
-**If both are `false`:** Skip to step 6.
-
-Check if phase has frontend indicators:
-
-```bash
-PHASE_SECTION=$(node ".rihal/bin/rihal-tools.cjs" roadmap get-phase "${PHASE}" 2>/dev/null)
-echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
-HAS_UI=$?
-```
-
-**If `HAS_UI` is 0 (frontend indicators found):**
-
-Check for existing UI-SPEC:
-```bash
-UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-```
-
-**If UI-SPEC.md found:** Set `UI_SPEC_PATH=$UI_SPEC_FILE`. Display: `Using UI design contract: ${UI_SPEC_PATH}`
-
-**If UI-SPEC.md missing AND `UI_GATE_CFG` is `true`:**
+## 6. Check Existing Plans
 
-Read auto-chain state:
 ```bash
-AUTO_CHAIN=$(node ".rihal/bin/rihal-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
+ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null || true
 ```
 
-**If `AUTO_CHAIN` is `true` (running inside a `--chain` or `--auto` pipeline):**
+**If exists AND `--reviews` flag:** Skip prompt — go straight to replanning (the purpose of `--reviews` is to replan with review feedback).
 
-Auto-generate UI-SPEC without prompting:
-```
-Skill(skill="rihal-ui-phase", args="${PHASE} --auto ${Rihal_WS}")
-```
-After `rihal-ui-phase` returns, re-read:
-```bash
-UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-UI_SPEC_PATH="${UI_SPEC_FILE}"
-```
-Continue to step 6.
+**If exists AND no `--reviews` flag:** Ask the user what they'd like to do. Tailor the message to context — do NOT say "as per the workflow" or expose implementation details. Examples:
 
-**If `AUTO_CHAIN` is `false` (manual invocation):**
+- If `phase_status` is `complete` or `executed`:
+  > "Phase {N} ({name}) already shipped {plan_count} plans and is marked {status}. Do you want to review those plans, add more, or replan from scratch?"
 
-If `TEXT_MODE` is true, present as a plain-text numbered list:
-```
-Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning?
+- If `phase_status` is `in_progress` or `planned` (or null):
+  > "Phase {N} ({name}) already has {plan_count} plan(s). Want to add more, review what's there, or start fresh?"
 
-1. Generate UI-SPEC first — Run /rihal-ui-phase {N} then re-run /rihal-sprint-plan {N}
-2. Continue without UI-SPEC
-3. Not a frontend phase
+Always offer exactly three numbered options:
+1. Add more plans
+2. View existing plans
+3. Replan from scratch
 
-Enter number:
-```
+Wait for the user's choice before proceeding. Do not auto-select.
 
-Otherwise use AskUserQuestion:
-- header: "UI Design Contract"
-- question: "Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning?"
-- options:
-  - "Generate UI-SPEC first" → Display: "Run `/rihal-ui-phase {N} ${Rihal_WS}` then re-run `/rihal-sprint-plan {N} ${Rihal_WS}`". Exit workflow.
-  - "Continue without UI-SPEC" → Continue to step 6.
-  - "Not a frontend phase" → Continue to step 6.
+**If user picks option 2 (View existing plans):**
 
-**If `HAS_UI` is 1 (no frontend indicators):** Skip silently to step 5.7.
+Display a sprint summary table (sprint id → one-line goal).
 
-## 5.7. Schema Push Detection Gate
+Then run a **best-effort codebase overlap check** before showing the execute prompt — Closes #596.
 
-> Detects schema-relevant files in the phase scope and injects a mandatory `[BLOCKING]` schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.
+**This check is always informational. It never blocks, never errors, never fails the workflow.** If any step below cannot complete for any reason, skip it silently and proceed straight to the execute prompt.
 
-Check if any files in the phase scope match schema patterns:
+1. Read the SPRINT.md files for this phase (they are already on disk — no tool calls needed beyond `Read`).
+2. From each sprint's `files_modified:` frontmatter list, note which paths already exist on disk vs. which are new.
+3. Separately, look at the sprint *goals* and compare against modules/components the codebase already has. Use your knowledge from any files already read this session; do NOT spawn new reads just for this check.
+4. Report what you found — one compact block:
 
-```bash
-PHASE_SECTION=$(node ".rihal/bin/rihal-tools.cjs" roadmap get-phase "${PHASE}" --pick section 2>/dev/null)
 ```
-
-Scan `PHASE_SECTION`, `CONTEXT.md` (if loaded), and `RESEARCH.md` (if exists) for file paths matching these ORM patterns:
-
-| ORM | File Patterns |
-|-----|--------------|
-| Payload CMS | `src/collections/**/*.ts`, `src/globals/**/*.ts` |
-| Prisma | `prisma/schema.prisma`, `prisma/schema/*.prisma` |
-| Drizzle | `drizzle/schema.ts`, `src/db/schema.ts`, `drizzle/*.ts` |
-| Supabase | `supabase/migrations/*.sql` |
-| TypeORM | `src/entities/**/*.ts`, `src/migrations/**/*.ts` |
-
-Also check if any existing SPRINT.md files for this phase already reference these file patterns in `files_modified`.
-
-**If schema-relevant files detected:**
-
-Set `SCHEMA_PUSH_REQUIRED=true` and `SCHEMA_ORM={detected_orm}`.
-
-Determine the push command for the detected ORM:
-
-| ORM | Push Command | Non-TTY Workaround |
-|-----|-------------|-------------------|
-| Payload CMS | `npx payload migrate` | `CI=true PAYLOAD_MIGRATING=true npx payload migrate` |
-| Prisma | `npx prisma db push` | `npx prisma db push --accept-data-loss` (if destructive) |
-| Drizzle | `npx drizzle-kit push` | `npx drizzle-kit push` |
-| Supabase | `supabase db push` | Set `SUPABASE_ACCESS_TOKEN` env var |
-| TypeORM | `npx typeorm migration:run` | `npx typeorm migration:run -d src/data-source.ts` |
-
-Inject the following into the planner prompt (step 8) as an additional constraint:
-
-```markdown
-<schema_push_requirement>
-**[BLOCKING] Schema Push Required**
-
-This phase modifies schema-relevant files ({detected_files}). The planner MUST include
-a `[BLOCKING]` task that runs the database schema push command AFTER all schema file
-modifications are complete but BEFORE verification.
-
-- ORM detected: {SCHEMA_ORM}
-- Push command: {push_command}
-- Non-TTY workaround: {env_hint}
-- If push requires interactive prompts that cannot be suppressed, flag the task for
-  manual intervention with `autonomous: false`
-
-This task is mandatory — the phase CANNOT pass verification without it. Build and
-type checks will pass without the push (types come from config, not the live database),
-creating a false-positive verification state.
-</schema_push_requirement>
+Codebase overlap check (best-effort):
+  ✓ N files already exist — plans will extend them
+  + M files are new — will be created
+  ⚠ Possible overlap: [file A] in the codebase may already cover [sprint X goal] — worth checking before executing
 ```
 
-Display: `Schema files detected ({SCHEMA_ORM}) — [BLOCKING] push task will be injected into plans`
+If nothing notable: one line — `No obvious conflicts detected.`
 
-**If no schema-relevant files detected:** Skip silently to step 6.
+**Hard rules (dead-ends — nothing here can cause failure):**
+- If a SPRINT.md can't be read → skip it, don't error
+- If files_modified is empty or absent → skip the file check, move on
+- If you're uncertain whether an overlap is real → don't mention it (false positives are noise)
+- If the whole check produces nothing → omit the block entirely, go straight to execute prompt
+- **Never ask a follow-up question about the overlap** — state it and move on
+- **Never refuse to show the execute prompt** because of an overlap finding
 
-## 6. Check Existing Plans
-
-```bash
-ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null || true
-```
-
-**If exists AND `--reviews` flag:** Skip prompt — go straight to replanning (the purpose of `--reviews` is to replan with review feedback).
-
-**If exists AND no `--reviews` flag:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch.
+Only after showing overlap results (or skipping them), show the execute prompt.
 
 ## 7. Use Context Paths from INIT
 
@@ -727,165 +396,43 @@ If missing and Nyquist is still enabled/applicable — ask user:
 
 Proceed to Step 8 only if user selects 2 or 3.
 
-## 8. Spawn rihal-planner Agent
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Rihal ► PLANNING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning planner...
-```
 
-**Gap-closure planner prompt (when `GAPS_MODE=true`):**
+@rihal/workflows/plan-spawn-planner.md
 
-When `GAPS_MODE=true`, use the prompt below in place of the standard planner prompt. The planner must emit **exactly one** new plan file at `${GAP_PLAN_PATH}` that closes the listed gaps. Do not create CONTEXT.md or RESEARCH.md references — gaps are grounded in already-shipped code.
+## 9. Handle Planner Return
 
-```markdown
-<planning_context>
-**Phase:** {phase_number}
-**Mode:** gap_closure
-**Phase goal:** {goal from ROADMAP.md}
+- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
+- **`## PHASE SPLIT RECOMMENDED`:** The planner determined the phase is too complex to implement all user decisions without simplifying them. Handle in step 9b.
+- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
+- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
 
-<files_to_read>
-- {VERIFICATION_FILE} (Authoritative verification report — source of truth for gaps)
-- {state_path} (Project State)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
-- Existing plan files in this phase: {EXISTING_PLAN_FILES}
-- Existing summary files in this phase: {EXISTING_SUMMARY_FILES}
-</files_to_read>
+**Sprint count guard (token cost protection — closes #584):**
 
-${AGENT_SKILLS_PLANNER}
+After planner returns `## PLANNING COMPLETE`, immediately count sprint files:
 
-<gap_list>
-{Serialized GAP_LIST — for each gap include id, title, expected behavior, actual behavior, status (gap_found|partial), and source section.}
-</gap_list>
-
-<output>
-Write a single new plan file to: {GAP_PLAN_PATH}
-
-Frontmatter MUST include:
----
-phase: {phase_number}
-plan_number: {NEXT_PLAN_NUMBER}
-gap_closure: true
-wave: 1
-depends_on: []
-files_modified: [...]
-autonomous: true|false
----
-
-Each gap in the list MUST be addressed by at least one task. Use the anti-shallow execution rules below.
-</output>
-</planning_context>
+```bash
+MAX_SPRINTS=$($TOOL config-get workflow.max_sprints_per_phase 2>/dev/null || echo "4")
+SPRINT_COUNT=$(find "${PHASE_DIR}" -maxdepth 1 -name "*-SPRINT.md" | wc -l | tr -d ' ')
 ```
 
-Proceed to the standard planner Task invocation below, but pass the gap-closure prompt above. After the planner returns, the normal plan-checker / revision loop (step 10+) runs unchanged.
-
----
-
-**Standard planner prompt (when `GAPS_MODE=false`):**
+If `SPRINT_COUNT > MAX_SPRINTS`:
 
-Planner prompt:
-
-```markdown
-<planning_context>
-**Phase:** {phase_number}
-**Mode:** {standard | gap_closure | reviews}
-
-<files_to_read>
-- {state_path} (Project State)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
-- {context_path} (USER DECISIONS from /rihal-discuss-phase)
-- {research_path} (Technical Research)
-- {verification_path} (Verification Gaps - if --gaps)
-- {uat_path} (UAT Gaps - if --gaps)
-- {reviews_path} (Cross-AI Review Feedback - if --reviews)
-- {UI_SPEC_PATH} (UI Design Contract — visual/interaction specs, if exists)
-${CONTEXT_WINDOW >= 500000 ? `
-**Cross-phase context (1M model enrichment):**
-- Prior phase CONTEXT.md files (locked decisions from earlier phases — maintain consistency)
-- Prior phase SUMMARY.md files (what was actually built — reuse patterns, avoid duplication)
-` : ''}
-</files_to_read>
-
-${AGENT_SKILLS_PLANNER}
-
-**Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
-
-**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines
-**Project skills:** Check .claude/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, plans should account for project skill rules
-
-</planning_context>
-
-<downstream_consumer>
-Output consumed by /rihal-execute-phase. Plans need:
-- Frontmatter (wave, depends_on, files_modified, autonomous)
-- Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task)
-- Verification criteria
-- must_haves for goal-backward verification
-</downstream_consumer>
-
-<deep_work_rules>
-## Anti-Shallow Execution Rules (MANDATORY)
-
-Every task MUST include these fields — they are NOT optional:
-
-1. **`<read_first>`** — Files the executor MUST read before touching anything. Always include:
-   - The file being modified (so executor sees current state, not assumptions)
-   - Any "source of truth" file referenced in CONTEXT.md (reference implementations, existing patterns, config files, schemas)
-   - Any file whose patterns, signatures, types, or conventions must be replicated or respected
-
-2. **`<acceptance_criteria>`** — Verifiable conditions that prove the task was done correctly. Rules:
-   - Every criterion must be checkable with grep, file read, test command, or CLI output
-   - NEVER use subjective language ("looks correct", "properly configured", "consistent with")
-   - ALWAYS include exact strings, patterns, values, or command outputs that must be present
-   - Examples:
-     - Code: `auth.py contains def verify_token(` / `test_auth.py exits 0`
-     - Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK`
-     - Docs: `README.md contains '## Installation'` / `API.md lists all endpoints`
-     - Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db`
-
-3. **`<action>`** — Must include CONCRETE values, not references. Rules:
-   - NEVER say "align X with Y", "match X to Y", "update to be consistent" without specifying the exact target state
-   - ALWAYS include the actual values: config keys, function signatures, SQL statements, class names, import paths, env vars, etc.
-   - If CONTEXT.md has a comparison table or expected values, copy them into the action verbatim
-   - The executor should be able to complete the task from the action text alone, without needing to read CONTEXT.md or reference files (read_first is for verification, not discovery)
-
-**Why this matters:** Executor agents work from the plan text. Vague instructions like "update the config to match production" produce shallow one-line changes. Concrete instructions like "add DATABASE_URL=postgresql://... , set POOL_SIZE=20, add REDIS_URL=redis://..." produce complete work. The cost of verbose plans is far less than the cost of re-doing shallow execution.
-</deep_work_rules>
-
-<quality_gate>
-- [ ] SPRINT.md files created in phase directory
-- [ ] Each plan has valid frontmatter
-- [ ] Tasks are specific and actionable
-- [ ] Every task has `<read_first>` with at least the file being modified
-- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
-- [ ] Every `<action>` contains concrete values (no "align X with Y" without specifying what)
-- [ ] Dependencies correctly identified
-- [ ] Waves assigned for parallel execution
-- [ ] must_haves derived from phase goal
-</quality_gate>
 ```
+⚠ Phase {N}: Planner created {SPRINT_COUNT} sprint files (limit: {MAX_SPRINTS}).
+  This phase is too large — the sprint-checker will be expensive and revision
+  loops will multiply the cost.
 
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="rihal-planner",
-  model="{planner_model}",
-  description="Plan Phase {phase}"
-)
+  Recommended: split this phase into two using /rihal-plan --split {N}
+
+Options:
+  1. Split phase now (recommended)
+  2. Continue anyway (accept higher token cost)
+  3. Re-plan with explicit 4-sprint limit
 ```
 
-## 9. Handle Planner Return
+In `mode: yolo` / autonomous: auto-select option 3 (re-plan with limit). Do not halt or ask.
 
-- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
-- **`## PHASE SPLIT RECOMMENDED`:** The planner determined the phase is too complex to implement all user decisions without simplifying them. Handle in step 9b.
-- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
-- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
+Re-plan prompt appended: `"IMPORTANT: Create at most {MAX_SPRINTS} SPRINT.md files. Merge smaller tasks into the nearest related sprint instead of creating new ones."`
 
 ## 9b. Handle Phase Split Recommendation
 
@@ -963,6 +510,7 @@ ${AGENT_SKILLS_CHECKER}
 Task(
   prompt=checker_prompt,
   subagent_type="rihal-sprint-checker",
+  model="sonnet",
   model="{checker_model}",
   description="Verify Phase {phase} plans"
 )
@@ -992,13 +540,23 @@ Apply this to the revision? [Yes] / [No, I'll decide]
 If yes: include the recommendation in the revision prompt. If no: proceed to revision loop as normal.
 If thinking_partner disabled: skip this block entirely.
 
-## 12. Revision Loop (Max 3 Iterations)
+## 12. Revision Loop (Max 3 Iterations, 1 in autonomous/yolo mode)
+
+**Mode-based iteration cap (token cost protection — closes #585):**
+
+```bash
+MAX_ITERATIONS=$($TOOL config-get workflow.max_checker_iterations 2>/dev/null || echo "")
+if [ -z "$MAX_ITERATIONS" ]; then
+  # Default: 1 in yolo/autonomous, 3 in guided
+  [ "$MODE" = "yolo" ] || [ -n "$AUTONOMOUS" ] && MAX_ITERATIONS=1 || MAX_ITERATIONS=3
+fi
+```
 
 Track `iteration_count` (starts at 1 after initial plan + check).
 Track `prev_issue_count` (initialized to `Infinity` before the loop begins).
 Track `stall_reentry_count` (starts at 0; incremented each time "Adjust approach" re-enters step 8).
 
-**If iteration_count < 3:**
+**If iteration_count < MAX_ITERATIONS:**
 
 **Sprint-checker malfunction guard (BLOCKER-class — added in v3.1.0 after #440):**
 
@@ -1072,6 +630,7 @@ Return what changed.
 Task(
   prompt=revision_prompt,
   subagent_type="rihal-planner",
+  model="sonnet",
   model="{planner_model}",
   description="Revise Phase {phase} plans"
 )
@@ -1232,7 +791,7 @@ Plans ready. Launching execute-phase...
 
 Launch execute-phase using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting):
 ```
-Skill(skill="rihal-execute-phase", args="${PHASE} --auto --no-transition ${Rihal_WS}")
+Skill(skill="rihal-execute", args="${PHASE} --auto --no-transition ${Rihal_WS}")
 ```
 
 The `--no-transition` flag tells execute-phase to return status after verification instead of chaining further. This keeps the auto-advance chain flat — each phase runs at the same nesting level rather than spawning deeper Task agents.
@@ -1253,7 +812,7 @@ The `--no-transition` flag tells execute-phase to return status after verificati
   Auto-advance stopped: Execution needs review.
 
   Review the output above and continue manually:
-  /rihal-execute-phase ${PHASE} ${Rihal_WS}
+  /rihal-execute ${PHASE} ${Rihal_WS}
   ```
 
 **If neither `--auto` nor config enabled:**
@@ -1286,7 +845,7 @@ Verification: {Passed | Passed with override | Skipped}
 
 /clear then:
 
-/rihal-execute-phase {X} ${Rihal_WS}
+/rihal-execute {X} ${Rihal_WS}
 
 ───────────────────────────────────────────────────────────────