@hanzlaa/rcode 3.4.32 → 3.5.0

package/rihal/commands/create-prd.md

@@ -0,0 +1,18 @@
+---
+name: rihal-create-prd
+description: "Create a Product Requirements Document from scratch through guided facilitation. Use when starting a new project or feature that needs a PRD before architecture or phases."
+argument-hint: "[topic]"
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+<objective>
+Execute create-prd workflow
+</objective>
+
+<execution_context>
+@.rihal/workflows/create-prd.md
+</execution_context>
+
+<process>
+Execute the create-prd workflow from @.rihal/workflows/create-prd.md end-to-end.
+</process>

package/rihal/commands/execute-milestone.md

@@ -0,0 +1,18 @@
+---
+name: rihal-execute-milestone
+description: Execute all phases in the current milestone in dependency order, with verify gates between phases. Closes #738.
+argument-hint: "[--milestone <name>] [--dry-run] [--skip-verify] [--wave N] [--phase N]"
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent, TaskCreate, TaskUpdate
+---
+
+<objective>
+Execute all phases in the current milestone in dependency order, with verify gates between waves.
+</objective>
+
+<execution_context>
+@.rihal/workflows/execute-milestone.md
+</execution_context>
+
+<process>
+Execute the execute-milestone workflow from @.rihal/workflows/execute-milestone.md end-to-end.
+</process>

package/rihal/commands/plan-milestone.md

@@ -0,0 +1,18 @@
+---
+name: rihal-plan-milestone
+description: Plan all phases in a milestone in parallel dependency waves. Reads ROADMAP.md, groups phases into dependency waves, spawns rihal-planner agents in parallel per wave. Closes #732.
+argument-hint: "[--milestone <name>] [--dry-run] [--skip-research] [--wave N]"
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent, TaskCreate, TaskUpdate
+---
+
+<objective>
+Plan all phases for a milestone using parallel dependency-wave execution. Group independent phases into concurrent waves, run rihal-planner for each in parallel.
+</objective>
+
+<execution_context>
+@.rihal/workflows/plan-milestone.md
+</execution_context>
+
+<process>
+Execute the plan-milestone workflow from @.rihal/workflows/plan-milestone.md end-to-end.
+</process>

package/rihal/commands/scaffold-milestone.md

@@ -0,0 +1,18 @@
+---
+name: rihal-scaffold-milestone
+description: Bulk-create all phase directories for a milestone from a pipe-separated name list or ROADMAP.md planned phases. Closes #731.
+argument-hint: "--names \"Phase Name 1|Phase Name 2|...\" [--start N]"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<objective>
+Execute scaffold-milestone workflow
+</objective>
+
+<execution_context>
+@.rihal/workflows/scaffold-milestone.md
+</execution_context>
+
+<process>
+Execute the scaffold-milestone workflow from @.rihal/workflows/scaffold-milestone.md end-to-end.
+</process>

package/rihal/commands/scaffold-skill.md

@@ -0,0 +1,18 @@
+---
+name: rihal-scaffold-skill
+description: "Scaffold a new compliant SKILL.md file for a Rihal role. Eliminates the friction of finding the right folder, copying an existing skill, and chasing 5-component compliance. Use when adding a new role-specific skill."
+argument-hint: "--role <role> --name <skill-name>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<objective>
+Execute scaffold-skill workflow
+</objective>
+
+<execution_context>
+@.rihal/workflows/scaffold-skill.md
+</execution_context>
+
+<process>
+Execute the scaffold-skill workflow from @.rihal/workflows/scaffold-skill.md end-to-end.
+</process>

package/rihal/references/REFERENCES_INDEX.md

@@ -21,8 +21,10 @@ These files were extracted from heavy agents (>100L) to reduce context budget pe
 | `code-reviewer-playbook.md` | rihal-code-reviewer |
 | `codebase-mapping-process.md` | rihal-codebase-mapper |
 | `debugger-playbook.md` | rihal-debugger |
+| `docs-auditor-playbook.md` | rihal-docs-auditor |
 | `executor-playbook.md` | rihal-executor |
 | `integration-verification-playbook.md` | rihal-integration-checker |
+| `nyquist-auditor-playbook.md` | rihal-nyquist-auditor |
 | `persona-engineer-shared.md` | rihal-haitham, rihal-omar, rihal-yousef |
 | `planner-playbook.md` | rihal-planner |
 | `remediation-planner-playbook.md` | rihal-remediation-planner |
@@ -52,16 +54,56 @@ These files were extracted from heavy agents (>100L) to reduce context budget pe
 | File | Loaded by |
 |------|-----------|
 | `auto-init-guard.md` | workflows/council.md, workflows/do.md, workflows/execute.md, workflows/new-project.md, workflows/plan.md, workflows/status.md |
