@hanzlaa/rcode 2.1.0

package/rihal/workflows/pause-work.md

@@ -0,0 +1,243 @@
+# Workflow: rihal:pause-work
+
+<purpose>
+Capture full project context and blocking constraints before pausing work. Creates `.rihal/HANDOFF.json` (structured machine-readable handoff) and `.rihal/.continue-here.md` (human-readable summary) for seamless context restoration on resume.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:pause-work <argument-here>
+```
+
+**Examples:**
+```
+/rihal:pause-work example 1
+/rihal:pause-work example 2
+```
+
+STOP — do not proceed.
+
+<available_tools>
+- Bash — read git status, log, file listing
+- Read — read state.json, current SPRINT.md
+- AskUserQuestion — collect blocking notes and constraints
+- Write — write HANDOFF.json and .continue-here.md
+</available_tools>
+
+## Step 1 — Load Project State
+
+```bash
+# Check Rihal project exists
+[ -d .rihal ] || (echo "❌ Not a Rihal project" && exit 1)
+
+# Load state.json
+cat .rihal/state.json 2>/dev/null || echo "{}"
+
+# Get git status
+git status --short
+
+# Get recent commits
+git log -5 --oneline --no-decorate
+
+# List current planning files
+find .planning -type f -name "*.md" 2>/dev/null | sort || true
+```
+
+Extract from state.json:
+- `current_phase` — active phase name
+- `current_sprint` — active plan index
+- `phases` — list of all phases
+- `executions` — completed executions
+- `blockers` — unresolved blockers
+- `decisions` — recent decisions
+
+## Step 2 — Read Active Plan (if any)
+
+If `current_sprint > 0`:
+
+```bash
+# Find the active SPRINT.md
+PLAN_FILE=$(find .planning/plans -name "SPRINT.md" -type f | head -1)
+[ -f "$PLAN_FILE" ] && cat "$PLAN_FILE" || true
+```
+
+Extract from active SPRINT.md:
+- Objective
+- Task list
+- Checkpoint status
+- Any in-progress or blocked tasks
+
+## Step 3 — Collect Blocking Constraints
+
+Ask user via AskUserQuestion for any constraints or notes:
+
+```
+Question:
+Are there any blocking constraints, external dependencies, or critical notes
+the next session should know about?
+
+Examples:
+  - Waiting for Figma designs (due Friday)
+  - Auth service down, can't test login
+  - Blocked on customer approval for Feature X
+  - Database migration needs manual intervention on production
+
+Leave blank if none.
+
+Your answer:
+```
+
+Store response as `blocking_constraints` string.
+
+## Step 4 — Analyze Uncommitted Work
+
+```bash
+GIT_STATUS=$(git status --short)
+UNCOMMITTED_COUNT=$(echo "$GIT_STATUS" | wc -l)
+
+# Categorize changes
+MODIFIED=$(echo "$GIT_STATUS" | grep "^ M" | awk '{print $2}' | tr '\n' ', ')
+ADDED=$(echo "$GIT_STATUS" | grep "^A " | awk '{print $2}' | tr '\n' ', ')
+DELETED=$(echo "$GIT_STATUS" | grep "^ D" | awk '{print $2}' | tr '\n' ', ')
+UNTRACKED=$(echo "$GIT_STATUS" | grep "^?" | awk '{print $2}' | tr '\n' ', ')
+```
+
+## Step 5 — Build HANDOFF.json
+
+Write `.rihal/HANDOFF.json` with structured data:
+
+```json
+{
+  "timestamp": "ISO-8601 timestamp",
+  "project": "project name from state.json",
+  "current_phase": "name of current phase or null",
+  "current_sprint": "index of current plan or 0",
+  "phases": [
+    {
+      "name": "phase name",
+      "status": "not-started|in-progress|completed",
+      "slug": "phase-slug"
+    }
+  ],
+  "completed_tasks": [
+    {
+      "plan": "SPRINT.md filename",
+      "task": "task description",
+      "completed_at": "ISO-8601 timestamp"
+    }
+  ],
+  "remaining_tasks": [
+    {
+      "plan": "SPRINT.md filename",
+      "task": "task description",
+      "status": "in-progress|blocked|pending"
+    }
+  ],
+  "uncommitted_files": {
+    "modified": ["file1", "file2"],
+    "added": ["file3"],
+    "deleted": ["file4"],
+    "untracked": ["file5"]
+  },
+  "blocking_constraints": "user-provided notes",
+  "notes": "auto-generated summary",
+  "decisions": [
+    {
+      "summary": "decision text",
+      "phase": "phase name",
+      "date": "ISO-8601 timestamp"
+    }
+  ],
+  "next_steps": [
+    "Suggested action 1",
+    "Suggested action 2"
+  ]
+}
+```
+
+## Step 6 — Write .continue-here.md
+
+Write `.rihal/.continue-here.md` with human-readable summary:
+
+```markdown
+# Resume from: {timestamp}
+
+## Project Status
+- **Phase:** {current_phase or "Not started"}
+- **Progress:** {X of Y phases completed}
+
+## Current Work
+{If current plan active:}
+- **Plan:** {filename}
+- **Objective:** {objective from SPRINT.md}
+- **Status:** {in-progress|paused|blocked}
+
+## Uncommitted Work
+{If uncommitted_count > 0:}
+```
+Modified: {list}
+Added: {list}
+Deleted: {list}
+Untracked: {list}
+```
+{Else:}
+No uncommitted changes.
+
+## Blocking Constraints
+{blocking_constraints or "None"}
+
+## Key Decisions
+{list 3 most recent decisions}
+
+## Next Steps
+1. {suggested action 1}
+2. {suggested action 2}
+3. {suggested action 3}
+
+---
+
+To resume work, run:
+\`\`\`bash
+/rihal:resume-work
+\`\`\`
+```
+
+## Step 7 — Print Summary
+
+```
+✓ Work paused successfully!
+
+Handoff saved:
+  - Machine-readable: .rihal/HANDOFF.json
+  - Human-readable: .rihal/.continue-here.md
+  - State snapshot: .rihal/state.json (updated)
+
+Current phase: {current_phase or "Not started"}
+Uncommitted changes: {count}
+
+Blocking constraints:
+  {blocking_constraints or "None"}
+
+To resume work, run:
+
+/rihal:resume-work
+```
+
+## Success Criteria
+
+- [ ] Task completed as requested
+- [ ] Output saved or reported
+- [ ] State updated if necessary
+- [ ] No errors encountered
+
+## On Error
+
+If arguments are invalid, missing files, or subagent fails:
+- Validate inputs match expected format
+- Check that required files exist
+- Retry with clearer arguments or report the specific error to the user
+

package/rihal/workflows/plan-milestone-gaps.md

@@ -0,0 +1,273 @@
+<purpose>
+Create all phases necessary to close gaps identified by `/rihal:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/rihal:add-phase` per gap.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 1. Load Audit Results
+
+```bash
+# Find the most recent audit file
+(ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null || true) | head -1
+```
+
+Parse YAML frontmatter to extract structured gaps:
+- `gaps.requirements` — unsatisfied requirements
+- `gaps.integration` — missing cross-phase connections
+- `gaps.flows` — broken E2E flows
+
+If no audit file exists or has no gaps, error:
+```
+No audit gaps found. Run `/rihal:audit-milestone` first.
+```
+
+## 2. Prioritize Gaps
+
+Group gaps by priority from REQUIREMENTS.md:
+
+| Priority | Action |
+|----------|--------|
+| `must` | Create phase, blocks milestone |
+| `should` | Create phase, recommended |
+| `nice` | Ask user: include or defer? |
+
+For integration/flow gaps, infer priority from affected requirements.
+
+## 3. Group Gaps into Phases
+
+Cluster related gaps into logical phases:
+
+**Grouping rules:**
+- Same affected phase → combine into one fix phase
+- Same subsystem (auth, API, UI) → combine
+- Dependency order (fix stubs before wiring)
+- Keep phases focused: 2-4 tasks each
+
+**Example grouping:**
+```
+Gap: DASH-01 unsatisfied (Dashboard doesn't fetch)
+Gap: Integration Phase 1→3 (Auth not passed to API calls)
+Gap: Flow "View dashboard" broken at data fetch
+
+→ Phase 6: "Wire Dashboard to API"
+  - Add fetch to Dashboard.tsx
+  - Include auth header in fetch
+  - Handle response, update state
+  - Render user data
+```
+
+## 4. Determine Phase Numbers
+
+Find highest existing phase:
+```bash
+# Get sorted phase list, extract last one
+HIGHEST=$(node ".rihal/bin/rihal-tools.cjs" phases list --pick directories[-1])
+```
+
+New phases continue from there:
+- If Phase 5 is highest, gaps become Phase 6, 7, 8...
+
+## 5. Present Gap Closure Plan
+
+```markdown
+## Gap Closure Plan
+
+**Milestone:** {version}
+**Gaps to close:** {N} requirements, {M} integration, {K} flows
+
+### Proposed Phases
+
+**Phase {N}: {Name}**
+Closes:
+- {REQ-ID}: {description}
+- Integration: {from} → {to}
+Tasks: {count}
+
+**Phase {N+1}: {Name}**
+Closes:
+- {REQ-ID}: {description}
+- Flow: {flow name}
+Tasks: {count}
+
+{If nice-to-have gaps exist:}
+
+### Deferred (nice-to-have)
+
+These gaps are optional. Include them?
+- {gap description}
+- {gap description}
+
+---
+
+Create these {X} phases? (yes / adjust / defer all optional)
+```
+
+Wait for user confirmation.
+
+## 6. Update ROADMAP.md
+
+Add new phases to current milestone:
+
+```markdown
+### Phase {N}: {Name}
+**Goal:** {derived from gaps being closed}
+**Requirements:** {REQ-IDs being satisfied}
+**Gap Closure:** Closes gaps from audit
+
+### Phase {N+1}: {Name}
+...
+```
+
+## 7. Update REQUIREMENTS.md Traceability Table (REQUIRED)
+
+For each REQ-ID assigned to a gap closure phase:
+- Update the Phase column to reflect the new gap closure phase
+- Reset Status to `Pending`
+
+Reset checked-off requirements the audit found unsatisfied:
+- Change `[x]` → `[ ]` for any requirement marked unsatisfied in the audit
+- Update coverage count at top of REQUIREMENTS.md
+
+```bash
+# Verify traceability table reflects gap closure assignments
+grep -c "Pending" .planning/REQUIREMENTS.md
+```
+
+## 8. Create Phase Directories
+
+```bash
+mkdir -p ".planning/phases/{NN}-{name}"
+```
+
+## 9. Commit Roadmap and Requirements Update
+
+```bash
+node ".rihal/bin/rihal-tools.cjs" commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
+```
+
+## 10. Offer Next Steps
+
+```markdown
+## ✓ Gap Closure Phases Created
+
+**Phases added:** {N} - {M}
+**Gaps addressed:** {count} requirements, {count} integration, {count} flows
+
+---
+
+## ▶ Next Up
+
+**Plan first gap closure phase**
+
+`/clear` then:
+
+`/rihal:plan {N}`
+
+---
+
+**Also available:**
+- `/rihal:execute-phase {N}` — if plans already exist
+- `cat .planning/ROADMAP.md` — see updated roadmap
+
+---
+
+**After all gap phases complete:**
+
+`/rihal:audit-milestone` — re-audit to verify gaps closed
+`/rihal:complete-milestone {version}` — archive when audit passes
+```
+
+</process>
+
+<gap_to_phase_mapping>
+
+## How Gaps Become Tasks
+
+**Requirement gap → Tasks:**
+```yaml
+gap:
+  id: DASH-01
+  description: "User sees their data"
+  reason: "Dashboard exists but doesn't fetch from API"
+  missing:
+    - "useEffect with fetch to /api/user/data"
+    - "State for user data"
+    - "Render user data in JSX"
+
+becomes:
+
+phase: "Wire Dashboard Data"
+tasks:
+  - name: "Add data fetching"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useEffect that fetches /api/user/data on mount"
+
+  - name: "Add state management"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useState for userData, loading, error states"
+
+  - name: "Render user data"
+    files: [src/components/Dashboard.tsx]
+    action: "Replace placeholder with userData.map rendering"
+```
+
+**Integration gap → Tasks:**
+```yaml
+gap:
+  from_phase: 1
+  to_phase: 3
+  connection: "Auth token → API calls"
+  reason: "Dashboard API calls don't include auth header"
+  missing:
+    - "Auth header in fetch calls"
+    - "Token refresh on 401"
+
+becomes:
+
+phase: "Add Auth to Dashboard API Calls"
+tasks:
+  - name: "Add auth header to fetches"
+    files: [src/components/Dashboard.tsx, src/lib/api.ts]
+    action: "Include Authorization header with token in all API calls"
+
+  - name: "Handle 401 responses"
+    files: [src/lib/api.ts]
+    action: "Add interceptor to refresh token or redirect to login on 401"
+```
+
+**Flow gap → Tasks:**
+```yaml
+gap:
+  name: "User views dashboard after login"
+  broken_at: "Dashboard data load"
+  reason: "No fetch call"
+  missing:
+    - "Fetch user data on mount"
+    - "Display loading state"
+    - "Render user data"
+
+becomes:
+
+# Usually same phase as requirement/integration gap
+# Flow gaps often overlap with other gap types
+```
+
+</gap_to_phase_mapping>
+
+<success_criteria>
+- [ ] MILESTONE-AUDIT.md loaded and gaps parsed
+- [ ] Gaps prioritized (must/should/nice)
+- [ ] Gaps grouped into logical phases
+- [ ] User confirmed phase plan
+- [ ] ROADMAP.md updated with new phases
+- [ ] REQUIREMENTS.md traceability table updated with gap closure phase assignments
+- [ ] Unsatisfied requirement checkboxes reset (`[x]` → `[ ]`)
+- [ ] Coverage count updated in REQUIREMENTS.md
+- [ ] Phase directories created
+- [ ] Changes committed (includes REQUIREMENTS.md)
+- [ ] User knows to run `/rihal:plan` next
+</success_criteria>