@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/workflows/audit-fix.md

@@ -0,0 +1,211 @@
+<purpose>
+Autonomous audit-to-fix pipeline. Runs an audit, parses findings, classifies each as
+auto-fixable vs manual-only, spawns executor agents for fixable issues, runs tests
+after each fix, and commits atomically with finding IDs for traceability.
+</purpose>
+
+@.rcode/references/karpathy-guidelines.md
+
+<available_agent_types>
+- rcode-executor — executes a specific, scoped code change
+</available_agent_types>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+- Print the usage block below
+- STOP — do not proceed
+
+**Usage:**
+```
+/rcode-audit-fix [--max N] [--severity high|medium|all] [--dry-run] [--source audit]
+```
+
+**Examples:**
+```
+/rcode-audit-fix
+/rcode-audit-fix --max 10 --severity high
+/rcode-audit-fix --dry-run
+```
+
+<process>
+
+<step name="parse-arguments">
+Extract flags from the user's invocation:
+
+- `--max N` — maximum findings to fix (default: **5**)
+- `--severity high|medium|all` — minimum severity to process (default: **medium**)
+- `--dry-run` — classify findings without fixing (shows classification table only)
+- `--source <audit>` — which audit to run (default: **audit-uat**)
+
+Validate `--source` is a supported audit. Currently supported:
+- `audit-uat`
+
+If `--source` is not supported, stop with an error:
+```
+Error: Unsupported audit source "{source}". Supported sources: audit-uat
+```
+</step>
+
+<step name="run-audit">
+Invoke the source audit command and capture output.
+
+For `audit-uat` source:
+```bash
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init audit-uat 2>/dev/null || echo "{}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Read existing UAT and verification files to extract findings:
+- Glob: `.planning/phases/*/*-UAT.md`
+- Glob: `.planning/phases/*/*-VERIFICATION.md`
+
+Parse each finding into a structured record:
+- **ID** — sequential identifier (F-01, F-02, ...)
+- **description** — concise summary of the issue
+- **severity** — high, medium, or low
+- **file_refs** — specific file paths referenced in the finding
+</step>
+
+<step name="classify-findings">
+For each finding, classify as one of:
+
+- **auto-fixable** — clear code change, specific file referenced, testable fix
+- **manual-only** — requires design decisions, ambiguous scope, architectural changes, user input needed
+- **skip** — severity below the `--severity` threshold
+
+**Classification heuristics** (err on manual-only when uncertain):
+
+Auto-fixable signals:
+- References a specific file path + line number
+- Describes a missing test or assertion
+- Missing export, wrong import path, typo in identifier
+- Clear single-file change with obvious expected behavior
+
+Manual-only signals:
+- Uses words like "consider", "evaluate", "design", "rethink"
+- Requires new architecture or API changes
+- Ambiguous scope or multiple valid approaches
+- Requires user input or design decisions
+- Cross-cutting concerns affecting multiple subsystems
+- Performance or scalability issues without clear fix
+
+**When uncertain, always classify as manual-only.**
+</step>
+
+<step name="present-classification">
+Display the classification table:
+
+```
+## Audit-Fix Classification
+
+| # | Finding | Severity | Classification | Reason |
+|---|---------|----------|---------------|--------|
+| F-01 | Missing export in index.ts | high | auto-fixable | Specific file, clear fix |
+| F-02 | No error handling in payment flow | high | manual-only | Requires design decisions |
+| F-03 | Test stub with 0 assertions | medium | auto-fixable | Clear test gap |
+```
+
+If `--dry-run` was specified, **stop here and exit**. The classification table is the
+final output — do not proceed to fixing.
+</step>
+
+<step name="fix-loop">
+For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
+
+**a. Spawn executor agent:**
+```
+Task(
+  prompt="Fix finding {ID}: {description}. Files: {file_refs}. Make the minimal change to resolve this specific finding. Do not refactor surrounding code.",
+  subagent_type="rcode-executor"
+)
+```
+
+**b. Run tests:**
+```bash
+npm test 2>&1 | tail -20
+```
+
+**c. If tests pass** — commit atomically:
+```bash
+git add {changed_files}
+git commit -m "fix({scope}): resolve {ID} — {description}"
+```
+The commit message **must** include the finding ID (e.g., F-01) for traceability.
+
+**d. If tests fail** — revert changes, mark finding as `fix-failed`, and **stop the pipeline**:
+```bash
+git checkout -- {changed_files} 2>/dev/null
+```
+Log the failure reason and stop processing — do not continue to the next finding.
+A test failure indicates the codebase may be in an unexpected state, so the pipeline
+must halt to avoid cascading issues. Remaining auto-fixable findings will appear in the
+report as `not-attempted`.
+</step>
+
+<step name="report">
+Present the final summary:
+
+```
+## Audit-Fix Complete
+
+**Source:** {audit_command}
+**Findings:** {total} total, {auto} auto-fixable, {manual} manual-only
+**Fixed:** {fixed_count}/{auto} auto-fixable findings
+**Failed:** {failed_count} (reverted)
+
+| # | Finding | Status | Commit |
+|---|---------|--------|--------|
+| F-01 | Missing export | Fixed | abc1234 |
+| F-03 | Test stub | Fix failed | (reverted) |
+
+### Manual-only findings (require developer attention):
+- F-02: No error handling in payment flow — requires design decisions
+```
+</step>
+
+</process>
+
+<success_criteria>
+- Auto-fixable findings processed sequentially until --max reached or a test failure stops the pipeline
+- Tests pass after each committed fix (no broken commits)
+- Failed fixes are reverted cleanly (no partial changes left)
+- Pipeline stops after the first test failure (no cascading fixes)
+- Every commit message contains the finding ID
+- Manual-only findings are surfaced for developer attention
+- --dry-run produces a useful standalone classification table
+</success_criteria>
+
+## Success Criteria
+
+- [ ] All auto-fixable findings processed sequentially; each committed with its finding ID in the commit message
+- [ ] Tests pass after each committed fix — no broken commits in git history
+- [ ] Failed fixes reverted cleanly with no partial changes left in the working tree
+- [ ] Pipeline stops after the first test failure (non-cascading)
+- [ ] Manual-only findings listed separately for developer attention
+- [ ] `--dry-run` produces a standalone classification table with finding IDs and fixability verdicts
+
+## On Error
+
+If arguments are invalid, missing files, or subagent fails:
+- Validate inputs match expected format
+- Check that required files exist
+- Retry with clearer arguments or report the specific error to the user
+
+
+## On Completion
+
+/rcode-audit — re-run audit to verify fixes applied correctly
+/rcode-review — review the auto-applied changes
+/rcode-progress — see overall project state
+
+## ▶ Next Up
+
+- /rcode-verify-phase {phase}
+- /rcode-audit {phase}
+- /rcode-progress
+
+## Next Up
+
+- `/rcode-verify-work` — verify that auto-fixed issues no longer reproduce
+- `/rcode-code-review` — review the generated fixes before shipping

package/rcode/workflows/audit-milestone.md

@@ -0,0 +1,193 @@
+# Workflow: rcode-audit-milestone
+
+<purpose>
+Cross-phase audit of milestone completion. Reads all SUMMARY.md files from completed phases, compares their outcomes to the original ROADMAP goals, flags gaps, and generates an audit report showing completion percentage and decision traceability.
+</purpose>
+
+## Step 0 — Parse arguments
+
+Parse `$ARGUMENTS`:
+- `--help` or `-h` → print usage and stop:
+  ```
+  /rcode-audit-milestone [<unverified-count>] [--fix-drift] [--strict] [--report]
+  ```
+- A bare integer (e.g. `28`) → `HINT_UNVERIFIED_COUNT = 28` (pre-computed by rcode-status for display; use as expected minimum in the scan)
+- `--fix-drift` → `FIX_DRIFT = true` (after audit, suggest the drift sync command)
+- `--strict` → `STRICT = true`
+- `--report` → `WRITE_REPORT = true`
+
+If `HINT_UNVERIFIED_COUNT` is set, print at the top of the audit output:
+```
+ℹ Expecting ~{HINT_UNVERIFIED_COUNT} phases to verify (from rcode-status)
+```
+
+## Step 1 — Locate milestone context
+
+Determine the active milestone. Check:
+
+1. Is there a `.planning/current-milestone.txt` file?
+2. If not, find the most recent directory in `.planning/milestones/`
+
+If neither exists:
+
+```
+⚠ No active milestone found. Start a new one:
+
+/rcode-new-milestone <name>
+```
+
+STOP.
+
+Store path as `$MILESTONE_DIR`.
+
+## Step 2 — Load original goals
+
+Read `$MILESTONE_DIR/ROADMAP.md` and extract the Goals section.
+
+Parse into array `$ORIGINAL_GOALS` (just the text of each goal).
+
+## Step 3 — Scan all phases
+
+List all directories in `$MILESTONE_DIR/phases/` and find every SUMMARY.md file.
+
+For each SUMMARY.md:
+- Extract the phase name (from the phase directory name or filename)
+- Extract the "Outcomes" or "Summary" section
+- Extract "Decisions Made" section if present
+- Store in array `$PHASE_SUMMARIES`
+
+## Step 4 — Audit completeness
+
+For each `$ORIGINAL_GOALS`:
+
+1. Search all phase SUMMARY.md files for text matching the goal
+2. If found, mark as ✓ COMPLETED
+3. If partially addressed, mark as ◐ PARTIAL
+4. If not addressed, mark as ✗ NOT ADDRESSED
+
+Create audit report showing coverage percentage:
+
+```
+Goal Coverage:
+  ✓ Goal 1: COMPLETED
+  ◐ Goal 2: PARTIAL (addressed in Phase 2, not Phase 3)
+  ✗ Goal 3: NOT ADDRESSED
+
+Coverage: 67% (2/3 goals fully addressed)
+```
+
+## Step 5 — Check for scope creep
+
+Count total phases and compare to original phase count in ROADMAP. If actual > planned:
+
+```
+⚠ Scope creep: Planned {planned} phases, executed {actual}. Review ROADMAP updates.
+```
+
+## Step 6 — Trace decisions
+
+If `--strict` flag set:
+
+- For each decision in any SUMMARY.md, verify it's documented in STATE.md under "Decisions Made"
+- Flag undocumented decisions
+
+```
+Decision Traceability (--strict mode):
+  ✓ Decision in Phase 1 documented in STATE
+  ⚠ Decision in Phase 2 NOT in STATE.md
+```
+
+## Step 7 — Generate report
+
+Create `.planning/audit-{TIMESTAMP}.md`:
+
+```markdown
+# Audit Report: {MILESTONE_NAME}
+
+**Date:** ISO-DATE
+**Milestone:** {MILESTONE_DIR}
+
+## Executive Summary
+
+{coverage_percentage}% of original goals completed.
+
+## Goal Coverage
+
+{detailed goal audit}
+
+## Scope
+
+- Planned phases: {count}
+- Executed phases: {count}
+- Variance: {+/- count}
+
+## Decision Traceability
+
+{decision_audit, if --strict}
+
+## Recommendations
+
+[Auto-generated based on gaps]
+```
+
+If `--report` flag set, also print the report to stdout. Otherwise, just save to file.
+
+## Success Criteria
+
+- Audit report created with goal coverage assessment
+- All phases scanned for outcomes
+- Original goals compared to actual outcomes
+- Report saved to `.planning/audit-*.md`
+
+## On Error
+
+If no SUMMARY.md files found, **do not dead-halt** (closes #234). Probe
+for executed-phase signals and offer recovery options:
+
+```bash
+PLANS=$(find "$MILESTONE_DIR" \( -name PLAN.md -o -name '*-SPRINT.md' \) 2>/dev/null | wc -l)
+GIT_FEAT=$(git log --oneline --grep='^feat' 2>/dev/null | wc -l)
+APPS=$(ls -d apps packages src 2>/dev/null | wc -l)
+```
+
+If `PLANS > 0` AND (`GIT_FEAT > 0` OR `APPS > 0`):
+
+```
+⚠ {PLANS} phases planned, 0 SUMMARY.md, {GIT_FEAT} feat commits, code present.
+  Phases were executed but never formally closed.
+
+  Options:
+    1. Synthesize SUMMARY.md per phase from SPRINT.md + git log [recommended]
+       (groups commits by phase tag like "feat(03-1):", writes a
+        first-pass SUMMARY.md the user can edit)
+    2. Run /rcode-verify-phase NN per phase (manual close path)
+    3. Continue audit anyway (only assesses what is documented — likely
+       reports 0% goal coverage)
+    0. Cancel
+```
+
+In `mode: yolo` (read via `node .rcode/bin/rcode-tools.cjs config-get
+mode`), auto-pick option 1. In guided mode, ask. STOP after the user
+picks 0 or 2; resume audit at Step 4 after option 1 completes.
+
+If `PLANS == 0`:
+
+```
+⚠ No phase summaries and no plans found. Have phases been executed?
+  Check: {MILESTONE_DIR}/phases/
+  Start one: /rcode-plan
+```
+
+STOP.
+
+If ROADMAP missing:
+
+```
+⚠ ROADMAP.md missing. Cannot audit without original goals.
+  Create one: /rcode-new-milestone
+```
+
+## Next Up
+
+- `/rcode-plan-milestone-gaps` — create fix phases for every gap the audit found
+- `/rcode-complete-milestone` — mark milestone complete when all gaps are resolved

package/rcode/workflows/audit-plans.md

@@ -0,0 +1,260 @@
+# Workflow: rcode-audit plans
+
+<purpose>
+Forward-looking planning integrity audit. Reads every SPRINT.md, ROADMAP.md,
+REQUIREMENTS.md, and STATE.md in the current milestone and checks for:
+  1. Structural completeness  — phases with no sprints, sprints with no tasks, tasks missing must_haves
+  2. Status consistency       — STATE.md current pointers vs actual sprint/phase status
+  3. Dependency integrity     — depends_on and requirements references that don't resolve
+  4. Next action recommendation — one concrete /rcode-* command to run next
+
+Unlike /rcode-audit-milestone (backward-looking), this audit is forward-looking:
+it checks *planned* items before they are executed.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains `--help` or `-h`:
+
+```
+/rcode-audit plans [--report] [--strict]
+```
+
+**Examples:**
+```
+/rcode-audit plans
+/rcode-audit plans --report
+/rcode-audit plans --strict
+```
+
+STOP — do not proceed.
+
+## Step 1 — Locate planning root
+
+```bash
+PLANNING=".planning"
+ROADMAP="$PLANNING/ROADMAP.md"
+STATE="$PLANNING/STATE.md"
+REQS="$PLANNING/REQUIREMENTS.md"
+PHASES_DIR="$PLANNING/phases"
+```
+
+If `$PLANNING` does not exist:
+```
+⚠ No .planning/ directory found.
+  Run /rcode-new-milestone to start a milestone.
+```
+STOP.
+
+If `$ROADMAP` does not exist:
+```
+⚠ No ROADMAP.md found at $ROADMAP.
+  Run /rcode-new-milestone to define goals.
+```
+STOP.
+
+## Step 2 — Collect all sprint files
+
+```bash
+SPRINT_FILES=$(find "$PHASES_DIR" -name "*-SPRINT.md" | sort)
+PHASE_DIRS=$(find "$PHASES_DIR" -mindepth 1 -maxdepth 1 -type d | sort)
+SPRINT_COUNT=$(echo "$SPRINT_FILES" | grep -c . || echo 0)
+PHASE_COUNT=$(echo "$PHASE_DIRS" | grep -c . || echo 0)
+```
+
+Read STATE.md and extract:
+- `current_phase` — the phase ID listed as current
+- `current_sprint` — the sprint ID listed as current (if any)
+- `milestone` — the active milestone name
+
+Read ROADMAP.md and extract every numbered phase entry (lines like `## Phase NN` or
+table rows with phase IDs). Store as `$ROADMAP_PHASES`.
+
+Read REQUIREMENTS.md (if it exists) and extract every requirement ID
+(e.g. `HIST-1`, `AUTH-3`) from headings or definition lines. Store as `$KNOWN_REQS`.
+
+## Step 3 — Run checks
+
+Initialize counters: `ERRORS=0`, `WARNINGS=0`. Build a findings array.
+
+### Check A — Structural completeness
+
+**A1. Phase directories with no sprint file**
+
+For each directory in `$PHASE_DIRS`:
+- If `find "$phase_dir" -name "*-SPRINT.md" | wc -l` returns 0
+- AND no SUMMARY.md exists in that directory (i.e. not yet completed)
+- → WARN: `Phase {phase_id} has no SPRINT.md — run /rcode-plan to create one`
+
+**A2. Sprint files with no tasks**
+
+For each file in `$SPRINT_FILES`:
+- Read the file and check if a `<tasks>` block exists
+- If `<tasks>` block is empty (no `<task` entries inside it)
+- → WARN: `Sprint {sprint_id} has no tasks — run /rcode-sprint-planning to add stories`
+
+**A3. Tasks missing must_haves / acceptance criteria**
+
+For each sprint file:
+- Parse the YAML frontmatter block (`---` ... `---`)
+- Check if `must_haves` key is present and non-empty
+- If missing or empty AND the sprint status is not `completed`
+- → WARN: `Sprint {sprint_id} missing must_haves — add acceptance criteria before executing`
+
+**A4. ROADMAP phases with no matching directory**
+
+For each phase ID in `$ROADMAP_PHASES`:
+- Check if a directory matching that ID exists in `$PHASES_DIR`
+- If not, and the phase is not marked as skipped/cancelled in ROADMAP
+- → ERROR: `ROADMAP lists Phase {id} but no directory exists — run /rcode-add-phase {id}`
+
+### Check B — Status consistency
+
+**B1. STATE.md current_phase points to a non-existent or completed phase**
+
+Read `current_phase` from STATE.md.
+
+If the phase directory does not exist:
+- → ERROR: `STATE.md current_phase={id} but that phase directory does not exist`
+
+If a SUMMARY.md exists in that phase directory (meaning it was completed and closed):
+- → WARN: `STATE.md current_phase={id} is already completed (has SUMMARY.md) — run /rcode-next to advance`
+
+**B2. STATE.md current_sprint points to a sprint where all tasks are done**
+
+If STATE.md has a `current_sprint` value:
+- Find the matching SPRINT.md file
+- Count tasks with `status: done` vs total tasks
+- If all tasks are done and sprint status is not `completed`
+- → WARN: `Sprint {sprint_id} all tasks done but not closed — run /rcode-verify-phase to close it`
+
+**B3. Phase directories with a SUMMARY.md but no entry in ROADMAP as completed**
+
+For each phase in `$PHASE_DIRS`:
+- If SUMMARY.md exists, the phase is done
+- Check that ROADMAP.md reflects this (status column or checkmark)
+- If ROADMAP still shows it as active/planned
+- → WARN: `Phase {id} has SUMMARY.md (complete) but ROADMAP shows it as active — update ROADMAP`
+
+### Check C — Dependency integrity
+
+**C1. depends_on references non-existent sprint**
+
+For each sprint file:
+- Read the `depends_on` list from the YAML frontmatter
+- For each entry in `depends_on`, check if a SPRINT.md with that phase/sprint ID exists
+- If not found
+- → ERROR: `Sprint {sprint_id} depends_on {missing_id} which does not exist`
+
+**C2. requirements references unknown requirement ID**
+
+For each sprint file:
+- Read the `requirements` list from YAML frontmatter
+- For each requirement ID, check if it appears in `$KNOWN_REQS` (from REQUIREMENTS.md)
+- If REQUIREMENTS.md exists but the ID is missing
+- → WARN: `Sprint {sprint_id} references unknown requirement {req_id} — add it to REQUIREMENTS.md`
+
+**C3. Wave ordering: sprint with depends_on in a later wave**
+
+For each sprint file:
+- Read `wave` and `depends_on` from YAML frontmatter
+- For each dependency, find the wave of the dependency sprint
+- If dependency wave >= current sprint's wave
+- → ERROR: `Sprint {sprint_id} (wave {w}) depends on {dep_id} (wave {dw}) — circular or forward dependency`
+
+## Step 4 — Build findings report
+
+Format all findings into severity groups:
+
+```
+rcode ► AUDIT PLANS
+
+Scanned: {PHASE_COUNT} phases, {SPRINT_COUNT} sprints
+Milestone: {milestone}
+
+━━━ ERRORS ({error_count}) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{each ERROR finding, prefixed with ✗}
+
+━━━ WARNINGS ({warning_count}) ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{each WARNING finding, prefixed with ⚠}
+
+━━━ CLEAN ({clean_count}) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{each passing check, prefixed with ✓}
+
+━━━ NEXT ACTION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{recommendation — see Step 5}
+```
+
+If zero errors and zero warnings:
+```
+✓ All planning checks passed. Plans are coherent and ready to execute.
+```
+
+## Step 5 — Recommend next action
+
+Pick exactly ONE recommended next command based on highest-priority finding:
+
+| Condition (checked in order) | Recommendation |
+|---|---|
+| Any ERROR from Check C (dependency) | `/rcode-plan` — fix dependency before executing |
+| Any ERROR from Check A4 (ROADMAP phase missing) | `/rcode-add-phase {id}` — create the missing phase |
+| Any WARN from B1 (current_phase completed) | `/rcode-next` — advance to the next phase |
+| Any WARN from B2 (sprint all-done not closed) | `/rcode-verify-phase` — close the current sprint |
+| Any WARN from A1 (phase with no sprint) | `/rcode-plan` — create sprint plan for the earliest unplanned phase |
+| Any WARN from A2 (sprint no tasks) | `/rcode-sprint-planning {sprint_id}` — groom the empty sprint |
+| Any WARN from A3 (missing must_haves) | `/rcode-create-story` — add acceptance criteria |
+| Any WARN from C2 (unknown requirement) | edit `REQUIREMENTS.md` — define the missing requirement |
+| No findings | `/rcode-execute` — plans are clean, execute the next sprint |
+
+Print as:
+```
+► Recommended next step:
+  {command}
+  {one-line reason}
+```
+
+## Step 6 — Save report (if --report flag)
+
+If `--report` is in `$ARGUMENTS`, write findings to:
+```
+.planning/audit-plans-{YYYY-MM-DD}.md
+```
+
+Format:
+```markdown
+# Plan Audit — {milestone}
+
+**Date:** {ISO-DATE}
+**Phases scanned:** {count}
+**Sprints scanned:** {count}
+**Errors:** {count}
+**Warnings:** {count}
+
+## Findings
+
+{all findings with severity}
+
+## Next Action
+
+{recommendation}
+```
+
+## Success Criteria
+
+- [ ] Runs without modification on any project with `.planning/` + ROADMAP.md
+- [ ] Zero false positives on phases that have SUMMARY.md (already completed)
+- [ ] Dependency check correctly resolves phase/sprint IDs from file paths
+- [ ] Exactly one "next action" command printed at end
+- [ ] `--report` writes a dated file under `.planning/`
+
+## On Error
+
+- `.planning/` missing → prompt to run `/rcode-new-milestone`
+- ROADMAP.md missing → prompt to run `/rcode-new-milestone`
+- No sprint files found → report as WARNING and recommend `/rcode-plan`
+- REQUIREMENTS.md missing → skip C2 check silently (not all projects use it)
+
+## Next Up
+
+- `/rcode-discuss-phase` — revisit grey-area decisions flagged by the audit
+- `/rcode-plan` — re-plan phases that failed the structural check