@hanzlaa/rcode 3.4.4 → 3.4.6

package/rihal/workflows/feature-drift.md

@@ -0,0 +1,243 @@
+# Workflow: rihal-feature-drift
+
+<purpose>
+Detect drift between PRD, epics, stories, and code. Report severity-tagged
+findings; optionally fix trivial items in-place via opt-in `--fix` flag.
+
+Closes the gap between feature-documentation layers that no other rihal tool
+spans (`docs-update` covers project docs, `correct-course` covers PRD-vs-code
+only, `memory-audit` reports but doesn't fix). Mirrors the writer+verifier
+loop pattern established by `docs-update`.
+</purpose>
+
+<required_reading>
+@.rihal/references/output-format.md
+</required_reading>
+
+<process>
+
+<step name="parse_args">
+Extract from $ARGUMENTS:
+- `--fix` flag — opt-in auto-fix for trivial items only (severity allowlist enforced in code)
+- `--quick` flag — fast-mode for hooks (Phase 8). Skips deep verifier loop, runs the auditor scan only. Target runtime <2s. **QUICK_MODE always implies report-only — never patches even if `--fix` is also passed.**
+- `--scope <phase|project>` — phase scope reads phase-local docs; project scope reads root docs
+- `--mode <feature|phase-status>` — drift dimension. `feature` (default) compares PRD↔epics↔stories↔code. `phase-status` (Phase 8 / #461) compares ROADMAP claim against shipping reality (SUMMARY.md presence, SPRINT.md presence, git log).
+- Optional positional phase number (only required when scope=phase)
+
+Default scope: project (root `.planning/PRD.md`, `.planning/epics/`, `.planning/stories/`). Default mode: feature.
+
+```bash
+FIX_MODE=false
+QUICK_MODE=false
+MODE="feature"
+
+if [[ "$ARGUMENTS" =~ (^|[[:space:]])--fix($|[[:space:]]) ]]; then
+  FIX_MODE=true
+fi
+if [[ "$ARGUMENTS" =~ (^|[[:space:]])--quick($|[[:space:]]) ]]; then
+  QUICK_MODE=true
+  # Safety: --quick forces report-only regardless of --fix.
+  # Hooks must never auto-modify files.
+  FIX_MODE=false
+fi
+if [[ "$ARGUMENTS" =~ --mode[[:space:]]+(feature|phase-status) ]]; then
+  MODE="${BASH_REMATCH[1]}"
+fi
+if [[ "$ARGUMENTS" =~ --mode=(feature|phase-status) ]]; then
+  MODE="${BASH_REMATCH[1]}"
+fi
+```
+</step>
+
+<step name="load_artifacts">
+Locate and read the layers that exist; track which layers are absent.
+
+For project scope:
+- PRD: `.planning/PRD.md` (or `.planning/REQUIREMENTS.md` as fallback)
+- Epics: `.planning/epics/*.md`
+- Stories: `.planning/stories/*.md`
+- Code surface: `src/`, `lib/`, `packages/`, `app/` (best-effort directory discovery)
+
+For phase scope (phase number passed):
+- PRD: `.planning/phases/{N}-*/PRD.md` (or per-phase REQUIREMENTS.md)
+- Epics: `.planning/phases/{N}-*/epics/*.md`
+- Stories: `.planning/phases/{N}-*/stories/*.md`
+- Code surface: same as project scope, plus any phase-specific `files_modified` from prior SPRINT.md
+
+For each missing artifact, log a warning to stdout and continue. This is
+**fail-open with notice** per Phase 6 D-3: never block scanning when an
+upstream layer is absent — report partial scope clearly.
+
+Track `present_layers[]` (subset of `["prd","epics","stories","code"]`).
+</step>
+
+<step name="scan_drift">
+**If `MODE=feature` (default):**
+
+Spawn `rihal-docs-auditor` with `--mode=feature-drift`. Pass:
+- artifact contents (from previous step)
+- `present_layers[]` so the auditor doesn't claim drift between absent layers
+- code surface paths
+
+Auditor returns structured JSON:
+
+```json
+{
+  "drift": [
+    {
+      "id": "drift-001",
+      "severity": "trivial|minor|major|critical",
+      "layer_a": "prd|epics|stories|code",
+      "layer_b": "prd|epics|stories|code",
+      "claim_a": "<text from layer_a>",
+      "claim_b": "<text from layer_b>",
+      "file": "<path>",
+      "line": <number-or-null>,
+      "fix_hint": "<exact replacement string when severity=trivial; otherwise null>"
+    }
+  ],
+  "layers_skipped": ["..."]
+}
+```
+
+**If `MODE=phase-status` (Phase 8 / #461):**
+
+Spawn `rihal-docs-auditor` with `--mode=phase-status`. Pass:
+- `roadmap_phases[]` — output of `node rihal/bin/rihal-tools.cjs roadmap list-phases` (post-#464 fix)
+- `phase_dirs[]` — output of `node rihal/bin/rihal-tools.cjs init phase-op N` for each phase number, OR a direct walk of `.planning/phases/*` that captures: dir name, presence of `*-SUMMARY.md`, `*-SPRINT.md`, `*-PLAN.md`, `*-CONTEXT.md`, `*-RESEARCH.md`, `*-VERIFICATION.md`
+- For each phase, the most recent commit hash that touches files in `${phase_dir}/` (used as a freshness signal)
+
+Auditor returns structured JSON:
+
+```json
+{
+  "drift": [
+    {
+      "id": "phase-status-drift-001",
+      "severity": "trivial|partial|major",
+      "phase_number": "<N>",
+      "claimed_status": "Complete|Active|Planned",
+      "shipping_signals": {
+        "has_summary": true,
+        "has_sprint": true,
+        "last_commit_iso": "<YYYY-MM-DD>",
+        "phase_dir_present": true
+      },
+      "evidence": "<one-line summary of why this is drift>",
+      "fix_hint": "<for trivial: exact ROADMAP edit (e.g., add ✓ marker); for partial/major: null>"
+    }
+  ]
+}
+```
+
+**Severity rules (HARD, enforced in this workflow not delegated):**
+- `trivial` — missing `✓` marker on heading even though Status says Complete; or missing date on Status: Complete line. `fix_hint` carries the exact insertion.
+- `partial` — N of M acceptance items shipped per phase ROADMAP entry; status doesn't reflect partial state. `fix_hint` is null — humans must decide whether to flip status or update acceptance.
+- `major` — entirely-incorrect status. Examples: Status: Complete with NO SUMMARY.md and NO commits on phase scope; Status: Planned but ALL acceptance items shipped (the Phase 4 case from this session). `fix_hint` always null — humans must decide.
+
+Parse the JSON. If parsing fails or the `drift` field is absent, treat the auditor's response as a malfunction and abort with a clear error pointing the user at the agent definition.
+</step>
+
+<step name="severity_classify">
+Hard allowlist for `--fix` mode — enforced in code, not by agent discretion.
+
+Trivial only:
+- typo correction (single-word misspelling, lowercase/uppercase letter case)
+- stale ISO date (e.g., "2024-12-31" when current date is later)
+- broken relative path (e.g., docs reference `./foo.md` but file moved)
+- factually-wrong-and-mechanically-correctable values (e.g., "API returns JSON" when code returns YAML — only when `fix_hint` carries the exact replacement)
+
+Anything else (minor / major / critical) is **report-only** — never patched
+even if `--fix` is set. This is the safety promise of D-2; do not weaken it.
+</step>
+
+<step name="report_or_fix">
+**If `FIX_MODE=false`:**
+
+Determine output path:
+- Inside a phase context: `${phase_dir}/DRIFT.md`
+- Otherwise: `.planning/audits/feature-drift-${ISO-date}.md`
+
+Write the report grouped by severity (critical / major / minor / trivial),
+each section listing the findings with: layer pair, claim mismatch, file:line.
+Print summary: `{N} drift findings — {trivial}/{minor}/{major}/{critical}`.
+
+**Phase ID convention for "proposed phase" / "Phase candidate" columns.**
+If the report includes a column suggesting where a finding should land
+(e.g. for downstream `/rihal-plan-milestone-gaps`), use the project's
+real numeric phase numbering — never invent English-letter labels like
+`P-NEW-AI-1` or `P-FIX-N`. Resolve the next free integer with:
+
+```bash
+HIGHEST=$(node ".rihal/bin/rihal-tools.cjs" phases list --pick "directories[-1]" 2>/dev/null || echo "")
+# Extract leading number; next candidate = N + 1, N + 2, ...
+```
+
+Or for a related cluster of findings, propose decimals under the most
+relevant existing phase (e.g. 14.1, 14.2) — the CLI auto-resolves the
+next free `parent.M` via `phase add --decimal <parent>` (#477 item C).
+
+This convention follows the `feedback-no-leading-zeros` rule from the
+Memory Bank: phase 6 not 06, phase 14.1 not 14-01, never letter-prefixed
+ad-hoc IDs.
+
+**If `FIX_MODE=true`:**
+
+Bounded fix loop, max 3 passes:
+
+```
+pass = 0
+while pass < 3:
+  pass += 1
+  trivial_findings = drift.filter(d => d.severity == "trivial")
+  if trivial_findings is empty: break
+
+  for each trivial finding:
+    spawn rihal-noor (writer) with the fix_hint payload
+    after the writer returns, run:
+      git add <file>
+      git commit -m "fix(drift): <what was stale> → <what's true now>"
+
+  re-run scan_drift (the auditor) to detect any new drift surfaced by the fixes
+```
+
+For findings with severity > trivial: add to the report only; never patch.
+
+After the loop, write the final report (same path as report-only mode), and
+print: `Fixed {N} trivial drifts across {N} commits. Report: {path}`.
+</step>
+
+<step name="commit">
+If `--fix` produced commits, those were already atomic per fix — no further
+work is needed.
+
+The report file itself is committed only when `commit_docs` is true:
+
+```bash
+COMMIT_DOCS=$(node ".rihal/bin/rihal-tools.cjs" config-get commit_docs 2>/dev/null || echo "false")
+if [[ "$COMMIT_DOCS" == "true" ]]; then
+  git add "${REPORT_PATH}"
+  git commit -m "docs(drift): scan ${ISO_DATE}"
+fi
+```
+</step>
+
+</process>
+
+<guardrails>
+- NEVER patch items above trivial severity, even if user passes a `--force` flag (don't even accept --force here)
+- NEVER spawn parallel writer agents — drift fixes must be sequential to avoid conflicting edits to the same file
+- Bounded fix loop: max 3 passes. If trivial findings remain after 3 passes, abort the loop and report them as unresolvable
+- If `layers_skipped` is non-empty, the report MUST clearly state which drift could not be detected (so the absence of findings doesn't read as "no drift exists")
+- The hard severity allowlist (trivial only for --fix) is enforced in this workflow's code path, not delegated to the agent. Do not move the check into the agent.
+- **`--quick` and `--fix` interaction (Phase 8):** when `QUICK_MODE=true`, `FIX_MODE` is forced to false in parse_args. Hooks must never auto-modify files. If a user explicitly invokes `feature-drift --quick --fix`, the workflow runs in report-only and prints a notice that `--fix` was suppressed by `--quick`. Do not weaken this rule.
+- **`--mode=phase-status` (Phase 8 / #461):** detector reads ROADMAP.md `**Status:**` lines and compares against shipping signals (SUMMARY.md, SPRINT.md, git log on phase scope). Severity rules: trivial = missing ✓ marker; partial = N of M acceptance items shipped; major = entirely-incorrect-status (e.g., Complete with no SUMMARY, Planned with all artifacts shipped). `--fix` patches only the trivial tier (✓ marker addition + missing date). NEVER auto-flip Active→Complete or Planned→Complete — those are decisions, not corrections.
+</guardrails>
+
+<success_criteria>
+- [ ] DRIFT.md (or `audits/feature-drift-{ISO}.md`) written with severity-grouped sections
+- [ ] When `--fix` set: only trivial items patched, each as atomic commit with `fix(drift):` message prefix
+- [ ] When layers missing: report clearly states limited scope (`layers_skipped` block prominent)
+- [ ] Bounded loop terminates within 3 passes
+- [ ] Report-only mode (no `--fix`) preserves zero file modifications outside the report itself
+</success_criteria>

package/rihal/workflows/forensics.md

@@ -54,7 +54,7 @@ Store as `$FAILED_EXECS`.
 Scan `.planning/` directory for:
 
 ```bash
-find .planning/ -name "SPRINT.md" -type f
+find .planning/ -maxdepth 5 -name "SPRINT.md" -type f | head -50
 ```
 
 For each SPRINT.md found, check if a corresponding SUMMARY.md exists:
@@ -157,7 +157,7 @@ To continue:
 
 **If no incomplete work found:**
 ```
-✅ No incomplete executions detected. All phases complete or active.
+✓ No incomplete executions detected. All phases complete or active.
 ```
 
 ## Step 8 — Print full diagnostic report
@@ -199,3 +199,11 @@ If arguments are invalid, missing files, or subagent fails:
 - Check that required files exist
 - Retry with clearer arguments or report the specific error to the user
 
+
+## ▶ Next Up
+
+After reviewing the diagnostic report, pick your recovery path:
+
+- **Phase stuck mid-execution:** `/rihal-resume-work`
+- **Phase planned but not executed:** `/rihal-execute {phase-number}`
+- **No incomplete work found:** `/rihal-progress` — view current state

package/rihal/workflows/health.md

@@ -1,7 +1,7 @@
 # Workflow: rihal-health
 
 <purpose>
-Run 6-point compliance check on rihal installation. Each check is pass/fail. Summary at the end.
+Run 9-point health check: 6 installation checks + 3 project-state checks. Each check is pass/fail. Summary at the end.
 </purpose>
 
 
@@ -35,7 +35,7 @@ test -d .rihal && test -w .rihal
 
 **Output on pass:**
 ```
-✅ PASS — .rihal/ directory exists and is writable
+✓ PASS — .rihal/ directory exists and is writable
 ```
 
 **Output on fail:**
@@ -59,7 +59,7 @@ Verify:
 
 **Output on pass:**
 ```
-✅ PASS — files-manifest.csv is valid (N files tracked)
+✓ PASS — files-manifest.csv is valid (N files tracked)
 ```
 
 **Output on fail:**
@@ -81,7 +81,7 @@ Detect drift: files that exist but hash doesn't match.
 
 **Output on pass:**
 ```
-✅ PASS — All files match manifest (no drift detected)
+✓ PASS — All files match manifest (no drift detected)
 ```
 
 **Output on fail (drift found):**
@@ -113,7 +113,7 @@ Parse as JSON. Verify top-level keys present:
 
 **Output on pass:**
 ```
-✅ PASS — state.json is valid and initialized
+✓ PASS — state.json is valid and initialized
 ```
 
 **Output on fail:**
@@ -136,7 +136,7 @@ Verify:
 
 **Output on pass:**
 ```
-✅ PASS — agent-manifest.csv is valid (N agents installed)
+✓ PASS — agent-manifest.csv is valid (N agents installed)
 ```
 
 **Output on fail:**
@@ -155,7 +155,7 @@ node .rihal/bin/rihal-tools.cjs version
 
 **Output on pass:**
 ```
-✅ PASS — rihal-tools.cjs is executable and responsive
+✓ PASS — rihal-tools.cjs is executable and responsive
 ```
 
 **Output on fail:**
@@ -163,26 +163,69 @@ node .rihal/bin/rihal-tools.cjs version
 ❌ FAIL — rihal-tools.cjs is missing or broken. Run: /rihal-update to repair
 ```
 
-## Step 6 — Count results and print final summary
+## Step 6 — Project state health checks (3 checks)
 
-**Action:** Count all pass/fail results and display overall status.
+Run these after installation checks. Skip if `.rihal/state.json` doesn't exist.
 
-Total: `{N}/6 checks passed`
+**Check 7 — state.json phase count matches ROADMAP.md**
 
-If all 6 pass:
+```bash
+ROADMAP_PHASES=$(grep -c '^## Phase\|^### Phase\|^- Phase' .planning/ROADMAP.md 2>/dev/null || echo 0)
+STATE_PHASES=$(node .rihal/bin/rihal-tools.cjs state read 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('phases',[])) if d else 0)" 2>/dev/null || echo 0)
 ```
-✅ All systems nominal — rihal is healthy
+
+If counts match: `✓ PASS — {N} phases in ROADMAP.md and state.json are in sync`
+If they differ: `⚠ WARN — ROADMAP.md has ${ROADMAP_PHASES} phases, state.json has ${STATE_PHASES}. Run: /rihal-status to investigate`
+
+**Check 8 — current phase has a SPRINT.md or CONTEXT.md**
+
+```bash
+CURRENT=$(node .rihal/bin/rihal-tools.cjs state read 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('current_phase',''))" 2>/dev/null)
+find .planning/phases/*${CURRENT}* -name "*-SPRINT.md" -o -name "*-CONTEXT.md" 2>/dev/null | head -1
 ```
 
-If fewer than 6 pass:
+If current_phase is null or empty: skip this check (not started).
+If file found: `✓ PASS — current phase ${CURRENT} has planning artifacts`
+If no file: `⚠ WARN — current phase ${CURRENT} has no SPRINT.md or CONTEXT.md. Run: /rihal-plan ${CURRENT}`
+
+**Check 9 — no phantom-complete phases (ROADMAP says complete but no artifacts)**
+
+```bash
+node .rihal/bin/rihal-tools.cjs state snapshot 2>/dev/null | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+insights = d.get('insights', [])
+phantom = [i for i in insights if i.get('kind') == 'phantom-complete']
+print(len(phantom))
+" 2>/dev/null || echo 0
 ```
-⚠️ {N}/6 checks passed — {M} issue(s) found
-Run: /rihal-update to repair
+
+If 0 phantoms: `✓ PASS — no phantom-complete phases detected`
+If any: `⚠ WARN — {N} phantom-complete phase(s) detected. Run: /rihal-audit to inspect`
+
+---
+
+## Step 7 — Count results and print final summary
+
+**Action:** Count all pass/fail/warn results and display overall status.
+
+Total: `{N}/9 checks passed`
+
+If all 9 pass:
+```
+✓ All systems nominal — rihal is healthy
+```
+
+If fewer than 9 pass:
+```
+⚠ {N}/9 checks passed — {M} issue(s) found
+Run: /rihal-update to repair installation issues
+Run: /rihal-status for project-state issues
 ```
 
 ## Success Criteria
 
-- [ ] All 6 checks executed
+- [ ] All 9 checks executed (skip state checks if no state.json)
 - [ ] Each check result printed clearly
 - [ ] Final summary shows pass/fail count
 - [ ] Repair instructions shown if any checks fail
@@ -192,3 +235,9 @@ Run: /rihal-update to repair
 - **Directory not readable:** Print error and suggest filesystem check
 - **CSV parsing fails:** Print error and suggest re-running update
 - **JSON corruption:** Print error and suggest state.json reset
+
+## ▶ Next Up
+
+- **Issues found:** `/rihal-forensics` — deep diagnostic on specific failures
+- **Ready to continue:** `/rihal-do` — interactive router guides next step
+- **Fix specific phase:** `/rihal-correct-course {phase}` — targeted correction

package/rihal/workflows/help.md

@@ -37,6 +37,15 @@ Output the matching `<tier-N>` block below verbatim. For `all`, output all three
 > **Rihal** is council-driven project automation built for solo agentic work in Claude Code.
 > Tier 1 is everything you need to ship a small project end-to-end. **8 commands.**
 
+## Not installed yet?
+
+```bash
+npx @hanzlaa/rcode install    # install into current project
+```
+
+Run this once from your project root. Then open a new Claude Code session and use the commands below.
+Need help? See `docs/getting-started.md` or run `/rihal-help` after install.
+
 ## The loop
 
 ```
@@ -116,20 +125,22 @@ init → new-project → plan → execute → next → status → ship
 | Command | When to use |
 |---------|-------------|
 | `/rihal-show <id>` | Print a phase or plan in full with execution status. |
-| `/rihal-add-phase <name>` | Append a new phase to the active milestone. |
-| `/rihal-insert-phase <after> <name>` | Insert urgent decimal phase (e.g. 7.1) without renumbering. |
-| `/rihal-remove-phase <n>` | Remove a future phase and renumber. |
+| `/rihal-phase <name> [--insert \| --remove]` | **Unified phase CRUD.** Default: append next integer phase. `--insert <parent>` slots a decimal phase. `--remove <id>` deletes an unstarted future phase. |
+| `/rihal-add-phase <name>` | Alias for `/rihal-phase <name>`. |
+| `/rihal-insert-phase <after> <name>` | Alias for `/rihal-phase --insert <after> <name>`. |
+| `/rihal-remove-phase <n>` | Alias for `/rihal-phase --remove <n>`. |
 | `/rihal-quick [flags]` | Small ad-hoc tasks with Rihal guarantees but skip optional agents. Flags: `--discuss`, `--research`, `--full`. |
-| `/rihal-fast "<task>"` | Trivial inline task — typo, gitignore tweak, etc. No subagents, ≤3 file edits. |
+| `/rihal-fast "<task>"` | Trivial inline task — typo, gitignore tweak, etc. No subagents, ≤3 file edits. *Not yet implemented (#482-B).* |
 
 ## Capture & session continuity
 
 | Command | When to use |
 |---------|-------------|
-| `/rihal-note "<text>"` | Zero-friction idea capture — appends to dated note file. |
-| `/rihal-add-todo [desc]` | Capture an idea or task as a todo (infers from conversation if no arg). |
-| `/rihal-check-todos [area]` | List pending todos and pick one to work on. |
-| `/rihal-plant-seed "<idea>"` | Capture a forward-looking idea with trigger conditions — surfaces at the right milestone. |
+| `/rihal-capture "<text>" [--note \| --seed \| --list]` | **Unified capture.** Default: todo. `--note` for passive observation. `--seed` for forward-looking idea with trigger conditions. `--list` to show pending todos. |
+| `/rihal-add-todo [desc]` | Alias for `/rihal-capture` (default mode). |
+| `/rihal-note "<text>"` | Alias for `/rihal-capture --note`. |
+| `/rihal-plant-seed "<idea>"` | Alias for `/rihal-capture --seed`. |
+| `/rihal-check-todos [area]` | Alias for `/rihal-capture --list`. |
 | `/rihal-resume-work` | Restore project context after a break. |
 | `/rihal-pause-work` | Create HANDOFF.json and continue-here.md before stopping mid-phase. |
 | `/rihal-session-report` | Work summary, decisions, open blockers from this session. |
@@ -175,6 +186,10 @@ init → new-project → plan → execute → next → status → ship
 | `/rihal-audit-uat` | Cross-phase audit of all outstanding UAT items. |
 | `/rihal-audit-fix` | Autonomous audit-to-fix pipeline — find, classify, fix, test, commit. |
 | `/rihal-code-review --karpathy` | Audit recent code against Karpathy's 4 LLM coding principles. |
+| `/rihal-karpathy-audit` | Full Karpathy engineering principles audit across the codebase. |
+| `/rihal-check-implementation-readiness` | Verify a feature is fully ready to implement before writing code. |
+| `/rihal-review-edge-case-hunter` | Hunt for edge cases and boundary conditions before execution. |
+| `/rihal-diagnose-issues` | Triage and diagnose systemic issues before a debug session. |
 | `/rihal-ui-phase <n>` | Generate UI design contract (UI-SPEC.md) for frontend phases. |
 | `/rihal-ui-review` | Retroactive 6-pillar visual audit of completed UI work. |
 | `/rihal-code-review --attack` | Hostile-perspective report — vulnerabilities, race conditions, abuse. |
@@ -186,6 +201,7 @@ init → new-project → plan → execute → next → status → ship
 | Command | Use |
 |---------|-----|
 | `/rihal-discuss-phase --power` | Bulk question generation with async UI for context-heavy phases. |
+| `/rihal-discuss-phase-power` | Standalone deep-dive phase discussion with full research + assumptions. |
 | `/rihal-chain <preset> <topic>` | Sequential agent pipeline (research → scope → build), typed artifacts. |
 | `/rihal-brainstorm` | Guided brainstorming — pick a method, generate ideas systematically. |
 | `/rihal-why <decision>` | Explain reasoning behind a decision, classification, or panel pick. |
@@ -201,7 +217,7 @@ init → new-project → plan → execute → next → status → ship
 | `/rihal-install <module>` | Install a Rihal capability bundle into the project. |
 | `/rihal-enable-hooks` | Install optional Rihal hooks into `.claude/settings.json`. |
 | `/rihal-scaffold-project` | Scaffold a new project from the official Rihal template. |
-| `/rihal-bootstrap` | Bootstrap repo with Vercel-linked resources and integrations. |
+| `/rihal-bootstrap` | Bootstrap repo with Vercel-linked resources and integrations. *Not yet implemented (#481).* |
 
 ## Story-level epics workflow
 
@@ -226,6 +242,17 @@ init → new-project → plan → execute → next → status → ship
 | `/rihal-notify-test` | Verify Slack/Discord/MS Teams webhook wiring — posts a test message. |
 | `/rihal-from-template <type>` | Seed .planning/ from a starter template (saas-b2b, api-backend, mobile-app). |
 | `/rihal-retrospective` | Run an epic retrospective and produce owned action items. |
+| `/rihal-new-project-research` | Research subcommand — deep research before new project roadmap creation. |
+| `/rihal-new-project-roadmap` | Roadmap subcommand — generate phase roadmap from new project research. |
+
+## Memory
+
+| Command | Use |
+|---------|-----|
+| `/rihal-memory-init` | Initialize the memory bank for a project (first-time setup). |
+| `/rihal-memory-update` | Update a specific memory entry with new information. |
+| `/rihal-memory-audit` | Audit all memory files for staleness and coverage gaps. |
+| `/rihal-memory-distill` | Distill verbose memory into concise, LLM-friendly summaries. |
 
 ## Operational / rare
 

package/rihal/workflows/import.md

@@ -1,5 +1,9 @@
 # Import Workflow
 
+<purpose>
+External plan ingestion with conflict detection and agent delegation. Imports an externally-authored plan, detects conflicts against existing project decisions, writes SPRINT.md, and validates via rihal-sprint-checker.
+</purpose>
+
 External plan ingestion with conflict detection and agent delegation.
 
 - **--from**: Import external plan → conflict detection → write SPRINT.md → validate via rihal-sprint-checker
@@ -97,7 +101,7 @@ Load project context for conflict detection:
    **If REQUIREMENTS.md does not exist:** skip requirement conflict checks and continue.
 4. Glob for all CONTEXT.md files across phase directories:
    ```bash
-   find .planning/phases/ -name "*-CONTEXT.md" -o -name "CONTEXT.md" 2>/dev/null
+   find .planning/phases/ -name "*-CONTEXT.md" -o -name "CONTEXT.md" 2>/dev/null | sort | tail -5
    ```
    Read each CONTEXT.md found — extract locked decisions (any decision in a `<decisions>` block)
 
@@ -243,12 +247,22 @@ Task({
 })
 ```
 
-If the checker returns errors:
+**If the Task() call itself fails** (subagent could not start, tool error, or unexpected exception):
+
+Display:
+```
+⚠  Sprint-checker could not run (subagent error). The plan file was written but validation was skipped.
+   You can validate manually later with: /rihal-discuss fatima review .planning/phases/{phase}/{plan}-SPRINT.md
+```
+
+Proceed to plan_finalize — do NOT abort the import over a validator failure.
+
+**If the checker returns errors:**
 - Display the errors to the user
 - Ask the user to resolve issues before the plan is considered imported
 - Do not delete the written file — the user can fix and re-validate manually
 
-If the checker returns clean:
+**If the checker returns clean:**
 - Display: "Plan validation passed"
 
 </step>

package/rihal/workflows/init.md

@@ -69,18 +69,28 @@ Print one-line state summary:
 
 If `state === "returning"` and `--reset` not passed:
 
-```
-✓ Rihal is already configured here.
+- If `rihla-present: yes` — print the standard returning message and STOP:
 
-What next?
-  /rihal-resume-work    — pick up where you left off
-  /rihal-status         — see the dashboard
-  /rihal-next           — suggested next action
+  ```
+  ✓ Rihal is already configured here.
 
-Or run with --reset to reconfigure.
-```
+  What next?
+    /rihal-resume-work    — pick up where you left off
+    /rihal-status         — see the dashboard
+    /rihal-next           — suggested next action
+
+  Or run with --reset to reconfigure.
+  ```
+
+- If `rihla-present: no` — RIHLA.md is missing from a partial prior init. Do NOT stop. Print a recovery notice and continue to Steps 4 and 4b to write the missing baseline:
+
+  ```
+  ✓ Rihal is already configured here.
+
+  RIHLA.md baseline is missing — completing the scan step now...
+  ```
 
-STOP here unless `--reset` was passed.
+  Skip Steps 2 and 3 (config already exists). Jump directly to Step 4.
 
 ## Step 2 — Ask the questions
 
@@ -336,5 +346,5 @@ Silent if state tools fail.
 - **AskUserQuestion unavailable:** fall back to reading defaults from env / existing config and skip the interactive step.
 - **config.yaml write fails:** print permission error and stop.
 - **git not installed:** skip git detection, still proceed.
-- **rihal-tools.cjs not found:** this command requires the installer to have run — point user to `install-v2.js`.
+- **rihal-tools.cjs not found:** this command requires the installer to have run — point user to `npx @hanzlaa/rcode install`.
 - **Existing RIHLA.md without `--reset`:** do NOT overwrite; note it in Step 4 output.

package/rihal/workflows/install.md

@@ -47,21 +47,13 @@ And stop.
 The installer needs to be called with the `--module` flag. Detect the rihal-code package location:
 
 ```bash
-# Try local dev first, then global
-if [ -f ./cli/install-v2.js ]; then
-  node ./cli/install-v2.js . --module {name} --force --yes
-elif [ -f "$(npm root -g)/@hanzlaa/rcode/cli/install-v2.js" ]; then
-  node "$(npm root -g)/@hanzlaa/rcode/cli/install-v2.js" . --module {name} --force --yes
-else
-  echo "Cannot find rihal-code package. Install it globally or run from the repo."
-  exit 1
-fi
+npx @hanzlaa/rcode install --module {name} --force --yes
 ```
 
 ## Step 4 — Print summary
 
 ```
-✅ Module installed: {name}
+✓ Module installed: {name}
    {description from module manifest}
 
 New commands available: