@hanzlaa/rcode 2.8.0 → 3.1.0

package/rihal/workflows/code-review.md

@@ -18,7 +18,7 @@ If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 
 **Usage:**
 ```
-/rihal:code-review <phase> [--depth=quick|standard|deep] [--files=path1,path2]
+/rihal:code-review <phase> [--depth=quick|standard|deep] [--files=path1,path2] [--karpathy]
 ```
 
 **Examples:**
@@ -26,8 +26,39 @@ If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 /rihal:code-review 01
 /rihal:code-review 02.1 --depth=deep
 /rihal:code-review 03 --files=src/auth.js,src/db.js
+/rihal:code-review HEAD~5..HEAD --karpathy
 ```
 
+## Step 0a — Karpathy mode delegation
+
+If `$ARGUMENTS` contains `--karpathy`, delegate to the Karpathy 4-principle audit workflow and stop:
+
+```
+Read and execute @.rihal/workflows/karpathy-audit.md end-to-end with the same arguments minus `--karpathy`.
+```
+
+The standard code-review steps below are skipped when `--karpathy` is set — the karpathy-audit workflow produces its own report.
+
+## Step 0b — Attack mode delegation
+
+If `$ARGUMENTS` contains `--attack`, delegate to the attack-mode review workflow and stop:
+
+```
+Read and execute @.rihal/workflows/review-adversarial.md end-to-end with the same arguments minus `--attack`.
+```
+
+Attack mode produces a weakness report from a hostile perspective — security vulnerabilities, race conditions, data loss, abuse cases. The standard code-review steps below are skipped when `--attack` is set.
+
+## Step 0c — Edge cases mode delegation
+
+If `$ARGUMENTS` contains `--edge-cases`, delegate to the edge-case-hunter workflow and stop:
+
+```
+Read and execute @.rihal/workflows/review-edge-case-hunter.md end-to-end with the same arguments minus `--edge-cases`.
+```
+
+Edge-cases mode enumerates boundary conditions by category (input, state, concurrency, network) with severity. The standard code-review steps below are skipped when `--edge-cases` is set.
+
 <process>
 
 <step name="initialize">

package/rihal/workflows/council.md

@@ -98,7 +98,7 @@ Currently registered council agents (always available if installed):
 - rihal-sadiq, rihal-waleed, rihal-fatima, rihal-mariam, rihal-hussain-pm
 
 Specialist agents that may be installed (add to panel if scorer surfaces them):
-- rihal-architect, rihal-ux-designer, rihal-tech-writer
+- rihal-ux-designer, rihal-noor
 - rihal-codebase-mapper, rihal-project-researcher, rihal-roadmapper
 - (and any other rihal-* agent in installed_agents)
 

package/rihal/workflows/discuss-phase-power.md

@@ -12,13 +12,13 @@ Power user mode for discuss-phase. Generates ALL questions upfront into a JSON s
 If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 
 ```
-/rihal:discuss-phase-power <argument-here>
+/rihal:discuss-phase --power <argument-here>
 ```
 
 **Examples:**
 ```
-/rihal:discuss-phase-power example 1
-/rihal:discuss-phase-power example 2
+/rihal:discuss-phase --power example 1
+/rihal:discuss-phase --power example 2
 ```
 
 STOP — do not proceed.

package/rihal/workflows/do.md

@@ -274,7 +274,7 @@ Evaluate `$QUESTION` against these routing rules. Apply the **first matching** r
 | A bug, error, crash, failure, or something broken | `/rihal:debug` | Needs systematic investigation |
 | Validate an idea, "working backwards", "press release", "PRFAQ", "is this worth building" | `/rihal:prfaq` | Stress-test concept before committing sprint capacity |
 | Brainstorm, generate ideas, "explore options", "what could we do" | `/rihal:brainstorm` | Structured ideation before planning |
-| Audit code quality, "review changes", "karpathy", "check my diff", "too complex" | `/rihal:karpathy-audit` | 4-principle code audit against recent diff |
+| Audit code quality, "review changes", "karpathy", "check my diff", "too complex" | `/rihal:code-review --karpathy` | 4-principle code audit against recent diff |
 | Walk through a change, "checkpoint", "explain this diff", "human review" | `/rihal:checkpoint-preview` | Human-in-the-loop diff walkthrough |
 | Exploring, researching, comparing, or "how does X work" | `/rihal:research-phase` | Domain research before planning |
 | Scope unclear, conflicting UIs/options, "which one", "better UX", "still have confusion", "how should X look", brainstorming vision | `/rihal:discuss-phase` | Decisions not yet locked — gather before planning |

package/rihal/workflows/docs-update.md

@@ -6,7 +6,7 @@ Generate, update, and verify project documentation — both canonical doc types
 
 <available_agent_types>
 Valid Rihal subagent types (use exact names — do not fall back to 'general-purpose'):
-- rihal-tech-writer — Writes and updates project documentation files
+- rihal-noor — Writes and updates project documentation files
 - rihal-docs-auditor — Verifies factual claims in docs against the live codebase
 </available_agent_types>
 
@@ -40,7 +40,7 @@ test -d docs || mkdir -p docs
 # Read agent manifest to get model for doc writers
 AGENT_MANIFEST=".rihal/_config/agent-manifest.csv"
 if [[ -f "$AGENT_MANIFEST" ]]; then
-  DOC_WRITER_MODEL=$(grep -i "rihal-tech-writer" "$AGENT_MANIFEST" | cut -d',' -f3)
+  DOC_WRITER_MODEL=$(grep -i "rihal-noor" "$AGENT_MANIFEST" | cut -d',' -f3)
 else
   DOC_WRITER_MODEL="claude-opus"  # fallback
 fi
@@ -151,11 +151,11 @@ Create output directories:
 mkdir -p docs
 ```
 
-For each doc in the queue, spawn a `rihal-tech-writer` agent in parallel waves (up to 3 agents in parallel per wave):
+For each doc in the queue, spawn a `rihal-noor` agent in parallel waves (up to 3 agents in parallel per wave):
 
 ```
 Task(
-  subagent_type="rihal-tech-writer",
+  subagent_type="rihal-noor",
   prompt="
 Generate documentation for {doc_type}.
 Output path: {resolved_path}

package/rihal/workflows/execute.md

@@ -507,11 +507,17 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
        </worktree_branch_check>
 
        <parallel_execution>
-       You are running as a PARALLEL executor agent. Use --no-verify on all git
-       commits to avoid pre-commit hook contention with other agents. The
-       orchestrator validates hooks once after all agents complete.
-       For rihal-tools commits: add --no-verify flag.
-       For direct git commits: use git commit --no-verify -m "..."
+       You are running as a PARALLEL executor agent. To avoid pre-commit hook
+       contention with other agents, acquire a file-based lock before each
+       commit and release it immediately after:
+
+         while ! mkdir .rihal/.commit-lock 2>/dev/null; do sleep 0.5; done
+         git commit -m "..."           # hooks run normally
+         rmdir .rihal/.commit-lock
+
+       Hooks run as designed for every commit. AGENTS.md forbids --no-verify;
+       hook failures must be fixed at the source, not bypassed. The orchestrator
+       still validates state once after all agents complete.
        </parallel_execution>
 
        <execution_context>
@@ -1291,6 +1297,56 @@ Also: `/rihal:verify-work {X} ${Rihal_WS}` — manual testing first
 Gap closure cycle: `/rihal:plan {X} --gaps ${Rihal_WS}` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/rihal:execute {X} --gaps-only ${Rihal_WS}` → verifier re-runs.
 </step>
 
+<step name="uat_gate" priority="blocker">
+**UAT gate (added in v3.1.0 after #443 / #448):**
+
+Before marking the phase complete, verify a passing VERIFICATION.md exists for this phase. Without it, the phase advances to `status: executed` (work done, awaiting verification) — not `status: complete`.
+
+```bash
+VERIFICATION_FILE=$(ls "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1)
+
+if [ -z "$VERIFICATION_FILE" ]; then
+  VERIFICATION_STATUS="missing"
+elif grep -q "^status:\s*pass\b" "$VERIFICATION_FILE" 2>/dev/null; then
+  VERIFICATION_STATUS="pass"
+elif grep -q "^status:\s*fail\b" "$VERIFICATION_FILE" 2>/dev/null; then
+  VERIFICATION_STATUS="fail"
+else
+  VERIFICATION_STATUS="indeterminate"
+fi
+```
+
+**If `VERIFICATION_STATUS` is `missing` or `indeterminate`:**
+
+1. Mark the phase as `status: executed` (NOT `complete`) via:
+   ```bash
+   node ".rihal/bin/rihal-tools.cjs" phase set-status "${PHASE_NUMBER}" executed
+   ```
+2. Print the mandatory UAT checklist:
+   ```
+   ⚠ Phase {X} EXECUTED but not yet verified.
+
+   The following acceptance criteria require human verification before
+   the phase can advance to `status: complete`:
+
+   {list AC items from SPRINT.md}
+
+   Run /rihal:verify-work {X} to perform UAT and produce VERIFICATION.md.
+   /rihal:next will refuse to advance until this gate passes.
+   ```
+3. STOP the workflow. Do NOT proceed to `update_roadmap`. Do NOT call `phase complete`.
+
+**If `VERIFICATION_STATUS` is `fail`:**
+
+1. Mark the phase as `status: executed` (so /rihal:plan --gaps can run a closure cycle).
+2. Surface the failed AC items.
+3. STOP. Don't mark complete on a failing verification.
+
+**Only when `VERIFICATION_STATUS` is `pass`** — proceed to `update_roadmap` below.
+
+The previous behaviour (printing "Next Up: /rihal:verify-work" without state-gating) caused phases to reach `status: complete` without any human-verified UAT — see #443 for the failure mode.
+</step>
+
 <step name="update_roadmap">
 **Mark phase complete and update all tracking files:**
 

package/rihal/workflows/help.md

@@ -174,18 +174,18 @@ init → new-project → plan → execute → next → status → ship
 | `/rihal:add-tests <n>` | Generate unit + E2E tests based on SPRINT/SUMMARY/CONTEXT. |
 | `/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:karpathy-audit` | Audit recent code against Karpathy's 4 LLM coding principles. |
+| `/rihal:code-review --karpathy` | Audit recent code against Karpathy's 4 LLM coding principles. |
 | `/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:review-adversarial` | Hostile-perspective report — vulnerabilities, race conditions, abuse. |
-| `/rihal:review-edge-case-hunter` | Enumerate edge cases by category and severity. |
+| `/rihal:code-review --attack` | Hostile-perspective report — vulnerabilities, race conditions, abuse. |
+| `/rihal:code-review --edge-cases` | Enumerate edge cases by category and severity. |
 | `/rihal:review` | Cross-AI peer review — invoke external AI CLIs to review plans. |
 
 ## Council variants & strategy power tools
 
 | Command | Use |
 |---------|-----|
-| `/rihal:discuss-phase-power` | Bulk question generation with async UI for context-heavy phases. |
+| `/rihal:discuss-phase --power` | Bulk question generation with async UI for context-heavy phases. |
 | `/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. |
@@ -213,7 +213,7 @@ init → new-project → plan → execute → next → status → ship
 | `/rihal:create-epics-and-stories` | Parse a PRD into numbered epic + story files. |
 | `/rihal:create-story` | Prepare a dev-ready STORY.md with full implementation context. |
 | `/rihal:dev-story <file>` | Execute an approved STORY by writing tests + code per AC. |
-| `/rihal:check-implementation-readiness` | Verify PRD + architecture + epics aligned before build. |
+| (internal) `check-implementation-readiness` | Guard called by `/rihal:plan` and `/rihal:execute` to verify PRD + architecture aligned before build. |
 | `/rihal:create-architecture` | Write an Architecture Decision Record (ADR). |
 | `/rihal:create-ux-design` | Realize a UX design that informs architecture and implementation. |
 | `/rihal:correct-course` | Course-correct mid-sprint when major change is discovered. |

package/rihal/workflows/karpathy-audit.md

@@ -14,15 +14,15 @@ If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 
 **Usage:**
 ```
-/rihal:karpathy-audit <phase> [--files=path1,path2]
-/rihal:karpathy-audit <git-ref>..HEAD
+/rihal:code-review --karpathy <phase> [--files=path1,path2]
+/rihal:code-review --karpathy <git-ref>..HEAD
 ```
 
 **Examples:**
 ```
-/rihal:karpathy-audit 03
-/rihal:karpathy-audit 02 --files=src/
-/rihal:karpathy-audit HEAD~5..HEAD
+/rihal:code-review --karpathy 03
+/rihal:code-review --karpathy 02 --files=src/
+/rihal:code-review --karpathy HEAD~5..HEAD
 ```
 
 <process>
@@ -44,7 +44,7 @@ Parse: `phase_found`, `phase_dir`, `phase_number`, `padded_phase`.
 
 If phase_found is false:
 ```
-Error: Phase ${PHASE_ARG} not found. Try /rihal:karpathy-audit HEAD~5..HEAD to audit recent commits instead.
+Error: Phase ${PHASE_ARG} not found. Try /rihal:code-review --karpathy HEAD~5..HEAD to audit recent commits instead.
 ```
 
 If git ref format (contains ".." or has no digit at start):
@@ -343,7 +343,7 @@ Aggregate all findings into a structured report:
 ---
 
 **Generated:** {date}
-**Run:** /rihal:karpathy-audit {original_arguments}
+**Run:** /rihal:code-review --karpathy {original_arguments}
 ```
 
 Write report to stdout and optionally to file `{phase_dir}/{padded_phase}-KARPATHY-AUDIT.md` if phase mode.
@@ -375,7 +375,7 @@ Review the full report above. Use /rihal:code-review-fix to auto-fix some issues
 **Next steps:**
 ```
 View full report: {report file path}
-Rerun: /rihal:karpathy-audit {arguments}
+Rerun: /rihal:code-review --karpathy {arguments}
 Auto-fix some issues: /rihal:code-review-fix {phase}
 ```
 </step>
@@ -395,7 +395,7 @@ Auto-fix some issues: /rihal:code-review-fix {phase}
 
 ## On Error
 
-- **Phase not found:** suggest `/rihal:karpathy-audit HEAD~5..HEAD` as the git-ref fallback.
+- **Phase not found:** suggest `/rihal:code-review --karpathy HEAD~5..HEAD` as the git-ref fallback.
 - **No source files in diff:** report "no auditable changes in range" and STOP — do not invent findings.
 - **karpathy-guidelines.md missing:** print "Reference doc missing. Run: npx @hanzlaa/rcode install ." and STOP.
 - **Empty diff:** STOP gracefully, do not run principle checks against an empty input.

package/rihal/workflows/memory-audit.md

@@ -0,0 +1,83 @@
+# Workflow: rcode-memory-audit
+
+Read-only audit of the Memory Bank. Produces a severity-tagged report. Never modifies files.
+
+---
+
+## Inputs
+
+None required. Optional `--severity {critical|warn|info}` to filter output.
+
+## Preconditions
+
+- `.rihal/memory/INDEX.md` exists
+
+## Halt conditions
+
+- Memory Bank not initialised → instruct to run `/rcode:memory-init` first
+
+---
+
+## Steps
+
+### Step 1 — Catalogue files
+
+Walk `.rihal/memory/` and build a list of every file plus its size and modification time. Include `.gitkeep` files for empty-subdir detection.
+
+### Step 2 — Check 1: Stale milestone
+
+Read `milestones/current.md`. Parse the "Target close" date. If `(today - target_close).days >= 30`, emit a `warn` finding.
+
+### Step 3 — Check 2: Resolved issues lingering
+
+For each entry in `incidents/known-issues.md`:
+- Parse "Real fix planned for" field
+- If it names a milestone that has been moved to `milestones/archive/`, emit a `warn` finding
+
+### Step 4 — Check 3: Template placeholders unfilled
+
+For each `*.md` file under `.rihal/memory/`:
+- Count occurrences of `{{` literally (template placeholders)
+- Count occurrences of `_(e.g.` (italicised template hints)
+- If either is non-zero, emit an `info` finding listing the file and count
+
+### Step 5 — Check 4: Stack vs decisions contradiction
+
+For each decision entry in `project/decisions.md` that mentions a technology name:
+- Extract candidate tech terms (proper nouns, capitalised + version)
+- Search `project/stack.md` for the term
+- If not found, emit a `critical` finding
+
+### Step 6 — Check 5: Empty subdirectories
+
+For `change-records/`, `incidents/post-mortems/`, `milestones/archive/`:
+- If only file is `.gitkeep`, emit an `info` finding (not a problem, just visibility)
+
+### Step 7 — Check 6: Distillate freshness
+
+For each `distillates/*.distillate.md`:
+- Read frontmatter `source-digest`
+- Recompute digest of current source files (per `rcode-memory-distill` rules)
+- If mismatch, emit a `warn` finding suggesting `/rcode:memory-distill`
+
+### Step 8 — Render report
+
+Group findings by severity (critical → warn → info), then by file within each severity group. For each finding, print:
+- File path
+- One-line description
+- One-line `Fix:` suggestion (which skill to run, or manual action)
+
+If `--severity` filter passed, hide findings below the threshold.
+
+If zero findings: print `✓ Memory Bank is healthy. 0 findings.`
+
+---
+
+## Post-conditions
+
+- No files modified
+- Report printed to stdout
+
+## Reversibility
+
+Read-only — no state to revert.

package/rihal/workflows/memory-distill.md

@@ -0,0 +1,103 @@
+# Workflow: rcode-memory-distill
+
+Regenerate Memory Bank distillates with lossless compression. Idempotent.
+
+---
+
+## Inputs
+
+- `--force` (optional) — regenerate even when source files are unchanged
+- `--target {project|stack|all}` (optional, default `all`) — limit which distillate to regenerate
+
+## Preconditions
+
+- `.rihal/memory/` exists
+- `.rihal/memory/distillates/` exists (created by `rcode-memory-init`)
+
+## Halt conditions
+
+- `.rihal/memory/` missing → instruct to run `/rcode:memory-init` first
+- All sources empty (only template placeholders) → warn and exit; no point distilling empty content
+
+---
+
+## Steps
+
+### Step 1 — Resolve source set
+
+For `target = project`:
+- `project/stack.md`, `project/decisions.md`, `project/glossary.md`
+- `people/stakeholders.md`, `people/team.md`
+- `milestones/current.md`
+- `incidents/known-issues.md`
+
+For `target = stack`:
+- `project/stack.md` only
+
+### Step 2 — Compute digest
+
+```
+digest = sha1(concat(file_path + ":" + mtime for each source file in sorted order))
+```
+
+If `--force` not passed and existing distillate's `source-digest:` matches, skip regeneration for that target.
+
+### Step 3 — Compress per target
+
+For each target's source set:
+
+1. Read all source files
+2. Extract: facts, decisions, constraints, relationships, named entities, dates
+3. Produce a dense markdown document organised by topic (not by source file)
+4. Strip overhead: pleasantries, redundant headings, examples that don't add new facts, template placeholders that weren't filled
+5. Preserve: every concrete claim, every decision, every link, every name, every date
+
+Compression target: ~30% of source token count. If output is larger, the source had a lot of substance and that's fine.
+
+### Step 4 — Losslessness check
+
+Walk each source file and confirm every "fact" (sentence containing a name, date, decision, or technical term) appears in the distillate either verbatim or via a directly-equivalent phrase. List any potential drops as warnings; user can `--force` past warnings if confident.
+
+### Step 5 — Write output
+
+For each target distillate, write:
+
+```markdown
+---
+generated: true
+do-not-edit: true
+regenerate-with: /rcode:memory-distill
+source-digest: <hash>
+generated-at: <ISO datetime>
+source-files:
+  - project/stack.md
+  - project/decisions.md
+  ...
+token-estimate: <approximate>
+---
+
+# Project Distillate — <project-name>
+
+<compressed content>
+```
+
+### Step 6 — Summary
+
+Print per-target:
+- Source file count
+- Output token estimate
+- Digest
+- Skip notice (if no-op)
+
+---
+
+## Post-conditions
+
+- `distillates/project.distillate.md` updated (if target includes project)
+- `distillates/stack.distillate.md` updated (if target includes stack)
+- Frontmatter `source-digest` matches the current source set
+- No source files modified
+
+## Reversibility
+
+Distillates are derived artefacts. Reverting a regeneration: `git checkout .rihal/memory/distillates/`.

package/rihal/workflows/memory-init.md

@@ -0,0 +1,102 @@
+# Workflow: rcode-memory-init
+
+Bootstraps the rcode Memory Bank in the current project. Idempotent — re-running on an initialised project switches to a gap report instead of overwriting.
+
+---
+
+## Inputs
+
+- **Project root** — current working directory; must contain a `.rihal/` folder (created by `rcode install`)
+- **Templates source** — `.rihal/templates/memory/` (copied from `rihal/templates/memory/` on install)
+
+## Preconditions
+
+- `.rihal/` exists (rcode is installed in this project)
+- `.rihal/templates/memory/` exists (templates ship with rcode)
+
+## Halt conditions
+
+- `.rihal/` missing → ask user to run `npx @hanzlaa/rcode install` first, then halt.
+- `.rihal/templates/memory/` missing → report bug, halt.
+- User cancels at any question → leave `.rihal/memory/` partially populated (whatever was seeded) and exit cleanly.
+
+---
+
+## Steps
+
+### Step 1 — Detect existing Memory Bank
+
+```bash
+if [ -f ".rihal/memory/INDEX.md" ]; then
+  # Switch to gap-report mode
+  exit_with_gap_report
+fi
+```
+
+If `INDEX.md` exists:
+- List every file under `.rihal/memory/`
+- For each, count non-template lines (lines that don't start with `<!--` or contain `_(...)_` placeholders)
+- Print which files are empty / template-only and which are populated
+- Suggest `/rcode:memory-update` for surgical edits and exit
+
+### Step 2 — Copy templates
+
+```bash
+mkdir -p .rihal/memory
+cp -R .rihal/templates/memory/. .rihal/memory/
+```
+
+Preserves the directory structure. Includes `.gitkeep` files in empty subdirs.
+
+### Step 3 — Substitute placeholders
+
+Replace in every `*.md` file under `.rihal/memory/`:
+- `{{PROJECT_NAME}}` → derived from `package.json` `name`, fallback to directory basename
+- `{{INIT_DATE}}` → today's date in `YYYY-MM-DD` format
+
+### Step 4 — Five init questions
+
+Ask each via AskUserQuestion. Accept short answers; do not push for paragraphs.
+
+**Q1.** What is the one-sentence project goal? *(saved to `milestones/current.md` → Goal)*
+
+**Q2.** Primary stack — frontend / backend / database? *(parsed into `project/stack.md` Runtime table)*
+
+**Q3.** What is the current milestone name? *(saved to `milestones/current.md` → Milestone Name; default `M1 — Initial`)*
+
+**Q4.** Primary external stakeholder name and role? *(appended to `people/stakeholders.md`)*
+
+**Q5.** Any known production issue you'd warn a new teammate about today? *(appended to `incidents/known-issues.md`; "none" is acceptable)*
+
+### Step 5 — Update state.json
+
+Add or update the `memory_bank` block in `.rihal/state.json`:
+
+```json
+{
+  "memory_bank": {
+    "initialised_at": "<ISO datetime>",
+    "version": 1
+  }
+}
+```
+
+### Step 6 — Print summary
+
+Show:
+- File tree of `.rihal/memory/`
+- Files seeded vs files still empty
+- Suggested next command: `/rcode:memory-distill`
+
+---
+
+## Post-conditions
+
+- `.rihal/memory/INDEX.md` exists with project name + date filled in
+- 4–5 of the seeded files have user-supplied content
+- `.rihal/state.json` records initialisation
+- The Diwan dashboard `/memory` route now renders content (Phase 3 dashboard work)
+
+## Reversibility
+
+Removing a botched init: `rm -rf .rihal/memory/` and `git checkout -- .rihal/state.json`. No external side effects.

package/rihal/workflows/memory-update.md

@@ -0,0 +1,83 @@
+# Workflow: rcode-memory-update
+
+Append-only surgical update to a single Memory Bank file. Never rewrites, never deletes.
+
+---
+
+## Inputs
+
+- **content** — the thing to remember, in plain English
+- **target** (optional) — explicit file path; if omitted, auto-detected from content
+
+## Preconditions
+
+- `.rihal/memory/` exists (run `/rcode:memory-init` first)
+
+## Halt conditions
+
+- `.rihal/memory/` missing → instruct user to init first
+- User asks to *change* (not append) an existing entry → refuse, redirect to direct file edit
+- Detected target file does not exist → report and halt (don't create new files in this workflow)
+
+---
+
+## Steps
+
+### Step 1 — Auto-detect target
+
+Match keywords in the user's content against this routing table:
+
+| Signal | Target |
+|---|---|
+| "decision", "we chose", "ADR", "decided" | `project/decisions.md` |
+| "bug", "issue", "broken", "workaround" | `incidents/known-issues.md` |
+| "stakeholder", "client", "contact", "rep" | `people/stakeholders.md` |
+| "milestone", "sprint", "phase", "blocker" | `milestones/current.md` |
+| "stack", "framework", "library", "switched to" | `project/stack.md` |
+| "term", "glossary", "what does X mean" | `project/glossary.md` |
+| "team", "who owns", "engineer", "responsibility" | `people/team.md` |
+| "change record", "deployment", "rollback" | `change-records/` (creates new file) |
+
+If ambiguous, ask the user to pick from the top 2 candidates.
+
+### Step 2 — Confirm with user
+
+Show:
+- Target file path
+- Proposed entry, formatted to match the file's existing entry style
+- A "Apply / cancel / edit format" choice
+
+### Step 3 — Append
+
+For appendable files (`decisions.md`, `known-issues.md`, `stakeholders.md`, `team.md`, `glossary.md`):
+- Insert above the `<!-- Append new entries above this line -->` marker if present
+- Otherwise append to end of file with a blank line separator
+
+For `milestones/current.md`:
+- Allow only field-level updates (Goal, Active phase, Blockers, Recent decisions)
+- Replace the field's value, not the whole file
+
+For `change-records/`:
+- Create a new file `YYYYMMDD-NNN.md` where `NNN` is the next sequence number
+- Use the change-record template format
+
+### Step 4 — Stamp and verify
+
+- Add `YYYY-MM-DD` date (today, ISO format) to every appended entry
+- Print a diff preview (last 20 lines of the file) so the user can confirm the change landed
+
+### Step 5 — Suggest distillate refresh
+
+If the change was to `project/`, `milestones/current.md`, or `incidents/`, suggest `/rcode:memory-distill` to refresh distillates. Optional, not enforced.
+
+---
+
+## Post-conditions
+
+- Exactly one file changed (or one new change-record file created)
+- File still parses as valid markdown
+- No content removed
+
+## Reversibility
+
+`git diff .rihal/memory/` shows exactly one append — easy to revert with `git checkout`.