@lifeaitools/rdc-skills 0.22.0 → 0.24.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "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": "00a9e253509122dd9948e1e558756f8f317f1b20"
+  "sha": "46460e5add65d8555ec9246eed10eb2d7c5fcbb4"
 }

package/package.json

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

package/skills/build/SKILL.md

@@ -163,6 +163,28 @@ Read the task title and description, then:
    - DB/migration task: at least schema object, relationship/guard, policy/permission, seed/fixture or backfill, and smoke query.
    - Editor/sidebar/CLI workflow: at least start, attach/open, enqueue action, observe result, timeout/error, and live refresh where applicable.
 
+   ### ⛔ Deliverable / acceptance check-off table — show BEFORE any implementation
+   Before dispatching the first wave, render a deliverable/acceptance table and
+   keep it visible through the build (lesson 2026-06-16-build-poor-goal-execution-mdk-brain:
+   a build satisfied generic checklist rows — tsc clean, route 200 — while never
+   touching the surface the user actually named, because no row anchored the
+   user's TARGET SURFACE). The table MUST contain:
+   - **One mandatory row for the user-named TARGET SURFACE** — the exact screen,
+     endpoint, file, or behavior the user asked for, by name. Its acceptance check
+     is what proves THAT surface renders/works, not a proxy.
+   - **At least one NEGATIVE verifier row** — a check that proves the WRONG thing
+     does NOT happen (e.g. "mock data is NOT rendered", "old route returns 404",
+     "stub component is absent from the bundle"). A positive-only suite passes
+     even when the deliverable is wired to the wrong source.
+
+   | Deliverable | Target surface? | Acceptance check | Negative verifier | Status |
+   |---|---|---|---|---|
+
+   **Gating rule:** any work item whose deliverable maps to the TARGET SURFACE row
+   stays in `review` (never `done`) until that target-surface acceptance check
+   passes. Generic gates (tsc, route 200) clearing is NOT sufficient to advance
+   the target-surface item.
+
    If the gate fails:
    - Interactive: show the failing rows and invoke `rdc:plan <epic-id>` to repair the matrix before dispatch.
    - Unattended: invoke `rdc:plan <epic-id> --unattended`, reload tasks, and run this gate once more.
@@ -192,24 +214,59 @@ Read the task title and description, then:
 7. **For each wave — dispatch typed agents in parallel:**
 
    ### ⛔ Agent Dispatch Non-Negotiable Defaults
-   Every `Agent()` call MUST include these parameters — no exceptions:
+   Every `Agent()` call MUST include these parameters:
    ```
    model: <chosen per the routing table below>
    max_turns: 70
-   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).
+   `isolation` is chosen per the dispatch-mode rule below — it is NOT a blanket
+   default. Worktree isolation is reserved for true parallel MULTI-committer waves
+   in the same repo; doc-only and single-committer waves default to NON-isolated.
+
+   ### ⛔ Dispatch mode — non-isolated is the default for single-committer / doc-only waves
+   Worktree isolation exists to protect a SHARED working tree from a git-index race
+   between MULTIPLE agents committing in parallel. When there is only ONE committer,
+   that race cannot occur, and the stale-base hazard of worktrees (see the HARD GATE
+   below — recurring across 2026-06-10/11/15/16/17/23) is pure downside. Pick the
+   dispatch mode by committer count, not by reflex:
+
+   | Wave shape | Dispatch mode | isolation |
+   |---|---|---|
+   | **Doc-only wave** (markdown/docs/plans, no code build) | NON-isolated, one committer on `develop` | omit `isolation` |
+   | **Single-committer wave** (only one agent commits, or work serializes to the supervisor) | NON-isolated, one committer on `develop` | omit `isolation` |
+   | **True parallel MULTI-committer wave** (2+ agents committing concurrently in the same repo, disjoint files) | worktree-isolated, supervisor merges | `isolation: "worktree"` |
+
+   - **Default = NON-isolated.** Only escalate to `isolation: "worktree"` when the
+     wave genuinely has 2+ concurrent committers in the same repo.
+   - A pure docs wave is single-committer by default: either dispatch ONE doc agent,
+     or have parallel doc agents return diffs/patches that the supervisor commits
+     serially. Do NOT fan out 2+ concurrent committers onto one shared `develop`
+     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, a pre-commit `sync:docs` ref-lock
+     race misattributed authorship). The fix for that race is single-committer
+     serialization, NOT blanket worktree isolation.
+   - When you DO need a true MULTI-committer parallel wave, worktree isolation is
+     mandatory AND the HARD GATE below (base == develop HEAD) MUST pass before
+     dispatch — a stale-base worktree wave is a build failure, not a warning.
+
+   ### ⛔ Foreign concurrent session guard — `git status` BEFORE the build
+   Worktree isolation protects against THIS build's own agents, not against a
+   DIFFERENT session (another cell, a Codex run, a human) already committing on
+   the same shared tree (lesson 2026-06-16-build-concurrent-session-shared-tree-commit-corruption:
+   a foreign session's staged-but-uncommitted files were swept into this build's
+   commit under the wrong message). Before dispatching any wave, run `git status`
+   to detect foreign-dirty files you did not create. If foreign-dirty files are
+   present: do NOT fan out concurrent committers — **serialize ALL committers to
+   the supervisor** (agents return diffs/patches; the supervisor stages and
+   commits each one alone). After every supervisor commit, assert the exact file
+   set landed and nothing foreign leaked in:
+   ```bash
+   git show --stat <sha>   # confirm ONLY the files this commit owns are listed
+   ```
+   A `git show --stat` that lists a file the agent did not touch = a foreign file
+   leaked into the commit; reset and re-stage by explicit path.
 
    **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.
 
@@ -231,25 +288,34 @@ 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
+   ### ⛔ HARD GATE — Worktree base MUST equal develop HEAD (blocking, not advisory)
    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:
+   commit (lessons 2026-06-10-build-worktree-stale-base, 2026-06-11-build-worktree-stale-base,
+   2026-06-15-build-worktree-stale-base, 2026-06-16-build-worktree-stale-base,
+   2026-06-17-build-worktree-stale-base, 2026-06-23-build-worktree-stale-base:
+   agents branched hundreds of commits / multiple 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). This is a recurring
+   harness defect, so the check is a **HARD BLOCKING GATE, not a suggestion.**
+
+   **Before dispatching ANY `isolation:"worktree"` wave**, the supervisor MUST run
+   the base==HEAD assertion and MUST abort isolation on any mismatch — there is no
+   "proceed anyway" path:
    ```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 != $DEV_HEAD (it is behind), the wave is UNSAFE — ABORT.
    ```
-   - 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).
+   - **MANDATORY ABORT:** if ANY worktree base != `$DEV_HEAD`, you MUST abort
+     isolation for this wave. Do NOT merge stale worktree output. Do NOT "fast-forward
+     and continue". Do NOT proceed with the isolated wave under any circumstance.
+     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).
+   - This gate is blocking by design: an isolated wave dispatched on a stale base
+     is treated as a build failure, not a warning. Skipping or downgrading this
+     assertion to advisory is a contract violation.
    - 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.
@@ -470,7 +536,7 @@ NEVER run pnpm build or pnpm turbo. Use npx vitest run only.
 - Push after each wave, not just at the end
 - Unattended: NEVER pause — continue automatically
 - Unattended: max 2 retries per task before escalating to advisor
-- Every Agent() dispatch: `model: <routed>` + `max_turns: 70` + `isolation: "worktree"` — non-negotiable. Model is chosen per task per the routing table in Step 7: Sonnet 4.6 for updates/edits, Opus 4.6 for harder coding, Opus 4.8 for design/innovative thought (CS 2.0, brand/UX, architecture). Supervisor logs `model=<chosen> reason=<phrase>` per agent. Exception: validator agent in Step 10 omits isolation; validator model stays `claude-sonnet-4-6` (verification, not generation).
+- Every Agent() dispatch: `model: <routed>` + `max_turns: 70` — non-negotiable. `isolation` is per the dispatch-mode rule in Step 7: NON-isolated (omit `isolation`) for doc-only and single-committer waves; `isolation: "worktree"` ONLY for true parallel MULTI-committer waves, and only after the HARD GATE (worktree base == develop HEAD) passes — a stale-base isolated wave is a build failure. Model is chosen per task per the routing table in Step 7: Sonnet 4.6 for updates/edits, Opus 4.6 for harder coding, Opus 4.8 for design/innovative thought (CS 2.0, brand/UX, architecture). Supervisor logs `model=<chosen> reason=<phrase>` per agent. Exception: validator agent in Step 10 always omits isolation; validator model stays `claude-sonnet-4-6` (verification, not generation).
 - Finding an existing file is NOT task completion — verify it satisfies the spec
 
 ## Capture lessons (exit step)

package/skills/deploy/SKILL.md

@@ -346,6 +346,25 @@ OG_IMG=$(echo "$HEAD" | grep -ioE 'property="og:image"[^>]*content="([^"]*)"' |
 
 **Why this exists (2026-06-05):** life.ai deployed to production with zero social/SEO metadata — no description, no OG, no favicon, no sitemap. HTTP 200 + TLS + content passed; metadata was invisible to the existing gates. This audit catches that class of defect.
 
+## Hotlink referer allowlist — new media.place.fund consumer domains
+
+When onboarding a NEW brand domain that loads assets from `media.place.fund`, add
+that domain to the hotlink-protection Worker's referer allowlist **before
+go-live** (lesson 2026-06-14-deploy-issholiving-referer-hotlink-403: a new brand
+domain served its own HTML fine but every `media.place.fund` image returned 403
+because the hotlink Worker rejected the unknown `Referer`). The image 403 is
+invisible to the HTTP-200 / TLS / metadata gates — they probe the HTML document,
+not the cross-origin asset.
+
+- Add the new origin (apex + `www`, dev + prod) to the Worker's referer allowlist
+  and redeploy the Worker before the brand domain goes live.
+- Verify with an explicit `Referer` probe (NOT a bare curl — a missing Referer can
+  pass while the real browser Referer fails):
+  ```bash
+  curl -s -o /dev/null -w "%{http_code}" -e "https://<new-brand-domain>/" \
+    "https://media.place.fund/<a-known-asset-path>"   # expect 200, not 403
+  ```
+
 ## PUBLISH.md Integration
 
 Every deploy reads `PUBLISH.md` from the app's source root to derive `watch_paths` and to register surfaces in Studio `artifact_registry`.

package/skills/fs-mcp/SKILL.md

@@ -73,6 +73,23 @@ Use URL ingest when the file already exists in cloud storage:
 fs_ingest_url url="https://..." path="docs/source/file.md" expected_sha256="<optional>"
 ```
 
+### ⛔ Ingest discipline (lesson 2026-06-16-collab-claudeai-fs-ingest-race-and-preview-pollution)
+
+- **Prefer synchronous `fs_write` over `fs_ingest_url` for commit-bound bytes.**
+  `fs_ingest_url` can return before the bytes have landed on disk; a `git add`
+  immediately after races the download and silently stages nothing. If you MUST
+  use `fs_ingest_url` for content you will commit, `fs_stat`-poll the target path
+  until size/hash is stable BEFORE staging or committing.
+- **A silent `git add` skip is NOT gitignore.** If `git add <path>` adds nothing
+  and the file is not obviously ignored, do not assume `.gitignore` — confirm with
+  `git check-ignore -v <path>`. No output means it is NOT ignored, so the real
+  cause is a missing/empty/racing file, not an ignore rule.
+- **Never ingest claude.ai preview / Artifacts URLs.** URLs like
+  `*.claude.ai/.../preview` or Artifact render endpoints serve a wrapped,
+  data-omelette-injected document (host chrome, sanitizer rewrites, injected
+  markers) — not the clean source bytes. Ingesting them pollutes the repo. Get
+  the durable source via the GitHub-branch import path (§4) instead.
+
 Use guarded append when appending to a known file:
 
 ```text

package/skills/overnight/SKILL.md

@@ -42,17 +42,38 @@ If the sentinel file does not exist, the Stop hook will NOT block — which mean
 
 Before touching any code, verify the environment is safe:
 
-1. **Clauth daemon alive:**
+1. **Clauth daemon alive AND unlocked:** `/ping` alive is NOT enough — a LOCKED
+   vault answers `/ping` but every `/v/<service>` returns nothing, so credentials
+   silently resolve empty and a long unattended run fails hours later
+   (lesson 2026-06-16-overnight-preflight-clauth-locked-and-shared-develop-cells).
+   Assert `locked:false` before proceeding:
    ```bash
    curl -s http://127.0.0.1:52437/ping
+   curl -s http://127.0.0.1:52437/status | python3 -c "import sys,json; s=json.load(sys.stdin); print('locked:', s.get('locked')); sys.exit(1 if s.get('locked') else 0)"
    ```
-   If not responding: report `BLOCKED: credential daemon offline` and exit. Do not proceed.
+   If not responding OR `locked:true`: report `BLOCKED: credential daemon offline or locked` and exit. Do not proceed.
 
-2. **Git state clean:**
+2. **Git state clean AND no concurrent committer on shared develop:** Overnight
+   shares the `develop` working tree with other cells/sessions. A second session
+   committing concurrently can drop a just-committed file during a rebase
+   (lessons 2026-06-16-overnight-preflight-clauth-locked-and-shared-develop-cells,
+   2026-06-17-build-shared-develop-rebase-dropped-committed-file).
    ```bash
    git status --short
+   git fetch -q origin && git log --oneline @..@{u}   # any rows = origin moved under you
    ```
-   Must be on the development branch with no uncommitted changes. If dirty: commit or stash first.
+   Must be on the development branch with no uncommitted changes. If dirty: commit
+   or stash first. If `origin/develop` is ahead of local at preflight, another
+   session is actively committing — enforce these rules for the whole run:
+   - **Atomic stage+commit by explicit path** — `git add <paths>` then immediate
+     `git commit`; never leave a wide `git add -A` window open while another
+     session may stage.
+   - **Post-push origin verification** — after every push, confirm each committed
+     file actually reached origin (a rebase can silently drop it):
+     ```bash
+     git cat-file -e origin/develop:<path> && echo "OK: <path> on origin" || echo "DROPPED: <path> — re-apply and re-push"
+     ```
+     A `DROPPED` result means re-apply the file on fresh `origin/develop` HEAD and push again.
 
 3. **Baseline review:**
    Run `rdc:review --unattended`. If `REVIEW_STATUS.verdict = "HAS_ISSUES"` and

package/skills/plan/SKILL.md

@@ -39,12 +39,52 @@ description: "Usage `rdc:plan <topic>` — No epic exists and you need architect
    - What tests exist?
    - What's the dependency graph?
 
+   ### ⛔ Before planning "wire fetchers into an existing view" — prove the view can render real data
+   When a work package wires real data into a view that already renders, do NOT
+   assume the view is fetch-ready (lesson 2026-06-16-build-verify-view-prop-api-before-wiring:
+   a view imported its rows from a module-level `../mock/` constant with no data
+   prop, so wiring an API fetcher changed nothing the user saw — and `tsc` + a
+   route-200 probe both passed because they never prove real data renders). Before
+   writing the WP, grep the target view for module-level `../mock/` (or `mockData`,
+   `fixtures/`, hard-coded seed arrays) imports AND confirm a real data prop /
+   loader seam exists:
+   ```bash
+   grep -nE "from ['\"].*/(mock|fixtures)" <target-view-file>
+   ```
+   If the view binds to a module-level mock and exposes no data prop, the WP MUST
+   include removing the mock import and threading a real prop — not just adding a
+   fetcher. "tsc + route 200" is NOT acceptance for "real data renders"; require a
+   negative verifier (mock value is absent from the rendered output).
+
 3. **Make design decisions** — for each major choice:
    - State the decision clearly
    - Document what was chosen and what was rejected
    - Explain WHY (tradeoff rationale)
    - Note consequences and reversibility
 
+   ### Ops / runtime / observability surfaces — ask cloud-DB vs locally-observable, do NOT default to Supabase-SSOT
+   For any ops, runtime, monitoring, or observability surface (process state, log
+   tails, deploy health, queue depth, session liveness, local daemon status),
+   surface the **data-source tradeoff as an explicit AskUserQuestion** rather than
+   reaching for Supabase-as-single-source-of-truth by reflex (lesson
+   2026-06-20-plan-cloud-vs-local-source-tradeoff). Some of this data is only
+   truthfully observable LOCALLY (the process/host itself) and a cloud-DB mirror
+   is stale or lossy; other data genuinely belongs in Supabase. In interactive
+   mode ask which source; in unattended mode escalate via advisor. Record the
+   chosen source and its staleness window as a Design Decision.
+
+   ### New shared `@regen/*` package — force an explicit consume-strategy Design Decision
+   When the plan introduces a NEW shared `@regen/*` package, check who consumes it.
+   If ANY consumer is a non-Next / CJS context (a Node CLI, a PM2 script, a Jest
+   suite, an MCP server, a `.cjs` tool) — not just Next.js apps that transpile ESM
+   workspace packages — the plan MUST contain an explicit **consume-strategy Design
+   Decision** (lesson 2026-06-20-plan-shared-lib-cjs-esm-dist-gap: an ESM-only
+   `dist` shipped fine to Next consumers but `require()` from a CJS consumer threw
+   `ERR_REQUIRE_ESM` at runtime). The decision picks ONE: emit a CJS (or dual
+   ESM+CJS) `dist`, OR have the CJS consumer install a TS/ESM loader (e.g.
+   `tsx`/`ts-node`). Name the consumers and the chosen strategy; do not leave the
+   module format implicit.
+
 4. **Define work packages** — break into agent-dispatchable units:
    - Each work package = one agent assignment
    - No file overlap between packages