@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/workflows/audit-uat.md

@@ -0,0 +1,114 @@
+<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 ".rcode/bin/rcode-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:** `/rcode-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 `/rcode-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>
+
+## Next Up
+
+- `/rcode-verify-work` — work through the outstanding UAT items
+- `/rcode-plan` — plan fix phases for blocked or human-needed items

package/rcode/workflows/audit-worktrees.md

@@ -0,0 +1,168 @@
+# Workflow: audit-worktrees
+
+<purpose>
+Scan for orphaned executor worktrees and branches left behind by rcode-execute.
+Reports each orphan with its age, merge status, and safe-to-delete verdict.
+With --prune, deletes confirmed-safe orphans automatically.
+</purpose>
+
+## Step 0 — Parse arguments
+
+- `--prune` → `PRUNE=true` — delete safe orphans after reporting
+- `--help` or `-h` → print usage and stop:
+  ```
+  /rcode-audit worktrees [--prune]
+  ```
+
+## Step 1 — Scan for orphaned worktrees
+
+Executor agents use branches prefixed `worktree-agent-`. Find all such branches
+and worktrees still present in the repo:
+
+```bash
+# Active worktrees with executor branches
+git worktree list --porcelain \
+  | awk 'BEGIN{p=""} /^worktree /{p=$2} /^branch /{if($2~/refs\/heads\/worktree-agent-/) print p"\t"$2}' \
+  > /tmp/rcode-active-wts.txt
+
+# Local branches with executor prefix (includes detached/removed worktrees)
+git branch --list 'worktree-agent-*' --format='%(refname:short)' \
+  > /tmp/rcode-orphan-br.txt
+
+ACTIVE_WT_COUNT=$(wc -l < /tmp/rcode-active-wts.txt)
+ORPHAN_BR_COUNT=$(wc -l < /tmp/rcode-orphan-br.txt)
+TOTAL=$((ACTIVE_WT_COUNT + ORPHAN_BR_COUNT))
+```
+
+If `TOTAL` is 0:
+
+```
+✓ No orphaned executor worktrees or branches found.
+```
+
+Stop.
+
+## Step 2 — For each orphan, gather intelligence
+
+For each entry (worktree or branch), run:
+
+```bash
+# Is it merged into the current branch?
+MERGED=$(git branch --merged HEAD --list '<branch>' 2>/dev/null | grep -c '<branch>')
+
+# When was the last commit on this branch?
+LAST_COMMIT=$(git log -1 --format="%ar %s" '<branch>' 2>/dev/null || echo "unknown")
+
+# How many commits does it have that are NOT on HEAD?
+AHEAD=$(git rev-list HEAD..'<branch>' --count 2>/dev/null || echo "?")
+```
+
+Build a report table:
+
+```
+rcode ► WORKTREE AUDIT
+══════════════════════════════════════════════════════════
+
+Orphaned executor artifacts: {TOTAL}
+
+  Branch                          Merged  Ahead  Last commit
+  ──────────────────────────────  ──────  ─────  ──────────────────────
+  worktree-agent-abc123           YES     0      3 days ago  feat: add auth
+  worktree-agent-def456           NO      2      1 hour ago  wip: migrations
+  ...
+
+Active worktrees still pointing to executor branches:
+  .claude/worktrees/agent-abc123  →  worktree-agent-abc123
+  ...
+```
+
+## Step 3 — Classify each orphan
+
+For each branch/worktree:
+
+- **SAFE** → `MERGED=YES` AND `AHEAD=0` — all commits are on HEAD, nothing to lose
+- **STALE** → `MERGED=YES` AND `AHEAD>0` — commits are ahead but branch is in merged list (rebased/squash-merged); verify before deleting
+- **UNMERGED** → `MERGED=NO` — DO NOT auto-delete; show explicitly and warn
+
+Print classification next to each entry.
+
+## Step 4 — Report summary
+
+```
+Summary:
+  SAFE to delete:     {N}  (merged, 0 ahead)
+  STALE (check first): {N}  (merged but ahead — may be rebase/squash)
+  UNMERGED (keep):    {N}  (not merged — manual review required)
+
+  To prune SAFE orphans: /rcode-audit worktrees --prune
+  To inspect UNMERGED:   git log HEAD..<branch> --oneline
+```
+
+If `PRUNE=false`, stop here.
+
+## Step 5 — Prune (only when --prune passed)
+
+Delete SAFE entries only. Never touch STALE or UNMERGED.
+
+For each SAFE branch:
+
+```bash
+# Remove the worktree if it still exists
+WT_PATH=$(awk -F'\t' '$2=="refs/heads/<branch>"{print $1}' /tmp/rcode-active-wts.txt)
+if [ -n "$WT_PATH" ] && [ -d "$WT_PATH" ]; then
+  git worktree remove "$WT_PATH" --force 2>/dev/null \
+    && echo "  ✓ removed worktree: $WT_PATH" \
+    || echo "  ⚠ could not remove worktree: $WT_PATH"
+fi
+
+# Delete the branch
+git branch -D '<branch>' 2>/dev/null \
+  && echo "  ✓ deleted branch: <branch>" \
+  || echo "  ⚠ could not delete branch: <branch>"
+```
+
+After all deletes, re-run Step 1 scan and confirm `TOTAL=0` for SAFE entries.
+
+Print final report:
+
+```
+Pruned: {N} safe orphans removed
+Kept:   {N} unmerged branches (manual review required)
+
+✓ Worktree cleanup complete
+```
+
+## Step 6 — Post-audit health note
+
+If any UNMERGED branches remain, print:
+
+```
+⚠ {N} unmerged executor branch(es) still present.
+  These have commits NOT on your current branch.
+  Inspect before deleting:
+
+  git log HEAD..worktree-agent-<id> --oneline
+  git show worktree-agent-<id>:<file>   # inspect specific file
+
+  To delete after manual review:
+  git worktree remove .claude/worktrees/<id> --force
+  git branch -D worktree-agent-<id>
+```
+
+## Success Criteria
+
+- [ ] All `worktree-agent-*` branches and worktrees found and reported
+- [ ] Each classified as SAFE / STALE / UNMERGED based on actual merge status
+- [ ] `--prune` deletes only SAFE entries, never UNMERGED
+- [ ] Post-prune confirmation scan verifies cleanup succeeded
+- [ ] Non-executor worktrees (feature branches, manual worktrees) are never touched
+
+## On Error
+
+- `git worktree list` fails → print `git not available or not a repo` and stop
+- `git branch -D` fails on a branch → skip it, note it in the report, continue
+
+## Next Up
+
+- `/rcode-status` — check overall project state after cleanup
+- `/rcode-do` — continue with your current work