+| `git-preflight.md` | workflows/code-review-fix.md, workflows/dev-story.md, workflows/execute.md, workflows/quick.md |
 | `output-format.md` | workflows/autonomous.md, workflows/council.md, workflows/decisions.md, workflows/discuss.md, workflows/do.md, workflows/execute.md, workflows/export-to-github.md, workflows/feature-drift.md, workflows/from-template.md, workflows/list-plans.md, workflows/map-codebase.md, workflows/new-milestone.md, workflows/new-project.md, workflows/next.md, workflows/notify-test.md, workflows/plan.md, workflows/replay.md, workflows/sprint-planning.md, workflows/sprint-status.md, workflows/status.md, workflows/verify-work.md |
 
 ---
 
-## Agents with Accepted Size Exceptions
+## Specialist References
 
-The Agent File Size Rule (CONTRIBUTING.md) requires agents >100L to extract to references.
-Two agents have documented deviations:
+| File | Loaded by |
+|------|-----------|
+| `design-tokens.md` | rihal-haitham, workflows/lens-audit.md (Lens 11) |
+
+---
+
+## Persona ↔ SKILL.md Mapping (#714)
+
+Persona agents are thin pointers — the bulk of each persona's playbook lives
+in a `SKILL.md` at `rihal/skills/agents/<name>-<role>/SKILL.md` and gets pulled
+in via `@-include`. This keeps agent files dependency-free + IDE-discoverable
+while the playbook can grow without ballooning every spawn.
+
+| Persona | Agent file | Playbook |
+|---------|------------|----------|
+| Hanzla | rihal-hanzla.md | rihal/skills/agents/hanzla-engineer/SKILL.md |
+| Waleed | rihal-waleed.md | rihal/skills/agents/waleed-architect/SKILL.md |
+| Sadiq | rihal-sadiq.md | rihal/skills/agents/sadiq-analyst/SKILL.md |
+| Fatima | rihal-fatima.md | rihal/skills/agents/fatima-qa/SKILL.md |
+| Mariam | rihal-mariam.md | rihal/skills/agents/mariam-marketing/SKILL.md |
+| Layla | rihal-layla.md | rihal/skills/agents/layla-designer/SKILL.md |
+| Hussain-PM | rihal-hussain-pm.md | rihal/skills/agents/hussain-pm/SKILL.md |
+| Noor | rihal-noor.md | rihal/skills/agents/noor-writer/SKILL.md |
+| Nasser | rihal-nasser.md | rihal/skills/agents/nasser-eng-manager/SKILL.md |
+| Zahra | rihal-zahra.md | rihal/skills/agents/zahra-branding/SKILL.md |
+| Ahmed | rihal-ahmed.md | rihal/skills/agents/ahmed-hassani-director/SKILL.md |
+| Zayd | rihal-zayd.md | rihal/skills/agents/zayd-ml/SKILL.md |
+| Yousef | rihal-yousef.md | rihal/skills/agents/yousef-backend/SKILL.md |
+| Haitham | rihal-haitham.md | rihal/skills/agents/haitham-frontend/SKILL.md |
+| Khalid | rihal-khalid.md | *(inline — 99L, no separate playbook)* |
+| Omar | rihal-omar.md | *(inline — 96L, no separate playbook)* |
+
+Khalid and Omar keep their content inline because no separate playbook
+exists. Both are under the 100-line budget; extracting them to SKILL.md is
+optional scope and not required for compliance.
+
+---
+
+## Size Compliance
+
+The Agent File Size Rule (CONTRIBUTING.md:212) requires agents >100L to extract to references.
 
-| Agent | Lines | Reason |
-|-------|-------|--------|
-| `rihal-nyquist-auditor.md` | 176L | Load-bearing XML execution blocks that cannot be separated from agent logic |
-| `rihal-docs-auditor.md` | 173L | Load-bearing JSON schema for /rihal-feature-drift dispatch |
+**All 45 agents currently comply** (max: 99L). The previously-listed exceptions
+(`rihal-nyquist-auditor.md` at 176L, `rihal-docs-auditor.md` at 173L) were slimmed
+in #713: their playbooks live in `nyquist-auditor-playbook.md` and
+`docs-auditor-playbook.md` respectively.

package/rihal/references/agent-contracts.md

@@ -10,3 +10,13 @@ Conventions Rihal sub-agents follow when invoked from a workflow.
   not granted in the agent definition is unavailable.
 - **Failure**: agents that hit an obstacle return a structured "blocked"
   message rather than fabricating output.
+
+## Iterative retrieval (research subagents)
+
+When a workflow spawns a research subagent, it passes the broader objective —
+not just the literal query — and evaluates the returned result for sufficiency
+against that objective. If the result is insufficient (coverage gap, vague
+recommendations, or a blocked signal), the workflow re-dispatches the same
+subagent with the named gaps, hard-capped at 3 cycles. This loop is research-only
+— it does not apply to executor subagents. See `iterative-retrieval.md` for the
+full contract.

package/rihal/references/design-tokens.md

@@ -0,0 +1,98 @@
+# 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/docs-auditor-playbook.md

@@ -0,0 +1,148 @@
+# 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/git-preflight.md

@@ -0,0 +1,117 @@
+# Git Preflight Contract
+
+Shared reference `@`-included by every code-touching workflow. Designed by Khalid (DevOps) to close #659.
+
+## When this runs
+
+Before ANY workflow step that will modify files in the working tree — i.e. before `/rihal-execute`, `/rihal-quick`, `/rihal-dev-story`, `/rihal-code-review-fix`, and any other workflow that writes outside `.planning/`.
+
+## The 4 checks
+
+Run these read-only commands in order. Any failure halts the workflow with the failure banner below.
+
+```bash
+# Check 1: working tree clean
+DIRTY=$(git status --porcelain 2>/dev/null)
+
+# Check 2: not on a protected branch
+BRANCH=$(git branch --show-current 2>/dev/null)
+PROTECTED="main master develop v2-prototype"
+
+# Check 3: branch follows naming convention
+# Allowed: feat/foo-bar, fix/123-baz, issue-123-name, task-123-slug
+BRANCH_OK=$(echo "$BRANCH" | grep -qE '^((feat|fix|docs|chore|refactor|test|perf|style|build|ci)/[a-z0-9][a-z0-9-]*|(issue|task)-[0-9]+-[a-z0-9-]+)$' && echo yes || echo no)
+
+# Check 4: scope drift — files touched that don't belong to the active task
+# The workflow MUST pass $TASK_SCOPE_GLOB (e.g. ".planning/phases/8-*/" or "src/auth/")
+# If the workflow can't compute scope, skip this check rather than fail closed.
+if [ -n "$TASK_SCOPE_GLOB" ]; then
+  OUT_OF_SCOPE=$(git diff --name-only HEAD 2>/dev/null | grep -vE "$TASK_SCOPE_GLOB" | head -10)
+fi
+```
+
+## Failure conditions
+
+The workflow MUST stop and print the banner below if ANY of:
+
+- `DIRTY` is non-empty AND user did not pass `--allow-dirty`
+- `BRANCH` is in `$PROTECTED` AND user did not pass `--on-main`
+- `BRANCH_OK` is `no` AND user did not pass `--allow-dirty` (branch-name lint is advisory if working tree is dirty AND user accepted the dirty override)
+- `OUT_OF_SCOPE` is non-empty AND user did not pass `--allow-scope-drift`
+
+## Failure UX (banner)
+
+```
+Khalid (خالد) — DevOps preflight
+
+Cannot start {workflow_name}. Git state is unsafe.
+
+  Branch:        {BRANCH}              {protected? "(protected)" : ""}
+  Working tree:  {dirty/clean}         {N modified, M untracked if dirty}
+  Branch name:   {BRANCH_OK ? "ok" : "doesn't match convention"}
+  Scope drift:   {N files outside task scope}
+
+  {if dirty: list up to 5 modified files}
+  {if scope drift: list up to 5 out-of-scope files}
+
+Fix path:
+  1. git checkout -b fix/<issue-num>-<short-slug>
+  2. git add <files> ; git commit -m "fix(scope): subject (#<issue>)"
+  3. Re-run /{workflow_name}
+
+Override (last resort, only if you understand the trade-off):
+  /{workflow_name} {args} --allow-dirty       # skip working-tree check
+  /{workflow_name} {args} --on-main           # skip protected-branch check
+  /{workflow_name} {args} --allow-scope-drift # skip scope-drift check
+
+▶ Next Up
+  Clean the tree or branch, then resume. Khalid does not gate hotfixes —
+  if this is a true emergency, --on-main is the right answer.
+```
+
+## Post-task commit prompt
+
+After the workflow's code-modifying work completes, BEFORE returning control to the user, prompt for a commit:
+
+```
+Khalid — commit checkpoint
+
+Modified files (staged or unstaged):
+  [list git status --short output, grouped by logical unit if possible]
+
+A commit is required before this workflow can be considered done.
+
+GH issue link required per AGENTS.md. What issue does this work close?
+  Issue # (digits only, or "none" if this is exploratory): ___
+
+Suggested commit (Conventional Commits):
+  {type}({scope}): {subject} (#{issue})
+
+  {body — optional, explain WHY}
+
+Run `git add <files> && git commit` with the message above, or edit before
+running. AGENTS.md forbids --no-verify; if a hook fails, fix the underlying
+cause.
+```
+
+The hook only stages and commits. **It does NOT push.** Push always requires fresh user consent per `.rihal/references/no-unauthorized-git-ops.md`.
+
+## Override flag semantics
+
+| Flag | Skips | When valid |
+|------|-------|------------|
+| `--allow-dirty` | working-tree clean check | resuming a partial in-progress task, or amending a WIP commit |
+| `--on-main` | protected-branch check | true hotfix where the user accepts the risk; CI / release flows |
+| `--allow-scope-drift` | scope drift check | refactor that legitimately spans phases; cross-cutting cleanup |
+
+Each flag is independent. The user must pass exactly the override they need; the workflow MUST NOT auto-promote one override into another.
+
+## What this does NOT do
+
+- Does not run `git fetch` / `git pull` — those are remote operations and need explicit consent (see `no-unauthorized-git-ops.md`).
+- Does not create branches automatically. The failure banner *suggests* the branch name; the user runs the command.
+- Does not block read-only workflows (`/rihal-status`, `/rihal-discuss`, `/rihal-council`, etc.).
+
+## Why a shared reference
+
+Same shape as `no-unauthorized-git-ops.md`: a pre-condition contract that every workflow includes by `@`-reference. Single source of truth — when the policy changes, exactly one file changes and every code-touching workflow inherits the update.

