@hanzlaa/rcode 2.1.0 → 2.3.1

package/rihal/references/karpathy-guidelines-full.md

@@ -0,0 +1,79 @@
+# Karpathy Coding Guidelines
+
+Behavioral guidelines derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Every rihal agent that writes, reviews, or refactors code must internalize these four principles.
+
+**Tradeoff:** These bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+**Rihal application:** In Round 1 of council/chain, every agent's response must include an `## Assumptions` block listing load-bearing assumptions. rihal-planner must ask via AskUserQuestion before writing a plan when scope is ambiguous. rihal-executor must stop on Rule 4 deviations and return a checkpoint, not silently guess.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Test: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+**Rihal application:** rihal-planner tasks must be single-purpose. rihal-executor must not add abstractions during task execution (deviation Rule 2 applies only to missing critical functionality, not speculative flexibility). rihal-code-review explicitly flags overengineering.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+**Rihal application:** rihal-executor commits must only include files its tasks touched. The deviation scope boundary (out-of-scope warnings logged to deferred-items.md, not fixed) enforces this. rihal-code-review-fix must not change style in files it's auditing.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+**Rihal application:** Every task in a SPRINT.md must have a "Done when:" clause that's externally verifiable. rihal-executor self-check loop verifies Done-when conditions were met. rihal-sprint-checker rejects plans where tasks have vague success criteria.
+
+## Enforcement
+
+Agents that write or modify code (rihal-executor, rihal-planner, rihal-tech-writer, rihal-codebase-mapper when producing code docs) must:
+1. @-include this file
+2. Apply the 4 principles as hard constraints, not suggestions
+3. Reference the specific principle when refusing to make a change (e.g., "Declining per Karpathy #3: that's adjacent to the requested change but not part of it")
+
+## Credit
+
+Original principles by Andrej Karpathy. Reference implementation by Forrest Chang at github.com/forrestchang/andrej-karpathy-skills. Adapted and extended for rihal's multi-agent architecture.

package/rihal/references/karpathy-guidelines.md

@@ -1,79 +1,11 @@
-# Karpathy Coding Guidelines
+# Karpathy Guidelines — Quick Reference
 
-Behavioral guidelines derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Every rihal agent that writes, reviews, or refactors code must internalize these four principles.
+Four hard constraints for every agent that writes, reviews, or modifies code or artifacts.
+Full text with Rihal-specific application notes: `@.rihal/references/karpathy-guidelines-full.md`
 
-**Tradeoff:** These bias toward caution over speed. For trivial tasks, use judgment.
+1. **Think first (P1)** — State assumptions explicitly before acting. If scope is ambiguous, ask. Never guess silently.
+2. **Simplicity (P2)** — Minimum code/scope that solves the problem. No speculative features, abstractions, or error handling for impossible cases.
+3. **Surgical (P3)** — Touch only what the task requires. Don't improve adjacent code, don't refactor what isn't broken.
+4. **Goal-driven (P4)** — Define a verifiable success criterion before starting. "Done when: X can be verified externally."
 
-## 1. Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-**Rihal application:** In Round 1 of council/chain, every agent's response must include an `## Assumptions` block listing load-bearing assumptions. rihal-planner must ask via AskUserQuestion before writing a plan when scope is ambiguous. rihal-executor must stop on Rule 4 deviations and return a checkpoint, not silently guess.
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Test: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-**Rihal application:** rihal-planner tasks must be single-purpose. rihal-executor must not add abstractions during task execution (deviation Rule 2 applies only to missing critical functionality, not speculative flexibility). rihal-code-review explicitly flags overengineering.
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it — don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-**Rihal application:** rihal-executor commits must only include files its tasks touched. The deviation scope boundary (out-of-scope warnings logged to deferred-items.md, not fixed) enforces this. rihal-code-review-fix must not change style in files it's auditing.
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-**Rihal application:** Every task in a SPRINT.md must have a "Done when:" clause that's externally verifiable. rihal-executor self-check loop verifies Done-when conditions were met. rihal-sprint-checker rejects plans where tasks have vague success criteria.
-
-## Enforcement
-
-Agents that write or modify code (rihal-executor, rihal-planner, rihal-tech-writer, rihal-codebase-mapper when producing code docs) must:
-1. @-include this file
-2. Apply the 4 principles as hard constraints, not suggestions
-3. Reference the specific principle when refusing to make a change (e.g., "Declining per Karpathy #3: that's adjacent to the requested change but not part of it")
-
-## Credit
-
-Original principles by Andrej Karpathy. Reference implementation by Forrest Chang at github.com/forrestchang/andrej-karpathy-skills. Adapted and extended for rihal's multi-agent architecture.
+When refusing a change, cite the principle: `"Declining per Karpathy P3 — that's adjacent to the requested change."`

package/rihal/references/model-profile-resolution.md

@@ -0,0 +1,8 @@
+# Model Profile Resolution
+
+Workflows pick a model via `node .rihal/bin/rihal-tools.cjs resolve-model
+<role>`, which reads `.rihal/config.yaml` `model_profile` and returns the
+concrete model id for that role per `rihal/config/model-profiles.json`.
+
+If `model_profile` is unset, default is `balanced`. Unknown profile falls
+back to `balanced` with a stderr warning.

package/rihal/references/phase-argument-parsing.md

@@ -0,0 +1,11 @@
+# Phase Argument Parsing
+
+Workflows accept a phase argument in two forms:
+
+- **Numeric**: `01`, `2`, `02.1` — resolved via
+  `node .rihal/bin/rihal-tools.cjs init phase-op "$ARG"` to the matching
+  phase directory under `.planning/phases/`.
+- **Path**: a direct `.planning/phases/<slug>/PLAN.md` path — used as-is.
+
+If the resolver returns `phase_found: false`, workflows must STOP with a
+"phase not found" message rather than fabricating a target.

package/rihal/references/revision-loop.md

@@ -0,0 +1,11 @@
+# Plan Revision Loop
+
+When `workflow.plan_checker` is enabled (`/rihal:settings`), `/rihal:plan`
+runs the rihal-plan-checker after the planner. Findings drive a bounded
+revision loop:
+
+1. Planner produces PLAN.md.
+2. Plan-checker scores against goal-backward criteria.
+3. If BLOCK / FLAG: planner revises with the findings as added input.
+4. Up to 2 revision rounds. After that, surface to user for manual
+   confirmation rather than loop indefinitely.

package/rihal/references/universal-anti-patterns.md

@@ -0,0 +1,15 @@
+# Universal Anti-Patterns (Discuss-Phase)
+
+Common failure modes the discuss workflow checks for:
+
+- **Solution-first framing**: jumping to implementation before constraints
+  are explicit.
+- **Hidden binary choice**: presenting a "decision" that has only one
+  viable option.
+- **Unowned action**: a "we should X" with no owner or deadline.
+- **Sunk-cost continuation**: defending an existing plan instead of
+  evaluating fresh evidence.
+- **Scope inflation**: bundling new work into the current decision.
+
+Discuss-phase flags any of these and asks for explicit framing before
+proceeding.

package/rihal/skills/actions/1-analysis/rihal-prfaq/SKILL.md

@@ -3,6 +3,16 @@ name: rihal-prfaq
 description: Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
 ---
 
+## Do NOT use this skill for
+
+- **Refining an existing PRD** — use `rihal-create-prd` or `rihal-edit-prd`.
+- **Brainstorming raw ideas** before there's a concept — use `rihal-brainstorming` first; PRFAQ assumes a candidate concept exists.
+- **Sprint or phase planning** — use `rihal-sprint-planning` / `rihal-create-milestone`.
+- **Pure market research with no product hypothesis** — use a research workflow.
+- **Single-question Q&A** — PRFAQ runs a multi-stage gauntlet; for a one-off answer, just answer.
+
+If the user asks to "validate" or "polish" an existing PRD, redirect to `rihal-validate-prd`.
+
 ## Workflow
 
 

package/rihal/skills/actions/2-plan/rihal-create-epics-and-stories/SKILL.md

@@ -15,9 +15,11 @@ Follow the instructions in ./workflow.md.
 ## Output Format
 
 - Produces .rihal/phases/{phase}/epics.md with hierarchical structure
-- Each epic has: Title | Goal | Stories (list) | Priority | Estimate
+- Each epic has: Title | Goal | Assumptions | Stories (list) | Priority | Estimate
 - Each story is independently testable and under 4-hour estimate
 - Do NOT create epics larger than 10 stories — split further
+- Every epic must include an `Assumptions` line — at minimum one entry; "none" is not acceptable
+- Every story must have a one-line verifiable AC before being listed — vague stories get flagged and blocked
 
 ## Examples
 

package/rihal/skills/actions/2-plan/rihal-create-milestone/SKILL.md

@@ -15,10 +15,12 @@ Follow the instructions in ./workflow.md.
 ## Output Format
 
 - Output: ROADMAP.md in `{planning_artifacts}/`
-- Structure: per milestone — Name, Window (dates), Goal (one sentence), Acceptance criteria, Kill criteria (binary), Phases (stub list), then a trailing Backlog / parking lot section
+- Structure: per milestone — Name, Window (dates), Goal (one sentence), Assumptions, Acceptance criteria, Kill criteria (binary), Phases (stub list), then a trailing Backlog / parking lot section
 - Each kill criterion must be binary (number + threshold), not adjectival
 - Every milestone has an explicit window with start + end dates
+- Every milestone must include an `Assumptions` block — decisions that, if wrong, invalidate this milestone's scope
 - Do NOT include: unquantified success language ("grow the user base"), open-ended milestones without dates, or more than 6 active milestones in one roadmap (split into v1/v2 if needed)
+- If a milestone goal cannot be expressed as a single verifiable sentence, split it into two milestones
 
 ## Examples
 

package/rihal/skills/actions/2-plan/rihal-create-milestone/steps/step-10-complete.md

@@ -33,7 +33,7 @@ Hard deadline:  {deadline or "none specified"}
 [{completedAt}]
 ```
 
-### 3. Next-step menu (intent-based, mirrors the GSD /progress Route A/B/C pattern)
+### 3. Next-step menu (intent-based Route A/B/C pattern)
 
 ```
 What's next?

package/rihal/skills/actions/2-plan/rihal-create-prd/SKILL.md

@@ -21,6 +21,19 @@ Follow the instructions in ./workflow.md.
 - Every section has explicit owner and deadline
 - Do NOT include: vague verbs ("optimize"), unquantified metrics, or requirements without owners
 
+## Fast-path detection
+
+If `$ARGUMENTS` or the opening message contains ALL FOUR of these fields, skip the discovery interview and go straight to drafting:
+
+| Field | Signal words |
+|-------|-------------|
+| Product / feature name | explicit name or noun |
+| Problem statement | "problem is", "users can't", "currently X fails" |
+| Target user | "for X users", "persona is", "audience is" |
+| Scope signal | "must have", "v1 only", "just need", "MVP" |
+
+When fast-pathing: confirm detected fields in one line ("Got it — building {name} for {user} to solve {problem}. Starting PRD draft."), then generate without asking further questions. If any of the four are absent, run the normal interview.
+
 ## Examples
 
 ### Happy Path

package/rihal/skills/actions/2-plan/rihal-create-story/SKILL.md

@@ -15,10 +15,12 @@ Follow the instructions in ./workflow.md.
 ## Output Format
 
 - Story file at .rihal/phases/{phase}/stories/story-{id}.md
-- Fixed sections: Goal | Context | Tasks (checklist) | Acceptance Criteria | Dependencies | File List (empty) | Dev Agent Record (empty)
+- Fixed sections: Goal | Assumptions | Context | Tasks (checklist) | Acceptance Criteria | Dependencies | File List (empty) | Dev Agent Record (empty)
 - Each task is ≤4 hours, in execution order
-- Acceptance criteria in Given/When/Then
+- Acceptance criteria in Given/When/Then — no criterion is valid unless a test can be written against it
+- `## Assumptions` block is mandatory: list every assumption that, if wrong, would change the story scope
 - Do NOT include implementation details in the story — those emerge during dev
+- If AC cannot be stated in Given/When/Then, stop and ask the user to clarify before generating the story
 
 ## Examples
 

package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/SKILL.md

@@ -3,6 +3,16 @@ name: rihal-checkpoint-preview
 description: 'LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change".'
 ---
 
+## Do NOT use this skill for
+
+- **Automated code review without a human** — use `/rihal:karpathy-audit` or a code-reviewer agent directly.
+- **Approving a deploy or merge** — this skill explains a change; it does not authorize git push, deploys, or PR merges.
+- **Bug investigation** from scratch — use `/rihal:debug` or the diagnose-issues workflow.
+- **Architecture review of an undelivered design** — this skill reviews delivered code/diffs, not specs.
+- **Sprint retros or milestone closure** — use `rihal-retrospective` or `rihal-complete-milestone`.
+
+If the user has not produced a diff or change to review, ask them to do so first instead of invoking this skill.
+
 ## Workflow
 
 

package/rihal/skills/actions/4-implementation/rihal-sprint-planning/SKILL.md

@@ -15,10 +15,12 @@ Follow the instructions in ./workflow.md.
 ## Output Format
 
 - Output: .rihal/phases/{phase}/sprint-{N}.md
-- Fixed structure: Sprint Goal (one sentence) | Duration | Stories (with owners) | Capacity Used/Available | Risks | Definition of Done
+- Fixed structure: Sprint Goal (one sentence) | Assumptions | Duration | Stories (with owners) | Capacity Used/Available | Risks | Definition of Done
 - Stories ranked by priority from epics.md
 - Leave 20% capacity buffer
 - Do NOT commit to stories without explicit owners
+- Sprint Goal must be one verifiable sentence — if it cannot be verified at sprint end without interpretation, rewrite it
+- `Assumptions` block required: list capacity assumptions, any known blockers assumed absent, any dependencies assumed resolved
 
 ## Examples
 

package/rihal/skills/agents/hussain-pm/SKILL.md

@@ -16,6 +16,14 @@ description: >
 
 # Hussain (PM) — Product Manager
 
+## Planning Quality Rules (Karpathy-adapted)
+
+Apply these as hard constraints when writing any PRD, story, epic, or scope definition:
+
+- **P1 — Think first:** Every PRD section must declare load-bearing assumptions explicitly before stating requirements. If scope is ambiguous, ask — do not guess silently.
+- **P2 — Simplicity:** Scope only what was asked. No speculative features, no "nice to have" requirements that weren't requested by the user or stakeholder.
+- **P4 — Goal-driven:** Every requirement must have a testable acceptance criterion. "System should handle X" is not a criterion — "Given Y, when Z, then the system returns W" is.
+
 ## Overview
 
 This skill embodies Hussain (حسين) in his Product Manager hat. It drives PRD creation through user interviews and requirements discovery, cuts scope ruthlessly, and ships the smallest thing that validates the assumption. Hussain does not fill templates — he interrogates until the problem is crystal clear.

package/rihal/skills/agents/hussain-sm/SKILL.md

@@ -15,6 +15,14 @@ description: >
 
 # Hussain (SM) — Scrum Master
 
+## Sprint Quality Rules (Karpathy-adapted)
+
+Apply these as hard constraints when preparing stories and planning sprints:
+
+- **P1 — Think first:** Before committing stories to a sprint, surface capacity assumptions explicitly. Never assume velocity or team availability — ask.
+- **P2 — Simplicity:** Each story must be independently deliverable. No story that bundles 2+ concerns. If a story needs a sub-story to make sense, split it.
+- **P4 — Goal-driven:** Every story must have a Definition of Done that can be verified without talking to anyone. "Works correctly" is not a DoD — "all AC pass + no regression in test suite" is.
+
 ## Overview
 
 This skill embodies Hussain (حسين) in his Scrum Master hat. It prepares stories with full context for the dev agent, plans sprints, runs retros, reports status, and course-corrects when things go sideways. Every story that reaches Hanzla is dev-ready — no ambiguity allowed.

package/rihal/templates/UAT.md

@@ -0,0 +1,29 @@
+# UAT — {{phase_name}}
+
+**Phase:** {{phase_id}}
+**Generated:** {{date}}
+
+## How to use
+
+For each scenario below, mark status: ✅ pass | ❌ fail | ⏸ skipped |
+🔍 needs-human. Add notes inline.
+
+## Scenarios
+
+### Scenario 1: {{golden path title}}
+
+**Steps:**
+1. {{action}}
+2. {{action}}
+
+**Expected:** {{outcome}}
+**Status:** ⏸
+**Notes:**
+
+### Scenario 2: {{edge case title}}
+
+(Repeat as needed.)
+
+## Outstanding items
+
+Items left as ⏸ or 🔍 carry forward to the next milestone audit.

package/rihal/templates/milestone.md

@@ -1,5 +1,7 @@
 # Milestone Template
 
+<!-- P2: Omit any section with nothing substantive. Empty sections are noise. Omit STATE.md blockers/workstreams if none active. Omit REQUIREMENTS.md out-of-scope if it doesn't constrain execution. -->
+
 Use this template when starting a new milestone with `/rihal:new-milestone`.
 
 ## ROADMAP.md

package/rihal/templates/sprint.md

@@ -1,70 +1,53 @@
 # Sprint {sprint_id} — {sprint_goal}
 
+<!-- P2: Omit Dependencies and Risks sections if empty. Omit Retrospective until sprint is complete. -->
+
 **Phase:** {phase_number} — {phase_name}
 **Status:** {status}
 **Velocity target:** {velocity_target} points
 **Started:** {started_at}
 
----
-
 ## Sprint Goal
 
 {sprint_goal}
 
----
-
 ## Stories
 
-| ID | Title | Points | Status | Acceptance |
-|----|-------|--------|--------|------------|
-| {story_id} | {title} | {points} | {status} | {acceptance} |
-
----
+| ID | Title | Points | Status | Done when |
+|----|-------|--------|--------|-----------|
+| {story_id} | {title} | {points} | {status} | {verifiable_ac} |
 
 ## Capacity
 
 - **Velocity target:** {velocity_target} points
-- **Average velocity (last 3):** {avg_velocity} points
 - **Total committed:** {total_points} points
 - **Buffer:** {buffer_points} points ({buffer_pct}%)
 
----
-
+<!-- Omit if no cross-story dependencies exist -->
 ## Dependencies
 
 | Story | Depends on | Status |
 |-------|-----------|--------|
-| | | |
-
----
 
+<!-- Omit if no risks identified -->
 ## Risks
 
 | Risk | Impact | Mitigation |
 |------|--------|------------|
-| | | |
 
----
-
-## Sprint Review Notes
-
-_Filled at sprint completion._
+## Sprint Review
 
+<!-- Fill at sprint completion only — omit this section until then -->
 - Stories completed: {done_count}/{total_count}
 - Velocity actual: {velocity_actual} points
-- Carryover stories: {carryover}
-
----
+- Carryover: {carryover}
 
 ## Retrospective
 
-_Filled at sprint completion._
-
+<!-- Fill at sprint completion only — omit this section until then -->
 ### What went well
 -
-
 ### What didn't
 -
-
 ### Action items
 -

package/rihal/templates/summary.md

@@ -0,0 +1,30 @@
+# Phase Summary — {{phase_name}}
+
+<!-- P2: Omit any section that has nothing substantive to say. An empty section is worse than no section. -->
+
+**Phase ID:** {{phase_id}}
+**Closed:** {{closed_at}}
+**Plan:** PLAN.md
+
+## Outcomes
+
+- {{what was built, in user-visible terms}}
+
+## Decisions Made
+
+<!-- Omit if no decisions were made that aren't already in PLAN.md -->
+- {{key choices and their rationale}}
+
+## Deviations from Plan
+
+<!-- Omit if execution matched the plan exactly -->
+- {{anything that diverged from PLAN.md and why}}
+
+## Issues Encountered
+
+<!-- Omit if no tasks were pruned, escalated, or skipped -->
+- {{tasks pruned, escalated, or skipped}}
+
+## Hand-off
+
+Next phase: {{next phase id and goal}}

package/rihal/templates/verification-report.md

@@ -0,0 +1,28 @@
+# Verification Report — {{phase_name}}
+
+**Phase:** {{phase_id}}
+**Verified:** {{date}}
+**Verifier:** rihal-verifier
+
+## Goal-backward check
+
+**Original goal:** {{phase goal from PLAN.md}}
+
+**Met?** ✅ / ◐ partial / ❌ not met
+
+**Evidence:**
+- {{file:line or test name proving the goal is met}}
+
+## Per-task verification
+
+| # | Task | Status | Evidence |
+|---|------|--------|----------|
+| 1 | {{task}} | ✅ | {{evidence}} |
+
+## Gaps
+
+- {{what wasn't delivered + why}}
+
+## Recommendation
+
+- proceed / revise / block

package/rihal/workflows/audit-milestone.md

@@ -140,13 +140,45 @@ If `--report` flag set, also print the report to stdout. Otherwise, just save to
 
 ## On Error
 
-If no SUMMARY.md files found:
+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 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)
 ```
-⚠ No phase summaries found. Have phases been executed?
+
+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 PLAN.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 /rihal: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 .rihal/bin/rihal-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: /rihal:plan
 ```
 
+STOP.
+
 If ROADMAP missing:
 
 ```