package/rcode/workflows/audit.md

@@ -0,0 +1,207 @@
+# Workflow: rcode-audit
+
+<purpose>
+Single entry point for every kind of audit. Asks the user *what* to audit
+and dispatches to the right sub-workflow. Closes #234 — replaces the prior
+state where users had to know about six separate audit/verify commands by
+name (`audit-milestone`, `audit-uat`, `audit-fix`, `code-review --karpathy`,
+`verify-phase`, `verify-work`).
+
+Honours `.rcode/config.yaml`: in `mode: yolo`, the router skips the menu
+and auto-picks the most-relevant target based on project state. In
+`mode: guided` (default), it asks.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains `--help` or `-h`:
+
+```
+/rcode-audit                           # interactive — asks what to audit
+/rcode-audit plans [--report]         # → audit-plans (structural + status + deps check)
+/rcode-audit phase [<NN>]              # → /rcode-verify-phase
+/rcode-audit milestone [--strict]      # → /rcode-audit-milestone (with synth fallback)
+/rcode-audit uat                       # → /rcode-audit-uat
+/rcode-audit code [--scope=...]        # → /rcode-review --karpathy
+/rcode-audit fix                       # → /rcode-audit-fix
+/rcode-audit work                      # → /rcode-verify-work
+/rcode-audit lens [<1-15> | all]       # → /rcode-lens-audit (15-lens methodology)
+/rcode-audit worktrees [--prune]       # → scan + report orphaned executor worktrees/branches
+```
+
+**Examples:**
+```
+/rcode-audit
+/rcode-audit plans
+/rcode-audit plans --report
+/rcode-audit milestone --strict
+/rcode-audit phase 03
+/rcode-audit lens security
+/rcode-audit lens all
+```
+
+## Step 1 — Resolve mode + arguments
+
+```bash
+TOOL="node .rcode/bin/rcode-tools.cjs"
+MODE=$($TOOL config-get mode 2>/dev/null || echo "guided")
+DISCUSS=$($TOOL config-get workflow.discuss_mode 2>/dev/null || echo "adaptive")
+```
+
+Parse `$ARGUMENTS`:
+- First word ∈ {plans, phase, milestone, uat, code, fix, work, lens, worktrees} → set `$TARGET`, drop it from args, jump to Step 4.
+- Empty or unrecognised → continue to Step 2.
+
+## Step 2 — Detect project state
+
+Probe what's audit-able right now:
+
+```bash
+ROADMAP=$([ -f .planning/ROADMAP.md ] && echo yes || echo no)
+PHASES=$(ls -d .planning/phases/*/ 2>/dev/null | wc -l)
+PLANS=$(find .planning/phases \( -name PLAN.md -o -name '*-SPRINT.md' \) 2>/dev/null | wc -l)
+SUMMARIES=$(find .planning/phases -name SUMMARY.md 2>/dev/null | wc -l)
+UAT_FILES=$(find .planning -name 'UAT*.md' 2>/dev/null | wc -l)
+ON_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+DIRTY=$([ -n "$(git status --porcelain 2>/dev/null)" ] && echo yes || echo no)
+```
+
+Use these to decide which menu options are *relevant* and which to mark
+as `(no data — skip)`.
+
+## Step 3 — Ask user (guided mode only)
+
+Also probe for orphaned executor worktrees (add to context for Step 3 menu):
+
+```bash
+ORPHAN_WTS=$(git worktree list --porcelain \
+  | awk '/^branch /{if($2 ~ /refs\/heads\/worktree-agent-/) print $2}' \
+  | wc -l)
+ORPHAN_BR=$(git branch --list 'worktree-agent-*' 2>/dev/null | wc -l)
+ORPHANS=$((ORPHAN_WTS + ORPHAN_BR))
+```
+
+If `$MODE` is `yolo`, skip this step and pick the most relevant target
+automatically (priority: `worktrees` if ORPHANS>0, else `work` if dirty
+branch, else `plans` if PLANS>0 and SUMMARIES<PLANS, else `milestone` if
+SUMMARIES>0, else `code`).
+
+Otherwise call AskUserQuestion:
+
+```
+Question:
+What do you want to audit?
+
+Options:
+  1. plans           — planning integrity: completeness, status, deps ({PLANS} sprints)
+  2. phase           — verify a single phase against its PLAN          ({PLANS} plans)
+  3. milestone       — cross-phase milestone goal coverage             ({SUMMARIES} summaries)
+  4. uat             — outstanding UAT / verification items            ({UAT_FILES} files)
+  5. code-quality    — Karpathy 4-principle code review                (current diff)
+  6. auto-fix        — audit then auto-fix findings                    (uses #1–5 output)
+  7. work            — verify current branch / WIP                     ({ON_BRANCH}, dirty={DIRTY})
+  8. lens            — 15-lens methodology audit                       (security, perf, tests…)
+  9. worktrees       — orphaned executor worktrees/branches            ({ORPHANS} found)
+  0. cancel
+```
+
+Set `$TARGET` from the user's choice.
+
+## Step 4 — Pre-flight per target
+
+Each target has a precondition. Fail loudly with the fix step *before*
+dispatching, so the user doesn't get a surprise halt deep inside the
+sub-workflow.
+
+| target | precondition | failure message |
+|---|---|---|
+| plans | `.planning/ROADMAP.md` exists | `No ROADMAP.md. Run /rcode-new-milestone first.` |
+| phase | at least one `.planning/phases/*/PLAN.md` or `*-SPRINT.md` | `No plan file found. Run /rcode-plan first.` |
+| milestone | ROADMAP.md exists | `No ROADMAP.md. Run /rcode-new-milestone first.` |
+| uat | at least one UAT*.md exists | `No UAT files yet. Run /rcode-execute on a phase first.` |
+| code | git repo with at least one commit | `Empty repo — nothing to audit yet.` |
+| fix | a prior audit report exists OR a prior `--report` artefact | `No audit findings yet. Run /rcode-audit first.` |
+| work | inside a git worktree | `Not in a git repo.` |
+| lens | `rcode/` or `.rcode/` directory exists | `No rcode source found. Run: npx @hanzlaa/rcode install .` |
+| worktrees | git repo exists | `Not in a git repo.` |
+
+For `milestone` specifically, check the **graceful-degrade** condition
+(closes #234 audit-milestone halt):
+
+```bash
+if [ "$TARGET" = "milestone" ] && [ "$SUMMARIES" -eq 0 ] && [ "$PLANS" -gt 0 ]; then
+  # Phases planned but no formal closes — offer to synthesize.
+  GIT_FEAT_COMMITS=$(git log --oneline --grep='^feat' 2>/dev/null | wc -l)
+  echo "⚠ $PLANS phases planned, 0 SUMMARY.md, $GIT_FEAT_COMMITS feat commits."
+  echo "  Phases were executed but never formally closed."
+  # Offer (yolo: auto-pick 1; guided: ask):
+  #   1. Synthesize SUMMARY.md per phase from SPRINT.md + git log    [recommended]
+  #   2. Run /rcode-verify-phase per phase (manual close)
+  #   3. Continue audit anyway (will only assess what's documented)
+  #   0. Cancel
+fi
+```
+
+In `mode: yolo`, auto-pick option 1: group `git log --oneline` output by
+phase tag (e.g. commits matching `^feat\(0?(\d+)`) and write a first-pass
+`SUMMARY.md` per phase under `.planning/phases/<phase>/SUMMARY.md`
+containing the goal (from SPRINT.md), the commit list, and a `# TODO:
+expand outcomes` marker. The user can then refine before re-running the
+audit.
+
+A native `phase synthesize-summaries` CLI subcommand is tracked separately
+(see #234 follow-ups) — until it lands, the LLM performs the synthesis
+inline using `git log` + `Read SPRINT.md` + `Write SUMMARY.md`.
+
+## Step 5 — Dispatch
+
+Run the target's slash command, forwarding remaining args:
+
+| target | dispatch |
+|---|---|
+| plans | execute `@.rcode/workflows/audit-plans.md` inline |
+| phase | `/rcode-verify-phase $REST_ARGS` |
+| milestone | `/rcode-audit-milestone $REST_ARGS` |
+| uat | `/rcode-audit-uat $REST_ARGS` |
+| code | `/rcode-review $REST_ARGS --karpathy` |
+| lens | `/rcode-lens-audit $REST_ARGS` |
+| fix | `/rcode-audit-fix $REST_ARGS` |
+| work | `/rcode-verify-work $REST_ARGS` |
+| worktrees | execute `@.rcode/workflows/audit-worktrees.md` inline |
+
+## Step 6 — Closing summary
+
+After the sub-workflow returns:
+
+```
+rcode ► AUDIT ({TARGET}) ✓
+
+Report: {report_path or "(stdout only)"}
+Findings: {count}
+
+Next:
+  /rcode-audit fix         — auto-fix findings classified as auto-fixable
+  /rcode-audit code        — drill into code-quality issues
+  /rcode-audit lens        — 15-lens methodology audit
+  /rcode-settings show     — review which audit gates are enabled
+```
+
+## Success Criteria
+
+- [ ] `/rcode-audit` (no args) presents menu in guided mode, auto-picks in yolo
+- [ ] `/rcode-audit milestone` short-circuits the menu
+- [ ] `/rcode-audit lens` dispatches to `/rcode-lens-audit` interactive picker
+- [ ] `/rcode-audit lens security` passes `security` directly to `/rcode-lens-audit`
+- [ ] When SUMMARY.md absent but SPRINT.md present, milestone offers synthesize/verify/skip — does not dead-halt
+- [ ] Sub-workflow's closing report is surfaced unchanged
+
+## On Error
+
+- **Sub-workflow not installed** (slash file missing): `Audit subroute '/rcode-{target}' not found. Run: npx @hanzlaa/rcode install .`
+- **Precondition failed**: print the message from Step 4's table, suggest the unblocking command, STOP.
+- **`.rcode/config.yaml` missing**: treat as `mode: guided`, continue.
+
+## Next Up
+
+- `/rcode-audit-fix` — auto-fix findings surfaced by the audit
+- `/rcode-verify-phase` — verify phase goal after fixes are applied