@hanzlaa/rcode 3.4.30 → 3.4.32

package/rihal/references/sprint-checker-playbook.md

@@ -0,0 +1,128 @@
+# Sprint Checker Playbook
+
+Loaded by `rihal-sprint-checker` via `@-include`. Contains the full
+verification methodology: project context loading, upstream input
+handling, core verification principle, 12 verification dimensions,
+execution steps, mandatory output markers, and constraints.
+
+CRITICAL: The "Mandatory output markers" section is load-bearing.
+The orchestrator malfunction guard checks for `issues:` and
+`verified_files:` YAML blocks in every agent return. Copy this
+section verbatim — no reformatting.
+
+<project_context>
+Before verifying, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agent/skills/` or `.agents/skills/` directory if either exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during verification
+4. 
+5. Verify sprints account for project skill patterns
+
+This ensures verification checks that sprints follow project-specific conventions.
+</project_context>
+
+<upstream_input>
+**CONTEXT.md** (if exists) — User decisions from `/rihal-discuss-phase`
+
+| Section | How You Use It |
+|---------|----------------|
+| `## Decisions` | LOCKED — sprints MUST implement these exactly. Flag if contradicted. |
+| `## the agent's Discretion` | Freedom areas — planner can choose approach, don't flag. |
+| `## Deferred Ideas` | Out of scope — sprints must NOT include these. Flag if present. |
+
+If CONTEXT.md exists, add verification dimension: **Context Compliance**
+- Do sprints honor locked decisions?
+- Are deferred ideas excluded?
+- Are discretion areas handled appropriately?
+</upstream_input>
+
+<core_principle>
+**Sprint completeness =/= Goal achievement**
+
+A task "create auth endpoint" can be in the sprint while password hashing is missing. The task exists but the goal "secure authentication" won't be achieved.
+
+Goal-backward verification works backwards from outcome:
+
+1. What must be TRUE for the phase goal to be achieved?
+2. Which tasks address each truth?
+3. Are those tasks complete (files, action, verify, done)?
+4. Are artifacts wired together, not just created in isolation?
+5. Will execution complete within context budget?
+
+Then verify each level against the actual sprint files.
+
+**The difference:**
+- `rihal-verifier`: Verifies code DID achieve goal (after execution)
+- `rihal-sprint-checker`: Verifies sprints WILL achieve goal (before execution)
+
+Same methodology (goal-backward), different timing, different subject matter.
+</core_principle>
+
+<verification_dimensions>
+
+
+1. Requirement Coverage
+2. Task Completeness
+3. Dependency Correctness
+4. Key Links Planned
+5. Scope Sanity
+6. Verification Derivation
+7. Context Compliance (only if CONTEXT.md present)
+8. Nyquist Compliance
+9. Cross-Sprint Data Contracts
+10. CLAUDE.md Compliance
+11. File References Verification
+12. Evidence Grounding (issue #649) — every task body MUST include an `<evidence>` block citing real grep hit counts, real `path:line` ranges, or an explicit `creates:` justification. A task that names a file count, component, or pattern with no traceable codebase query is **theoretical** and rejected. Run a sample of the cited greps yourself; if the planner's claimed "13 hits" actually returns 4, downgrade to BLOCKER.
+
+Each dimension has pass/partial/fail criteria, remediation guidance, and output format requirements.
+
+</verification_dimensions>
+
+## Execution (Slim)
+
+1. **Load context** — Read phase SCOPE.md, CONTEXT.md (if present), RESEARCH.md, and all SPRINT.md files.
+2. **Run dimensions** — For each verification dimension, collect evidence and classify (pass / partial / fail).
+3. **Programmatic evidence check (issue #649)** — call:
+   ```
+   node .rihal/bin/rihal-tools.cjs plan validate-evidence <phase> --spot-check
+   ```
+   Exit code 0 = pass, 1 = at least one task violation. Inline the JSON `violations[]` into dimension 12 of CHECK.md verbatim — these are authoritative and must not be paraphrased away.
+4. **Synthesize** — Produce CHECK.md with overall verdict, per-dimension scores, remediation asks.
+5. **Return** — Block execution if critical dimensions fail (Evidence Grounding is critical); proceed with cautions if only partials.
+
+## Mandatory output markers (per #440 / #445 fix)
+
+Every return from this agent MUST include at least one of these YAML markers — they prove tool invocation actually happened. The orchestrator's malfunction guard in `plan.md` blocks execution if none are present.
+
+```yaml
+issues:           # always emit, even if empty (issues: [])
+  - dimension: <name>
+    severity: BLOCKER | WARNING | INFO
+    path: <file:line>
+    finding: <short text>
+
+verified_files:   # list every file actually read during verification
+  - path: <relative path>
+    bytes: <int>
+```
+
+If you have not invoked `Read`, `Bash`, `Grep`, or `Glob` during execution, do NOT return — instead, report the failure and stop. Empty narrative output is treated as malfunction, not pass.
+
+## On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Full dimension definitions with examples, checks, output formats | `.rihal/agents-rules/sprint-checker/dimensions.md` |
+| Step-by-step verification process (Steps 1-9.5) | `.rihal/agents-rules/sprint-checker/process.md` |
+
+Read these only when actually performing the check. Don't preemptively load.
+
+## Constraints
+
+- Never modify sprints — read-only analysis
+- Produce CHECK.md at `.planning/phases/{phase}/{phase}-{sprint}-CHECK.md`
+- Block execution on critical fails (missing coverage, broken deps, unverifiable outcomes)

package/rihal/references/ux-designer-playbook.md

@@ -0,0 +1,74 @@
+# UX Designer Playbook
+
+Loaded by `rihal-ux-designer` via `@-include`. Contains the full thinking
+framework, specialization descriptions, workflow steps, and worked examples.
+
+The agent stub holds the role identity, response format, principles,
+anti-patterns, redirects, and constraints.
+
+---
+
+## How you think
+
+Every UX question has four pressure points:
+1. **What is the user's goal in this moment?** — Not the feature, the goal. User completes checkout, not "user sees payment form"
+2. **What feedback does the user need to feel in control?** — Loading states, progress, errors, success. Silence kills trust.
+3. **What will confuse this user?** — Name one specific misconception and design around it
+4. **How does this serve the 10th-time user, not the first?** — Delight happens through invisible efficiency
+
+---
+
+## Specializations
+
+### Usability Audits
+
+- Audit existing interfaces for clarity, consistency, friction
+- Map user journeys and identify drop-off points
+- Test against accessibility standards (WCAG 2.1 AA minimum)
+- Recommend low-cost, high-impact improvements
+
+### Design System Work
+
+- Define component library philosophy: when to have variants vs. separate components
+- Establish typography, color, spacing scales
+- Document patterns for forms, tables, modals, navigation
+- Ensure consistency across surfaces without becoming rigid
+
+### Accessibility Strategy
+
+- Audit for WCAG violations (color contrast, keyboard navigation, screen reader support)
+- Design for real disability, not sympathy: cognitive load, motor control, sensory limitations
+- Plan gradual remediation: quick wins vs. architectural changes
+- Educate team on accessible design as capability, not compliance checkbox
+
+### Design-Driven Decisions
+
+- Evaluate features through UX lens: launch simpler version first, layer complexity
+- Design for different user segments (power users vs. newcomers)
+- Plan onboarding and progressive disclosure (novice → expert)
+- Define "done" through user success metrics, not design completion
+
+---
+
+## Workflow
+
+1. **Identify the user's goal** — not the feature request. What is the user trying to accomplish?
+2. **Map current friction** — where do users get stuck, abandon, or misunderstand?
+3. **Propose flows** — user journey maps, not wireframes. What sequence of interactions gets the user to their goal?
+4. **Apply four pressure points** — goal clarity, feedback needs, confusing elements, 10th-time efficiency.
+5. **Handle edge cases** — empty states, error states, loading states, rare-but-valid paths.
+6. **Define success metrics** — how will we know the design worked? Conversion, task completion time, error rate.
+7. **Route** — implementation to Haitham, prioritization to Hussain-PM, technical feasibility to Waleed.
+
+---
+
+## Examples
+
+**Happy path** — design lead management flow
+> 🎨 **UX Designer:** Goal: sales rep records a lead during a call, in under 30 seconds. Current friction: 7-field form with required fields. Per 10th-time-user, after 100 leads they know the required fields — but they still tab through all 7. Proposed: 3-field quick-add (name, phone, source) → drawer to fill rest later. Empty state for missing data shows inline edit prompt. Error state gives field-specific guidance, not generic "please fix errors."
+
+**Edge case** — designing for RTL and LTR simultaneously
+> 🎨 **UX Designer:** Navigation flows left-to-right cognitively in LTR but right-to-left in Arabic RTL. "Next step" arrow direction inverts. Breadcrumbs reverse. Checklist item position mirrors. Route to Haitham for logical-properties implementation — these are implementation decisions once the direction hierarchy is defined.
+
+**Negative** — asked to evaluate a feature request for business fit
+> 🎨 **UX Designer:** "Should we build X?" is a strategy question, not a UX question. I evaluate HOW to design X once it's in scope. Route to Sadiq for "should we build it" and Hussain-PM for scope and prioritization: `/rihal-council sadiq hussain-pm — feature fit for [X]`.

package/rihal/references/verifier-playbook.md

@@ -0,0 +1,104 @@
+# Verifier Playbook
+
+Loaded by `rihal-verifier` via `@-include`. Contains the full verification
+flow, final status tables, on-demand rule files, and success criteria checklist.
+
+The agent stub holds the role definition, critical rules, constraints, and
+@-include list.
+
+---
+
+## Project Context Loading
+
+Before verifying, discover project context:
+
+- **Project instructions:** Read `./CLAUDE.md` if it exists. Follow project-specific guidelines.
+- **Project skills:** Check `.agent/skills/` or `.agents/skills/` directories. Load relevant `SKILL.md` indexes and `rules/*.md` files as needed during verification.
+
+---
+
+## Core Principle
+
+**Task completion ≠ Goal achievement.** A task "create chat component" can be marked complete when the component is a placeholder. Goal-backward verification asks:
+
+1. What must be TRUE for the goal to be achieved?
+2. What must EXIST for those truths to hold?
+3. What must be WIRED for those artifacts to function?
+4. What data must FLOW for those artifacts to be real?
+
+---
+
+## Verification Flow (Slim)
+
+1. **Check for previous VERIFICATION.md** — if exists with gaps, enter RE-VERIFICATION MODE (skip to Step 3).
+2. **Load context** — SPRINT.md, SUMMARY.md, ROADMAP.md goal, REQUIREMENTS.md.
+3. **Establish must-haves** — from PLAN frontmatter (Option A), ROADMAP success criteria (Option B), or derive from goal (Option C).
+4. **Verify observable truths** — for each truth, status ✓ VERIFIED / ✗ FAILED / ? UNCERTAIN.
+5. **Verify artifacts (3 levels)** — exists, substantive, wired. Use `rihal-tools.cjs verify artifacts`.
+6. **Data-flow trace (Level 4)** — for wired artifacts rendering dynamic data, trace upstream to confirm real data source.
+7. **Verify key links** — component→API, API→DB, form→handler, state→render. Use `rihal-tools.cjs verify key-links`.
+8. **Requirements coverage** — cross-reference PLAN `requirements:` against REQUIREMENTS.md. Flag ORPHANED.
+9. **Anti-pattern scan** — TODO/FIXME/placeholder/empty-return/hardcoded-empty. Classify Blocker/Warning/Info.
+10. **Behavioral spot-checks** — run 2-4 quick commands (<10s each) against runnable code. Skip if no runnable entry points.
+11. **Human verification needs** — visual, real-time, external service, uncertain wiring.
+12. **Determine status** — passed | gaps_found | human_needed. Score = verified_truths / total_truths.
+13. **Structure gap output** — YAML frontmatter for `/rihal-plan --gaps`.
+14. **Create VERIFICATION.md** — use Write tool (never heredoc). Return to orchestrator. DO NOT COMMIT.
+
+---
+
+## Final Status Tables
+
+**Artifact status (all 4 levels):**
+
+| Exists | Substantive | Wired | Data Flows | Status |
+| ------ | ----------- | ----- | ---------- | ------ |
+| ✓ | ✓ | ✓ | ✓ | ✓ VERIFIED |
+| ✓ | ✓ | ✓ | ✗ | ⚠️ HOLLOW — wired but data disconnected |
+| ✓ | ✓ | ✗ | - | ⚠️ ORPHANED |
+| ✓ | ✗ | - | - | ✗ STUB |
+| ✗ | - | - | - | ✗ MISSING |
+
+**Overall status decision:**
+
+- **passed** — All truths VERIFIED, all artifacts pass 1-3, all key links WIRED, no blocker anti-patterns.
+- **gaps_found** — Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker anti-patterns found.
+- **human_needed** — All automated checks pass but items flagged for human verification.
+
+---
+
+## On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Previous-verification check + load context + establish must-haves (Steps 0-2) | `.rihal/agents-rules/verifier/context-loading.md` |
+| Observable truths + 3-level artifact verification (Steps 3-4) | `.rihal/agents-rules/verifier/artifact-verification.md` |
+| Level-4 data-flow trace patterns (Step 4b) | `.rihal/agents-rules/verifier/data-flow-trace.md` |
+| Key link wiring fallback patterns (Step 5) | `.rihal/agents-rules/verifier/key-links.md` |
+| Requirements coverage + orphaned detection (Step 6) | `.rihal/agents-rules/verifier/requirements-coverage.md` |
+| Anti-pattern grep commands + stub reference patterns (Step 7) | `.rihal/agents-rules/verifier/anti-patterns.md` |
+| Behavioral spot-check command examples (Step 7b) | `.rihal/agents-rules/verifier/behavioral-spot-checks.md` |
+| Status determination + gap YAML structure (Steps 8-10) | `.rihal/agents-rules/verifier/gap-output.md` |
+| VERIFICATION.md template + return-to-orchestrator format | `.rihal/agents-rules/verifier/verification-report.md` |
+
+Read these ONLY when the current step needs them. Don't preemptively load.
+
+---
+
+## Success Criteria
+
+- [ ] Previous VERIFICATION.md checked (Step 0)
+- [ ] Must-haves loaded (re-verification) or established (initial mode)
+- [ ] All truths verified with status and evidence
+- [ ] All artifacts checked at levels 1-3 (exists, substantive, wired)
+- [ ] Data-flow trace (Level 4) run on wired artifacts that render dynamic data
+- [ ] All key links verified
+- [ ] Requirements coverage assessed (if applicable)
+- [ ] Anti-patterns scanned and categorized
+- [ ] Behavioral spot-checks run on runnable code (or skipped with reason)
+- [ ] Human verification items identified
+- [ ] Overall status determined
+- [ ] Gaps structured in YAML frontmatter (if gaps_found)
+- [ ] Re-verification metadata included (if previous existed)
+- [ ] VERIFICATION.md created via Write tool
+- [ ] Results returned to orchestrator (NOT committed)

package/rihal/skills/actions/1-analysis/research/rihal-domain-research/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-domain-research
+internal: true
 description: >
   Conduct industry domain deep-dive research to build subject matter
   expertise on a specific business domain. Activates when the user says

package/rihal/skills/actions/1-analysis/research/rihal-market-research/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-market-research
+internal: true
 description: >
   Analyze market size, competitive landscape, customer needs, and trends for
   a product or industry. Activates when the user says "market research",

package/rihal/skills/actions/1-analysis/research/rihal-technical-research/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-technical-research
+internal: true
 description: >
   Research technical feasibility, architecture options, and implementation
   approaches for a proposed product or feature. Activates when the user says

package/rihal/skills/actions/1-analysis/rihal-document-project/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-document-project
+internal: true
 description: >
   Analyze an existing codebase and produce documentation for both human and
   LLM consumption (brownfield analysis). Activates when the user says

package/rihal/skills/actions/1-analysis/rihal-prfaq/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-prfaq
+internal: true
 description: Working Backwards PRFAQ challenge to forge product concepts.
 triggers:
   - "prfaq"

package/rihal/skills/actions/1-analysis/rihal-product-brief/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-product-brief
+internal: true
 description: >
   Create a product brief through guided discovery or autonomous research.
   Activates when the user says "create a product brief", "write a product

package/rihal/skills/actions/2-plan/rihal-create-epics-and-stories/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-create-epics-and-stories
+internal: true
 description: >
   Break a PRD into epics and user stories that drive development. Activates
   when the user says "create epics", "break this into stories", "generate

package/rihal/skills/actions/2-plan/rihal-create-milestone/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-create-milestone
+internal: true
 description: >
   Design the milestone roadmap (M1..Mn) for a project from an approved PRD.
   Activates when the user says "create milestones", "plan milestones",

package/rihal/skills/actions/2-plan/rihal-create-prd/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-create-prd
+internal: true
 description: >
   Create a new Product Requirements Document from scratch through guided
   facilitation. Activates when the user says "create a PRD", "write product

package/rihal/skills/actions/2-plan/rihal-create-story/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-create-story
+internal: true
 description: >
   Prepare a dev-ready user story with full implementation context. Activates
   when the user says "create the next story", "prepare a story", "create

package/rihal/skills/actions/2-plan/rihal-create-ux-design/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-create-ux-design
+internal: true
 description: >
   Guide through realizing a UX design that informs architecture and
   implementation — user flows, wireframes, design system updates. Activates

package/rihal/skills/actions/2-plan/rihal-edit-prd/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-edit-prd
+internal: true
 description: >
   Update an existing Product Requirements Document with new sections,
   revisions, or clarifications. Activates when the user says "update the

package/rihal/skills/actions/2-plan/rihal-frontend-design/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-frontend-design
+internal: true
 description: >
   Create distinctive, production-grade frontend interfaces with a committed
   aesthetic direction — typography, colour, motion, spatial composition,

package/rihal/skills/actions/2-plan/rihal-validate-prd/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-validate-prd
+internal: true
 description: >
   Validate an existing PRD for comprehensiveness, leanness, organization,
   and internal consistency. Activates when the user says "validate the PRD",

package/rihal/skills/actions/3-solutioning/rihal-check-implementation-readiness/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-check-implementation-readiness
+internal: true
 description: >
   Verify that PRD, UX designs, architecture decisions, and epics/stories are
   all aligned and ready for implementation. Activates when the user says

package/rihal/skills/actions/3-solutioning/rihal-create-architecture/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-create-architecture
+internal: true
 description: >
   Write an Architecture Decision Record (ADR) to lock a significant
   technical decision. Activates when the user says "write an ADR", "create

package/rihal/skills/actions/3-solutioning/rihal-generate-project-context/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-generate-project-context
+internal: true
 description: >
   Generate a project-context.md file that summarizes project standards,
   conventions, tech stack, and key patterns for AI agents to reference.

package/rihal/skills/actions/4-implementation/rihal-browser-verify/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-browser-verify
+internal: true
 description: Use Chrome DevTools MCP to verify browser behaviour — DOM state, console errors, network requests,.
 triggers:
   - "verify in browser"

package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-checkpoint-preview
+internal: true
 description: "LLM-assisted human-in-the-loop review."
 triggers:
   - "checkpoint preview"

package/rihal/skills/actions/4-implementation/rihal-ci/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-ci
+internal: true
 description: CI/CD setup and quality gates for the rcode-default stack — GitHub Actions for Node test matrix,.
 triggers:
   - "set up ci"

package/rihal/skills/actions/4-implementation/rihal-code-review/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-code-review
+internal: true
 description: >
   Review code changes using parallel adversarial review layers and produce
   actionable findings. Activates when the user says "review this code", "run

package/rihal/skills/actions/4-implementation/rihal-correct-course/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-correct-course
+internal: true
 description: >
   Course-correct when major change is discovered mid-sprint or
   mid-implementation. Activates when the user says "course correct", "change

package/rihal/skills/actions/4-implementation/rihal-debug/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-debug
+internal: true
 description: Root-cause debugging via the scientific method.
 triggers:
   # English

package/rihal/skills/actions/4-implementation/rihal-dev-story/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-dev-story
+internal: true
 description: >
   Execute an approved story file by writing tests and code that fulfill
   every acceptance criterion. Activates when the user says "dev this story",

package/rihal/skills/actions/4-implementation/rihal-git-flow/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-git-flow
+internal: true
 description: Branching, commits, conflicts, parallel work — aligned with the Rihal Epic→Feature→Task hierarchy.
 triggers:
   - "git flow"

package/rihal/skills/actions/4-implementation/rihal-harden/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-harden
+internal: true
 description: Security hardening checklist for SaaS applications.
 triggers:
   - "harden this"

package/rihal/skills/actions/4-implementation/rihal-incremental/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-incremental
+internal: true
 description: Ship code in small, atomic, verifiable steps.
 triggers:
   - "ship incrementally"

package/rihal/skills/actions/4-implementation/rihal-migrate/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-migrate
+internal: true
 description: Plan and execute the move from MVP to production-grade infrastructure without rewriting from.
 triggers:
   - "graduate the mvp"

package/rihal/skills/actions/4-implementation/rihal-perf/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-perf
+internal: true
 description: Performance optimisation for the rcode-default stack — Next.js (LCP / TBT / CLS / hydration),.
 triggers:
   - "optimize performance"

package/rihal/skills/actions/4-implementation/rihal-prove-it/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-prove-it
+internal: true
 description: Test-first development.
 triggers:
   - "prove it"

package/rihal/skills/actions/4-implementation/rihal-qa-generate-e2e-tests/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-qa-generate-e2e-tests
+internal: true
 description: >
   Generate end-to-end tests for an existing feature using the project's
   standard test framework. Activates when the user says "generate e2e

package/rihal/skills/actions/4-implementation/rihal-retrospective/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-retrospective
+internal: true
 description: >
   Run an epic retrospective that reviews completed work, extracts learnings,
   and produces owned action items. Activates when the user says "run

package/rihal/skills/actions/4-implementation/rihal-scaffold-project/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-scaffold-project
+internal: true
 description: >
   Scaffold a new project for Rihalians using the official Rihal template repo.
   Activates when the user says "scaffold project", "create project", "new project",

package/rihal/skills/actions/4-implementation/rihal-source-truth/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-source-truth
+internal: true
 description: Cite official documentation before writing or recommending any framework, library, or API code.
 triggers:
   - "cite the docs"

package/rihal/skills/actions/4-implementation/rihal-sprint-planning/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-sprint-planning
+internal: true
 description: >
   Generate or update a sprint plan that sequences stories for dev execution.
   Activates when the user says "plan the sprint", "create sprint plan", "run

package/rihal/skills/actions/4-implementation/rihal-sprint-status/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-sprint-status
+internal: true
 description: >
   Generate a sprint status report showing progress, blockers, and
   recommended next actions. Activates when the user says "sprint status",

package/rihal/skills/actions/4-implementation/rihal-trim/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: rihal-trim
+internal: true
 description: Code simplification.
 triggers:
   - "trim this"

package/rihal/workflows/add-phase.md

@@ -104,6 +104,43 @@ Update STATE.md to reflect the new phase:
 If "Roadmap Evolution" section doesn't exist, create it.
 </step>
 
+<step name="milestone_health_check">
+After the phase is added, run the milestone-health gauge (issue #718):
+
+```bash
+HEALTH=$(node ".rihal/bin/rihal-tools.cjs" milestone-health 2>/dev/null)
+RECOMMENDATION=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).recommendation||'unknown')}catch{console.log('unknown')}})")
+OPEN_COUNT=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).open_phases||0)}catch{console.log(0)}})")
+MILESTONE_NAME=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).milestone||'')}catch{console.log('')}})")
+```
+
+If `RECOMMENDATION` is `should-close` (≥12 open phases), surface a hard nudge:
+
+```
+⚠ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases.
+
+Phase {N} is now in this milestone, but the milestone is well past the
+12-phase threshold for considering closure. Phases are accumulating without
+a milestone boundary — historically this is where roadmaps lose structure.
+
+Recommended next step:
+  /rihal-complete-milestone    close {MILESTONE_NAME} cleanly + archive done phases
+  /rihal-new-milestone         start a fresh milestone for ongoing work
+
+If you genuinely want a giant single-milestone roadmap, ignore this and
+continue. The threshold is conservative on purpose.
+```
+
+If `RECOMMENDATION` is `consider-closing` (8-11 open phases), softer nudge:
+
+```
+ℹ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases — getting full.
+   Consider /rihal-complete-milestone before adding more.
+```
+
+If `RECOMMENDATION` is `healthy`, say nothing.
+</step>
+
 <step name="completion">
 Present completion summary: