@hanzlaa/rcode 4.1.1 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.1.1",
+  "version": "4.3.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/bin/rcode-tools.cjs

@@ -447,12 +447,19 @@ function cmdInit(workflowName, rawArgs) {
         } catch { /* parser failure shouldn't break init */ }
       }
 
-      // Find phase directory on disk (matches both '6-name' and legacy '06-name').
+      // Find phase directory on disk (matches '1-name', '01-name', and '001-name' prefixes).
       let phaseDirEntry = null;
       if (fs.existsSync(phasesDir)) {
-        const padded = String(phaseNum).padStart(2, '0');
+        const n = String(phaseNum);
+        const pad2 = n.padStart(2, '0');
+        const pad3 = n.padStart(3, '0');
         for (const entry of fs.readdirSync(phasesDir)) {
-          if (entry === String(phaseNum) || entry.startsWith(`${phaseNum}-`) || entry.startsWith(`${padded}-`)) {
+          if (
+            entry === n ||
+            entry.startsWith(`${n}-`) ||
+            entry.startsWith(`${pad2}-`) ||
+            entry.startsWith(`${pad3}-`)
+          ) {
             phaseDirEntry = entry;
             break;
           }
@@ -463,10 +470,12 @@ function cmdInit(workflowName, rawArgs) {
       out.phase_number = String(phaseNum);
       // Issue #652 — no leading zeros in planning artifacts. The field name
       // 'padded_phase' is kept for workflow backward compat but the value is
-      // now the canonical (unpadded) phase number. The resolver above still
-      // accepts legacy '06-name' directories for older projects.
+      // now the canonical (unpadded) phase number (e.g. "6", not "06").
+      // Workflows MUST NOT rely on this being zero-padded; use phase_number instead.
+      // The resolver above still accepts legacy '06-name' / '006-name' dirs for older projects.
       out.padded_phase = String(phaseNum);
       out.phase_name = roadmapPhase ? roadmapPhase.name : null;
+      // Strip all leading-zero prefix digits so '001-name', '01-name', '1-name' → 'name'.
       out.phase_slug = phaseDirEntry ? phaseDirEntry.replace(/^\d+-/, '') : null;
       out.phase_dir = phaseDirEntry ? path.join(PLANNING_DIR, 'phases', phaseDirEntry) : null;
 
@@ -1367,7 +1376,7 @@ function cmdState(subArgs) {
       String(p.id) === String(flags.phase) ||
       p.name === flags.phase
     );
-    if (phaseIdx === -1) throw new Error(`Phase "${flags.phase}" not found in state`);
+    if (phaseIdx === -1) throw new Error(`Phase "${flags.phase}" not found in state. If the phase exists in ROADMAP.md, run "rcode state sync" or "/rcode-update" to synchronize state first.`);
     const phase = state.phases[phaseIdx];
 
     // Derive phase number: prefer explicit .number, fallback to array position

package/rcode/commands/scaffold-project.md

@@ -1,7 +1,7 @@
 ---
 name: rcode-scaffold-project
-description: "Scaffold a new project from the official rcode template repo."
-argument-hint: "[project-name]"
+description: "Scaffold a new project from the official rcode template repo, or add rcode to an existing project with --here."
+argument-hint: "[project-name | --here]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rcode/skills/actions/2-plan/rcode-create-epics-and-stories/steps/step-04-final-validation.md

@@ -119,7 +119,7 @@ If all validations pass:
 - Ensure proper formatting
 - Save the final epics.md
 
-### 7. State Sync (MANDATORY — closes #126)
+### 7. State Sync (MANDATORY)
 
 After saving `.planning/epics.md`, you MUST sync state so `.rcode/state.json` reflects the new epics. Without this, downstream workflows (`/rcode-status`, `/rcode-progress`, `/rcode-execute`) see a divergent picture.
 

package/rcode/skills/actions/2-plan/rcode-create-milestone/steps/README.md

@@ -4,8 +4,8 @@ This skill uses the same step-file architecture as `rcode-create-prd` and `rcode
 
 ## Status
 
-- All 10 step files are **implemented and production-ready** as of #134.
-- Scaffolded in #129; completed in #134; compliance re-verified in #137.
+- All 10 step files are **implemented and production-ready**.
+- Scaffolded, completed, and compliance-verified across multiple releases.
 - If a step is missing from this directory at runtime, re-install the package — do not fall back to inline generation.
 
 ## Expected Step Files (per workflow.md)

package/rcode/skills/actions/2-plan/rcode-create-milestone/steps/step-09-state-sync.md

@@ -4,7 +4,7 @@
 
 ## STEP GOAL
 
-Call the state-sync CLI so `.rcode/state.json` reflects every milestone and phase we just wrote to `ROADMAP.md`. This closes the drift loophole documented in issue #126 and enforced by `_shared/state-sync-rule.md`.
+Call the state-sync CLI so `.rcode/state.json` reflects every milestone and phase we just wrote to `ROADMAP.md`. This closes the state-drift loophole enforced by `_shared/state-sync-rule.md`.
 
 ## MANDATORY RULES
 

package/rcode/skills/actions/4-implementation/rcode-code-review/steps/step-02-review.md

@@ -17,7 +17,7 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 
 2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
 
-   **Subagent mapping** (issue #720): the three reviewer roles below map to actual agents shipped in `.claude/agents/`. The skill names that used to be referenced here (`rcode-review-adversarial-general`, `rcode-review-edge-case-hunter`) are skills, not subagents, and `Task(subagent_type=...)` cannot reach them. Use the agents listed.
+   **Subagent mapping:** the three reviewer roles below map to actual agents shipped in `.claude/agents/`. The skill names that used to be referenced here (`rcode-review-adversarial-general`, `rcode-review-edge-case-hunter`) are skills, not subagents, and `Task(subagent_type=...)` cannot reach them. Use the agents listed.
 
    - **Blind Hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Dispatch:
      `Task(subagent_type="rcode-security-adversary", model="{review_model}", prompt="<adversarial review of diff>")`. The security-adversary persona's cynical mindset is the right fit for an isolated diff-only review.

package/rcode/skills/actions/4-implementation/rcode-git-flow/SKILL.md

@@ -81,7 +81,7 @@ Do NOT include: force-pushes to main; commits with AI attribution; bundled commi
 
 ## Examples
 
-**Happy path** — Issue #387 (refresh README counts) → branch `docs/readme-counts` → 1 commit with subject `docs(readme): refresh agent/command/skill counts and add MIGRATIONS link` → push → PR with `Closes #387` → squash-merge.
+**Happy path** — A tracked issue (refresh README counts) → branch `docs/readme-counts` → 1 commit with subject `docs(readme): refresh agent/command/skill counts and add MIGRATIONS link` → push → PR with `Closes` the tracked issue → squash-merge.
 
 **Edge case — conflict on team.yaml** — Two branches both edit team.yaml. Resolve by: pull both versions, manually merge agent entries (preserve unique IDs), run `node --test test/agents-registry.test.cjs`, commit.
 

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/SKILL.md

@@ -2,10 +2,12 @@
 name: rcode-scaffold-project
 internal: true
 description: >
-  Scaffold a new project for rcode users using the official rcode template repo.
+  Scaffold a new project for rcode users using the official rcode template repo,
+  or initialize rcode in an existing project (brownfield / --here mode).
   Activates when the user says "scaffold project", "create project", "new project",
   "initialize project", "setup new project", "scaffold from template", "create from template",
-  "rcode new project", or "start a new rcode project". Do NOT use for generating
+  "rcode new project", "start a new rcode project", "scaffold here", "use here",
+  "scaffold in this project", or "initialize rcode here". Do NOT use for generating
   project context files (use rcode-generate-project-context) or cloning websites
   (use rcode-clone-website).
 triggers:
@@ -18,6 +20,12 @@ triggers:
   - "create from template"
   - "rcode new project"
   - "start a new rcode project"
+  - "scaffold here"
+  - "scaffold --here"
+  - "use current directory"
+  - "scaffold in this project"
+  - "initialize rcode here"
+  - "add rcode to existing project"
 user-invocable: true
 ---
 @.rcode/references/karpathy-guidelines.md
@@ -30,14 +38,21 @@ user-invocable: true
 
 ## Overview
 
-This skill bootstraps a new rcode project by cloning the official rcode template
-repository (`https://github.com/rcode-om/template`) into a target directory.
+This skill operates in two modes:
 
-It always clones fresh from GitHub — nothing is stored locally — so if the template
-is updated, the next scaffold automatically picks up the latest version.
+**Greenfield mode (default):** Bootstraps a new rcode project by cloning the
+official rcode template (`https://github.com/rcode-om/template`) into a target
+directory. Always clones fresh from GitHub.
+
+**Brownfield mode (`--here`):** Initializes rcode in an *existing* project
+without cloning the template. Use this when your codebase already exists and
+you just want to add rcode structure to it. Invoke as:
+`/rcode-scaffold-project --here` or just say "scaffold here" / "add rcode to
+this existing project".
 
 The workflow enforces safety: it never overwrites an existing non-empty directory
-without explicit user consent.
+without explicit user consent (greenfield), and never modifies existing project
+files in brownfield mode.
 
 ## On Activation
 
@@ -53,9 +68,10 @@ Then proceed to `./steps/step-01-target.md`.
 
 | # | Stage | Purpose | File |
 |---|-------|---------|------|
-| 1 | Target Directory | Get + validate destination path | `steps/step-01-target.md` |
-| 2 | Safety Check | Verify folder is empty or get new path | `steps/step-02-safety.md` |
-| 3 | Clone | Clone template repo fresh from GitHub | `steps/step-03-clone.md` |
+| 1 | Target Directory | Get + validate destination path; detect `--here` flag | `steps/step-01-target.md` |
+| 2 | Safety Check | Verify folder is empty or get new path (greenfield); brownfield consent (brownfield) | `steps/step-02-safety.md` |
+| 3a | Clone | Clone template repo fresh from GitHub *(greenfield only)* | `steps/step-03-clone.md` |
+| 3b | Brownfield Init | Overlay rcode structure into existing project *(brownfield only)* | `steps/step-03-brownfield.md` |
 | 4 | Post-Setup | Rename, init git, suggest next steps | `steps/step-04-post-setup.md` |
 
 ## Design Decisions
@@ -63,6 +79,7 @@ Then proceed to `./steps/step-01-target.md`.
 - **Always clone fresh** — never cache template locally. Template updates are free.
 - **No local template copy** — single source of truth is `https://github.com/rcode-om/template`.
 - **Safety first** — never touch a non-empty directory without user approval.
+- **Brownfield never overwrites** — in `--here` mode, existing files are never modified.
 - **Minimal assumptions** — ask before acting on any ambiguity.
 
 ## Output Format
@@ -86,6 +103,16 @@ Then proceed to `./steps/step-01-target.md`.
 **Input:** "scaffold project"
 **Expected:** Ask for project name before proceeding.
 
+### Happy Path — Brownfield (--here)
+**Input:** "/rcode-scaffold-project --here" or "add rcode to this existing project"
+**Expected:** Detect brownfield mode, use current directory, ask for consent, overlay
+`.rcode/` structure only, never touch existing files, summarize what was added.
+
+### Edge Case — Brownfield, .rcode already exists
+**Input:** `--here` flag but `.rcode/` already present in current dir
+**Expected:** "rcode is already initialized here. Run `/rcode-init` to reconfigure."
+
 ### Negative Test
-**Input:** "scaffold my existing repo" (existing non-empty dir provided)
-**Expected:** Safety check triggers. Never overwrites. Offers alternatives.
+**Input:** "scaffold my existing repo" (existing non-empty dir provided, no --here flag)
+**Expected:** Safety check triggers. Never overwrites. Offers alternatives including
+"Use `--here` mode to add rcode to this existing project instead".

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-01-target.md

@@ -1,14 +1,29 @@
 # Step 1: Target Directory
 
 ## Goal
-Determine the target directory for the new project.
+Determine the target directory and mode (greenfield or brownfield).
 
-## Rules
-- If the user already provided a project name or path when invoking the skill, use it.
+## Brownfield Detection (`--here` flag)
+
+Check whether the user invoked with `--here`, said "scaffold here", "add rcode to
+this project", "initialize rcode here", or any equivalent phrasing.
+
+If **brownfield mode** is detected:
+- Set `{brownfield_mode}` = `true`
+- Set `{target_path}` = current working directory (`pwd`)
+- Set `{project_name}` = basename of current directory
+- Inform the user:
+  > "Brownfield mode — I'll add rcode to the current directory `{target_path}` without touching any existing files."
+- Skip the name prompt and proceed directly to `step-02-safety.md`.
+
+## Greenfield Mode (default)
+
+- If the user already provided a project name or path, use it.
 - If not, ask: **"What should the project be called? I'll create a folder with that name in the current directory."**
 - Accept either a bare name (`my-app`) or a full path (`/home/user/projects/my-app`).
 - If bare name: resolve to `{cwd}/{name}` where `{cwd}` is the directory the user is currently in.
 - Store resolved path as `{target_path}` and project name as `{project_name}`.
+- Set `{brownfield_mode}` = `false`.
 - **Security:** Reject paths containing `..` traversal sequences before proceeding:
   ```bash
   case "{target_path}" in

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-02-safety.md

@@ -3,7 +3,29 @@
 ## Goal
 Ensure the target directory is safe to scaffold into.
 
-## Check: Does the directory exist?
+---
+
+## Brownfield Mode (`{brownfield_mode}` = true)
+
+### Case D — `.rcode/` already exists
+- Check if `{target_path}/.rcode/` already exists.
+- If yes: **STOP.**
+  > "rcode is already initialized in this directory. Run `/rcode-init` to reconfigure, or `/rcode-update` to update skills."
+- Do not proceed further.
+
+### Case E — `.rcode/` does not exist (proceed with consent)
+- Inform the user what will be created:
+  > "I'll add the following to `{target_path}` (existing files will NOT be touched):
+  > - `.rcode/` — rcode config and skills directory
+  > - `.rcode/config.json` — project config (name, language, etc.)
+  >
+  > Shall I proceed?"
+- Wait for explicit confirmation before proceeding.
+- On confirmation: proceed to `step-03-brownfield.md`.
+
+---
+
+## Greenfield Mode (`{brownfield_mode}` = false)
 
 ### Case A — Directory does not exist
 - Safe to proceed.
@@ -17,19 +39,21 @@ Ensure the target directory is safe to scaffold into.
 
 ### Case C — Directory exists and is NOT EMPTY
 - **STOP. Do not touch anything.**
-- Present the user with two options:
+- Present the user with options:
 
   > "The folder `{target_path}` already has files in it. For safety I won't touch it.
   >
   > What would you like to do?
   > **A)** Create a new folder called `{project_name}-new` instead
   > **B)** Give me a different folder name
-  > **C)** Empty the folder yourself first, then tell me when it's ready"
+  > **C)** Empty the folder yourself first, then tell me when it's ready
+  > **D)** Add rcode to this existing project instead (`--here` mode)"
 
 - Wait for user response. Do NOT proceed until user explicitly confirms.
 - If user chooses **A**: set `{target_path}` = `{cwd}/{project_name}-new`, proceed to step-03-clone.md.
 - If user chooses **B**: ask for new name, loop back to step-01-target.md logic.
 - If user chooses **C**: wait. When user says "ready" or "done", re-check the folder. Only proceed if it is now empty.
+- If user chooses **D**: set `{brownfield_mode}` = `true`, proceed to Case E above (brownfield consent).
 
 ## Security Note
 **NEVER delete, move, or modify files in an existing directory.** The user must take that action themselves. This skill only creates new content.

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-03-brownfield.md

@@ -0,0 +1,57 @@
+# Step 3b: Brownfield Initialization
+
+## Goal
+Add rcode structure to an existing project without cloning the template.
+No existing files are ever modified.
+
+## What Gets Created
+
+Only the following paths are written. If any already exist, skip and report:
+
+```
+{target_path}/
+└── .rcode/
+    └── config.json      ← project config (name, language)
+```
+
+## Execution
+
+### 1. Create `.rcode/` directory
+```bash
+mkdir -p "{target_path}/.rcode"
+```
+
+### 2. Write `.rcode/config.json`
+Create with sensible defaults derived from the existing project:
+```json
+{
+  "project_name": "{project_name}",
+  "communication_language": "English",
+  "created_at": "{iso_date}",
+  "mode": "brownfield"
+}
+```
+- Detect language preference from existing README or package.json if present.
+- Set `{iso_date}` from the current date.
+
+### 3. Detect existing project metadata (offer, don't force)
+- If `package.json` exists: read `name` field and offer to use it as `{project_name}` if different.
+- If `README.md` exists: acknowledge it and skip creating a new one.
+
+## Progress Updates
+Narrate each step:
+- "Creating `.rcode/` directory..."
+- "Writing `.rcode/config.json`..."
+- "Done! Proceeding to post-setup..."
+
+## Error Handling
+
+### `.rcode/` creation fails (permissions)
+- Report: "Couldn't create `.rcode/` — check directory permissions."
+- Do NOT retry automatically.
+
+## Output
+Confirm to the user:
+> "rcode structure added to `{target_path}`. No existing files were modified."
+
+Then proceed to `step-04-post-setup.md`.

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-03-clone.md

@@ -1,4 +1,7 @@
-# Step 3: Clone Template
+# Step 3a: Clone Template (Greenfield Only)
+
+> **Brownfield mode:** If `{brownfield_mode}` is `true`, skip this step entirely
+> and proceed to `step-03-brownfield.md` instead.
 
 ## Goal
 Clone the official rcode template repository fresh from GitHub into `{target_path}`.

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/steps/step-04-post-setup.md

@@ -18,8 +18,9 @@ Finalize the scaffolded project and guide the user on next steps.
 - Run only if user confirms.
 
 ### 3. Summary
-Print a clean summary:
+Print a clean summary based on mode:
 
+**Greenfield:**
 ```
 ✅ Project scaffolded successfully!
 
@@ -33,6 +34,19 @@ Next steps:
   pnpm dev           ← to start development server
 ```
 
+**Brownfield (`--here` mode):**
+```
+✅ rcode initialized in existing project!
+
+📁 Location:  {target_path}
+🗂  Added:     .rcode/config.json
+📝 Note:      No existing files were modified.
+
+Next steps:
+  /rcode-init         ← configure rcode for this project
+  /rcode-new-project  ← design project requirements & roadmap
+```
+
 ### 4. Suggest next rcode skills
 Offer relevant follow-up actions:
 > "What would you like to do next?

package/rcode/skills/actions/4-implementation/rcode-trim/SKILL.md

@@ -66,7 +66,7 @@ Do NOT include: changes that touch behaviour; "while I'm here, also..."; trimmin
 
 **Happy path** — A 220-line component with 4 unused props, 2 dead useState hooks, and 30 lines of commented-out exploration code → trim to 140 lines, behaviour unchanged, tests green.
 
-**Edge case — comment that earns its lines** — `// see issue #234 — Postgres pre-13 doesn't return rowCount on UPSERT, so we re-query`. Don't touch it. The comment captures a constraint that won't be obvious from the code alone.
+**Edge case — comment that earns its lines** — `// see the upstream issue — Postgres pre-13 doesn't return rowCount on UPSERT, so we re-query`. Don't touch it. The comment captures a constraint that won't be obvious from the code alone.
 
 **Negative — "simplify by rewriting"** — User asks to "clean up" a working module. If the rewrite is bigger than the cuts, it's not trimming — it's a refactor. Refuse and route to `rcode-incremental` with a real task.
 

package/rcode/workflows/audit-milestone.md

@@ -141,7 +141,7 @@ If `--report` flag set, also print the report to stdout. Otherwise, just save to
 
 ## On Error
 
-If no SUMMARY.md files found, **do not dead-halt** (closes #234). Probe
+If no SUMMARY.md files found, **do not dead-halt**. Probe
 for executed-phase signals and offer recovery options:
 
 ```bash

package/rcode/workflows/discuss-phase.md

@@ -875,7 +875,7 @@ Display banner:
 Context captured. Launching plan...
 ```
 
-Launch plan using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting — see #686):
+Launch plan using the Skill tool to avoid nested Task sessions (which cause runtime freezes due to deep agent nesting):
 ```
 Skill(skill="rcode-plan", args="${PHASE} --auto ${RCODE_WS}")
 ```

package/rcode/workflows/execute-milestone.md

@@ -1,5 +1,5 @@
 <purpose>
-Execute all phases in the current milestone in dependency order, with verify gates between waves. Closes #738.
+Execute all phases in the current milestone in dependency order, with verify gates between waves.
 Reads the ROADMAP.md to determine phase ordering, executes each phase via /rcode-execute, runs /rcode-verify-phase after each, and surfaces blockers before advancing.
 </purpose>
 

package/rcode/workflows/execute-regression-gates.md

@@ -32,6 +32,9 @@ if [ -f "package.json" ]; then
 elif [ -f "Cargo.toml" ]; then
   cargo test 2>&1
 elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+  # Python prerequisites: ensure Python 3.10+ is active (python --version).
+  # Install dependencies (pip install -r requirements.txt or uv sync).
+  # Activate your venv if applicable before running tests.
   python -m pytest ${REGRESSION_FILES} -q --tb=short 2>&1
 fi
 ```

package/rcode/workflows/execute-sprint.md

@@ -17,6 +17,26 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 <process>
 
+<preflight name="dependency_check">
+**Check for uninstalled dependencies:** If a `package.json` exists in the project root but `node_modules/` is absent or empty, emit a WARNING and stop:
+
+```
+⚠ WARNING: package.json found but node_modules/ is missing or empty.
+  Run: pnpm install   (or npm install if pnpm is not available)
+  Then re-run the sprint. Proceeding without installed dependencies will cause task failures.
+```
+
+Do NOT auto-run the install. Emit the message and let the user decide.
+
+```bash
+if [ -f package.json ] && [ ! -d node_modules ] || [ -f package.json ] && [ -z "$(ls -A node_modules 2>/dev/null)" ]; then
+  echo "⚠ WARNING: package.json found but node_modules/ is missing or empty."
+  echo "  Run: pnpm install (or npm install if pnpm is not available)"
+  echo "  Then re-run the sprint."
+fi
+```
+</preflight>
+
 <step name="init_context" priority="first">
 Load execution context (paths only to minimize orchestrator context):
 
@@ -295,6 +315,12 @@ If a commit is BLOCKED by a hook:
 
 After each task (verification passed, done criteria met), commit immediately.
 
+**Preflight — verify git repo exists:**
+```bash
+git rev-parse --git-dir
+```
+If this fails, stop and emit: `No git repository found. Run git init first, then re-run this workflow.`
+
 **1. Check:** `git status --short`
 
 **2. Stage individually** (NEVER `git add .` or `git add -A`):
@@ -350,7 +376,7 @@ If new untracked files appeared after running scripts or tools, decide for each:
 </task_commit>
 
 <post_step_revert_gate>
-## Post-Step Revert Detection Gate (closes #737)
+## Post-Step Revert Detection Gate
 
 After committing each task, run a diff check to detect accidental reverts. This catches the class of bug where a task's implementation unknowingly undoes work from a previous task or wave.
 

package/rcode/workflows/execute-waves.md

@@ -26,6 +26,12 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
          seen_files[file] = plan
    ```
 
+   **Pseudocode quality checklist — apply before implementing any algorithm derived above:**
+   - No bare `except Exception` — catch specific exceptions
+   - No mutation of a collection while iterating over it
+   - Guard against file overwrites (check if path exists before writing)
+   - Validate inputs before processing
+
    **If overlap is detected:**
    - Warn the user:
      ```

package/rcode/workflows/execute.md

@@ -7,12 +7,22 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s
 findings BEFORE any subagents are spawned. If any check fails, stop and
 route back to the user.
 
+0. **Project-status preflight:**
+   ```bash
+   PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || echo uninitialized)
+   ```
+   If `PROJECT_STATUS` is `uninstalled`, `uninitialized`, or `stub`:
+   ```
+   Project not initialized. Run /rcode-init first (or /rcode-new-project for a greenfield project), then return here.
+   ```
+   Stop. Do not proceed until `project-status` returns `real`.
+
 1. **Init state**: `node .rcode/bin/rcode-tools.cjs init execute {N}`
 2. **Phase index**: list all plans via `phase-plan-index {N}` — extract
    plan count, wave count, autonomy flag per plan, files_modified overlaps
 3. **Anti-patterns**: check for `.continue-here.md` (paused state), STATE.md
    error flag, existing VERIFICATION.md with FAIL items without overrides
-4. **Branch check** (issue #659): confirm current git branch is appropriate
+4. **Branch check**: confirm current git branch is appropriate
    for the work. Two checks, both blocking:
 
    a. **Not on main/master without consent**: if `git branch --show-current`
@@ -773,7 +783,7 @@ node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-${PARENT_PHASE}): resolve U
 
 
 <step name="uat_gate" priority="blocker">
-**UAT gate (added in v3.1.0 after #443 / #448):**
+**UAT gate:**
 
 Before marking the phase complete, verify a passing VERIFICATION.md exists for this phase. Without it, the phase advances to `status: executed` (work done, awaiting verification) — not `status: complete`.
 
@@ -822,7 +832,7 @@ fi
 
 **Only when `VERIFICATION_STATUS` is `pass`** — proceed to `update_roadmap` below.
 
-The previous behaviour (printing "Next Up: /rcode-verify-work" without state-gating) caused phases to reach `status: complete` without any human-verified UAT — see #443 for the failure mode.
+The previous behaviour (printing "Next Up: /rcode-verify-work" without state-gating) caused phases to reach `status: complete` without any human-verified UAT.
 </step>
 
 <step name="update_roadmap">

package/rcode/workflows/new-milestone.md

@@ -22,12 +22,12 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 Parse `$ARGUMENTS` before anything else:
 - `--reset-phase-numbers` flag → restart roadmap phase numbering at `1`
 - `--dry-run` flag → show what would be written, do not commit
-- `--from-draft <path>` flag → use an existing MILESTONE-CONTEXT.md or ROADMAP draft as the milestone definition (closes #740). When present, set `DRAFT_FILE=<path>` and `FROM_DRAFT_MODE=true`.
+- `--from-draft <path>` flag → use an existing MILESTONE-CONTEXT.md or ROADMAP draft as the milestone definition. When present, set `DRAFT_FILE=<path>` and `FROM_DRAFT_MODE=true`.
 - Remaining text → milestone name (optional)
 
 If `--from-draft` is absent, continue phase numbering from the previous milestone.
 
-**From-draft mode (closes #740):**
+**From-draft mode:**
 
 When `FROM_DRAFT_MODE=true`:
 1. Read the draft file at `DRAFT_FILE`. Accept any markdown file — MILESTONE-CONTEXT.md, a scratch doc, or a ROADMAP partial.

package/rcode/workflows/new-project.md

@@ -881,6 +881,10 @@ Present completion summary:
 **[N] phases** | **[X] requirements** | Ready to build ✓
 ```
 
+> **Verify before planning:**
+> (a) `.planning/ROADMAP.md` contains real `## Phase N` headings — open it and add them if the file is still a stub.
+> (b) Run `npx rcode state sync --from-disk` to populate `.rcode/state.json` with the phases array so downstream commands (`/rcode-plan`, `/rcode-execute-sprint`, etc.) can read the phase list.
+
 **If auto mode:**
 
 ```

package/rcode/workflows/plan-research-validation.md

@@ -8,7 +8,7 @@ Sub-steps of plan.md — Steps 5 through 5.7. Handles research, validation archi
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
-**If RESEARCH.md missing AND `has_context` is true AND no `--research` flag:** Skip research silently and proceed to step 6. CONTEXT.md already captures the user's design decisions — re-researching adds tokens without new signal. Display: `Research skipped — CONTEXT.md found (use --research to force)`. This closes #588.
+**If RESEARCH.md missing AND `has_context` is true AND no `--research` flag:** Skip research silently and proceed to step 6. CONTEXT.md already captures the user's design decisions — re-researching adds tokens without new signal. Display: `Research skipped — CONTEXT.md found (use --research to force)`.
 
 **If RESEARCH.md missing OR `--research` flag:**
 

package/rcode/workflows/plan-spawn-planner.md

@@ -3,8 +3,8 @@ Sub-step of plan.md — Step 8 Spawn rcode-planner Agent. Spawns rcode-planner w
 </purpose>
 
 <filename_convention>
-Issue #657 — every SPRINT.md, including the first plan in a phase, uses the
-sequence-numbered form `{phase}-{plan}-SPRINT.md` (no leading zeros per #652).
+Every SPRINT.md, including the first plan in a phase, uses the
+sequence-numbered form `{phase}-{plan}-SPRINT.md` (no leading zeros).
 Examples: `8-1-SPRINT.md`, `8-2-SPRINT.md`. Do NOT emit a bare `{phase}-SPRINT.md`
 or `{phase}-PLAN.md` for the first plan — that creates an inconsistent series
 when a second plan is added later. The plan-number computation in plan.md uses