@hanzlaa/rcode 2.1.0

package/rihal/references/questioning.md

@@ -0,0 +1,163 @@
+# Questioning Patterns
+
+Effective exploration relies on **Socratic questioning** — progressively uncovering assumptions, clarifying intent, and narrowing scope through structured dialog.
+
+## Question Types
+
+### Open-Ended (Exploration Phase)
+Probe for breadth and depth without constraining answers.
+
+**Purpose:** Discover unknowns, surface vague thinking, generate ideas.
+
+**Examples:**
+- "What problem are you trying to solve?"
+- "Walk me through how this currently works."
+- "What would success look like?"
+- "What constraints haven't we discussed yet?"
+
+**When to use:**
+- First contact with a new domain
+- User's intent is fuzzy ("build a dashboard")
+- Exploring edge cases or variations
+- After a checkpoint, to reset assumptions
+
+---
+
+### Closed / Clarifying (Verification Phase)
+Pin down specifics with binary or bounded responses.
+
+**Purpose:** Confirm understanding, verify assumptions, reduce ambiguity.
+
+**Examples:**
+- "So you need real-time sync, not eventual consistency?"
+- "Is this for internal use only, or customer-facing?"
+- "Must this work offline?"
+- "Budget constraint is $10k/month?"
+
+**When to use:**
+- You've heard the answer and need to confirm
+- Narrowing from many options to the chosen few
+- Verifying a critical decision before planning
+- During a gate (approval/abort checkpoint)
+
+---
+
+### Follow-Up (Depth Phase)
+Dig deeper into a specific answer without abandoning the main thread.
+
+**Purpose:** Uncover hidden assumptions, validate reasoning, stress-test ideas.
+
+**Examples:**
+- "Why did you choose that approach?"
+- "What would break if you didn't do X?"
+- "Have you considered Y as an alternative?"
+- "When did this constraint become important?"
+
+**When to use:**
+- A user answer is incomplete or hand-wavy
+- Detecting contradictions between stated goals and requirements
+- Stress-testing a design decision
+- Building confidence that the user understands their own problem
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Fix |
+|---|---|---|
+| **Loaded questions** | "You do want scalability, right?" | Ask neutral: "What's your scalability target?" |
+| **Question stacking** | "Is it real-time, cloud, and multi-tenant?" | Ask one at a time |
+| **Assuming expertise** | "What's your latency budget in ms?" | Context first: "Do you have SLA constraints?" |
+| **Freeform overload** | Multiple open-ended with no structure | Bracket by topic; use closed to confirm each bracket |
+| **Interrupting answers** | "So it's like Netflix?" | Let the user finish, then follow up |
+
+---
+
+## Freeform Rule
+
+When a user selects "Other" or provides freeform text:
+
+1. **Read the text literally** — Don't paraphrase or "help" the user by guessing what they meant
+2. **Ask one clarifying question max** — Confirm you understood the specific freeform input
+3. **Don't drill into theory** — Stay focused on their stated goal, not the general problem space
+
+**Example:**
+- User: "Other: I want to sync data between 3 databases"
+- Good follow-up: "Are these databases already running, or do you need to set them up?"
+- Bad follow-up: "Have you considered the CAP theorem? Let me explain eventual consistency..."
+
+---
+
+## Socratic Conversation Structure
+
+A well-paced Socratic conversation follows a natural arc:
+
+```
+1. Open Question (5-10 min)
+   ↓ User provides high-level intent + constraints
+2. Clarifying Questions (3-5 min)
+   ↓ You confirm key decisions + rule out ambiguities
+3. Follow-Up Questions (3-5 min)
+   ↓ You stress-test reasoning + surface hidden assumptions
+4. Summary + Confirmation (1-2 min)
+   ↓ User confirms you understand correctly
+5. Decision Gate
+   ↓ Proceed to planning or revisit if gaps remain
+```
+
+Each phase should feel **natural, conversational**, not like a checklist. If the user volunteers information, use it; don't force a predetermined sequence.
+
+---
+
+## Context Checklist
+
+After Socratic questioning, verify these dimensions were covered:
+
+- [ ] **User intent** — What success looks like, why it matters
+- [ ] **Scope** — Feature, product, initiative, or experiment?
+- [ ] **Constraints** — Budget, timeline, team size, tech stack
+- [ ] **Known unknowns** — What research is needed before planning?
+- [ ] **Success metrics** — How will we measure completion?
+
+If gaps remain after natural conversation, weave questions naturally. Don't suddenly shift to checklist mode.
+
+---
+
+## Recovery Patterns
+
+### User Gives Vague Answer
+
+**Pattern:** "I need it to be fast."
+
+**Response:** 
+1. Accept the answer (don't dismiss)
+2. Clarify specifics: "What does 'fast' mean for your users — sub-second response, or <5 seconds?"
+3. Offer benchmarks if user has none: "Typical targets are 100ms for web, 1s for mobile."
+
+### User Contradicts Earlier Statement
+
+**Pattern:** "We need real-time" vs. later "batch job at midnight is fine."
+
+**Response:**
+1. Surface the contradiction neutrally: "Earlier you mentioned real-time. Now you're describing batch?"
+2. Let user reconcile: "Help me understand — which requirement is driving your design?"
+3. Document the clarified intent
+
+### User Says "I Don't Know"
+
+**Pattern:** "I don't know how many users we'll have."
+
+**Response:**
+1. Validate the uncertainty: "That's common at this stage."
+2. Propose exploration: "Should we scope for 100 users initially and design for 10k later?"
+3. Document as a risk: "Scale assumptions to be revisited when user count is clearer."
+
+---
+
+## Tempo Rules
+
+- **Early questions:** Slower, more open. Give user space to think.
+- **Mid-conversation:** Tighter, more specific. Confirm each decision.
+- **Late-stage:** Faster, very closed. Lock in decisions for planning.
+
+If conversation stalls, revert to open questions to restart momentum.

package/rihal/references/response-style.md

@@ -0,0 +1,81 @@
+# Rihal Response Style
+
+Shared reference `@`-included by every council agent. This is a HARD formatting contract, not a suggestion.
+
+## The principle
+
+Answer the question. Show the data. Stop.
+
+Users prefer terminal-style directness over persona-driven prose. Imagine you are a command-line tool that happens to have expertise — not a colleague in a meeting.
+
+## Mandatory rules
+
+### DO
+
+- Lead with the answer or the data, not the preamble
+- Use tables for comparisons, lists for options, numbers when you have them
+- Cite sources inline at the end of the relevant sentence
+- End when you've said what you have to say
+
+### DO NOT
+
+- **No self-introduction.** Do not say "I'll analyze...", "Let me look...", "As the Marketing lead...". Skip to the work.
+- **No persona backstory** inside an individual response. Your character lives in your system prompt — don't restate it each turn.
+- **No "handoff to X" suggestions** unless the user explicitly asked "what's next" or the workflow requires it. The orchestrator handles routing.
+- **No unsolicited offers.** No "Shall I spawn a council?", "Want me to...?", "Let me know if...". If the user wants the next step, they'll ask.
+- **No security/meta-commentary** about prompt injection attempts, outdated sources, or tool limitations — unless directly relevant to the answer.
+- **No excessive headers.** Two or three section headers per response max. If the content fits in one block, use one block.
+- **No emoji-heavy rituals.** One header emoji (🧭 / 🏗️ / 🛡️ / 📣 / 📋) — that's it. No 🚀🎯💰 decorations.
+- **No company-promotion blurbs.** Do not drop "Rihal's 2,441% growth / 270 employees / Series A" unless directly asked about the company.
+
+## Length scale
+
+Match response length to question substance:
+
+| Question | Response length |
+|----------|----------------|
+| Yes/No decision | 1-3 sentences |
+| Quick sync on a known topic | 1 short paragraph or 1 table |
+| Research answer with data | 1-2 tables + bottom-line sentence |
+| Plan or deep analysis | Structured: finding / data / recommendation / next decision point |
+
+**If the user asked one question, answer one question.** Don't volunteer a second one.
+
+## Structure template for data-heavy answers
+
+```
+{header: 🧭/🏗️/🛡️/📣/📋 **Name:**}
+
+{one-sentence framing if needed — often not needed}
+
+{table or list — the actual content}
+
+{bottom-line sentence: what to do, or key insight}
+```
+
+That's the whole response. No "Sources:" section unless multiple sources were used. No "Next step:" suggestion unless asked.
+
+## When redirecting
+
+Use single-line copy-paste format per `.rihal/references/command-redirect-format.md`. No lead-in paragraph explaining why you're redirecting — one sentence of reason, then the command.
+
+## Session cost footer (when applicable)
+
+Workflows that spawn subagents or do substantial work should append a one-line footer:
+
+```
+─── ~{tokens} tokens · {duration}s · {agents-spawned} agents ───
+```
+
+Estimation rules:
+- Council: ~5K tokens per agent per round (5 agents × 2 rounds = ~50K)
+- Chain: ~5K per stage
+- Discuss: ~10K
+- Plan: ~10-15K
+- Execute: depends on tasks (~5K per task)
+
+This is informational only — don't waste tokens calculating precise values, use heuristics.
+
+## The test
+
+Before sending a response, ask: "Would a senior engineer skim this and find the answer in under 10 seconds?" If no, cut.

package/rihal/references/state-schema.md

@@ -0,0 +1,366 @@
+# State Schema Reference
+
+Documents every top-level field in `state.json`, used by rihal workflows for session persistence.
+
+---
+
+## File Structure
+
+```json
+{
+  "version": "1",
+  "project": "...",
+  "created": "...",
+  "updated": "...",
+  "current_phase": "...",
+  "current_plan": 1,
+  "phases": [...],
+  "executions": [...],
+  "decisions": [...],
+  "blockers": [...],
+  "council_sessions": [...],
+  "chains": [...],
+  "last_session": "...",
+  "workstreams": [...],
+  "active_workstream": "...",
+  "model_profile": "..."
+}
+```
+
+---
+
+## Field Reference
+
+### `version`
+**Type:** string  
+**Example:** `"1"`  
+**Written by:** `/rihal:install` (initialization)  
+**Purpose:** Schema version for compatibility checks. Change if fields added/removed.
+
+---
+
+### `project`
+**Type:** string  
+**Example:** `"Rihal v2"`  
+**Written by:** `/rihal:install` (reads from config.yaml)  
+**Purpose:** Project name for context and reports.
+
+---
+
+### `created`
+**Type:** ISO date string  
+**Example:** `"2026-04-01T10:30:00Z"`  
+**Written by:** `/rihal:install` (first session)  
+**Purpose:** Timestamp of project creation, never changes.
+
+---
+
+### `updated`
+**Type:** ISO date string  
+**Example:** `"2026-04-12T15:45:30Z"`  
+**Written by:** Any command that modifies state  
+**Purpose:** Last write timestamp; aids session recovery.
+
+---
+
+### `current_phase`
+**Type:** string or null  
+**Example:** `"Phase 2: Authentication"` or `null`  
+**Written by:** `/rihal:do`, `/rihal:next`, `/rihal:resume-work`  
+**Purpose:** Name of active phase, null if no phase active.
+
+---
+
+### `current_plan`
+**Type:** number  
+**Example:** `2`  
+**Written by:** `/rihal:do --execute` (incremented after each phase completion)  
+**Purpose:** Counter for plan versions. Increments 1→2→3 as phases complete.
+
+---
+
+### `phases`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "number": 1,
+    "name": "Setup & Scaffolding",
+    "started": "2026-04-01T10:30:00Z",
+    "completed": "2026-04-03T14:20:00Z",
+    "sprints": [
+      {
+        "id": "01.1",
+        "number": 1,
+        "goal": "Project structure + CI",
+        "status": "completed",
+        "velocity_target": 13,
+        "velocity_actual": 11,
+        "started_at": "2026-04-01T10:30:00Z",
+        "completed_at": "2026-04-02T18:00:00Z",
+        "stories": [
+          {
+            "id": "01.1.01",
+            "title": "Initialize repo with standard layout",
+            "points": 3,
+            "status": "done",
+            "acceptance": "Repo has src/, tests/, CI config"
+          },
+          {
+            "id": "01.1.02",
+            "title": "Setup CI pipeline",
+            "points": 5,
+            "status": "done",
+            "acceptance": "PR checks run lint + test"
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+**Written by:** `/rihal:do --execute`, `/rihal:next`, sprint/story state tools  
+**Purpose:** Tracks phases with nested sprints and stories.
+
+**Sprint fields:**
+- `id` — `{NN}.{S}` (phase.sprint)
+- `goal` — one-sentence sprint focus
+- `status` — `planned | active | completed`
+- `velocity_target` — estimated story points
+- `velocity_actual` — actual points completed (set on sprint complete)
+- `stories[]` — array of story objects
+
+**Story fields:**
+- `id` — `{NN}.{S}.{TT}` (phase.sprint.story)
+- `title` — story description
+- `points` — story points (0 = unestimated)
+- `status` — `todo | in_progress | review | done`
+- `acceptance` — acceptance criteria (optional)
+
+---
+
+### `velocity_history`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  { "sprint": "01.1", "points": 11, "completed_at": "2026-04-02T18:00:00Z" },
+  { "sprint": "01.2", "points": 13, "completed_at": "2026-04-05T16:00:00Z" }
+]
+```
+**Written by:** `sprint complete` state tool  
+**Purpose:** Rolling velocity log. Used to calculate average velocity for sprint capacity planning.
+
+---
+
+### `current_sprint`
+**Type:** string (nullable)  
+**Example:** `"01.1"`  
+**Written by:** `sprint add`, `sprint start`, `sprint complete`  
+**Purpose:** Currently active sprint. Null when no sprint in progress.
+
+---
+
+### `executions`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "plan": "01.02",
+    "tasks": 3,
+    "duration_ms": 3600000,
+    "commit_hash": "abc123def456",
+    "committed_at": "2026-04-03T14:20:00Z"
+  }
+]
+```
+**Written by:** `/rihal:execute` (after each plan completes)  
+**Purpose:** Log of each plan execution. The `plan` field is the plan ID string (e.g., "01.02"), not a number.
+
+---
+
+### `decisions`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "summary": "Use JWT instead of session cookies",
+    "phase": "Phase 2",
+    "plan": 1,
+    "date": "2026-04-04T09:15:00Z"
+  }
+]
+```
+**Written by:** `/rihal:council`, `/rihal:discuss`  
+**Purpose:** Records architectural/strategic decisions for history.
+
+---
+
+### `blockers`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "description": "API rate limit blocks load testing",
+    "phase": "Phase 3",
+    "plan": 1,
+    "date": "2026-04-05T11:00:00Z",
+    "resolved": "2026-04-05T13:30:00Z"
+  }
+]
+```
+**Written by:** `/rihal:do`, `/rihal:health`  
+**Purpose:** Tracks blockers, when identified, which phase, and resolution time.
+
+---
+
+### `council_sessions`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "date": "2026-04-04T10:00:00Z",
+    "question_slug": "auth-strategy",
+    "panel": ["rihal-sadiq", "rihal-waleed", "rihal-fatima"],
+    "artifact_path": "rihal/artifacts/council-sessions/auth-strategy-20260404.md"
+  }
+]
+```
+**Written by:** `/rihal:council`  
+**Purpose:** History of council deliberations, panelists, output artifacts.
+
+---
+
+### `chains`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "date": "2026-04-05T14:00:00Z",
+    "slug": "implement-login-flow",
+    "agents": ["rihal-waleed", "rihal-fatima"],
+    "artifacts_dir": "rihal/artifacts/chains/implement-login-flow-20260405"
+  }
+]
+```
+**Written by:** `/rihal:chain`  
+**Purpose:** History of multi-agent chains, participants, work artifacts.
+
+---
+
+### `last_session`
+**Type:** ISO date string  
+**Example:** `"2026-04-12T15:45:30Z"`  
+**Written by:** Every subcommand that runs (updates at session end)  
+**Purpose:** Enables `/rihal:resume-work` to find context from last session.
+
+---
+
+### `workstreams`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "name": "Frontend",
+    "created": "2026-04-01T10:30:00Z",
+    "active": true,
+    "completed": null,
+    "phases": [1, 2, 3]
+  },
+  {
+    "name": "Backend API",
+    "created": "2026-04-02T09:00:00Z",
+    "active": true,
+    "completed": null,
+    "phases": [1, 2, 4]
+  }
+]
+```
+**Written by:** `/rihal:workstream --create`, `/rihal:do --execute`  
+**Purpose:** Tracks parallel workstreams, which phases belong to each.
+
+---
+
+### `active_workstream`
+**Type:** string or null  
+**Example:** `"Frontend"` or `null`  
+**Written by:** `/rihal:workstream --activate`, `/rihal:do`  
+**Purpose:** Currently active workstream; null if no workstream focus.
+
+---
+
+### `model_profile`
+**Type:** string  
+**Example:** `"balanced"` (options: `quality`, `balanced`, `budget`, `inherit`)  
+**Written by:** `/rihal:set-profile`  
+**Purpose:** Model selection for council agents. Affects token spend and quality.
+
+---
+
+## Usage Examples
+
+### Reading Phase Progress
+```python
+current_phase = state['current_phase']
+completed_phases = [p for p in state['phases'] if p['completed'] is not None]
+progress = f"{len(completed_phases)}/{len(state['phases'])} phases complete"
+```
+
+### Checking for Blockers
+```python
+unresolved_blockers = [b for b in state['blockers'] if b['resolved'] is None]
+if unresolved_blockers:
+    print(f"⚠️ {len(unresolved_blockers)} open blockers")
+```
+
+### Resuming Session
+```python
+last_session = state['last_session']
+current_phase = state['current_phase']
+# Provide context: "Last session: {last_session}. Phase: {current_phase}"
+```
+
+### Tracking Decisions
+```python
+phase_decisions = [d for d in state['decisions'] if d['phase'] == current_phase]
+print(f"Decisions made in {current_phase}:")
+for d in phase_decisions:
+    print(f"  - {d['summary']}")
+```
+
+---
+
+## ID Formats Accepted by resolve-id
+
+The `state resolve-id <id>` command accepts the following formats:
+
+| Format | Example | Resolves To | Notes |
+|--------|---------|-------------|-------|
+| `M{N}` | `M1`, `M2` | Milestone N | Lowercase or uppercase M |
+| `{NN}` | `01`, `02`, `10` | Phase with number NN | Zero-padded two-digit phase number |
+| `{NN.S}` | `01.1`, `02.3` | Sprint S in Phase NN | Sprint within a phase |
+| `{NN.S.TT}` | `01.1.01`, `02.3.05` | Story TT in Sprint NN.S | Three-part hierarchical story ID |
+| `{NN.M}` | `02.1`, `03.2` | Decimal phase (legacy) OR sprint | Context-dependent — prefer sprint interpretation |
+
+**Examples:**
+```bash
+node .rihal/bin/rihal-tools.cjs state resolve-id M1          # → Milestone 1
+node .rihal/bin/rihal-tools.cjs state resolve-id 02          # → Phase 02
+node .rihal/bin/rihal-tools.cjs state resolve-id 01.1        # → Sprint 1 in Phase 01
+node .rihal/bin/rihal-tools.cjs state resolve-id 01.1.03     # → Story 3 in Sprint 01.1
+```
+
+**Sprint state commands:**
+```bash
+node .rihal/bin/rihal-tools.cjs state sprint add --phase 01 --goal "Setup" --velocity 13
+node .rihal/bin/rihal-tools.cjs state story add --title "Login" --points 5
+node .rihal/bin/rihal-tools.cjs state story move --id 01.1.01 --status done
+node .rihal/bin/rihal-tools.cjs state sprint velocity
+```