@hanzlaa/rcode 2.2.0 → 2.3.2

package/rihal/workflows/settings.md

@@ -1,185 +1,184 @@
 # Workflow: rihal:settings
 
 <purpose>
-Interactive configuration wizard for Rihal project settings. Collects user preferences for model profile, research strategy, execution gates, and branching strategy, then writes them back to .rihal/config.yaml.
+View and edit Rihal project settings stored in `.rihal/config.yaml`. Closes
+#233 — replaces the previous broken implementation that wrote flat keys
+nothing read and corrupted the nested `workflow:` / `git:` sections on every
+save.
+
+The single source of truth for config keys is the table in Step 1.5. All keys
+documented there are consumed somewhere in the codebase — settings that the
+wizard writes are settings that workflows actually honour.
 </purpose>
 
-
 ## Step 0 — Usage check
 
-If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+If `$ARGUMENTS` contains `--help` or `-h`:
 
 ```
-/rihal:settings <argument-here>
+/rihal:settings              # show current + interactive edit
+/rihal:settings show         # show current only
+/rihal:settings get <key>    # read a single dotted key (e.g. workflow.discuss_mode)
+/rihal:settings set <key> <value>   # write a single dotted key
 ```
 
 **Examples:**
 ```
-/rihal:settings example 1
-/rihal:settings example 2
+/rihal:settings show
+/rihal:settings get workflow.research_by_default
+/rihal:settings set workflow.research_by_default true
+/rihal:settings set git.branching_strategy feature-branch
 ```
 
-STOP — do not proceed.
+## Step 1 — Resolve mode
 
-<available_tools>
-- AskUserQuestion — collect user input
-- Read — read current config.yaml
-- Write — write updated config.yaml
-- Bash — validate git state if needed
-</available_tools>
+Parse `$ARGUMENTS`:
+- `show` (or empty) → run Step 1.5 then Step 2 (interactive)
+- `get <key>` → Step 1.7 then STOP
+- `set <key> <value>` → Step 1.8 then STOP
+- anything else → print usage from Step 0 and STOP
 
-## Step 1 — Initialize
+## Step 1.5 — Show current settings
 
-Load current settings from `.rihal/config.yaml`:
+Read each known key via `rihal-tools.cjs config-get <dotted.key>` (the
+nested-safe reader in `rihal/bin/lib/config.cjs`). **Do not** call the legacy
+`config set` — it uses a flat YAML parser and corrupts nested sections.
 
 ```bash
-[ -f .rihal/config.yaml ] && cat .rihal/config.yaml || echo "# No config yet"
+TOOL="node .rihal/bin/rihal-tools.cjs"
+$TOOL config-get user_name                            || echo "(unset)"
+$TOOL config-get communication_language               || echo "(unset)"
+$TOOL config-get mode                                 || echo "(unset)"
+$TOOL config-get model_profile                        || echo "(unset)"
+$TOOL config-get workflow.research_by_default         || echo "(unset)"
+$TOOL config-get workflow.plan_checker                || echo "(unset)"
+$TOOL config-get workflow.post_execute_gates          || echo "(unset)"
+$TOOL config-get workflow.ui_safety_gate              || echo "(unset)"
+$TOOL config-get workflow.discuss_mode                || echo "(unset)"
+$TOOL config-get git.branching_strategy               || echo "(unset)"
+$TOOL config-get git.commit_docs                      || echo "(unset)"
+$TOOL config-get output.verbose                       || echo "(unset)"
 ```
 
