projecta-rrr 1.19.1 → 1.20.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.20.0] - 2026-03-22
+
+### Added
+
+- **YAML Frontmatter STATE.md** - Machine-readable state with `schema_version: 2`, consolidated `frontmatter.js` module replacing 4+ duplicate parsers across codebase
+- **Structured HANDOFF.json** - Machine-readable pause/resume alongside `.continue-here.md` with priority chain (HANDOFF.json > .continue-here.md > STATE.md)
+- **Stub Detection** - Tree-sitter context-aware analysis detecting TODO/FIXME/empty implementations per-plan during execution (`stub-detector.js`)
+- **Two-Stage Verification** - Stage 1 correctness check (including stubs), Stage 2 quality review (non-blocking advisory by default, configurable to blocking)
+- **`/rrr:next` Command** - Auto-routing with 8-state routing table and `--dry-run` preview mode
+- **`/rrr:ship` Command** - PR creation via `gh` CLI with planning artifacts as description, graceful fallback to `SHIP-READY.md`
+- **Cross-Phase Regression Gate** - Runs prior phases' test suites before new phase execution with affected-files filter, caching, and `--skip-regression` escape hatch
+- **PLAN.md `test_command:` Schema** - Per-plan test discovery via frontmatter field
+- **Auto-Advance Pipeline** - `--auto` flag on `/rrr:execute-phase` chains discuss→plan→execute with triple budget caps (per-step, per-pipeline, wall-clock) and `.planning/.stop-auto` stop-file
+- **Node Repair** - Retry→decompose→prune→escalate recovery chain with max depth 1, Pushpa error classification integration, git rollback before repair, HANDOFF.json checkpointing
+
+### Changed
+
+- All STATE.md consumers now use `frontmatter.js` with dual-read (YAML first, regex fallback)
+- `pause-work.md` now writes HANDOFF.json alongside `.continue-here.md`
+- `pipeline.js` delegates to `frontmatter.js` instead of local parser
+- `verify-phase.md` restructured into two-stage workflow
+- `execute-plan.md` includes per-plan stub scan and node repair on task failure
+- `execute-phase.md` includes regression gate (blocking) and auto-advance pipeline
+- `transition.md` includes advisory regression check
+
 ## [1.19.1] - 2026-02-11
 
 ### Fixed

package/commands/rrr/execute-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rrr:execute-phase
 description: Execute all plans in a phase with wave-based parallelization
-argument-hint: "<phase-number>"
+argument-hint: "<phase-number> [--auto] [--dry-run] [--step-cap=30m] [--pipeline-cap=4h] [--wall-cap=6h]"
 allowed-tools:
   - Read
   - Write
@@ -20,6 +20,8 @@ Execute all plans in a phase using wave-based parallel execution.
 Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
 
 Context budget: ~15% orchestrator, 100% fresh per subagent.
+
+When `--auto` flag is passed, chains discuss-plan-execute automatically for the phase (and subsequent phases if applicable). Pipeline enforces triple budget caps and checks for `.planning/.stop-auto` stop-file before each step. Use `--dry-run` with `--auto` to preview the pipeline plan without executing.
 </objective>
 
 <execution_context>
@@ -34,6 +36,8 @@ Phase: $ARGUMENTS
 
 @.planning/ROADMAP.md
 @.planning/STATE.md
+@rrr/lib/pipeline.js
+@rrr/lib/budget-caps.js
 </context>
 
 <process>

package/commands/rrr/next.md

