@lifeaitools/rdc-skills 0.20.4 → 0.20.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.20.4",
+  "version": "0.20.5",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/git-sha.json

@@ -1,3 +1,3 @@
 {
-  "sha": "d7e04b5d2955e49d3a63357710e1691a48f2184b"
+  "sha": "564ace3c41ccf10d58d8c0cc8c0709d7574b653d"
 }

package/guides/output-contract.md

@@ -37,6 +37,16 @@ thing they need: **is this working or not, and what step are we on?**
    - `⚠️ <skill>: <N findings> — <next action>`
    - `❌ <skill>: <one-sentence reason>`
 
+   ⛔ **The verdict emoji (✅ / ⚠️ / ❌) MUST be the FIRST character of the final
+   line — never prefix it with `**Verdict:**` or any other text.** The enforcing
+   Stop-hook checks that a line *begins* with the emoji; `**Verdict:** ✅ PASS …`
+   reads as a verdict to a human but FAILS the machine check because the line
+   starts with `**Verdict:`, not `✅` (lesson 2026-06-08-collab-verdict-line-must-start-with-emoji).
+
+   > This guide is the source under `guides/output-contract.md`; it is mirrored to
+   > `regen-root/.rdc/guides/output-contract.md` by the installer. Edit only the
+   > rdc-skills source here — never the mirror.
+
 7. **Interactive checklists only when human input is required.** If the skill
    needs a decision (pick an epic, confirm a destructive op), ask ONE question,
    then resume.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.20.4",
+  "version": "0.20.5",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",

package/skills/build/SKILL.md

