@hanzlaa/rcode 4.7.2 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.7.2",
+  "version": "4.8.0",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/agents/rcode-haitham.md

@@ -12,7 +12,7 @@ description: |
   typography / colour system (use Zahra), architecture decisions (use Waleed),
   backend / API (use Yousef), test strategy (use Fatima), strategic priority
   (use Sadiq).
-tools: Read, Grep, Glob, Bash, WebFetch
+tools: Read, Grep, Glob, Bash, WebFetch, Write, Edit
 color: cyan
 ---
 

package/rcode/agents/rcode-hanzla.md

@@ -8,7 +8,7 @@ description: |
   Do NOT use for: architecture (Waleed), backend perf / queues (Yousef),
   frontend / RTL / a11y (Haitham), UX flows (Layla), test strategy (Fatima),
   deployment / CI (Khalid), scope (Hussain-PM).
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, Write, Edit
 color: green
 ---
 

package/rcode/agents/rcode-hussain-pm.md

@@ -9,7 +9,7 @@ description: |
   Do NOT use for: technical feasibility (Waleed), implementation (Hanzla /
   Yousef / Haitham), market positioning (Mariam), strategic go/no-go and
   kill criteria (Sadiq), QA test strategy (Fatima), sprint scrum ops (Hussain-SM).
-tools: Read, Grep, Glob, WebFetch
+tools: Read, Grep, Glob, WebFetch, Write, Edit
 color: orange
 ---
 

package/rcode/agents/rcode-nyquist-auditor.md

@@ -1,7 +1,7 @@
 ---
 name: rcode-nyquist-auditor
 description: Fills Nyquist validation gaps by generating tests and verifying coverage for phase requirements
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, Write, Edit
 color: purple
 ---
 

package/rcode/agents/rcode-omar.md

@@ -10,7 +10,7 @@ description: |
   deep frontend (use Haitham), deep backend perf (use Yousef), test strategy
   (use Fatima), scope / PRD (use Hussain-PM), strategic priority (use Sadiq),
   ML / RAG / embeddings (use Zayd), DevOps / deployment (use Khalid).
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, Write, Edit
 color: green
 ---
 

package/rcode/agents/rcode-remediation-planner.md

@@ -1,7 +1,7 @@
 ---
 name: rcode-remediation-planner
 description: Remediation Planner — spawned to plan remediation for issues, blockers, and failures. Creates action plans to recover from deviations, resolve blockers, and get back on track.
-tools: Read, Grep, Glob, Bash, Edit
+tools: Read, Grep, Glob, Bash
 color: orange
 ---
 

package/rcode/agents/rcode-waleed.md

@@ -10,7 +10,7 @@ description: |
   Do NOT use for: strategy / "should we build" (Sadiq), backend impl (Yousef),
   scope / PRD (Hussain-PM), test strategy (Fatima), market / GTM (Mariam),
   org-level multi-team coordination (Ahmed-Hassani-Director).
-tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, Write, Edit
 color: green
 ---
 

package/rcode/agents/rcode-yousef.md

@@ -11,7 +11,7 @@ description: |
   (use Haitham), test methodology (use Fatima), strategic priority (use Sadiq),
   scope / PRD (use Hussain-PM), implementation across the full stack
   (use Hanzla / Omar), deployment / CI (use Khalid).
-tools: Read, Grep, Glob, Bash, WebFetch
+tools: Read, Grep, Glob, Bash, WebFetch, Write, Edit
 color: blue
 ---
 

package/rcode/agents/rules/planner/task-templates.md

@@ -1,10 +1,12 @@
 # rcode Planner: Task Templates by Type
 
+<!-- id= and <title> are REQUIRED across every template below — this is what server/lib/scanner.js's buildPhaseTree actually parses. Do not use a `name` child tag or a bare title attribute; both are legacy/unsupported paths. -->
+
 ## Standard Task Template
 
 ```xml
-<task type="auto">
-  <name>Task: [Action-oriented name]</name>
+<task id="{sprint-id}.{NN}" type="auto">
+  <title>Task: [Action-oriented name]</title>
   <files>path/to/file.ext, path/to/another.ts</files>
   <action>[Specific implementation with what to avoid and WHY]</action>
   <verify>
@@ -21,8 +23,8 @@
 Use when you can write `expect(fn(input)).toBe(output)` before implementing.
 
 ```xml