package/rihal/references/iterative-retrieval.md

@@ -0,0 +1,85 @@
+# Iterative Retrieval — Bounded Research Loop
+
+The contract a research-spawning workflow follows when dispatching a research
+subagent and handling its return. Designed to be `@`-included by any workflow
+that spawns a research subagent (`rihal-phase-researcher`,
+`rihal-project-researcher`, `rihal-research-synthesizer`,
+`rihal-codebase-mapper`).
+
+Goal: research subagents get a follow-up gate, the same way executors get a
+verifier gate. A single research dispatch may return a shallow or partial
+result; this loop re-queries it — bounded — until the result is sufficient
+against the original objective.
+
+---
+
+## 1. Initial dispatch — pass the broader objective
+
+The orchestrator MUST pass the broader **objective** into the subagent prompt,
+not just the literal query. The subagent needs to know *why* the research
+matters and *what its output must enable downstream* — otherwise it optimizes
+for the narrow question and misses what the consumer actually needs.
+
+Include an `<objective>` block of this shape in the dispatch prompt:
+
+```
+<objective>
+{literal research query — the specific thing to find out}
+
+Why this matters: {the broader phase/project goal this research serves}
+Downstream consumer: {what planning/requirements/roadmap step uses this
+  result, and what a sufficient result must let that step do}
+</objective>
+```
+
+The literal query stays; the objective frames it.
+
+---
+
+## 2. Sufficiency evaluation — on return
+
+After the subagent returns its `## RESEARCH COMPLETE` summary, the orchestrator
+evaluates the result against the Step-1 objective **before** routing onward.
+The result is **insufficient** if any of these hold:
+
+- **Coverage gap** — the result does not address every dimension the objective
+  asked for (a missing dimension, an unanswered sub-question).
+- **Vague recommendations** — recommendations lack specifics: no versions, no
+  rationale, "consider X or Y" menus instead of "use X because Y".
+- **Blocked signal** — the subagent returned `## RESEARCH INCONCLUSIVE`, a
+  structured blocked message, or flagged a dimension it could not resolve.
+
+If none hold, the result is sufficient — proceed with normal routing.
+
+---
+
+## 3. Re-dispatch — same subagent, named gaps
+
+If insufficient, re-spawn the **SAME** `subagent_type` with a follow-up prompt
+that:
+
+- names the **specific gaps** found in Section 2 (which dimension, which
+  vague recommendation, which blocked signal),
+- includes the **prior result** so the subagent does not redo finished work,
+- asks **only for the missing pieces** — not a full re-research.
+
+The follow-up dispatch carries the same `<objective>` block from Step 1.
+
+---
+
+## 4. Hard cap — maximum 3 cycles
+
+The loop is hard-capped at **3 cycles**: the initial dispatch plus at most 2
+follow-up re-dispatches. After cycle 3, the orchestrator accepts the best
+result obtained, records the residual gaps in the research artifact (a
+`## Residual Gaps` note or equivalent), and proceeds. **Never loop unbounded** —
+3 cycles is the ceiling regardless of remaining gaps.
+
+---
+
+## 5. Out of scope — executors
+
+This loop applies to **research subagents only**. It does **not** apply to
+executor subagents — the executor checkpoint/verifier flow is unchanged. Do
+not re-dispatch an executor based on a sufficiency evaluation; executors have
+their own checkpoint and verifier gates.