@@ -0,0 +1,301 @@
+---
+name: rrr:next
+description: Determine and execute the next action based on project state
+argument-hint: "[--dry-run]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - SlashCommand
+  - AskUserQuestion
+---
+
+<objective>
+Determine the next action based on STATE.md and either execute it or show what would happen (--dry-run).
+
+Single command that replaces the "read progress, decide, copy command, run command" workflow. This is the unit action that the auto-advance pipeline (Phase 70) will loop over.
+</objective>
+
+<execution_context>
+@rrr/lib/phase-paths.md
+@rrr/lib/state-schema.md
+@rrr/lib/milestone-utils.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+
+<step name="parse_arguments">
+**Parse arguments:**
+
+Check if `$ARGUMENTS` contains `--dry-run`:
+- If yes: set `DRY_RUN=true`
+- If no: set `DRY_RUN=false`
+</step>
+
+<step name="read_state">
+**Read and parse STATE.md:**
+
+Use Read tool to read `.planning/STATE.md`.
+
+**If file not found (no .planning/ directory):**
+
+```
+No RRR project found.
+
+Expected: .planning/STATE.md
+
+To start: /rrr:new-project
+```
+
+Exit.
+
+**Parse the Current Position section:**
+
+Extract these fields from the `## Current Position` section:
+- `Milestone:` value (e.g., "v1.20", "Between milestones")
+- `Phase:` value (e.g., "66 of 71 (State Infrastructure)", "--")
+- `Plan:` value (e.g., "4 of 4 in current phase", "--")
+- `Status:` value (e.g., "Phase complete", "Executing", "Ready to plan")
+
+**If Milestone field is missing:**
+
+```
+STATE.md missing Milestone field. Run /rrr:complete-milestone or /rrr:new-milestone to fix.
+```
+
+Exit.
+
+Parse phase number from Phase field (e.g., "66" from "66 of 71 (State Infrastructure)").
+Parse phase total from Phase field (e.g., "71" from "66 of 71 (State Infrastructure)").
+Parse phase name from Phase field (e.g., "State Infrastructure" from "66 of 71 (State Infrastructure)").
+</step>
+
+<step name="check_between_milestones">
+**Check for "Between milestones" state:**
+
+If `Milestone` equals `Between milestones`:
+
+1. Check if `.planning/MILESTONE-CONTEXT.md` exists:
+
+   **On macOS/Linux:**
+   ```bash
+   ls .planning/MILESTONE-CONTEXT.md 2>/dev/null
+   ```
+
+   **On Windows:**
+   Use Read tool to check existence.
+
+2. Route based on context existence:
+
+   **If MILESTONE-CONTEXT.md exists:**
+   - Action: "Create milestone from gathered context"
+   - Command: `/rrr:new-milestone`
+
+   **If MILESTONE-CONTEXT.md does NOT exist:**
+   - Action: "Discuss next milestone"
+   - Command: `/rrr:discuss-milestone`
+
+3. Go to **output step** with determined action and command.
+</step>
+
+<step name="check_special_statuses">
+**Check for special status values:**
+
+These statuses have direct mappings regardless of file counts:
+
+| Status | Action | Command |
+|--------|--------|---------|
+| `Defining requirements` | Define requirements | `/rrr:define-requirements` |
+| `Planning roadmap` | Create roadmap | `/rrr:create-roadmap` |
+| `Ready to discuss next milestone` | Discuss next milestone | `/rrr:discuss-milestone` |
+
+If Status matches any of these, go to **output step** with the mapped action and command.
+</step>
+
+<step name="locate_phase">
+**Locate current phase directory:**
+
+Use `find_phase_dir()` from phase-paths library to locate the current phase:
+
+```bash
+PHASE_NUM={parsed phase number}
+PHASE_DIR=$(find_phase_dir "$PHASE_NUM")
+if [ -z "$PHASE_DIR" ]; then
+  echo "Phase $PHASE_NUM directory not found"
+fi
+```
+
+If phase directory not found and Status is "Ready to plan":
+- Action: "Plan phase {phase_num} ({phase_name})"
+- Command: `/rrr:plan-phase {phase_num}`
+- Go to **output step**.
+
+If phase directory not found and Status is NOT "Ready to plan":
+- Use AskUserQuestion to ask user what to do.
+- Exit.
+</step>
+
+<step name="count_files">
+**Count plan and summary files in phase directory:**
+
+```bash
+PLAN_COUNT=$(ls -1 "${PHASE_DIR}"/*-PLAN.md 2>/dev/null | wc -l | tr -d ' ')
+SUMMARY_COUNT=$(ls -1 "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null | wc -l | tr -d ' ')
+```
+
+Also check for UAT gaps:
+
+```bash
+UAT_GAPS=$(grep -l "status: diagnosed" "${PHASE_DIR}"/*-UAT.md 2>/dev/null | wc -l | tr -d ' ')
+```
+</step>
+
+<step name="route">
+**Determine next action based on state and file counts:**
+
+**Priority 1: UAT gaps exist (UAT_GAPS > 0)**
+
+- Action: "Plan gap closure for phase {phase_num} UAT issues"
+- Command: `/rrr:plan-phase {phase_num} --gaps`
+
+**Priority 2: Status is "Ready to plan" or no PLAN.md files (PLAN_COUNT = 0)**
+
+- Action: "Plan phase {phase_num} ({phase_name})"
+- Command: `/rrr:plan-phase {phase_num}`
+
+**Priority 3: Status is "Ready to execute" or "Executing" (unexecuted plans exist: SUMMARY_COUNT < PLAN_COUNT)**
+
+- Action: "Execute phase {phase_num} ({phase_name})"
+- Command: `/rrr:execute-phase {phase_num}`
+
+**Priority 4: Phase complete (SUMMARY_COUNT = PLAN_COUNT AND PLAN_COUNT > 0)**
+
+Read ROADMAP.md to determine if more phases remain in the milestone.
+
+Parse the Phases section to find all phase numbers in the current milestone.
+Identify the current phase number and the highest phase number.
+
+**If current phase < highest phase (more phases remain):**
+
+Find the next phase from ROADMAP.md:
+- Read the `## Phases` section
+- Find the phase entry AFTER the current one
+- Extract next phase number and name
+
+Before routing, update STATE.md:
+- Phase: `{next_phase_num} of {phase_total} ({next_phase_name})`
+- Plan: `Not started`
+- Status: `Ready to plan`
+- Last activity: `{today} -- Transitioned from Phase {current} to Phase {next}`
+
+Then:
+- Action: "Transition to Phase {next_phase_num} ({next_phase_name}) and plan it"
+- Command: `/rrr:plan-phase {next_phase_num}`
+
+**If current phase = highest phase (last phase in milestone):**
+
+- Action: "Complete milestone (all phases done)"
+- Command: `/rrr:complete-milestone`
+
+**Priority 5: Ambiguous state**
+
+If none of the above conditions match, use AskUserQuestion:
+
+```
+Unable to determine next action automatically.
+
+Current state:
+- Milestone: {value}
+- Phase: {value}
+- Plan: {value}
+- Status: {value}
+
+What would you like to do?
+```
+
+Provide options:
+- "Run /rrr:progress for full status"
+- "Plan current phase"
+- "Execute current phase"
+
+Exit after user responds.
+</step>
+
+<step name="output">
+**Display result based on dry-run flag:**
+
+**If DRY_RUN is true:**
+
+```
+## Dry Run
+
+**Current state:**
+- Milestone: {milestone}
+- Phase: {phase}
+- Plan: {plan}
+- Status: {status}
+
+**Next action:** {action description}
+**Command:** `{command}`
+
+Run `/rrr:next` (without --dry-run) to execute.
+```
+
+Exit. Do NOT execute the command.
+
+**If DRY_RUN is false:**
+
+```
+## Next: {action description}
+
+Executing `{command}`...
+```
+
+Then use SlashCommand to invoke the determined command:
+
+```
+SlashCommand(command_name="{command_name}", command_args="{command_args}")
+```
+
+Where:
+- `command_name` is the full slash command name (e.g., "rrr:execute-phase")
+- `command_args` is the arguments string (e.g., "68")
+
+</step>
+
+</process>
+
+<edge_cases>
+**Handle these edge cases gracefully:**
+
+1. **No .planning/ directory:** Show "No RRR project found" and suggest `/rrr:new-project`
+
+2. **STATE.md missing Milestone field:** Warn and suggest running `/rrr:complete-milestone` or `/rrr:new-milestone`
+
+3. **Phase directory not found:** If status says phase should exist but directory is missing, suggest planning it
+
+4. **Ambiguous state:** When automatic routing fails, use AskUserQuestion to present options
+
+5. **Phase complete but can't determine next phase:** Read ROADMAP.md for phase list; if ambiguous, ask user
+
+6. **All plans executed but status not updated:** Detect SUMMARY_COUNT = PLAN_COUNT even if Status still says "Executing" -- treat as phase complete
+</edge_cases>
+
+<success_criteria>
+- [ ] Reads STATE.md and determines correct next action for every status value
+- [ ] `--dry-run` shows what would happen without executing
+- [ ] Normal mode executes the determined action via SlashCommand
+- [ ] Routing covers all STATE.md status values from state-schema.md
+- [ ] Between milestones state routes correctly (with/without MILESTONE-CONTEXT.md)
+- [ ] Edge cases handled gracefully (no project, missing fields, ambiguous state)
+- [ ] Command is lean -- no progress bars, no semantic search status, no audit runs
+- [ ] Routing logic is self-contained (not delegating to progress.md)
+</success_criteria>

