@hanzlaa/rcode 4.7.3 → 4.9.0

package/rcode/workflows/plan.md

@@ -47,12 +47,10 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 <!-- 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 ? '@.rcode/references/ui-brand.md' : ''}
-@.rcode/references/revision-loop.md
-@.rcode/references/gate-prompts.md
 @.rcode/references/karpathy-guidelines.md
 <!-- Read .rcode/references/agent-contracts.md only if defining or debugging agent contracts -->
-<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic -->
-@.rcode/references/thinking-models-planning.md
+<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic; thinking-models-planning.md (127 lines) only if features.thinking_partner is enabled -->
+${THINKING_PARTNER_ENABLED === 'true' ? '@.rcode/references/thinking-models-planning.md' : ''}
 </required_reading>
 
 <available_agent_types>
@@ -228,91 +226,9 @@ PHASE_INFO=$(node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "${PHASE}")
 
 ## 3.6. Handle `--gaps` Mode
 
-**Skip unless:** `GAPS_MODE=true`.
+**Skip unless:** `GAPS_MODE=true`. When active, read the full gap-closure procedure below (extracted to keep this file within AGENTS.md's 1000-line cap for the common, non-gaps-mode path).
 
-**Purpose:** Read `NNN-VERIFICATION.md`, extract failing/partial gaps, count existing plan files, and prepare a `gap_list` payload to feed the planner. On completion, control flow continues at step 8 (skipping CONTEXT.md gating, research, and validation-strategy creation).
-
-**Step 1: Locate VERIFICATION.md**
-
-```bash
-PHASE_DIR=$(node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "${PHASE}" --pick dir 2>/dev/null || echo "")
-# Fallback if --pick dir not supported. TODO(#118): expose roadmap --pick dir cleanly.
-if [[ -z "$PHASE_DIR" ]]; then
-  PHASE_DIR=$(ls -d .planning/phases/${padded_phase}-* 2>/dev/null | head -1)
-fi
-
-VERIFICATION_FILE=$(ls "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1)
-```
-
-**If `VERIFICATION_FILE` is empty:**
-```
-Error: No VERIFICATION.md found for Phase {X}. Gap-closure planning requires the phase to have run through the verifier first.
-
-Try:
-  /rcode-execute {X} ${RCODE_WS}      # run or re-run execution + verification
-```
-Exit workflow.
-
-**Step 2: Extract gaps from VERIFICATION.md**
-
-Parse the file for gap entries with `status: gap_found` or `status: partial`. Inspect these sections:
-- `## Automated Gap` (or `## Automated Gaps`)
-- `## Human Verification Required`
-- Any findings block that includes a `status:` field set to `gap_found` or `partial`
-
-Collect into `GAP_LIST` (an ordered list where each entry has: id, title, expected, actual, status, source_section, severity if present).
-
-If `GAP_LIST` is empty, display:
-```
-Phase {X} VERIFICATION.md contains no gap_found or partial items — nothing to close.
-Report: {VERIFICATION_FILE}
-```
-Exit workflow.
-
-**Step 3: Determine next plan number**
-
-```bash
-EXISTING_PLAN_COUNT=$(ls "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null | wc -l | tr -d ' ')
-# Issue #652 — no leading zeros in planning artifacts. Phase 8 not 08, plan 2 not 02.
-NEXT_PLAN_NUMBER=$((EXISTING_PLAN_COUNT + 1))
-PADDED_PHASE="${PHASE}"
-GAP_PLAN_FILENAME="${PADDED_PHASE}-${NEXT_PLAN_NUMBER}-SPRINT.md"
-GAP_PLAN_PATH="${PHASE_DIR}/${GAP_PLAN_FILENAME}"
-```
-
-If `EXISTING_PLAN_COUNT == 0`, there is no prior execution to reference. Display a warning but proceed — the planner can still close verification gaps.
-
-**Step 4: Gather prior plans for planner context**
-
-```bash
-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' ' ')
-```
-
-**Step 5: Display banner**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- rcode ► GAP-CLOSURE PLANNING — Phase {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Verification report: {VERIFICATION_FILE}
-Gaps to close:       {count(GAP_LIST)}
-Existing plans:      {EXISTING_PLAN_COUNT}
-New plan file:       {GAP_PLAN_FILENAME}
-```
-
-**Step 6: Skip ahead**
-
-Control flow jumps directly to step 8 (Spawn rcode-planner). Steps 4 (CONTEXT.md), 5 (Research), and 5.5 (Validation) are ALL skipped when `GAPS_MODE=true`.
-
-Step 8 will consume these variables when filling the planner prompt:
-- `GAP_LIST` — serialized list of gaps (id, title, expected, actual, status)
-- `GAP_PLAN_PATH` — exact output path the planner must write
-- `EXISTING_PLAN_FILES` / `EXISTING_SUMMARY_FILES` — prior phase context
-- `VERIFICATION_FILE` — authoritative source-of-truth
-
-After the planner returns, the existing plan-checker / revision loop (step 10 onward) runs unchanged — gap plans are verified just like normal plans.
+${GAPS_MODE === 'true' ? '@.rcode/references/plan-gaps-mode.md' : ''}
 
 ## 4. Load CONTEXT.md
 
@@ -679,23 +595,11 @@ Task(
 - **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
 
 **Thinking partner for architectural tradeoffs (conditional):**
-If `features.thinking_partner` is enabled, scan the checker's issues for architectural tradeoff keywords
-("architecture", "approach", "strategy", "pattern", "vs", "alternative"). If found:
-
-```
-The sprint-checker flagged an architectural decision point:
-{issue description}
-
-Brief analysis:
-- Option A: {approach_from_plan} — {pros/cons}
-- Option B: {alternative_approach} — {pros/cons}
-- Recommendation: {choice} aligned with {phase_goal}
-
-Apply this to the revision? [Yes] / [No, I'll decide]
+```bash
+THINKING_PARTNER_ENABLED=$(node ".rcode/bin/rcode-tools.cjs" config-get features.thinking_partner 2>/dev/null || echo "false")
 ```
-
-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.
+${THINKING_PARTNER_ENABLED === 'true' ? '@.rcode/references/plan-thinking-partner.md' : ''}
+If `features.thinking_partner` is disabled: skip this block entirely.
 
 ## 12. Revision Loop (Max 3 Iterations, 1 in autonomous/yolo mode)
 
@@ -805,16 +709,18 @@ Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 Before declaring plans ready, validate the wave-parallelism rule the planner declares: **same wave + overlapping `files_modified` = sequential, not parallel**. If two plans share `depends_on` (same wave) and both list the same file in `files_modified`, the planner should have marked the later one `sequential: true`. Catch the cases where it didn't.
 
 ```bash
-# For every pair of plans (A, B) with the same depends_on:
-#   if files_modified(A) ∩ files_modified(B) is non-empty:
-#     - the later plan (by sprint id) MUST declare sequential: true
-#     - and must list the conflicting files in its frontmatter
-
-node ".rcode/bin/rcode-tools.cjs" plan check-wave-overlaps "${PHASE_NUMBER}"
+# Skip if plan_count == 1 (from INIT JSON): with exactly one plan in the phase,
+# there is no second plan to overlap with — a conflict is structurally impossible.
+if [[ "${plan_count}" -eq 1 ]]; then
+  echo "Wave parallelism: skipped (single plan, overlap structurally impossible)."
+else
+  # For every pair of plans (A, B) with the same depends_on, if files_modified(A)
+  # ∩ files_modified(B) is non-empty, the later plan (by sprint id) MUST declare
+  # sequential: true and list the conflicting files in its frontmatter.
+  node ".rcode/bin/rcode-tools.cjs" plan check-wave-overlaps "${PHASE_NUMBER}"
+fi
 ```
-
-The CLI helper returns a JSON report:
-
+Returns (else branch only):
 ```json
 {
   "conflicts": [
@@ -841,15 +747,13 @@ The CLI helper returns a JSON report:
 3. Re-run the checker to confirm the updated frontmatter.
 4. Display: `Wave parallelism: {N} conflict(s) auto-corrected to sequential.`
 
-**If `conflicts` is empty:** Display `Wave parallelism: ✓ no file-overlap conflicts.` and proceed.
-
-This closes the wave-overlap gap — the rule was stated in `rcode-planner.md` but not enforced. Now it's enforced automatically.
+**If `conflicts` is empty:** Display `Wave parallelism: ✓ no file-overlap conflicts.` and proceed. (This closes the wave-overlap gap — the rule was stated in `rcode-planner.md` but not enforced until now.)
 
 ## 13. Requirements Coverage Gate
 
 After plans pass the checker (or checker is skipped), verify that all phase requirements are covered by at least one plan.
 
-**Skip if:** `phase_req_ids` is null or TBD (no requirements mapped to this phase).
+**Skip if:** `phase_req_ids` is null, `TBD`, or an empty array/list (no requirements mapped to this phase) — `[[ -z "$phase_req_ids" || "$phase_req_ids" == "TBD" || "$phase_req_ids" == "[]" || "$phase_req_ids" == "null" ]]` — proceed to step 14.
 
 **Step 1: Extract requirement IDs claimed by plans**
 ```bash
@@ -962,8 +866,9 @@ Display banner:
 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):
+Launch execute-phase using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting). Skill() keeps execute.md running in this same context — set `AUTO_CHAINED_FROM_PLAN=true` so execute.md's required_reading doesn't re-read files this context already loaded (see AUDIT-workflow-complexity.md finding 3):
 ```
+AUTO_CHAINED_FROM_PLAN=true
 Skill(skill="rcode-execute", args="${PHASE} --auto --no-transition ${RCODE_WS}")
 ```
 
@@ -1065,27 +970,11 @@ Verification: {Passed | Passed with override | Skipped}
 </offer_next>
 
 <windows_troubleshooting>
-**Windows users:** If sprint-plan freezes during agent spawning (common on Windows due to
-stdio deadlocks with MCP servers — see Claude Code issue anthropics/claude-code#28126):
-
-1. **Force-kill:** Close the terminal (Ctrl+C may not work)
-2. **Clean up orphaned processes:**
-   ```powershell
-   # Kill orphaned node processes from stale MCP servers
-   Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force
-   ```
-3. **Clean up stale task directories:**
-   ```powershell
-   # Remove stale subagent task dirs (Claude Code never cleans these on crash)
-   Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\tasks\*" -ErrorAction SilentlyContinue
-   ```
-4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json
-5. **Retry:** Restart Claude Code and run `/rcode-plan` again
-
-If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents:
-```
-/rcode-plan N --skip-research
+```bash
+# Windows-only content (stdio deadlock recovery) — skip the read on other platforms.
+WINDOWS=$([[ "$(uname -s 2>/dev/null)" == MINGW* || "$(uname -s 2>/dev/null)" == CYGWIN* || -n "$WINDIR" ]] && echo true || echo false)
 ```
+${WINDOWS === 'true' ? '@.rcode/references/plan-windows-troubleshooting.md' : ''}
 </windows_troubleshooting>
 
 <success_criteria>

package/rcode/workflows/quick.md

@@ -60,7 +60,7 @@ Procedure:
    Reason: bulk-detection threshold ({matched signal}) — auto-route avoids
            refusing and forcing you to re-paste the list.
    ```
-4. Dispatch `/rcode-add-phase {phase-slug}` and pass `$TASK` verbatim. The add-phase workflow uses the pre-extracted task list as the phase task list — no user re-entry needed.
+4. **Dispatch by calling the `Skill` tool — do NOT just print the banner as text.** The banner above is a *display*, not the dispatch itself. You must call `Skill(skill: "rcode-add-phase", args: "{phase-slug} " + $TASK)` (passing `$TASK` verbatim as the pre-extracted task list) immediately after printing the banner. Printing `/rcode-add-phase {phase-slug}` in a code block or banner without invoking the Skill tool is NOT dispatch — the routed command will never run and the workflow will stall (same failure mode documented in `do.md`'s dispatch step).
 5. STOP this workflow — add-phase takes over from here.
 
 If the bulk detection does NOT match, continue to scope_check.

package/rcode/workflows/scaffold-skill.md

@@ -117,6 +117,21 @@ if [ -n "$fails" ]; then
 fi
 ```
 
+## Step 3.5 — Prove It Moved the Needle
+
+Passing the 5-component check in Step 3 only proves the file has the right shape — a triggers block, an Overview, a Workflow, an Output Format, and Examples. It says nothing about whether loading the skill actually changes what an agent does. A skill can be structurally perfect and still be a no-op in practice: the model reads it, nods along, and then falls back to its untrained default the moment a real scenario hits.
+
+Do not mark a new or edited skill as ready to ship until you've run this gate:
+
+1. **Write the pressure scenario.** Take the exact situation the skill's triggers describe — the moment the skill is supposed to change the agent's behavior — and phrase it as a concrete task an agent could be handed cold, with no mention of the skill.
+2. **Run the control.** Spawn a fresh subagent with no memory of this conversation and the skill NOT loaded (do not mention it, do not point at its path). Give it the pressure scenario. Record what it does by default — this is almost always the suboptimal or wrong behavior the skill exists to correct.
+3. **Run the treatment.** Spawn a second fresh subagent, same scenario, this time with the skill loaded (either by having it available for the model to invoke, or by including its content directly in the prompt). Record what it does.
+4. **Compare.** The treatment run must diverge from the control run in the specific direction the skill claims to produce. "Both agents produced fine-looking output" is not a pass — the question is whether the skill was the reason for the difference. If the two runs land on the same behavior, the skill has no measurable effect yet, no matter how clean its markdown is.
+
+If the comparison shows no behavioral difference, the skill is not done. Go back and sharpen the Workflow section, the triggers, or the examples — whichever part failed to actually steer the model — and rerun this gate. Do not ship on structural compliance alone.
+
+Skip this gate only when scaffolding a brand-new, still-empty skill (Step 2's placeholders haven't been filled in yet — there's no behavior to test). Once real content replaces the placeholders, this gate becomes mandatory before the skill is considered ready.
+
 ## Step 4 — Confirm and Next Up
 
 Print:
@@ -127,13 +142,16 @@ Print:
 
   All 5 required components are present (triggers, Overview, Workflow,
   Output Format, Examples). The placeholders need real content before
-  the skill becomes useful.
+  the skill becomes useful — and once they're filled in, run Step 3.5
+  (Prove It Moved the Needle) before calling the skill done.
 
 ▶ Next Up
   $EDITOR rcode/skills/actions/<group>/rcode-<NAME>/SKILL.md
                                                   # fill in placeholders
   npx @hanzlaa/rcode install --force              # install to .claude/skills/
   node --test test/compliance.test.cjs            # verify compliance
+                                                  # then: control vs. treatment
+                                                  # subagent run (Step 3.5)
 ```
 
 ## Next Up

package/rcode/workflows/secure-phase.md

@@ -3,7 +3,8 @@ Verify threat mitigations for a completed phase. Confirm SPRINT.md threat regist
 </purpose>
 
 <required_reading>
-@.rcode/references/ui-brand.md
+<!-- ui-brand.md (254 lines): only load when the phase goal/CONTEXT.md contains UI signals — mirrors plan.md:49's PHASE_GOAL_HAS_UI pattern -->
+${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 </required_reading>
 
 <available_agent_types>
@@ -50,6 +51,11 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`,
 ```bash
 AUDITOR_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-security-auditor --raw)
 SECURITY_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+
+# 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)
 ```
 
 If `SECURITY_CFG` is `false`: exit with "Security enforcement disabled. Enable via /rcode-settings."

package/rcode/workflows/sprint-planning.md

@@ -1,41 +1,18 @@
 # Workflow: rcode-sprint-planning
 
 <purpose>
-Plan the next sprint. Authoritative implementation lives in the
-`rcode-sprint-planning` skill — this workflow delegates to it so every
-safety rail (capacity gate per #127, halt-at-menu per #124, state-sync
-per #198) fires identically whether the user invokes the slash command
-or the phrase-activated skill.
-
-The skill MUST be loaded before the in-line steps below run. If the skill
-file is missing (broken install), report and stop — do not silently fall
-back to the in-line implementation.
+Plan the next sprint and write a SPRINT.md. The in-line steps below ARE the
+authoritative path for this — this project's own history confirms it: 54/54
+real *-SPRINT.md files under .planning/phases/ were produced by this in-line
+flow, none by the rcode-sprint-planning skill.
+
+The `rcode-sprint-planning` skill (`.rcode/skills/rcode-sprint-planning/SKILL.md`,
+workflow at `.rcode/skills/rcode-sprint-planning/workflow.md`) is a SEPARATE tool:
+it generates `sprint-status.yaml` from `.planning/epics/` files (epic/story status
+tracking: backlog -> ready-for-dev -> in-progress -> review -> done), not a
+SPRINT.md. Do not delegate to it expecting a SPRINT.md output.
 </purpose>
 
-<delegate_to_skill>
-Required skill: `rcode-sprint-planning`
-Path:           `.rcode/skills/rcode-sprint-planning/SKILL.md`
-Workflow ref:   `.rcode/skills/rcode-sprint-planning/workflow.md`
-Fallback path:  `.claude/skills/rcode-sprint-planning/SKILL.md`
-
-Behaviour:
-1. Load the skill's `SKILL.md` and `workflow.md`. Apply every Critical
-   Rule from the workflow's `## CRITICAL RULES (NO EXCEPTIONS)` block,
-   including the capacity gate (step n="0") which MUST halt for
-   numeric capacity inputs before any story is committed.
-2. Run the skill's step files in order. The in-line steps below this
-   block are a fallback summary for legacy installs that lack the skill;
-   they are NOT the authoritative behaviour.
-3. After SPRINT.md is written, ALWAYS run:
-   `node .rcode/bin/rcode-tools.cjs state sync --from-disk`
-   so state.sprints[] reflects the new sprint.
-
-If skill files are missing: print
-"Sprint-planning skill not installed. Run: npx @hanzlaa/rcode install"
-and exit non-zero. Do not proceed with the legacy in-line steps because
-they bypass the capacity gate.
-</delegate_to_skill>
-
 <required_reading>
 @.rcode/references/output-format.md
 @.rcode/brain/best-practices/no-autonomous-bypass.md
@@ -52,7 +29,7 @@ Open with banner:
 ```
 TaskCreate: "Load phase scope + velocity", "Capacity gate (halt for numbers)", "Curate stories with user", "Register sprint + stories in state", "Write SPRINT.md", "Sync state", "Start sprint".
 Closure: `rcode ► SPRINT {NN.S} READY ✓ ({N} stories, {M} points)`
-Next Up: `/rcode-execute .planning/phases/{phase}/SPRINT.md`
+Next Up: `/rcode-execute .planning/phases/{phase}/{phase}-{plan}-SPRINT.md`
 </output_format>
 
 <process>
@@ -177,7 +154,7 @@ node .rcode/bin/rcode-tools.cjs state story add \
   --points {points}
 ```
 
-Write SPRINT.md to `.planning/phases/{phase_slug}/SPRINT.md`. Use `.rcode/templates/sprint.md` as a template if it exists; otherwise produce the file inline with these sections (the template file may be absent in this install). Fill in:
+Write SPRINT.md to `.planning/phases/{phase_slug}/{phase}-{plan}-SPRINT.md`. Use `.rcode/templates/sprint.md` as a template if it exists; otherwise produce the file inline with these sections (the template file may be absent in this install). Fill in:
 - Sprint goal
 - Stories table (from user-confirmed list)
 - Capacity section (velocity target, average, buffer)
@@ -203,13 +180,13 @@ Stories: {count} ({total_points} points)
 Capacity: {velocity_target} points ({buffer}% buffer)
 
 Next:
-  /rcode-execute .planning/phases/{phase}/SPRINT.md   ← execute the sprint
+  /rcode-execute .planning/phases/{phase}/{phase}-{plan}-SPRINT.md   ← execute the sprint
   /rcode-sprint-status                                ← check progress anytime
 ```
 
 ## Output Format
 
-- SPRINT.md at `.planning/phases/{phase_slug}/SPRINT.md`
+- SPRINT.md at `.planning/phases/{phase_slug}/{phase}-{plan}-SPRINT.md`
 - Sprint + stories registered in `.rcode/state.json`
 - Console summary with next-step commands
 

package/rcode/workflows/validate-phase.md

@@ -3,7 +3,8 @@ Audit Nyquist validation gaps for a completed phase. Generate missing tests. Upd
 </purpose>
 
 <required_reading>
-@.rcode/references/ui-brand.md
+<!-- ui-brand.md (254 lines): only load when the phase goal/CONTEXT.md contains UI signals — mirrors plan.md:49's PHASE_GOAL_HAS_UI pattern -->
+${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 @.rcode/references/karpathy-guidelines.md
 </required_reading>
 
@@ -32,6 +33,11 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 ```bash
 AUDITOR_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-nyquist-auditor --raw)
 NYQUIST_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.nyquist_validation --raw)
+
+# 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)
 ```
 
 If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /rcode-settings."