@hanzlaa/rcode 4.0.0 → 4.1.0

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/templates/wave-prompt.md

@@ -0,0 +1,69 @@
+# Wave-Agent Prompt Template
+
+Use this as the body of `herdr pane send-text` when dispatching each agent in a wave. Replace the placeholders.
+
+---
+
+```
+You are in an isolated worktree at <WORKTREE_PATH> on branch <BRANCH_NAME>. <REPO_NAME> repo.
+
+YOUR PARENT BRANCH IS <INTEGRATION_BRANCH> (NOT master). Your branch was forked from <INTEGRATION_BRANCH>. When you finish, the orchestrator will merge your branch INTO <INTEGRATION_BRANCH> (not master). Master stays untouched throughout the campaign.
+
+If you need to pull the latest parent work (rare, only between waves):
+  git fetch origin
+  git merge origin/<INTEGRATION_BRANCH> --no-edit
+
+CAMPAIGN MODE — pick top 3-5 pending P1/P2 items from <AUDIT_DOC_PATH> and ship them. Long-running autonomous fix campaign — your branch will be merged into the campaign integration branch when done.
+
+PROTOCOL
+1. Read <AUDIT_DOC_PATH> fully. Identify items marked pending, ⏳, [ ], TODO, or labeled P1/P2 that are NOT already shipped (cross-reference `git log <INTEGRATION_BRANCH>` to avoid double-fixing).
+2. Pick 3-5 items that are surgical, well-scoped, and unrelated to other in-flight campaign agents (no overlap with: <IN_FLIGHT_AREAS>).
+3. Implement each item as a small, separately-committed change. Conventional commit format (e.g. `fix(area): summary` / `feat(area): summary`). Each commit message must reference the audit finding.
+4. STRICT auto-heal from project CLAUDE.md while editing:
+   - super_admin in role filters
+   - no silent .catch(()=>{}) — use logger.warn with reason
+   - no React.FC, no style={{}}, no raw <button> (use Button component)
+   - no alert()/confirm() — use toast/AlertDialog
+   - Prisma schema changes need migration files via `prisma migrate dev --create-only --name <slug>`
+   - new /api routes need server/middleware/routeSecurity.js MANIFEST entries
+5. Keep TSC at baseline. Run `pnpm tsc --noEmit` before final commit. If you introduce a NEW error, fix it before committing.
+6. STAY on branch <BRANCH_NAME>. Do NOT push. Do NOT merge to master. Do NOT merge to <INTEGRATION_BRANCH>. Do NOT touch other audit areas.
+7. End with a short numbered summary listing each commit (hash + one-line message) and what audit item it addressed.
+
+DO NOT
+- Touch master at all
+- Merge into the integration branch (the orchestrator does that — your job is to commit on your own branch and stop)
+- Touch out-of-scope code outside the audit area
+- Add new abstractions or refactor wholesale
+- Make schema changes without a migration file
+- Write tests "as a bonus" unless the audit specifically called for them
+- Push to origin
+
+Begin by reading the audit doc and listing the candidate items you'll fix.
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Source |
+|---|---|
+| `<WORKTREE_PATH>` | `../sm-worktrees/camp-<area>` |
+| `<BRANCH_NAME>` | `campaign-<area>` |
+| `<INTEGRATION_BRANCH>` | `campaign-integration` (default) or `campaign-<topic>` for named campaigns |
+| `<REPO_NAME>` | e.g. `LeadLyze` |
+| `<AUDIT_DOC_PATH>` | `.planning/audits/AUDIT-<area>.md` |
+| `<IN_FLIGHT_AREAS>` | Comma-list from STATE.md |
+
+## When to deviate from this template
+- **Heavy schema work**: add explicit migration-naming guidance and require `prisma migrate diff` review before commit.
+- **Pure UI/CSS area**: drop the routeSecurity MANIFEST bullet, add "use design tokens not hex codes".
+- **Authentication / RBAC area**: add "no role-relation rename without checking every call site; super_admin always included".
+
+## Related templates
+- `BACKLOG-template.md` — initial backlog format
+- `heartbeat.sh` — secondary heartbeat process
+
+## Related rules
+- `rules/integration-branch.md` — why the parent branch is `<INTEGRATION_BRANCH>` and not master
+- `rules/merge-strategy.md` — what happens after sub-agent commits land on the branch

package/rcode/templates/sprint.md

@@ -35,6 +35,22 @@
 | Risk | Impact | Mitigation |
 |------|--------|------------|
 
+## Files Touched
+
+<!-- Planner must populate before handoff to executor. Used by wave-overlap checker and merge reviewers. -->
+
+**Creates:**
+<!-- - `exact/path/new-file.ts` — one-line responsibility -->
+
+**Modifies:**
+<!-- - `exact/path/existing.ts` — what changes -->
+
+**Tests:**
+<!-- - `tests/exact/path/test.ts` — tests for -->
+
+**Aggregator files (append-only — never replace):**
+<!-- - `packages/shared/src/index.ts` — adds export for X -->
+
 ## Sprint Review
 
 <!-- Fill at sprint completion only — omit this section until then -->

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/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`);
 });