@hanzlaa/rcode 3.6.8 → 3.6.15

package/rihal/team.yaml

@@ -85,6 +85,20 @@ agents:
       - backlog
     description: Scope, requirements, PRD writing, user stories, and backlog curation.
 
+  - id: rihal-hussain-sm
+    name: Hussain (حسين)
+    skill_path: rihal/skills/agents/hussain-sm
+    role: Scrum Master
+    authority_level: product
+    domain_keywords:
+      - sprint-planning
+      - story-preparation
+      - sprint-status
+      - retrospective
+      - course-correction
+      - agile-ceremonies
+    description: Sprint planning, story preparation, sprint status reporting, retrospectives, and mid-sprint course correction.
+
   - id: rihal-yousef
     name: Yousef (يوسف)
     file_path: rihal/agents/rihal-yousef.md
@@ -272,6 +286,48 @@ agents:
       - migrations
     description: Generalist engineer for implementation tasks spanning frontend and backend. Pairs with Hanzla on complex stories.
 
+  - id: rihal-dalil-scout
+    name: Dalil (دليل)
+    skill_path: rihal/skills/agents/dalil-scout
+    role: Codebase Scout
+    authority_level: analysis
+    domain_keywords:
+      - codebase-discovery
+      - repository-exploration
+      - topic-sweep
+      - architecture-mapping
+      - integrations-audit
+      - project-structure
+    description: Repository discovery, multi-root exploration, focused topic sweeps, and structured codebase documents.
+
+  - id: rihal-raees-orchestrator
+    name: Raees (رئيس)
+    skill_path: rihal/skills/agents/raees-orchestrator
+    role: Project Orchestration Director
+    authority_level: strategic
+    domain_keywords:
+      - orchestration
+      - dispatch
+      - work-routing
+      - phase-sequencing
+      - team-coordination
+      - handoffs
+    description: Dispatches work to the right specialists, sequences phases, identifies parallel vs sequential work, and coordinates handoffs.
+
+  - id: rihal-majlis-council
+    name: Majlis (مجلس)
+    skill_path: rihal/skills/agents/majlis-council
+    role: Multi-Agent Council
+    authority_level: strategic
+    domain_keywords:
+      - council
+      - team-consultation
+      - multi-agent-discussion
+      - crisis-mode
+      - incident-response
+      - cross-domain
+    description: Convenes the Rihal team to discuss any topic, collects perspectives from all relevant specialists, and delivers a synthesised answer with dissent noted.
+
 utility_agents:
   - id: rihal-planner
     name: Rihal Planner

package/rihal/templates/UAT.md

@@ -1,29 +1,80 @@
-# UAT — {{phase_name}}
+# UAT.md — User Acceptance Test Template
 
-**Phase:** {{phase_id}}
-**Generated:** {{date}}
+Each phase produces a UAT.md alongside its SUMMARY.md. UAT documents how a non-developer can verify the phase delivered what it promised.
 
-## How to use
+## Frontmatter
 
-For each scenario below, mark status: ✅ pass | ❌ fail | ⏸ skipped |
-🔍 needs-human. Add notes inline.
+```yaml
+---
+phase: NN
+phase_name: <slug>
+generated: <ISO date>
+status: pending | passed | partial | diagnosed | blocked | skipped | human_needed
+last_run: <ISO date>
+---
+```
 
-## Scenarios
+## Sections
 
-### Scenario 1: {{golden path title}}
+### Phase goal (verbatim from ROADMAP.md)
 
-**Steps:**
-1. {{action}}
-2. {{action}}
+One paragraph copied straight from the phase's roadmap entry. No paraphrase.
 
-**Expected:** {{outcome}}
-**Status:** ⏸
-**Notes:**
+### What to verify
 
-### Scenario 2: {{edge case title}}
+A bullet list. Each bullet is one observable behavior:
 
-(Repeat as needed.)
+- ✅ **<feature>** — open <screen / endpoint / file>, do <action>, observe <expected outcome>
+- ✅ **<feature>** — run `<exact command>`, expect output containing `<exact substring>`
 
-## Outstanding items
+Every bullet must be runnable without reading the source code.
 
-Items left as ⏸ or 🔍 carry forward to the next milestone audit.
+### Setup steps
+
+If the verifier needs to seed data, set env vars, or start services:
+
+```bash
+# 1. install
+npx @hanzlaa/rcode install
+# 2. seed
+node .rihal/bin/rihal-tools.cjs ...
+# 3. ready
+open http://localhost:3000/foo
+```
+
+### Per-criterion result
+
+After running, fill in:
+
+| # | Criterion | Result | Notes |
+|---|-----------|:------:|-------|
+| 1 | <copy from "What to verify"> | ✅ / ⚠️ / ❌ | <one line> |
+| 2 | ... | ... | ... |
+
+### Outstanding items
+
+Anything that could not be verified, or where the verifier hit a blocker:
+
+- **<criterion>**: status = `blocked` because <reason>; needs <action> from <owner>.
+
+### Sign-off
+
+```
+Verified by: <name>
+Date: <ISO>
+Verdict: PASSED | PARTIAL | FAILED
+```
+
+## Status values
+
+- `pending` — UAT.md generated but not yet run.
+- `passed` — every criterion green.
+- `partial` — some criteria green, some not. Note which.
+- `diagnosed` — failed criteria have a known cause + a fix is in flight.
+- `blocked` — failed criteria need external work (data, infra, API access).
+- `skipped` — verifier intentionally did not run a criterion (with reason).
+- `human_needed` — automated check inconclusive; needs subjective human judgment.
+
+## Audit
+
+`/rihal:audit-uat` aggregates UAT.md files across all phases and surfaces outstanding items in one report.

package/rihal/templates/memory/INDEX.md

@@ -37,8 +37,8 @@
 - **`project/decisions.md`** — append every architectural choice as it's made
 - **`milestones/current.md`** — update on milestone phase transitions
 - **`incidents/known-issues.md`** — add when a workaround ships, remove when a real fix lands
-- **`distillates/`** — regenerate via `/rcode:memory-distill` when source files change
-- **Whole bank** — audit via `/rcode:memory-audit` at every milestone close
+- **`distillates/`** — regenerate via `/rihal-memory-distill` when source files change
+- **Whole bank** — audit via `/rihal-memory-audit` at every milestone close
 
 ## Constraints
 

package/rihal/templates/memory/distillates/project.distillate.md

@@ -1,11 +1,11 @@
 ---
 generated: true
 do-not-edit: true
-regenerate-with: /rcode:memory-distill
+regenerate-with: /rihal-memory-distill
 ---
 
 # Project Distillate — `{{PROJECT_NAME}}`
 
 > Generated, lossless compression of `project/`, `people/`, `milestones/current.md`, and `incidents/known-issues.md`. Optimised for LLM context loading. Hand-edits are overwritten on regenerate.
 
-_(Run `/rcode:memory-distill` to populate.)_
+_(Run `/rihal-memory-distill` to populate.)_

package/rihal/templates/memory/distillates/stack.distillate.md

@@ -1,11 +1,11 @@
 ---
 generated: true
 do-not-edit: true
-regenerate-with: /rcode:memory-distill
+regenerate-with: /rihal-memory-distill
 ---
 
 # Stack Distillate — `{{PROJECT_NAME}}`
 
 > Generated, lossless compression of `project/stack.md` only. Useful when you need stack context but not full project history.
 
-_(Run `/rcode:memory-distill --target stack` to populate.)_
+_(Run `/rihal-memory-distill --target stack` to populate.)_

package/rihal/templates/memory/project/stack.md

@@ -1,6 +1,6 @@
 # Stack — `{{PROJECT_NAME}}`
 
-Inventory of languages, frameworks, libraries, and services. Refreshed via `/rcode:memory-update` when stack changes.
+Inventory of languages, frameworks, libraries, and services. Refreshed via `/rihal-memory-update` when stack changes.
 
 ---
 

package/rihal/templates/summary.md

@@ -1,60 +1,77 @@
+# SUMMARY.md Template
+
+Each plan or sprint task produces a SUMMARY.md when it completes. The summary is the unit of work's lasting record — what was done, why, what remains, what other work it affects.
+
+## Frontmatter
+
+```yaml
 ---
-phase: "{{phase_id}}"
-status: complete
-closed_at: "{{closed_at}}"
+phase: NN
+plan: NN.M             # if applicable
+sprint: N              # if applicable
+story_id: NN.M         # if dev-story produced this
+generated: <ISO date>
+status: complete | partial | blocked
+verified: false        # flips to true after /rihal:verify-work passes
 ---
+```
+
+## Sections
+
+### One-liner
+
+A single line describing what was accomplished. Goes into `/rihal:progress` recent-work bullets, council recaps, milestone summaries. Be specific:
+
+> ❌ "Added some dashboard improvements"
+> ✅ "Wired live engagement metrics to dashboard top-3 tweets card; updates every 30s via SSE"
 
-# Phase Summary — {{phase_name}}
+### Outcomes
 
-<!-- P2: Omit any section that has nothing substantive to say. An empty section is worse than no section. -->
+What changed as a result of this work, observable from outside:
 
-**Phase ID:** {{phase_id}}
-**Closed:** {{closed_at}}
-**Sprint:** SPRINT.md
+- ...
 
-## Outcomes
+### Files touched
 
-- {{what was built, in user-visible terms}}
+```
+src/dashboard/Card.tsx        new
+src/dashboard/index.tsx       modified — added engagement subscription
+src/lib/sse.ts                new — SSE client wrapper
+test/dashboard.test.ts        new — 4 tests
+```
 
-## Decisions Made
+### Decisions
 
-<!-- Omit if no decisions were made that aren't already in SPRINT.md -->
-- {{key choices and their rationale}}
+Decisions made during execution that aren't already in `state.decisions[]`:
 
-## Deviations from Plan
+- **<decision>**: chose A over B because <one-line reason>. Tradeoff: <what we gave up>.
 
-<!-- Omit if execution matched the plan exactly -->
-- {{anything that diverged from SPRINT.md and why}}
+### Issues encountered
 
-## Issues Encountered
+Problems hit during execution and how they were resolved:
 
-<!-- Omit if no tasks were pruned, escalated, or skipped -->
-- {{tasks pruned, escalated, or skipped}}
+- **<problem>**: <one-line description>. Resolved by <action>. Time spent: <approx>.
 
-## Patterns Established
+If a problem was NOT resolved, it goes here AND becomes a follow-up filed below.
 
-<!-- Omit if no new patterns were introduced. List architectural/coding patterns future phases should follow. -->
-<!-- Example: "All service errors now wrap in ServiceError(code, message) — see auth.service.ts:42" -->
-- {{new pattern introduced by this phase and where it lives}}
+### Follow-ups
 
-## Provides
+GH issues filed (or to file) for work that this story surfaced but didn't ship:
 
-<!-- What this phase exposes for future phases to build on. Be specific: function names, API endpoints, data models, config keys. -->
-<!-- Example: "UserRepository.findByEmail() — src/repositories/user.repo.ts" -->
-- {{what future phases can reuse from this phase}}
+- #N — <title>
+- (to file) — <description>
 
-## Requires
+### Verification
 
-<!-- What this phase consumed from prior phases. Helps trace dependency chains. -->
-<!-- Example: "Database connection from Phase 3 (src/db/connection.ts)" -->
-- {{what this phase depended on from earlier phases}}
+How a verifier confirms this story is actually done:
 
-## Affects
+- Run `<command>`, expect `<output>`
+- Open `<UI element>`, click `<button>`, observe `<state change>`
 
-<!-- Downstream phases or components that may be impacted by what changed here. -->
-<!-- Example: "Phase 9 (checkout flow) — depends on Cart model introduced here" -->
-- {{phases or components that should re-verify after this phase}}
+This block feeds into UAT.md when the phase completes.
 
-## Hand-off
+### Status
 
-Next phase: {{next phase id and goal}}
+- **complete** — all acceptance criteria green, follow-ups filed.
+- **partial** — some AC green, others deferred. Document which AC are open.
+- **blocked** — couldn't proceed. Owner of unblock + ETA.

package/rihal/templates/verification-report.md

@@ -1,28 +1,83 @@
-# Verification Report — {{phase_name}}
+# Verification Report Template
 
-**Phase:** {{phase_id}}
-**Verified:** {{date}}
-**Verifier:** rihal-verifier
+Used by `/rihal:verify-phase`. Goal-backward analysis of whether the phase actually delivered the goal stated in ROADMAP.md.
 
-## Goal-backward check
+## Frontmatter
 
-**Original goal:** {{phase goal from PLAN.md}}
+```yaml
+---
+phase: NN
+phase_name: <slug>
+verifier: <agent / human>
+verified_at: <ISO date>
+verdict: pass | fail | partial
+goal_source: ROADMAP.md (commit-sha-at-phase-start)
+---
+```
 
-**Met?** ✅ / ◐ partial / ❌ not met
+## Sections
 
-**Evidence:**
-- {{file:line or test name proving the goal is met}}
+### Phase goal (verbatim)
 
-## Per-task verification
+> <paste the goal statement from ROADMAP.md exactly as written when this phase was planned>
 
-| # | Task | Status | Evidence |
-|---|------|--------|----------|
-| 1 | {{task}} | ✅ | {{evidence}} |
+### Goal decomposition
 
-## Gaps
+The goal as one sentence is too coarse to verify against. Decompose into checkable claims:
 
-- {{what wasn't delivered + why}}
+1. **Claim 1**: <one observable thing the goal implies>
+2. **Claim 2**: ...
+3. **Claim N**: ...
 
-## Recommendation
+### Evidence per claim
 
-- proceed / revise / block
+For each claim, list:
+
+- **Source of truth**: code path / file / endpoint / behavior
+- **Verification method**: command / test name / manual step
+- **Result**: ✅ / ❌ / ⚠️
+- **Notes**: anything surprising
+
+```
+| # | Claim | Method | Result | Notes |
+|---|-------|--------|:------:|-------|
+| 1 | ... | ... | ✅ | ... |
+```
+
+### Coverage gaps
+
+What the phase goal said but no evidence-trail covered. List explicitly:
+
+- **<claim>** has no implementation that can be pointed to. Either:
+  - The goal was aspirational and the phase didn't implement it (gap to file as follow-up)
+  - The implementation exists but no test or doc covers it (gap to file as test debt)
+
+### Side-effect audit
+
+What the phase changed BEYOND the goal. Often these are silent:
+
+- New dependencies added
+- Schema changes
+- API contract changes
+- File-tree changes (new dirs, deleted files)
+
+Each side effect should be intentional and documented.
+
+### Verdict reasoning
+
+One paragraph explaining why the verdict (pass / fail / partial) was chosen. Include any judgment calls.
+
+### Follow-ups
+
+Issues filed (or to file) for gaps surfaced during verification:
+
+- #N — <title>
+- (to file) — <description>
+
+## Sign-off
+
+```
+Verifier: <name or agent id>
+Date: <ISO>
+Verdict: <verdict from frontmatter>
+```

package/rihal/workflows/analyze-dependencies.md

@@ -1,7 +1,7 @@
 # Workflow: rihal-analyze-dependencies
 
 <purpose>
-Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/rihal-manager`.
+Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution.
 </purpose>
 
 
@@ -119,7 +119,7 @@ When writing:
 - Preserve all other phase content unchanged
 - Do not reorder phases
 
-After applying: "ROADMAP.md updated. Run `/rihal-manager` to execute phases in the correct order."
+After applying: "ROADMAP.md updated. Run `/rihal-execute-milestone` to execute phases in the correct order."
 
 ## Success Criteria
 
@@ -140,5 +140,5 @@ After applying: "ROADMAP.md updated. Run `/rihal-manager` to execute phases in t
 ## ▶ Next Up
 
 - **Circular deps found:** Fix dependency cycle, then re-run analysis
-- **Ready to execute:** `/rihal-execute {phase}` — run with dependency awareness
-- **Review roadmap:** `/rihal-progress` — see full project state
+- /rihal-execute {phase}
+- /rihal-progress

package/rihal/workflows/audit-fix.md

@@ -199,6 +199,6 @@ If arguments are invalid, missing files, or subagent fails:
 
 ## ▶ Next Up
 
-- **Fixes applied:** `/rihal-verify-phase {phase}` — re-verify after fixes
-- **More issues:** `/rihal-audit {phase}` — run audit again to confirm
-- **All clean:** `/rihal-progress` — check project state
+- /rihal-verify-phase {phase}
+- /rihal-audit {phase}
+- /rihal-progress

package/rihal/workflows/audit-milestone.md

@@ -4,22 +4,23 @@
 Cross-phase audit of milestone completion. Reads all SUMMARY.md files from completed phases, compares their outcomes to the original ROADMAP goals, flags gaps, and generates an audit report showing completion percentage and decision traceability.
 </purpose>
 
-## Step 0 — Usage check
+## Step 0 — Parse arguments
 
-If `$ARGUMENTS` contains only `--help` or `-h`:
+Parse `$ARGUMENTS`:
+- `--help` or `-h` → print usage and stop:
+  ```
+  /rihal-audit-milestone [<unverified-count>] [--fix-drift] [--strict] [--report]
+  ```
+- A bare integer (e.g. `28`) → `HINT_UNVERIFIED_COUNT = 28` (pre-computed by rihal-status for display; use as expected minimum in the scan)
+- `--fix-drift` → `FIX_DRIFT = true` (after audit, suggest the drift sync command)
+- `--strict` → `STRICT = true`
+- `--report` → `WRITE_REPORT = true`
 
+If `HINT_UNVERIFIED_COUNT` is set, print at the top of the audit output:
 ```
-/rihal-audit-milestone [--strict] [--report]
+ℹ Expecting ~{HINT_UNVERIFIED_COUNT} phases to verify (from rihal-status)
 ```
 
-**Examples:**
-```
-/rihal-audit-milestone
-/rihal-audit-milestone --strict --report
-```
-
-STOP — do not proceed.
-
 ## Step 1 — Locate milestone context
 
 Determine the active milestone. Check:

package/rihal/workflows/audit-worktrees.md

@@ -0,0 +1,163 @@
+# Workflow: audit-worktrees
+
+<purpose>
+Scan for orphaned executor worktrees and branches left behind by rihal-execute.
+Reports each orphan with its age, merge status, and safe-to-delete verdict.
+With --prune, deletes confirmed-safe orphans automatically.
+</purpose>
+
+## Step 0 — Parse arguments
+
+- `--prune` → `PRUNE=true` — delete safe orphans after reporting
+- `--help` or `-h` → print usage and stop:
+  ```
+  /rihal-audit worktrees [--prune]
+  ```
+
+## Step 1 — Scan for orphaned worktrees
+
+Executor agents use branches prefixed `worktree-agent-`. Find all such branches
+and worktrees still present in the repo:
+
+```bash
+# Active worktrees with executor branches
+git worktree list --porcelain \
+  | awk 'BEGIN{p=""} /^worktree /{p=$2} /^branch /{if($2~/refs\/heads\/worktree-agent-/) print p"\t"$2}' \
+  > /tmp/rihal-active-wts.txt
+
+# Local branches with executor prefix (includes detached/removed worktrees)
+git branch --list 'worktree-agent-*' --format='%(refname:short)' \
+  > /tmp/rihal-orphan-br.txt
+
+ACTIVE_WT_COUNT=$(wc -l < /tmp/rihal-active-wts.txt)
+ORPHAN_BR_COUNT=$(wc -l < /tmp/rihal-orphan-br.txt)
+TOTAL=$((ACTIVE_WT_COUNT + ORPHAN_BR_COUNT))
+```
+
+If `TOTAL` is 0:
+
+```
+✓ No orphaned executor worktrees or branches found.
+```
+
+Stop.
+
+## Step 2 — For each orphan, gather intelligence
+
+For each entry (worktree or branch), run:
+
+```bash
+# Is it merged into the current branch?
+MERGED=$(git branch --merged HEAD --list '<branch>' 2>/dev/null | grep -c '<branch>')
+
+# When was the last commit on this branch?
+LAST_COMMIT=$(git log -1 --format="%ar %s" '<branch>' 2>/dev/null || echo "unknown")
+
+# How many commits does it have that are NOT on HEAD?
+AHEAD=$(git rev-list HEAD..'<branch>' --count 2>/dev/null || echo "?")
+```
+
+Build a report table:
+
+```
+RIHAL ► WORKTREE AUDIT
+══════════════════════════════════════════════════════════
+
+Orphaned executor artifacts: {TOTAL}
+
+  Branch                          Merged  Ahead  Last commit
+  ──────────────────────────────  ──────  ─────  ──────────────────────
+  worktree-agent-abc123           YES     0      3 days ago  feat: add auth
+  worktree-agent-def456           NO      2      1 hour ago  wip: migrations
+  ...
+
+Active worktrees still pointing to executor branches:
+  .claude/worktrees/agent-abc123  →  worktree-agent-abc123
+  ...
+```
+
+## Step 3 — Classify each orphan
+
+For each branch/worktree:
+
+- **SAFE** → `MERGED=YES` AND `AHEAD=0` — all commits are on HEAD, nothing to lose
+- **STALE** → `MERGED=YES` AND `AHEAD>0` — commits are ahead but branch is in merged list (rebased/squash-merged); verify before deleting
+- **UNMERGED** → `MERGED=NO` — DO NOT auto-delete; show explicitly and warn
+
+Print classification next to each entry.
+
+## Step 4 — Report summary
+
+```
+Summary:
+  SAFE to delete:     {N}  (merged, 0 ahead)
+  STALE (check first): {N}  (merged but ahead — may be rebase/squash)
+  UNMERGED (keep):    {N}  (not merged — manual review required)
+
+  To prune SAFE orphans: /rihal-audit worktrees --prune
+  To inspect UNMERGED:   git log HEAD..<branch> --oneline
+```
+
+If `PRUNE=false`, stop here.
+
+## Step 5 — Prune (only when --prune passed)
+
+Delete SAFE entries only. Never touch STALE or UNMERGED.
+
+For each SAFE branch:
+
+```bash
+# Remove the worktree if it still exists
+WT_PATH=$(awk -F'\t' '$2=="refs/heads/<branch>"{print $1}' /tmp/rihal-active-wts.txt)
+if [ -n "$WT_PATH" ] && [ -d "$WT_PATH" ]; then
+  git worktree remove "$WT_PATH" --force 2>/dev/null \
+    && echo "  ✓ removed worktree: $WT_PATH" \
+    || echo "  ⚠ could not remove worktree: $WT_PATH"
+fi
+
+# Delete the branch
+git branch -D '<branch>' 2>/dev/null \
+  && echo "  ✓ deleted branch: <branch>" \
+  || echo "  ⚠ could not delete branch: <branch>"
+```
+
+After all deletes, re-run Step 1 scan and confirm `TOTAL=0` for SAFE entries.
+
+Print final report:
+
+```
+Pruned: {N} safe orphans removed
+Kept:   {N} unmerged branches (manual review required)
+
+✓ Worktree cleanup complete
+```
+
+## Step 6 — Post-audit health note
+
+If any UNMERGED branches remain, print:
+
+```
+⚠ {N} unmerged executor branch(es) still present.
+  These have commits NOT on your current branch.
+  Inspect before deleting:
+
+  git log HEAD..worktree-agent-<id> --oneline
+  git show worktree-agent-<id>:<file>   # inspect specific file
+
+  To delete after manual review:
+  git worktree remove .claude/worktrees/<id> --force
+  git branch -D worktree-agent-<id>
+```
+
+## Success Criteria
+
+- [ ] All `worktree-agent-*` branches and worktrees found and reported
+- [ ] Each classified as SAFE / STALE / UNMERGED based on actual merge status
+- [ ] `--prune` deletes only SAFE entries, never UNMERGED
+- [ ] Post-prune confirmation scan verifies cleanup succeeded
+- [ ] Non-executor worktrees (feature branches, manual worktrees) are never touched
+
+## On Error
+
+- `git worktree list` fails → print `git not available or not a repo` and stop
+- `git branch -D` fails on a branch → skip it, note it in the report, continue