package/commands/rrr/pause-work.md

@@ -89,9 +89,34 @@ Start with: [specific first action when resuming]
 Be specific enough for a fresh Claude to understand immediately.
 </step>
 
+<step name="write_handoff_json">
+**Write structured HANDOFF.json alongside .continue-here.md:**
+
+```bash
+# Create HANDOFF.json in same phase directory for machine-readable resume
+node -e "
+const { writeHandoff } = require('$RRR_DIR/lib/handoff');
+writeHandoff({
+  phase: '[XX-name]',
+  plan: '[current plan number]',
+  task: [current task number],
+  total_tasks: [total tasks],
+  status: '[in_progress|blocked]',
+  last_updated: new Date().toISOString(),
+  decisions: [/* key decisions from this session */],
+  blockers: [/* any blockers */],
+  next_action: '[specific first action when resuming]'
+}, '[phase-dir-path]');
+" 2>/dev/null || echo "HANDOFF.json write skipped (handoff.js not available)"
+```
+
+This enables the Priority 1 resume path in `/rrr:resume-work` (HANDOFF.json > .continue-here.md > STATE.md).
+</step>
+
 <step name="commit">
 ```bash
 git add .planning/milestones/**/phases/*/.continue-here.md
+git add .planning/milestones/**/phases/*/HANDOFF.json 2>/dev/null
 git commit -m "wip: [phase-name] paused at task [X]/[Y]"
 ```
 </step>
@@ -116,6 +141,7 @@ To resume: /rrr:resume-work
 
 <success_criteria>
 - [ ] .continue-here.md created in correct phase directory
+- [ ] HANDOFF.json created alongside .continue-here.md
 - [ ] All sections filled with specific content
 - [ ] Committed as WIP
 - [ ] User knows location and how to resume