@hanzlaa/rcode 3.4.31 → 3.4.33

package/rihal/references/integration-verification-playbook.md

@@ -0,0 +1,392 @@
+# Integration Verification Playbook
+
+Loaded by `rihal-integration-checker` via `@-include`. Contains the full
+six-step verification process, structured output template, critical rules,
+and success criteria.
+
+---
+
+## Step 1: Build Export/Import Map
+
+For each phase, extract what it provides and what it should consume.
+
+**From SUMMARYs, extract:**
+
+```bash
+# Key exports from each phase
+for summary in .planning/phases/*/*-SUMMARY.md; do
+  echo "=== $summary ==="
+  grep -A 10 "Key Files\|Exports\|Provides" "$summary" 2>/dev/null
+done
+```
+
+**Build provides/consumes map:**
+
+```
+Phase 1 (Auth):
+  provides: getCurrentUser, AuthProvider, useAuth, /api/auth/*
+  consumes: nothing (foundation)
+
+Phase 2 (API):
+  provides: /api/users/*, /api/data/*, UserType, DataType
+  consumes: getCurrentUser (for protected routes)
+
+Phase 3 (Dashboard):
+  provides: Dashboard, UserCard, DataList
+  consumes: /api/users/*, /api/data/*, useAuth
+```
+
+## Step 2: Verify Export Usage
+
+For each phase's exports, verify they're imported and used.
+
+**Check imports:**
+
+```bash
+check_export_used() {
+  local export_name="$1"
+  local source_phase="$2"
+  local search_path="${3:-src/}"
+
+  # Find imports
+  local imports=$(grep -r "import.*$export_name" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | \
+    grep -v "$source_phase" | wc -l)
+
+  # Find usage (not just import)
+  local uses=$(grep -r "$export_name" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | \
+    grep -v "import" | grep -v "$source_phase" | wc -l)
+
+  if [ "$imports" -gt 0 ] && [ "$uses" -gt 0 ]; then
+    echo "CONNECTED ($imports imports, $uses uses)"
+  elif [ "$imports" -gt 0 ]; then
+    echo "IMPORTED_NOT_USED ($imports imports, 0 uses)"
+  else
+    echo "ORPHANED (0 imports)"
+  fi
+}
+```
+
+**Run for key exports:**
+
+- Auth exports (getCurrentUser, useAuth, AuthProvider)
+- Type exports (UserType, etc.)
+- Utility exports (formatDate, etc.)
+- Component exports (shared components)
+
+## Step 3: Verify API Coverage
+
+Check that API routes have consumers.
+
+**Find all API routes:**
+
+```bash
+# Next.js App Router
+find src/app/api -name "route.ts" 2>/dev/null | while read route; do
+  # Extract route path from file path
+  path=$(echo "$route" | sed 's|src/app/api||' | sed 's|/route.ts||')
+  echo "/api$path"
+done
+
+# Next.js Pages Router
+find src/pages/api -name "*.ts" 2>/dev/null | while read route; do
+  path=$(echo "$route" | sed 's|src/pages/api||' | sed 's|\.ts||')
+  echo "/api$path"
+done
+```
+
+**Check each route has consumers:**
+
+```bash
+check_api_consumed() {
+  local route="$1"
+  local search_path="${2:-src/}"
+
+  # Search for fetch/axios calls to this route
+  local fetches=$(grep -r "fetch.*['\"]$route\|axios.*['\"]$route" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l)
+
+  # Also check for dynamic routes (replace [id] with pattern)
+  local dynamic_route=$(echo "$route" | sed 's/\[.*\]/.*/g')
+  local dynamic_fetches=$(grep -r "fetch.*['\"]$dynamic_route\|axios.*['\"]$dynamic_route" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l)
+
+  local total=$((fetches + dynamic_fetches))
+
+  if [ "$total" -gt 0 ]; then
+    echo "CONSUMED ($total calls)"
+  else
+    echo "ORPHANED (no calls found)"
+  fi
+}
+```
+
+## Step 4: Verify Auth Protection
+
+Check that routes requiring auth actually check auth.
+
+**Find protected route indicators:**
+
+```bash
+# Routes that should be protected (dashboard, settings, user data)
+protected_patterns="dashboard|settings|profile|account|user"
+
+# Find components/pages matching these patterns
+grep -r -l "$protected_patterns" src/ --include="*.tsx" 2>/dev/null
+```
+
+**Check auth usage in protected areas:**
+
+```bash
+check_auth_protection() {
+  local file="$1"
+
+  # Check for auth hooks/context usage
+  local has_auth=$(grep -E "useAuth|useSession|getCurrentUser|isAuthenticated" "$file" 2>/dev/null)
+
+  # Check for redirect on no auth
+  local has_redirect=$(grep -E "redirect.*login|router.push.*login|navigate.*login" "$file" 2>/dev/null)
+
+  if [ -n "$has_auth" ] || [ -n "$has_redirect" ]; then
+    echo "PROTECTED"
+  else
+    echo "UNPROTECTED"
+  fi
+}
+```
+
+## Step 5: Verify E2E Flows
+
+Derive flows from milestone goals and trace through codebase.
+
+**Common flow patterns:**
+
+### Flow: User Authentication
+
+```bash
+verify_auth_flow() {
+  echo "=== Auth Flow ==="
+
+  # Step 1: Login form exists
+  local login_form=$(grep -r -l "login\|Login" src/ --include="*.tsx" 2>/dev/null | head -1)
+  [ -n "$login_form" ] && echo "✓ Login form: $login_form" || echo "✗ Login form: MISSING"
+
+  # Step 2: Form submits to API
+  if [ -n "$login_form" ]; then
+    local submits=$(grep -E "fetch.*auth|axios.*auth|/api/auth" "$login_form" 2>/dev/null)
+    [ -n "$submits" ] && echo "✓ Submits to API" || echo "✗ Form doesn't submit to API"
+  fi
+
+  # Step 3: API route exists
+  local api_route=$(find src -path "*api/auth*" -name "*.ts" 2>/dev/null | head -1)
+  [ -n "$api_route" ] && echo "✓ API route: $api_route" || echo "✗ API route: MISSING"
+
+  # Step 4: Redirect after success
+  if [ -n "$login_form" ]; then
+    local redirect=$(grep -E "redirect|router.push|navigate" "$login_form" 2>/dev/null)
+    [ -n "$redirect" ] && echo "✓ Redirects after login" || echo "✗ No redirect after login"
+  fi
+}
+```
+
+### Flow: Data Display
+
+```bash
+verify_data_flow() {
+  local component="$1"
+  local api_route="$2"
+  local data_var="$3"
+
+  echo "=== Data Flow: $component → $api_route ==="
+
+  # Step 1: Component exists
+  local comp_file=$(find src -name "*$component*" -name "*.tsx" 2>/dev/null | head -1)
+  [ -n "$comp_file" ] && echo "✓ Component: $comp_file" || echo "✗ Component: MISSING"
+
+  if [ -n "$comp_file" ]; then
+    # Step 2: Fetches data
+    local fetches=$(grep -E "fetch|axios|useSWR|useQuery" "$comp_file" 2>/dev/null)
+    [ -n "$fetches" ] && echo "✓ Has fetch call" || echo "✗ No fetch call"
+
+    # Step 3: Has state for data
+    local has_state=$(grep -E "useState|useQuery|useSWR" "$comp_file" 2>/dev/null)
+    [ -n "$has_state" ] && echo "✓ Has state" || echo "✗ No state for data"
+
+    # Step 4: Renders data
+    local renders=$(grep -E "\{.*$data_var.*\}|\{$data_var\." "$comp_file" 2>/dev/null)
+    [ -n "$renders" ] && echo "✓ Renders data" || echo "✗ Doesn't render data"
+  fi
+
+  # Step 5: API route exists and returns data
+  local route_file=$(find src -path "*$api_route*" -name "*.ts" 2>/dev/null | head -1)
+  [ -n "$route_file" ] && echo "✓ API route: $route_file" || echo "✗ API route: MISSING"
+
+  if [ -n "$route_file" ]; then
+    local returns_data=$(grep -E "return.*json|res.json" "$route_file" 2>/dev/null)
+    [ -n "$returns_data" ] && echo "✓ API returns data" || echo "✗ API doesn't return data"
+  fi
+}
+```
+
+### Flow: Form Submission
+
+```bash
+verify_form_flow() {
+  local form_component="$1"
+  local api_route="$2"
+
+  echo "=== Form Flow: $form_component → $api_route ==="
+
+  local form_file=$(find src -name "*$form_component*" -name "*.tsx" 2>/dev/null | head -1)
+
+  if [ -n "$form_file" ]; then
+    # Step 1: Has form element
+    local has_form=$(grep -E "<form|onSubmit" "$form_file" 2>/dev/null)
+    [ -n "$has_form" ] && echo "✓ Has form" || echo "✗ No form element"
+
+    # Step 2: Handler calls API
+    local calls_api=$(grep -E "fetch.*$api_route|axios.*$api_route" "$form_file" 2>/dev/null)
+    [ -n "$calls_api" ] && echo "✓ Calls API" || echo "✗ Doesn't call API"
+
+    # Step 3: Handles response
+    local handles_response=$(grep -E "\.then|await.*fetch|setError|setSuccess" "$form_file" 2>/dev/null)
+    [ -n "$handles_response" ] && echo "✓ Handles response" || echo "✗ Doesn't handle response"
+
+    # Step 4: Shows feedback
+    local shows_feedback=$(grep -E "error|success|loading|isLoading" "$form_file" 2>/dev/null)
+    [ -n "$shows_feedback" ] && echo "✓ Shows feedback" || echo "✗ No user feedback"
+  fi
+}
+```
+
+## Step 6: Compile Integration Report
+
+Structure findings for milestone auditor.
+
+**Wiring status:**
+
+```yaml
+wiring:
+  connected:
+    - export: "getCurrentUser"
+      from: "Phase 1 (Auth)"
+      used_by: ["Phase 3 (Dashboard)", "Phase 4 (Settings)"]
+
+  orphaned:
+    - export: "formatUserData"
+      from: "Phase 2 (Utils)"
+      reason: "Exported but never imported"
+
+  missing:
+    - expected: "Auth check in Dashboard"
+      from: "Phase 1"
+      to: "Phase 3"
+      reason: "Dashboard doesn't call useAuth or check session"
+```
+
+**Flow status:**
+
+```yaml
+flows:
+  complete:
+    - name: "User signup"
+      steps: ["Form", "API", "DB", "Redirect"]
+
+  broken:
+    - name: "View dashboard"
+      broken_at: "Data fetch"
+      reason: "Dashboard component doesn't fetch user data"
+      steps_complete: ["Route", "Component render"]
+      steps_missing: ["Fetch", "State", "Display"]
+```
+
+---
+
+Return structured report to milestone auditor:
+
+```markdown
+## Integration Check Complete
+
+### Wiring Summary
+
+**Connected:** {N} exports properly used
+**Orphaned:** {N} exports created but unused
+**Missing:** {N} expected connections not found
+
+### API Coverage
+
+**Consumed:** {N} routes have callers
+**Orphaned:** {N} routes with no callers
+
+### Auth Protection
+
+**Protected:** {N} sensitive areas check auth
+**Unprotected:** {N} sensitive areas missing auth
+
+### E2E Flows
+
+**Complete:** {N} flows work end-to-end
+**Broken:** {N} flows have breaks
+
+### Detailed Findings
+
+#### Orphaned Exports
+
+{List each with from/reason}
+
+#### Missing Connections
+
+{List each with from/to/expected/reason}
+
+#### Broken Flows
+
+{List each with name/broken_at/reason/missing_steps}
+
+#### Unprotected Routes
+
+{List each with path/reason}
+
+#### Requirements Integration Map
+
+| Requirement | Integration Path | Status | Issue |
+|-------------|-----------------|--------|-------|
+| {REQ-ID} | {Phase X export → Phase Y import → consumer} | WIRED / PARTIAL / UNWIRED | {specific issue or "—"} |
+
+**Requirements with no cross-phase wiring:**
+{List REQ-IDs that exist in a single phase with no integration touchpoints — these may be self-contained or may indicate missing connections}
+```
+
+---
+
+**Check connections, not existence.** Files existing is phase-level. Files connecting is integration-level.
+
+**Trace full paths.** Component → API → DB → Response → Display. Break at any point = broken flow.
+
+**Check both directions.** Export exists AND import exists AND import is used AND used correctly.
+
+**Be specific about breaks.** "Dashboard doesn't work" is useless. "Dashboard.tsx line 45 fetches /api/users but doesn't await response" is actionable.
+
+**Return structured data.** The milestone auditor aggregates your findings. Use consistent format.
+
+---
+
+- [ ] Export/import map built from SUMMARYs
+- [ ] All key exports checked for usage
+- [ ] All API routes checked for consumers
+- [ ] Auth protection verified on sensitive routes
+- [ ] E2E flows traced and status determined
+- [ ] Orphaned code identified
+- [ ] Missing connections identified
+- [ ] Broken flows identified with specific break points
+- [ ] Requirements Integration Map produced with per-requirement wiring status
+- [ ] Requirements with no cross-phase wiring identified
+- [ ] Structured report returned to auditor
+
+---
+
+- verify external service connectivity
+- check environment variables are properly set
+- validate API integrations and database connections
+- document all integration failures with remediation steps
+- return structured PASS/FAIL report

package/rihal/references/persona-engineer-shared.md

@@ -0,0 +1,61 @@
+# Engineer Persona Shared Rules
+
+Loaded by `rihal-haitham`, `rihal-omar`, and `rihal-yousef` via `@-include`.
+Contains the shared communication discipline, heuristic protocol, and
+operational constraints that all three engineer personas inherit.
+
+Persona-specific content (identity, capabilities, named heuristics,
+examples, redirects) lives in each agent's own file.
+
+---
+
+## Communication Discipline
+
+- Response prefix with persona glyph. No emojis beyond the persona glyph (each stub defines its own glyph).
+- **STRICTLY FORBIDDEN from starting with "Great", "Certainly", "Okay", "Sure"** — direct, never conversational.
+- Never end with "Let me know if you have questions".
+- Never opens with generic context-setting ("In React, you typically…", "Generally speaking…"). Opens with what the actual code does.
+
+---
+
+## Named-Heuristic Protocol
+
+Every engineer persona operates five named heuristics. The specific heuristics differ per persona — the protocol for applying them is shared:
+
+- When refusing or recommending, cite the heuristic **by name** (e.g., "Per [heuristic name], …").
+- "Cite by name" is mandatory, not stylistic.
+- Never refuse or recommend without connecting the decision back to a named rule.
+- When asked to explain a decision, name the heuristic first, then the reasoning.
+
+---
+
+## Anti-Pattern Enforcement Protocol
+
+Every engineer persona maintains an Anti-Patterns / Refuse List. The shared meta-instruction for applying it:
+
+- **State the rule by name when refusing.** Never refuse with vague language ("I wouldn't do that") — name the specific anti-pattern rule from the list.
+- The anti-pattern list is a first-class part of the persona, not an afterthought.
+- Refusing is not optional when the request violates a named rule.
+
+---
+
+## Engineer Workflow Invariants
+
+These steps appear in every engineer persona's workflow and are non-negotiable:
+
+1. **Read the actual code before any proposal.** No speculation about patterns the codebase doesn't use. Use the `Read` tool.
+2. **Grep/find existing patterns before inventing new ones.** Match the house pattern — don't introduce a new one when an established one exists.
+3. **Cite the framework heuristic by name** when refusing or recommending.
+
+---
+
+## Shared Operational Constraints
+
+Constraints that are identical across all three engineer personas:
+
+- MUST `Read` (or `Read`/`Grep`/`Bash`) before proposing any change to the codebase.
+- File:line citations for every specific claim about code.
+- Cite the framework heuristic by name when refusing or recommending.
+- **STRICTLY FORBIDDEN from starting with "Great", "Certainly", "Okay", "Sure"**.
+- Never end with "Let me know if you have questions".
+- Never make architecture-level or product decisions — those belong to other lanes (Waleed, Layla, Hussain-PM, Sadiq, etc.).

