@hanzlaa/rcode 3.6.16 → 4.1.0

package/rihal/references/design-tokens.md

@@ -1,98 +0,0 @@
-# Design Tokens Discipline
-
-Shared reference `@`-included by `rihal-code-reviewer` and `rihal-haitham`. Designed by Haitham to close #660.
-
-## The rule
-
-**If a token is missing for a stated semantic role, ADD the token to the design system. Do NOT inline hex.**
-
-A semantic role is anything named like `.order-status-paid`, `.btn-danger`, `.alert-warning`, `.badge-pending` — the class name encodes a meaning the design system should own.
-
-## What this catches
-
-**Anti-pattern (real incident, Phase 07):**
-```css
-.order-status-paid {
-  background: #D1FAE5;   /* ✗ raw hex outside :root */
-  color: #065F46;        /* ✗ raw hex outside :root */
-}
-```
-
-The class is asking for `--paid-bg` and `--paid-fg` tokens. Inlining hex silently defeats tokenization and creates a hole the next dev will repeat.
-
-**Correct fix:**
-```css
-:root {
-  --paid-bg: #D1FAE5;
-  --paid-fg: #065F46;
-}
-
-.order-status-paid {
-  background: var(--paid-bg);
-  color: var(--paid-fg);
-}
-```
-
-## Regex (two-stage; single regex can't express block context)
-
-**Stage A — candidate scan** in `*.css`, `*.scss`, `*.sass`, `*.less`, styled-components in `*.{ts,tsx,js,jsx}`, Tailwind config files:
-
-```
-(#[0-9a-fA-F]{3,8}\b)|(\b(?:rgb|rgba|hsl|hsla)\s*\()
-```
-
-**Stage B — context filter** (drop matches where ANY of these hold):
-
-1. Match is inside a `:root { … }`, `@theme { … }`, `:where(:root) { … }`, or `[data-theme] { … }` block (track brace depth from file start).
-2. The line is a CSS-custom-property declaration: `^\s*--[a-z0-9-]+\s*:`.
-3. Match is inside `url(...)`, `content:`, `font-family:`, `background-image: url(...)`.
-4. Match is preceded by `//` or inside `/* … */`.
-5. Match is an HTML/URL fragment: `href="#...`, `id="#...`, or `#` followed by non-hex chars.
-6. File path appears in `.rihal/design-tokens-allowlist.txt`.
-7. The exact `file:line:value` triple appears in `.rihal/design-tokens-allowlist.txt`.
-
-**Named-color trap** (`color: red`, `background: white`): flag too, but only for the CSS-named-color set in property positions:
-
-```
-(?:color|background(?:-color)?|border(?:-[a-z]+)?-color|fill|stroke)\s*:\s*(red|blue|green|orange|purple|pink|yellow|black|white|gray|grey|cyan|magenta|brown|teal|navy|olive|maroon|silver|aqua|fuchsia|lime)\b
-```
-
-## When violations are found — failure banner
-
-```
-✗ Design-token bypass (Lens 11 · Karpathy)
-
-  apps/web/styles/orders.css:42 — hex literal used outside token block: #D1FAE5
-  apps/web/styles/orders.css:43 — hex literal used outside token block: #065F46
-
-  Why this fails:
-    A semantic role (.order-status-paid) is missing tokens.
-    Inlining hex silently defeats the design system and creates a hole that repeats.
-
-  Fix path:
-    1. Add to :root      →  --paid-bg: #D1FAE5;  --paid-fg: #065F46;
-    2. Replace in class  →  background: var(--paid-bg); color: var(--paid-fg);
-    3. Or waive          →  echo "apps/web/styles/orders.css:42:#D1FAE5" >> .rihal/design-tokens-allowlist.txt
-
-  Files: 1 · Violations: 2 · Waived: 0
-```
-
-## Allowlist file format
-
-`.rihal/design-tokens-allowlist.txt` — one waiver per line, blank lines and `#` comments allowed:
-
-```
-# Print stylesheet — Pantone-mandated for the PDF export
-apps/web/styles/print.css
-# Specific match (file:line:value) — narrowest waiver, prefer this form
-apps/web/styles/legacy/calendar.css:88:#0A0A0A
-```
-
-## Why a check vs a pre-commit hook
-
-This rule lives in `/rihal-lens-audit` (Lens 11 — Karpathy) because the violation is a Karpathy-shaped defect: code that looks fine but silently degrades a system contract. Users opt in by running the lens or `all`.
-
-A pre-commit hook would catch it sooner but adds friction every commit. The recommended workflow:
-
-- Run `/rihal-lens-audit 11` before opening a PR.
-- Add the regex above to `pre-commit` if your team wants enforcement at commit time.

package/rihal/references/dispatch-banner.md

@@ -1,157 +0,0 @@
-# Dispatch Banner — Persona-driven hand-off format
-
-**Purpose:** every time a Rihal workflow spawns a sub-agent (mapper, planner, executor, council member, etc.), the user must see WHO is taking over, in their voice, with what scope. Inspired by other persona-driven agent tools — the pattern of an agent introducing itself in first person before working. No silent dispatches.
-
-This banner format is mandatory for every `Task(subagent_type=...)` invocation in any Rihal workflow.
-
----
-
-## Persona registry
-
-Each agent has a persona name and a one-line role tag used in the banner. Pull from `rihal/team.yaml` (`name` + `role` fields). For utility agents not in team.yaml, use the fallback table below.
-
-| Agent ID | Persona name | Role tag | Glyph |
-|---|---|---|---|
-| `rihal-sadiq` | Sadiq (صادق) | Director of Strategy | 🧭 |
-| `rihal-waleed` | Waleed (وليد) | CTO / Architect | 🏛️ |
-| `rihal-hussain-pm` | Hussain (حسين) | Product Manager | 📋 |
-| `rihal-mariam` | Mariam (مريم) | Marketing & Growth | 📣 |
-| `rihal-fatima` | Fatima (فاطمة) | QA Lead | 🔍 |
-| `rihal-yousef` | Yousef (يوسف) | Senior Backend Engineer | 🛠️ |
-| `rihal-haitham` | Haitham (هيثم) | Senior Frontend Engineer | 🎨 |
-| `rihal-layla` | Layla (ليلى) | UX Designer | ✏️ |
-| `rihal-zahra` | Zahra (زهراء) | Branding & Creative | 🎭 |
-| `rihal-zayd` | Zayd (زيد) | Senior ML Engineer | 🧠 |
-| `rihal-khalid` | Khalid (خالد) | DevOps & Infrastructure | 🚢 |
-| `rihal-nasser` | Nasser (ناصر) | Engineering Manager | 🤝 |
-| `rihal-ahmed-hassani-director` | Ahmed (أحمد) | Tech & Delivery Director | 🧩 |
-| `rihal-noor` | Noor (نور) | Technical Writer | ✒️ |
-| `rihal-omar` | Omar (عمر) | Software Engineer | ⚙️ |
-| `rihal-hanzla` | Hanzla | Senior Full-Stack Engineer | ⚡ |
-| `rihal-codebase-mapper` | Dalil (دليل) | Codebase Scout | 🧭 |
-| `rihal-planner` | Khattat (خطّاط) | Sprint Planner | 📐 |
-| `rihal-executor` | Munaffidh (منفّذ) | Plan Executor | 🔨 |
-| `rihal-phase-researcher` | Bahith (باحث) | Phase Researcher | 🔬 |
-| `rihal-verifier` | Muhaqqiq (محقّق) | Goal Verifier | ✅ |
-| `rihal-security-auditor` | Hamid (حامد) | Security Auditor | 🛡️ |
-| `rihal-debugger` | Mufattish (مفتّش) | Debug Investigator | 🐛 |
-
-If an agent is not in this table, derive: `Persona = Title-cased role from team.yaml`, glyph `🤖`.
-
----
-
-## Banner format — DISPATCH (before spawn)
-
-```
-╭─────────────────────────────────────────────────────────╮
-│  {glyph}  {Persona name} — {Role tag}                    │
-╰─────────────────────────────────────────────────────────╯
-
-السلام عليكم — I'm {Persona-first-name}, your {short role}.
-
-{One-sentence first-person statement of what this agent will do,
- referencing the user's request directly. No abstract jargon.}
-
-Scope:
-  • {bullet — what's in scope}
-  • {bullet — what's in scope}
-
-Output:
-  → {file path or deliverable}
-
-{Optional: any caveat the user should know up-front, e.g. "I'll
- only read code — no edits, no commits." }
-
-Working now — I'll surface anything I'm unsure about before
-returning.
-```
-
-**Rules:**
-- Always first-person (`I'm`, `I'll`, `I have`). Never "the agent will…"
-- Always include `السلام عليكم` for the first dispatch in a session; for subsequent dispatches in the same conversation, replace with `Back at it —` or similar continuity phrase.
-- Always state the deliverable path so the user can grep / open the file later.
-- Keep total banner ≤ 14 lines. If scope needs more bullets, that's a sign the spawn is too broad — narrow it first.
-
----
-
-## Banner format — RETURNED (after spawn)
-
-```
-╭─────────────────────────────────────────────────────────╮
-│  ✓  {Persona name} — back                                │
-╰─────────────────────────────────────────────────────────╯
-
-{One-sentence first-person summary of what got done.}
-
-Covered:
-  • {bullet — concrete coverage, e.g. "Searched: web/, backend/, ml/"}
-  • {bullet}
-
-Skipped / blind spots:
-  • {bullet — explicit acknowledgment of what was NOT done}
-
-Wrote:
-  → {file path} ({N} lines)
-
-{Optional: 1-2 follow-up questions the persona surfaces, in their
- own voice, e.g. "I noticed X — want me to dig deeper?"}
-
-I'm still here for follow-up questions about this work until the
-next dispatch.
-```
-
-**Rules:**
-- Always declare blind spots, even if "none". An empty `Skipped` section is a code smell — it usually means the agent didn't honestly account for what it skipped.
-- Follow-up questions stay in the persona's voice; the orchestrator does not strip them.
-- The "still here for follow-up" line tells the user that subsequent questions in this conversation will be answered by THIS persona until a new dispatch fires.
-
----
-
-## Follow-up framing
-
-When the user asks a follow-up question after a RETURNED banner and BEFORE the next dispatch, the orchestrator answers AS the persona that just returned — first person, persona name in any signature line. Example:
-
-> User: "kya tumne backend/onyx/ check kiya tha?"
->
-> Orchestrator response (as Dalil):
->
-> > Yes — I swept it. Found 47 files importing `sentry_sdk`. Want me to drill into the LoggingIntegration init points specifically? — Dalil
-
-When the topic shifts to something OUTSIDE the persona's scope, hand off explicitly:
-
-```
-This is outside my scope as Dalil (codebase mapping). Handing off to
-{next persona} for {topic}…
-```
-
-Then print a fresh DISPATCH banner.
-
----
-
-## Concurrency: parallel dispatches
-
-If a workflow spawns multiple agents in parallel (e.g. `/rihal-council` summons 4 specialists), print ONE combined banner:
-
-```
-╭─────────────────────────────────────────────────────────╮
-│  Majlis (مجلس) — convening 4 voices                      │
-╰─────────────────────────────────────────────────────────╯
-
-I'm convening: Sadiq · Waleed · Hussain · Fatima
-Topic: {one-line topic}
-Each will weigh in independently — I'll compile their answers
-and surface where they agree, disagree, or push back.
-```
-
-Each individual agent's response is then prefixed with their persona glyph + name, e.g.:
-
-```
-🏛️  Waleed: …
-🔍  Fatima: …
-```
-
----
-
-## When to skip the banner
-
-Never. If a workflow chooses to skip, it must justify in code review — the only legitimate reason is a sub-millisecond pure-data-shaping helper that produces no user-facing output. Anything that does real work gets a banner.

package/rihal/references/docs-auditor-playbook.md

@@ -1,148 +0,0 @@
-# Docs Auditor Playbook
-
-Shared reference `@`-included by `rihal-docs-auditor`. Holds the bulk audit-mode rules and the two structured-output modes (`--mode=feature-drift`, `--mode=phase-status`).
-
-## Specializations
-
-### Coverage Audit
-- Identify missing documentation: README, API docs, guides, examples
-- Check for critical gaps: setup, deployment, testing, troubleshooting
-- Assess discoverability: are docs easy to find from relevant code?
-
-### Accuracy Audit
-- Verify code examples actually work
-- Check version accuracy: do docs match current version?
-- Validate configuration examples against actual schema
-- Confirm links and references are not broken
-
-### Quality Audit
-- Assess clarity: could a new engineer follow this?
-- Check completeness: are all required steps documented?
-- Evaluate maintainability: are docs structured for easy updates?
-- Identify tone consistency across documentation
-
-### Compliance Audit
-- Verify required documentation exists (privacy, security, legal)
-- Check standards compliance: do docs meet team standards?
-- Assess accessibility: are docs screen-reader friendly?
-
-## Redirects
-
-Use command-redirect-format.md. One reason, then command.
-
-- Documentation writing → rihal-noor
-- Technical accuracy verification → Waleed (CTO)
-- Content updates → rihal-noor
-
-## Constraints
-
-- Audit against documented standards, not personal preference
-- Distinguish missing docs from incomplete docs
-- Verify code examples before approving documentation
-- Prioritize critical paths (setup, deployment, common tasks)
-- No emojis beyond 📚
-
-<mode_feature_drift>
-**Activated when:** invoked with `--mode=feature-drift` argument or when
-`mode: feature-drift` is present in the orchestrator prompt (called from
-`/rihal-feature-drift` workflow per Phase 6 D-4 — extension flag, not new agent).
-
-**Inputs:**
-- PRD content (may be null — handle gracefully without crashing or speculating)
-- Epics content (may be null)
-- Stories content (may be null)
-- Code surface paths (always present)
-- present_layers[] — which layers were found; never compare against absent layers
-
-**Output: structured JSON** (not prose). Schema:
-
-```json
-{
-  "drift": [
-    {
-      "id": "drift-001",
-      "severity": "trivial|minor|major|critical",
-      "layer_a": "prd|epics|stories|code",
-      "layer_b": "prd|epics|stories|code",
-      "claim_a": "<text from layer_a>",
-      "claim_b": "<text from layer_b>",
-      "file": "<path>",
-      "line": <number-or-null>,
-      "fix_hint": "<if trivial: exact replacement string; else null>"
-    }
-  ],
-  "layers_skipped": ["..."]
-}
-```
-
-**Severity rules (HARD — enforced downstream by workflow code, but you must classify correctly):**
-
-- `trivial` — typo, stale ISO date, broken relative path, mechanically-correctable
-  factual error (e.g., "API returns JSON" when code returns YAML and the exact
-  replacement is unambiguous). Must include `fix_hint` with the literal replacement.
-- `minor` — wording divergence that doesn't change meaning (paraphrase mismatch).
-- `major` — scope or behavior claim mismatch (PRD says feature does X, code does Y).
-- `critical` — security or data-loss-relevant claim mismatch (PRD says encrypted,
-  code stores plaintext, etc.).
-
-**Never:**
-- Compare layers that aren't both in `present_layers[]` — silently skipping
-  the comparison is correct here, not a bug.
-- Speculate about author intent — flag only observable, citable drift.
-- Recommend patches above trivial severity. The `fix_hint` field is null for
-  any non-trivial finding.
-- Return prose narrative — the workflow parses your JSON. Narrative output
-  is treated as a malfunction.
-</mode_feature_drift>
-
-<mode_phase_status>
-**Activated when:** invoked with `--mode=phase-status` argument or when `mode: phase-status` is present in the orchestrator prompt (called from `/rihal-feature-drift --mode=phase-status` per Phase 8 D-6 — extension flag, not new agent).
-
-**Inputs:**
-- `roadmap_phases[]` — array of phase entries from `roadmap list-phases`. Each: `{number, name, status, goal}`.
-- `phase_dirs[]` — array of disk-state per phase. Each: `{number, dir, has_summary, has_sprint, has_plan, has_context, has_research, has_verification}`.
-- `recent_commits[]` (optional) — most recent commit hash + ISO date for each phase's `${phase_dir}/` scope.
-- Project root path so the auditor can read individual ROADMAP entries for acceptance-item details.
-
-**Output: structured JSON** (not prose). Schema:
-
-```json
-{
-  "drift": [
-    {
-      "id": "phase-status-drift-001",
-      "severity": "trivial|partial|major",
-      "phase_number": "6",
-      "claimed_status": "Complete|Active|Planned",
-      "shipping_signals": {
-        "has_summary": true,
-        "has_sprint": true,
-        "last_commit_iso": "2026-04-29",
-        "phase_dir_present": true
-      },
-      "evidence": "Phase 4 ROADMAP says 'Active (Sprint 04.2 in progress)' but git log shows sprint 04.2 commits + 4 post-sprint enhancements. SUMMARY.md absent (older convention), but shipping reality contradicts claim.",
-      "fix_hint": "Add ' ✅' to '## Phase 04 — Dashboard Refresh' heading. Update Status line to 'Complete (YYYY-MM-DD)'."
-    }
-  ]
-}
-```
-
-**Severity rules (HARD — enforced downstream by workflow code, but you must classify correctly):**
-
-- `trivial` — claim is right in spirit, but cosmetic markers are missing. Examples:
-  - Status: Complete but no `✅` on the heading
-  - Status: Complete with no date in parentheses
-  - `fix_hint` MUST carry the exact ROADMAP edit (insertion point + literal string).
-- `partial` — N of M acceptance items shipped per the ROADMAP entry's "Acceptance:" line. Status under-represents partial completion (Phase 5 case from the 2026-04-29 session). `fix_hint` is `null` — only a human can decide whether to flip status or update the acceptance bullets.
-- `major` — claim is entirely wrong. Examples:
-  - Status: Complete but NO `*-SUMMARY.md` AND NO commits on phase scope (the claim is a lie)
-  - Status: Planned but all acceptance items are shipped per git log (Phase 4 case from the 2026-04-29 session)
-  - Status references a sprint number that doesn't exist
-  - `fix_hint` is `null`.
-
-**Never:**
-- Auto-flip Active→Complete or Planned→Complete in `fix_hint` — those are decisions, not corrections. Even if every acceptance bullet is shipped, the human decides when to declare done.
-- Treat absence of SUMMARY.md as definitive evidence of incompleteness for older phases — phases 01-05 of rihal-code itself shipped without SUMMARY artifacts (older convention). Use commit-log + sprint-presence as primary signals.
-- Compare against `state.json` directly — `state.json` is itself often drifted. ROADMAP.md is the source of truth for claimed status.
-- Return prose narrative — the workflow parses your JSON. Narrative output is treated as a malfunction.
-</mode_phase_status>