-Parse the config to extract current values:
-- `model_profile` (default: "balanced")
-- `enable_research_pre_step` (default: "false")
-- `enable_plan_checker_loop` (default: "true")
-- `enable_post_execute_verifier` (default: "false")
-- `branching_strategy` (default: "none")
-
-Store these as `current_*` variables for pre-fill use.
-
-## Step 2 — Collect Settings
-
-Use AskUserQuestion to prompt the user for each setting. Pre-fill current values where applicable.
-
-### Setting 1: Model Profile
+Render as a table:
 
 ```
-Question:
-Which model profile would you like to use?
+Current Rihal Settings (.rihal/config.yaml)
 
-Options:
-  1. quality (Opus for reasoning agents, Sonnet for executor, Haiku for utilities)
-  2. balanced (Sonnet across the board) [CURRENT]
-  3. budget (Haiku across the board)
-  4. inherit (Use parent session model, no override)
+  Identity
+    user_name                       : {value}
+    communication_language          : {value}
 
-Your choice: [pre-filled with current_model_profile]
-```
+  Execution
+    mode                            : {value}    # guided | yolo
+    model_profile                   : {value}    # quality | balanced | budget | inherit
 
-Valid responses: 1, 2, 3, 4, or exact names (quality, balanced, budget, inherit).
-Map numeric choices to profile names. Store as `new_model_profile`.
+  Workflow gates
+    workflow.research_by_default    : {value}    # true | false
+    workflow.plan_checker           : {value}    # true | false
+    workflow.post_execute_gates     : {value}    # true | false
+    workflow.ui_safety_gate         : {value}    # true | false
+    workflow.discuss_mode           : {value}    # adaptive | discuss | skip
 
-### Setting 2: Enable Research Pre-step
+  Output
+    output.verbose                  : {value}    # false (slim, default) | true (full detail)
 
+  Git
+    git.branching_strategy          : {value}    # none | feature-branch | worktree-isolation
+    git.commit_docs                 : {value}    # true | false
 ```
-Question:
-Enable research pre-step in /rihal:plan by default?
 
-This runs a research phase before planning if enabled, providing additional context.
+If invoked as `/rihal:settings show`, STOP here.
 
-Options:
-  1. Yes
-  2. No [CURRENT]
+## Step 1.7 — `get <key>`
 
-Your choice:
+```bash
+node .rihal/bin/rihal-tools.cjs config-get "$KEY"
 ```
 
-Valid responses: 1/yes/y or 2/no/n. Store as `new_enable_research_pre_step` (true/false string).
-
-### Setting 3: Enable Plan-Checker Loop
+Print the result (empty output means unset). STOP.
 
-```
-Question:
-Enable sprint-checker loop during /rihal:plan?
+## Step 1.8 — `set <key> <value>`
 
-This verifies and repairs plans before execution if enabled.
+Validate the key against the table in Step 1.5 — reject unknown keys with
+the table printed.
 
-Options:
-  1. Yes [CURRENT]
-  2. No
+Validate the value:
+- `mode` ∈ {guided, yolo}
+- `model_profile` ∈ {quality, balanced, budget, inherit}
+- `workflow.discuss_mode` ∈ {adaptive, discuss, skip}
+- `git.branching_strategy` ∈ {none, feature-branch, worktree-isolation}
+- `workflow.*` booleans ∈ {true, false}
+- `output.verbose` ∈ {true, false}
 
-Your choice:
+```bash
+node .rihal/bin/rihal-tools.cjs config-set "$KEY" "$VALUE"
 ```
 
-Valid responses: 1/yes/y or 2/no/n. Store as `new_enable_plan_checker_loop` (true/false string).
-
-### Setting 4: Enable Post-Execute Verifier Gates
-
+Print:
 ```
-Question:
-Enable post-execute verifier gates?
-
-This runs verification after each task execution to catch regressions and issues.
-
-Options:
-  1. Yes
-  2. No [CURRENT]
-
-Your choice:
+✓ {key} = {value}
 ```
 
-Valid responses: 1/yes/y or 2/no/n. Store as `new_enable_post_execute_verifier` (true/false string).
-
-### Setting 5: Branching Strategy
+STOP.
 
-```
-Question:
-What branching strategy should workflows use?
+## Step 2 — Interactive edit
 
-Options:
-  1. none (No branching, work on current branch)
-  2. feature-branch (Create feature branches, leave checkout to user)
-  3. worktree-isolation (Use git worktrees for isolated work)
+After Step 1.5 prints the table, use the **`AskUserQuestion` tool** to prompt:
 
-Your choice: [pre-filled with current_branching_strategy]
 ```