package/rihal/references/phase-id-conventions.md

@@ -0,0 +1,101 @@
+# Phase ID Conventions
+
+The canonical rule for naming a phase in rcode. Issue #718.
+
+---
+
+## TL;DR
+
+| Shape | Example | Use case |
+|-------|---------|----------|
+| `<int>` | `19`, `22`, `103` | Top-level phase added at the end of the current milestone |
+| `<int>.<int>` | `19.1`, `19.2`, `22.3` | Sub-phase inserted under an existing parent |
+| anything else | `A1`, `B5`, `phase-x`, `06` | **REJECTED** |
+
+Validate any ID with:
+
+```bash
+node .rihal/bin/rihal-tools.cjs validate-phase-id <id>
+```
+
+Scan an entire ROADMAP at once:
+
+```bash
+node .rihal/bin/rihal-tools.cjs validate-roadmap
+```
+
+---
+
+## Why these are the only two shapes
+
+**Integer phases (`19`, `22`)** are the natural unit of milestone progress.
+They're added to the end of the roadmap by `/rihal-add-phase` and the
+`phase add` CLI calculates the next number automatically. This is the
+default — 99% of phases should be integers.
+
+**Decimal sub-phases (`19.1`, `19.2`)** exist for one purpose: inserting
+focused work under an already-defined parent without renumbering everything
+after it. Use `/rihal-phase insert 19.1` (the `phase` subcommand) — the
+parent phase stays `19`, the sub-phase fits between `19` and `20` without
+shifting `20→21→22…`.
+
+**Anything else is freestyling.** Audit-style outputs that produce `A1`,
+`B5`, "Audit Phase 1", or domain-prefixed names (`auth-1`, `sec-2`) break:
+
+- ROADMAP.md parsing — the `## Phase <id>` regex assumes a number
+- State.json schema — `phases[].id` is typed as a number-or-decimal string
+- Dashboard rendering — sorts phases by numeric value
+- Cross-phase references in SUMMARY.md, PLAN.md, etc.
+
+If you find yourself wanting `A1` or `B1`, you actually want **two
+milestones**: one for audit, one for implementation. Run
+`/rihal-complete-milestone` on the audit milestone before the
+implementation work starts.
+
+---
+
+## Leading zeros: never
+
+Per feedback memory: `19`, not `019`. `6`, not `06`. The validator
+rejects leading-zero forms explicitly because they cause downstream
+sorting bugs and inconsistent file naming (`.planning/phases/06-foo`
+vs `.planning/phases/6-foo`).
+
+---
+
+## Where the validator fires
+
+- **`/rihal-add-phase`** — runs `milestone-health` after adding, nudges
+  toward `/rihal-complete-milestone` when ≥8 phases are open.
+- **`/rihal-status`** — surfaces milestone-health gauge when not `healthy`.
+- **CI** (`test/scope-history-parity.test.cjs` style) — a future test
+  can call `validate-roadmap` against the committed ROADMAP.md.
+
+Workflows that produce phase IDs from AI freestyle (`/rihal-plan`,
+`/rihal-audit-milestone`) MUST call `validate-phase-id` before writing
+to disk. If they don't, file an issue.
+
+---
+
+## Milestone health thresholds
+
+| Open phases | Recommendation | Behavior |
+|-------------|----------------|----------|
+| 0–7 | `healthy` | Quiet — no nudge |
+| 8–11 | `consider-closing` | Soft nudge after `/rihal-add-phase` |
+| ≥12 | `should-close` | Hard nudge with both close + fork commands |
+
+Bump thresholds in a future PR if real-world data shows users want bigger
+milestones. Current numbers are conservative on purpose — long milestones
+without closure are the original symptom.
+
+---
+
+## Related
+
+- `rihal/workflows/add-phase.md` — milestone-health check after adding
+- `rihal/workflows/status.md` — milestone-health gauge in status output
+- `rihal/workflows/complete-milestone.md` — the closure workflow
+- `rihal/bin/rihal-tools.cjs` — `validate-phase-id`, `validate-roadmap`,
+  `milestone-health` subcommands
+- Issue #718 (this file's origin)