@hanzlaa/rcode 2.1.0

package/rihal/workflows/audit-fix.md

@@ -0,0 +1,190 @@
+<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>
+
+<available_agent_types>
+- rihal-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:**
+```
+/rihal:audit-fix [--max N] [--severity high|medium|all] [--dry-run] [--source audit]
+```
+
+**Examples:**
+```
+/rihal:audit-fix
+/rihal:audit-fix --max 10 --severity high
+/rihal: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 ".rihal/bin/rihal-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="rihal-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
+
+- [ ] Task completed as requested
+- [ ] Output saved or reported
+- [ ] State updated if necessary
+- [ ] No errors encountered
+
+## 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
+

package/rihal/workflows/audit-milestone.md

@@ -0,0 +1,155 @@
+# Workflow: rihal: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 — Usage check
+
+If `$ARGUMENTS` contains only `--help` or `-h`:
+
+```
+/rihal:audit-milestone [--strict] [--report]
+```
+
+**Examples:**
+```
+/rihal:audit-milestone
+/rihal:audit-milestone --strict --report
+```
+
+STOP — do not proceed.
+
+## 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:
+
+/rihal: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:
+
+```
+⚠ No phase summaries found. Have phases been executed?
+  Check: {MILESTONE_DIR}/phases/
+```
+
+If ROADMAP missing:
+
+```
+⚠ ROADMAP.md missing. Cannot audit without original goals.
+  Create one: /rihal:new-milestone
+```

package/rihal/workflows/audit-uat.md

@@ -0,0 +1,109 @@
+<purpose>
+Cross-phase audit of all UAT and verification files. Finds every outstanding item (pending, skipped, blocked, human_needed), optionally verifies against the codebase to detect stale docs, and produces a prioritized human test plan.
+</purpose>
+
+<process>
+
+<step name="initialize">
+Run the CLI audit:
+
+```bash
+AUDIT=$(node ".rihal/bin/rihal-tools.cjs" audit-uat --raw)
+```
+
+Parse JSON for `results` array and `summary` object.
+
+If `summary.total_items` is 0:
+```
+## All Clear
+
+No outstanding UAT or verification items found across all phases.
+All tests are passing, resolved, or diagnosed with fix plans.
+```
+Stop here.
+</step>
+
+<step name="categorize">
+Group items by what's actionable NOW vs. what needs prerequisites:
+
+**Testable Now** (no external dependencies):
+- `pending` — tests never run
+- `human_uat` — human verification items
+- `skipped_unresolved` — skipped without clear blocking reason
+
+**Needs Prerequisites:**
+- `server_blocked` — needs external server running
+- `device_needed` — needs physical device (not simulator)
+- `build_needed` — needs release/preview build
+- `third_party` — needs external service configuration
+
+For each item in "Testable Now", use Grep/Read to check if the underlying feature still exists in the codebase:
+- If the test references a component/function that no longer exists → mark as `stale`
+- If the test references code that has been significantly rewritten → mark as `needs_update`
+- Otherwise → mark as `active`
+</step>
+
+<step name="present">
+Present the audit report:
+
+```
+## UAT Audit Report
+
+**{total_items} outstanding items across {total_files} files in {phase_count} phases**
+
+### Testable Now ({count})
+
+| # | Phase | Test | Description | Status |
+|---|-------|------|-------------|--------|
+| 1 | {phase} | {test_name} | {expected} | {active/stale/needs_update} |
+...
+
+### Needs Prerequisites ({count})
+
+| # | Phase | Test | Blocked By | Description |
+|---|-------|------|------------|-------------|
+| 1 | {phase} | {test_name} | {category} | {expected} |
+...
+
+### Stale (can be closed) ({count})
+
+| # | Phase | Test | Why Stale |
+|---|-------|------|-----------|
+| 1 | {phase} | {test_name} | {reason} |
+...
+
+---
+
+## Recommended Actions
+
+1. **Close stale items:** `/rihal:verify-work {phase}` — mark stale tests as resolved
+2. **Run active tests:** Human UAT test plan below
+3. **When prerequisites met:** Retest blocked items with `/rihal:verify-work {phase}`
+```
+</step>
+
+<step name="test_plan">
+Generate a human UAT test plan for "Testable Now" + "active" items only:
+
+Group by what can be tested together (same screen, same feature, same prerequisite):
+
+```
+## Human UAT Test Plan
+
+### Group 1: {category — e.g., "Billing Flow"}
+Prerequisites: {what needs to be running/configured}
+
+1. **{Test name}** (Phase {N})
+   - Navigate to: {where}
+   - Do: {action}
+   - Expected: {expected behavior}
+
+2. **{Test name}** (Phase {N})
+   ...
+
+### Group 2: {category}
+...
+```
+</step>
+
+</process>