npm - @hanzlaa/rcode - Versions diffs - 3.6.16 → 4.1.0 - Mend

@hanzlaa/rcode 3.6.16 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1493) hide show

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

@@ -0,0 +1,93 @@
+---
+name: rcode-git-flow
+internal: true
+description: Branching, commits, conflicts, parallel work — aligned with the rcode Epic→Feature→Task hierarchy.
+triggers:
+  - "git flow"
+  - "branching strategy"
+  - "open a pr"
+  - "merge conflict"
+  - "rebase or merge"
+  - "feature branch"
+  - "commit policy"
+  - "branch from main"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+## Overview
+The rcode git workflow: feature branches off main, Conventional Commits, PRs that close issues with `Closes #N`, no force-push to main, no AI attribution in commit messages. Aligned with the Epic→Feature→Task hierarchy in `GITHUB_WORKFLOW.md` so every branch traces back to an issue.
+## Branching
+- **`main`** — always green. CI must pass. Never force-pushed.
+- **`feature/<short-slug>`** — branched from latest `main` for new work.
+- **`fix/<issue-N>-<slug>`** — branched from `main` for bug fixes; one branch per issue.
+- **`docs/<short-slug>`** — branched from `main` for doc-only changes.
+Naming: kebab-case slug, ≤40 chars after the prefix.
+## Commit policy
+- **Conventional Commits:** `type(scope): subject`
+- **Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
+- **Scopes:** see `AGENTS.md` for the allow-list (`agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, etc.)
+- **Subject:** lowercase first letter, imperative mood, no trailing period, ≤72 chars
+- **Body:** explain the WHY (the diff shows the WHAT)
+- **Footer:** `Closes #N` for the issue this commit completes
+- **Forbidden:** AI attribution lines (`Co-Authored-By: Claude`, "Generated with..."). User does not want this.
+- **Forbidden:** `--no-verify` to skip hooks. Fix the underlying issue.
+- **Forbidden:** `git add -A` or `git add .` without reading the staged set first.
+## Workflow
+1. **Sync.** `git pull --rebase origin main` before starting any new work.
+2. **Branch.** `git checkout -b feature/<slug>` from latest main.
+3. **Commit small.** One logical change per commit. Run tests before committing.
+4. **Push the branch.** **`git push origin <branch>`** requires user authorization (see `AGENTS.md` push policy). Never push to main directly.
+5. **Open the PR.** `gh pr create --base main --title "<conventional-commits subject>" --body "<body>"`. Body links the issue: `Closes #N`.
+6. **Review cycle.** Address feedback as additional commits (don't rewrite history once the PR is open).
+7. **Merge.** Squash-merge by default; preserve commit history only when the chain is meaningful (rare). After merge: `git checkout main && git pull && git branch -d <branch>`.
+## Conflict resolution
+1. Don't reflexively `git pull --rebase` mid-PR. First read both sides.
+2. Use `git mergetool` or your IDE's conflict UI — manual `<<<<<<<` editing is error-prone.
+3. After resolving: run the full test suite. Conflicts often hide behavioural overlaps the tests catch.
+4. Commit message: `merge: resolve conflicts with main` (chore-type, no scope needed).
+## Output Format
+For a new feature:
+```
+Branch: feature/<slug>   (from latest main)
+Issue: #N — <title>
+Commit plan:
+  1. <conventional commit subject>
+  2. <conventional commit subject>
+  ...
+PR title: <type>(<scope>): <subject>
+PR body footer: Closes #N
+Push approval required at: branch push, PR open, post-review push (each separately).
+```
+Do NOT include: force-pushes to main; commits with AI attribution; bundled commits ("feat: do everything").
+## 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.
+**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.
+**Negative — pushing to main** — User asks "just push it to main". Refuse — feature branches + PRs are non-negotiable per `AGENTS.md`. Open a PR even for a one-line fix.
+## Memory Bank Hooks
+- **Reads:** `.rcode/memory/project/decisions.md` (so prior branching decisions are loaded)
+- **Writes:** none directly — the skill drives git, not Memory Bank state

package/rcode/skills/actions/4-implementation/rcode-harden/SKILL.md ADDED Viewed

@@ -0,0 +1,98 @@
+---
+name: rcode-harden
+internal: true
+description: Security hardening checklist for SaaS applications.
+triggers:
+  - "harden this"
+  - "security check"
+  - "auth audit"
+  - "tenant isolation"
+  - "keycloak ad sync"
+  - "secure this endpoint"
+  - "owasp"
+  - "before we ship"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+## Overview
+Pre-launch security pass for SaaS code. Not a generic OWASP checklist — opinionated for the rcode-default stack (Next.js / Strapi / Postgres / Keycloak / Sentry). Especially focused on the failure modes that have actually bitten rcode projects: Keycloak ↔ AD sync drift, multi-tenant query leaks, and JWT-as-source-of-truth bugs.
+## Workflow
+1. **Map the attack surface.** List every endpoint, file upload, third-party webhook, and background job. If you can't enumerate them, you can't audit them.
+2. **Per surface, run the checklist** below.
+3. **Triage findings:** Critical (block launch), High (fix before next sprint), Medium (track in `incidents/known-issues.md`).
+4. **Verify fixes** end-to-end — most security bugs are caught by writing the malicious test case, not by code review alone.
+## Checklist (applied per surface)
+### Authentication
+- JWT verified on every request, not just `POST /login`. The token can be forged otherwise.
+- Issuer (`iss`), audience (`aud`), expiry (`exp`), and signature all checked. Missing any one is a compromise.
+- For Keycloak: re-fetch the JWKS keys, don't pin them — Keycloak rotates.
+- AD sync: every Keycloak login should re-validate the user against AD; stale Keycloak users post-AD-deactivation is the documented rcode incident.
+- Session invalidation on password change actually clears all sessions, not just the current one.
+### Authorization
+- Role checks AT the resource handler, not in the URL or query layer.
+- Tenant isolation: every query that reads tenant data MUST filter by tenant_id derived from the JWT, never from a request parameter.
+- "Admin" routes require role check + audit log write, in that order.
+### Input validation
+- All request bodies validated at the boundary (zod / joi / strapi schema).
+- File uploads: MIME-sniff the content, don't trust `Content-Type`; cap size; quarantine before processing.
+- Path parameters: reject `..`, absolute paths, and URL-encoded variants.
+### Data handling
+- Secrets in env vars, not in code. CI scans for committed secrets.
+- PII redacted from logs and Sentry breadcrumbs (`beforeSend` filter).
+- Encryption at rest on Postgres for any table holding government-sensitive data.
+### External integrations
+- Webhook signatures verified on receipt; replay-attack window enforced (timestamp + nonce).
+- Outbound API calls have a timeout; no infinite waits.
+- Third-party SDKs pinned to a known-good version; renovate-bot PRs reviewed manually.
+## Output Format
+```
+Surfaces audited: <count>
+Critical (block launch):
+  ✗ <surface> — <issue> — <exploit path>
+High (fix this sprint):
+  ⚠ <surface> — <issue>
+Medium (track):
+  · <surface> — <issue>
+Memory Bank update:
+  → wrote <count> entries to .rcode/memory/incidents/known-issues.md
+  → wrote audit summary to .rcode/memory/change-records/<date>-001.md
+```
+## Examples
+**Happy path** — Pre-launch audit of a tenant-isolated dashboard → finds 2 queries missing `WHERE tenant_id = $1` (CRITICAL) → 1 webhook missing signature check (HIGH) → 3 medium findings. Block launch until critical findings fixed; reaudit.
+**Edge case — Keycloak ↔ AD drift** — User deactivated in AD but their Keycloak token still works for 24h. Add: validate-against-AD step at every login + 5-minute Keycloak token TTL.
+**Negative — "we'll add security later"** — Refuse. Security retrofits are 10× the cost of building it in. Block until at least the Critical findings have a plan.
+## When NOT to use this skill
+Do NOT use this skill for CI/CD setup (use rcode-ci), performance optimization (use rcode-perf), general code review (use rcode-review), or MVP-to-production migration (use rcode-migrate).
+## Memory Bank Hooks
+- **Reads:** `.rcode/memory/project/stack.md` (auth layer detection), `.rcode/memory/incidents/post-mortems/` (prior auth/security incidents)
+- **Writes:** `.rcode/memory/incidents/known-issues.md` (deferred findings); `.rcode/memory/change-records/YYYYMMDD-NNN.md` (the audit itself as a change record)

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/SKILL.md ADDED Viewed

@@ -0,0 +1,162 @@
+---
+name: rcode-herdr-orchestration
+description: Orchestrate parallel cld agents in herdr — single-shot fan-out OR long-running autonomous wave-based fix campaign with durable backlog and integration branch. Do NOT use for a single quick task; invoke directly without herdr for that.
+triggers:
+  # English — single-shot orchestration
+  - "orchestrate agents"
+  - "run agents in herdr"
+  - "parallel audit"
+  - "spin up agents"
+  - "use herdr to do"
+  - "split work across panes"
+  - "fan out work in herdr"
+  - "multi-agent in herdr"
+  # English — autonomous campaign mode
+  - "autonomous fix campaign"
+  - "auto mode"
+  - "auto loop"
+  - "run waves of agents"
+  - "dispatch waves"
+  - "100+ commits"
+  - "keep working until done"
+  - "complete site audit and fix"
+  # Roman Urdu / Hindi
+  - "herdr mein chalao"
+  - "parallel agents lagao"
+  - "panes mein todo"
+  - "ek saath kai agents"
+  - "auto mode chalao"
+  - "waves mein fix karo"
+  - "campaign chalao"
+  # Arabic native
+  - "شغّل وكلاء بالتوازي"
+  - "وزّع العمل على عدة وكلاء"
+  - "استخدم herdr"
+  - "حملة إصلاح تلقائية"
+  - "موجات من الوكلاء"
+  - "وضع تلقائي"
+user-invocable: true
+---
+# rcode-herdr-orchestration
+## Overview
+Run many Claude agents in parallel inside `herdr` (terminal agent multiplexer), monitor
+them, and merge their work back safely.
+Two modes: **single-shot** (bounded fan-out, one sitting, merge back done) and
+**autonomous campaign** (100+ commits across waves with durable backlog and integration
+branch). Both share the same golden rules and pane mechanics. See `references.md` for
+the full campaign workflow and deep-dive rules.
+---
+## Golden rules (NON-NEGOTIABLE — apply to BOTH modes)
+1. **Use `cld`, never `claude`.** `cld` is the alias for
+   `claude --dangerously-skip-permissions`. Send it via `herdr pane send-text` + `send-keys Enter`
+   so the shell alias resolves. Do NOT use `herdr pane run` for `cld`.
+2. **If you must invoke `claude` directly** (alias unavailable): pass
+   `--dangerously-skip-permissions` AND run in **interactive mode** (no `-p`/`--print`).
+   A non-interactive `claude -p` call is invisible to herdr.
+3. **One git worktree per agent.** Never share a working tree between orchestrated agents.
+4. **Work locally, commit locally. Never push to origin or deploy** during an
+   orchestration run unless the user explicitly authorizes it afterward.
+5. **The orchestrator NEVER claims a wakeup it cannot fire.** `ScheduleWakeup` only
+   fires when `/loop` is active — clarify the heartbeat path with the user first.
+6. **Ignore stray buffer text in panes.** Leftover user text at an idle prompt is NOT
+   an agent question — do not Enter it.
+---
+## herdr CLI reference
+```bash
+herdr workspace list
+herdr tab list --workspace <wid>
+herdr tab create --workspace <wid> --label "X" --cwd PATH --focus
+herdr tab close <tab_id>               # IDs RENUMBER after a close — re-list
+herdr pane list --workspace <wid>      # pane_id, label, agent_status
+herdr pane split <pane_id> --direction right|down --cwd PATH --no-focus
+herdr pane rename <pane_id> "Label"
+herdr pane read <pane_id> --source visible|recent --lines N --format text
+herdr pane send-text <pane_id> "text"  # types text (no newline)
+herdr pane send-keys <pane_id> Enter|C-c|BSpace
+```
+`agent_status`: `working`, `blocked` (waiting on question/permission), `idle`/`done`, `unknown`.
+---
+## MODE 1 — Single-shot orchestration
+Use when work is bounded and can finish in one batch.
+**Steps:**
+1. Decide N areas (4 per tab default — 2×2 grid). Each area = one agent = one worktree = one branch.
+2. Create worktrees: `git worktree add ../sm-worktrees/$A -b audit-$A master` for each area.
+3. Create tab + split panes, one per worktree.
+4. Launch `cld` in every pane (`send-text "cld"` + `send-keys Enter`). Sleep 7s after.
+5. Send each agent a self-contained prompt with worktree path, branch, and task.
+   - Audits: diagnose-only first. Fixes: incremental edits, no rewrites, commit each fix.
+6. Monitor: `herdr pane list` every ~2 min. Unblock stuck panes via `send-keys`/`send-text`.
+7. Merge back: `git add -f .planning/audits/*.md && git commit` inside each worktree, then
+   `git merge <branch> --no-edit` from main repo. Verify `pnpm tsc --noEmit` count unchanged.
+8. Cleanup: `git worktree remove --force` each tree. Close herdr tab (re-list IDs first).
+---
+## MODE 2 — Autonomous campaign (summary)
+Use for `100+ commits`, `keep working until done`, `complete site audit and fix`.
+Full Phase 0-3 protocol, integration-branch rules, wave cadence, and anti-patterns are
+in **`references.md`** (sibling file). Key constraints:
+- Maintain one `campaign-integration` branch; sub-agents fork from it, never master.
+- Wave size: 3-5 agents, 10-15 min per wave. ScheduleWakeup ends EVERY turn.
+- Phase 3: show user the full diff + ask explicitly how to land (PR / merge / squash / leave).
+- Never push to origin master without an explicit yes — per campaign, not per session.
+---
+## When NOT to use this skill
+- A single, quick, one-agent task — just run it directly on the main tree, no herdr.
+- Anything the user wants to step through interactively — orchestration is for parallel,
+  hands-off batches.
+---
+## Output Format
+**Single-shot:** one worktree per agent on `audit-<area>` branch, per-area audit doc at
+`.planning/audits/AUDIT-<area>.md` (committed via `git add -f`), work merged back to
+calling branch with commits preserved.
+**Campaign:** durable backlog at `.planning/campaign/BACKLOG.md`, state log at
+`.planning/campaign/STATE.md`, one long-lived `campaign-integration` branch accumulating
+wave merges — master NOT touched until Phase 3 with explicit user consent.
+In both modes, orchestrator chat output is concise wave/pane status only.
+---
+## Examples
+**Happy path — single-shot 4-area parallel audit:**
+User: "Fan out a security audit across the auth, API, DB, and frontend areas in parallel."
+Orchestrator creates 4 worktrees on branches `audit-auth`, `audit-api`, `audit-db`,
+`audit-frontend`. Sends each agent: "You are in `../sm-worktrees/auth` on branch
+`audit-auth`. Diagnose security issues — report findings to `.planning/audits/AUDIT-auth.md`,
+no code changes yet." Monitors until all idle, merges branches, confirms TSC count stable.
+**Edge case — sub-agent goes silent past wave duration:**
+If `herdr pane list` shows a pane stuck `working` past 25 min: `herdr pane read <id>` —
+usually an AskUserQuestion blocking. Pick the safe option via `send-keys`. If still stuck
+after another 10 min, `C-c` the pane, note the partial work, revert the branch, and
+re-dispatch the item in the next wave.
+**Negative example — when NOT to invoke this skill:**
+User: "Fix the typo in README line 4." This is a one-line edit. Invoke herdr orchestration
+for this is overkill — just edit the file directly on the current branch.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/references.md ADDED Viewed

@@ -0,0 +1,136 @@
+# rcode-herdr-orchestration — References
+Overflow content split from SKILL.md per the 200-line budget. Read SKILL.md first.
+---
+## MODE 2 — Full campaign workflow
+### Extra hard rules (rules 7-11, in addition to the 6 golden rules in SKILL.md)
+7. **Durable backlog.** Commit `.planning/campaign/BACKLOG.md` at campaign start so the
+   campaign survives auto-compact. Don't keep the work list in conversation memory only.
+8. **Campaign integration branch.** Maintain ONE long-lived branch (default
+   `campaign-integration`). Sub-agents always fork from it — never directly from master.
+   Wave-N merges land on the integration branch; master only sees the campaign via a
+   single explicit merge at Phase 3. See `rules/integration-branch.md`.
+9. **Merge into the integration branch as you go.** Wave-N branches merge into the
+   integration branch BEFORE wave-(N+1) dispatches.
+10. **TSC stays at integration baseline.** Capture `pnpm tsc --noEmit | grep -c "error TS"`
+    at campaign start. Any wave that breaks the baseline is reverted before the next wave.
+11. **No push without explicit user consent — per campaign, not per session.** Per-change
+    consents earlier in the session do NOT extend.
+### Wave cadence
+- **Wave size**: 3-5 sub-agents. More than 5 = harder to merge, more conflicts.
+- **Wave duration**: 10-15 min target. If a wave runs past 25 min, peek for stuck agents.
+- **Heartbeat**: orchestrator wakes every 10-15 min. Cache-window math: 270s, 720s, 1200s.
+### Backlog pipeline
+```
+.planning/audits/AUDIT-*.md  ──┐
+grep TODO/FIXME/HACK         ──┼──▶  .planning/campaign/BACKLOG.md  ──▶  wave-1, wave-2, …
+existing pending P1/P2 items ──┘                    ▲
+                                                    │
+                              wave-N findings append back ↑
+```
+### Phase 0 — Initialize (one-time)
+1. Confirm baseline: `git branch --show-current` = master, clean tree, capture TSC count.
+2. Create the campaign integration branch:
+   ```bash
+   git checkout -b campaign-integration master
+   ```
+3. Mine the backlog into `.planning/campaign/BACKLOG.md` from audit docs +
+   `grep -rn "TODO\|FIXME\|HACK\|XXX"`. Commit it on the integration branch.
+4. Start the bash heartbeat (`bash templates/heartbeat.sh &`).
+### Phase 1 — Wave dispatch
+1. Read next 3-5 items from BACKLOG.md → move to STATE.md "In flight (wave N)".
+2. Create worktree + branch **forked from integration branch**:
+   ```bash
+   git worktree add ../sm-worktrees/camp-<area> -b campaign-<area> campaign-integration
+   ```
+3. Create/reuse herdr tab, split panes, launch `cld --model sonnet` in each.
+4. Send each agent a wave prompt (use `templates/wave-prompt.md`):
+   - Worktree path + branch + parent = `campaign-integration`
+   - Specific backlog item + audit doc reference
+   - "Do not push. Do not merge. Do not touch master or the integration branch directly."
+5. **End the turn with ScheduleWakeup. Always.**
+### Phase 2 — Heartbeat loop (every 10-15 min)
+1. `herdr pane list` — count panes in `working` vs `idle`/`done`.
+2. For every branch with new commits: merge into the integration branch (NOT master).
+3. After each merge: `pnpm tsc --noEmit` regression check. Bumped count = revert from integration.
+4. Do NOT push to origin master. Do NOT touch master.
+5. Move shipped items from STATE.md "in flight" → "shipped".
+6. If BACKLOG.md still has items → dispatch wave-(N+1). Else → Phase 3.
+7. **End the turn with ScheduleWakeup** while any pane is working OR BACKLOG.md is non-empty.
+### Phase 3 — Drain & Land
+1. When BACKLOG.md empty AND all panes idle: kill heartbeat bash loop.
+2. Show user the full diff of integration branch vs master.
+3. Ask explicitly: "Campaign work is on `campaign-integration` (N commits ahead of
+   master). How do you want to land it?" Options:
+   - PR: `gh pr create --base master --head campaign-integration`
+   - Merge to master locally (explicit yes required)
+   - Squash-merge for one tidy commit
+   - Leave the integration branch for human review
+4. Never `git push origin master` without an explicit yes.
+---
+## Key files (campaign mode)
+| File | Purpose |
+|------|---------|
+| `.planning/campaign/BACKLOG.md` | Durable work list. Committed at campaign start. |
+| `.planning/campaign/STATE.md` | Waves shipped, in-flight, TSC drift per wave. |
+| `.planning/campaign/HEARTBEAT` | `touch`ed by bash loop every 30s — mtime proves orchestrator alive. |
+| `templates/BACKLOG-template.md` | Starter for the backlog file. |
+| `templates/STATE-template.md` | Starter for the state file. |
+| `templates/heartbeat.sh` | Background heartbeat script template. |
+| `templates/wave-prompt.md` | Per-agent prompt boilerplate. |
+---
+## Rules deep-dive
+- **`rules/integration-branch.md`** ← READ FIRST for campaign mode
+- `rules/orchestrator-rhythm.md` — heartbeat / ScheduleWakeup decision tree
+- `rules/wave-design.md` — wave sizing
+- `rules/backlog-building.md` — audit mining, TODO scan, dedup
+- `rules/merge-strategy.md` — TSC gate
+- `rules/composition-with-herdr.md` — how campaign mode layers on single-shot mechanics
+---
+## Gotchas (field-tested, both modes)
+- **herdr renumbers tab IDs on close.** Always re-list before the next close.
+- **Parallel agents tangle branches** if they share a working tree — one worktree per agent always.
+- **`.planning/` is often gitignored** — audit docs need `git add -f`.
+- **`make brain`'s `git push` is `|| true`** — it silently fails on a diverged branch.
+  Never assume a deploy shipped your local commits without checking.
+- **Diverged local vs origin master** is the #1 risk after a long parallel run. Do NOT
+  auto-resolve conflicts unattended — surface to the user.
+- Capture extra `sleep` after launching `cld` — it takes ~5-7s to boot.
+---
+## Anti-patterns (campaign mode)
+| Failure | Prevented by |
+|---|---|
+| Cross-wave merge conflicts pile up | Integration branch — every wave inherits prior waves' work |
+| Orchestrator goes silent mid-campaign | Hard rule 5 + heartbeat template |
+| Lost backlog after auto-compact | Phase 0 commits BACKLOG.md on integration branch |
+| Silent push to master without consent | Hard rule 11 + Phase 3 ask-before-land |
+| TSC drift compounds | Phase 2 regression check + revert from integration branch |
+| Integration branch never lands | Phase 3 mandatory "how to land it" question |

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/backlog-building.md ADDED Viewed

@@ -0,0 +1,113 @@
+# Backlog Building
+How to build a durable, prioritized, committed campaign backlog.
+## Purpose
+The backlog is the campaign's spine. Without a durable file-on-disk backlog, an auto-compact erases the work plan and the campaign collapses. This rule encodes the build + maintain pipeline.
+## Rules
+### Source priority (highest signal first)
+1. **Existing audit docs** at `.planning/audits/AUDIT-*.md` — these are human-curated and already prioritized P1/P2. Most reliable source.
+2. **`/audit-fix` skill outputs** if available — Rihal projects often have these pre-generated.
+3. **Pending items** in the project's CHANGELOG / ROADMAP / `.planning/state.md`.
+4. **Code-level TODOs**: `grep -rn -E "// *(TODO|FIXME|HACK|XXX)[: ]"` in `server/` + `src/` — lowest signal, often stale.
+5. **CI failures / open GitHub issues** — only if explicit user request.
+### Backlog format
+```markdown
+# CAMPAIGN BACKLOG
+Generated: <ISO timestamp>
+Baseline TSC errors: <count>
+## Open items
+- [ ] **<area>** (P<priority>): <one-line description>. Source: <audit-doc>:<line>
+- [ ] **<area>** (P<priority>): …
+## In flight (wave N)
+- [~] **<area>**: assigned to pane <pane-id>, branch <branch>, started <time>
+## Shipped
+- [x] **<area>**: commit <sha>, wave <N>, finished <time>
+```
+### Dedup rules
+Before adding an item to the backlog, check:
+- Is there an existing master commit covering it? `git log --oneline | grep -i <keyword>`
+- Is there an in-flight branch covering it? `git branch | grep -i <keyword>`
+- Is it identical to another backlog item with a different file:line? Merge them.
+### Maintenance during the campaign
+- Every wave merge: move items from "In flight" → "Shipped" with the commit SHA.
+- Every wave dispatch: move items from "Open" → "In flight" with pane + branch.
+- New findings from a sub-agent's audit phase: append to "Open" with source attribution.
+- Item rejected by a wave-agent (out of scope, blocked, etc.): mark `[skip]` with reason — do not delete.
+### Commit the backlog
+```bash
+git add -f .planning/campaign/BACKLOG.md .planning/campaign/STATE.md
+git commit -m "chore(campaign): backlog snapshot at wave <N>"
+```
+The `-f` is required if `.planning/` is gitignored (common in Rihal projects).
+## Examples
+### Building backlog from audit docs
+```bash
+{
+  echo "# CAMPAIGN BACKLOG"
+  echo "Generated: $(date -u +%FT%TZ)"
+  echo "Baseline TSC: $(pnpm tsc --noEmit 2>&1 | grep -c 'error TS')"
+  echo
+  echo "## Open items"
+  for f in .planning/audits/AUDIT-*.md; do
+    area=$(basename "$f" .md | sed 's/^AUDIT-//')
+    pending=$(grep -nE "(⏳|^- \[ \]|^### P[12])" "$f" 2>/dev/null | head -5)
+    [ -n "$pending" ] && echo "$pending" | sed "s|^|- [ ] **$area** (from $f) |"
+  done
+} > .planning/campaign/BACKLOG.md
+```
+### State transition
+```diff
+- [ ] **call-update-flow** (P1): add Sentry capture on EventBus handler errors. Source: AUDIT-call-update-flow.md:142
++ [~] **call-update-flow**: assigned to pane w65..-8, branch campaign-call-update-flow, started 2026-05-26T14:32Z
+```
+later:
+```diff
+- [~] **call-update-flow**: assigned to pane w65..-8, branch campaign-call-update-flow, started 2026-05-26T14:32Z
++ [x] **call-update-flow**: commit 40b908d9, wave 2, finished 2026-05-26T14:51Z
+```
+## Anti-Patterns
+### Backlog only in conversation memory
+**Problem**: Auto-compact wipes it; the next turn can't resume.
+**Instead**: File on disk, committed.
+### Massive backlog dumped once
+**Problem**: A 200-item backlog overwhelms wave selection — orchestrator picks badly because it can't see the whole context.
+**Instead**: Build in chunks. Top 20-30 items as "Open"; lower-priority items as a footnote or separate file.
+### Mining TODOs from test files
+**Problem**: Test TODOs are often "this case is unimplemented" — they're test scaffolding, not real bugs.
+**Instead**: `grep ... | grep -v "\.test\.\|\.spec\."` to filter them out.
+### Skipping dedup
+**Problem**: Same bug fixed 3 times by 3 waves because none knew the others were working on it.
+**Instead**: Always check master log + in-flight branches before adding.
+## Related
+- `wave-design.md` — backlog drives wave composition
+- `composition-with-herdr.md` — STATE.md ties to herdr pane labels
+## Changelog
+- 2026-05-26: Initial.