-<task type="auto" tdd="true">
-  <name>Task: [name]</name>
+<task id="{sprint-id}.{NN}" type="auto" tdd="true">
+  <title>Task: [name]</title>
   <files>src/feature.ts, src/feature.test.ts</files>
   <behavior>
     - Test 1: [expected behavior]
@@ -44,8 +46,8 @@ Use when you can write `expect(fn(input)).toBe(output)` before implementing.
 Use for visual/functional verification (90% of checkpoints).
 
 ```xml
-<task type="checkpoint:human-verify" gate="blocking">
-  <name>Verify: [Feature name works]</name>
+<task id="{sprint-id}.{NN}" type="checkpoint:human-verify" gate="blocking">
+  <title>Verify: [Feature name works]</title>
   <what-built>[What the agent automated]</what-built>
   <how-to-verify>
     1. Navigate to http://localhost:3000/login
@@ -65,8 +67,8 @@ Use for visual/functional verification (90% of checkpoints).
 Use for implementation choices (9% of checkpoints).
 
 ```xml
-<task type="checkpoint:decision" gate="blocking">
-  <name>Decide: Database schema for messages</name>
+<task id="{sprint-id}.{NN}" type="checkpoint:decision" gate="blocking">
+  <title>Decide: Database schema for messages</title>
   <what-youre-deciding>
     Where to store user-to-message relationships:
     
@@ -94,8 +96,8 @@ Use for implementation choices (9% of checkpoints).
 Use for unavoidable manual steps (1% of checkpoints).
 
 ```xml
-<task type="checkpoint:human-action" gate="blocking">
-  <name>Set up Stripe API key</name>
+<task id="{sprint-id}.{NN}" type="checkpoint:human-action" gate="blocking">
+  <title>Set up Stripe API key</title>
   <what-needed>
     The next task implements Stripe payment processing, which requires your API key.
   </what-needed>
@@ -115,8 +117,8 @@ Use for unavoidable manual steps (1% of checkpoints).
 ## Database Migration Task Template
 
 ```xml
-<task type="auto">
-  <name>Task: Add role field to users table</name>
+<task id="{sprint-id}.{NN}" type="auto">
+  <title>Task: Add role field to users table</title>
   <files>prisma/schema.prisma, prisma/migrations/[timestamp]_add_role.sql</files>
   <action>
     1. Update User model in schema: add `role String @default("user")`
@@ -136,8 +138,8 @@ Use for unavoidable manual steps (1% of checkpoints).
 ## API Endpoint Task Template
 
 ```xml
-<task type="auto">
-  <name>Task: Implement POST /api/users endpoint</name>
+<task id="{sprint-id}.{NN}" type="auto">
+  <title>Task: Implement POST /api/users endpoint</title>
   <files>src/app/api/users/route.ts, src/types/user.ts</files>
   <action>
     Create POST endpoint accepting { email, password, name }:
@@ -167,8 +169,8 @@ Use for unavoidable manual steps (1% of checkpoints).
 ## UI Component Task Template
 
 ```xml
-<task type="auto">
-  <name>Task: Create LoginForm component</name>
+<task id="{sprint-id}.{NN}" type="auto">
+  <title>Task: Create LoginForm component</title>
   <files>src/components/LoginForm.tsx, src/components/LoginForm.test.tsx</files>
   <action>
     Create form component with:
@@ -195,8 +197,8 @@ Use for unavoidable manual steps (1% of checkpoints).
 ## Configuration Task Template
 
 ```xml
-<task type="auto">
-  <name>Task: Configure environment variables</name>
+<task id="{sprint-id}.{NN}" type="auto">
+  <title>Task: Configure environment variables</title>
   <files>.env.example, .env.local (local only)</files>
   <action>
     1. Create .env.example with template (no real values):
@@ -219,8 +221,8 @@ Use for unavoidable manual steps (1% of checkpoints).
 ## Documentation Task Template
 
 ```xml
-<task type="auto">
-  <name>Task: Document authentication flow</name>
+<task id="{sprint-id}.{NN}" type="auto">
+  <title>Task: Document authentication flow</title>
   <files>docs/AUTHENTICATION.md</files>
   <action>
     Document in docs/AUTHENTICATION.md:
