@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/references/revision-loop.md

@@ -0,0 +1,38 @@
+# Revision Loop
+
+When a plan is reviewed (by `rcode-plan-checker`, by a council, or by the user) and the verdict is "needs changes", the planner must run the revision loop — not silently accept the feedback and move on.
+
+## The loop
+
+1. **Receive feedback.** Capture every reviewer concern as a structured list:
+   - Source (which reviewer / agent / user)
+   - Concern (one-sentence summary)
+   - Suggested change (if any)
+   - Severity (blocker / warning / suggestion)
+
+2. **Triage.** For each concern, classify:
+   - **Accept** — change the plan as suggested.
+   - **Counter** — disagree, document why, keep original plan.
+   - **Defer** — out of scope for this phase; file as follow-up.
+
+3. **Apply.** Make the accepted changes to PLAN.md. Mark the diff in a "Revision N" section so reviewers can see what changed.
+
+4. **Re-circulate.** Send the revised plan back to the reviewer that surfaced the blocker. If a council reviewed, send to the same panel.
+
+5. **Iterate or proceed.**
+   - All blockers resolved → proceed to execute.
+   - Any blocker still standing → either escalate (to user) or stop the phase.
+
+## Loop bound
+
+Three revisions is the soft cap. If a plan needs four revisions, the underlying disagreement isn't about the plan — it's about scope, requirements, or strategy. Halt the loop, run `/rcode-discuss-phase` or `/rcode-council` to resolve the upstream disagreement, then start a fresh plan.
+
+## What never happens
+
+- Silent acceptance. If a concern is rejected ("counter"), it's documented with a reason in the PLAN.md revision history.
+- Blanket revisions. Each round addresses specific concerns from specific reviewers. Don't bundle "various improvements" into a single revision.
+- Skipping the loop because the planner thinks they know better. The loop exists because reviewers catch what planners miss.
+
+## Output of the loop
+
+A PLAN.md with a "Revision history" section showing each round, what changed, and who signed off. This becomes the audit trail when the phase ships and someone asks "why did we build it this way?"

package/rcode/references/roadmapper-playbook.md

@@ -0,0 +1,82 @@
+# Roadmapper Playbook
+
+Loaded by `rcode-roadmapper` via `@-include`. Contains the downstream consumer
+table, philosophy, workflow steps, and worked examples.
+
+The agent stub holds the role definition, principles, anti-patterns, and
+@-include list.
+
+---
+
+## Downstream Consumer
+
+Your ROADMAP.md is consumed by `/rcode-plan` which uses it to:
+
+| Output | How Plan-Phase Uses It |
+|--------|------------------------|
+| Phase goals | Decomposed into executable plans |
+| Success criteria | Inform must_haves derivation |
+| Requirement mappings | Ensure plans cover phase scope |
+| Dependencies | Order plan execution |
+
+**Be specific.** Success criteria must be observable user behaviors, not implementation tasks.
+
+---
+
+## Philosophy
+
+### Solo Developer + Agent Workflow
+
+You are roadmapping for ONE person (the user) and ONE implementer (the agent).
+- No teams, stakeholders, sprints, resource allocation
+- User is the visionary/product owner
+- The agent is the builder
+- Phases are buckets of work, not project management artifacts
+
+### Anti-Enterprise
+
+NEVER include phases for:
+- Team coordination, stakeholder management
+- Sprint ceremonies, retrospectives
+- Documentation for documentation's sake
+- Change management processes
+
+If it sounds like corporate PM theater, delete it.
+
+### On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Full detailed guide (tool priorities, output formats, templates, pitfalls, examples) | `.rcode/agents-rules/roadmapper/detailed-guide.md` |
+
+Read only when the current task needs the detail. Don't preemptively load.
+
+---
+
+## Workflow
+
+1. **Read context** — REQUIREMENTS.md, FEATURES.md, ARCHITECTURE.md, STACK.md, RESEARCH.md (per `<files_to_read>`).
+2. **Cluster requirements** — group related requirements into natural delivery units.
+3. **Derive phases** — name each phase by what the user can DO after it, not what was built.
+4. **Map 100% of requirements** — every req maps to exactly one phase. Verify coverage.
+5. **Write success criteria** — 2-5 observable behaviors per phase. Goal-backward.
+6. **Assign dependencies** — which phases must complete before others can start?
+7. **Initialize STATE.md** — project memory with phase list, status=pending.
+8. **Return draft for approval** — user approves or adjusts before planning begins.
+
+---
+
+## Examples
+
+**Happy path** — SaaS product roadmap
+> Roadmapper output for "task management app":
+> Phase 1 — Foundation: User can create an account, log in, and see an empty dashboard. (covers REQ-01, REQ-02, REQ-03)
+> Phase 2 — Core tasks: User can create, edit, complete, and delete tasks. (REQ-04 through REQ-09)
+> Phase 3 — Collaboration: User can share a board and assign tasks to another user. (REQ-10, REQ-11)
+> Each phase: 2-4 weeks of solo implementation. Observable success criteria listed.
+
+**Edge case** — research reveals a dependency conflict between phases
+> A feature in Phase 3 requires a data model change that breaks Phase 2 API contracts. Detected at roadmap time. Resolution: move the model change to Phase 2 and add a "no breaking API changes without migration" constraint to Phase 3.
+
+**Negative** — asked to add a "testing phase" at the end
+> Testing is not a phase — it's embedded in every phase's success criteria and verification step. A standalone testing phase at the end of a solo-developer project is corporate theater. Each phase ships working, tested code or it doesn't ship. Removing.

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

@@ -0,0 +1,128 @@
+# Sprint Checker Playbook
+
+Loaded by `rcode-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 `/rcode-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:**
+- `rcode-verifier`: Verifies code DID achieve goal (after execution)
+- `rcode-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 .rcode/bin/rcode-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 | `.rcode/agents-rules/sprint-checker/dimensions.md` |
+| Step-by-step verification process (Steps 1-9.5) | `.rcode/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/rcode/references/state-schema.md

@@ -0,0 +1,366 @@
+# State Schema Reference
+
+Documents every top-level field in `state.json`, used by rcode workflows for session persistence.
+
+---
+
+## File Structure
+
+```json
+{
+  "version": "1",
+  "project": "...",
+  "created": "...",
+  "updated": "...",
+  "current_phase": "...",
+  "current_plan": 1,
+  "phases": [...],
+  "executions": [...],
+  "decisions": [...],
+  "blockers": [...],
+  "council_sessions": [...],
+  "chains": [...],
+  "last_session": "...",
+  "workstreams": [...],
+  "active_workstream": "...",
+  "model_profile": "..."
+}
+```
+
+---
+
+## Field Reference
+
+### `version`
+**Type:** string  
+**Example:** `"1"`  
+**Written by:** `/rcode-install` (initialization)  
+**Purpose:** Schema version for compatibility checks. Change if fields added/removed.
+
+---
+
+### `project`
+**Type:** string  
+**Example:** `"rcode v2"`  
+**Written by:** `/rcode-install` (reads from config.yaml)  
+**Purpose:** Project name for context and reports.
+
+---
+
+### `created`
+**Type:** ISO date string  
+**Example:** `"2026-04-01T10:30:00Z"`  
+**Written by:** `/rcode-install` (first session)  
+**Purpose:** Timestamp of project creation, never changes.
+
+---
+
+### `updated`
+**Type:** ISO date string  
+**Example:** `"2026-04-12T15:45:30Z"`  
+**Written by:** Any command that modifies state  
+**Purpose:** Last write timestamp; aids session recovery.
+
+---
+
+### `current_phase`
+**Type:** string or null  
+**Example:** `"Phase 2: Authentication"` or `null`  
+**Written by:** `/rcode-do`, `/rcode-next`, `/rcode-resume-work`  
+**Purpose:** Name of active phase, null if no phase active.
+
+---
+
+### `current_plan`
+**Type:** number  
+**Example:** `2`  
+**Written by:** `/rcode-do --execute` (incremented after each phase completion)  
+**Purpose:** Counter for plan versions. Increments 1→2→3 as phases complete.
+
+---
+
+### `phases`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "number": 1,
+    "name": "Setup & Scaffolding",
+    "started": "2026-04-01T10:30:00Z",
+    "completed": "2026-04-03T14:20:00Z",
+    "sprints": [
+      {
+        "id": "01.1",
+        "number": 1,
+        "goal": "Project structure + CI",
+        "status": "completed",
+        "velocity_target": 13,
+        "velocity_actual": 11,
+        "started_at": "2026-04-01T10:30:00Z",
+        "completed_at": "2026-04-02T18:00:00Z",
+        "stories": [
+          {
+            "id": "01.1.01",
+            "title": "Initialize repo with standard layout",
+            "points": 3,
+            "status": "done",
+            "acceptance": "Repo has src/, tests/, CI config"
+          },
+          {
+            "id": "01.1.02",
+            "title": "Setup CI pipeline",
+            "points": 5,
+            "status": "done",
+            "acceptance": "PR checks run lint + test"
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+**Written by:** `/rcode-do --execute`, `/rcode-next`, sprint/story state tools  
+**Purpose:** Tracks phases with nested sprints and stories.
+
+**Sprint fields:**
+- `id` — `{NN}.{S}` (phase.sprint)
+- `goal` — one-sentence sprint focus
+- `status` — `planned | active | completed`
+- `velocity_target` — estimated story points
+- `velocity_actual` — actual points completed (set on sprint complete)
+- `stories[]` — array of story objects
+
+**Story fields:**
+- `id` — `{NN}.{S}.{TT}` (phase.sprint.story)
+- `title` — story description
+- `points` — story points (0 = unestimated)
+- `status` — `todo | in_progress | review | done`
+- `acceptance` — acceptance criteria (optional)
+
+---
+
+### `velocity_history`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  { "sprint": "01.1", "points": 11, "completed_at": "2026-04-02T18:00:00Z" },
+  { "sprint": "01.2", "points": 13, "completed_at": "2026-04-05T16:00:00Z" }
+]
+```
+**Written by:** `sprint complete` state tool  
+**Purpose:** Rolling velocity log. Used to calculate average velocity for sprint capacity planning.
+
+---
+
+### `current_sprint`
+**Type:** string (nullable)  
+**Example:** `"01.1"`  
+**Written by:** `sprint add`, `sprint start`, `sprint complete`  
+**Purpose:** Currently active sprint. Null when no sprint in progress.
+
+---
+
+### `executions`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "plan": "01.02",
+    "tasks": 3,
+    "duration_ms": 3600000,
+    "commit_hash": "abc123def456",
+    "committed_at": "2026-04-03T14:20:00Z"
+  }
+]
+```
+**Written by:** `/rcode-execute` (after each plan completes)  
+**Purpose:** Log of each plan execution. The `plan` field is the plan ID string (e.g., "01.02"), not a number.
+
+---
+
+### `decisions`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "summary": "Use JWT instead of session cookies",
+    "phase": "Phase 2",
+    "plan": 1,
+    "date": "2026-04-04T09:15:00Z"
+  }
+]
+```
+**Written by:** `/rcode-council`, `/rcode-discuss`  
+**Purpose:** Records architectural/strategic decisions for history.
+
+---
+
+### `blockers`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "description": "API rate limit blocks load testing",
+    "phase": "Phase 3",
+    "plan": 1,
+    "date": "2026-04-05T11:00:00Z",
+    "resolved": "2026-04-05T13:30:00Z"
+  }
+]
+```
+**Written by:** `/rcode-do`, `/rcode-health`  
+**Purpose:** Tracks blockers, when identified, which phase, and resolution time.
+
+---
+
+### `council_sessions`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "date": "2026-04-04T10:00:00Z",
+    "question_slug": "auth-strategy",
+    "panel": ["rcode-sadiq", "rcode-waleed", "rcode-fatima"],
+    "artifact_path": "rcode/artifacts/council-sessions/auth-strategy-20260404.md"
+  }
+]
+```
+**Written by:** `/rcode-council`  
+**Purpose:** History of council deliberations, panelists, output artifacts.
+
+---
+
+### `chains`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "date": "2026-04-05T14:00:00Z",
+    "slug": "implement-login-flow",
+    "agents": ["rcode-waleed", "rcode-fatima"],
+    "artifacts_dir": "rcode/artifacts/chains/implement-login-flow-20260405"
+  }
+]
+```
+**Written by:** `/rcode-chain`  
+**Purpose:** History of multi-agent chains, participants, work artifacts.
+
+---
+
+### `last_session`
+**Type:** ISO date string  
+**Example:** `"2026-04-12T15:45:30Z"`  
+**Written by:** Every subcommand that runs (updates at session end)  
+**Purpose:** Enables `/rcode-resume-work` to find context from last session.
+
+---
+
+### `workstreams`
+**Type:** array of objects  
+**Example:**
+```json
+[
+  {
+    "name": "Frontend",
+    "created": "2026-04-01T10:30:00Z",
+    "active": true,
+    "completed": null,
+    "phases": [1, 2, 3]
+  },
+  {
+    "name": "Backend API",
+    "created": "2026-04-02T09:00:00Z",
+    "active": true,
+    "completed": null,
+    "phases": [1, 2, 4]
+  }
+]
+```
+**Written by:** `/rcode-workstream --create`, `/rcode-do --execute`  
+**Purpose:** Tracks parallel workstreams, which phases belong to each.
+
+---
+
+### `active_workstream`
+**Type:** string or null  
+**Example:** `"Frontend"` or `null`  
+**Written by:** `/rcode-workstream --activate`, `/rcode-do`  
+**Purpose:** Currently active workstream; null if no workstream focus.
+
+---
+
+### `model_profile`
+**Type:** string  
+**Example:** `"balanced"` (options: `quality`, `balanced`, `budget`, `inherit`)  
+**Written by:** `/rcode-set-profile`  
+**Purpose:** Model selection for council agents. Affects token spend and quality.
+
+---
+
+## Usage Examples
+
+### Reading Phase Progress
+```python
+current_phase = state['current_phase']
+completed_phases = [p for p in state['phases'] if p['completed'] is not None]
+progress = f"{len(completed_phases)}/{len(state['phases'])} phases complete"
+```
+
+### Checking for Blockers
+```python
+unresolved_blockers = [b for b in state['blockers'] if b['resolved'] is None]
+if unresolved_blockers:
+    print(f"⚠️ {len(unresolved_blockers)} open blockers")
+```
+
+### Resuming Session
+```python
+last_session = state['last_session']
+current_phase = state['current_phase']
+# Provide context: "Last session: {last_session}. Phase: {current_phase}"
+```
+
+### Tracking Decisions
+```python
+phase_decisions = [d for d in state['decisions'] if d['phase'] == current_phase]
+print(f"Decisions made in {current_phase}:")
+for d in phase_decisions:
+    print(f"  - {d['summary']}")
+```
+
+---
+
+## ID Formats Accepted by resolve-id
+
+The `state resolve-id <id>` command accepts the following formats:
+
+| Format | Example | Resolves To | Notes |
+|--------|---------|-------------|-------|
+| `M{N}` | `M1`, `M2` | Milestone N | Lowercase or uppercase M |
+| `{NN}` | `01`, `02`, `10` | Phase with number NN | Zero-padded two-digit phase number |
+| `{NN.S}` | `01.1`, `02.3` | Sprint S in Phase NN | Sprint within a phase |
+| `{NN.S.TT}` | `01.1.01`, `02.3.05` | Story TT in Sprint NN.S | Three-part hierarchical story ID |
+| `{NN.M}` | `02.1`, `03.2` | Decimal phase (legacy) OR sprint | Context-dependent — prefer sprint interpretation |
+
+**Examples:**
+```bash
+node .rcode/bin/rcode-tools.cjs state resolve-id M1          # → Milestone 1
+node .rcode/bin/rcode-tools.cjs state resolve-id 02          # → Phase 02
+node .rcode/bin/rcode-tools.cjs state resolve-id 01.1        # → Sprint 1 in Phase 01
+node .rcode/bin/rcode-tools.cjs state resolve-id 01.1.03     # → Story 3 in Sprint 01.1
+```
+
+**Sprint state commands:**
+```bash
+node .rcode/bin/rcode-tools.cjs state sprint add --phase 01 --goal "Setup" --velocity 13
+node .rcode/bin/rcode-tools.cjs state story add --title "Login" --points 5
+node .rcode/bin/rcode-tools.cjs state story move --id 01.1.01 --status done
+node .rcode/bin/rcode-tools.cjs state sprint velocity
+```