@hanzlaa/rcode 2.2.0 → 2.3.1

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Rihal Code (rcode) — installable context-brain for Rihalians. 44 agents, 93 slash commands, 58 skills, pullable Rihal standards. Unified install for Claude Code, Cursor, and Gemini.",
   "main": "cli/index.js",
   "bin": {
-    "rcode": "cli/index.js",
-    "rihal-code": "cli/index.js"
+    "rcode": "dist/rcode.js",
+    "rihal-code": "dist/rcode.js"
   },
   "scripts": {
     "dashboard": "node server/dashboard.js",
     "test": "node --test",
     "test:ci": "node --test --test-reporter=spec",
-    "postinstall": "node cli/postinstall.js"
+    "postinstall": "node cli/postinstall.js",
+    "build:cli": "node scripts/build.cjs",
+    "build": "node scripts/build.cjs"
   },
   "files": [
     "cli/",
     "rihal/",
     "server/",
+    "dist/",
     ".rihal-template/",
     "README.md",
     "AGENTS.md",
@@ -54,6 +57,16 @@
     "node": ">=18.0.0"
   },
   "dependencies": {},
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "picocolors": "^1.1.1",
+    "nanospinner": "^1.2.2",
+    "fast-glob": "^3.3.3",
+    "zod": "^3.24.0",
+    "semver": "^7.7.1",
+    "diff": "^7.0.0",
+    "@clack/prompts": "^0.9.1"
+  },
   "publishConfig": {
     "access": "public"
   }

package/rihal/DOCS-AUDIT.md

@@ -0,0 +1,14 @@
+# DOCS-AUDIT.md (per-project artefact)
+
+This file is generated by `/rihal:document-project` into the project root
+as `DOCS-AUDIT.md`. The shipped reference here just defines the schema:
+
+- **Inventory:** every doc file (path, last-touched, owner, freshness).
+- **Gaps:** docs that should exist per the project's domain (e.g. README,
+  CONTRIBUTING, ADRs for major decisions) but don't.
+- **Stale:** docs that diverge from current code/state (links to dead
+  files, version mismatches, removed features still documented).
+- **Recommendations:** ordered remediation list.
+
+Workflows that @-include this file expect the live audit output, which
+the workflow itself writes to disk before reading.

package/rihal/agents/rihal-code-reviewer.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Code Reviewer

package/rihal/agents/rihal-codebase-mapper.md

@@ -7,7 +7,7 @@ color: cyan
 
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 
 <role>
 You are a rihal codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.rihal/codebase/`.

package/rihal/agents/rihal-docs-auditor.md

@@ -6,7 +6,7 @@ color: gold
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Documentation Auditor

package/rihal/agents/rihal-edge-case-hunter.md

@@ -6,7 +6,7 @@ color: maroon
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Edge Case Hunter

package/rihal/agents/rihal-executor.md

@@ -6,7 +6,7 @@ color: yellow
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
 @.rihal/references/no-unauthorized-git-ops.md
 

package/rihal/agents/rihal-hussain-pm.md

@@ -7,6 +7,7 @@ color: orange
 
 @.rihal/references/response-style.md
 @.rihal/references/codebase-grounding.md
+@.rihal/references/karpathy-guidelines.md
 
 # Hussain-PM — Product Manager
 

package/rihal/agents/rihal-nyquist-auditor.md

@@ -6,7 +6,7 @@ color: #8B5CF6
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 <role>

package/rihal/agents/rihal-phase-researcher.md

@@ -7,8 +7,7 @@ color: cyan
 
 
 @.rihal/references/response-style.md
-
-
+@.rihal/references/karpathy-guidelines.md
 
 <role>
 You are a Rihal phase researcher. You answer "What do I need to know to PLAN this phase well?" and produce a single RESEARCH.md that the planner consumes.

package/rihal/agents/rihal-planner.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
 
 <role>

package/rihal/agents/rihal-roadmapper.md

@@ -8,6 +8,7 @@ color: purple
 
 @.rihal/references/response-style.md
 @.rihal/references/output-realism.md
+@.rihal/references/karpathy-guidelines.md
 
 <role>
 You are a rihal roadmapper. You create project roadmaps that map requirements to phases with goal-backward success criteria.

package/rihal/agents/rihal-security-adversary.md

@@ -6,7 +6,7 @@ color: darkred
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Security Adversary

package/rihal/agents/rihal-security-auditor.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Security Auditor

package/rihal/agents/rihal-sprint-checker.md

@@ -7,7 +7,7 @@ color: green
 
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 
 <role>
 You are a Rihal sprint checker. Verify that sprints WILL achieve the phase goal, not just that they look complete.

package/rihal/agents/rihal-verifier.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 <role>

package/rihal/bin/lib/roadmap.cjs

@@ -1,9 +1,8 @@
 /**
  * Roadmap — Rihal ROADMAP.md parsing and mutation helpers.
  *
- * Self-contained (stdlib only). Matches GSD output shapes for the subset of
- * commands that Rihal workflows currently invoke: get-phase, list-phases,
- * update-plan-progress, and clear.
+ * Self-contained (stdlib only). Subcommands invoked by Rihal workflows:
+ * get-phase, list-phases, update-plan-progress, clear.
  */
 
 const fs = require('fs');

package/rihal/bin/rihal-tools.cjs

@@ -1950,7 +1950,7 @@ function cmdState(subArgs) {
   // --- promote-backlog <from> --to <target> ---
   // Promote a 999.x parking-lot phase to a real phase number.
   // Mutates state.phases[]; renames the on-disk directory if present.
-  // Tracks issue #159 (M2.5 — GSD-parity 999.x convention).
+  // Tracks issue #159 (M2.5 — 999.x parking-lot convention).
   if (sub === 'promote-backlog') {
     const from = subArgs[1];
     const flags = parseFlags(2);
@@ -2568,8 +2568,12 @@ function cmdResolveModel(agentId) {
 }
 
 /**
- * config set --key <k> --value <v> — update a key in .rihal/config.yaml
- * Writes YAML-style `key: value` (quotes strings with spaces).
+ * config set --key <k> --value <v> — DEPRECATED legacy form.
+ *
+ * Closes #233. The original implementation used a flat YAML parser that
+ * destroyed the nested `workflow:` and `git:` sections on every save.
+ * This shim now delegates to the nested-safe writer in lib/config.cjs and
+ * emits a one-line deprecation warning to stderr so callers migrate.
  */
 function cmdConfigSet(subArgs) {
   const flags = {};
@@ -2587,34 +2591,10 @@ function cmdConfigSet(subArgs) {
   if (!key) throw new Error('config set requires --key <key> --value <value>\n  e.g. config set --key language --value Arabic');
   if (!value) throw new Error('config set requires --key <key> --value <value>\n  e.g. config set --key language --value Arabic');
 
-  const configPath = path.join(RIHAL_DIR, 'config.yaml');
-  fs.mkdirSync(RIHAL_DIR, { recursive: true });
-
-  let content = '';
-  if (fs.existsSync(configPath)) {
-    content = fs.readFileSync(configPath, 'utf8');
-  }
-
-  // Parse current config
-  const config = parseSimpleYaml(content);
-
-  // Update the key
-  config[key] = value;
-
-  // Serialize back to YAML
-  const lines = [];
-  for (const [k, v] of Object.entries(config)) {
-    const needsQuotes = /\s/.test(v);
-    const yamlValue = needsQuotes ? `"${v.replace(/"/g, '\\"')}"` : v;
-    lines.push(`${k}: ${yamlValue}`);
-  }
-
-  const newContent = lines.join('\n') + '\n';
-  const tmp = configPath + '.tmp';
-  fs.writeFileSync(tmp, newContent, 'utf8');
-  fs.renameSync(tmp, configPath);
+  process.stderr.write(`[deprecated] 'config set --key X --value Y' — use 'config-set X Y' instead (preserves nested YAML).\n`);
 
-  return { ok: true, key, value, path: configPath };
+  const cfg = require(path.join(__dirname, 'lib', 'config.cjs'));
+  return cfg.cmdSet(PROJECT_ROOT, key, value);
 }
 
 /**
@@ -3033,7 +3013,7 @@ function cmdBrain(args) {
 }
 
 /**
- * cmdProgress — single pre-computed progress blob (GSD-parity, issue #159).
+ * cmdProgress — single pre-computed progress blob (issue #159).
  *
  * Subcommands:
  *   progress init          Full snapshot — everything /rihal:progress needs.

package/rihal/commands/audit.md

@@ -0,0 +1,8 @@
+---
+name: rihal:audit
+description: Single audit entry point — asks what to audit (phase, milestone, UAT, code, fix, work) and dispatches to the right subroute. Honours .rihal/config.yaml mode.
+argument-hint: "[phase | milestone | uat | code | fix | work] [...subroute args]"
+allowed-tools: Read, Write, Bash, AskUserQuestion
+---
+
+@.rihal/workflows/audit.md

package/rihal/commands/checkpoint-preview.md

@@ -0,0 +1,13 @@
+---
+name: rihal:checkpoint-preview
+description: Human-in-the-loop change review — makes sense of a diff, focuses attention where it matters, and walks through testing. Use when you say "checkpoint", "walk me through this", or "human review".
+argument-hint: "[<branch-or-diff>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+@.rihal/workflows/checkpoint-preview.md

package/rihal/commands/config.md

@@ -1,8 +1,8 @@
 ---
 name: rihal:config
-description: View or edit Rihal configuration (language, mode, model profile, branching strategy)
-argument-hint: "[show | set <key> <value>]"
-allowed-tools: Read, Bash, AskUserQuestion
+description: Alias for /rihal:settings — view or edit Rihal config (language, mode, model profile, workflow gates, git strategy)
+argument-hint: "[show | get <key> | set <key> <value>]"
+allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 
-@.rihal/workflows/config.md
+@.rihal/workflows/settings.md

package/rihal/commands/prfaq.md

@@ -0,0 +1,15 @@
+---
+name: rihal:prfaq
+description: Working Backwards PRFAQ challenge — stress-test a product concept by writing the press release before building it. Produces a battle-hardened PRFAQ document + PRD distillate.
+argument-hint: "[<idea>] [--headless] [--customer=<persona>] [--problem=<problem>] [--stakes=<why>] [--solution=<concept>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Agent
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+---
+
+@.rihal/workflows/prfaq.md

package/rihal/commands/settings.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:settings
-description: Interactive configuration wizard for Rihal project settings. Update model profile, research strategy, execution gates, and branching strategy.
-argument-hint: ""
+description: View or edit Rihal project settings (mode, model_profile, workflow gates, git strategy). Supports show / get / set / interactive modes.
+argument-hint: "[show | get <key> | set <key> <value>]"
 allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 

package/rihal/references/agent-contracts.md

@@ -0,0 +1,12 @@
+# Agent Contracts
+
+Conventions Rihal sub-agents follow when invoked from a workflow.
+
+- **Input**: a single prompt string. The orchestrator passes structured data
+  inline (path lists, JSON blobs) — sub-agents do not stream args.
+- **Output**: one final message back to the orchestrator. No partial state
+  is visible mid-run.
+- **Side effects**: each agent's tool list is its full surface — any tool
+  not granted in the agent definition is unavailable.
+- **Failure**: agents that hit an obstacle return a structured "blocked"
+  message rather than fabricating output.

package/rihal/references/karpathy-guidelines-full.md

@@ -0,0 +1,79 @@
+# Karpathy Coding Guidelines
+
+Behavioral guidelines derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Every rihal agent that writes, reviews, or refactors code must internalize these four principles.
+
+**Tradeoff:** These bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+**Rihal application:** In Round 1 of council/chain, every agent's response must include an `## Assumptions` block listing load-bearing assumptions. rihal-planner must ask via AskUserQuestion before writing a plan when scope is ambiguous. rihal-executor must stop on Rule 4 deviations and return a checkpoint, not silently guess.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Test: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+**Rihal application:** rihal-planner tasks must be single-purpose. rihal-executor must not add abstractions during task execution (deviation Rule 2 applies only to missing critical functionality, not speculative flexibility). rihal-code-review explicitly flags overengineering.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+**Rihal application:** rihal-executor commits must only include files its tasks touched. The deviation scope boundary (out-of-scope warnings logged to deferred-items.md, not fixed) enforces this. rihal-code-review-fix must not change style in files it's auditing.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+**Rihal application:** Every task in a SPRINT.md must have a "Done when:" clause that's externally verifiable. rihal-executor self-check loop verifies Done-when conditions were met. rihal-sprint-checker rejects plans where tasks have vague success criteria.
+
+## Enforcement
+
+Agents that write or modify code (rihal-executor, rihal-planner, rihal-tech-writer, rihal-codebase-mapper when producing code docs) must:
+1. @-include this file
+2. Apply the 4 principles as hard constraints, not suggestions
+3. Reference the specific principle when refusing to make a change (e.g., "Declining per Karpathy #3: that's adjacent to the requested change but not part of it")
+
+## Credit
+
+Original principles by Andrej Karpathy. Reference implementation by Forrest Chang at github.com/forrestchang/andrej-karpathy-skills. Adapted and extended for rihal's multi-agent architecture.

package/rihal/references/karpathy-guidelines.md

@@ -1,79 +1,11 @@
-# Karpathy Coding Guidelines
+# Karpathy Guidelines — Quick Reference
 
-Behavioral guidelines derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Every rihal agent that writes, reviews, or refactors code must internalize these four principles.
+Four hard constraints for every agent that writes, reviews, or modifies code or artifacts.
+Full text with Rihal-specific application notes: `@.rihal/references/karpathy-guidelines-full.md`
 
-**Tradeoff:** These bias toward caution over speed. For trivial tasks, use judgment.
+1. **Think first (P1)** — State assumptions explicitly before acting. If scope is ambiguous, ask. Never guess silently.
+2. **Simplicity (P2)** — Minimum code/scope that solves the problem. No speculative features, abstractions, or error handling for impossible cases.
+3. **Surgical (P3)** — Touch only what the task requires. Don't improve adjacent code, don't refactor what isn't broken.
+4. **Goal-driven (P4)** — Define a verifiable success criterion before starting. "Done when: X can be verified externally."
 
-## 1. Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-**Rihal application:** In Round 1 of council/chain, every agent's response must include an `## Assumptions` block listing load-bearing assumptions. rihal-planner must ask via AskUserQuestion before writing a plan when scope is ambiguous. rihal-executor must stop on Rule 4 deviations and return a checkpoint, not silently guess.
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Test: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-**Rihal application:** rihal-planner tasks must be single-purpose. rihal-executor must not add abstractions during task execution (deviation Rule 2 applies only to missing critical functionality, not speculative flexibility). rihal-code-review explicitly flags overengineering.
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it — don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-**Rihal application:** rihal-executor commits must only include files its tasks touched. The deviation scope boundary (out-of-scope warnings logged to deferred-items.md, not fixed) enforces this. rihal-code-review-fix must not change style in files it's auditing.
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-**Rihal application:** Every task in a SPRINT.md must have a "Done when:" clause that's externally verifiable. rihal-executor self-check loop verifies Done-when conditions were met. rihal-sprint-checker rejects plans where tasks have vague success criteria.
-
-## Enforcement
-
-Agents that write or modify code (rihal-executor, rihal-planner, rihal-tech-writer, rihal-codebase-mapper when producing code docs) must:
-1. @-include this file
-2. Apply the 4 principles as hard constraints, not suggestions
-3. Reference the specific principle when refusing to make a change (e.g., "Declining per Karpathy #3: that's adjacent to the requested change but not part of it")
-
-## Credit
-
-Original principles by Andrej Karpathy. Reference implementation by Forrest Chang at github.com/forrestchang/andrej-karpathy-skills. Adapted and extended for rihal's multi-agent architecture.
+When refusing a change, cite the principle: `"Declining per Karpathy P3 — that's adjacent to the requested change."`

package/rihal/references/model-profile-resolution.md

@@ -0,0 +1,8 @@
+# Model Profile Resolution
+
+Workflows pick a model via `node .rihal/bin/rihal-tools.cjs resolve-model
+<role>`, which reads `.rihal/config.yaml` `model_profile` and returns the
+concrete model id for that role per `rihal/config/model-profiles.json`.
+
+If `model_profile` is unset, default is `balanced`. Unknown profile falls
+back to `balanced` with a stderr warning.

package/rihal/references/phase-argument-parsing.md

@@ -0,0 +1,11 @@
+# Phase Argument Parsing
+
+Workflows accept a phase argument in two forms:
+
+- **Numeric**: `01`, `2`, `02.1` — resolved via
+  `node .rihal/bin/rihal-tools.cjs init phase-op "$ARG"` to the matching
+  phase directory under `.planning/phases/`.
+- **Path**: a direct `.planning/phases/<slug>/PLAN.md` path — used as-is.
+
+If the resolver returns `phase_found: false`, workflows must STOP with a
+"phase not found" message rather than fabricating a target.

package/rihal/references/revision-loop.md

@@ -0,0 +1,11 @@
+# Plan Revision Loop
+
+When `workflow.plan_checker` is enabled (`/rihal:settings`), `/rihal:plan`
+runs the rihal-plan-checker after the planner. Findings drive a bounded
+revision loop:
+
+1. Planner produces PLAN.md.
+2. Plan-checker scores against goal-backward criteria.
+3. If BLOCK / FLAG: planner revises with the findings as added input.
+4. Up to 2 revision rounds. After that, surface to user for manual
+   confirmation rather than loop indefinitely.

package/rihal/references/universal-anti-patterns.md

@@ -0,0 +1,15 @@
+# Universal Anti-Patterns (Discuss-Phase)
+
+Common failure modes the discuss workflow checks for:
+
+- **Solution-first framing**: jumping to implementation before constraints
+  are explicit.
+- **Hidden binary choice**: presenting a "decision" that has only one
+  viable option.
+- **Unowned action**: a "we should X" with no owner or deadline.
+- **Sunk-cost continuation**: defending an existing plan instead of
+  evaluating fresh evidence.
+- **Scope inflation**: bundling new work into the current decision.
+
+Discuss-phase flags any of these and asks for explicit framing before
+proceeding.

package/rihal/skills/actions/1-analysis/rihal-prfaq/SKILL.md

@@ -3,6 +3,16 @@ name: rihal-prfaq
 description: Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
 ---
 
+## Do NOT use this skill for
+
+- **Refining an existing PRD** — use `rihal-create-prd` or `rihal-edit-prd`.
+- **Brainstorming raw ideas** before there's a concept — use `rihal-brainstorming` first; PRFAQ assumes a candidate concept exists.
+- **Sprint or phase planning** — use `rihal-sprint-planning` / `rihal-create-milestone`.
+- **Pure market research with no product hypothesis** — use a research workflow.
+- **Single-question Q&A** — PRFAQ runs a multi-stage gauntlet; for a one-off answer, just answer.
+
+If the user asks to "validate" or "polish" an existing PRD, redirect to `rihal-validate-prd`.
+
 ## Workflow
 
 

package/rihal/skills/actions/2-plan/rihal-create-epics-and-stories/SKILL.md

@@ -15,9 +15,11 @@ Follow the instructions in ./workflow.md.
 ## Output Format
 
 - Produces .rihal/phases/{phase}/epics.md with hierarchical structure
-- Each epic has: Title | Goal | Stories (list) | Priority | Estimate
+- Each epic has: Title | Goal | Assumptions | Stories (list) | Priority | Estimate
 - Each story is independently testable and under 4-hour estimate
 - Do NOT create epics larger than 10 stories — split further
+- Every epic must include an `Assumptions` line — at minimum one entry; "none" is not acceptable
+- Every story must have a one-line verifiable AC before being listed — vague stories get flagged and blocked
 
 ## Examples
 

package/rihal/skills/actions/2-plan/rihal-create-milestone/SKILL.md

@@ -15,10 +15,12 @@ Follow the instructions in ./workflow.md.
 ## Output Format
 
 - Output: ROADMAP.md in `{planning_artifacts}/`
-- Structure: per milestone — Name, Window (dates), Goal (one sentence), Acceptance criteria, Kill criteria (binary), Phases (stub list), then a trailing Backlog / parking lot section
+- Structure: per milestone — Name, Window (dates), Goal (one sentence), Assumptions, Acceptance criteria, Kill criteria (binary), Phases (stub list), then a trailing Backlog / parking lot section
 - Each kill criterion must be binary (number + threshold), not adjectival
 - Every milestone has an explicit window with start + end dates
+- Every milestone must include an `Assumptions` block — decisions that, if wrong, invalidate this milestone's scope
 - Do NOT include: unquantified success language ("grow the user base"), open-ended milestones without dates, or more than 6 active milestones in one roadmap (split into v1/v2 if needed)
+- If a milestone goal cannot be expressed as a single verifiable sentence, split it into two milestones
 
 ## Examples
 

package/rihal/skills/actions/2-plan/rihal-create-milestone/steps/step-10-complete.md

@@ -33,7 +33,7 @@ Hard deadline:  {deadline or "none specified"}
 [{completedAt}]
 ```
 
-### 3. Next-step menu (intent-based, mirrors the GSD /progress Route A/B/C pattern)
+### 3. Next-step menu (intent-based Route A/B/C pattern)
 
 ```
 What's next?