@hanzlaa/rcode 4.3.3 → 4.4.0

package/package.json

@@ -1,21 +1,11 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.3.3",
+  "version": "4.4.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": {
     "rcode": "dist/rcode.js"
   },
-  "scripts": {
-    "dashboard": "node server/dashboard.js",
-    "test": "node --test",
-    "test:ci": "node --test --test-reporter=spec",
-    "postinstall": "node cli/postinstall.js",
-    "build:cli": "node scripts/build.cjs",
-    "build": "node scripts/build.cjs",
-    "prepack": "node scripts/build.cjs",
-    "dogfood": "bash scripts/dogfood-check.sh"
-  },
   "files": [
     "cli/",
     "rcode/",
@@ -61,16 +51,6 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "devDependencies": {
-    "@clack/prompts": "^0.9.1",
-    "diff": "^8.0.4",
-    "esbuild": "^0.25.0",
-    "fast-glob": "^3.3.3",
-    "nanospinner": "^1.2.2",
-    "picocolors": "^1.1.1",
-    "semver": "^7.7.1",
-    "zod": "^3.24.0"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -79,5 +59,15 @@
   },
   "optionalDependencies": {
     "@lydell/node-pty": "1.2.0-beta.12"
+  },
+  "scripts": {
+    "dashboard": "node server/dashboard.js",
+    "test": "node --test",
+    "test:ci": "node --test --test-reporter=spec",
+    "postinstall": "node cli/postinstall.js",
+    "build:cli": "node scripts/build.cjs",
+    "build": "node scripts/build.cjs",
+    "dogfood": "bash scripts/dogfood-check.sh",
+    "test:skills": "node test/skill-snapshot.test.cjs"
   }
-}
+}

package/rcode/agents/rcode-codebase-mapper.md

