@hanzlaa/rcode 3.6.3 → 3.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.6.3",
+  "version": "3.6.5",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rihal/commands/audit.md

@@ -1,7 +1,7 @@
 ---
 name: rihal-audit
-description: Single audit entry point — asks what to audit (phase, milestone, UAT, code, fix, work, lens) and dispatches to the right subroute. Honours .rihal/config.yaml mode.
-argument-hint: "[phase | milestone | uat | code | fix | work | lens [<1-15> | all]] [...subroute args]"
+description: Single audit entry point — asks what to audit (plans, phase, milestone, UAT, code, fix, work, lens) and dispatches to the right subroute. Honours .rihal/config.yaml mode.
+argument-hint: "[plans | phase | milestone | uat | code | fix | work | lens [<1-15> | all]] [--report] [...subroute args]"
 allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 

package/rihal/skills/actions/4-implementation/rihal-debug/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: rihal-debug
-internal: true
-description: Root-cause debugging via the scientific method.
+description: Root-cause debugging via the scientific method. Enforces investigate-before-fix, structured hypothesis iteration, multi-component evidence gathering, and architectural escalation after 3 failed fixes.
 triggers:
   # English
   - "debug this"
@@ -12,11 +11,15 @@ triggers:
   - "track this down"
   - "narrow down the bug"
   - "scientific method"
+  - "bug fix"
+  - "something is broken"
   # Roman Urdu / Hindi
   - "kharab kyu hai"
   - "bug dhoondo"
   - "fix karo bug"
   - "theek karo"
+  - "kya masla hai"
+  - "kyu kaam nahi kar raha"
   # Arabic native
   - "صحّح هذا"
   - "ما المشكلة"