@@ -242,8 +244,8 @@ Use for unavoidable manual steps (1% of checkpoints).
 ## Refactoring Task Template
 
 ```xml
-<task type="auto">
-  <name>Task: Extract auth validation to utility</name>
+<task id="{sprint-id}.{NN}" type="auto">
+  <title>Task: Extract auth validation to utility</title>
   <files>src/lib/auth-validation.ts, src/api/auth/login/route.ts</files>
   <action>
     1. Create src/lib/auth-validation.ts with functions:

package/rcode/agents/rules/verifier/verification-report.md

@@ -4,7 +4,7 @@
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
-Create `.rcode/phases/{phase_dir}/{phase_num}-VERIFICATION.md`:
+Create `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`:
 
 ```markdown
 ---
@@ -108,7 +108,7 @@ Return with:
 
 **Status:** {passed | gaps_found | human_needed}
 **Score:** {N}/{M} must-haves verified
-**Report:** .rcode/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+**Report:** .planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
 
 {If passed:}
 All must-haves verified. Phase goal achieved. Ready to proceed.

package/rcode/bin/lib/roadmap.cjs

@@ -326,7 +326,12 @@ function cmdUpdatePlanProgress(projectRoot, phaseNum, planId, status) {
   if (!phaseNum) {
     throw new Error('Usage: roadmap update-plan-progress <phase> [<plan-id> <status>]');
   }
-  // 1-arg form: auto-detect progress from disk
+  // 1-arg form: auto-detect progress from disk and persist it into the
+  // phase's **Status:**/**Plans:** prose block in ROADMAP.md.
+  // Fix #1013: this branch used to only *compute* status from disk and
+  // return it — it never read/wrote ROADMAP.md at all, so it always
+  // reported `updated: false` even when the computed status genuinely
+  // differed from the stale prose already in the file.
   if (!planId && !status) {
     const planningDir = path.join(projectRoot, '.planning', 'phases');
     let phaseDir = null;
@@ -344,12 +349,83 @@ function cmdUpdatePlanProgress(projectRoot, phaseNum, planId, status) {
     const planFiles = files.filter(f => /(?:^|-)(SPRINT|PLAN)\.md$/i.test(f));
     const summaryFiles = files.filter(f => /(?:^|-)SUMMARY\.md$/i.test(f));
     const allDone = planFiles.length > 0 && summaryFiles.length >= planFiles.length;
+    const computedStatus = allDone ? 'complete' : 'in_progress';
+    const note = `phase ${phaseNum}: ${planFiles.length} plan(s), ${summaryFiles.length} summary(s) — ${allDone ? 'complete' : 'in progress'}`;
+
+    const { path: rp } = resolveRoadmapPath(projectRoot);
+    if (!fs.existsSync(rp)) {
+      return { updated: false, note, plan_count: planFiles.length, summary_count: summaryFiles.length, status: computedStatus, error: 'ROADMAP.md not found' };
+    }
+    const content = fs.readFileSync(rp, 'utf8');
+    const phases = extractPhases(content);
+    const phase = phases.find((p) => normalizePhaseNum(p.number) === normalizePhaseNum(phaseNum));
+    if (!phase) {
+      return { updated: false, note, plan_count: planFiles.length, summary_count: summaryFiles.length, status: computedStatus, error: `phase ${phaseNum} not found in ROADMAP.md` };
+    }
+
+    const planIdRe = /^(\d+[A-Z]?(?:\.\d+)?-\d+)-(?:SPRINT|PLAN)\.md$/i;
+    const summaryIdRe = /^(\d+[A-Z]?(?:\.\d+)?-\d+)-SUMMARY\.md$/i;
+    const summarizedIds = new Set(
+      summaryFiles.map((f) => { const m = f.match(summaryIdRe); return m ? m[1] : null; }).filter(Boolean)
+    );
+    const planIds = [...new Set(
+      planFiles.map((f) => { const m = f.match(planIdRe); return m ? m[1] : null; }).filter(Boolean)
+    )].sort();
+
+    const section = content.slice(phase.headerIndex, phase.sectionEnd);
+    let newSection = section;
+    let changed = false;
+
+    // Update **Status:** — only when the computed status actually differs
+    // from what the prose says, so re-running this after completion is a
+    // no-op instead of rewriting the completion date every time.
+    const statusLineRe = /(\*\*Status(?::\*\*|\*\*:)\s*)([^\n]+)/i;
+    const statusMatch = section.match(statusLineRe);
+    if (statusMatch) {
+      const currentStatusNorm = statusMatch[2].trim().toLowerCase();
+      if (computedStatus === 'complete' && !currentStatusNorm.startsWith('complete')) {
+        const today = new Date().toISOString().slice(0, 10);
+        newSection = newSection.replace(statusLineRe, `$1Complete (${today})`);
+        changed = true;
+      } else if (computedStatus === 'in_progress' && currentStatusNorm.startsWith('planned')) {
+        newSection = newSection.replace(statusLineRe, `$1In Progress`);
+        changed = true;
+      }
+    }
+
+    // Replace a placeholder **Plans:** list (`- _TBD_` or empty) with the
+    // plan IDs actually found on disk. Leave already-populated lists alone.
+    if (planIds.length > 0) {
+      const plansBlockRe = /(\*\*Plans(?::\*\*|\*\*:)\s*\n)((?:\s*-\s*[^\n]+\n?)+)/i;
+      const plansMatch = newSection.match(plansBlockRe);
+      if (plansMatch) {
+        const isPlaceholder = /^\s*-\s*_TBD_\s*$/im.test(plansMatch[2]) || plansMatch[2].trim() === '';
+        if (isPlaceholder) {
+          const plansList = planIds
+            .map((id) => `- ${id} — ${summarizedIds.has(id) ? 'SUMMARY shipped' : 'in progress'}`)
+            .join('\n') + '\n';
+          newSection = newSection.replace(plansBlockRe, `$1${plansList}`);
+          changed = true;
+        }
+      }
+    }
+
+    if (!changed) {
+      return { updated: false, note: `${note} (ROADMAP.md already reflects this)`, plan_count: planFiles.length, summary_count: summaryFiles.length, status: computedStatus };
+    }
+
+    const newContent = content.slice(0, phase.headerIndex) + newSection + content.slice(phase.sectionEnd);
+    const tmp = rp + '.tmp';
+    fs.writeFileSync(tmp, newContent, 'utf8');
+    fs.renameSync(tmp, rp);
+
     return {
-      updated: false,
-      note: `phase ${phaseNum}: ${planFiles.length} plan(s), ${summaryFiles.length} summary(s) — ${allDone ? 'complete' : 'in progress'}`,
+      updated: true,
+      phase: phaseNum,
+      status: computedStatus,
       plan_count: planFiles.length,
       summary_count: summaryFiles.length,
-      status: allDone ? 'complete' : 'in_progress',
+      note: `ROADMAP.md phase ${phaseNum} block updated to ${computedStatus}`,
     };
   }
 

package/rcode/bin/rcode-tools.cjs

@@ -381,6 +381,7 @@ function cmdInit(workflowName, rawArgs) {
 
   let panel = [];
   let scores = {};
+  let domain = null;
 
   let agent_id = null;
 
@@ -395,8 +396,12 @@ function cmdInit(workflowName, rawArgs) {
     // Don't pad when user explicitly specified the agent list — their
     // choice is the final word.
     panel = filterPanelToInstalled(ideal, councilAgents, { pad: flags.agents.length === 0 });
+    // #1010 — domain must populate on every council session, not just
+    // --explain, because council.md's <output_format> banner prints
+    // Domain: unconditionally.
+    const explained = scorer.explainSelection(question, opts);
+    domain = explained.domain || null;
     if (flags.explain) {
-      const explained = scorer.explainSelection(question, opts);
       scores = explained.scores || {};
     }
   }
@@ -426,9 +431,14 @@ function cmdInit(workflowName, rawArgs) {
     flags,
     panel,
     scores,
+    domain,
     question_type: questionClassification.type,
     question_signals: questionClassification.signals,
     mode: config.mode || null,
+    // #1010 — response_language was only ever populated for phase-op/
+    // sprint-plan below; council.md documents it as a top-level init field
+    // and gates language pass-through to subagents on it being set.
+    response_language: config.response_language || config.language || null,
     config,
     installed_agents: installedAgents,
     paths: {
@@ -1519,6 +1529,10 @@ function cmdState(subArgs) {
   // =====================================================================
 
   // --- sprint add --phase NN --goal "Sprint goal" ---
+  // NOTE: this populates entry.sprints[] (an array). A separate code path,
+  // 'planned-phase' below (~line 3152), populates entry.plans (a plain count).
+  // These two fields are never reconciled with each other — see AUDIT-redundant-work.md
+  // finding 1 cross-check. Do not assume one implies the other is populated.
   if (sub === 'sprint' && subArgs[1] === 'add') {
     const flags = parseFlags(2);
     const state = readState() || defaultState();
@@ -3149,6 +3163,9 @@ function cmdState(subArgs) {
   // Execution-lifecycle phase state
   // =====================================================================
 
+  // NOTE: entry.plans (a count) is disjoint from entry.sprints[] (an array,
+  // set by 'sprint add' above) — see the comment there. Known schema divergence,
+  // not yet unified; do not read one as evidence the other is in sync.
   if (sub === 'planned-phase') {
     const flags = parseFlags(1);
     if (!flags.phase) throw new Error('planned-phase requires --phase <N>');

package/rcode/brain/best-practices/state-sync-rule.md

@@ -8,7 +8,7 @@ Immediately after appending content to any of:
 
 - `.planning/ROADMAP.md` — milestones and phases
 - `.planning/epics.md` — epics and stories
-- `.rcode/phases/{phase}/sprint-{N}.md` — sprint commitments
+- `.planning/phases/{phase-dir}/{phase}-{plan}-SPRINT.md` — sprint commitments
 
 Call the state-sync helper:
 

package/rcode/references/council-protocol.md

@@ -32,7 +32,7 @@ Agreements without new information are silence. If an agent genuinely has nothin
 
 ## Panel selection (deterministic scoring)
 
-rcode's council uses a pure-function keyword scorer (`cli/lib/council-panel.cjs`) instead of LLM judgment. This is intentional:
+rcode's council uses a pure-function keyword scorer (`rcode/bin/lib/council-panel.cjs` source, installed at `.rcode/bin/lib/council-panel.cjs`) instead of LLM judgment. This is intentional:
 
 - **Deterministic:** same question produces same panel every time
 - **Testable:** the scoring function has unit tests
@@ -47,13 +47,18 @@ The scoring table is versioned with the package. Users who want different weight
 - Scope/feature questions (containing "scope", "feature", "roadmap", "prd") always include Hussain-PM.
 - If fewer than the minimum panel size (default 3) score non-zero, the panel is padded with the STRATEGIC_PADDING_ORDER list: sadiq, hussain-pm, waleed, fatima, nasser.
 
-**v2 prototype note:** only Sadiq, Waleed, and Fatima are installed as first-class subagents. The scorer may select agent ids that don't yet have subagent files — the orchestrator must filter to installed agents and fall back to the 3-agent panel.
+**Installed roster:** the full agent roster (currently 45 agents under `rcode/agents/`) is installed as first-class subagents. The scorer may still select an agent id that isn't present in a given project's installed set — the orchestrator filters the scored panel down to `installed_agents` from `init council` and pads from the fallback order if needed.
 
 ## Response presentation
 
-Subagent responses are presented **verbatim and in panel order**. The orchestrator never summarizes, paraphrases, or condenses agent output. The user came to the council to hear the agents speak in their own voices — summary defeats the point.
+Two presentation modes control how panel responses appear inline. The session artifact (see below) always stores the full verbatim text regardless of mode — only the inline presentation differs:
 
-After all verbatim responses, the orchestrator may add a single **Orchestrator Note** (max 3 sentences) that flags a disagreement worth following up on or recommends a second round. The Orchestrator Note is clearly labeled so it's not confused with agent speech.
+- **Default (compact summary)** — scannable in ~20 seconds: a one-sentence paraphrased position per agent, a convergence/divergence table, and Round 2 deltas. No verbatim transcripts inline.
+- **Verbose** (`--verbose` flag or `output.verbose: true` in config) — full verbatim responses printed in panel order, no summarization.
+
+The user came to the council to hear the agents' actual positions, not filler agreement — so even in compact mode, paraphrase the substance, not "I agree with X."
+
+After the panel output, the orchestrator may add a single **Orchestrator Note** (max 2-3 sentences) that flags a disagreement worth following up on or recommends a second round. The Orchestrator Note is clearly labeled so it's not confused with agent speech.
 
 ## Session artifact format
 

package/rcode/references/execute-auto-copy-learnings.md

@@ -0,0 +1,15 @@
+# execute.md — auto_copy_learnings (global learnings store)
+
+Extracted from `execute.md`'s `auto_copy_learnings` step. Only loaded when `features.global_learnings` is enabled (disabled by default) — see the conditional include at that point in `execute.md`.
+
+**Auto-copy phase learnings to global store (when enabled).**
+
+This step runs AFTER phase completion and SUMMARY.md is written. It copies any LEARNINGS.md
+entries from the completed phase to the global learnings store at `.rcode/knowledge/`.
+
+1. Check if LEARNINGS.md exists in the phase directory (use the `phase_dir` value from init context)
+2. If found, copy to global store:
+```bash
+node ".rcode/bin/rcode-tools.cjs" learnings copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"
+```
+Copy failure must NOT block phase completion.

package/rcode/references/execute-close-parent-artifacts.md

@@ -0,0 +1,49 @@
+# execute.md — close_parent_artifacts (decimal/polish phases only)
+
+Extracted from `execute.md`'s `close_parent_artifacts` step. Only loaded when `PHASE_NUMBER` contains a decimal (gap-closure phases like `4.1`, `03.1`) — see the conditional include at that point in `execute.md`.
+
+For decimal/polish phases only (X.Y pattern): close the feedback loop by resolving parent UAT and debug artifacts.
+
+**1. Detect decimal phase and derive parent:**
+```bash
+# Check if phase_number contains a decimal
+if [[ "$PHASE_NUMBER" == *.* ]]; then
+  PARENT_PHASE="${PHASE_NUMBER%%.*}"
+fi
+```
+
+**2. Find parent UAT file:**
+```bash
+PARENT_INFO=$(node ".rcode/bin/rcode-tools.cjs" find-phase "${PARENT_PHASE}" --raw)
+# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
+```
+
+**If no parent UAT found:** Skip this step (gap-closure may have been triggered by VERIFICATION.md instead).
+
+**3. Update UAT gap statuses:**
+
+Read the parent UAT file's `## Gaps` section. For each gap entry with `status: failed`:
+- Update to `status: resolved`
+
+**4. Update UAT frontmatter:**
+
+If all gaps now have `status: resolved`:
+- Update frontmatter `status: diagnosed` → `status: resolved`
+- Update frontmatter `updated:` timestamp
+
+**5. Resolve referenced debug sessions:**
+
+For each gap that has a `debug_session:` field:
+- Read the debug session file
+- Update frontmatter `status:` → `resolved`
+- Update frontmatter `updated:` timestamp
+- Move to resolved directory:
+```bash
+mkdir -p .planning/debug/resolved
+mv .planning/debug/{slug}.md .planning/debug/resolved/
+```
+
+**6. Commit updated artifacts:**
+```bash
+node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
+```

package/rcode/references/execute-interactive-mode.md

@@ -0,0 +1,44 @@
+# execute.md — Interactive Execution Mode
+
+Extracted from `execute.md`'s `check_interactive_mode` step. Only loaded when the `--interactive` flag is present — see the conditional include at that point in `execute.md`.
+
+Interactive mode executes plans sequentially **inline** (no subagent spawning) with user
+checkpoints between tasks. The user can review, modify, or redirect work at any point.
+
+**Interactive execution flow:**
+
+1. Load plan inventory as normal (discover_and_group_plans)
+2. For each plan (sequentially, ignoring wave grouping):
+
+   a. **Present the plan to the user:**
+      ```
+      ## Plan {plan_id}: {plan_name}
+
+      Objective: {from plan file}
+      Tasks: {task_count}
+
+      Options:
+      - Execute (proceed with all tasks)
+      - Review first (show task breakdown before starting)
+      - Skip (move to next plan)
+      - Stop (end execution, save progress)
+      ```
+
+   b. **If "Review first":** Read and display the full plan file. Ask again: Execute, Modify, Skip.
+
+   c. **If "Execute":** Read and follow `.rcode/workflows/execute-sprint.md` **inline**
+      (do NOT spawn a subagent). Execute tasks one at a time.
+
+   d. **After each task:** Pause briefly. If the user intervenes (types anything), stop and address
+      their feedback before continuing. Otherwise proceed to next task.
+
+   e. **After plan complete:** Show results, commit, create SUMMARY.md, then present next plan.
+      **Overwrite guard:** If the SUMMARY.md file already exists from a previous run, delete it first with `rm -f <path>` before writing the new version. Never append to or skip an existing SUMMARY.md — always overwrite with the current sprint's completion data.
+
+3. After all plans: proceed to verification (same as normal mode).
+
+**Benefits of interactive mode:**
+- No subagent overhead — dramatically lower token usage
+- User catches mistakes early — saves costly verification cycles
+- Maintains rcode's planning/tracking structure
+- Best for: small phases, bug fixes, verification gaps, learning rcode

package/rcode/references/execute-notify-webhooks.md

@@ -0,0 +1,22 @@
+# execute.md — notify_on_completion (webhook notifications)
+
+Extracted from `execute.md`'s `notify_on_completion` step. Only loaded when a webhook URL is configured — see the conditional include at that point in `execute.md`.
+
+**Post phase completion to configured webhooks (Slack / Discord / MS Teams).**
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" notify send \
+  --title "Phase ${phase_number} complete — ${phase_name}" \
+  --body "$(basename "$PWD") · $(git rev-parse --short HEAD) · ${incomplete_count:-0} plan(s) remaining" \
+  --event "execute-done" 2>/dev/null || true
+```
+
+Users configure webhooks by editing `.rcode/config.yaml`:
+
+```yaml
+slack_webhook_url: "https://hooks.slack.com/services/..."
+discord_webhook_url: "https://discord.com/api/webhooks/..."
+teams_webhook_url: "https://outlook.office.com/webhook/..."
+```
+
+Then verify with `/rcode-notify-test`.

package/rcode/references/execution-protocol.md

@@ -10,13 +10,13 @@ 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
+phase: "8"                  # phase ID (no leading zeros — issue #652)
+plan_number: 1               # plan ID within phase (no leading zeros — issue #652)
+wave: 1                      # auto-derived from depends_on
+depends_on: []                # list of other plan IDs like ["8-1"]
+files_modified: []            # files this plan touches
+autonomous: true               # whether the plan runs without checkpoints
+requirements: []               # requirement IDs mapped to this plan, if any
 ---
 
 ## Objective
@@ -41,10 +41,10 @@ type: checkpoint:human-verify
 
 **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)
+- Phase: `{N}` — no leading zeros (issue #652), e.g. 1, 2, 72
+- Decimal phase (inserted): `{N.M}` (e.g., 2.1, 72.3)
+- Plan within phase: `{N.M}` (e.g., 1.2)
+- Task within plan: `{N.M.T}` (e.g., 1.2.3)
 
 **Task types:**
 - `auto` — executor runs without pausing

package/rcode/references/git-preflight.md

@@ -19,8 +19,8 @@ BRANCH=$(git branch --show-current 2>/dev/null)
 PROTECTED="main master develop v2-prototype"
 
 # Check 3: branch follows naming convention
-# Allowed: feat/foo-bar, fix/123-baz, issue-123-name, task-123-slug
-BRANCH_OK=$(echo "$BRANCH" | grep -qE '^((feat|fix|docs|chore|refactor|test|perf|style|build|ci)/[a-z0-9][a-z0-9-]*|(issue|task)-[0-9]+-[a-z0-9-]+)$' && echo yes || echo no)
+# Allowed: feat/foo-bar, fix/123-baz, issue-123-name, task-123-slug, 8-1-aria (phase-plan-slug)
+BRANCH_OK=$(echo "$BRANCH" | grep -qE '^((feat|fix|docs|chore|refactor|test|perf|style|build|ci)/[a-z0-9][a-z0-9-]*|(issue|task)-[0-9]+-[a-z0-9-]+|[0-9]+-[0-9]+-[a-z0-9-]+)$' && echo yes || echo no)
 
 # Check 4: scope drift — files touched that don't belong to the active task
 # The workflow MUST pass $TASK_SCOPE_GLOB (e.g. ".planning/phases/8-*/" or "src/auth/")