@hanzlaa/rcode 2.1.0

package/rihal/workflows/undo.md

@@ -0,0 +1,426 @@
+<purpose>
+Safe git revert workflow. Rolls back Rihal phase or plan commits using the phase manifest with dependency checks and a confirmation gate. Uses git revert --no-commit (NEVER git reset) to preserve history.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:undo <argument-here>
+```
+
+**Examples:**
+```
+/rihal:undo example 1
+/rihal:undo example 2
+```
+
+STOP — do not proceed.
+
+<required_reading>
+@.rihal/references/ui-brand.md
+@.rihal/references/gate-prompts.md
+</required_reading>
+
+<process>
+
+<step name="banner" priority="first">
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Rihal ► UNDO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="parse_arguments">
+Parse $ARGUMENTS for the undo mode:
+
+- `--last N` → MODE=last, COUNT=N (integer, default 10 if N missing)
+- `--phase NN` → MODE=phase, TARGET_PHASE=NN (two-digit phase number)
+- `--plan NN-MM` → MODE=plan, TARGET_PLAN=NN-MM (phase-plan ID)
+- `--to-snapshot` → TO_SNAPSHOT=true (only combines with `--phase NN`). Uses the pre-execution git tag `rihal/snapshot/phase-NN` to determine the full commit range to revert — guaranteed to restore exact pre-execution state regardless of manifest accuracy.
+
+If no valid argument is provided, display usage and exit:
+
+```
+Usage: /rihal:undo --last N | --phase NN [--to-snapshot] | --plan NN-MM
+
+Modes:
+  --last N              Show last N Rihal commits for interactive selection
+  --phase NN            Revert all commits for phase NN (uses manifest, fallback to git log)
+  --phase NN --to-snapshot
+                        Revert every commit between rihal/snapshot/phase-NN and HEAD —
+                        exact restore to the pre-execution tag created by /rihal:execute
+  --plan NN-MM          Revert all commits for plan NN-MM
+
+Examples:
+  /rihal:undo --last 5
+  /rihal:undo --phase 03
+  /rihal:undo --phase 03 --to-snapshot
+  /rihal:undo --plan 03-02
+```
+
+</step>
+
+<step name="confirmation_gate" priority="safety">
+**SAFETY GATE — This is a destructive operation. Confirmation is mandatory.**
+
+Before gathering any commits, display:
+
+```
+⚠  UNDO is destructive — commits will be reverted via git revert --no-commit.
+
+Unsure what will be reverted? Run first:
+
+/rihal:undo --last 5
+
+to preview the last 5 Rihal commits before choosing.
+```
+
+Use AskUserQuestion with explicit confirmation:
+
+```
+AskUserQuestion(
+  header: "Confirm Undo",
+  question: "Proceed with undo operation?",
+  options: [
+    { label: "Preview first", description: "Show what will be reverted" },
+    { label: "Proceed", description: "Continue with undo" },
+    { label: "Cancel", description: "Abort" }
+  ]
+)
+```
+
+**If "Cancel":** display "Undo cancelled. No changes made." and exit.
+
+**If "Preview first":** temporarily switch MODE to `last` with COUNT=5, gather and display commits (do NOT confirm-revert yet), then re-ask this gate.
+
+**If "Proceed":** continue to gather_commits.
+
+</step>
+
+<step name="gather_commits">
+Based on MODE, gather candidate commits.
+
+**MODE=last:**
+
+Run:
+```bash
+git log --oneline --no-merges -${COUNT}
+```
+
+Filter for Rihal conventional commits matching `type(scope): message` pattern (e.g., `feat(04-01):`, `docs(03):`, `fix(02-03):`).
+
+Display a numbered list of matching commits:
+```
+Recent Rihal commits:
+  1. abc1234 feat(04-01): implement auth endpoint
+  2. def5678 docs(03-02): complete plan summary
+  3. ghi9012 fix(02-03): correct validation logic
+```
+
+Use AskUserQuestion to ask:
+- question: "Which commits to revert? Enter numbers (e.g., 1,3) or 'all'"
+- header: "Select"
+
+Parse the user's selection into COMMITS list.
+
+---
+
+**MODE=phase:**
+
+**If `TO_SNAPSHOT` is true:**
+
+```bash
+SNAPSHOT_TAG="rihal/snapshot/phase-${TARGET_PHASE}"
+if ! git rev-parse --verify "refs/tags/${SNAPSHOT_TAG}" >/dev/null 2>&1; then
+  cat <<EOF
+No snapshot tag found: ${SNAPSHOT_TAG}
+
+Snapshots are created automatically when /rihal:execute runs for a phase.
+Options:
+  - Drop --to-snapshot and use manifest/git-log fallback:   /rihal:undo --phase ${TARGET_PHASE}
+  - Re-run /rihal:execute <phase> to create a snapshot for future undo
+EOF
+  exit 0
+fi
+
+mapfile -t COMMITS < <(git log --pretty=format:%H --no-merges "${SNAPSHOT_TAG}..HEAD")
+```
+
+If the range is empty (HEAD is already at the snapshot):
+```
+Nothing to revert — HEAD already matches ${SNAPSHOT_TAG}.
+```
+Exit cleanly. Skip the rest of this step.
+
+Otherwise set `SNAPSHOT_SHA=$(git rev-parse --short "${SNAPSHOT_TAG}")` for use in the confirm_revert preview (display the target SHA).
+
+---
+
+**If `TO_SNAPSHOT` is false (default):**
+
+Read `.planning/.phase-manifest.json` if it exists.
+
+If the file exists and `manifest.phases?.[TARGET_PHASE]?.commits` is a non-empty array:
+  - Use `manifest.phases[TARGET_PHASE].commits` entries as COMMITS (each entry is a commit hash)
+
+If the file does not exist, or `manifest.phases?.[TARGET_PHASE]` is missing:
+  - Display: "Manifest has no entry for phase ${TARGET_PHASE} (or file missing), falling back to git log search"
+  - Fallback: run git log and filter for the target phase scope:
+    ```bash
+    git log --oneline --no-merges --all | grep -E "\(0*${TARGET_PHASE}(-[0-9]+)?\):" | head -50
+    ```
+  - Use matching commits as COMMITS
+
+---
+
+**MODE=plan:**
+
+Run:
+```bash
+git log --oneline --no-merges --all | grep -E "\(${TARGET_PLAN}\)" | head -50
+```
+
+Use matching commits as COMMITS.
+
+---
+
+**Empty check:**
+
+If COMMITS is empty after gathering:
+```
+No commits found for ${MODE} ${TARGET}. Nothing to revert.
+```
+Exit cleanly.
+</step>
+
+<step name="dependency_check">
+**Applies when MODE=phase or MODE=plan.**
+
+Skip this step entirely for MODE=last.
+
+---
+
+**MODE=phase:**
+
+Read `.planning/ROADMAP.md` inline.
+
+Search for phases that list a dependency on the target phase. Look for patterns like:
+- "Depends on: Phase ${TARGET_PHASE}"
+- "Depends on: ${TARGET_PHASE}"
+- "depends_on: [${TARGET_PHASE}]"
+
+For each dependent phase N found:
+1. Check if `.planning/phases/${N}-*/` directory exists
+2. If directory exists, check for any SPRINT.md or SUMMARY.md files inside it
+
+If any downstream phase has started work, collect warnings:
+```
+⚠  Downstream dependency detected:
+   Phase ${N} depends on Phase ${TARGET_PHASE} and has started work.
+```
+
+---
+
+**MODE=plan:**
+
+Extract the phase number from TARGET_PLAN (the NN part of NN-MM). Extract the plan number (the MM part).
+
+Look for later plans in the same phase directory (`.planning/phases/${NN}-*/`). For each later plan (plans with number > MM):
+1. Read the later plan's SPRINT.md
+2. Check if its `<files>` sections or `consumes` fields reference outputs from the target plan
+3. Also scan later plan's frontmatter for `depends_on:` field matching the target plan ID
+
+If any later plan references the target plan's outputs, collect warnings:
+```
+⚠  Intra-phase dependency detected:
+   Plan ${LATER_PLAN} in phase ${NN} references outputs from plan ${TARGET_PLAN}.
+```
+
+---
+
+If any warnings exist (from either mode):
+- Display all warnings
+- Use AskUserQuestion with approve-revise-abort pattern:
+  - question: "Downstream work depends on the target being reverted. Proceed anyway?"
+  - header: "Confirm"
+  - options: Proceed | Abort
+
+If user selects "Abort": exit with "Revert cancelled. No changes made."
+</step>
+
+<step name="confirm_revert">
+Display the confirmation gate using approve-revise-abort pattern from gate-prompts.md.
+
+Show:
+```
+The following commits will be reverted (in reverse chronological order):
+
+  {hash} — {message}
+  {hash} — {message}
+  ...
+
+Total: {N} commit(s) to revert
+```
+
+Use AskUserQuestion:
+- question: "Proceed with revert?"
+- header: "Approve?"
+- options: Approve | Abort
+
+If "Abort": display "Revert cancelled. No changes made." and exit.
+If "Approve": ask for a reason:
+
+```
+AskUserQuestion(
+  header: "Reason",
+  question: "Brief reason for the revert (used in commit message):",
+  options: []
+)
+```
+
+Store the response as REVERT_REASON. Continue to execute_revert.
+</step>
+
+<step name="execute_revert">
+**HARD CONSTRAINT: Use git revert --no-commit. NEVER use git reset (except for conflict cleanup as documented below).**
+
+**Dirty-tree guard (run first, before any revert):**
+
+Run `git status --porcelain`. If the output is non-empty, display the dirty files and abort:
+```
+Working tree has uncommitted changes. Commit or stash them before running /rihal:undo.
+```
+Exit immediately — do not proceed to any revert operations.
+
+---
+
+Sort COMMITS in reverse chronological order (newest first). If commits came from git log (already newest-first), they are already in correct order.
+
+For each commit hash in COMMITS:
+```bash
+git revert --no-commit ${HASH}
+```
+
+If any revert fails (merge conflict or error):
+1. Display the error message
+2. Run cleanup — handle both first-call and mid-sequence cases:
+   ```bash
+   # Try git revert --abort first (works if this is the first failed revert)
+   git revert --abort 2>/dev/null
+   # If prior --no-commit reverts already staged cleanly before this failure,
+   # revert --abort may be a no-op. Clean up staged and working tree changes:
+   git reset HEAD 2>/dev/null
+   git restore . 2>/dev/null
+   ```
+3. Display:
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  ERROR                                                       ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Revert failed on commit ${HASH}.
+   Likely cause: merge conflict with subsequent changes.
+
+   **To fix:** Resolve the conflict manually or revert commits individually.
+   All pending reverts have been aborted — working tree is clean.
+   ```
+4. Exit with error.
+
+After all reverts are staged successfully, create a single commit:
+
+For MODE=phase (default):
+```bash
+git commit -m "revert(${TARGET_PHASE}): undo phase ${TARGET_PHASE} — ${REVERT_REASON}"
+```
+
+For MODE=phase with `--to-snapshot`:
+```bash
+git commit -m "revert(${TARGET_PHASE}): restore phase ${TARGET_PHASE} to snapshot ${SNAPSHOT_SHA} — ${REVERT_REASON}"
+```
+
+For MODE=plan:
+```bash
+git commit -m "revert(${TARGET_PLAN}): undo plan ${TARGET_PLAN} — ${REVERT_REASON}"
+```
+
+For MODE=last:
+```bash
+git commit -m "revert: undo ${N} selected commits — ${REVERT_REASON}"
+```
+</step>
+
+<step name="summary">
+Display the completion banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Rihal ► UNDO COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show summary:
+```
+  ✓ ${N} commit(s) reverted
+  ✓ Single revert commit created: ${REVERT_HASH}
+```
+
+Show next steps:
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Review state** — verify project is in expected state after revert
+
+/clear then:
+
+/rihal:progress
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/rihal:execute ${PHASE}` — re-execute if needed
+- `/rihal:undo --last 1` — undo the revert itself if something went wrong
+
+───────────────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Arguments parsed correctly for all three modes
+- [ ] --phase mode reads .planning/.phase-manifest.json using manifest.phases[TARGET_PHASE].commits
+- [ ] --phase mode falls back to git log if manifest entry missing
+- [ ] --phase --to-snapshot uses rihal/snapshot/phase-NN tag and reverts ${TAG}..HEAD
+- [ ] --to-snapshot exits cleanly when the snapshot tag is missing (no surprise no-op)
+- [ ] Dependency check warns when downstream phases have started (MODE=phase)
+- [ ] Dependency check warns when later plans reference target plan outputs (MODE=plan)
+- [ ] Dirty-tree guard aborts if working tree has uncommitted changes
+- [ ] Confirmation gate shown before any revert execution
+- [ ] Reverts use git revert --no-commit in reverse chronological order
+- [ ] Single commit created after all reverts staged
+- [ ] Error handling cleans up both first-call and mid-sequence conflict cases
+- [ ] git reset --hard is NEVER used anywhere in this workflow
+</success_criteria>
+
+## Success Criteria
+
+- [ ] Task completed as requested
+- [ ] Output saved or reported
+- [ ] State updated if necessary
+- [ ] No errors encountered
+
+## On Error
+
+If arguments are invalid, missing files, or subagent fails:
+- Validate inputs match expected format
+- Check that required files exist
+- Retry with clearer arguments or report the specific error to the user
+

package/rihal/workflows/update.md

@@ -0,0 +1,185 @@
+# Workflow: rihal:update
+
+<purpose>
+Detect package updates for rihal-code by comparing installed file hashes against source package hashes. Show changelog (added/changed/removed files), ask user confirmation, then run installer with --force --yes if approved.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:update <argument-here>
+```
+
+**Examples:**
+```
+/rihal:update example 1
+/rihal:update example 2
+```
+
+STOP — do not proceed.
+
+## Step 1 — Locate installed package
+
+Find the rihal-code package using one of these strategies (in order):
+1. Check `$(npm root -g)/rihal-code/cli/install-v2.js` (global install)
+2. Check `./cli/install-v2.js` (local install)
+3. If neither exists, print:
+   ```
+   ❌ rihal-code package not found. Install with:
+   npm install -g rihal-code
+   ```
+   Exit.
+
+Store the installer path in `$INSTALLER_PATH`.
+
+## Step 2 — Read installed manifest
+
+Read `.rihal/_config/files-manifest.csv` from the current project:
+
+```bash
+cat .rihal/_config/files-manifest.csv
+```
+
+If the file doesn't exist:
+```
+ℹ️ No rihal installation detected in this project.
+Run: node <installer-path> . --force --yes
+```
+Exit.
+
+Parse the CSV (columns: `rel,sha256,size`). Store as `$INSTALLED_HASHES` (map rel → sha256).
+
+## Step 3 — Read source manifest
+
+Run the installer helper to read the source package's file list:
+
+```bash
+node "$INSTALLER_PATH" --list-files 2>/dev/null || echo "[]"
+```
+
+If that flag doesn't exist, walk the source package's `rihal/` directory manually:
+- Find all files in `$(npm root -g)/rihal-code/rihal/` (or local `./rihal/`)
+- Compute SHA256 for each
+- Store as `$SOURCE_HASHES` (map rel → sha256)
+
+## Step 4 — Compute changelog
+
+Compare `$INSTALLED_HASHES` against `$SOURCE_HASHES`:
+
+- **Added:** files in SOURCE but not in INSTALLED
+- **Changed:** files in both with different SHA256
+- **Removed:** files in INSTALLED but not in SOURCE
+
+Count each category. Store results in `$ADDED`, `$CHANGED`, `$REMOVED` (arrays of rel paths).
+
+If all three lists are empty:
+```
+✅ rihal-code is up to date (no changes detected)
+```
+Exit.
+
+## Step 5 — Print changelog
+
+Print a human-readable changelog:
+
+```
+📦 rihal-code Update Available
+
+Added files (3):
+  ✨ rihal/commands/update.md
+  ✨ rihal/workflows/update.md
+  ✨ rihal/commands/stats.md
+
+Changed files (2):
+  🔄 rihal/modules/core.yaml
+  🔄 cli/install-v2.js
+
+Removed files (1):
+  ❌ rihal/references/old-style.md
+
+Total: +3 / ~2 / -1
+```
+
+## Step 6 — Ask user confirmation
+
+Call AskUserQuestion:
+
+```
+Proceed with update?
+
+Options:
+[1] Proceed — Apply update
+[2] Cancel — Skip for now
+[3] Show diff — List all changed files
+```
+
+- If user chooses [3], print full diff (all added/changed/removed file names, 1 per line)
+- Then re-ask the confirmation question
+- If user chooses [1], proceed to Step 7
+- If user chooses [2], print "Update cancelled" and exit
+
+## Step 7 — Apply update
+
+Run the installer with `--force --yes`:
+
+```bash
+node "$INSTALLER_PATH" . --force --yes
+```
+
+If the command exits with non-zero status, print:
+```
+❌ Update failed. Check the output above.
+```
+Exit with error code.
+
+## Step 8 — Pull Rihal brain content (v2.0)
+
+After installer finishes, refresh the brain content from configured sources (issue #158). This is idempotent and safe to re-run.
+
+```bash
+node .rihal/bin/rihal-tools.cjs brain pull
+```
+
+Parse the JSON output. Report counts to the user:
+- `pulled[]` — sources actually fetched (git or in-repo)
+- `skipped[]` — sources with `<PLACEHOLDER>` URLs (waiting on issue #162 / M5)
+- `errors[]` — sources that failed (network, auth, etc.)
+
+If the user passed a version argument (`/rihal:update v1.3.0`), pass it through to `brain pull` as `--version v1.3.0`. When supported, `brain pull` will pin each source to the commit recorded in that release's `sources.yaml`. Unknown versions: treat as latest and warn.
+
+## Step 9 — Success summary
+
+Print:
+
+```
+✅ rihal-code updated successfully
+
+Updated files: N
+  - file-path-1
+  - file-path-2
+  ...
+
+Rihal brain: M sources pulled, K skipped (placeholder URLs)
+
+New version available at: .rihal/
+
+Run /rihal:status to verify installation.
+```
+
+## Success Criteria
+
+- [ ] Task completed as requested
+- [ ] Output saved or reported
+- [ ] State updated if necessary
+- [ ] No errors encountered
+
+## On Error
+
+If arguments are invalid, missing files, or subagent fails:
+- Validate inputs match expected format
+- Check that required files exist
+- Retry with clearer arguments or report the specific error to the user
+