@@ -29,29 +32,136 @@ user-invocable: false
 @.rihal/references/karpathy-guidelines.md
 
 
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+```
+
+If you have not completed Phase 1, you cannot propose a fix. "It seems to work" is a red flag — keep investigating until the mechanism is clear. Symptom fixes are failure.
+
 ## Overview
 
-Debugging is investigation, not pattern-matching. Each iteration narrows the problem space — never widens it. The skill enforces a written hypothesis, an experiment that distinguishes "yes" from "no", and a captured observation. Random fixes that "happen to work" are not allowed — the bug must be understood.
+Debugging is investigation, not pattern-matching. Each iteration narrows the problem space — never widens it. The skill enforces a written hypothesis, an experiment that distinguishes "yes" from "no", and a captured observation. Random fixes are not allowed — the bug must be understood before the fix is written.
+
+## Phase 1 — Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Reproduce consistently.** Write the exact steps. If not reproducible, make it reproducible first — anything else is guessing.
+
+2. **Read the error carefully.** Don't skim stack traces. Note file paths, line numbers, error codes. They often contain the exact answer.
+
+3. **Check recent changes.** `git diff`, recent commits, new dependencies, config changes, environment differences.
+
+4. **Gather evidence in multi-component systems.**
+
+   When the system has multiple layers (API → service → DB, CI → build → signing, frontend → backend → queue):
+
+   Add diagnostic instrumentation at EACH component boundary BEFORE proposing fixes:
+   ```
+   For EACH boundary:
+     - Log what data enters the component
+     - Log what data exits the component
+     - Verify env/config propagation
+     - Check state at each layer
+
+   Run ONCE to gather evidence showing WHERE it breaks.
+   THEN identify the failing component.
+   THEN investigate that specific component.
+   ```
+
+   Example:
+   ```bash
+   # Layer 1: incoming request
+   console.log('[L1] body:', req.body, 'userId:', req.user?.id)
+
+   # Layer 2: service call
+   console.log('[L2] args to createTask:', args)
+
+   # Layer 3: DB query
+   console.log('[L3] Prisma input:', data)
+   ```
+
+   This reveals which layer fails — not guessing.
 
-## Workflow
+5. **Trace data flow backward.** Where does the bad value originate? What called this function with that bad value? Keep tracing up until you find the source. Fix at source, not at symptom.
 
-1. **Reproduce the bug.** Write the exact steps. If you can't reproduce it, the first job is making it reproducible — anything else is guessing.
-2. **State the hypothesis.** "I think the bug is in <component>; specifically <mechanism>." One sentence, falsifiable.
-3. **Design the experiment.** What single test, log line, or dataflow change would distinguish a true hypothesis from a false one?
-4. **Run it. Capture the observation.** Console output verbatim, screenshot, stack trace, network response — whatever the experiment produced.
-5. **Update the hypothesis.** Either confirmed (now narrow to the next layer) or refuted (form a new hypothesis based on what was observed).
-6. **Stop conditions:** the bug is reproducible from a unit test (then hand to `rihal-prove-it`), OR the root cause is a known external constraint (e.g. third-party API behaviour) that you record in `incidents/known-issues.md`.
-7. **Never apply a fix without understanding why it works.** "It seems to fix it" is a red flag — keep investigating until the mechanism is clear.
+## Phase 2 — Pattern Analysis
 
-## Sentry / observability integration
+Before forming a hypothesis, find the comparison point:
+
+1. **Find working examples.** Locate similar code in the same codebase that works. What's different?
+2. **Read reference implementations completely.** Don't skim — partial understanding guarantees bugs.
+3. **List every difference**, however small. Don't assume "that can't matter."
+4. **Check assumptions.** What config, environment, or state does this code assume?
+
+## Phase 3 — Hypothesis and Experiment
+
+Scientific method:
+
+1. **State ONE hypothesis.** "I think X is the root cause because Y." Write it down. Be specific, not vague.
+2. **Design the minimal experiment.** What single test, log line, or code change would confirm or refute this hypothesis?
+3. **Run it. Capture the observation verbatim.** Console output, stack trace, network response — whatever was produced.
+4. **Update.** Confirmed → Phase 4. Refuted → form a new hypothesis based on what was observed. Do NOT add more fixes on top.
+
+## Phase 4 — Implementation
+
+1. **Create a failing test first.** Simplest possible reproduction. Use `rihal-prove-it` for writing the test that locks the fix in.
+2. **Implement ONE fix.** Address the root cause identified. No "while I'm here" improvements. No bundled refactors.
+3. **Verify.** Test passes. No other tests broken. Issue actually resolved.
+4. **If fix doesn't work:** STOP. Count fix attempts.
+   - < 3 attempts: return to Phase 1 with new information.
+   - **≥ 3 attempts: STOP — this is an architectural problem.**
+
+## Architectural Escalation (after 3 failed fixes)
+
+Pattern that signals architectural problem:
+- Each fix reveals new coupling or shared state in a different place
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+When this pattern appears:
+1. Stop attempting fixes
+2. Ask: is this pattern fundamentally sound, or are we continuing through inertia?
+3. Discuss with the user before attempting more fixes
+4. Consider `/rihal-council` for a cross-functional review
+
+## Sentry / Observability Integration
 
 If the project has Sentry (`@sentry/*` in `package.json` or `sentry-sdk` in Python):
 
-- Quote the actual Sentry issue ID and stack trace in the hypothesis section
-- Look at breadcrumbs for the chain of events leading to the error
-- Check the issue's "first seen / last seen" — recurring or one-off matters
+- Quote the actual Sentry issue ID and stack trace in the hypothesis
+- Read breadcrumbs for the chain of events leading to the error
+- Check "first seen / last seen" — recurring or one-off matters
 - Cross-reference with deployment timestamps to identify regressions
 
+## Red Flags — STOP and return to Phase 1
+
+If you catch yourself thinking any of these:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes and run tests"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "It seems to fix it"
+- "One more fix attempt" (when already tried 2+)
+- Proposing solutions before tracing data flow
+- Each fix reveals a new problem in a different place
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple bugs have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+) | 3+ failures = architectural problem. Escalate, don't fix again. |
+
 ## Output Format
 
 ```
@@ -59,9 +169,12 @@ Reproduction:
   <exact steps>
   <observed vs expected>
 
+Phase 1 — Evidence
+  <what layers were instrumented and what they showed>
+
 Iteration 1
-  Hypothesis: <falsifiable claim>
-  Experiment: <what we did>
+  Hypothesis: <falsifiable claim — "I think X because Y">
+  Experiment: <the single test/log that would confirm or refute>
   Observation: <verbatim output>
   Outcome: confirmed | refuted | partial
 
@@ -69,26 +182,30 @@ Iteration N
   ...
 
 Root cause:
-  <one paragraph explanation of the actual mechanism>
+  <one paragraph — the actual mechanism, not the symptom>
 
 Fix scope:
-  <minimum change that fixes the cause, not the symptom>
+  <minimum change that addresses the cause>
 
 Regression test:
-  <hand off to rihal-prove-it for the test that locks the fix in>
+  <hand to rihal-prove-it — the test that locks the fix in>
 ```
 
-Do NOT include: "tried X and it seems to work"; speculative "maybe it's caching"; broad refactors disguised as bug fixes.
+Do NOT include: "tried X and it seems to work" · speculative "maybe it's caching" · broad refactors disguised as bug fixes.
 
 ## Examples
 
-**Happy path** — "Login fails for Arabic usernames" → reproduce: POST `/login` with `محمد` returns 500 → hypothesis: encoding boundary in URL parsing → experiment: add hex-dump log of the raw request → observation: bytes are UTF-8 but the Postgres driver re-encodes as Latin-1 → root cause: client_encoding mismatch → fix: pin client_encoding=utf8 → regression test asserts non-ASCII login returns 200.
+**Happy path** — "Login fails for Arabic usernames" → reproduce: POST `/login` with `محمد` returns 500 → Phase 1: hex-dump log of raw request body → observation: UTF-8 bytes, but Postgres driver re-encodes as Latin-1 → root cause: `client_encoding` mismatch → fix: pin `client_encoding=utf8` in connection string → regression test asserts non-ASCII login returns 200.
+
+**Multi-component** — "Tasks not appearing after creation" → instrument three layers: controller logs input, service logs DB call args, DB query logs row count → observation: service receives correct args, DB returns `rowCount: 0` → hypothesis: wrong table name in query → confirmed → one-line fix, regression test added.
+
+**Edge case — flaky test** — Passes locally, fails in CI 30% of the time → hypothesis: race condition → experiment: `--runInBand` → still flaky → next hypothesis: filesystem timing → experiment: `await fs.stat` after write → confirmed → fix.
 
-**Edge case — flaky test** — Test passes locally, fails in CI 30% of the time → hypothesis: race condition → experiment: run with `--runInBand` → observation: still flaky → next hypothesis: filesystem timing → experiment: await fs.stat after write → confirmed → fix.
+**Negative — shotgun fix** — "I added a try/catch around the whole function and now it doesn't crash." Refuse. The exception is silently swallowed; the bug still exists. Restore the throw and form a real hypothesis.
 
-**Negative — shotgun fix** — "I added a try/catch around the whole function and now it doesn't crash". Refuse. The exception is now silently swallowed; the bug still exists. Restore the throw and form a real hypothesis.
+**Architectural escalation** — Three separate fixes attempted (missing await, wrong env var, stale cache) — each fix exposed a new problem elsewhere. Stop. The async data-flow design is wrong. Escalate to `/rihal-council` before attempting Fix #4.
 
 ## Memory Bank Hooks
 
-- **Reads:** `.rihal/memory/incidents/known-issues.md` (so prior debugging context is loaded), `.rihal/memory/project/stack.md` (Sentry presence)
-- **Writes:** append the root cause to `.rihal/memory/incidents/post-mortems/YYYYMMDD-<slug>.md` when an incident is resolved; remove the entry from `known-issues.md` once the fix is verified in production
+- **Reads:** `.rihal/memory/incidents/known-issues.md` (prior debugging context), `.rihal/memory/project/stack.md` (Sentry presence, observability tools)
+- **Writes:** append root cause to `.rihal/memory/incidents/post-mortems/YYYYMMDD-<slug>.md` when resolved; remove from `known-issues.md` once fix is verified in production

package/rihal/workflows/audit-plans.md

@@ -0,0 +1,255 @@
+# Workflow: rihal-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 /rihal-* command to run next
+
+Unlike /rihal-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`:
+
+```
+/rihal-audit plans [--report] [--strict]
+```
+
+**Examples:**
+```
+/rihal-audit plans
+/rihal-audit plans --report
+/rihal-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 /rihal-new-milestone to start a milestone.
+```
+STOP.
+
+If `$ROADMAP` does not exist:
+```
+⚠ No ROADMAP.md found at $ROADMAP.
+  Run /rihal-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 /rihal-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 /rihal-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 /rihal-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 /rihal-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 /rihal-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:
+
+```
+RIHAL ► 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) | `/rihal-plan` — fix dependency before executing |
+| Any ERROR from Check A4 (ROADMAP phase missing) | `/rihal-add-phase {id}` — create the missing phase |
+| Any WARN from B1 (current_phase completed) | `/rihal-next` — advance to the next phase |
+| Any WARN from B2 (sprint all-done not closed) | `/rihal-verify-phase` — close the current sprint |
+| Any WARN from A1 (phase with no sprint) | `/rihal-plan` — create sprint plan for the earliest unplanned phase |
+| Any WARN from A2 (sprint no tasks) | `/rihal-sprint-planning {sprint_id}` — groom the empty sprint |
+| Any WARN from A3 (missing must_haves) | `/rihal-create-story` — add acceptance criteria |
+| Any WARN from C2 (unknown requirement) | edit `REQUIREMENTS.md` — define the missing requirement |
+| No findings | `/rihal-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 `/rihal-new-milestone`
+- ROADMAP.md missing → prompt to run `/rihal-new-milestone`
+- No sprint files found → report as WARNING and recommend `/rihal-plan`
+- REQUIREMENTS.md missing → skip C2 check silently (not all projects use it)

package/rihal/workflows/audit.md

@@ -18,6 +18,7 @@ If `$ARGUMENTS` contains `--help` or `-h`:
 
 ```
 /rihal-audit                           # interactive — asks what to audit
+/rihal-audit plans [--report]         # → audit-plans (structural + status + deps check)
 /rihal-audit phase [<NN>]              # → /rihal-verify-phase
 /rihal-audit milestone [--strict]      # → /rihal-audit-milestone (with synth fallback)
 /rihal-audit uat                       # → /rihal-audit-uat
@@ -30,6 +31,8 @@ If `$ARGUMENTS` contains `--help` or `-h`:
 **Examples:**
 ```
 /rihal-audit
+/rihal-audit plans
+/rihal-audit plans --report
 /rihal-audit milestone --strict
 /rihal-audit phase 03
 /rihal-audit lens security
@@ -45,7 +48,7 @@ DISCUSS=$($TOOL config-get workflow.discuss_mode 2>/dev/null || echo "adaptive")
 ```
 
 Parse `$ARGUMENTS`:
-- First word ∈ {phase, milestone, uat, code, fix, work, lens} → set `$TARGET`, drop it from args, jump to Step 4.
+- First word ∈ {plans, phase, milestone, uat, code, fix, work, lens} → set `$TARGET`, drop it from args, jump to Step 4.
 - Empty or unrecognised → continue to Step 2.
 
 ## Step 2 — Detect project state
@@ -68,7 +71,7 @@ as `(no data — skip)`.
 ## Step 3 — Ask user (guided mode only)
 
 If `$MODE` is `yolo`, skip this step and pick the most relevant target
-automatically (priority: `work` if dirty branch, else `phase` if PLANS>0
+automatically (priority: `work` if dirty branch, else `plans` if PLANS>0
 and SUMMARIES<PLANS, else `milestone` if SUMMARIES>0, else `code`).
 
 Otherwise call AskUserQuestion:
@@ -78,13 +81,14 @@ Question:
 What do you want to audit?
 
 Options:
-  1. phase           — verify a single phase against its PLAN  ({PLANS} plans)
-  2. milestone       — cross-phase milestone goal coverage     ({SUMMARIES} summaries)
-  3. uat             — outstanding UAT / verification items    ({UAT_FILES} files)
-  4. code-quality    — Karpathy 4-principle code review        (current diff)
-  5. auto-fix        — audit then auto-fix findings            (uses #1–4 output)
-  6. work            — verify current branch / WIP             ({ON_BRANCH}, dirty={DIRTY})
-  7. lens            — 15-lens methodology audit               (security, perf, tests…)
+  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…)
   0. cancel
 ```
 
@@ -98,6 +102,7 @@ sub-workflow.
 
 | target | precondition | failure message |
 |---|---|---|
+| plans | `.planning/ROADMAP.md` exists | `No ROADMAP.md. Run /rihal-new-milestone first.` |
 | phase | at least one `.planning/phases/*/PLAN.md` or `*-SPRINT.md` | `No plan file found. Run /rihal-plan first.` |
 | milestone | ROADMAP.md exists | `No ROADMAP.md. Run /rihal-new-milestone first.` |
 | uat | at least one UAT*.md exists | `No UAT files yet. Run /rihal-execute on a phase first.` |
@@ -140,6 +145,7 @@ Run the target's slash command, forwarding remaining args:
 
 | target | dispatch |
 |---|---|
+| plans | execute `@.rihal/workflows/audit-plans.md` inline |
 | phase | `/rihal-verify-phase $REST_ARGS` |
 | milestone | `/rihal-audit-milestone $REST_ARGS` |
 | uat | `/rihal-audit-uat $REST_ARGS` |