@hanzlaa/rcode 4.0.0 → 4.1.1

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

@@ -111,6 +111,31 @@ Output consumed by /rcode-execute. Plans need:
 - Tasks in XML format with read_first, files, acceptance_criteria, verify (with `<automated>` child), and done fields (MANDATORY on every task)
 - Verification criteria
 - must_haves for goal-backward verification
+- **`## Files Touched`** section (see below) — required on every SPRINT.md
+
+### Required: ## Files Touched Section
+
+Every SPRINT.md must end with a `## Files Touched` section that the planner populates:
+
+```markdown
+## Files Touched
+
+**Creates:**
+- `exact/path/to/new/file.ts` — [one-line responsibility]
+
+**Modifies:**
+- `exact/path/to/existing.ts` — [what changes]
+
+**Tests:**
+- `tests/exact/path/test.ts` — [tests for]
+
+**Aggregator files (append-only):**
+- `packages/shared/src/index.ts` — adds export for Foo, Bar
+```
+
+This section is read by the wave-overlap checker and by human reviewers to quickly audit
+cross-sprint file ownership before merging. If a file appears in `## Files Touched` for two
+plans in the same wave, the later plan must declare `sequential: true`.
 </downstream_consumer>
 
 <deep_work_rules>
@@ -133,6 +158,72 @@ Rules:
 - This map is what informs task decomposition — each task should produce self-contained changes
 - In existing codebases: follow established patterns; only restructure files if a file is genuinely unwieldy and the split is included as its own task
 
+## File-Ownership & Conflict-Avoidance (MANDATORY)
+
+**Evidence from overnight parallel builds (calorie-calculator-ai, 2026-05-26):**
+- Sprints 1-2 and 3-1 both created `diary.py` with divergent content — 3-1's mock-history
+  endpoints were silently lost at merge.
+- Sprints 3-3 and 3-4 both created `HistoryScreen.tsx` — collision required manual triage.
+- Sprints 1-4 and 1-5 both created `CalorieRing`, `MealSlotCard`, and related components.
+- `packages/shared/src/index.ts` was modified by 4 independent sprints — every merge required
+  conflict resolution.
+- Wave-4 executors stubbed missing deps locally while master had an unmerged upstream; the
+  stubs collided with canonical implementations at merge.
+
+### Cross-Sprint File Manifest (produce before task decomposition)
+
+After the File Structure Map, build a cross-sprint ownership table:
+
+```
+CROSS-SPRINT FILE MANIFEST:
+  Sprint 1: creates [path/a.ts, path/b.ts]  modifies [path/c.ts]
+  Sprint 2: creates [path/d.ts]             modifies [path/c.ts]   ← OVERLAP on path/c.ts
+  Sprint 3: creates [path/b.ts]             modifies []             ← COLLISION — b.ts in sprint 1 too
+  ...
+  OWNERSHIP ASSIGNMENTS:
+    path/c.ts — sprint 1 writes canonical, sprint 2 must be sequential_after: 1
+    path/b.ts — DEFECT: only one sprint may create a file; merge or sequence
+```
+
+**Rules:**
+- Only ONE sprint may _create_ a given file. Two sprints creating the same file is a plan defect — either merge the tasks into one sprint or sequence them and have the later sprint extend (not recreate).
+- If two sprints in the same wave both _modify_ the same file, the later sprint MUST have `sequential: true` and `sequential_after: <earlier_sprint_id>` in its frontmatter.
+- Frontmatter `files_modified:` must list ALL files from `<files>` blocks — this is the source-of-truth for the executor's intra-wave overlap checker.
+
+### Aggregator-File Rule
+
+These files are known aggregators — multiple sprints always want to add to them:
+
+| Pattern | Examples |
+|---------|---------|
+| Barrel exports | `**/index.ts`, `**/index.tsx` |
+| State store | `**/store/index.ts`, `**/store/index.js` |
+| Types barrel | `**/types/index.ts`, `**/types.ts` |
+| Python entrypoints | `main.py`, `app.py`, `router/__init__.py`, `**/__init__.py` |
+| Package manifest | `package.json` (scripts / deps blocks) |
+
+**Hard rule:** For aggregator files, the `<action>` block MUST say:
+
+> "Append to existing exports — do NOT overwrite or replace the full file. Use `Edit`
+> (old_string / new_string) with a targeted insertion. Preserve all existing content."
+
+Never use `Write` on an aggregator file in a plan that other sprints also touch.
+
+### Verify-Command Accuracy
+
+In every `<verify><automated>` block, prefer `pnpm run <script>` over raw tool invocations
+to avoid the mismatch where the planner writes `tsc --noEmit` but the project calls it `type-check`:
+
+| Raw invocation (avoid) | pnpm script form (prefer) |
+|------------------------|--------------------------|
+| `tsc --noEmit` | `pnpm run type-check` or `pnpm run typecheck` |
+| `eslint .` | `pnpm run lint` |
+| `jest` / `vitest` | `pnpm run test` |
+| `python -m pytest` | check `pyproject.toml` for script alias |
+
+Check `package.json` scripts before writing a verify command. If `package.json` is not yet
+read, add it to `<read_first>` for any task that writes a verify command.
+
 ## No-Placeholders Rule (HARD BLOCKER)
 
 Every step must contain the actual content the executor needs. These are **plan failures** — never write them:
@@ -217,9 +308,14 @@ Every task MUST include these fields — they are NOT optional:
 
 <quality_gate>
 - [ ] File structure map written before first task (files_to_create / files_to_modify / files_for_tests)
+- [ ] Cross-sprint file manifest built — no file in 2+ same-wave sprints without `sequential: true`
+- [ ] No file created by more than one sprint (creation collision = plan defect)
+- [ ] Aggregator files (index.ts, __init__.py, main.py, package.json, etc.) use append-only `Edit`, not `Write`
+- [ ] Verify commands use `pnpm run <script>` not raw tool invocations (tsc, eslint, jest)
 - [ ] No placeholder patterns: no TBD/TODO/implement-later, no "similar to Task N", no code steps without code
 - [ ] SPRINT.md files created in phase directory
 - [ ] Each plan has valid frontmatter including `files_modified:` array aggregating all `<files>` paths across tasks (consumed by execute.md intra-wave overlap checker)
+- [ ] Each plan's `## Files Touched` section populated with create/modify/test lists
 - [ ] Tasks are specific and actionable
 - [ ] Every task has `<read_first>` with at least the file being modified
 - [ ] Every task has `<files>` listing exact files this task will modify or create

package/rcode/workflows/plan.md

@@ -460,6 +460,73 @@ Proceed to Step 8 only if user selects 2 or 3.
 
 @.rcode/workflows/plan-spawn-planner.md
 
+## 8.5. File-Ownership & Conflict-Avoidance
+
+After the planner returns SPRINT.md files, run these checks before advancing to step 9.
+These rules were added after overnight parallel builds exposed silent merge-time data loss
+(calorie-calculator-ai, 2026-05-26). The wave-overlap CLI check in step 12.5 catches
+same-wave/same-file issues mechanically; this step catches plan-level ownership gaps earlier.
+
+**Step 1 — Build the cross-sprint file manifest.**
+
+Read each SPRINT.md produced this run and collect its `files_modified:` frontmatter list.
+Produce a de-duplicated map: `file → [sprint_ids that touch it]`.
+
+```bash
+# Quick grep of frontmatter to build the manifest
+grep -A 50 "^files_modified:" "${PHASE_DIR}"/*-SPRINT.md 2>/dev/null
+```
+
+**Step 2 — Flag collisions.**
+
+For each file that appears in 2+ sprint lists:
+
+| Type | Rule |
+|------|------|
+| Two sprints **create** the same file | Plan defect — merge tasks or sequence; only one sprint may create a file |
+| Two same-wave sprints **modify** the same file | Later sprint MUST have `sequential: true` + `sequential_after:` in frontmatter |
+| An aggregator file touched by multiple sprints | Each sprint's `<action>` must use append-only `Edit`, not `Write` |
+
+Aggregator patterns (known high-collision targets):
+- `**/index.ts`, `**/index.tsx` (barrel exports)
+- `**/store/index.ts`, `**/store/index.js`
+- `**/types/index.ts`, `**/types.ts`
+- `main.py`, `app.py`, `router/__init__.py`, `**/__init__.py`
+- `package.json` (scripts / deps blocks)
+
+**Step 3 — Verify-command accuracy.**
+
+Scan every `<verify><automated>` block for raw tool invocations (`tsc --noEmit`, `eslint .`,
+`jest`, `vitest`). If found, check `package.json` scripts and replace with the `pnpm run <script>`
+equivalent. Mismatch example from overnight build: plan wrote `tsc --noEmit` but the project's
+script was named `type-check`.
+
+**Step 4 — Report and gate.**
+
+If any creation collision found → **BLOCK plan acceptance**. Edit the colliding sprint to remove
+the duplicate creation task (have the second sprint import/extend from the first sprint's output).
+
+If any modify-collision found in the same wave → edit the later sprint's frontmatter immediately:
+```yaml
+sequential: true
+sequential_after: <earlier_sprint_id>
+conflicting_files: [<shared_files...>]
+```
+
+Display a summary:
+```
+File-Ownership Check:
+  ✓ N files with single owner
+  ⚠ M aggregator files — append-only instructions verified
+  ✗ K creation collisions (blocked — fixed inline)
+  ~ J sequential flags added
+```
+
+If no issues: `File-Ownership Check: ✓ no collisions.`
+
+**This check is informational for warnings and blocking for creation collisions.**
+It never silently passes a plan where two sprints create the same file.
+
 ## 9. Handle Planner Return
 
 - **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.

package/rcode/workflows/retrospective.md

@@ -9,7 +9,11 @@ Run an epic retrospective and produce owned action items. Delegates to the rcode
 Locate and follow the installed skill:
 
 ```bash
-find .rcode/skills/actions -path "*rcode-retrospective/workflow.md" 2>/dev/null | head -1
+if [ -f .rcode/skills/rcode-retrospective/workflow.md ]; then
+  printf '%s\n' ".rcode/skills/rcode-retrospective/workflow.md"
+else
+  find .rcode/skills/actions -path "*rcode-retrospective/workflow.md" 2>/dev/null | head -1
+fi
 ```
 
 Read and follow the workflow at that path. If the path is empty:

package/rcode/workflows/sprint-planning.md

@@ -14,8 +14,9 @@ back to the in-line implementation.
 
 <delegate_to_skill>
 Required skill: `rcode-sprint-planning`
-Path:           `.claude/skills/rcode-sprint-planning/SKILL.md`
-Workflow ref:   `.claude/skills/rcode-sprint-planning/workflow.md`
+Path:           `.rcode/skills/rcode-sprint-planning/SKILL.md`
+Workflow ref:   `.rcode/skills/rcode-sprint-planning/workflow.md`
+Fallback path:  `.claude/skills/rcode-sprint-planning/SKILL.md`
 
 Behaviour:
 1. Load the skill's `SKILL.md` and `workflow.md`. Apply every Critical
@@ -99,8 +100,9 @@ Exit.
 - Commit max 80% of average (buffer for interrupts + unknowns)
 
 **If no velocity history (first sprint):**
-- Ask user: "This is your first sprint. How many story points can you commit to? (Typical: 8-13 for solo dev + AI)"
-- Or use `--velocity` flag
+- If `--velocity <N>` flag was supplied, use that value directly and skip the prompt.
+- If `mode == "yolo"` (config) and no `--velocity` flag, default to 10 points and proceed.
+- Otherwise ask user: "This is your first sprint. How many story points can you commit to? (Typical: 8-13 for solo dev + AI)"
 
 Store as `velocity_target`.
 
@@ -127,7 +129,9 @@ Present story table to user:
 **Capacity check:** Total committed points <= velocity_target.
 If over: "We're at {N} points vs {target} capacity. Move story #{X} to next sprint?"
 
-Wait for user confirmation before proceeding.
+**Automation escape:** if `mode == "yolo"` or `--auto` flag was passed, skip the
+confirmation; automatically move lowest-priority over-capacity stories to backlog
+and proceed. Otherwise wait for user confirmation before proceeding.
 
 ## Step 4 — Create sprint
 

package/server/dashboard.js

@@ -17,7 +17,7 @@
  *   server/lib/html/client.js    - Client-side JS (routing, rendering, etc.)
  *
  * Run: node server/dashboard.js
- * Stop: kill $(lsof -t -i:7717)
+ * Stop: kill $(ss -ltnp 'sport = :7717' | awk 'NR>1{match($6,/pid=([0-9]+)/,m); print m[1]}')
  */
 
 const http    = require('http');
@@ -145,7 +145,7 @@ server.listen(PORT, '127.0.0.1', () => {
   console.log(`   Scanning:   ${RCODE_DIR}`);
   console.log(`   Refresh:    30s soft poll`);
   console.log(`   Keys:       R=refresh  1-9=views  F=filter`);
-  console.log(`   Stop:       kill $(lsof -t -i:${PORT})`);
+  console.log(`   Stop:       kill $(ss -ltnp 'sport = :${PORT}' | awk 'NR>1{match($6,/pid=([0-9]+)/,m); print m[1]}')`);
   console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 });