@@ -199,6 +199,18 @@ Read the task title and description, then:
    isolation: "worktree"
    ```
 
+   ### ⛔ Concurrent committers ⇒ worktree isolation, no exceptions (docs included)
+   For ANY parallel agent dispatch where the agents COMMIT — **including a pure
+   docs wave** — force `isolation: "worktree"` so each agent commits in its own
+   tree and the orchestrator merges. NEVER fan out concurrent committers onto one
+   shared working tree (lesson 2026-06-13-build-concurrent-agents-same-branch-git-race:
+   three parallel doc agents on one `develop` tree raced on the git index/stash —
+   one commit swept in another agent's staged-but-uncommitted files under the wrong
+   message, two agents reported the SAME SHA, and a pre-commit `sync:docs` ref-lock
+   race misattributed authorship). "It's just docs" is NOT an exemption. The only
+   alternative to worktree isolation is running the committing agents **sequentially**
+   on the shared tree (one commits and pushes before the next starts).
+
    **Agent model routing — pick per task, not per wave.** The supervisor session model does NOT cascade to agents; you must set `model` explicitly on every dispatch.
 
    | Task character | Model | When to pick it |
@@ -219,6 +231,31 @@ Read the task title and description, then:
    Without `max_turns: 70`, agents hit the default turn cap mid-task and stop.
    `isolation: "worktree"` gives each agent its own git worktree and branch — eliminates push race conditions and index lock contention when multiple agents commit in parallel. The supervisor merges worktree branches after each wave (Step 9).
 
+   ### ⛔ Worktree base must equal develop HEAD — assert BEFORE every isolated wave
+   The worktree-isolation harness has shipped worktrees pinned to a STALE base
+   commit (lessons 2026-06-10-build-worktree-stale-base, 2026-06-11-build-worktree-stale-base:
+   agents branched 464 commits / 4 days behind develop HEAD, on a tree where the
+   target app did not yet exist — their diffs would have silently reverted merged
+   work or operated on a deleted structure). **Before dispatching ANY
+   `isolation:"worktree"` wave**, assert each worktree's base equals current
+   develop HEAD:
+   ```bash
+   DEV_HEAD=$(git rev-parse develop)
+   # After worktrees are created, for each agent worktree:
+   git worktree list   # compare each agent worktree's SHA to $DEV_HEAD
+   # If a worktree base != $DEV_HEAD (it is behind), the wave is UNSAFE.
+   ```
+   - If any worktree base is behind `$DEV_HEAD`: **ABORT isolation for this wave.**
+     Do NOT merge stale worktree output. Pivot to **sequential, non-isolated
+     dispatch on a real `develop` checkout** (one disjoint WP at a time to avoid
+     `.git/index` races; the supervisor pushes) — the same reason the validator
+     runs non-isolated (it must see merged develop).
+   - Also at every merge: `git show <branch>:<key-file> | grep -c <symbol-a-prior-wave-introduced>`
+     — a 0 where there should be ≥1 means the branch is stale or deleted a shared
+     export; resolve to `--ours` and re-apply that wave's real delta on current HEAD.
+     esbuild/tsc PASS is necessary, not sufficient — pair it with a grep gate on
+     the symbols a refactor must preserve.
+
    ### Forked agents vs. standalone agents
 
    **When the supervisor has already read the plan** (via a prior `Read` tool call in the same session),
@@ -237,6 +274,21 @@ Read the task title and description, then:
    **When the supervisor has NOT read the plan** (e.g. dispatching from a fresh `rdc:build` call with
    only an epic ID), the agent has no plan context — write a full briefing prompt with all specs.
 
+   ### ⛔ Reuse contract — when a WP builds on an existing subsystem
+   When a work package extends an existing subsystem, "compose adapter + X"
+   under-specifies reuse and lets an agent legitimately re-author markup/logic the
+   subsystem already exposes (lesson 2026-06-11-build-reuse-existing-engine-prompt:
+   an agent set up to reinvent a grid when the card engine already shipped four
+   `CardLayout` display types + a full `parseCommand → CardSpec → adapter → CardModel[]`
+   calling sequence). The dispatch prompt MUST:
+   1. **Enumerate the existing public API the agent must reuse, BY FILE** — types/enums
+      (`packages/.../types.ts:NN`), calling-sequence functions, AND the existing
+      display/render components — not just the data adapter.
+   2. **Mark which seams are extend/delegate-only.** State explicitly: "thread a
+      pass-through prop (e.g. `layout`) to the existing components; do NOT
+      reimplement layout/render." Verify at WP review that the agent reused the
+      named parser/adapter/components and did not hand-roll a parallel implementation.
+
    ---
 
    ### Required agent prompt contents
@@ -270,6 +322,25 @@ Read the task title and description, then:
    - Use `run_in_background: true` for parallel execution
    - NEVER let agents overlap on the same files
 
+   ### ⛔ Agent Definition-of-Done additions (include in every prompt)
+   - **Declare every import in the package's OWN package.json.** Every import an
+     agent adds MUST be present in that package's own `package.json`
+     dependencies/devDependencies — never rely on monorepo-hoisted deps. A pnpm
+     worktree can import a root-hoisted dep (e.g. `vitest`,
+     `@supabase/supabase-js`) so `tsc`/`vitest` PASS in the worktree, then `tsc`
+     FAILS on a clean develop checkout after merge (lesson
+     2026-06-10-build-card-engine-agent-deps). Agent prompt line: *"Verify that
+     every import you add is declared in this package's own package.json — do not
+     rely on hoisted monorepo deps."*
+   - **A server/MCP/API task is NOT done without a committed automated test that
+     ships in the SAME commit and exercises EVERY surface.** Manual curl / a single
+     `/health` 200 is a proxy, not coverage (lesson 2026-06-10-build-weak-dod-no-tests).
+     For a collection (MCP skills, API routes, CLI commands): loop over ALL items
+     and assert `output == source` — never a single spot check. Wire an npm script
+     and run it green before the item leaves `review`. Agent prompt line: *"This
+     task is not done until a committed test in the same commit exercises every
+     surface; for collections, loop all items and assert output == source."*
+
 8. **Post-wave test gate (mandatory):**
    After all agents in a wave complete, before proceeding:
    ```bash

package/skills/collab/SKILL.md

@@ -98,8 +98,17 @@ Print `[rdc:collab] Still listening...` and retry SSE immediately. After 10
 consecutive 30s timeouts (5 min idle), print a longer heartbeat but keep
 looping.
 
-**If curl fails (daemon restart, connection refused, non-200):** fall back to
-polling path below.
+**⛔ curl exit 28 (`--max-time`) is SUCCESS, not failure, on an SSE read.**
+`curl --max-time 30` ALWAYS exits 28 at the timeout boundary — that is normal for
+a long-lived SSE stream and says nothing about delivery. If a `data:` event was
+received in the output, process it and proceed to Step 4 — do NOT treat exit 28 as
+a curl failure (lesson 2026-06-08-collab-sse-exit-28-is-success: exit 28 arrived
+together with a full `event: message` / `data: {...}` payload, and reading it as a
+failure misclassified a zero-latency delivery). Only **connection-refused or a
+non-200** is a real curl failure that triggers the polling fallback.
+
+**If curl fails (daemon restart, connection refused, non-200 — NOT a bare exit 28
+with a delivered `data:` event):** fall back to polling path below.
 
 ### Fallback path — polling (2s interval)
 
@@ -215,6 +224,15 @@ If Dave types in this terminal during a turn:
 - Treat it as an override injected into the current task
 - Acknowledge it in your `chitchat_reply` response
 - If it changes direction mid-task, note what you stopped and why
+- ⛔ **When an interjection appears to CONTRADICT the task premise, restate your
+  understanding in ONE sentence and confirm before branching into a wide
+  `AskUserQuestion` menu.** A tight "I read this as X — correct?" reconciles faster
+  than a multiple-choice and avoids acting on a misread premise (lesson
+  2026-06-08-collab-premise-contradicting-interjection: "there is no pm2 this
+  replaces it" was read as "PM2 is abolished as the transport" and triggered a
+  3-option transport menu, when it meant "there was no dev *site* yet — push to
+  the unchanged PM2 path"; the wide menu over-committed to one interpretation and
+  cost a round).
 
 ## Capture lessons (exit step)
 

package/skills/deploy/SKILL.md

@@ -66,6 +66,28 @@ rdc:deploy: <slug> → <domain>
 ✅ rdc:deploy: <slug> deployed in Nm Ns
 ```
 
+#### Static PM2 dev sites — do NOT trust the push webhook (SSH-reset + served-hash gate)
+
+For a **static** PM2 dev site, `git push` succeeding does NOT mean the live site
+updated: the push webhook skips/instruments static apps unreliably, so the host
+working tree (and the committed `dist/` it serves) can stay STUCK across several
+pushes while HTTP stays 200 and `origin/develop` looks shipped (lesson
+2026-06-11-deploy-static-host-stuck: issho served the v1.10.0 bundle across three
+pushes because `/srv/regen/regen-root` never pulled). The only signal is the
+SERVED bundle hash vs the local `dist/` hash.
+
+After pushing committed `dist/`, SSH-reset the host explicitly, then verify the
+served hash:
+```bash
+_K=$(mktemp); curl -s http://127.0.0.1:52437/v/vultr-dev-ssh > "$_K"; printf '\n' >> "$_K"; chmod 600 "$_K"
+ssh -i "$_K" root@64.237.54.189 'cd /srv/regen/regen-root && git fetch -q origin develop && git reset -q --hard origin/develop && pm2 restart <app> --update-env'
+rm -f "$_K"
+# Then verify SERVED hash == local build hash (HTTP 200 is NOT proof):
+curl -s https://<app>.dev.place.fund/ | grep -oE 'index-[A-Za-z0-9_-]+\.js'   # served
+grep -oE 'index-[A-Za-z0-9_-]+\.js' sites/<app>/dist/index.html                # local
+```
+Only when the two hashes match do the content/screenshot gates mean anything.
+
 ### Mode 2 — new <slug>
 
 **MANDATORY:** All new apps are created from `docs/runbooks/coolify-app-templates.json`. Read that file first — pick the right template, substitute the required vars, POST the exact payload. No manual field configuration. No improvisation. The template encodes all learned lessons (base_directory, build_pack, watch_paths, health_check, ports). Deviating from it breaks things.
@@ -112,6 +134,40 @@ rdc:deploy diagnose: <slug>
 ⚠️ rdc:deploy diagnose: <root cause in one sentence> — fix: <one command>
 ```
 