@@ -30,6 +30,18 @@ Your job: Explore thoroughly across ALL source roots (never assume `src/` is the
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+## Timeout Strategy
+
+If this scan takes longer than expected (many large files, deep directories):
+
+1. **After 3 minutes without writing an output file:** Write a partial CONVENTIONS.md or TESTING.md with what has been discovered so far, clearly marked `## [PARTIAL — scan timed out]` at the top. A partial file is better than no file.
+
+2. **Scope reduction:** If a directory scan is taking too long, limit depth: scan top-level + src/ + lib/ + app/ only. Skip node_modules, dist, .next, .git, coverage automatically.
+
+3. **Never emit only a greeting and go silent.** If you cannot complete the full scan, write whatever you have found to the output file immediately and explain what was skipped.
+
+4. **On stall recovery:** If restarted after a stall, check which output files already exist under `.planning/maps/`. Skip any that are already written (non-empty). Only write the missing ones.
+
 <why_this_matters>
 **These documents are consumed by other rcode commands:**
 

package/rcode/agents/rcode-phase-researcher.md

@@ -83,6 +83,19 @@ Named rules. Cite by name when applying.
 6. **Write RESEARCH.md** — sections in order: User Constraints → Standard Stack → Architecture Patterns → Don't Hand-Roll → Common Pitfalls → Code Examples.
 7. **Return to orchestrator** — RESEARCH.md path in the return message.
 
+## Iterative Retrieval Protocol
+
+After your first search pass, evaluate what's still unknown:
+1. List the open questions your initial searches did NOT answer
+2. If there are ≥2 open questions, run a second search pass targeting those gaps
+3. After the second pass, if critical questions remain (marked MUST-KNOW in your output), run a third pass
+4. Stop when: (a) all MUST-KNOW gaps are filled, (b) 3 passes are complete, or (c) the same result appears in 2+ searches (diminishing returns signal)
+
+Log each pass as:
+  Pass 1: [query list] → [results summary]
+  Pass 2: [gap-filling queries] → [results summary]
+  Pass 3 (if needed): [remaining gaps] → [results summary]
+
 ## Anti-Patterns / Refuse List
 
 - **Never omit User Constraints** — the planner enforces them; missing constraints cause plan/user conflicts.

package/rcode/agents/rcode-project-researcher.md

@@ -28,6 +28,25 @@ Your files feed the roadmap:
 **Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z."
 </role>
 
+## content-site Mode
+
+When `project_type` is `content-site` (detected from PROJECT.md or the new-project classification step), skip the generic STACK.md / FEATURES.md / ARCHITECTURE.md research flow. Instead produce:
+
+**KEYWORDS.md** — seed keyword list with intent classification per keyword (informational / commercial / transactional / navigational). Call `claude-seo:seo-cluster` if available to generate the SERP-overlap cluster map. Minimum: 20 keywords across at least 3 intent categories.
+
+**CLUSTERS.md** — hub/spoke content architecture. Each cluster = one hub page + N spoke pages. Derive from keyword intent groupings. Include: page type per node (hub / spoke / programmatic / location), primary keyword, secondary keywords (≤3), and estimated internal link targets (hub links to all spokes; each spoke links back to hub + 2 sibling spokes).
+
+**PITFALLS.md** — SEO-specific pitfalls for this project. Must include at minimum:
+1. Thin-content risk (pages under word floor indexed before enrichment)
+2. Canonical drift (programmatic pages with near-duplicate URLs getting split authority)
+3. Noindex strategy (when to gate pages as noindex until enriched vs. index immediately)
+4. Duplicate title/H1 trap (city×service matrix producing identical meta across locations)
+5. Crawl budget waste (low-value pages consuming crawl allocation)
+
+Reference `seo-content-factory` for the full production pipeline and `seo-growth-orchestrator` for strategy orchestration.
+
+Do NOT produce STACK.md, FEATURES.md, or ARCHITECTURE.md for content-site projects. Technology stack research is secondary — the content pipeline is the product.
+
 <philosophy>
 
 ## Honest Reporting
@@ -81,6 +100,19 @@ Named rules. Cite by name when applying.
    - `PITFALLS.md` — risk flags for deeper research
 6. **Return to orchestrator** — list all written files.
 
+## Iterative Retrieval Protocol
+
+After your first search pass, evaluate what's still unknown:
+1. List the open questions your initial searches did NOT answer
+2. If there are ≥2 open questions, run a second search pass targeting those gaps
+3. After the second pass, if critical questions remain (marked MUST-KNOW in your output), run a third pass
+4. Stop when: (a) all MUST-KNOW gaps are filled, (b) 3 passes are complete, or (c) the same result appears in 2+ searches (diminishing returns signal)
+
+Log each pass as:
+  Pass 1: [query list] → [results summary]
+  Pass 2: [gap-filling queries] → [results summary]
+  Pass 3 (if needed): [remaining gaps] → [results summary]
+
 ## Anti-Patterns / Refuse List
 
 - **Never present a menu of options** when a clear recommendation can be made. Per Confident-but-honest.

package/rcode/agents/rcode-roadmapper.md

@@ -46,3 +46,18 @@ Named rules. Cite by name when applying.
 - **Never over-phase** — for a solo developer project, 3-7 phases is typical. 15 phases is corporate theater.
 - **Never start planning before reading the research files** — phases without research produce wrong phase structures.
 
+## Scope Constraint
+
+**rcode-roadmapper creates ONLY:**
+- `ROADMAP.md` — the project roadmap with phases, requirements, and success criteria
+- One `PHASE.md` per phase directory (if phase-level detail files are requested)
+- `STATE.md` — project memory initialization
+- `REQUIREMENTS.md` traceability updates
+
+**rcode-roadmapper MUST NOT create:**
+- `SPRINT.md` — sprint planning is handled exclusively by `/rcode-plan`
+- `PLAN.md` — plan files are out of scope for this agent
+- Any other sprint-level or task-level planning files
+
+If you find yourself about to write a `SPRINT.md` file, **STOP** — that file is out of scope for this agent. Sprint planning is the responsibility of `/rcode-plan`, not `/rcode-new-project` or the roadmapper.
+

package/rcode/agents/rules/planner/common-patterns.md

@@ -371,3 +371,43 @@ If your work doesn't match any pattern:
 4. Document the rationale in the plan
 
 Novel patterns are fine — just ensure they're still decomposed correctly.
+
+---
+
+## Known Stack Constraints
+
+Hard-won version constraints and format requirements that the planner must honour
+when generating `devDependencies`, scaffold files, or code snippets. Getting these
+wrong causes runtime crashes or build failures that are hard to diagnose.
+
+### Mobile / Expo
+
+**Expo SDK 55+ requires TypeScript ≥ 5.4**
+
+`tsconfig.base.json` in Expo SDK 55 sets `"module": "preserve"`, which TypeScript
+< 5.4 does not support and will error on at compile time.
+
+- When generating `devDependencies` for any Expo SDK 50+ project, always specify
+  `"typescript": "~5.8.0"` (or at minimum `"~5.4.0"`).
+- **Never** emit `"typescript": "~5.3.x"` for an Expo project.
+
+### Drizzle ORM — Migrations Barrel Format (v0.30.x+)
+
+The migrations barrel passed to `drizzle-orm/expo-sqlite` (and similar drivers)
+must be an **object**, not an array.
+
+```ts
+// CORRECT — object spread
+import * as m0000 from './migrations/0000_bored_microchip.sql';
+export const migrations = { m0000 };
+
+// WRONG — array causes a runtime crash
+export const migrations = [m0000];
+```
+
+Additional rules:
+- SQL filenames are auto-generated by `drizzle-kit generate` (e.g. `0000_bored_microchip.sql`).
+  Never hardcode SQL filenames in plans — instruct the executor to match actual
+  `drizzle-kit` output or use a dynamic import glob.
+- The barrel file must be re-generated (or updated) whenever `drizzle-kit generate`
+  produces a new migration file.

package/rcode/bin/lib/roadmap.cjs

@@ -14,6 +14,69 @@ function roadmapPathFor(projectRoot) {
   return path.join(projectRoot, '.planning', 'ROADMAP.md');
 }
 
+/**
+ * Resolve the active ROADMAP file path for a project.
+ *
+ * Convention detection (#734):
+ *   1. Single file — .planning/ROADMAP.md (primary / existing behaviour)
+ *   2. Per-milestone — .planning/ROADMAP-M<N>.md, e.g. ROADMAP-M3.md
+ *      Selects the file that matches state.current_milestone when present;
+ *      falls back to the lexicographically last file when no state is set.
+ *
+ * Returns { path, convention, milestone } where convention is
+ * 'single' | 'per-milestone'.
+ */
+function resolveRoadmapPath(projectRoot) {
+  const single = path.join(projectRoot, '.planning', 'ROADMAP.md');
+  if (fs.existsSync(single)) {
+    return { path: single, convention: 'single', milestone: null };
+  }
+
+  // Scan for ROADMAP-M*.md files
+  const planningDir = path.join(projectRoot, '.planning');
+  let milestoneFiles = [];
+  if (fs.existsSync(planningDir)) {
+    milestoneFiles = fs.readdirSync(planningDir)
+      .filter(f => /^ROADMAP-M\d+\.md$/i.test(f))
+      .sort();
+  }
+
+  if (milestoneFiles.length === 0) {
+    // Neither convention found — return the canonical path (callers handle missing file)
+    return { path: single, convention: 'single', milestone: null };
+  }
+
+  // Read state.json to find current_milestone
+  const stateJsonPath = path.join(projectRoot, '.rcode', 'state.json');
+  let currentMilestone = null;
+  if (fs.existsSync(stateJsonPath)) {
+    try {
+      const st = JSON.parse(fs.readFileSync(stateJsonPath, 'utf8'));
+      currentMilestone = st.current_milestone || null;
+    } catch { /* non-fatal */ }
+  }
+
+  // Try to match by milestone id (e.g. "M3", "3", "milestone-3")
+  let matched = null;
+  if (currentMilestone) {
+    const numMatch = String(currentMilestone).match(/(\d+)/);
+    const milestoneNum = numMatch ? numMatch[1] : null;
+    if (milestoneNum) {
+      matched = milestoneFiles.find(f => {
+        const m = f.match(/^ROADMAP-M(\d+)\.md$/i);
+        return m && m[1] === milestoneNum;
+      });
+    }
+  }
+
+  // Fall back to the last file in sorted order
+  if (!matched) matched = milestoneFiles[milestoneFiles.length - 1];
+
+  const resolvedPath = path.join(planningDir, matched);
+  const milestoneLabel = matched.replace(/^ROADMAP-M(\d+)\.md$/i, 'M$1');
+  return { path: resolvedPath, convention: 'per-milestone', milestone: milestoneLabel };
+}
+
 /**
  * Extract all phase sections. Each returned entry includes:
  *   number, name, goal, section (raw markdown slice), headerIndex, sectionEnd
@@ -66,11 +129,30 @@ function extractPhases(content) {
 
 function parseRequirements(section) {
   // Matches both bold-style (**Requirements:**) and heading-style (### Requirements)
-  const match = section.match(/(?:\*\*Requirements(?::\*\*|\*\*:)|#{1,4}\s*Requirements\s*:?)[^\n]*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
-  if (!match) return [];
-  return match[1].split('\n')
-    .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
-    .filter(Boolean);
+  // followed by a list block.
+  const listMatch = section.match(/(?:\*\*Requirements(?::\*\*|\*\*:)|#{1,4}\s*Requirements\s*:?)[^\n]*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
+  if (listMatch) {
+    return listMatch[1].split('\n')
+      .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
+      .filter(Boolean);
+  }
+
+  // Also capture REQ-IDs from inline lines like:
+  //   **REQs:** REQ-004, REQ-010, REQ-020
+  //   Requirements: REQ-001, REQ-002
+  //   **Covers:** REQ-001, REQ-003
+  // Collect every line in the section that contains REQ-\d+ patterns.
+  const seen = new Set();
+  const out = [];
+  const reqIdRe = /\bREQ-[A-Z0-9][A-Z0-9-]*\b/g;
+  for (const line of section.split('\n')) {
+    if (!/REQ-/i.test(line)) continue;
+    const ids = line.match(reqIdRe) || [];
+    for (const id of ids) {
+      if (!seen.has(id)) { seen.add(id); out.push(id); }
+    }
+  }
+  return out;
 }
 
 function parseSuccessCriteria(section) {
@@ -124,7 +206,7 @@ function phaseStatus(section) {
 function normalizePhaseNum(n) { return parseInt(String(n).replace(/^0+/, '') || '0', 10); }
 
 function cmdGetPhase(projectRoot, phaseNum, opts = {}) {
-  const rp = roadmapPathFor(projectRoot);
+  const { path: rp } = resolveRoadmapPath(projectRoot);
   if (!fs.existsSync(rp)) {
     return { found: false, error: 'ROADMAP.md not found', phase_number: phaseNum };
   }
@@ -169,19 +251,67 @@ function cmdGetPhase(projectRoot, phaseNum, opts = {}) {
 }
 
 function cmdListPhases(projectRoot) {
-  const rp = roadmapPathFor(projectRoot);
+  const { path: rp } = resolveRoadmapPath(projectRoot);
   if (!fs.existsSync(rp)) return [];
   const content = fs.readFileSync(rp, 'utf8');
   // Phase 10 / #466 — prefer the parsed Status field from extractPhases over
   // the legacy phaseStatus() heuristic, which only matched literal "completed"
   // in the header and missed our **Status:** Complete convention. Fall back to
   // phaseStatus() only when extractPhases couldn't parse a Status line.
-  return extractPhases(content).map((p) => ({
+  const phases = extractPhases(content).map((p) => ({
     number: p.number,
     name: p.name,
     status: p.status === 'unknown' ? phaseStatus(p.section) : p.status,
     status_raw: p.status_raw,
   }));
+
+  // Fix #856 — state.current_phase is authoritative for which phase is in_progress.
+  // ROADMAP.md may carry a stale "Active" marker from a previous phase after
+  // `state set-phase` has moved forward. Read state.json and override statuses so
+  // exactly one phase (the current one) gets in_progress, and any other phase that
+  // ROADMAP still labels active/in_progress is demoted to planned.
+  const stateJsonPath = path.join(projectRoot, '.rcode', 'state.json');
+  let currentPhase = null;
+  if (fs.existsSync(stateJsonPath)) {
+    try {
+      const st = JSON.parse(fs.readFileSync(stateJsonPath, 'utf8'));
+      currentPhase = st.current_phase || null;
+    } catch { /* non-fatal — fall through to ROADMAP-only statuses */ }
+  }
+
+  if (!currentPhase) return phases;
+
+  // Extract the numeric prefix from current_phase (e.g. "02-correctness-fixes" → "2").
+  const numPrefixMatch = String(currentPhase).match(/^(\d+)/);
+  const leadingNum = numPrefixMatch ? String(parseInt(numPrefixMatch[1], 10)) : null;
+
+  let matched = false;
+  return phases.map((p) => {
+    // Normalize the ROADMAP phase number (strip leading zeros) for comparison.
+    const normNum = String(parseInt(String(p.number), 10));
+    const isCurrentPhase =
+      !matched && (
+        p.name === currentPhase ||
+        (leadingNum !== null && normNum === leadingNum) ||
+        String(p.number) === String(currentPhase)
+      );
+    if (isCurrentPhase) {
+      matched = true;
+      // Only promote to in_progress if not already complete/closed.
+      const s = String(p.status || '').toLowerCase();
+      if (s !== 'complete' && s !== 'closed') {
+        return { ...p, status: 'in_progress' };
+      }
+      return p;
+    }
+    // Demote any other phase that ROADMAP still marks active/in_progress —
+    // state.current_phase is the single source of truth for the active phase.
+    const s = String(p.status || '').toLowerCase();
+    if (s === 'active' || s === 'in_progress') {
+      return { ...p, status: 'planned' };
+    }
+    return p;
+  });
 }
 
 /**
@@ -226,7 +356,7 @@ function cmdUpdatePlanProgress(projectRoot, phaseNum, planId, status) {
   if (!planId || !status) {
     throw new Error('Usage: roadmap update-plan-progress <phase> <plan-id> <status>');
   }
-  const rp = roadmapPathFor(projectRoot);
+  const { path: rp } = resolveRoadmapPath(projectRoot);
   if (!fs.existsSync(rp)) {
     return { updated: false, error: 'ROADMAP.md not found' };
   }
@@ -278,7 +408,7 @@ function cmdUpdatePlanProgress(projectRoot, phaseNum, planId, status) {
  * roadmap summary — overview of phase counts and active phase.
  */
 function cmdSummary(projectRoot) {
-  const rp = roadmapPathFor(projectRoot);
+  const { path: rp } = resolveRoadmapPath(projectRoot);
   if (!fs.existsSync(rp)) return { found: false, error: 'ROADMAP.md not found' };
   const phases = cmdListPhases(projectRoot);
   const total = phases.length;
@@ -297,6 +427,8 @@ function cmdSummary(projectRoot) {
  * roadmap clear — archive and scaffold.
  */
 function cmdClear(projectRoot) {
+  // Clear always targets the canonical single-file path — per-milestone files
+  // are managed per-milestone and not cleared globally.
   const rp = roadmapPathFor(projectRoot);
   // Derive current version from config.yaml or default v1.0
   const configPath = path.join(projectRoot, '.rcode', 'config.yaml');
@@ -322,6 +454,43 @@ function cmdClear(projectRoot) {
   return { cleared: true, archived, version, roadmap: rp };
 }
 
+/**
+ * roadmap detect — report which ROADMAP convention is in use (#734).
+ *
+ * Outputs a human-readable line and returns structured JSON.
+ * Examples:
+ *   single: .planning/ROADMAP.md
+ *   per-milestone: .planning/ROADMAP-M3.md (current)
+ */
+function cmdDetect(projectRoot) {
+  const resolved = resolveRoadmapPath(projectRoot);
+  const exists = fs.existsSync(resolved.path);
+  const rel = path.relative(projectRoot, resolved.path);
+
+  if (resolved.convention === 'single') {
+    const label = exists ? `single: ${rel}` : `single: ${rel} (not found)`;
+    return { __raw: label, convention: 'single', path: rel, exists, milestone: null };
+  }
+
+  // per-milestone — also list all available milestone files
+  const planningDir = path.join(projectRoot, '.planning');
+  const allFiles = fs.existsSync(planningDir)
+    ? fs.readdirSync(planningDir).filter(f => /^ROADMAP-M\d+\.md$/i.test(f)).sort()
+    : [];
+
+  const label = exists
+    ? `per-milestone: ${rel} (current)`
+    : `per-milestone: ${rel} (current, not found)`;
+  return {
+    __raw: label,
+    convention: 'per-milestone',
+    path: rel,
+    exists,
+    milestone: resolved.milestone,
+    all_milestone_files: allFiles.map(f => path.join('.planning', f)),
+  };
+}
+
 function dispatch(projectRoot, subArgs) {
   const sub = subArgs[0];
   const rest = subArgs.slice(1);
@@ -344,8 +513,10 @@ function dispatch(projectRoot, subArgs) {
       return cmdClear(projectRoot);
     case 'summary':
       return cmdSummary(projectRoot);
+    case 'detect':
+      return cmdDetect(projectRoot);
     default:
-      throw new Error(`Unknown roadmap subcommand: ${sub}. Valid: get-phase, list-phases, update-plan-progress, clear, summary`);
+      throw new Error(`Unknown roadmap subcommand: ${sub}. Valid: get-phase, list-phases, update-plan-progress, clear, summary, detect`);
   }
 }
 
@@ -356,4 +527,6 @@ module.exports = {
   cmdUpdatePlanProgress,
   cmdClear,
   cmdSummary,
+  cmdDetect,
+  resolveRoadmapPath,
 };