@hanzlaa/rcode 4.1.1 → 4.1.2

package/rcode/workflows/plan.md

@@ -64,6 +64,20 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 <process>
 
+## 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. Initialize
 
 Load all context in one call (paths only to minimize orchestrator context):
@@ -117,7 +131,7 @@ fi
 
 When `GAPS_MODE=true`, the workflow switches to **gap-closure planning**: read the phase's VERIFICATION.md, extract verification gaps classified `gap_found` or `partial`, and produce a single new numbered plan file (`NNN-NN-SPRINT.md`) that closes them. Research, CONTEXT.md gating, and VALIDATION.md creation are skipped — gaps are grounded in already-shipped code, not new design work.
 
-**Detect from-stub mode (closes #736):**
+**Detect from-stub mode:**
 ```bash
 if [[ "$ARGUMENTS" =~ (^|[[:space:]])--from-stub($|[[:space:]]) ]]; then
   FROM_STUB_MODE=true
@@ -154,7 +168,7 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
 
 **Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
 
-**TASKS.md ingestion (#385 chain).** If the phase directory contains a `TASKS.md` file (typically auto-extracted by `/rcode-add-phase` from a bulk `/rcode-quick` or `/rcode-do` route), read it now:
+**TASKS.md ingestion.** If the phase directory contains a `TASKS.md` file (typically auto-extracted by `/rcode-add-phase` from a bulk `/rcode-quick` or `/rcode-do` route), read it now:
 
 ```bash
 TASKS_FILE=".planning/phases/${padded_phase}-${phase_slug}/TASKS.md"
@@ -187,6 +201,12 @@ Exit workflow.
 ## 3. Validate Phase
 
 ```bash
+# Stub-ROADMAP guard — emit a warning if ROADMAP.md has no real phase headings.
+ROADMAP_PHASE_COUNT=$(grep -c "^## Phase " "${ROADMAP_PATH}" 2>/dev/null || echo 0)
+if [ "${ROADMAP_PHASE_COUNT}" -eq 0 ]; then
+  echo "⚠ WARN: ROADMAP.md appears to be a stub — add real ## Phase headings before running plan."
+  exit 1
+fi
 PHASE_INFO=$(node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "${PHASE}")
 ```
 
@@ -326,7 +346,7 @@ Otherwise use AskUserQuestion:
 If "Continue without context": Proceed to step 5.
 If "Run discuss-phase first":
   **IMPORTANT:** Do NOT invoke discuss-phase as a nested Skill/Task call — AskUserQuestion
-  does not work correctly in nested subcontexts (#1009). Instead, display the command
+  does not work correctly in nested subcontexts. Instead, display the command
   and exit so the user runs it as a top-level command:
   ```
   Run this command first, then re-run /rcode-plan {X} ${RCODE_WS}:
@@ -362,7 +382,7 @@ Always offer exactly three numbered options:
 
 Wait for the user's choice before proceeding. Do not auto-select.
 
-**If user picks option 1 (Add more plans) — issue #650:**
+**If user picks option 1 (Add more plans):**
 
 This is **NOT** a license to hand-write a new SPRINT.md inline. Continue down the
 normal pipeline exactly as if no plans existed yet:
@@ -376,8 +396,7 @@ normal pipeline exactly as if no plans existed yet:
    first-time plan. The "PLANNED ✓" banner is gated on a passing CHECK.md.
 
 A run that emits a SPRINT.md without a corresponding planner Task() invocation
-in the same turn is a malfunction — see issue #650. Stop and report instead of
-shipping a hand-rolled plan.
+in the same turn is a malfunction. Stop and report instead of shipping a hand-rolled plan.
 
 **If user picks option 3 (Replan from scratch):**
 
@@ -390,7 +409,7 @@ still mandatory.
 
 Display a sprint summary table (sprint id → one-line goal).
 
-Then run a **best-effort codebase overlap check** before showing the execute prompt — Closes #596.
+Then run a **best-effort codebase overlap check** before showing the execute prompt.
 
 **This check is always informational. It never blocks, never errors, never fails the workflow.** If any step below cannot complete for any reason, skip it silently and proceed straight to the execute prompt.
 
@@ -534,7 +553,7 @@ It never silently passes a plan where two sprints create the same file.
 - **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
 - **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
 
-**Sprint count guard (token cost protection — closes #584):**
+**Sprint count guard (token cost protection):**
 
 After planner returns `## PLANNING COMPLETE`, immediately count sprint files:
 
@@ -670,7 +689,7 @@ If thinking_partner disabled: skip this block entirely.
 
 ## 12. Revision Loop (Max 3 Iterations, 1 in autonomous/yolo mode)
 
-**Mode-based iteration cap (token cost protection — closes #585):**
+**Mode-based iteration cap (token cost protection):**
 
 ```bash
 MAX_ITERATIONS=$($TOOL config-get workflow.max_checker_iterations 2>/dev/null || echo "")
@@ -686,7 +705,7 @@ Track `stall_reentry_count` (starts at 0; incremented each time "Adjust approach
 
 **If iteration_count < MAX_ITERATIONS:**
 
-**Sprint-checker malfunction guard (BLOCKER-class — added in v3.1.0 after #440):**
+**Sprint-checker malfunction guard (BLOCKER-class):**
 
 Before parsing issues, verify the checker actually invoked tools. The checker MUST exhibit at least one of these evidence markers in its return:
 
@@ -695,11 +714,11 @@ Before parsing issues, verify the checker actually invoked tools. The checker MU
 - At least one `path:` field in any block (e.g. `path: src/components/Foo.tsx:42`)
 - A summary line of the form `Verified N of M files` or `Checked N symbols`
 
-If NONE of these evidence markers are present, the checker malfunctioned (returned narrative without invoking tools — see #440). BLOCK execution:
+If NONE of these evidence markers are present, the checker malfunctioned (returned narrative without invoking tools). BLOCK execution:
 
 ```
 Display: "Sprint-checker returned without evidence of tool use — likely
-         malfunctioned (cf. issue #440). Refusing to advance the plan
+         malfunctioned (returned narrative without tool use). Refusing to advance the plan
          on unverified output. Re-run /rcode-plan or inspect the agent."
 Halt the workflow with a non-zero exit signal.
 ```
@@ -771,7 +790,7 @@ Display: `Max iterations reached. {N} issues remain:` + issue list
 
 Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
-## 12.5. Wave Parallelism File-Overlap Check (added in v3.1.0 after #442)
+## 12.5. Wave Parallelism File-Overlap Check
 
 Before declaring plans ready, validate the wave-parallelism rule the planner declares: **same wave + overlapping `files_modified` = sequential, not parallel**. If two plans share `depends_on` (same wave) and both list the same file in `files_modified`, the planner should have marked the later one `sequential: true`. Catch the cases where it didn't.
 
@@ -814,7 +833,7 @@ The CLI helper returns a JSON report:
 
 **If `conflicts` is empty:** Display `Wave parallelism: ✓ no file-overlap conflicts.` and proceed.
 
-This closes the gap from #442 — the rule was stated in `rcode-planner.md` but not enforced. Now it's enforced automatically.
+This closes the wave-overlap gap — the rule was stated in `rcode-planner.md` but not enforced. Now it's enforced automatically.
 
 ## 13. Requirements Coverage Gate
 
@@ -948,7 +967,7 @@ Route to `<offer_next>` (existing behavior).
 </process>
 
 <banner_emission_gate>
-Issue #655 — the success banner is gated on real verification, not vibes.
+The success banner is gated on real verification, not vibes.
 Before emitting `PLANNED ✓`, confirm one of these is true:
 
 1. A passing CHECK.md exists at `${PHASE_DIR}/*-CHECK.md` from rcode-sprint-checker

package/rcode/workflows/review.md

@@ -82,6 +82,8 @@ Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is va
 
 Read from init: `phase_dir`, `phase_number`, `padded_phase`.
 
+If `phase_dir` is null or empty, STOP and tell the user: "Phase directory not found on disk. Create the phase directory under `.planning/phases/` first (e.g. `mkdir -p .planning/phases/1-name`), then re-run."
+
 Then read:
 1. `.planning/PROJECT.md` (first 80 lines — project context)
 2. Phase section from `.planning/ROADMAP.md`

package/rcode/workflows/scaffold-project.md

@@ -1,7 +1,11 @@
 # Workflow: rcode-scaffold-project
 
 <purpose>
-Scaffold a new project from the official rcode template repo. Delegates to the rcode-scaffold-project skill.
+Scaffold a new project from the official rcode template repo, or initialize rcode
+in an existing project (brownfield mode). Delegates to the rcode-scaffold-project skill.
+
+Use `--here` (or say "scaffold here") to add rcode to an existing directory without
+cloning the template. Existing files are never modified in brownfield mode.
 </purpose>
 
 ## Execution

package/rcode/workflows/session-report.md

@@ -79,7 +79,7 @@ Extract counts:
 
 ### Step 5a — Prefer measured totals from cost.jsonl
 
-If the `cost-track` hook (#745) is enabled, it appends one usage record per
+If the `cost-track` hook is enabled, it appends one usage record per
 response to `.rcode/telemetry/cost.jsonl`. Check for it first:
 
 ```bash

package/rcode/workflows/ship.md

@@ -34,6 +34,45 @@ the plan → execute → verify → **ship** loop.
 ```
 </purpose>
 
+<prerequisites>
+
+**Required before running `/rcode-ship`:**
+
+1. **Git remote configured** — `git remote -v` must list at least one remote (typically `origin`). Without a remote, the push and PR steps will fail.
+2. **`gh` CLI authenticated** — `gh auth status` must succeed. Without this, PR creation will fail.
+3. **Clean working tree** — no uncommitted changes (`git status --short` returns nothing).
+4. **On a feature branch** — not on `main` or `develop` directly.
+5. **Verification passed** — `/rcode-verify-phase <phase>` must have run and produced a VERIFICATION.md with `status: passed`.
+
+</prerequisites>
+
+<warning>
+
+**If your workspace has no git remote or `gh` is not authenticated, the push and PR steps will fail.**
+
+Check before running:
+```bash
+git remote -v          # must list at least one remote
+gh auth status         # must exit 0
+```
+
+**Manual fallbacks if these are missing:**
+
+- **No remote:** Add one with `git remote add origin <repo-url>`, then re-run `/rcode-ship`. Or push manually:
+  ```bash
+  git push origin <branch>
+  ```
+  Then open a PR via the GitHub web UI at `https://github.com/<owner>/<repo>/compare/<branch>`.
+
+- **`gh` not authenticated:** Run `gh auth login` to authenticate, then re-run `/rcode-ship`. Or create the PR directly at:
+  ```
+  https://github.com/<owner>/<repo>/compare/<branch>
+  ```
+
+- **Git worktree context:** If `.git` is a file (not a directory), you are in a worktree. Remotes are shared with the main repo — run `git remote -v` from the main repo root to verify. If the main repo has `origin`, the worktree inherits it automatically.
+
+</warning>
+
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>

package/rcode/workflows/sprint-planning.md

@@ -73,6 +73,33 @@ If `$ARGUMENTS` contains `--help` or `-h`:
 
 STOP — do not proceed.
 
+## Preflight — Project-status check
+
+```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`.
+
+## Preflight — Dependency check
+
+If a `package.json` exists in the project root but `node_modules/` is absent or empty, emit a WARNING before planning begins:
+
+```
+⚠ WARNING: package.json found but node_modules/ is missing or empty.
+  Run: pnpm install   (or npm install if pnpm is not available)
+  Sprint planning can continue, but the resulting sprint tasks will fail at execution time
+  unless dependencies are installed first.
+```
+
+Do NOT auto-run the install. Emit the message and let the user decide.
+
 ## Step 1 — Load context
 
 ```bash

package/rcode/workflows/status.md

@@ -1,7 +1,7 @@
 # Workflow: rcode-status
 
 <purpose>
-Render a human-readable project status dashboard. All data comes from a single `rcode-tools progress init` call — this workflow does NOT parse ROADMAP.md, walk SUMMARY.md files, or grep state.json itself. Rendering only. See `rcode-tools.cjs` `cmdProgress` for the source-of-truth logic (issue #159 M2.5).
+Render a human-readable project status dashboard. All data comes from a single `rcode-tools progress init` call — this workflow does NOT parse ROADMAP.md, walk SUMMARY.md files, or grep state.json itself. Rendering only. See `rcode-tools.cjs` `cmdProgress` for the source-of-truth logic.
 
 **SSOT:** `.rcode/state.json`. `/rcode-status` and `/rcode-progress` both call the same CLI so they cannot disagree. If the CLI reports a drift insight, surface it — do not silently compensate.
 </purpose>
@@ -53,7 +53,7 @@ Then stop.
 If `SNAPSHOT.weighted_progress > 0` but `SNAPSHOT.completed_count === 0`, display
 the weighted bar as the primary progress indicator to avoid a misleading `0/N (0%)`.
 
-### Milestone health (issue #718)
+### Milestone health
 
 After the main dashboard, call `rcode-tools milestone-health` and surface
 a gauge when the milestone is full:
@@ -108,7 +108,7 @@ Phases:
 
 If a phase number starts with `999.`, render with a `🅿` marker and the label `(parking lot)`.
 
-## Step 4 — Insights (NEW — issue #159)
+## Step 4 — Insights
 
 If `SNAPSHOT.insights[]` is non-empty, print above the Next Up section: