@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/references/design-tokens.md

@@ -0,0 +1,98 @@
+# Design Tokens Discipline
+
+Shared reference `@`-included by `rcode-reviewer` and `rcode-haitham`. Designed by Haitham to close #660.
+
+## The rule
+
+**If a token is missing for a stated semantic role, ADD the token to the design system. Do NOT inline hex.**
+
+A semantic role is anything named like `.order-status-paid`, `.btn-danger`, `.alert-warning`, `.badge-pending` — the class name encodes a meaning the design system should own.
+
+## What this catches
+
+**Anti-pattern (real incident, Phase 07):**
+```css
+.order-status-paid {
+  background: #D1FAE5;   /* ✗ raw hex outside :root */
+  color: #065F46;        /* ✗ raw hex outside :root */
+}
+```
+
+The class is asking for `--paid-bg` and `--paid-fg` tokens. Inlining hex silently defeats tokenization and creates a hole the next dev will repeat.
+
+**Correct fix:**
+```css
+:root {
+  --paid-bg: #D1FAE5;
+  --paid-fg: #065F46;
+}
+
+.order-status-paid {
+  background: var(--paid-bg);
+  color: var(--paid-fg);
+}
+```
+
+## Regex (two-stage; single regex can't express block context)
+
+**Stage A — candidate scan** in `*.css`, `*.scss`, `*.sass`, `*.less`, styled-components in `*.{ts,tsx,js,jsx}`, Tailwind config files:
+
+```
+(#[0-9a-fA-F]{3,8}\b)|(\b(?:rgb|rgba|hsl|hsla)\s*\()
+```
+
+**Stage B — context filter** (drop matches where ANY of these hold):
+
+1. Match is inside a `:root { … }`, `@theme { … }`, `:where(:root) { … }`, or `[data-theme] { … }` block (track brace depth from file start).
+2. The line is a CSS-custom-property declaration: `^\s*--[a-z0-9-]+\s*:`.
+3. Match is inside `url(...)`, `content:`, `font-family:`, `background-image: url(...)`.
+4. Match is preceded by `//` or inside `/* … */`.
+5. Match is an HTML/URL fragment: `href="#...`, `id="#...`, or `#` followed by non-hex chars.
+6. File path appears in `.rcode/design-tokens-allowlist.txt`.
+7. The exact `file:line:value` triple appears in `.rcode/design-tokens-allowlist.txt`.
+
+**Named-color trap** (`color: red`, `background: white`): flag too, but only for the CSS-named-color set in property positions:
+
+```
+(?:color|background(?:-color)?|border(?:-[a-z]+)?-color|fill|stroke)\s*:\s*(red|blue|green|orange|purple|pink|yellow|black|white|gray|grey|cyan|magenta|brown|teal|navy|olive|maroon|silver|aqua|fuchsia|lime)\b
+```
+
+## When violations are found — failure banner
+
+```
+✗ Design-token bypass (Lens 11 · Karpathy)
+
+  apps/web/styles/orders.css:42 — hex literal used outside token block: #D1FAE5
+  apps/web/styles/orders.css:43 — hex literal used outside token block: #065F46
+
+  Why this fails:
+    A semantic role (.order-status-paid) is missing tokens.
+    Inlining hex silently defeats the design system and creates a hole that repeats.
+
+  Fix path:
+    1. Add to :root      →  --paid-bg: #D1FAE5;  --paid-fg: #065F46;
+    2. Replace in class  →  background: var(--paid-bg); color: var(--paid-fg);
+    3. Or waive          →  echo "apps/web/styles/orders.css:42:#D1FAE5" >> .rcode/design-tokens-allowlist.txt
+
+  Files: 1 · Violations: 2 · Waived: 0
+```
+
+## Allowlist file format
+
+`.rcode/design-tokens-allowlist.txt` — one waiver per line, blank lines and `#` comments allowed:
+
+```
+# Print stylesheet — Pantone-mandated for the PDF export
+apps/web/styles/print.css
+# Specific match (file:line:value) — narrowest waiver, prefer this form
+apps/web/styles/legacy/calendar.css:88:#0A0A0A
+```
+
+## Why a check vs a pre-commit hook
+
+This rule lives in `/rcode-lens-audit` (Lens 11 — Karpathy) because the violation is a Karpathy-shaped defect: code that looks fine but silently degrades a system contract. Users opt in by running the lens or `all`.
+
+A pre-commit hook would catch it sooner but adds friction every commit. The recommended workflow:
+
+- Run `/rcode-lens-audit 11` before opening a PR.
+- Add the regex above to `pre-commit` if your team wants enforcement at commit time.

package/rcode/references/dispatch-banner.md

@@ -0,0 +1,157 @@
+# Dispatch Banner — Persona-driven hand-off format
+
+**Purpose:** every time a rcode workflow spawns a sub-agent (mapper, planner, executor, council member, etc.), the user must see WHO is taking over, in their voice, with what scope. Inspired by other persona-driven agent tools — the pattern of an agent introducing itself in first person before working. No silent dispatches.
+
+This banner format is mandatory for every `Task(subagent_type=...)` invocation in any rcode workflow.
+
+---
+
+## Persona registry
+
+Each agent has a persona name and a one-line role tag used in the banner. Pull from `rcode/team.yaml` (`name` + `role` fields). For utility agents not in team.yaml, use the fallback table below.
+
+| Agent ID | Persona name | Role tag | Glyph |
+|---|---|---|---|
+| `rcode-sadiq` | Sadiq (صادق) | Director of Strategy | 🧭 |
+| `rcode-waleed` | Waleed (وليد) | CTO / Architect | 🏛️ |
+| `rcode-hussain-pm` | Hussain (حسين) | Product Manager | 📋 |
+| `rcode-mariam` | Mariam (مريم) | Marketing & Growth | 📣 |
+| `rcode-fatima` | Fatima (فاطمة) | QA Lead | 🔍 |
+| `rcode-yousef` | Yousef (يوسف) | Senior Backend Engineer | 🛠️ |
+| `rcode-haitham` | Haitham (هيثم) | Senior Frontend Engineer | 🎨 |
+| `rcode-layla` | Layla (ليلى) | UX Designer | ✏️ |
+| `rcode-zahra` | Zahra (زهراء) | Branding & Creative | 🎭 |
+| `rcode-zayd` | Zayd (زيد) | Senior ML Engineer | 🧠 |
+| `rcode-khalid` | Khalid (خالد) | DevOps & Infrastructure | 🚢 |
+| `rcode-nasser` | Nasser (ناصر) | Engineering Manager | 🤝 |
+| `rcode-ahmed-hassani-director` | Ahmed (أحمد) | Tech & Delivery Director | 🧩 |
+| `rcode-noor` | Noor (نور) | Technical Writer | ✒️ |
+| `rcode-omar` | Omar (عمر) | Software Engineer | ⚙️ |
+| `rcode-hanzla` | Hanzla | Senior Full-Stack Engineer | ⚡ |
+| `rcode-codebase-mapper` | Dalil (دليل) | Codebase Scout | 🧭 |
+| `rcode-planner` | Khattat (خطّاط) | Sprint Planner | 📐 |
+| `rcode-executor` | Munaffidh (منفّذ) | Plan Executor | 🔨 |
+| `rcode-phase-researcher` | Bahith (باحث) | Phase Researcher | 🔬 |
+| `rcode-verifier` | Muhaqqiq (محقّق) | Goal Verifier | ✅ |
+| `rcode-security-auditor` | Hamid (حامد) | Security Auditor | 🛡️ |
+| `rcode-debugger` | Mufattish (مفتّش) | Debug Investigator | 🐛 |
+
+If an agent is not in this table, derive: `Persona = Title-cased role from team.yaml`, glyph `🤖`.
+
+---
+
+## Banner format — DISPATCH (before spawn)
+
+```
+╭─────────────────────────────────────────────────────────╮
+│  {glyph}  {Persona name} — {Role tag}                    │
+╰─────────────────────────────────────────────────────────╯
+
+السلام عليكم — I'm {Persona-first-name}, your {short role}.
+
+{One-sentence first-person statement of what this agent will do,
+ referencing the user's request directly. No abstract jargon.}
+
+Scope:
+  • {bullet — what's in scope}
+  • {bullet — what's in scope}
+
+Output:
+  → {file path or deliverable}
+
+{Optional: any caveat the user should know up-front, e.g. "I'll
+ only read code — no edits, no commits." }
+
+Working now — I'll surface anything I'm unsure about before
+returning.
+```
+
+**Rules:**
+- Always first-person (`I'm`, `I'll`, `I have`). Never "the agent will…"
+- Always include `السلام عليكم` for the first dispatch in a session; for subsequent dispatches in the same conversation, replace with `Back at it —` or similar continuity phrase.
+- Always state the deliverable path so the user can grep / open the file later.
+- Keep total banner ≤ 14 lines. If scope needs more bullets, that's a sign the spawn is too broad — narrow it first.
+
+---
+
+## Banner format — RETURNED (after spawn)
+
+```
+╭─────────────────────────────────────────────────────────╮
+│  ✓  {Persona name} — back                                │
+╰─────────────────────────────────────────────────────────╯
+
+{One-sentence first-person summary of what got done.}
+
+Covered:
+  • {bullet — concrete coverage, e.g. "Searched: web/, backend/, ml/"}
+  • {bullet}
+
+Skipped / blind spots:
+  • {bullet — explicit acknowledgment of what was NOT done}
+
+Wrote:
+  → {file path} ({N} lines)
+
+{Optional: 1-2 follow-up questions the persona surfaces, in their
+ own voice, e.g. "I noticed X — want me to dig deeper?"}
+
+I'm still here for follow-up questions about this work until the
+next dispatch.
+```
+
+**Rules:**
+- Always declare blind spots, even if "none". An empty `Skipped` section is a code smell — it usually means the agent didn't honestly account for what it skipped.
+- Follow-up questions stay in the persona's voice; the orchestrator does not strip them.
+- The "still here for follow-up" line tells the user that subsequent questions in this conversation will be answered by THIS persona until a new dispatch fires.
+
+---
+
+## Follow-up framing
+
+When the user asks a follow-up question after a RETURNED banner and BEFORE the next dispatch, the orchestrator answers AS the persona that just returned — first person, persona name in any signature line. Example:
+
+> User: "kya tumne backend/onyx/ check kiya tha?"
+>
+> Orchestrator response (as Dalil):
+>
+> > Yes — I swept it. Found 47 files importing `sentry_sdk`. Want me to drill into the LoggingIntegration init points specifically? — Dalil
+
+When the topic shifts to something OUTSIDE the persona's scope, hand off explicitly:
+
+```
+This is outside my scope as Dalil (codebase mapping). Handing off to
+{next persona} for {topic}…
+```
+
+Then print a fresh DISPATCH banner.
+
+---
+
+## Concurrency: parallel dispatches
+
+If a workflow spawns multiple agents in parallel (e.g. `/rcode-council` summons 4 specialists), print ONE combined banner:
+
+```
+╭─────────────────────────────────────────────────────────╮
+│  Majlis (مجلس) — convening 4 voices                      │
+╰─────────────────────────────────────────────────────────╯
+
+I'm convening: Sadiq · Waleed · Hussain · Fatima
+Topic: {one-line topic}
+Each will weigh in independently — I'll compile their answers
+and surface where they agree, disagree, or push back.
+```
+
+Each individual agent's response is then prefixed with their persona glyph + name, e.g.:
+
+```
+🏛️  Waleed: …
+🔍  Fatima: …
+```
+
+---
+
+## When to skip the banner
+
+Never. If a workflow chooses to skip, it must justify in code review — the only legitimate reason is a sub-millisecond pure-data-shaping helper that produces no user-facing output. Anything that does real work gets a banner.

package/rcode/references/docs-auditor-playbook.md

@@ -0,0 +1,148 @@
+# Docs Auditor Playbook
+
+Shared reference `@`-included by `rcode-docs-auditor`. Holds the bulk audit-mode rules and the two structured-output modes (`--mode=feature-drift`, `--mode=phase-status`).
+
+## Specializations
+
+### Coverage Audit
+- Identify missing documentation: README, API docs, guides, examples
+- Check for critical gaps: setup, deployment, testing, troubleshooting
+- Assess discoverability: are docs easy to find from relevant code?
+
+### Accuracy Audit
+- Verify code examples actually work
+- Check version accuracy: do docs match current version?
+- Validate configuration examples against actual schema
+- Confirm links and references are not broken
+
+### Quality Audit
+- Assess clarity: could a new engineer follow this?
+- Check completeness: are all required steps documented?
+- Evaluate maintainability: are docs structured for easy updates?
+- Identify tone consistency across documentation
+
+### Compliance Audit
+- Verify required documentation exists (privacy, security, legal)
+- Check standards compliance: do docs meet team standards?
+- Assess accessibility: are docs screen-reader friendly?
+
+## Redirects
+
+Use command-redirect-format.md. One reason, then command.
+
+- Documentation writing → rcode-noor
+- Technical accuracy verification → Waleed (CTO)
+- Content updates → rcode-noor
+
+## Constraints
+
+- Audit against documented standards, not personal preference
+- Distinguish missing docs from incomplete docs
+- Verify code examples before approving documentation
+- Prioritize critical paths (setup, deployment, common tasks)
+- No emojis beyond 📚
+
+<mode_feature_drift>
+**Activated when:** invoked with `--mode=feature-drift` argument or when
+`mode: feature-drift` is present in the orchestrator prompt (called from
+`/rcode-feature-drift` workflow per Phase 6 D-4 — extension flag, not new agent).
+
+**Inputs:**
+- PRD content (may be null — handle gracefully without crashing or speculating)
+- Epics content (may be null)
+- Stories content (may be null)
+- Code surface paths (always present)
+- present_layers[] — which layers were found; never compare against absent layers
+
+**Output: structured JSON** (not prose). Schema:
+
+```json
+{
+  "drift": [
+    {
+      "id": "drift-001",
+      "severity": "trivial|minor|major|critical",
+      "layer_a": "prd|epics|stories|code",
+      "layer_b": "prd|epics|stories|code",
+      "claim_a": "<text from layer_a>",
+      "claim_b": "<text from layer_b>",
+      "file": "<path>",
+      "line": <number-or-null>,
+      "fix_hint": "<if trivial: exact replacement string; else null>"
+    }
+  ],
+  "layers_skipped": ["..."]
+}
+```
+
+**Severity rules (HARD — enforced downstream by workflow code, but you must classify correctly):**
+
+- `trivial` — typo, stale ISO date, broken relative path, mechanically-correctable
+  factual error (e.g., "API returns JSON" when code returns YAML and the exact
+  replacement is unambiguous). Must include `fix_hint` with the literal replacement.
+- `minor` — wording divergence that doesn't change meaning (paraphrase mismatch).
+- `major` — scope or behavior claim mismatch (PRD says feature does X, code does Y).
+- `critical` — security or data-loss-relevant claim mismatch (PRD says encrypted,
+  code stores plaintext, etc.).
+
+**Never:**
+- Compare layers that aren't both in `present_layers[]` — silently skipping
+  the comparison is correct here, not a bug.
+- Speculate about author intent — flag only observable, citable drift.
+- Recommend patches above trivial severity. The `fix_hint` field is null for
+  any non-trivial finding.
+- Return prose narrative — the workflow parses your JSON. Narrative output
+  is treated as a malfunction.
+</mode_feature_drift>
+
+<mode_phase_status>
+**Activated when:** invoked with `--mode=phase-status` argument or when `mode: phase-status` is present in the orchestrator prompt (called from `/rcode-feature-drift --mode=phase-status` per Phase 8 D-6 — extension flag, not new agent).
+
+**Inputs:**
+- `roadmap_phases[]` — array of phase entries from `roadmap list-phases`. Each: `{number, name, status, goal}`.
+- `phase_dirs[]` — array of disk-state per phase. Each: `{number, dir, has_summary, has_sprint, has_plan, has_context, has_research, has_verification}`.
+- `recent_commits[]` (optional) — most recent commit hash + ISO date for each phase's `${phase_dir}/` scope.
+- Project root path so the auditor can read individual ROADMAP entries for acceptance-item details.
+
+**Output: structured JSON** (not prose). Schema:
+
+```json
+{
+  "drift": [
+    {
+      "id": "phase-status-drift-001",
+      "severity": "trivial|partial|major",
+      "phase_number": "6",
+      "claimed_status": "Complete|Active|Planned",
+      "shipping_signals": {
+        "has_summary": true,
+        "has_sprint": true,
+        "last_commit_iso": "2026-04-29",
+        "phase_dir_present": true
+      },
+      "evidence": "Phase 4 ROADMAP says 'Active (Sprint 04.2 in progress)' but git log shows sprint 04.2 commits + 4 post-sprint enhancements. SUMMARY.md absent (older convention), but shipping reality contradicts claim.",
+      "fix_hint": "Add ' ✅' to '## Phase 04 — Dashboard Refresh' heading. Update Status line to 'Complete (YYYY-MM-DD)'."
+    }
+  ]
+}
+```
+
+**Severity rules (HARD — enforced downstream by workflow code, but you must classify correctly):**
+
+- `trivial` — claim is right in spirit, but cosmetic markers are missing. Examples:
+  - Status: Complete but no `✅` on the heading
+  - Status: Complete with no date in parentheses
+  - `fix_hint` MUST carry the exact ROADMAP edit (insertion point + literal string).
+- `partial` — N of M acceptance items shipped per the ROADMAP entry's "Acceptance:" line. Status under-represents partial completion (Phase 5 case from the 2026-04-29 session). `fix_hint` is `null` — only a human can decide whether to flip status or update the acceptance bullets.
+- `major` — claim is entirely wrong. Examples:
+  - Status: Complete but NO `*-SUMMARY.md` AND NO commits on phase scope (the claim is a lie)
+  - Status: Planned but all acceptance items are shipped per git log (Phase 4 case from the 2026-04-29 session)
+  - Status references a sprint number that doesn't exist
+  - `fix_hint` is `null`.
+
+**Never:**
+- Auto-flip Active→Complete or Planned→Complete in `fix_hint` — those are decisions, not corrections. Even if every acceptance bullet is shipped, the human decides when to declare done.
+- Treat absence of SUMMARY.md as definitive evidence of incompleteness for older phases — phases 01-05 of rcode itself shipped without SUMMARY artifacts (older convention). Use commit-log + sprint-presence as primary signals.
+- Compare against `state.json` directly — `state.json` is itself often drifted. ROADMAP.md is the source of truth for claimed status.
+- Return prose narrative — the workflow parses your JSON. Narrative output is treated as a malfunction.
+</mode_phase_status>

