@hanzlaa/rcode 3.4.4 → 3.4.6

package/rihal/workflows/map-codebase.md

@@ -93,7 +93,9 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_MAPPER=$(node .rihal/bin/rihal-tools.cjs agent-skills rihal-codebase-mapper 2>/dev/null)
 ```
 
-Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `response_language`.
+
+**If `response_language` is set:** include `Respond in {response_language}.` in all spawned subagent prompts.
 </step>
 
 <step name="check_existing">
@@ -167,6 +169,7 @@ Use Task tool with `subagent_type="rihal-codebase-mapper"`, `model="{mapper_mode
 ```
 Task(
   subagent_type="rihal-codebase-mapper",
+  model="sonnet",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase tech stack",
@@ -188,6 +191,7 @@ ${AGENT_SKILLS_MAPPER}"
 ```
 Task(
   subagent_type="rihal-codebase-mapper",
+  model="sonnet",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase architecture",
@@ -209,6 +213,7 @@ ${AGENT_SKILLS_MAPPER}"
 ```
 Task(
   subagent_type="rihal-codebase-mapper",
+  model="sonnet",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase conventions",
@@ -230,6 +235,7 @@ ${AGENT_SKILLS_MAPPER}"
 ```
 Task(
   subagent_type="rihal-codebase-mapper",
+  model="sonnet",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase concerns",

package/rihal/workflows/memory-audit.md

@@ -1,12 +1,31 @@
 # Workflow: rcode-memory-audit
 
-Read-only audit of the Memory Bank. Produces a severity-tagged report. Never modifies files.
+<purpose>
+Audit the Memory Bank for stale entries, contradictions, missing sections, and content that should be archived. Read-only by default with severity-tagged report; `--fix` patches trivial items per Phase 6 D-1 / D-2.
+</purpose>
+
+Audit the Memory Bank. Default mode is read-only (severity-tagged report).
+Optional `--fix` flag patches trivial items in place per Phase 6 D-1 / D-2.
 
 ---
 
 ## Inputs
 
-None required. Optional `--severity {critical|warn|info}` to filter output.
+None required.
+
+Optional flags:
+- `--severity {critical|warn|info}` — filter report output
+- `--fix` — opt-in auto-fix mode. Patches only items the auditor classifies
+  as severity=trivial (typos, stale ISO dates, broken relative paths,
+  factually-wrong-and-mechanically-correctable values). Hard-allowlisted
+  in code: items above trivial are never patched. Default OFF.
+
+```bash
+FIX_MODE=false
+if [[ "$ARGUMENTS" =~ (^|[[:space:]])--fix($|[[:space:]]) ]]; then
+  FIX_MODE=true
+fi
+```
 
 ## Preconditions
 
@@ -71,13 +90,56 @@ If `--severity` filter passed, hide findings below the threshold.
 
 If zero findings: print `✓ Memory Bank is healthy. 0 findings.`
 
+### Step 9 — Apply fixes (only when `--fix` is set)
+
+<step name="apply_fixes">
+Skip if `FIX_MODE` is false.
+
+For each finding from the audit:
+- If severity is `trivial` (typo, stale ISO date, dead relative path,
+  provably-wrong factual value with an unambiguous replacement), patch in place.
+- For all other severities (`info`, `warn`, `critical`), leave for human review
+  and keep them in the report — never patch.
+
+Patching rule (HARD): use file Read+Edit (NOT regex sed) so fixes are exact
+string replacements that fail loudly on ambiguity. Sed-based mass-replace is
+forbidden because it silently rewrites unintended occurrences.
+
+Atomic commit per fix:
+
+```bash
+git add <file>
+git commit -m "fix(memory): <what was stale> → <what's true now>"
+```
+
+After the loop, log: `Memory --fix applied {N} trivial corrections across {M} commits.`
+
+If a finding marked trivial fails to patch (file changed mid-flight, ambiguous
+replacement, etc.), log it under "Skipped fixes" in the final report and
+continue with the next finding — never abort the whole run on a single failure.
+</step>
+
 ---
 
+## Guardrails
+
+- `--fix` NEVER patches above trivial severity, even with a `--force` flag (don't accept --force here)
+- `--fix` uses Read+Edit, not regex sed
+- `--fix` commits each correction atomically (no batched commits)
+- Default behavior (no `--fix`) is unchanged: report-only
+
 ## Post-conditions
 
-- No files modified
-- Report printed to stdout
+- When `--fix` is OFF: no files modified; report printed to stdout
+- When `--fix` is ON: only trivial items modified; each as its own commit; report still printed
 
 ## Reversibility
 
-Read-only — no state to revert.
+- Default mode: read-only — no state to revert.
+- `--fix` mode: each fix is its own atomic git commit, so individual fixes can be reverted with `git revert <hash>`.
+
+## Success criteria
+
+- [ ] Default behavior unchanged — `--fix` off by default; report-only path preserved
+- [ ] `--fix` patches only trivial items, each as atomic commit prefixed `fix(memory):`
+- [ ] Report still printed even in `--fix` mode (so user sees what was/wasn't patched)

package/rihal/workflows/memory-distill.md

@@ -1,5 +1,9 @@
 # Workflow: rcode-memory-distill
 
+<purpose>
+Regenerate Memory Bank distillates with lossless compression — token-optimized snapshots of source files for fast LLM context loading. Idempotent: re-running on already-distilled content produces identical output.
+</purpose>
+
 Regenerate Memory Bank distillates with lossless compression. Idempotent.
 
 ---
@@ -101,3 +105,9 @@ Print per-target:
 ## Reversibility
 
 Distillates are derived artefacts. Reverting a regeneration: `git checkout .rihal/memory/distillates/`.
+
+## On Completion
+
+/rihal-memory-audit — audit all memory files for staleness
+/rihal-next — get suggested next action
+/rihal-resume-work — continue with current work context

package/rihal/workflows/memory-init.md

@@ -1,5 +1,9 @@
 # Workflow: rcode-memory-init
 
+<purpose>
+Bootstrap the rcode Memory Bank for a project. Copies templates from `rihal/templates/memory/` into `.rihal/memory/`, then asks 5 seed questions to populate context. Idempotent: re-running on an initialised project produces a gap report instead of overwriting.
+</purpose>
+
 Bootstraps the rcode Memory Bank in the current project. Idempotent — re-running on an initialised project switches to a gap report instead of overwriting.
 
 ---

package/rihal/workflows/memory-update.md

@@ -1,5 +1,9 @@
 # Workflow: rcode-memory-update
 
+<purpose>
+Append-only surgical update to a single Memory Bank file. Adds a decision, known issue, stakeholder note, or milestone update from current conversation context. Never rewrites, never deletes — pure append.
+</purpose>
+
 Append-only surgical update to a single Memory Bank file. Never rewrites, never deletes.
 
 ---

package/rihal/workflows/new-milestone.md

@@ -549,11 +549,16 @@ git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md 2>/dev
   echo "ℹ .planning/ gitignored — roadmap written, not committed"
 ```
 
-Also record the milestone start in state:
+Also record the milestone start in state and sync roadmapper phases:
 
 ```bash
 node ".rihal/bin/rihal-tools.cjs" state add-decision \
   --summary "Started milestone v[X.Y] [Name]: [N] phases, [X] requirements" 2>/dev/null || true
+
+# Sync all roadmapper-created phases into state.json.
+# rihal-roadmapper writes ROADMAP.md as text — it never calls `phase add` — so
+# state.json has no phase entries until this runs. Closes #504.
+node ".rihal/bin/rihal-tools.cjs" state sync --from-disk 2>/dev/null || true
 ```
 
 ## 11. Done
@@ -611,6 +616,7 @@ or
 - **Roadmapper returns ROADMAP BLOCKED:** surface the blocker, collect resolution, re-spawn.
 - **`rihal-tools.cjs state` fails:** continue — state tracking is optional, file artifacts are mandatory.
 - **`.planning/` is gitignored:** write files, print ℹ notice, do not error.
+- **Phase archive completes but state.json write fails mid-sequence:** do NOT re-archive. Tell the user: "Phase archive completed but milestone state was not recorded. Recovery: run `node .rihal/bin/rihal-tools.cjs state sync --from-disk` then re-run `/rihal-new-milestone` — it will detect the existing archive and skip re-archiving."
 </on_error>
 </content>
 </invoke>

package/rihal/workflows/new-project-create-roadmap.md

@@ -0,0 +1,176 @@
+<purpose>
+Sub-step of new-project.md — Step 8 Create Roadmap. Spawns rihal-roadmapper agent to build ROADMAP.md from requirements and project type. Includes approval gate and commit.
+</purpose>
+
+## 8. Create Roadmap
+
+Display stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning roadmapper...
+```
+
+Spawn rihal-roadmapper agent:
+
+```
+Task(prompt="
+<planning_context>
+
+<files_to_read>
+- .planning/PROJECT.md (Project context)
+- .planning/REQUIREMENTS.md (v1 Requirements)
+- .planning/research/SUMMARY.md (Research findings - if exists)
+- .planning/config.json (Granularity and mode settings)
+</files_to_read>
+
+${AGENT_ROADMAPPER}
+
+</planning_context>
+
+<instructions>
+Create roadmap:
+1. Derive phases from requirements (don't impose structure)
+2. Map every v1 requirement to exactly one phase
+3. Derive 2-5 success criteria per phase (observable user behaviors)
+4. Validate 100% coverage
+5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+6. Return ROADMAP CREATED with summary
+
+Write files first, then return. This ensures artifacts persist even if context is lost.
+</instructions>
+", subagent_type="rihal-roadmapper", model="${ROADMAPPER_MODEL}", description="Create roadmap")
+```
+
+**Handle roadmapper return:**
+
+**If `## ROADMAP BLOCKED`:**
+
+- Present blocker information
+- Work with user to resolve
+- Re-spawn when resolved
+
+**If `## ROADMAP CREATED`:**
+
+Read the created ROADMAP.md and present it nicely inline:
+
+```
+---
+
+## Proposed Roadmap
+
+**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓
+
+| # | Phase | Goal | Requirements | Success Criteria |
+|---|-------|------|--------------|------------------|
+| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
+| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |
+| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
+
+### Phase Details
+
+**Phase 1: [Name]**
+Goal: [goal]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [criterion]
+2. [criterion]
+3. [criterion]
+
+[... continue for all phases ...]
+
+---
+```
+
+**If auto mode:** Skip approval gate — auto-approve and commit directly.
+
+**CRITICAL: Ask for approval before committing (interactive mode only):**
+
+Use AskUserQuestion:
+
+- header: "Roadmap"
+- question: "Does this roadmap structure work for you?"
+- options:
+  - "Approve" — Commit and continue
+  - "Adjust phases" — Tell me what to change
+  - "Review full file" — Show raw ROADMAP.md
+
+**If "Approve":** Continue to commit.
+
+**If "Adjust phases":**
+
+- Get user's adjustment notes
+- Re-spawn roadmapper with revision context:
+
+  ```
+  Task(prompt="
+  <revision>
+  User feedback on roadmap:
+  [user's notes]
+
+  <files_to_read>
+  - .planning/ROADMAP.md (Current roadmap to revise)
+  </files_to_read>
+
+  ${AGENT_ROADMAPPER}
+
+  Update the roadmap based on feedback. Edit files in place.
+  Return ROADMAP REVISED with changes made.
+  </revision>
+  ", subagent_type="rihal-roadmapper", model="${ROADMAPPER_MODEL}", description="Revise roadmap")
+  ```
+
+- Present revised roadmap
+- Loop until user approves
+
+**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
+
+**Generate or refresh project instruction file before final commit:**
+
+The rihal-tools CLI does not expose a `generate-claude-md` subcommand. Instead, if `$INSTRUCTION_FILE` does not already exist, write a minimal instruction file pointing at the rihal workflow docs:
+
+```markdown
+# {INSTRUCTION_FILE} — project instructions
+
+This project uses Rihal for planning and execution. See `.planning/PROJECT.md` for context and `.planning/ROADMAP.md` for phases.
+
+Common commands:
+- /rihal-progress — check status and next action
+- /rihal-discuss-phase N — gather context before planning phase N
+- /rihal-plan N — create a SPRINT.md for phase N
+- /rihal-execute N — execute a SPRINT.md
+- /rihal-verify-work — conversational UAT
+- /rihal-complete-milestone — archive milestone and reset
+
+Rules:
+- Never run `git push` without explicit user authorization.
+- No Claude/AI attribution in commits.
+- Prefer editing existing files over creating new ones.
+```
+
+If it already exists, leave it alone (respect user-customized content).
+
+**Commit roadmap (guarded):**
+
+```bash
+git add \
+  .planning/ROADMAP.md \
+  .planning/STATE.md \
+  .planning/REQUIREMENTS.md \
+  "$INSTRUCTION_FILE" 2>/dev/null \
+&& git commit -m "docs: create roadmap ([N] phases)" 2>/dev/null \
+|| echo "ℹ .planning/ gitignored — roadmap written, not committed (instruction file committed separately)"
+
+# Fallback: also try committing just the instruction file if .planning was ignored
+git add "$INSTRUCTION_FILE" 2>/dev/null && git commit -m "docs: add project instruction file" 2>/dev/null || true
+
+# Sync all roadmapper-created phases into state.json.
+# rihal-roadmapper writes ROADMAP.md as text — it never calls `phase add` — so
+# state.json is empty after this step unless we sync it. Without this, every
+# /rihal-status shows "N phases not registered" warnings immediately after init.
+node ".rihal/bin/rihal-tools.cjs" state sync --from-disk 2>/dev/null || true
+```
+

package/rihal/workflows/new-project-define-requirements.md

@@ -0,0 +1,160 @@
+<purpose>
+Sub-step of new-project.md — Step 7 Define Requirements. Gathers functional requirements through conversation and writes REQUIREMENTS.md.
+</purpose>
+
+## 7. Define Requirements
+
+Display stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► DEFINING REQUIREMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Load context:**
+
+Read PROJECT.md and extract:
+
+- Core value (the ONE thing that must work)
+- Stated constraints (budget, timeline, tech limitations)
+- Any explicit scope boundaries
+
+**If research exists:** Read research/FEATURES.md and extract feature categories.
+
+**If auto mode:**
+
+- Auto-include all table stakes features
+- Include features explicitly mentioned in provided document
+- Auto-defer differentiators not mentioned in document
+- Skip per-category AskUserQuestion loops
+- Skip "Any additions?" question
+- Skip requirements approval gate
+- Generate REQUIREMENTS.md and commit directly
+
+**Present features by category (interactive mode only):**
+
+```
+Here are the features for [domain]:
+
+## Authentication
+**Table stakes:**
+- Sign up with email/password
+- Email verification
+- Password reset
+- Session management
+
+**Differentiators:**
+- Magic link login
+- OAuth (Google, GitHub)
+- 2FA
+
+**Research notes:** [any relevant notes]
+
+---
+
+## [Next Category]
+...
+```
+
+**If no research:** Gather requirements through conversation.
+
+Ask: "What are the main things users need to be able to do?"
+
+For each capability mentioned:
+
+- Ask clarifying questions to make it specific
+- Probe for related capabilities
+- Group into categories
+
+**Scope each category:**
+
+For each category, use AskUserQuestion:
+
+- header: "[Category]" (max 12 chars)
+- question: "Which [category] features are in v1?"
+- multiSelect: true
+- options:
+  - "[Feature 1]" — [brief description]
+  - "[Feature 2]" — [brief description]
+  - "[Feature 3]" — [brief description]
+  - "None for v1" — Defer entire category
+
+Track responses:
+
+- Selected features → v1 requirements
+- Unselected table stakes → v2
+- Unselected differentiators → out of scope
+
+**Identify gaps:**
+
+Use AskUserQuestion:
+
+- header: "Additions"
+- question: "Any requirements research missed?"
+- options:
+  - "No, research covered it" — Proceed
+  - "Yes, let me add some" — Capture additions
+
+**Validate core value:**
+
+Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
+
+**Generate REQUIREMENTS.md:**
+
+Create `.planning/REQUIREMENTS.md` with:
+
+- v1 Requirements grouped by category (checkboxes, REQ-IDs)
+- v2 Requirements (deferred)
+- Out of Scope (explicit exclusions with reasoning)
+- Traceability section (empty, filled by roadmap)
+
+**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
+
+**Requirement quality criteria:**
+
+Good requirements are:
+
+- **Specific and testable:** "User can reset password via email link"
+- **User-centric:** "User can X"
+- **Atomic:** One capability per requirement
+- **Independent:** Minimal dependencies on other requirements
+
+Reject vague requirements. Push for specificity:
+
+- "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
+- "Support sharing" → "User can share post via link that opens in recipient's browser"
+
+**Present full requirements list (interactive mode only):**
+
+Show every requirement for user confirmation:
+
+```
+## v1 Requirements
+
+### Authentication
+- [ ] **AUTH-01**: User can create account with email/password
+- [ ] **AUTH-02**: User can log in and stay logged in across sessions
+- [ ] **AUTH-03**: User can log out from any page
+
+### Content
+- [ ] **CONT-01**: User can create posts with text
+- [ ] **CONT-02**: User can edit their own posts
+
+[... full list ...]
+
+---
+
+Does this capture what you're building? (yes / adjust)
+```
+
+If "adjust": Return to scoping.
+
+**Commit requirements (guarded):**
+
+```bash
+git add .planning/REQUIREMENTS.md 2>/dev/null \
+  && git commit -m "docs: define v1 requirements" 2>/dev/null \
+  || echo "ℹ .planning/ gitignored — requirements written, not committed"
+```
+