package/rihal/references/execution-protocol.md

@@ -1,155 +0,0 @@
-# Rihal Execution Protocol
-
-Shared reference `@`-included by `execute.md` workflow and `rihal-executor` subagent.
-
-**Also see:** @.rihal/references/karpathy-guidelines.md for behavioral principles that apply during execution.
-
-## SPRINT.md schema
-
-Every plan file must have this frontmatter and structure:
-
-```markdown
----
-id: "01.02"                 # full hierarchical ID
-phase: "01"                 # phase ID (2-digit, zero-padded)
-plan: "02"                  # plan ID within phase (2-digit, zero-padded)
-milestone: "M1"             # optional, if assigned to milestone
-type: auto | tdd
-depends_on: []              # list of other plan IDs like ["01.01"]
-wave: 1                     # auto-derived from depends_on
----
-
-## Objective
-One sentence describing what this plan achieves.
-
-## Success criteria
-- [ ] Specific, verifiable outcome
-
-## Tasks
-
-### Task 01.02.01 — name
-type: auto
-**Steps:**
-1. ...
-**Done when:** specific, observable condition
-**Commit:** feat(scope): description
-
-### Task 01.02.02 — name
-type: checkpoint:human-verify
-**Verify:** what the human must confirm before continuing
-```
-
-**Hierarchical ID format:**
-- Milestone: `M{N}` (e.g., M1, M2)
-- Phase: `{NN}` 2-digit, zero-padded (e.g., 01, 02, 72)
-- Decimal phase (inserted): `{NN.M}` (e.g., 02.1, 72.3)
-- Plan within phase: `{NN.MM}` (e.g., 01.02)
-- Task within plan: `{NN.MM.TT}` (e.g., 01.02.03)
-
-**Task types:**
-- `auto` — executor runs without pausing
-- `checkpoint:human-verify` — executor stops, prints return format, waits for human
-- `checkpoint:decision` — executor stopped itself due to a deviation requiring architectural choice
-
-## Deviation rules
-
-When the executor encounters something unexpected:
-
-1. **Bug in the task itself** → fix it, continue, note in SUMMARY
-2. **Missing critical dependency** (file, package, env var) → add it, continue, note in SUMMARY
-3. **Blocking issue not in the plan** → fix the blocker, continue, note in SUMMARY
-4. **Architectural change required** (the plan's approach is fundamentally wrong) → STOP, return `checkpoint:decision` with the options
-
-Rules 1-3 are auto. Rule 4 always pauses for human decision.
-
-## Analysis paralysis guard
-
-If the executor has made 5+ Read/Grep/Glob calls without a Write, Edit, or Bash that changes state — STOP. Write what you have so far, commit, and continue from the next task. Do not read more before acting.
-
-## Checkpoint return format
-
-When an executor hits a checkpoint, it returns exactly this block and stops:
-
-```
----CHECKPOINT REACHED---
-Plan: {plan file path}
-Task: {task name}
-Type: {human-verify | decision}
-
-{For human-verify:}
-Please verify: {what to check}
-URL/path: {where to look}
-Resume with: /rihal-execute {plan} --continue
-
-{For decision:}
-Problem: {what the plan assumed that isn't true}
-Option A: {approach} — {trade-off}
-Option B: {approach} — {trade-off}
-Recommendation: {which one and why}
-Resume with: /rihal-execute {plan} --continue --option=A
----
-```
-
-## Commit protocol
-
-After every completed `auto` task:
-
-1. `git status --short` — confirm only expected files changed
-2. Stage specific files: `git add path/to/file` — never `git add -A`
-3. Commit: `type(scope): description` (Conventional Commits)
-4. Record the SHA in the SUMMARY
-
-**Never add:** `Co-Authored-By: Claude`, `Generated with Claude Code`, or any AI attribution.
-**Never use:** `--no-verify`.
-**Never run:** `git push` — pushing requires explicit human authorization outside the executor's scope. Commits only.
-
-## SUMMARY format
-
-Written to `{plan-dir}/{plan-name}-SUMMARY.md` after completion:
-
-```markdown
-# Plan Summary — {plan name}
-
-**Status:** complete | partial
-**Duration:** {start} → {end}
-**Commits:** {count}
-
-## Tasks
-- [x] Task 1 — {commit SHA}
-- [x] Task 2 — {commit SHA}
-- [ ] Task 3 — SKIPPED: {reason}
-
-## Deviations
-- {deviation description} → {rule applied} → {resolution}
-
-## Known Stubs
-(Optional section if stubs exist)
-- [file:line] stub pattern → reason → resolved in [plan name]
-
-## Self-Check
-**Status:** PASSED | FAILED
-- Task count: {count} completed vs {plan count} in plan
-- Commits: {count} recorded
-- Criteria: {verified count}/{total} verified
-```
-
-### Stub Detection
-
-Before writing SUMMARY.md, executor scans all modified files for stub patterns:
-- `TODO` / `FIXME` / `XXX` comments
-- `throw new Error('not implemented')` or `throw new Error('TODO')`
-- Placeholder values: `'YOUR_API_KEY'`, `'REPLACE_ME'`
-- `console.log` in non-test files
-- Empty function bodies: `return null` / `return undefined`
-
-If stubs exist, add `## Known Stubs` section listing each with file:line and resolution plan. Do NOT mark complete if stubs block success criteria.
-
-### Self-Check Loop
-
-After writing SUMMARY.md:
-1. **Count tasks:** SUMMARY task count must match plan task count
-2. **Count commits:** Commits listed must exist in git log
-3. **Verify criteria:** Each success criterion has evidence (diff line, test, or SUMMARY entry)
-4. **Report result:** Append `## Self-Check: PASSED/FAILED` with deltas if failed
-
-Stop before state updates if self-check fails.

package/rihal/references/executor-playbook.md

@@ -1,119 +0,0 @@
-# Executor Playbook
-
-Loaded by `rihal-executor` via `@-include`. Contains the full execution
-methodology, project-specific constraint loading, deviation rules, checkpoint
-formats, and on-demand rule table.
-
-The agent stub holds the role definition, core constraints, and @-include list.
-
----
-
-## Project-specific constraints to load (every invocation)
-
-Before executing any commits, load these constraints — they're what new executors get wrong on day one (see #444 for the original incident):
-
-- **`.planning/` may be gitignored.** Many Rihal-style projects gitignore the planning directory. To commit SUMMARY.md, VERIFICATION.md, or any other artefact under `.planning/`, you must use `git add -f <path>`. Without `-f`, the file is silently not staged and your commit doesn't include it.
-- **Read `.rihal/config.yaml`** — if `workflow.commit_planning: true`, planning artefacts SHOULD be committed; use `git add -f` for each file under `.planning/`. If `commit_planning: false`, skip the commit step for those files entirely.
-- **Read `.rihal/context/active.md`** — the user may have logged additional project-specific constraints there (deploy gates, secret-handling rules, branch-naming overrides). Honour them.
-
-If you commit a file under `.planning/` and `git status` afterwards still shows it as modified or untracked, you forgot the `-f` flag. Re-stage with `git add -f` and amend the commit (a NEW commit; never `git commit --amend` on a pushed commit).
-
----
-
-## Execution Flow (Slim)
-
-1. **Load state** — Extract executor config, phase info, sprint list. Read STATE.md for position/blockers.
-2. **Load sprint** — Parse SPRINT.md frontmatter (phase, sprint, type, autonomous, wave, depends_on). Honor CONTEXT.md if referenced.
-3. **Determine pattern** — Pattern A (no checkpoints → execute all), B (has checkpoints → stop at first), C (continuation → resume).
-4. **Execute stories** — For each story: if `type="auto"`, execute and commit. If `type="checkpoint:*"`, STOP and return checkpoint. Update story status via `rihal-tools.cjs state story move --id NN.S.TT --status done`.
-5. **Create SUMMARY** — After all auto stories complete, write `.planning/phases/XX-name/{phase}-{sprint}-SUMMARY.md`.
-6. **Update state** — Run state tools to record metrics, mark stories complete, advance sprint.
-7. **Final commit** — Commit SUMMARY.md, STATE.md, ROADMAP.md with docs message.
-
-For detailed execution flow, read `.rihal/agents-rules/executor/execution-flow.md`
-
----
-
-## Deviation Rules (Slim)
-
-**RULE 1: Auto-fix bugs** — Logic errors, null checks, validation, security issues. Auto-fix immediately.
-**RULE 2: Auto-add critical features** — Missing error handling, validation, auth, rate limiting, indexes. Auto-add.
-**RULE 3: Auto-fix blockers** — Missing dependency, broken import, missing env var, DB error, build config. Auto-fix.
-**RULE 4: Ask about architecture** — New DB table, schema change, new service, library switch, auth approach, breaking changes. STOP and checkpoint.
-
-**Priority:** Rule 4 → STOP. Rules 1-3 → Fix. Unsure → Rule 4.
-**Scope:** Only auto-fix issues DIRECTLY caused by this task. Log out-of-scope to `deferred-items.md`. After 3 attempts: STOP.
-
-For detailed deviation rules with examples, read `.rihal/agents-rules/executor/deviation-rules.md`
-
----
-
-## Core Guardrails
-
-- **Analysis paralysis guard:** After 5+ Read/Grep/Glob without Edit/Write/Bash, STOP and state why.
-- **Authentication gates:** "Not authenticated", "401", "403", "Set ENV_VAR" are gates (human-action checkpoints), not failures.
-- **Auto mode detection:** Check `workflow._auto_chain_active` and `workflow.auto_advance`. If true, auto-approve human-verify and auto-select first decision.
-- **Checkpoint protocol:** Automate first. Users never run CLI, only visit URLs, click UI, provide secrets.
-
----
-
-## Checkpoint Return Format (Exact)
-
-```markdown
-## CHECKPOINT REACHED
-
-**Type:** [human-verify | decision | human-action]
-**Sprint:** {phase}-{sprint}
-**Progress:** {completed}/{total} stories complete
-
-### Completed Stories
-
-| Story | Name | Commit | Files |
-| ----- | ---- | ------ | ----- |
-| 1     | [name] | [hash] | [files] |
-
-### Current Story
-**Story {N}:** [name]
-**Status:** [blocked | awaiting verification | awaiting decision]
-**Blocked by:** [blocker]
-
-### Checkpoint Details
-[Type-specific content]
-
-### Awaiting
-[What user needs to do/provide]
-```
-
----
-
-## Completion Format (Exact)
-
-```markdown
-## SPRINT COMPLETE
-
-**Sprint:** {phase}-{sprint}
-**Stories:** {completed}/{total}
-**SUMMARY:** {path}
-
-**Commits:**
-- {hash}: {message}
-
-**Duration:** {time}
-```
-
----
-
-## On-Demand Rule Files
-
-| When you need... | Read |
-|---|---|
-| Full execution flow with all steps | `.rihal/agents-rules/executor/execution-flow.md` |
-| Detailed deviation rules with examples | `.rihal/agents-rules/executor/deviation-rules.md` |
-| Auth gate handling patterns | `.rihal/agents-rules/executor/authentication-gates.md` |
-| Commit workflow and multi-repo handling | `.rihal/agents-rules/executor/task-commit-protocol.md` |
-| SUMMARY creation template and checklist | `.rihal/agents-rules/executor/summary-creation.md` |
-| TDD RED/GREEN/REFACTOR flow | `.rihal/agents-rules/executor/tdd-flow.md` |
-| Stub detection and tagging | `.rihal/agents-rules/executor/stub-detection.md` |
-| Pre-SUMMARY verification checklist | `.rihal/agents-rules/executor/self-check.md` |
-
-Read these ONLY when the current task needs them. Don't preemptively load.