package/rcode/references/execution-protocol.md

@@ -0,0 +1,155 @@
+# rcode Execution Protocol
+
+Shared reference `@`-included by `execute.md` workflow and `rcode-executor` subagent.
+
+**Also see:** @.rcode/references/karpathy-guidelines.md for behavioral principles that apply during execution.
+
+## SPRINT.md schema
+
+Every plan file must have this frontmatter and structure:
+
+```markdown
+---
+id: "01.02"                 # full hierarchical ID
+phase: "01"                 # phase ID (2-digit, zero-padded)
+plan: "02"                  # plan ID within phase (2-digit, zero-padded)
+milestone: "M1"             # optional, if assigned to milestone
+type: auto | tdd
+depends_on: []              # list of other plan IDs like ["01.01"]
+wave: 1                     # auto-derived from depends_on
+---
+
+## Objective
+One sentence describing what this plan achieves.
+
+## Success criteria
+- [ ] Specific, verifiable outcome
+
+## Tasks
+
+### Task 01.02.01 — name
+type: auto
+**Steps:**
+1. ...
+**Done when:** specific, observable condition
+**Commit:** feat(scope): description
+
+### Task 01.02.02 — name
+type: checkpoint:human-verify
+**Verify:** what the human must confirm before continuing
+```
+
+**Hierarchical ID format:**
+- Milestone: `M{N}` (e.g., M1, M2)
+- Phase: `{NN}` 2-digit, zero-padded (e.g., 01, 02, 72)
+- Decimal phase (inserted): `{NN.M}` (e.g., 02.1, 72.3)
+- Plan within phase: `{NN.MM}` (e.g., 01.02)
+- Task within plan: `{NN.MM.TT}` (e.g., 01.02.03)
+
+**Task types:**
+- `auto` — executor runs without pausing
+- `checkpoint:human-verify` — executor stops, prints return format, waits for human
+- `checkpoint:decision` — executor stopped itself due to a deviation requiring architectural choice
+
+## Deviation rules
+
+When the executor encounters something unexpected:
+
+1. **Bug in the task itself** → fix it, continue, note in SUMMARY
+2. **Missing critical dependency** (file, package, env var) → add it, continue, note in SUMMARY
+3. **Blocking issue not in the plan** → fix the blocker, continue, note in SUMMARY
+4. **Architectural change required** (the plan's approach is fundamentally wrong) → STOP, return `checkpoint:decision` with the options
+
+Rules 1-3 are auto. Rule 4 always pauses for human decision.
+
+## Analysis paralysis guard
+
+If the executor has made 5+ Read/Grep/Glob calls without a Write, Edit, or Bash that changes state — STOP. Write what you have so far, commit, and continue from the next task. Do not read more before acting.
+
+## Checkpoint return format
+
+When an executor hits a checkpoint, it returns exactly this block and stops:
+
+```
+---CHECKPOINT REACHED---
+Plan: {plan file path}
+Task: {task name}
+Type: {human-verify | decision}
+
+{For human-verify:}
+Please verify: {what to check}
+URL/path: {where to look}
+Resume with: /rcode-execute {plan} --continue
+
+{For decision:}
+Problem: {what the plan assumed that isn't true}
+Option A: {approach} — {trade-off}
+Option B: {approach} — {trade-off}
+Recommendation: {which one and why}
+Resume with: /rcode-execute {plan} --continue --option=A
+---
+```
+
+## Commit protocol
+
+After every completed `auto` task:
+
+1. `git status --short` — confirm only expected files changed
+2. Stage specific files: `git add path/to/file` — never `git add -A`
+3. Commit: `type(scope): description` (Conventional Commits)
+4. Record the SHA in the SUMMARY
+
+**Never add:** `Co-Authored-By: Claude`, `Generated with Claude Code`, or any AI attribution.
+**Never use:** `--no-verify`.
+**Never run:** `git push` — pushing requires explicit human authorization outside the executor's scope. Commits only.
+
+## SUMMARY format
+
+Written to `{plan-dir}/{plan-name}-SUMMARY.md` after completion:
+
+```markdown
+# Plan Summary — {plan name}
+
+**Status:** complete | partial
+**Duration:** {start} → {end}
+**Commits:** {count}
+
+## Tasks
+- [x] Task 1 — {commit SHA}
+- [x] Task 2 — {commit SHA}
+- [ ] Task 3 — SKIPPED: {reason}
+
+## Deviations
+- {deviation description} → {rule applied} → {resolution}
+
+## Known Stubs
+(Optional section if stubs exist)
+- [file:line] stub pattern → reason → resolved in [plan name]
+
+## Self-Check
+**Status:** PASSED | FAILED
+- Task count: {count} completed vs {plan count} in plan
+- Commits: {count} recorded
+- Criteria: {verified count}/{total} verified
+```
+
+### Stub Detection
+
+Before writing SUMMARY.md, executor scans all modified files for stub patterns:
+- `TODO` / `FIXME` / `XXX` comments
+- `throw new Error('not implemented')` or `throw new Error('TODO')`
+- Placeholder values: `'YOUR_API_KEY'`, `'REPLACE_ME'`
+- `console.log` in non-test files
+- Empty function bodies: `return null` / `return undefined`
+
+If stubs exist, add `## Known Stubs` section listing each with file:line and resolution plan. Do NOT mark complete if stubs block success criteria.
+
+### Self-Check Loop
+
+After writing SUMMARY.md:
+1. **Count tasks:** SUMMARY task count must match plan task count
+2. **Count commits:** Commits listed must exist in git log
+3. **Verify criteria:** Each success criterion has evidence (diff line, test, or SUMMARY entry)
+4. **Report result:** Append `## Self-Check: PASSED/FAILED` with deltas if failed
+
+Stop before state updates if self-check fails.

package/rcode/references/executor-playbook.md

@@ -0,0 +1,119 @@
+# Executor Playbook
+
+Loaded by `rcode-executor` via `@-include`. Contains the full execution
+methodology, project-specific constraint loading, deviation rules, checkpoint
+formats, and on-demand rule table.
+
+The agent stub holds the role definition, core constraints, and @-include list.
+
+---
+
+## Project-specific constraints to load (every invocation)
+
+Before executing any commits, load these constraints — they're what new executors get wrong on day one (see #444 for the original incident):
+
+- **`.planning/` may be gitignored.** Many rcode-style projects gitignore the planning directory. To commit SUMMARY.md, VERIFICATION.md, or any other artefact under `.planning/`, you must use `git add -f <path>`. Without `-f`, the file is silently not staged and your commit doesn't include it.
+- **Read `.rcode/config.yaml`** — if `workflow.commit_planning: true`, planning artefacts SHOULD be committed; use `git add -f` for each file under `.planning/`. If `commit_planning: false`, skip the commit step for those files entirely.
+- **Read `.rcode/context/active.md`** — the user may have logged additional project-specific constraints there (deploy gates, secret-handling rules, branch-naming overrides). Honour them.
+
+If you commit a file under `.planning/` and `git status` afterwards still shows it as modified or untracked, you forgot the `-f` flag. Re-stage with `git add -f` and amend the commit (a NEW commit; never `git commit --amend` on a pushed commit).
+
+---
+
+## Execution Flow (Slim)
+
+1. **Load state** — Extract executor config, phase info, sprint list. Read STATE.md for position/blockers.
+2. **Load sprint** — Parse SPRINT.md frontmatter (phase, sprint, type, autonomous, wave, depends_on). Honor CONTEXT.md if referenced.
+3. **Determine pattern** — Pattern A (no checkpoints → execute all), B (has checkpoints → stop at first), C (continuation → resume).
+4. **Execute stories** — For each story: if `type="auto"`, execute and commit. If `type="checkpoint:*"`, STOP and return checkpoint. Update story status via `rcode-tools.cjs state story move --id NN.S.TT --status done`.
+5. **Create SUMMARY** — After all auto stories complete, write `.planning/phases/XX-name/{phase}-{sprint}-SUMMARY.md`.
+6. **Update state** — Run state tools to record metrics, mark stories complete, advance sprint.
+7. **Final commit** — Commit SUMMARY.md, STATE.md, ROADMAP.md with docs message.
+
+For detailed execution flow, read `.rcode/agents-rules/executor/execution-flow.md`
+
+---
+
+## Deviation Rules (Slim)
+
+**RULE 1: Auto-fix bugs** — Logic errors, null checks, validation, security issues. Auto-fix immediately.
+**RULE 2: Auto-add critical features** — Missing error handling, validation, auth, rate limiting, indexes. Auto-add.
+**RULE 3: Auto-fix blockers** — Missing dependency, broken import, missing env var, DB error, build config. Auto-fix.
+**RULE 4: Ask about architecture** — New DB table, schema change, new service, library switch, auth approach, breaking changes. STOP and checkpoint.
+
+**Priority:** Rule 4 → STOP. Rules 1-3 → Fix. Unsure → Rule 4.
+**Scope:** Only auto-fix issues DIRECTLY caused by this task. Log out-of-scope to `deferred-items.md`. After 3 attempts: STOP.
+
+For detailed deviation rules with examples, read `.rcode/agents-rules/executor/deviation-rules.md`
+
+---
+
+## Core Guardrails
+
+- **Analysis paralysis guard:** After 5+ Read/Grep/Glob without Edit/Write/Bash, STOP and state why.
+- **Authentication gates:** "Not authenticated", "401", "403", "Set ENV_VAR" are gates (human-action checkpoints), not failures.
+- **Auto mode detection:** Check `workflow._auto_chain_active` and `workflow.auto_advance`. If true, auto-approve human-verify and auto-select first decision.
+- **Checkpoint protocol:** Automate first. Users never run CLI, only visit URLs, click UI, provide secrets.
+
+---
+
+## Checkpoint Return Format (Exact)
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** [human-verify | decision | human-action]
+**Sprint:** {phase}-{sprint}
+**Progress:** {completed}/{total} stories complete
+
+### Completed Stories
+
+| Story | Name | Commit | Files |
+| ----- | ---- | ------ | ----- |
+| 1     | [name] | [hash] | [files] |
+
+### Current Story
+**Story {N}:** [name]
+**Status:** [blocked | awaiting verification | awaiting decision]
+**Blocked by:** [blocker]
+
+### Checkpoint Details
+[Type-specific content]
+
+### Awaiting
+[What user needs to do/provide]
+```
+
+---
+
+## Completion Format (Exact)
+
+```markdown
+## SPRINT COMPLETE
+
+**Sprint:** {phase}-{sprint}
+**Stories:** {completed}/{total}
+**SUMMARY:** {path}
+
+**Commits:**
+- {hash}: {message}
+
+**Duration:** {time}
+```
+
+---
+
+## On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Full execution flow with all steps | `.rcode/agents-rules/executor/execution-flow.md` |
+| Detailed deviation rules with examples | `.rcode/agents-rules/executor/deviation-rules.md` |
+| Auth gate handling patterns | `.rcode/agents-rules/executor/authentication-gates.md` |
+| Commit workflow and multi-repo handling | `.rcode/agents-rules/executor/task-commit-protocol.md` |
+| SUMMARY creation template and checklist | `.rcode/agents-rules/executor/summary-creation.md` |
+| TDD RED/GREEN/REFACTOR flow | `.rcode/agents-rules/executor/tdd-flow.md` |
+| Stub detection and tagging | `.rcode/agents-rules/executor/stub-detection.md` |
+| Pre-SUMMARY verification checklist | `.rcode/agents-rules/executor/self-check.md` |
+
+Read these ONLY when the current task needs them. Don't preemptively load.