+#### `next start` crash-loop — check `.next/BUILD_ID` FIRST
+
+When a PM2 `next start` app is crash-looping (`pm2 jlist` shows high `restart_time`
+/ "waiting restart"), check **`.next/BUILD_ID`** before chasing env/port theories —
+it is the single gate `next start` enforces (`Could not find a production build in
+the '.next' directory` repeats for every restart when it is missing). A `.next`
+tree can exist as a PARTIAL build (manifests + server artifacts but no `BUILD_ID`)
+— the signature of a `next build` that started but was interrupted/OOM-killed; the
+crash loop then churns CPU and can re-trigger the OOM (lesson
+2026-06-13-deploy-nextstart-missing-buildid: ~7300 restarts, all `BUILD_ID`-missing,
+while the documented prior lead was the NEXT_PUBLIC env issue — which was NOT the
+cause here). Fix sequence:
+```bash
+pm2 stop <app>                              # halt the loop so it stops competing for resources
+rm -rf apps/<name>/.next                    # clear the partial tree
+pnpm --filter @regen/<name> build           # ONE clean scoped build (LOCAL BUILD SAFETY)
+pm2 restart <app> --update-env
+```
+Guard: assert `apps/<name>/.next/BUILD_ID` exists before (re)starting any
+`next start` process.
+
+#### ⛔ On the 2nd IDENTICAL failed probe, STOP polling and diagnose full-state
+
+A repeated identical failure (same 404, same 502, same non-200) is a STRUCTURAL
+signal, not eventual-consistency — polling it will never clear it and reads to the
+user as stalling/throttling (lesson 2026-06-10-deploy-stop-polling-diagnose: a
+12×-404 poll loop on a remote-managed tunnel that was structurally ignoring the
+local config — it could never clear). On the **2nd identical failed check**, stop
+polling and pull GROUND TRUTH instead: list ALL processes / the whole effective
+remote config / the full event log (`debugging-protocol.md` Rule 6 — full-state, not
+a narrow filter). Poll ONLY when something is genuinely in-progress with a known
+finish (a deploy build, a DNS first-create) — never to hope a structural error
+resolves itself.
+
 ### Mode 4 — audit
 
 ```
@@ -159,6 +215,10 @@ rdc:deploy promote: <slug> → <prod-domain>
 [ ] Scope resolved: --hotfix <sha> → that commit; else the app-path commits on develop not on main
 [ ] Scope guard: promote ONLY this app's paths. NEVER merge develop→main wholesale (drags unrelated WIP to prod)
 [ ] Clean worktree off origin/main (never switch the dirty working tree)
+[ ] Export Supabase creds in the worktree BEFORE commit (the pre-commit `sync:docs` hook needs them, and a fresh worktree does NOT inherit the main checkout's `.env*`/shell env — without the key sync:docs silently regenerates a GUTTED `app-deployments.md` ("Registry: unavailable") and `git add`s it into the surgical promote; `--no-verify` is forbidden):
+      `export NEXT_PUBLIC_SUPABASE_URL=https://uvojezuorjgqzmhhgluu.supabase.co`
+      `export NEXT_PUBLIC_SUPABASE_ANON_KEY=$(curl -s http://127.0.0.1:52437/v/supabase-anon)`
+      Then ALWAYS `git show --stat HEAD` before pushing and confirm the file set is scoped — never ship the no-key gutted app-deployments.md. (lesson 2026-06-13-deploy-worktree-syncdocs-guts-app-deployments)
 [ ] Apply change: cherry-pick <sha> (or `git checkout <develop-sha> -- <app-paths>`); confirm diff = expected files only
 [ ] Mandatory pre-promote code-review (pr-review-toolkit:code-reviewer on the promote diff). Block on critical/high.
 [ ] Commit on promote branch; push branch (NOT main directly — the main-push hook blocks raw main pushes)
@@ -393,8 +453,23 @@ curl -s -X PATCH -H "Authorization: Bearer $_COOLIFY" \
   -H "Content-Type: application/json" \
   -d '{"watch_paths":"apps/<name>/**\npackages/**"}' \
   "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
+
+# Change the app's domain — the writable field is "domains", NOT "fqdn"
+# (Coolify v4 PATCH rejects {"fqdn":...} with "This field is not allowed"; fqdn is read-only/derived)
+curl -s -X PATCH -H "Authorization: Bearer $_COOLIFY" \
+  -H "Content-Type: application/json" \
+  -d '{"domains":"https://<host>"}' \
+  "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
 ```
 
+**Domain change / namespace migration** (lesson 2026-06-13-deploy-media-manager-namespace-migration):
+PATCH `applications/<uuid>` with `{"domains":"https://<host>"}` — never `fqdn`.
+For an app NEW to main (first prod deploy) also bring the app + a lockfile importer
+to main (clean worktree off origin/main, `pnpm install --lockfile-only`, verify the
+diff = additions for `apps/<name>:` only); resolve the lockfile-guard vs scope-guard
+collision by committing the app+lockfile as a SINGLE `chore(infra):`-subject commit
+(the scope-guard's documented escape hatch) so both pre-commit guards pass.
+
 **Never print `$_COOLIFY` to stdout.** Inline from clauth only — do not assign raw strings.
 
 If clauth daemon is not responding (`curl -s http://127.0.0.1:52437/ping` fails):

package/skills/plan/SKILL.md

@@ -251,6 +251,24 @@ Q5. What SSL path?
 
 Embed all five answers into the infra task description verbatim before handing to the agent.
 
+## MCP / infra plans — mirror the closest sibling deployment FIRST
+
+Before writing any plan that stands up an MCP server or infra service, read how the
+**closest existing sibling** is actually deployed (`.mcp.json` + its PM2/tunnel or
+Coolify/Docker config) and **cite it in the plan**. Two MCP topologies coexist and
+applying the wrong reference over-engineers the design (lesson
+2026-06-10-plan-mirror-sibling-mcp-pattern: a first MCP plan proposed
+Docker + Coolify + a Cloudflare-proxied origin + runtime GitHub-pull when the real
+pattern was a local Node process + clauth-managed tunnel, exactly like codeflow-mcp):
+
+- **LOCAL-MCP reference = `codeflow-mcp`** — local Node process (`:3109`) + clauth-managed
+  tunnel ingress. Mirror this for MCPs that live on Dave's box.
+- **REMOTE-MCP reference = `web-research` / `regen-media`** — Coolify/Docker, Cloudflare-proxied
+  origin (`.claude/rules/mcp-endpoint-design.md` covers the REMOTE class only).
+
+Decide which class applies and name the sibling in the plan's Design Decisions before
+designing topology. Do not reach for the REMOTE rule by default.
+
 ## Capture lessons (exit step)
 
 Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-plan-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.

package/skills/release/SKILL.md

@@ -99,6 +99,31 @@ npm view <package-name> version
 
 Never use `--force` or bypass hooks. If a hook fails, fix the cause.
 
+## ⛔ Standalone-repo staging guard (no `git add -A`)
+
+Standalone repos (`rdc-skills`, `clauth`, `build-corpus`) have NO pre-commit
+doc-sync/scope guard to catch contamination. In them:
+
+- **REFUSE `git add -A` / `git add .`.** Stage explicit declared paths only
+  (`git add skills/<name>/SKILL.md package.json ...`).
+- Run `git status --porcelain` FIRST. If untracked files exist that are not part
+  of the declared change, STOP — list or stash them; do not sweep them in.
+- **Pre-tag guard: refuse to tag if `git diff --cached --name-only` includes any
+  path outside the declared change set.** A broad add swept 4 pre-existing
+  untracked skill files into a tagged release that CI published before anyone
+  noticed (lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
+  dirty-tree contamination class as a lockfile generated against a dirty tree.
+
+## ⛔ Cross-platform prepack + verify the PUBLISHED tarball
+
+- **Prepack must be OS-agnostic.** A bash-style `prepack` chain (`node A || true && node B || true && node stamp`) short-circuits under Windows **cmd.exe** (npm runs lifecycle scripts via cmd, not bash; `true` is not a cmd builtin and `||`/`&&` evaluate differently), so an appended step silently never runs (lesson 2026-06-13-release-windows-cmd-prepack-shortcircuit). When a prepack step must run cross-platform, use a node wrapper / `shx` / `cross-env` — never rely on `|| true` shell semantics that differ between cmd and bash.
+- **Validate the PUBLISHED artifact, not a local Windows `npm pack`.** A local Windows `npm pack` is NOT a faithful rehearsal of the CI (ubuntu/bash) publish. After publish, verify the real tarball:
+  ```bash
+  npm pack <pkg>@<version>            # downloads the PUBLISHED tarball
+  tar -xzOf <pkg>-<version>.tgz package/<file>   # inspect the shipped file
+  ```
+  Confirm the published artifact carries what CI's prepack was supposed to stamp (e.g. `git_sha == tag commit`).
+
 ## RDC Skills Package
 
 For this package, prefer the npm installer binary after publish: