@hanzlaa/rcode 4.7.2 → 4.8.0

package/AGENTS.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `init`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CLAUDE.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `init`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CONTRIBUTING.md

@@ -282,10 +282,12 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `getting-started` — the `docs/getting-started.md` onboarding guide
 - `config` — team.yaml, config.yaml
 - `github` — CI/CD, issue templates, PR templates
+- `github-sync` — `cli/github-sync.js` and its discovery/parsing logic
 - `cli` — `cli/*.js` and `rcode/bin/rcode-tools.cjs`
 - `state` — `.rcode/state.json` and state-manipulation code paths
 - `refs` — files inside `rcode/references/`
 - `hooks` — `.claude/hooks/*` and install-time hook wiring
+- `init` — `/rcode-init` command and init-time project bootstrap
 - `install` — installer flow, manifest, side-effects
 - `memory` — Memory Bank distillates and templates
 - `brand` — branding/voice across surfaces
@@ -310,6 +312,8 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `plan` — plan workflow
 - `planner` — planner agent
 - `readme` — README.md
+- `review` — code review reports and review-gate fixes (e.g. `NN-REVIEW.md` resolutions)
+- `rcode` — cross-cutting rcode planning/methodology commits not tied to one narrower scope
 - `sync` — install/state sync flows
 - `sprint` — sprint-level workflow additions and fixes
 - `agent-exp` — agent experience improvements

package/cli/github-sync.js

@@ -11,10 +11,10 @@
  *   rcode github-sync --execute       # actually create issues
  *
  * Granular targeting (push specific items):
- *   --phase=phase-02          push one phase (all its epics + stories)
- *   --sprint=sprint-01        push stories belonging to one sprint
- *   --epic=epic-1-auth        push one epic and its child stories
- *   --story=story-1-1-login   push one story
+ *   --phase=44                push one phase (all its epics + stories)
+ *   --sprint=44.1             push stories belonging to one sprint
+ *   --epic=EPIC-01            push one epic and its child stories
+ *   --story=44.1.1            push one story (sprint-track task id or epic-track story id, e.g. 1.1)
  *
  * Options:
  *   --repo=owner/name     target a specific repo (otherwise auto-detect)
@@ -45,6 +45,7 @@ const gh = require('./lib/github.cjs');
 const { askText, PromptAbortError } = require('./lib/prompts.cjs');
 const { writeJsonAtomic } = require('./lib/fsutil.cjs');
 const { loadConfig } = require('./lib/config.cjs');
+const { discoverPhases, applyGranularFilters } = require('./lib/github-sync-discover.cjs');
 
 /**
  * Hash a string — used to detect content changes between syncs.
@@ -140,51 +141,6 @@ function parseArgs(args) {
   return opts;
 }
 
-/**
- * Parse YAML-ish frontmatter from the top of a markdown file.
- * Used to extract explicit epic/sprint linking from story files.
- * Returns an object of key/value strings, or {} if no frontmatter block.
- */
-function extractFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return {};
-  const fm = {};
-  for (const line of match[1].split(/\r?\n/)) {
-    const m = line.match(/^([\w_-]+)\s*:\s*(.*)$/);
-    if (m) fm[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
-  }
-  return fm;
-}
-
-/**
- * Parse .rcode/phases/{phase}/sprints.md if present and return a map of
- * sprint-id → story-ids (based on "- [ ] story-X-Y" list entries under
- * each sprint section). Used by --sprint=ID filtering.
- *
- * Sprint section convention:
- *   ## Sprint 1 — {goal}
- *   - [ ] story-1-1-login
- *   - [ ] story-1-2-signup
- */
-function parseSprintsFile(sprintsContent) {
-  if (!sprintsContent) return {};
-  const sprintMap = {};
-  let currentSprint = null;
-  for (const line of sprintsContent.split(/\r?\n/)) {
-    const header = line.match(/^##\s+Sprint\s+(\S+)/i);
-    if (header) {
-      currentSprint = `sprint-${header[1].replace(/[^\w-]/g, '')}`;
-      sprintMap[currentSprint] = [];
-      continue;
-    }
-    if (currentSprint) {
-      const item = line.match(/^\s*-\s*\[[ xX]\]\s+(\S+)/);
-      if (item) sprintMap[currentSprint].push(item[1]);
-    }
-  }
-  return sprintMap;
-}
-
 // ---------- Discover .rcode/ content ----------
 
 function loadState(cwd) {
@@ -196,148 +152,6 @@ function loadState(cwd) {
   try { return JSON.parse(fs.readFileSync(statePath, 'utf8')); } catch { return null; }
 }
 
-function discoverPhases(cwd) {
-  const phasesDir = path.join(cwd, '.rcode/phases');
-  if (!fs.existsSync(phasesDir)) return [];
-
-  const phases = [];
-  for (const entry of fs.readdirSync(phasesDir, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const phaseDir = path.join(phasesDir, entry.name);
-    const briefPath = path.join(phaseDir, 'brief.md');
-    const sprintsPath = path.join(phaseDir, 'sprints.md');
-    const storiesDir = path.join(phaseDir, 'stories');
-    const tasksDir = path.join(phaseDir, 'tasks');
-
-    const sprintsContent = fs.existsSync(sprintsPath)
-      ? fs.readFileSync(sprintsPath, 'utf8')
-      : null;
-
-    const phase = {
-      id: entry.name,
-      brief: fs.existsSync(briefPath) ? fs.readFileSync(briefPath, 'utf8') : null,
-      sprints: sprintsContent,
-      sprintMap: parseSprintsFile(sprintsContent),
-      stories: [],
-      epics: [],
-    };
-
-    if (fs.existsSync(storiesDir)) {
-      for (const file of fs.readdirSync(storiesDir)) {
-        if (!file.endsWith('.md')) continue;
-        const content = fs.readFileSync(path.join(storiesDir, file), 'utf8');
-        const fm = extractFrontmatter(content);
-        const id = file.replace('.md', '');
-        // Figure out which epic this story belongs to: prefer explicit
-        // frontmatter, fall back to "story-X-..." → "epic-X-..." naming
-        // convention so existing projects without frontmatter still link.
-        let parentEpic = fm.epic || null;
-        if (!parentEpic) {
-          const m = id.match(/^story-(\d+)/);
-          if (m) parentEpic = `epic-${m[1]}`;
-        }
-        // Figure out which sprint this story belongs to: explicit
-        // frontmatter wins, else look it up in the sprint map.
-        let sprintId = fm.sprint || null;
-        if (!sprintId) {
-          for (const [sid, storyList] of Object.entries(phase.sprintMap)) {
-            if (storyList.some((s) => s === id || id.startsWith(s))) {
-              sprintId = sid;
-              break;
-            }
-          }
-        }
-        phase.stories.push({
-          id,
-          file,
-          content,
-          title: extractTitle(content) || id,
-          parentEpic,
-          sprintId,
-          frontmatter: fm,
-        });
-      }
-    }
-
-    if (fs.existsSync(tasksDir)) {
-      for (const file of fs.readdirSync(tasksDir)) {
-        if (!file.endsWith('.md')) continue;
-        const content = fs.readFileSync(path.join(tasksDir, file), 'utf8');
-        const fm = extractFrontmatter(content);
-        phase.epics.push({
-          id: file.replace('.md', ''),
-          file,
-          content,
-          title: extractTitle(content) || file.replace('.md', ''),
-          frontmatter: fm,
-        });
-      }
-    }
-
-    phases.push(phase);
-  }
-
-  return phases;
-}
-
-/**
- * Apply granular --sprint/--epic/--story filters to the discovered phases.
- * Mutates a shallow copy — original discovery result is not touched.
- * Returns a new phases array where only the requested items remain.
- */
-function applyGranularFilters(phases, opts) {
-  // No filters → return as-is
-  if (!opts.sprint && !opts.epic && !opts.story) return phases;
-
-  const filtered = phases.map((p) => ({
-    ...p,
-    epics: [...p.epics],
-    stories: [...p.stories],
-  }));
-
-  if (opts.sprint) {
-    for (const p of filtered) {
-      // Keep only stories whose sprintId matches
-      p.stories = p.stories.filter((s) => s.sprintId === opts.sprint);
-      // Keep only epics that have at least one remaining story or whose id
-      // the user might also be interested in (conservative: keep all epics
-      // in this phase so child stories have a visible parent reference)
-      // Actually: if filtering by sprint, user wants the sprint's work —
-      // stories only. Drop epics unless they're referenced by a remaining
-      // story.
-      const liveEpicIds = new Set(p.stories.map((s) => s.parentEpic).filter(Boolean));
-      p.epics = p.epics.filter((e) => liveEpicIds.has(e.id));
-    }
-  }
-
-  if (opts.epic) {
-    for (const p of filtered) {
-      p.epics = p.epics.filter((e) => e.id === opts.epic);
-      // Keep stories whose parentEpic matches
-      p.stories = p.stories.filter((s) => s.parentEpic === opts.epic);
-    }
-  }
-
-  if (opts.story) {
-    for (const p of filtered) {
-      p.stories = p.stories.filter((s) => s.id === opts.story);
-      // Keep any epic a surviving story points at (so link target exists)
-      const parents = new Set(p.stories.map((s) => s.parentEpic).filter(Boolean));
-      p.epics = p.epics.filter((e) => parents.has(e.id));
-    }
-  }
-
-  // Drop phases that ended up completely empty after filtering
-  return filtered.filter(
-    (p) => p.epics.length > 0 || p.stories.length > 0,
-  );
-}
-
-function extractTitle(markdown) {
-  const match = markdown.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : null;
-}
-
 // ---------- Load/save sync map (for idempotency) ----------
 
 function loadSyncMap(cwd) {
@@ -460,7 +274,9 @@ async function main(args) {
   // ------ Discover phases ------
   let phases = discoverPhases(cwd);
   if (opts.phase) {
-    phases = phases.filter((p) => p.id === opts.phase);
+    // Match either the full directory id or the bare numeric prefix so
+    // --phase=44 and --phase=44-github-sync-... both work.
+    phases = phases.filter((p) => p.id === opts.phase || p.numericId === opts.phase);
     if (phases.length === 0) {
       console.error(`❌ Phase '${opts.phase}' not found.`);
       process.exit(1);
@@ -481,8 +297,8 @@ async function main(args) {
       console.error(`   Check the filter value or run without filters to see available ids.`);
       process.exit(1);
     }
-    console.log(`ℹ  No phases found in .rcode/phases/ — nothing to sync.`);
-    console.log(`   Run 'rcode init' or create a phase to get started.`);
+    console.log(`ℹ  No phases found in .planning/phases/ or epics in .planning/epics/ — nothing to sync.`);
+    console.log(`   Run /rcode-plan or /rcode-create-epics-and-stories to get started.`);
     process.exit(0);
   }
 
@@ -551,7 +367,7 @@ async function main(args) {
       { name: 'QA', color: 'd73a4a', description: 'Quality assurance' },
       { name: 'Docs', color: 'c5def5', description: 'Documentation' },
     ] : [],
-    milestones: phases.filter((p) => !syncMap.phases[p.id]),
+    milestones: phases.filter((p) => !p.noMilestone && !syncMap.phases[p.id]),
     epics: phases.flatMap((p) =>
       p.epics.filter((e) => !syncMap.epics[e.id]).map((e) => ({ ...e, phase: p.id })),
     ),
@@ -702,7 +518,7 @@ async function main(args) {
         `## 📊 Meta`,
         ``,
         `- **Phase:** \`${epic.phase}\``,
-        `- **Source:** \`.rcode/phases/${epic.phase}/tasks/${epic.file}\``,
+        `- **Source:** \`${epic.sourcePath}\``,
         `- **Synced by:** rcode github-sync`,
         ``,
         `## 📝 Child Stories`,
@@ -785,7 +601,7 @@ async function main(args) {
         parentRefLine,
         sprintRefLine,
         `- **Phase:** \`${story.phase}\``,
-        `- **Source:** \`.rcode/phases/${story.phase}/stories/${story.file}\``,
+        `- **Source:** \`${story.sourcePath}\``,
         `- **Synced by:** rcode github-sync`,
         ``,
         `> **Linking:** Reference this story in commits with \`refs #${'{issue}'}\``,
@@ -892,7 +708,7 @@ async function main(args) {
       const body = [
         `## 🎯 Epic Vision`,
         ``,
-        `_Strategic goal this Epic contributes to. Fill in from \`.rcode/phases/${epic.phase}/tasks/${epic.file}\`._`,
+        `_Strategic goal this Epic contributes to. Fill in from \`${epic.sourcePath}\`._`,
         ``,
         `## 📋 Source Content`,
         ``,
@@ -903,7 +719,7 @@ async function main(args) {
         `## 📊 Meta`,
         ``,
         `- **Phase:** \`${epic.phase}\``,
-        `- **Source:** \`.rcode/phases/${epic.phase}/tasks/${epic.file}\``,
+        `- **Source:** \`${epic.sourcePath}\``,
         `- **Last synced:** ${new Date().toISOString()}`,
       ].join('\n');
 
@@ -937,7 +753,7 @@ async function main(args) {
       const body = [
         `## 🎯 Problem Statement`,
         ``,
-        `_From \`.rcode/phases/${story.phase}/stories/${story.file}\`._`,
+        `_From \`${story.sourcePath}\`._`,
         ``,
         `## 📋 Source Content`,
         ``,
@@ -948,7 +764,7 @@ async function main(args) {
         `## 📊 Meta`,
         ``,
         `- **Phase:** \`${story.phase}\``,
-        `- **Source:** \`.rcode/phases/${story.phase}/stories/${story.file}\``,
+        `- **Source:** \`${story.sourcePath}\``,
         `- **Last synced:** ${new Date().toISOString()}`,
       ].join('\n');
 

package/cli/lib/config.cjs

@@ -49,7 +49,7 @@ const HARDCODED_DEFAULTS = {
 
   // Paths
   output_folder: '.rcode',
-  planning_artifacts: '.rcode/phases',
+  planning_artifacts: '.planning/phases',
   project_knowledge: '.rcode/context',
 
   // Model profile — matches model-profiles.json names

package/cli/lib/github-sync-discover.cjs

@@ -0,0 +1,304 @@
+/**
+ * cli/lib/github-sync-discover.cjs — phase/epic/story discovery for github-sync
+ *
+ * Owns discovery for BOTH artifact tracks this project produces:
+ *   - sprint-track:  .planning/phases/{slug}/{phase}-{plan}-SPRINT.md
+ *                    (`<task id="" title="">` XML blocks, current planner output)
+ *   - epic-track:    .planning/epics/EPIC-{NN}.md + .planning/epics/stories/{N}.{M}.md
+ *                    (PRD → epics → stories chain, phase-agnostic per docs/adr/0001)
+ *
+ * Required by both cli/github-sync.js (the CLI entry point) and
+ * test/github-sync.test.cjs (so discovery logic is exercised directly instead
+ * of being duplicated inline in tests).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse YAML-ish frontmatter from the top of a markdown file.
+ * Used to extract explicit epic/sprint linking from story files.
+ * Returns an object of key/value strings, or {} if no frontmatter block.
+ */
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const fm = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^([\w_-]+)\s*:\s*(.*)$/);
+    if (m) fm[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+
+function extractTitle(markdown) {
+  const match = markdown.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Parse `<task id="" title="">` blocks out of a SPRINT.md's text, mirroring
+ * server/lib/scanner.js's buildPhaseTree parser (the proven-working reference
+ * implementation for the current planner output format). Falls back to the
+ * legacy `### Story|Task N — title` heading format when no `<task>` blocks
+ * are present (pre-<task> SPRINT.md era).
+ *
+ * Each returned item becomes a story-equivalent GitHub issue — the
+ * sprint-track has no separate epic level; sprint grouping is surfaced via
+ * the `sprintId` field in the issue body's "Sprint:" line.
+ */
+function parseSprintTasks(text, sprintId, file, sourcePathPrefix) {
+  const tasks = [];
+  const taskRe = /<task\b([^>]*)>([\s\S]*?)<\/task>/g;
+  let tm;
+  let n = 0;
+  while ((tm = taskRe.exec(text))) {
+    n += 1;
+    const idM = tm[1].match(/id="([^"]+)"/);
+    const titleAttrM = tm[1].match(/title="([^"]*)"/);
+    const titleTagM = tm[2].match(/<title>([\s\S]*?)<\/title>/);
+    tasks.push({
+      id: idM ? idM[1] : `${sprintId}-task-${n}`,
+      file,
+      content: tm[0],
+      title: (titleAttrM && titleAttrM[1].trim()) || (titleTagM && titleTagM[1].trim()) || `Task ${n}`,
+      parentEpic: null,
+      sprintId,
+      frontmatter: {},
+      sourcePath: `${sourcePathPrefix}/${file}`,
+    });
+  }
+
+  // Fallback for pre-<task> SPRINT.md format: "### Story N — title" / "### Task X — title".
+  if (tasks.length === 0) {
+    const headRe = /^#{2,4}\s+(?:Story|Task)\s+([^\s—–-]+)\s*[—–-]\s*(.+?)\s*$/gm;
+    let hm;
+    while ((hm = headRe.exec(text))) {
+      tasks.push({
+        id: hm[1].trim(),
+        file,
+        content: hm[0],
+        title: hm[2].trim(),
+        parentEpic: null,
+        sprintId,
+        frontmatter: {},
+        sourcePath: `${sourcePathPrefix}/${file}`,
+      });
+    }
+  }
+
+  return tasks;
+}
+
+/**
+ * Discover sprint-track phases from .planning/phases/*-SPRINT.md files.
+ * Returns every discovered phase directory, even ones with zero SPRINT.md
+ * files (parity with the dead legacy directory-tree discovery behavior).
+ */
+function discoverSprintTrackPhases(cwd) {
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  if (!fs.existsSync(phasesDir)) return [];
+
+  const phases = [];
+  for (const entry of fs.readdirSync(phasesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const numericIdM = entry.name.match(/^(\d+)-/);
+    const numericId = numericIdM ? numericIdM[1] : null;
+    const phaseDir = path.join(phasesDir, entry.name);
+    const sourcePathPrefix = `.planning/phases/${entry.name}`;
+
+    const sprintFiles = fs
+      .readdirSync(phaseDir)
+      .filter((f) => /-SPRINT\.md$/i.test(f))
+      .sort((a, b) => {
+        const na = parseInt((a.match(/-(\d+)-SPRINT\.md$/i) || [])[1] || '0', 10);
+        const nb = parseInt((b.match(/-(\d+)-SPRINT\.md$/i) || [])[1] || '0', 10);
+        return na - nb;
+      });
+
+    const stories = [];
+    for (const file of sprintFiles) {
+      const text = fs.readFileSync(path.join(phaseDir, file), 'utf8');
+      const fileM = file.match(/^(\d+)-(\d+)-SPRINT\.md$/i);
+      let sprintId;
+      if (fileM) {
+        sprintId = `${parseInt(fileM[1], 10)}.${parseInt(fileM[2], 10)}`;
+      } else {
+        const fm = extractFrontmatter(text);
+        sprintId = fm.sprint || file.replace(/-SPRINT\.md$/i, '');
+      }
+      stories.push(...parseSprintTasks(text, sprintId, file, sourcePathPrefix));
+    }
+
+    phases.push({
+      id: entry.name,
+      numericId,
+      brief: null,
+      sprints: null,
+      sprintMap: {},
+      stories,
+      epics: [],
+      noMilestone: false,
+    });
+  }
+
+  return phases;
+}
+
+/**
+ * Discover the epic-track from .planning/epics/EPIC-{NN}.md +
+ * .planning/epics/stories/{N}.{M}.md, per the layout in
+ * rcode/workflows/create-epics-and-stories.md. Story files use bold
+ * Markdown fields (`**Epic:** EPIC-{N} — {title}`), NOT YAML frontmatter —
+ * extractFrontmatter correctly returns {} for these and is not used here.
+ *
+ * Epic file names are zero-padded (EPIC-01.md) but a story's `**Epic:**`
+ * field is unpadded (EPIC-1) — match by NUMERIC value so padding
+ * differences never break the parent link.
+ *
+ * Returns null when .planning/epics/ doesn't exist, or when it exists but
+ * has no epics and no stories (nothing to sync — avoid a spurious empty
+ * synthetic phase).
+ */
+function discoverEpicTrackPhase(cwd) {
+  const epicsDir = path.join(cwd, '.planning', 'epics');
+  if (!fs.existsSync(epicsDir)) return null;
+
+  const epics = [];
+  const epicFiles = fs.readdirSync(epicsDir).filter((f) => /^EPIC-\d+\.md$/i.test(f));
+  for (const file of epicFiles) {
+    const content = fs.readFileSync(path.join(epicsDir, file), 'utf8');
+    const numM = file.match(/(\d+)/);
+    const epicNumber = numM ? parseInt(numM[1], 10) : null;
+    const id = file.replace(/\.md$/i, '');
+    epics.push({
+      id,
+      file,
+      epicNumber,
+      content,
+      title: extractTitle(content) || id,
+      frontmatter: {},
+      sourcePath: `.planning/epics/${file}`,
+    });
+  }
+
+  const stories = [];
+  const storiesDir = path.join(epicsDir, 'stories');
+  if (fs.existsSync(storiesDir)) {
+    const storyFiles = fs.readdirSync(storiesDir).filter((f) => /^[\d.]+\.md$/.test(f));
+    for (const file of storyFiles) {
+      const content = fs.readFileSync(path.join(storiesDir, file), 'utf8');
+      const id = file.replace(/\.md$/i, '');
+      const epicRefM = content.match(/\*\*Epic:\*\*\s*EPIC-(\d+)/i);
+      let parentEpic = null;
+      if (epicRefM) {
+        const refNum = parseInt(epicRefM[1], 10);
+        const matchedEpic = epics.find((e) => e.epicNumber === refNum);
+        if (matchedEpic) parentEpic = matchedEpic.id;
+      }
+      stories.push({
+        id,
+        file,
+        content,
+        title: extractTitle(content) || id,
+        parentEpic,
+        sprintId: null,
+        frontmatter: {},
+        sourcePath: `.planning/epics/stories/${file}`,
+      });
+    }
+  }
+
+  if (epics.length === 0 && stories.length === 0) return null;
+
+  return {
+    id: 'epics',
+    numericId: null,
+    brief: null,
+    sprints: null,
+    sprintMap: {},
+    stories,
+    epics,
+    // Signals this synthetic phase has no numbered-phase milestone to
+    // attach to on GitHub — epic-track is a deliberately phase-agnostic
+    // PRD→epics→stories chain per docs/adr/0001, distinct from the numbered
+    // .planning/phases/ milestones.
+    noMilestone: true,
+  };
+}
+
+/**
+ * Combine sprint-track and epic-track discovery into one phases array.
+ */
+function discoverPhases(cwd) {
+  const phases = discoverSprintTrackPhases(cwd);
+  const epicPhase = discoverEpicTrackPhase(cwd);
+  if (epicPhase) phases.push(epicPhase);
+  return phases;
+}
+
+/**
+ * Apply granular --sprint/--epic/--story filters to the discovered phases.
+ * Mutates a shallow copy — original discovery result is not touched.
+ * Returns a new phases array where only the requested items remain.
+ */
+function applyGranularFilters(phases, opts) {
+  // No filters → return as-is
+  if (!opts.sprint && !opts.epic && !opts.story) return phases;
+
+  const filtered = phases.map((p) => ({
+    ...p,
+    epics: [...p.epics],
+    stories: [...p.stories],
+  }));
+
+  if (opts.sprint) {
+    // Normalize both dash and dot sprint-id forms so --sprint=44-1 and
+    // --sprint=44.1 both match a stored sprintId of "44.1".
+    const sprintNorm = opts.sprint.replace(/-/g, '.');
+    for (const p of filtered) {
+      // Keep only stories whose sprintId matches
+      p.stories = p.stories.filter((s) => s.sprintId === opts.sprint || s.sprintId === sprintNorm);
+      // Keep only epics that have at least one remaining story or whose id
+      // the user might also be interested in (conservative: keep all epics
+      // in this phase so child stories have a visible parent reference)
+      // Actually: if filtering by sprint, user wants the sprint's work —
+      // stories only. Drop epics unless they're referenced by a remaining
+      // story.
+      const liveEpicIds = new Set(p.stories.map((s) => s.parentEpic).filter(Boolean));
+      p.epics = p.epics.filter((e) => liveEpicIds.has(e.id));
+    }
+  }
+
+  if (opts.epic) {
+    for (const p of filtered) {
+      p.epics = p.epics.filter((e) => e.id === opts.epic);
+      // Keep stories whose parentEpic matches
+      p.stories = p.stories.filter((s) => s.parentEpic === opts.epic);
+    }
+  }
+
+  if (opts.story) {
+    for (const p of filtered) {
+      p.stories = p.stories.filter((s) => s.id === opts.story);
+      // Keep any epic a surviving story points at (so link target exists)
+      const parents = new Set(p.stories.map((s) => s.parentEpic).filter(Boolean));
+      p.epics = p.epics.filter((e) => parents.has(e.id));
+    }
+  }
+
+  // Drop phases that ended up completely empty after filtering
+  return filtered.filter(
+    (p) => p.epics.length > 0 || p.stories.length > 0,
+  );
+}
+
+module.exports = {
+  extractFrontmatter,
+  extractTitle,
+  discoverSprintTrackPhases,
+  discoverEpicTrackPhase,
+  discoverPhases,
+  applyGranularFilters,
+};