+Which setting would you like to change?
 
-Valid responses: 1, 2, 3, or exact names (none, feature-branch, worktree-isolation).
-Map numeric choices to strategy names. Store as `new_branching_strategy`.
+  1. mode (guided / yolo)
+  2. model_profile (quality / balanced / budget / inherit)
+  3. workflow.research_by_default (true / false)
+  4. workflow.plan_checker (true / false)
+  5. workflow.post_execute_gates (true / false)
+  6. workflow.ui_safety_gate (true / false)
+  7. workflow.discuss_mode (adaptive / discuss / skip)
+  8. git.branching_strategy (none / feature-branch / worktree-isolation)
+  9. git.commit_docs (true / false)
+  10. communication_language
+  11. output.verbose (true / false)
+  0. Done — exit
+```
 
-## Step 3 — Write Config
+When the user picks a number, use **`AskUserQuestion` tool** again to ask for
+the new value, showing the allowed values for that key.
 
-After collecting all settings, write them back to `.rihal/config.yaml` using `rihal-tools.cjs config set`:
+Then call:
 
 ```bash
-node .rihal/bin/rihal-tools.cjs config set --key model_profile --value "$new_model_profile"
-node .rihal/bin/rihal-tools.cjs config set --key enable_research_pre_step --value "$new_enable_research_pre_step"
-node .rihal/bin/rihal-tools.cjs config set --key enable_plan_checker_loop --value "$new_enable_plan_checker_loop"
-node .rihal/bin/rihal-tools.cjs config set --key enable_post_execute_verifier --value "$new_enable_post_execute_verifier"
-node .rihal/bin/rihal-tools.cjs config set --key branching_strategy --value "$new_branching_strategy"
+node .rihal/bin/rihal-tools.cjs config-set "{dotted.key}" "{value}"
 ```
 
-## Step 4 — Confirm and Print
+After each successful write, re-display the affected row so the user sees the
+change took effect.
 
-Print a summary of the new settings:
+Use **`AskUserQuestion`** again to loop — ask which setting to change next —
+until the user picks `0` or `done`.
 
-```
-✓ Settings updated successfully!
+## Step 3 — Closing summary
 
-Model Profile: $new_model_profile
-Research pre-step: $new_enable_research_pre_step
-Plan-checker loop: $new_enable_plan_checker_loop
-Post-execute verifier: $new_enable_post_execute_verifier
-Branching strategy: $new_branching_strategy
+Print:
 
-Settings saved to: .rihal/config.yaml
 ```
+✓ Settings saved to .rihal/config.yaml
 
-Print a tip:
-
-```
-Tip: Use /rihal:resume-work to reload config and continue work.
+Tip: settings take effect on the next workflow run. Use /rihal:settings show
+to verify, or /rihal:resume-work to reload context.
 ```
 
 ## Success Criteria
 
-- [ ] Task completed as requested
-- [ ] Output saved or reported
-- [ ] State updated if necessary
-- [ ] No errors encountered
+- [ ] `/rihal:settings show` prints all 11 keys (no `(unset)` for keys with defaults)
+- [ ] `/rihal:settings set workflow.discuss_mode discuss` round-trips: `config-get` returns `discuss`
+- [ ] After any save, sibling keys in `workflow:` and `git:` blocks are preserved (no nesting corruption)
+- [ ] Unknown keys are rejected with the allowed-keys table
 
 ## 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
-
+- **`.rihal/config.yaml` missing:** print "No config found. Run /rihal:init first." and STOP.
+- **Invalid key:** print the allowed keys from Step 1.5 and STOP.
+- **Invalid value:** print the allowed values for that key and STOP.
+- **`rihal-tools.cjs` missing:** print "Run: npx @hanzlaa/rcode install ." and STOP.

package/rihal/workflows/ship.md

@@ -1,5 +1,35 @@
 <purpose>
-Create a pull request from completed phase/milestone work, generate a rich PR body from planning artifacts, optionally run code review, and prepare for merge. Closes the plan → execute → verify → ship loop.
+Push a verified feature branch and open a pull request with an auto-generated
+body drawn from planning artifacts (ROADMAP, VERIFICATION, SUMMARY). Closes
+the plan → execute → verify → **ship** loop.
+
+**What this command does:**
+1. Runs preflight: clean tree, on a feature branch, VERIFICATION.md passed, gh CLI authenticated
+2. Pushes the branch to origin
+3. Generates a rich PR body — phase goal, list of changes, requirements addressed, verification status
+4. Creates the PR via `gh pr create`
+5. Optionally requests a reviewer
+6. Updates STATE.md with shipping status
+
+**Preconditions (all must be true before running):**
+- `/rihal:execute <phase>` completed
+- `/rihal:verify-phase <phase>` passed (VERIFICATION.md exists with `status: passed`)
+- You are on a feature branch (not main/develop directly)
+- `gh` CLI is authenticated (`gh auth status`)
+
+**This command is NOT for:**
+- Publishing npm packages → use `npm publish`
+- Creating git release tags → use `git tag -a vX.Y.Z && git push --tags`
+- Repos that commit directly to main (`git.branching_strategy: none`)
+- The rihal-code framework repo itself (no phases exist there)
+
+**Typical usage:**
+```
+/rihal:plan 1          → plan the phase
+/rihal:execute 1       → build it
+/rihal:verify-phase 1  → prove it works
+/rihal:ship 1          → PR it ← you are here
+```
 </purpose>
 
 <required_reading>

package/rihal/workflows/sprint-planning.md

@@ -1,11 +1,46 @@
 # Workflow: rihal:sprint-planning
 
 <purpose>
-Plan the next sprint: compute capacity from velocity history, prioritize stories from phase scope, create SPRINT.md, register sprint + stories in state.json.
-
-Uses rihal-tools.cjs sprint/story state commands for tracking.
+Plan the next sprint. Authoritative implementation lives in the
+`rihal-sprint-planning` skill — this workflow delegates to it so every
+safety rail (capacity gate per #127, halt-at-menu per #124, state-sync
+per #198) fires identically whether the user invokes the slash command
+or the phrase-activated skill.
+
+The skill MUST be loaded before the in-line steps below run. If the skill
+file is missing (broken install), report and stop — do not silently fall
+back to the in-line implementation.
 </purpose>
 
+<delegate_to_skill>
+Required skill: `rihal-sprint-planning`
+Path:           `.claude/skills/rihal-sprint-planning/SKILL.md`
+Workflow ref:   `.claude/skills/rihal-sprint-planning/workflow.md`
+
+Behaviour:
+1. Load the skill's `SKILL.md` and `workflow.md`. Apply every Critical
+   Rule from the workflow's `## CRITICAL RULES (NO EXCEPTIONS)` block,
+   including the capacity gate (step n="0") which MUST halt for
+   numeric capacity inputs before any story is committed.
+2. Run the skill's step files in order. The in-line steps below this
+   block are a fallback summary for legacy installs that lack the skill;
+   they are NOT the authoritative behaviour.
+3. After SPRINT.md is written, ALWAYS run:
+   `node .rihal/bin/rihal-tools.cjs state sync --from-disk`
+   so state.sprints[] reflects the new sprint.
+
+If skill files are missing: print
+"Sprint-planning skill not installed. Run: npx @hanzlaa/rcode install"
+and exit non-zero. Do not proceed with the legacy in-line steps because
+they bypass the capacity gate.
+</delegate_to_skill>
+
+<required_reading>
+@.rihal/references/output-format.md
+@rihal/brain/best-practices/no-autonomous-bypass.md
+@rihal/brain/best-practices/state-sync-rule.md
+</required_reading>
+
 <output_format>
 Open with banner:
 ```
@@ -13,15 +48,11 @@ Open with banner:
  RIHAL ► PLANNING SPRINT
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
-TaskCreate: "Load phase scope + velocity", "Curate stories with user", "Register sprint + stories in state", "Write SPRINT.md", "Start sprint".
+TaskCreate: "Load phase scope + velocity", "Capacity gate (halt for numbers)", "Curate stories with user", "Register sprint + stories in state", "Write SPRINT.md", "Sync state", "Start sprint".
 Closure: `RIHAL ► SPRINT {NN.S} READY ✓ ({N} stories, {M} points)`
 Next Up: `/rihal:execute .planning/phases/{phase}/SPRINT.md`
 </output_format>
 
-<required_reading>
-@.rihal/references/output-format.md
-</required_reading>
-
 <process>
 ## Step 0 — Usage check
 

package/rihal/workflows/status.md

@@ -16,10 +16,15 @@ Render a human-readable project status dashboard. All data comes from a single `
 
 ```bash
 SNAPSHOT=$(node .rihal/bin/rihal-tools.cjs progress init)
+VERBOSE=$(node .rihal/bin/rihal-tools.cjs config-get output.verbose 2>/dev/null || echo "false")
 ```
 
 Parse as JSON. If `SNAPSHOT.ok` is not true, print a one-line error and stop.
 
+**Slim mode** (default when `VERBOSE != "true"`): Output Steps 2–3 only (banner + phases list). Skip decisions, blockers detail, and route menu — just print the top route as a single "Next: `/rihal:X`" line. Append `(run /rihal:status --verbose for full detail)`.
+
+**Verbose mode** (`VERBOSE == "true"` or `$ARGUMENTS` contains `--verbose`): Full Steps 2–6 output.
+
 If `SNAPSHOT.project` is empty and `SNAPSHOT.phases` is empty, print:
 
 ```

package/rihal/workflows/ui-phase.md

@@ -22,7 +22,7 @@ If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 STOP — do not proceed.
 
 <available_agent_types>
-- `rihal-ui-designer` — UI specification generator
+- `rihal-ux-designer` — UI specification generator
 </available_agent_types>
 
 ## Step 0 — Initialize
@@ -51,11 +51,11 @@ Load existing design system, extract:
 
 ## Step 2 — Spawn UI Designer
 
-Spawn `rihal-ui-designer` subagent:
+Spawn `rihal-ux-designer` subagent:
 
 ```
 Task tool call:
-  subagent_type: "rihal-ui-designer"
+  subagent_type: "rihal-ux-designer"
   description: "Generate UI-SPEC.md"
   prompt: |
     Generate a UI-SPEC.md file with the following structure:

package/rihal/workflows/update.md

@@ -1,39 +1,56 @@
 # 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.
+Pull the latest rcode from npm and install it **non-destructively** —
+overwrite only files the user hasn't customized since their last install.
+User-modified files are preserved and reported. Closes #232.
+
+Default invocation:
+```
+npx @hanzlaa/rcode@latest install . --non-destructive --yes
+```
+
+The `--non-destructive` flag (set by default in this workflow) makes the
+installer compare each file's current SHA256 to the SHA256 stored in
+`.rihal/_config/files-manifest.csv` from the previous install:
+- Hashes match → file is pristine → safe to overwrite with new version
+- Hashes differ → user has edited it → SKIP and report
+
+Per-project state is ALWAYS preserved (never touched by either mode):
+- `.rihal/config.yaml`
+- `.rihal/state.json` (and `.lock`)
+- `.planning/` (PRD, ROADMAP, sprints, SUMMARY files)
+- `.rihal/brain/` content (refreshed via `brain pull` separately)
 </purpose>
 
 
 ## Step 0 — Usage check
 
-If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+If `$ARGUMENTS` contains `--help` or `-h`:
 
 ```
-/rihal:update <argument-here>
+/rihal:update                       # pull latest, preserve user-modified files
+/rihal:update v2.4.0                # pin to a specific version
+/rihal:update --force-overwrite     # discard local edits, overwrite all rcode files
 ```
 
 **Examples:**
 ```
-/rihal:update example 1
-/rihal:update example 2
+/rihal:update
+/rihal:update v2.4.0
+/rihal:update --force-overwrite
 ```
 
-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.
+Find the local rcode installer (used as the network-fallback path in
+Step 7). Try in order:
+
+1. `$(npm root -g)/@hanzlaa/rcode/cli/install.js` (global install)
+2. `./cli/install.js` (local clone)
+3. If neither exists, skip — Step 7's primary path uses `npx @hanzlaa/rcode@latest` and works without a local installer.
 
-Store the installer path in `$INSTALLER_PATH`.
+Store the resolved path (or empty) in `$INSTALLER_PATH`.
 
 ## Step 2 — Read installed manifest
 
@@ -45,8 +62,8 @@ 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
+ℹ️ No rcode installation detected in this project.
+Run: npx @hanzlaa/rcode@latest install . --yes
 ```
 Exit.
 
@@ -121,20 +138,61 @@ Options:
 - If user chooses [1], proceed to Step 7
 - If user chooses [2], print "Update cancelled" and exit
 
-## Step 7 — Apply update
+## Step 7 — Apply update (non-destructive by default per #232)
 
-Run the installer with `--force --yes`:
+Pull from npm AND install non-destructively. User-modified files are
+preserved automatically; the installer reports each one in the summary.
 
 ```bash
-node "$INSTALLER_PATH" . --force --yes
+npx @hanzlaa/rcode@latest install . --non-destructive --yes
+```
+
+**If the user explicitly wants destructive overwrite** (rare — only
+when they intentionally want to discard their customizations):
+
+```bash
+npx @hanzlaa/rcode@latest install . --force-overwrite --yes
+```
+
+**Version pinning** — if the user passed `/rihal:update v2.4.0`, pass
+the version through:
+
+```bash
+npx @hanzlaa/rcode@2.4.0 install . --non-destructive --yes
+```
+
+**Local fallback** — if the user's network can't reach npm, fall back
+to the locally-cached installer (still non-destructive):
+
+```bash
+node "$INSTALLER_PATH" . --non-destructive --yes
 ```
 
 If the command exits with non-zero status, print:
+
 ```
 ❌ Update failed. Check the output above.
+   Tip: try --force-overwrite if you intentionally want to overwrite
+   your customizations, or run with the local installer fallback.
 ```
+
 Exit with error code.
 
+## Step 7.5 — Surface preserved files
+
+The installer's stdout will include a "user-modified preserved" report
+when relevant. Capture it and re-print as a callout so users notice:
+
+```
+ℹ Files preserved (your customizations were kept):
+   - .claude/skills/rihal-create-prd/workflow.md
+   - rihal/workflows/sprint-planning.md
+   - .rihal/references/output-format.md
+
+These will not auto-update on future /rihal:update calls. To force
+their update next time, run /rihal:update --force-overwrite.
+```
+
 ## 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.

package/rihal/workflows/validate-phase.md

@@ -83,7 +83,13 @@ No gaps → skip to Step 6, set `nyquist_compliant: true`.
 
 ## 4. Present Gap Plan
 
-Call AskUserQuestion with gap table and options:
+```bash
+CONFIG_MODE=$(node .rihal/bin/rihal-tools.cjs config-get mode 2>/dev/null || echo "guided")
+```
+
+**If `CONFIG_MODE == "yolo"`:** Auto-select option 1 ("Fix all gaps") and proceed to Step 5 without asking. Print: `▶ Auto-fixing all gaps (yolo mode).`
+
+Otherwise call AskUserQuestion with gap table and options:
 1. "Fix all gaps" → Step 5
 2. "Skip — mark manual-only" → add to Manual-Only, Step 6
 3. "Cancel" → exit