@lifeaitools/rdc-skills 0.26.2 → 0.26.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.26.0",
+  "version": "0.26.3",
   "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",
@@ -1574,6 +1574,30 @@
       "enabled_default": true,
       "codeflow_required": false
     },
+    "behavior-audit": {
+      "name": "behavior-audit",
+      "slash": "rdc:behavior-audit",
+      "category": "reporting",
+      "usage": "rdc:behavior-audit <report-dir> [--since-days N] [--latest N] [--reprocess]",
+      "args": {
+        "positional": [{ "name": "report-dir", "required": true, "description": "Bounded directory for the evidence bundle.", "accepts": "path" }],
+        "flags": [
+          { "name": "--since-days", "type": "number", "default": 7, "description": "Only include transcripts modified within the window." },
+          { "name": "--latest", "type": "number", "default": null, "description": "Limit to the newest N sessions per engine." },
+          { "name": "--reprocess", "type": "boolean", "default": false, "description": "Intentionally parse completed hashes again without deleting the ledger." }
+        ]
+      },
+      "requires": ["codeflow", "work-items-rpc"],
+      "produces": ["work_items", ".rdc/reports/"],
+      "default_model": "inherit",
+      "triggers": ["audit transcript calls", "audit codex behavior", "audit claude behavior", "truth gate audit", "review behavior evidence", "why did the agent bypass the gate"],
+      "follows": ["workitems"],
+      "leads_to": ["review"],
+      "sandbox_aware": false,
+      "output_contract": "guides/output-contract.md",
+      "enabled_default": true,
+      "codeflow_required": true
+    },
     "onramp": {
       "name": "onramp",
       "slash": "rdc:onramp",

package/README.md

@@ -181,7 +181,7 @@ Throughout the skills, the following substitutions have been made to make them p
 
 ## Skills Overview
 
-34 MCP skills organized into 8 manifest categories. Nineteen of these also have
+36 MCP skills organized into 8 manifest categories. Nineteen of these also have
 `/rdc:*` command shorthands for Claude Code/plugin callers.
 
 Use `rdc_skill_list` for the authoritative live catalog, including names,
@@ -303,6 +303,7 @@ Boundaries:
 
 ```
 skills/
+  behavior-audit/SKILL.md (governed behavior and policy audit)
   brochure/SKILL.md    (print-quality PDF rendering)
   build/SKILL.md       (dispatch agents in waves — mandatory validator gate)
   channel-formatter/SKILL.md (channel-native formatting and content packs)

package/RELEASE.md

@@ -27,11 +27,16 @@ git checkout master
 git pull --ff-only origin master
 git merge <feature-branch> --no-edit
 
-# 2. Bump the version
+# 2. Bump the version — package.json AND the plugin manifest, they must match.
+#    rdc-skills-self-test fails the whole run (plugin manifest FAIL) if they drift,
+#    and .claude-plugin/plugin.json ships inside the published npm package, so a
+#    stale plugin.json version is a real defect in the release, not a lint nit.
 npm version patch|minor|major --no-git-tag-version
+# then hand-edit .claude-plugin/plugin.json's top-level "version" field to match —
+# there is no script for this yet, only the self-test catches drift after the fact.
 
 # 3. Commit, tag, and push
-git add package.json package-lock.json
+git add package.json .claude-plugin/plugin.json
 git commit -m "release: v$(node -e \"console.log(require('./package.json').version)\")"
 git tag "v$(node -e \"console.log(require('./package.json').version)\")"
 git push origin master --tags
@@ -43,6 +48,9 @@ npm view @lifeaitools/rdc-skills version
 npm install -g @lifeaitools/rdc-skills@latest
 npm list -g @lifeaitools/rdc-skills --depth=0
 rdc-skills-self-test
+# ^ run this LAST and read the verdict line, not just the section pass counts —
+#   a plugin-manifest version mismatch prints as a single top-line FAIL above the
+#   skill/guide tables, which all pass independently of it. Exit code 1 on drift.
 ```
 
 ## Public MCP release gate
@@ -61,11 +69,19 @@ The public `/health` version must equal the released npm version and its skill
 count must match the packaged catalog. The local installer never restarts or
 deploys that endpoint.
 
-The Vultr host checks out this repository at `/srv/regen/rdc-skills`. Install or
-refresh its standalone systemd unit after pulling `master`:
+The Vultr host checks out this repository at `/srv/regen/rdc-skills` — it runs
+straight from the checkout (no `npm install`), so `/health`'s `git_sha` comes
+from `bin/rdc-skills-mcp.mjs`'s runtime `git rev-parse HEAD` fallback, NOT a
+stamped `git-sha.json` (that file is `.gitignore`d on purpose — it's a
+pack-time-only artifact for npm-installed copies; see the comment above its
+`.gitignore` entry). `install-systemd.sh` alone does not restart the running
+process. After pulling `master`:
 
 ```bash
-sudo ./deploy/install-systemd.sh
+git pull --ff-only origin master
+sudo ./deploy/install-systemd.sh        # re-verify/re-enable the unit config
+sudo systemctl restart rdc-skills-mcp.service   # actually load the new commit
+curl -fsS https://rdc-skills.regendevcorp.com/health   # confirm git_sha == new HEAD
 ```
 
 Port `3110` is reserved for this public MCP ingress. Application fleet manifests

package/commands/build.md

@@ -71,12 +71,21 @@ Read the task title and description, then:
 
 ## Procedure
 
-1. **Load the epic:**
+1. **Load the epic and its durable admission decisions:**
    ```sql
-   SELECT get_work_items_by_epic('<epic-id>', 'todo');
+   SELECT get_work_items_by_epic('<epic-id>');
    ```
+   - Read `design_review_state` and `status` for every executable child.
+   - Only `automatic_approved`, `human_approved`, or legacy `not_required` rows may be considered for dispatch.
+   - For `pending`, `needs_human`, or `rejected`, write an `admission_refocus` receipt, keep the child blocked, and route it to the reviewer/planner. **Do not dispatch it, retry it, or call the epic complete.**
    - Interactive (no args): show open epics, ask which to build
    - Unattended (no tasks found): escalate via advisor tool
+   - **Read the epic's `plan_ref`, `spec_ref`, `architecture_ref`, and `scoping_statement` fields** (returned on the epic row itself). `scoping_statement` bounds what this build may touch — do not silently expand past it. If `architecture_ref` is set, this epic crosses an architectural boundary: read that doc now, before classifying or dispatching any task, and carry it into every agent prompt in step 7.
+
+1a. **Run the durable CodeFlow supervisor before each wave and after every gate-changing action.**
+   - Invoke `runOrchestrator()` with the project manifest, `SupabaseStateStore`, and the real phase dispatcher. It is the sole authority for resuming/refocusing a phase DAG; do not reconstruct waves by hand from task prose.
+   - A returned `admission_refocus` or `pipeline_blocked` is a durable hold, not a failed attempt to work around. Preserve its task state and route the required Design Review or validator closure.
+   - Only a returned `pipeline_complete` whose phase tasks are all design-review admitted **and** durably `done` permits an epic completion claim. If the project lacks a real dispatcher/manifest, report `BLOCKED: CodeFlow supervisor entrypoint unavailable` rather than emulating completion.
 
 2. **CHECK FOR EXISTING WORK (mandatory — never skip):**
    ```sql
@@ -103,7 +112,7 @@ Read the task title and description, then:
 
 5. **Classify each task** → assign agent type from the table above.
 
-6. **Group tasks into waves** — parallelize tasks with no file overlap:
+6. **Use the supervisor-resolved waves** — parallelize only phases returned by `runOrchestrator()` after its durable admission check:
    - Wave 1: independent tasks (different packages/files)
    - Wave 2: tasks that depend on Wave 1 outputs
    - Wave 3: integration tasks
@@ -114,7 +123,9 @@ Read the task title and description, then:
      - `"Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md first (fallback: .rdc/guides/agent-bootstrap.md), then {PROJECT_ROOT}/.rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md) before starting."`
      - Specific files to create/modify
      - Exact deliverables and commit message
+     - The epic's `scoping_statement` — explicit boundary on what this task may and may not touch
      - `"NEVER run pnpm build/test. NEVER modify files outside your scope."`
+   - **If the epic's `architecture_ref` is set:** include `"Read <architecture_ref> before implementing. Your task's checklist requires a checked architecture-fidelity-<slug> row before this item can close — when you tick it, its evidence must cite the specific section/boundary of <architecture_ref> your implementation conforms to, not just 'done'."` A task under an `architecture_ref` epic will hard-fail at the exit gate (step 9) without this row checked with real evidence.
    - Use `run_in_background: true` for parallel execution
    - NEVER let agents overlap on the same files
 
@@ -133,6 +144,8 @@ Read the task title and description, then:
    - Verify commit landed on the development branch
    - Push to origin *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
    - Ensure the agent submitted `implementation_report.codeflow_post`, then set the work item to `review`; the validator closes `done`
+   - Re-invoke `runOrchestrator()` after the durable status/gate update. A task in `review` remains incomplete even when its phase gate passed.
+   - **If the epic's `architecture_ref` is set:** before the validator attempts `done`, confirm the task's checklist has a checked `architecture-fidelity-*` row with real evidence (a cited doc section, not a bare "matches"). `update_work_item_status(..., 'done')` will hard-reject otherwise — catching this here avoids a wasted validator round-trip.
    - Continue to next wave
 
    **If an agent fails:**
@@ -160,7 +173,7 @@ Read the task title and description, then:
         echo "[RDC_TEST] skipping git push origin {development-branch}"
       fi
       ```
-    - Update epic version: `bump_epic_version()`
+    - Re-invoke `runOrchestrator()` and require its `pipeline_complete` receipt before `bump_epic_version()` or any epic completion claim. A clean code review or green test suite is not a substitute for admitted, validator-closed work items.
     - Report summary with verification evidence quoted
 
 ## Agent TDD Requirements
@@ -178,6 +191,7 @@ NEVER run pnpm build or pnpm turbo. Use npx vitest run only.
 - NEVER run `pnpm build` (crashes system) — code only
 - Every agent reads its guide file — no exceptions
 - Update Supabase work items IN REAL TIME — not batch at end
+- **Never dispatch, resume, or complete around `design_review_state`; the durable database result and `runOrchestrator()` receipt win over an agent's narrative**
 - Push after each wave, not just at the end
 - Unattended: NEVER pause — continue automatically
 - Unattended: max 2 retries per task before escalating to advisor

package/commands/handoff.md

@@ -105,6 +105,19 @@ SELECT insert_work_item(
   p_source      := 'planning'
 );
 
+-- Immediately populate governance refs — the handoff's plan doc IS the plan_ref/spec_ref.
+-- Set architecture_ref ONLY when this handoff crosses an architectural boundary (storage
+-- authority, process topology, auth boundary, deployment model, persistence, service
+-- ownership, public contract); leave it NULL for ordinary feature work, or every task
+-- below gets held for a review it doesn't need.
+SELECT set_epic_governance_refs(
+  p_epic_id := '<epic-uuid>'::uuid,
+  p_plan_ref := '.rdc/plans/<topic-slug>.md',
+  p_spec_ref := '.rdc/plans/<topic-slug>.md',
+  p_architecture_ref := '<docs/systems/<system>/ARCHITECTURE.md or NULL>',
+  p_scoping_statement := '<one paragraph: what is explicitly in scope and what is explicitly out of scope>'
+);
+
 -- Create tasks (one per work package)
 SELECT insert_work_item(
   p_title       := '<Package Name>',
@@ -121,6 +134,9 @@ Est: <hours>',
   p_labels      := ARRAY['<label>'],
   p_estimated_hours := 2,
   p_source      := 'planning'
+  -- If the epic has architecture_ref set, also add a required
+  -- architecture-fidelity-<slug> checklist row via p_checklist here — the exit gate
+  -- hard-rejects `done` on any task under an architecture_ref epic that lacks one.
 );
 ```
 

package/commands/overnight.md

@@ -101,6 +101,7 @@ rdc:plan <epic-id> --unattended
 
 Check `PLAN_STATUS.task_count > 0` before continuing.
 If 0 tasks created: escalate via advisor, then skip if still unresolved.
+If `PLAN_STATUS.held_for_design_review > 0`: do not silently promote those tasks to todo. Log the held task IDs and their durable assessment, request human Design Review, and continue only with the independently admitted portion of the epic.
 
 ### 3c. Build
 
@@ -114,6 +115,7 @@ Agents receive the relevant guide file from `.rdc/guides/` (fallback: `.rdc/guid
 
 After each wave: check `BUILD_STATUS`. If `escalated: true`, log the escalation
 in the overnight doc and continue — don't stop the loop.
+After each wave and after every resumed epic, require the `runOrchestrator()` receipt from `rdc:build`. `admission_refocus` or `pipeline_blocked` means the epic is held for durable Design Review or validator closure; log that state and do not hand-reconstruct a dispatch wave.
 
 ### 3d. Review
 
@@ -122,7 +124,7 @@ rdc:review --unattended
 ```
 
 Check `REVIEW_STATUS.verdict`:
-- `"CLEAN"`: mark epic `done` in work_items, push, continue to next epic
+- `"CLEAN"`: re-run the durable CodeFlow supervisor. Mark an epic `done` only when its receipt is `pipeline_complete` and every executable child is design-review admitted and validator-closed (`status = done`); otherwise preserve the epic/task hold and log `admission_refocus` or `pipeline_blocked`.
 - `"HAS_ISSUES"` with `escalations > 0`: log issues, push what's clean, continue
 - `"HAS_ISSUES"` with `escalations = 0` (all auto-fixed): push, continue
 
@@ -215,6 +217,7 @@ Provide the advisor with:
 - NEVER let agents overlap on the same files
 - Push after every epic, not just at the end
 - Update Supabase work items in real time throughout
+- **A clean review never overrides a durable Design Review hold, an incomplete checklist, or missing validator closure**
 - Max 2 hours per epic — if exceeded, skip and log `TIMEOUT`
 - If credential daemon goes down mid-session: write current state to overnight doc, push, exit gracefully
 - If git push fails: log the failure, attempt rebase, retry once — do not force push

package/commands/plan.md

@@ -107,6 +107,11 @@ description: >-
    - Include the guide file path (from `.rdc/guides/`, fallback `.rdc/guides/`) in each work package description
    - Include any relevant architecture doc, context file, or package CLAUDE.md the agent must read
    - Estimate: small (1 agent, <500 LOC), medium (1 agent, 500-1500 LOC), large (needs splitting)
+   - Attach a **Design Review contract** to every executable package. It must contain:
+     - architecture alignment: registered architecture-evidence reference(s), declared target boundary, and a concrete alignment claim;
+     - completeness: independently observable acceptance criteria plus at least one required `decomp-*` and `test-*` checklist row; and
+     - proportionality: estimated files/LOC, declared surfaces, and change kind.
+   - Do not invent architecture evidence. Missing, unregistered, broad-refactor, multi-surface, or disproportionate contracts are intentionally routed to human Design Review.
 
 6. **Write plan doc** to `.rdc/plans/<topic-slug>.md` (fallback: `.rdc/plans/<topic-slug>.md` if `.rdc/` does not exist):
    ```markdown
@@ -127,14 +132,19 @@ description: >-
 
 7. **Create Supabase epic + child tasks:**
    - Epic via `insert_work_item(p_item_type := 'epic', ...)`
-   - One task per work package via `insert_work_item(p_parent_id := <epic_id>, ...)`
+   - Immediately call `set_epic_governance_refs(p_epic_id, p_plan_ref := '.rdc/plans/<topic-slug>.md', p_spec_ref := '.rdc/plans/<topic-slug>.md', p_architecture_ref := '<ARCHITECTURE.md path or NULL — set only when this plan crosses an architectural boundary>', p_scoping_statement := '<in/out of scope, one paragraph>')` so `rdc:build`/`rdc:overnight`/`rdc:fixit`/`rdc:refactor` never have to guess or stall on these fields
+   - One task per work package only through `upsert_admitted_work_item(...)`, never a direct `work_items` write. Supply a stable source fingerprint, the package checklist, and the Design Review contract from Step 5.
+   - Read the durable result for each package:
+     - `dispatchable: true` / `automatic_approved` → task may become `todo`;
+     - `dispatchable: false` / `needs_human` or `pending` → keep the task `blocked`, label it `needs-human-design-review`, and include the assessment in the plan status.
+   - If (and only if) the epic's `architecture_ref` is set, each task's checklist passed to `upsert_admitted_work_item` MUST also include one required `architecture-fidelity-<slug>` row naming the specific architecture doc + boundary — the exit gate hard-rejects `done` on any task under an `architecture_ref` epic missing this row. Do not add it under an epic with no `architecture_ref` — that holds ordinary work for a review it doesn't need.
    - Set priorities: urgent/high/normal based on sequencing
 
 8. **Report results:**
    - Interactive: present the plan for approval before building
    - Unattended: skip approval, proceed immediately, emit status block:
      ```
-     PLAN_STATUS: { epic_id, task_count, doc_path, waves, source_docs_read: [list], architecture_conflicts: [] }
+     PLAN_STATUS: { epic_id, task_count, dispatchable_task_count, held_for_design_review, doc_path, waves, source_docs_read: [list], architecture_conflicts: [] }
      ```
 
 ## Unattended Escalation
@@ -153,6 +163,7 @@ choose the most conservative/reversible approach and document the decision.
 - Each work package must be independently executable by an agent
 - No file overlap between work packages
 - Include test requirements in every work package
+- **No executable work item is dispatchable without a durable Design Review decision; a planner cannot self-approve by supplying prose-only evidence**
 - Reference affected CLAUDE.md files and architecture docs in each work package description
 - Reference the relevant guide file from `.rdc/guides/` (fallback: `.rdc/guides/`) for agent context
 - Always list source docs read in the output doc header and status block

package/commands/workitems.md

@@ -39,6 +39,18 @@ SELECT insert_work_item(
   p_labels      := ARRAY['system-label'],
   p_source      := 'planning'
 );
+
+-- Immediately populate governance refs. architecture_ref stays NULL unless this epic
+-- crosses an architectural boundary (storage authority, process topology, auth boundary,
+-- deployment model, persistence, service ownership, public contract) — setting it holds
+-- every child task for a required architecture-fidelity-* checklist row at close time.
+SELECT set_epic_governance_refs(
+  p_epic_id := '<epic-uuid>'::uuid,
+  p_plan_ref := '.rdc/plans/<n>.md or NULL',
+  p_spec_ref := '.rdc/plans/<n>.md or NULL',
+  p_architecture_ref := NULL,
+  p_scoping_statement := '<one paragraph: what is in scope and what is explicitly out>'
+);
 ```
 
 ## Create Task

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -35,7 +35,7 @@
     "rdc-design": "node scripts/rdc-design-cli.mjs",
     "test:hooks": "node scripts/test-rdc-hooks.mjs",
     "test:truth-gate": "node tests/run-evidence-gate.test.mjs && node tests/work-item-exit-gate-l2.test.mjs && node tests/work-item-exit-gate-l3.test.mjs && node tests/require-work-item-on-commit.test.mjs && node tests/harness-gates.test.mjs",
-    "test:acceptance": "node tests/acceptance.test.mjs && node tests/install-rdc-skills.test.mjs && node tests/help-surface.test.mjs && node tests/manifest-contract-fields.test.mjs && node tests/skill-test-matrix.test.mjs && node tests/curl-surface.test.mjs",
+    "test:acceptance": "node tests/acceptance.test.mjs && node tests/install-rdc-skills.test.mjs && node tests/help-surface.test.mjs && node tests/manifest-contract-fields.test.mjs && node tests/skill-test-matrix.test.mjs && node tests/completion-gate-supervisor-admission.test.mjs && node tests/curl-surface.test.mjs",
     "acceptance": "node scripts/acceptance.mjs --changed",
     "test:mcp": "node tests/mcp.test.mjs",
     "test:mcp:remote": "node tests/mcp.test.mjs --remote",

package/scripts/validate-publish-manifests.js

@@ -27,6 +27,7 @@ const fs = require('fs');
 const path = require('path');
 const https = require('https');
 const http = require('http');
+const { execFileSync } = require('child_process');
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -68,7 +69,35 @@ for (let i = 0; i < args.length; i++) {
 // Constants
 // ---------------------------------------------------------------------------
 
-const MONOREPO_ROOT = 'C:/Dev/regen-root';
+/**
+ * Resolve the regen-root monorepo checkout this run should validate against.
+ *
+ * 2026-07-26 (lesson 2026-07-26-deploy-worktree-validator-root): hardcoding
+ * 'C:/Dev/regen-root' made every check run against the main tree even when
+ * this validator was invoked from a registered worktree lane
+ * (`C:/Dev/regen-root.wt/<lane>`), so a newly-landed app's PUBLISH.md read as
+ * "not found" though the file existed on the lane's own branch.
+ *
+ * Resolution order: explicit override env var, then `git rev-parse
+ * --show-toplevel` from the caller's cwd (works for the main tree AND any
+ * worktree lane), then the historical default as a last resort.
+ */
+function resolveMonorepoRoot() {
+  if (process.env.REGEN_ROOT) return process.env.REGEN_ROOT;
+  if (process.env.PROJECT_ROOT) return process.env.PROJECT_ROOT;
+  try {
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    }).trim();
+    if (top) return top;
+  } catch {
+    // Not inside a git checkout (or git unavailable) — fall through to the default.
+  }
+  return 'C:/Dev/regen-root';
+}
+
+const MONOREPO_ROOT = resolveMonorepoRoot();
 const CLAUTH_BASE = 'http://127.0.0.1:52437';
 
 // Ordered list of root-relative prefixes to probe when looking for app source

package/skills/behavior-audit/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: rdc:behavior-audit
+description: "Usage `rdc:behavior-audit <report-dir> [--since-days N] [--latest N] [--reprocess]` — produces a bounded, redacted Claude/Codex transcript evidence bundle, incrementally skips completed transcript hashes, and aligns candidate behavior problems to shared truth-governance rules."
+---
+
+> **OUTPUT CONTRACT:** Begin and end with the same checklist. Do not call an audit clean, complete, or compliant without the evidence-bundle manifest and an independent validator decision.
+
+# rdc:behavior-audit — Cross-Engine Truth and Behavior Audit
+
+## When to Use
+
+- Audit transcript calls, truth-gate behavior, premature closure, evidence provenance, or cross-engine enforcement drift.
+- Create a bounded redacted evidence bundle for a behavior-governance work item.
+- Do not use this skill to alter source transcripts, deploy services, or self-certify a behavioral conclusion.
+
+## Required Inputs
+
+- `<report-dir>`: a bounded output directory, for example `reports/behavior-audit/2026-08-08`.
+- Optional `--since-days N`, `--latest N`, or `--reprocess` scope controls.
+- The current repository must contain `scripts/transcript_call_matrix.py`; block if it is absent rather than inventing a collector.
+
+## Procedure
+
+1. Create or claim a work item before collection. Its checklist must cover scope, provenance, redaction, rule alignment, independent review, and validator closure.
+2. Resolve the repository root with `git rev-parse --show-toplevel`, then run CodeFlow context before reading project sources.
+3. Run the collector from the repository root: `python -B scripts/transcript_call_matrix.py --since-days 7 --format none --report-dir <report-dir> --processing-ledger .rdc/state/transcript-call-processing.json`.
+4. Require `manifest.json`, `tool-call-matrix.html`, `tool-call-totals.csv`, `locators.jsonl`, and `problems.jsonl` in `<report-dir>`.
+5. Confirm every locator's transcript SHA matches its processed session and that secret-shaped material is absent from problem excerpts.
+6. Classify each finding as an observation, causal hypothesis, intervention, or validator decision; do not elevate an observation into a diagnosis.
+7. Align findings to `mission-contract-non-bypassable`, `independent-validator`, `mandatory-independent-review`, `evidence-provenance`, `no-premature-completion`, and `cross-engine-parity`.
+8. Dispatch independent review and a separate validator for collector or skill changes. The collecting executor cannot close the work item.
+
+## Decision Rules
+
+- An empty evidence set is a validator decision (`not_applicable`), not executor proof of compliance.
+- A failed collector or incomplete report leaves transcript hashes unmarked; repair and rerun.
+- A changed transcript hash is new evidence even if the filename and session ID are unchanged.
+- Report structural facts until a verifier attests broader behavior claims.
+- Never deploy, promote, alter enforcement hooks, or rewrite transcripts as part of this audit unless a linked work item explicitly authorizes it.

package/skills/behavior-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Behavior Audit"
+  short_description: "Audit Claude and Codex behavior against shared rules."
+  default_prompt: "Run a behavior audit for the last seven days and write the evidence bundle to a report directory."

package/skills/build/SKILL.md

@@ -72,10 +72,20 @@ Read the task title and description, then:
 
 ## Procedure
 
-1. **Load the epic and run pre-flight gate:**
+1. **Load the epic, durable admission decisions, and run the pre-flight gate:**
    ```sql
-   SELECT get_work_items_by_epic('<epic-id>', 'todo');
+   SELECT get_work_items_by_epic('<epic-id>');
    ```
+   - Read `design_review_state` and `status` for every executable child.
+   - Only `automatic_approved`, `human_approved`, or legacy `not_required` rows may be considered for dispatch.
+   - For `pending`, `needs_human`, or `rejected`, write an `admission_refocus` receipt, keep the child blocked, and route it to the reviewer/planner. **Do not dispatch it, retry it, or call the epic complete.**
+
+1a. **Run the durable CodeFlow supervisor before each wave and after every gate-changing action.**
+   - Invoke `runOrchestrator()` with the project manifest, `SupabaseStateStore`, and the real phase dispatcher. It is the sole authority for resuming/refocusing a phase DAG; do not reconstruct waves by hand from task prose.
+   - A returned `admission_refocus` or `pipeline_blocked` is a durable hold, not a failed attempt to work around. Preserve its task state and route the required Design Review or validator closure.
+   - Only a returned `pipeline_complete` whose phase tasks are all design-review admitted **and** durably `done` permits an epic completion claim. If the project lacks a real dispatcher/manifest, report `BLOCKED: CodeFlow supervisor entrypoint unavailable` rather than emulating completion.
+
+   **Read the epic's `plan_ref`, `spec_ref`, `architecture_ref`, and `scoping_statement`** (columns on the epic row). `scoping_statement` bounds what this build may touch. If `architecture_ref` is set, this epic crosses an architectural boundary — read that doc now, before classifying or dispatching any task, and carry it into every agent prompt below.
 
    **Session lock — claim the epic immediately (before any agent dispatch):**
 
@@ -103,6 +113,7 @@ Read the task title and description, then:
    | Plan doc missing `## Checklist Quality Gate` with `verdict: PASS` | → Invoke `rdc:plan` on this epic. Do NOT dispatch agents. |
    | Any implementation task lacks `decomp-*` items, has < 10 attested rows, or leaves a declared surface (screen/api/db/tool) uncovered | → Invoke `rdc:plan` on this epic. Coarse/under-decomposed checklists cannot be safely dispatched. |
    | Any `decomp-*` item lacks route/file, action, expected result, or evidence artifact | → Invoke `rdc:plan` on this epic. Do NOT dispatch agents. |
+   | Epic has `architecture_ref` set and any implementation task's checklist lacks a required `architecture-fidelity-*` row | → Invoke `rdc:plan` on this epic. That task will hard-fail the exit gate at close regardless of build quality — catch it here, not after a wasted agent run. |
    | Tasks exist and have descriptions | → Continue with build. |
 
    **Re-planning is not a failure — it is correct behavior.** The build skill is the last gate before agent dispatch; catching an under-specified epic here is cheaper than a wasted agent run.
@@ -296,7 +307,7 @@ Read the task title and description, then:
     The agent must complete every item on this checklist and return it checked off in AGENT_COMPLETE.
     A checklist with unchecked items = incomplete work. Do not proceed to next wave with unchecked items.
 
-6. **Group tasks into waves** — parallelize tasks with no file overlap:
+6. **Use the supervisor-resolved waves** — parallelize only phases returned by `runOrchestrator()` after its durable admission check:
    - Wave 1: independent tasks (different packages/files)
    - Wave 2: tasks that depend on Wave 1 outputs
    - Wave 3: integration tasks
@@ -488,6 +499,10 @@ Read the task title and description, then:
        - test-contract-xxx: <description> → verify the export/type/shape exists
        Tick each item as you complete it. Do NOT batch — tick immediately after each verification.
        ```
+     - **If the epic's `architecture_ref` is set**, the task's checklist carries a required `architecture-fidelity-*` row. Include it verbatim and instruct the agent:
+       ```
+       ARCHITECTURE FIDELITY — this epic crosses an architectural boundary (<architecture_ref>). Read that doc before implementing. Before ticking architecture-fidelity-<slug>, your implementation must actually conform to it — tick it via update_checklist_item(..., p_actor_role := 'agent') with evidence that cites the specific section/boundary, not a bare "done". update_work_item_status(..., 'done') hard-rejects this task without this row checked.
+       ```
    - Use `run_in_background: true` for parallel execution
    - NEVER let agents overlap on the same files
 
@@ -543,6 +558,7 @@ Read the task title and description, then:
 
    - Resolve any conflicts before proceeding — do not skip
    - Worker agents set items to `review` — **do NOT close to `done` yet**
+   - Re-invoke `runOrchestrator()` after the durable status/gate update. A task in `review` remains incomplete even when its phase gate passed.
    - After all branches merged, push once:
      ```bash
      if [ "$RDC_TEST" != "1" ]; then
@@ -633,7 +649,7 @@ Read the task title and description, then:
 
 11. **After verification passes:**
     - All wave commits are already on develop and pushed (Step 9 pushes after each wave merge).
-    - Update epic version: `bump_epic_version()`
+    - Re-invoke `runOrchestrator()` and require its `pipeline_complete` receipt before `bump_epic_version()` or any epic completion claim. A clean code review or green test suite is not a substitute for admitted, validator-closed work items.
     - Report summary with verification evidence quoted
 
 ## Agent TDD Requirements
@@ -651,6 +667,7 @@ NEVER run pnpm build or pnpm turbo. Use npx vitest run only.
 - NEVER run `pnpm build` (crashes system) — code only
 - Every agent reads its guide file — no exceptions
 - Update Supabase work items IN REAL TIME — not batch at end
+- **Never dispatch, resume, or complete around `design_review_state`; the durable database result and `runOrchestrator()` receipt win over an agent's narrative**
 - Push after each wave, not just at the end
 - Unattended: NEVER pause — continue automatically
 - Unattended: max 2 retries per task before escalating to advisor

package/skills/deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rdc:deploy
-description: "Usage `rdc:deploy <slug> [new|diagnose|audit|promote|convert] [--fix|--hotfix <sha>]` or `rdc:deploy maintenance <service>` — Deploy applications or operate a private Coolify infrastructure service with guarded, internal-only checks."
+description: "Usage `rdc:deploy <slug> [promote|diagnose|audit|convert]` — registry-resolved PM2 development deployment and Coolify production promotion through clauth's bearer-authenticated job control plane, with status receipts and mandatory content gates."
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
@@ -8,14 +8,14 @@ description: "Usage `rdc:deploy <slug> [new|diagnose|audit|promote|convert] [--f
 > One checklist upfront, updated in place, shown again at end with a 1-line verdict.
 
 
-# rdc:deploy — Coolify Operations
+# rdc:deploy — Bearer Deployment Control Plane
 
 **READ FIRST:** `guides/output-contract.md`. Checklist-only output. No narration.
 No raw MCP dumps. No UUIDs unless asked.
 
 > **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
 >
-> *Under `$RDC_TEST=1`:* Modes 1 (deploy), 2 (new), and 5 (promote) are **entirely skipped** — echo `[RDC_TEST] skipping Coolify deploy/create/promote` and mark every `[ ]` line in those checklists as `[~]`. Modes 3 (diagnose) and 4 (audit without `--fix`) are **read-only and run normally**. Mode 4 with `--fix` skips all remediation — echo `[RDC_TEST] skipping audit --fix remediation` and report findings only. Registry SELECTs, Coolify status reads, HTTP gate probes, TLS checks, and DNS lookups are NOT destructive and run normally. Anything that writes (create app, set watch_paths, deploy trigger, **PR/admin-merge to main**, env var write, DNS write, CF cache purge, registry UPDATE/INSERT) is gated.
+> *Under `$RDC_TEST=1`:* Modes 1 (PM2 dev deploy), 2 (new), and 5 (Coolify promote) are **entirely skipped** — echo `[RDC_TEST] skipping PM2 deploy/create/Coolify promote` and mark every `[ ]` line in those checklists as `[~]`. Modes 3 (diagnose) and 4 (audit without `--fix`) are **read-only and run normally**. Mode 4 with `--fix` skips all remediation — echo `[RDC_TEST] skipping audit --fix remediation` and report findings only. Registry SELECTs, Coolify status reads, HTTP gate probes, TLS checks, and DNS lookups are NOT destructive and run normally. Anything that writes (create app, set watch_paths, deploy trigger, **PR/admin-merge to main**, env var write, DNS write, CF cache purge, registry UPDATE/INSERT) is gated.
 
 ## When to Use
 - Project lead says "deploy", "ship it", "push to production", "update the server"
@@ -28,8 +28,8 @@ No raw MCP dumps. No UUIDs unless asked.
 
 ## Arguments
 
-- `rdc:deploy <slug>` — deploy existing app (latest commit on its watched branch)
-- `rdc:deploy <slug> <build-id>` — deploy specific commit/tag
+- `rdc:deploy <slug>` — submit the registered `develop` deployment to the PM2 dev target
+- `rdc:deploy <slug> <ref>` — submit one registered manifest ref (never arbitrary shell or repository input)
 - `rdc:deploy <slug> promote` — promote the verified `develop` change for this app to production (Mode 5)
 - `rdc:deploy <slug> promote --hotfix <sha>` — promote a specific commit (cherry-pick just that sha to `main`)
 - `rdc:deploy <slug> convert` — convert a prod app's runtime in place from static→Next (Mode 6); use when dev is Next but prod is still a static Coolify build
@@ -42,25 +42,24 @@ No raw MCP dumps. No UUIDs unless asked.
 
 ## Modes
 
-### Mode 1 — deploy <slug> [build-id]
+### Mode 1 — deploy <slug> [ref]
 
 ```
-rdc:deploy: <slug> → <domain>
+rdc:deploy: <slug> → PM2 dev target
 [ ] Registry lookup (slug, uuid, branch, type, env_vars_needed)
 [ ] Runtime-source guard: if the source being deployed is static (`sites/<name>`, nixpacks/static) but the registry `runtime` for <slug> is `next`, BLOCK — never deploy a flat/static source over a Next app. A static prototype deploys only under its OWN slug (never an existing Next app's slug), dev only. Changing a slug's runtime is architectural. (`.claude/rules/production-stack-nextjs.md`)
-[ ] Git state verified (branch matches Coolify, commit pushed)
-[ ] Build-id resolved (default: HEAD of watched branch)
-[ ] Env vars present in Coolify (compare to registry)
-[ ] Type-specific preflight (see docs/runbooks/coolify-deploy-checklist.md)
+[ ] Git state verified (registered ref is pushed to origin)
+[ ] Dev deployment manifest resolved (application, repo path, fixed build argv, PM2 name, allowed ref, health URL)
+[ ] Local clauth retrieves `vultr-ops-api-token` internally; bearer is never printed or passed by an agent
 [ ] Mandatory pre-deploy code-review (pr-review-toolkit:code-reviewer on `git diff <last-deployed-sha>..HEAD` for this app's paths). Block deploy on `critical`/`high` findings; record `medium`/`low` and proceed.
 [ ] PUBLISH.md read from app root (warn if absent; fail if present but invalid)
 [ ] watch_paths derived from PUBLISH.md surfaces (union of all surface watch_paths arrays) and updated in app_deployments
-[ ] Deploy triggered
-[ ] Deployment reached "finished" state
+[ ] `clauth ops deploy --endpoint <control-plane> --application <slug> --ref <registered-ref>` accepted (202)
+[ ] Job polled at `GET /v1/ops/jobs/<id>` to terminal state; receipt proves checkout SHA, build, PM2 reload, and health probe
 [ ] Gate: HTTP 200
 [ ] Gate: TLS valid (no SSL cipher mismatch)
 [ ] Gate: cache headers correct on HTML
-[ ] Gate: container running on declared port
+[ ] Gate: named PM2 process is online at its declared port
 [ ] Gate: metadata audit (see § Metadata Audit below) — warn on gaps, do not block deploy
 [ ] Cloudflare cache purged (if proxied)
 [ ] artifact_registry INSERT per PUBLISH.md surface (if PUBLISH.md present)
@@ -68,27 +67,19 @@ 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)
+#### Static PM2 dev sites — bearer job + served-content 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.
+For a **static** PM2 dev site, a successful `git push` is not deployment proof:
+the formerly unreliable webhook could leave the host working tree and committed
+`dist/` stale while HTTP still returned 200. The agent MUST submit the same
+manifest-scoped `clauth ops deploy` job used by every other dev runtime, then
+record its checkout SHA, declared build, PM2 reload, and health receipt.
 
-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.
+Agents MUST NOT retrieve `vultr-dev-ssh`, stage private keys, run raw SSH, reset
+the host checkout, or invoke PM2 directly. If a served-asset hash or content
+marker does not match the declared build after the job reaches `succeeded`, mark
+the deployment verification failed and use `rdc:deploy <slug> diagnose`; only
+the server-operations recovery procedure may perform host-level repair.
 
 ### Mode 2 — new <slug>
 
@@ -246,14 +237,13 @@ rdc:deploy promote: <slug> → <prod-domain>
 ✅ rdc:deploy promote: <slug> live in prod — <changed-string> verified
 ```
 
-**The explicit Coolify trigger (the whole point — do not skip):**
-```bash
-_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
-# Correct endpoint is GET /api/v1/deploy?uuid= — NOT POST /applications/<uuid>/deploy (that 404s)
-curl -s -H "Authorization: Bearer $_COOLIFY" \
-  "$DEPLOY_API_BASE/api/v1/deploy?uuid=<PROD_UUID>&force=true"
-# → {"deployments":[{"deployment_uuid":"...","message":"...deployment queued."}]}
-```
+**The explicit Coolify trigger (the whole point — do not skip):** submit
+`clauth ops promote --endpoint <control-plane> --application <registered-coolify-uuid>`.
+The local client retrieves `vultr-ops-api-token` internally; the server-side
+allowlist owns the Coolify UUID and keeps `coolify-api` out of agent inputs and
+transcripts. Poll the returned job or subscribe to
+`GET /v1/ops/jobs/<id>/events` until the redacted receipt reaches a terminal
+state.
 
 **Why each guard exists (lessons from 2026-06-05 EF Hooper promote):**
 - `main` branch protection rejects PR merge without `--admin`; a raw `git push …:main` is blocked by the main-push hook → must go branch → PR → admin-merge.
@@ -487,52 +477,27 @@ ON CONFLICT (entity_slug, surface_id) DO UPDATE SET
 
 If the INSERT fails, surface the failure in the deploy output but **do NOT roll back the deploy**. The artifact registry is a post-deploy record, not a deploy gate.
 
-## Coolify Access — clauth + REST API
+## Control-plane Access — clauth bearer jobs
 
-All Coolify operations use the clauth daemon and the Coolify REST API directly.
-There is no Coolify MCP server. Do not reference `@masonator/coolify-mcp`.
+There is no Coolify MCP server. Agent-facing deploy and promotion operations use
+the clauth control plane, not raw PM2, SSH, or the Coolify deploy-trigger API.
+The local fixed client obtains `vultr-ops-api-token` from local clauth and sends
+it as `Authorization: Bearer`; it never prints the token.
 
 ```bash
-# Get token (plain text — no JSON parsing needed)
-_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
-
-# List applications
-curl -s -H "Authorization: Bearer $_COOLIFY" \
-  "$DEPLOY_API_BASE/api/v1/applications"
-
-# Get application details
-curl -s -H "Authorization: Bearer $_COOLIFY" \
-  "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
-
-# Deploy (trigger) — correct endpoint is GET /api/v1/deploy?uuid=
-# (POST /applications/<uuid>/deploy returns {"message":"Not found."})
-curl -s -H "Authorization: Bearer $_COOLIFY" \
-  "$DEPLOY_API_BASE/api/v1/deploy?uuid=<uuid>&force=true"
-
-# Get deployment logs
-curl -s -H "Authorization: Bearer $_COOLIFY" \
-  "$DEPLOY_API_BASE/api/v1/deployments/<deployment-id>"
-
-# Set env var
-curl -s -X POST -H "Authorization: Bearer $_COOLIFY" \
-  -H "Content-Type: application/json" \
-  -d '{"key":"<KEY>","value":"<VALUE>"}' \
-  "$DEPLOY_API_BASE/api/v1/applications/<uuid>/envs"
-
-# Set watch_paths
-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>"
+clauth ops catalog --endpoint <control-plane>
+clauth ops list --endpoint <control-plane>
+clauth ops describe --endpoint <control-plane> --target <pm2-name>
+clauth ops deploy --endpoint <control-plane> --application <slug> --ref <registered-ref>
+clauth ops promote --endpoint <control-plane> --application <registered-coolify-uuid>
+clauth ops job --endpoint <control-plane> --job <job-id>
 ```
 
+Returns are accepted jobs (`202`) and the server persists redacted `queued`,
+`running`, `building`, `waiting`, and terminal events. Generic PM2 catalog
+operations are policy-disabled unless the server owner explicitly allowlists the
+operation and target.
+
 **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

package/skills/handoff/SKILL.md

@@ -127,6 +127,19 @@ SELECT insert_work_item(
   p_source      := 'planning'
 );
 
+-- Immediately populate governance refs — the handoff's plan doc IS the plan_ref/spec_ref.
+-- Set architecture_ref ONLY when this handoff crosses an architectural boundary (storage
+-- authority, process topology, auth boundary, deployment model, persistence, service
+-- ownership, public contract); leave it NULL for ordinary feature work, or every task
+-- below gets held for a review it doesn't need.
+SELECT set_epic_governance_refs(
+  p_epic_id := '<epic-uuid>'::uuid,
+  p_plan_ref := '.rdc/plans/<topic-slug>.md',
+  p_spec_ref := '.rdc/plans/<topic-slug>.md',
+  p_architecture_ref := '<docs/systems/<system>/ARCHITECTURE.md or NULL>',
+  p_scoping_statement := '<one paragraph: what is explicitly in scope and what is explicitly out of scope>'
+);
+
 -- Create tasks (one per work package)
 SELECT insert_work_item(
   p_title       := '<Package Name>',

package/skills/onramp/SKILL.md

@@ -249,6 +249,16 @@ SELECT insert_work_item(
   p_project_node_id := '<project_node_id>'::uuid,
   p_labels          := ARRAY['onramp','<archetype>']
 );
+
+-- Immediately populate governance refs. architecture_ref stays NULL — onramp phases are
+-- data/content pipeline work (research, brand, site build), not an architectural-boundary
+-- change; setting it would hold every phase task for a review it doesn't need.
+SELECT set_epic_governance_refs(
+  p_epic_id := '<epic-uuid>'::uuid,
+  p_spec_ref := 'BRIDGE-MODE-SPEC.md',
+  p_architecture_ref := NULL,
+  p_scoping_statement := 'Enroll <slug> through the 7 onramp phases: enroll, research + document integration, conflict resolution, brand book + imagery, Regen Score gate, site build, deploy dev.'
+);
 ```
 
 ### 1.5 Disk Tree + Directory Verification

package/skills/overnight/SKILL.md

@@ -126,6 +126,7 @@ rdc:plan <epic-id> --unattended
 
 Check `PLAN_STATUS.task_count > 0` before continuing.
 If 0 tasks created: escalate via advisor, then skip if still unresolved.
+If `PLAN_STATUS.held_for_design_review > 0`: do not silently promote those tasks to todo. Log the held task IDs and their durable assessment, request human Design Review, and continue only with the independently admitted portion of the epic.
 
 ### 3c. Build
 
@@ -139,6 +140,7 @@ Agents receive the relevant guide file from `.rdc/guides/` (fallback: `.rdc/guid
 
 After each wave: check `BUILD_STATUS`. If `escalated: true`, log the escalation
 in the overnight doc and continue — don't stop the loop.
+After each wave and after every resumed epic, require the `runOrchestrator()` receipt from `rdc:build`. `admission_refocus` or `pipeline_blocked` means the epic is held for durable Design Review or validator closure; log that state and do not hand-reconstruct a dispatch wave.
 
 **Mandatory code-review gate inherited from rdc:build (Step 9b).** Every wave inside `rdc:build` runs a `pr-review-toolkit:code-reviewer` pass before the next wave dispatches. Critical/high findings reopen the affected work items to `todo` and the next wave fixes them. Overnight does not skip or weaken this gate. If a wave's code-review escalates twice, advisor decides; otherwise the loop continues.
 
@@ -149,7 +151,7 @@ rdc:review --unattended
 ```
 
 Check `REVIEW_STATUS.verdict`:
-- `"CLEAN"`: mark epic `done` in work_items, push, continue to next epic
+- `"CLEAN"`: re-run the durable CodeFlow supervisor. Mark an epic `done` only when its receipt is `pipeline_complete` and every executable child is design-review admitted and validator-closed (`status = done`); otherwise preserve the epic/task hold and log `admission_refocus` or `pipeline_blocked`.
 - `"HAS_ISSUES"` with `escalations > 0`: log issues, push what's clean, continue
 - `"HAS_ISSUES"` with `escalations = 0` (all auto-fixed): push, continue
 
@@ -242,6 +244,7 @@ Provide the advisor with:
 - NEVER let agents overlap on the same files
 - Push after every epic, not just at the end
 - Update Supabase work items in real time throughout
+- **A clean review never overrides a durable Design Review hold, an incomplete checklist, or missing validator closure**
 - Max 2 hours per epic — if exceeded, skip and log `TIMEOUT`
 - If credential daemon goes down mid-session: write current state to overnight doc, push, exit gracefully
 - If git push fails: log the failure, attempt rebase, retry once — do not force push

package/skills/plan/SKILL.md

@@ -234,15 +234,31 @@ description: "Usage `rdc:plan <topic>` — No epic exists and you need architect
    - Epic via `insert_work_item(p_item_type := 'epic', p_definition_of_done := '[...]'::jsonb, ...)`
    - Epic DoD MUST include: `{"id":"test-plan-verified","text":"All test plan items implemented and passing","required":true,"checked":false}`
    - Set `p_definition_of_done` on the epic — child tasks inserted under it will auto-inherit it as their checklist
-   - One task per work package via `insert_work_item(p_parent_id := <epic_id>, ...)` — checklist auto-hydrated from epic's DoD
+   - **Immediately after creating the epic, call `set_epic_governance_refs`** so downstream execution (`rdc:build`, `rdc:overnight`, `rdc:fixit`, `rdc:refactor`) never has to guess or stall waiting on these fields:
+     ```sql
+     SELECT set_epic_governance_refs(
+       p_epic_id := '<epic_id>',
+       p_plan_ref := '.rdc/plans/<topic-slug>.md',           -- the doc written in step 6
+       p_spec_ref := '.rdc/plans/<topic-slug>.md',            -- same doc unless a dedicated spec doc exists for this topic
+       p_architecture_ref := '<docs/systems/<system>/ARCHITECTURE.md or NULL>',  -- set ONLY when this plan crosses an architectural boundary (storage authority, process topology, auth boundary, deployment model, persistence, service ownership, public contract) — leave NULL for ordinary feature/bugfix work, or every task gets held for human review that doesn't need it
+       p_scoping_statement := '<one paragraph: what is explicitly in scope and what is explicitly out of scope for this epic>'
+     );
+     ```
+   - Attach a **Design Review contract** to every executable work package. It must contain registered architecture-evidence reference(s), declared target boundary, and a concrete alignment claim; independently observable acceptance criteria plus required `decomp-*` and `test-*` rows; and estimated files/LOC, declared surfaces, and change kind.
+   - One executable task per work package only through `upsert_admitted_work_item(...)`, never a direct `work_items` write. Supply a stable source fingerprint, the task checklist, and the Design Review contract. `insert_work_item` remains valid for the parent epic only.
+   - Do not invent architecture evidence. Missing or unregistered evidence, broad refactors, multi-surface work, or disproportionate contracts intentionally route to human Design Review.
+   - Read the durable result for each package: `dispatchable: true` / `automatic_approved` may become `todo`; `dispatchable: false` / `needs_human` or `pending` stays `blocked`, gets `needs-human-design-review`, and is reported as held.
    - **Additionally, write decomposition rows as checklist items** on each task, using id format `decomp-<surface>-<slug>`.
      The task checklist MUST include both the atomic `decomp-*` rows and the `test-*` verification rows.
      The `decomp-*` row text must include the route/file, action, expected result, and evidence artifact.
-   - **Write test plan items as checklist items** on each task, using id format `test-<type>-<slug>`:
+   - **Write test plan items as checklist items** on each task, using id format `test-<type>-<slug>`.
+   - **If (and only if) the epic's `architecture_ref` is set** (this work package crosses an architectural boundary), ALSO write one required `architecture-fidelity-<slug>` checklist row on that task: text names the specific architecture doc + the boundary being touched, e.g. `"implementation matches docs/systems/codeflow/ARCHITECTURE.md § local-index registration"`. This is checked at CLOSE time by `update_work_item_status(..., 'done')`, independently of the Design Review contract's own `dispatchable`/`needs_human` admission check above — the exit gate hard-rejects closure on any task under an architecture_ref epic that lacks this row. Do not add it to tasks under an epic with no `architecture_ref`; that would hold ordinary work for a review it doesn't need.
      ```sql
-     SELECT insert_work_item(
+     SELECT upsert_admitted_work_item(
+       p_source_fingerprint := 'plan:<epic-id>:wp-2-ast-scanner:v1',
        p_parent_id := '<epic_id>',
        p_title := 'WP-2: AST Scanner',
+       p_description := 'Bounded scanner work package with its durable Design Review contract.',
        p_checklist := '[
          {"id":"decomp-api-scan-success","text":"api: GET /api/layout/scan?dir=apps/studio/src returns 200 JSON with roots[] and warnings[]; evidence: route probe output","required":true,"checked":false},
          {"id":"test-assert-scanner-filters","text":"assert: scanFile returns only container components","required":true,"checked":false},
@@ -250,10 +266,16 @@ description: "Usage `rdc:plan <topic>` — No epic exists and you need architect
          {"id":"test-smoke-scan-api","text":"smoke: GET /api/layout/scan returns 200","required":true,"checked":false},
          {"id":"test-contract-scanresult","text":"contract: ScanResult shape matches spec","required":true,"checked":false},
          {"id":"tsc-clean","text":"npx tsc --noEmit passes","required":true,"checked":false}
-       ]'::jsonb
+         -- Only add an architecture-fidelity-* row here too if this task's epic has architecture_ref set.
+       ]'::jsonb,
+       p_design_review := '{
+         "architecture":{"alignment_claim":"Scanner change stays within the declared analysis boundary.","evidence_refs":["<registered-reference>"],"target_boundaries":["<declared-boundary>"]},
+         "acceptance":{"criteria":["scanner focused test passes"]},
+         "proportionality":{"estimated_files":2,"estimated_loc":180,"declared_surfaces":["<surface>"],"change_kind":"feature"}
+       }'::jsonb
      );
      ```
-   - Agents MUST tick each `decomp-*` and `test-*` checklist item as they implement/verify it via `update_checklist_item(..., p_actor_session_id := '<agent-session-id>', p_actor_role := 'agent')`
+   - Agents MUST tick each `decomp-*`, `test-*`, and (when present) `architecture-fidelity-*` checklist item as they implement/verify it via `update_checklist_item(..., p_actor_session_id := '<agent-session-id>', p_actor_role := 'agent')`
    - Agents submit `implementation_report.codeflow_post`, then move work to `review`; validators close `done`
    - `update_work_item_status('done', ..., p_actor_role := 'validator')` rejects missing reports, unchecked required items, and supervisor/validator re-ticks
    - Set priorities: urgent/high/normal based on sequencing
@@ -262,7 +284,7 @@ description: "Usage `rdc:plan <topic>` — No epic exists and you need architect
    - Interactive: present the plan for approval before building
    - Unattended: skip approval, proceed immediately, emit status block:
      ```
-     PLAN_STATUS: { epic_id, task_count, doc_path, waves }
+     PLAN_STATUS: { epic_id, task_count, dispatchable_task_count, held_for_design_review, doc_path, waves }
      ```
 
 ## Unattended Escalation
@@ -280,6 +302,7 @@ choose the most conservative/reversible approach and document the decision.
 - Each work package must be independently executable by an agent
 - No file overlap between work packages
 - Include test requirements in every work package
+- **No executable work item is dispatchable without a durable Design Review decision; a planner cannot self-approve with prose-only evidence**
 - Reference affected CLAUDE.md files in each work package description
 - Reference the relevant guide file from `.rdc/guides/` (fallback: `.rdc/guides/`) for agent context
 - **If a work package involves creating a new deployed app:** the task description MUST say "Use `rdc:deploy new <slug>` — do NOT create the Coolify app manually. Read `docs/runbooks/coolify-app-templates.json` first." Assign it to an `infra` agent. This is a hard rule — manually created apps have consistently been misconfigured.

package/skills/tests/MATRIX.md

@@ -1,6 +1,6 @@
 # RDC Skill Test Suite Matrix
 
-Current coverage: 35 manifests for 35 skill directories.
+Current coverage: 36 manifests for 36 skill directories.
 
 The manifest layer verifies each skill can be started from a realistic caller prompt in an isolated `RDC_TEST=1` sandbox. The acceptance harness can run either Claude (`--engine claude`) or Codex (`--engine codex`) against the same manifests and records the engine stream, extracted tool calls, stdout/stderr artifacts, rendered assistant output, failures, lessons learned, and next build optimizations under `.rdc/reports/`.
 
@@ -8,6 +8,7 @@ The manifest layer verifies each skill can be started from a realistic caller pr
 
 | Skill | Manifest | Fixture prompt class | Assertions | Acceptance depth |
 |---|---|---|---|---|
+| `rdc:behavior-audit` | `rdc-behavior-audit.test.json` | Bounded transcript-audit fixture | `commits_made`, `exit_code`, `stdout_contains` | Redacted evidence bundle, independent validator, and no-deploy/no-self-certify checks |
 | `rdc:brochure` | `rdc-brochure.test.json` | HTML-to-PDF brochure fixture | `exit_code`, `stdout_contains` | PDF artifact, page/size/source output, and no upload/deploy/source-modification checks |
 | `rdc:build` | `rdc-build.test.json` | Unattended build from sandbox label | `commits_made`, `exit_code`, `stdout_contains` | Dispatch guide, code-review, validator, sandbox, and no-push/no-skip checks |
 | `rdc:channel-formatter` | `rdc-channel-formatter.test.json` | Long article to social content pack | `exit_code`, `stdout_contains` | Output contains, output not contains, tool-call routing |

package/skills/tests/README.md

@@ -1,7 +1,7 @@
 # Tier 2 Test Manifests
 
 Each RDC skill directory has a colocated test manifest at `skills/tests/rdc-<name>.test.json`.
-There are currently 35 manifests for 35 skill directories. These drive the Tier 2
+There are currently 36 manifests for 36 skill directories. These drive the Tier 2
 behavioral runner and the build acceptance harness for both Claude and Codex.
 
 See `MATRIX.md` for the current skill-by-skill coverage table.

package/skills/tests/rdc-behavior-audit.test.json

@@ -0,0 +1,12 @@
+{
+  "manifest_version": 1,
+  "skill": "rdc:behavior-audit",
+  "description": "Behavior audit requires a bounded output path and preserves transcript evidence as redacted, validator-governed artifacts.",
+  "fixture": { "prompt": "rdc:behavior-audit reports/behavior-audit/test --since-days 7", "env": { "RDC_TEST": "1" } },
+  "assertions": { "exit_code": 0, "commits_made": { "min": 0 }, "stdout_contains": ["manifest.json", "locators.jsonl", "independent", "validator"] },
+  "acceptance": {
+    "output_contains": ["manifest.json", "redacted", "validator"],
+    "output_not_contains": ["deploy", "rewrite transcripts", "self-certify"]
+  },
+  "teardown": { "reset_branch": true }
+}

package/skills/workitems/SKILL.md

@@ -53,6 +53,18 @@ SELECT insert_work_item(
   p_labels      := ARRAY['system-label'],
   p_source      := 'planning'
 );
+
+-- Immediately populate governance refs. architecture_ref stays NULL unless this epic
+-- crosses an architectural boundary (storage authority, process topology, auth boundary,
+-- deployment model, persistence, service ownership, public contract) — setting it holds
+-- every child task for a required architecture-fidelity-* checklist row at close time.
+SELECT set_epic_governance_refs(
+  p_epic_id := '<epic-uuid>'::uuid,
+  p_plan_ref := '.rdc/plans/<n>.md or NULL',
+  p_spec_ref := '.rdc/plans/<n>.md or NULL',
+  p_architecture_ref := NULL,
+  p_scoping_statement := '<one paragraph: what is in scope and what is explicitly out>'
+);
 ```
 
 ## Create Task

package/tests/completion-gate-supervisor-admission.test.mjs

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { getSkillBody } from '../lib/catalog.mjs';
+
+const served = (name) => {
+  const body = getSkillBody(name);
+  assert.ok(body, `${name} must have a live catalog body`);
+  return body;
+};
+
+test('live rdc_skill_get planning body creates executable work through the durable admission contract', () => {
+  const plan = served('rdc:plan');
+  assert.match(plan, /upsert_admitted_work_item/);
+  assert.match(plan, /Design Review contract/);
+  assert.match(plan, /needs_human/);
+  assert.doesNotMatch(plan, /One task per work package via `insert_work_item/);
+});
+
+test('live rdc_skill_get build body routes work through CodeFlow admission and validator closure', () => {
+  const build = served('rdc:build');
+  assert.match(build, /runOrchestrator\(\)/);
+  assert.match(build, /SupabaseStateStore/);
+  assert.match(build, /admission_refocus/);
+  assert.match(build, /pipeline_complete/);
+  assert.match(build, /durably `done`/);
+});
+
+test('live rdc_skill_get overnight body cannot map CLEAN directly to an incomplete epic', () => {
+  const overnight = served('rdc:overnight');
+  assert.match(overnight, /only when its receipt is `pipeline_complete`/i);
+  assert.match(overnight, /validator-closed/);
+  assert.doesNotMatch(overnight, /"CLEAN"`: mark epic `done` in work_items, push, continue to next epic/);
+});

package/tests/help-surface.test.mjs

@@ -35,7 +35,7 @@ for (const [name, text] of Object.entries(docs)) {
   assert.doesNotMatch(text, /https:\/\/rdc-skills\.dev\.regendevcorp\.com\/mcp/, `${name} must not point callers at dev MCP`);
 }
 
-assert.match(docs.readme, /34 MCP skills organized into 8 manifest categories/, 'README should use manifest category count');
+assert.match(docs.readme, /36 MCP skills organized into 8 manifest categories/, 'README should use manifest category count');
 assert.match(docs.readme, /Nineteen[\s\S]*\/rdc:\*` command shorthands/i, 'README should distinguish slash-command shorthands from full MCP skills');
 assert.match(docs.readme, /Use `rdc_skill_list` for the authoritative live catalog/, 'README should point callers to live MCP catalog');
 assert.doesNotMatch(docs.readme, /All user-invocable skills become available as slash commands/, 'README must not imply all MCP skills are slash commands');

package/tests/install-rdc-skills.test.mjs

@@ -24,7 +24,7 @@ const plugin = JSON.parse(readFileSync(join(REPO_ROOT, '.claude-plugin', 'plugin
 const skillCount = Array.isArray(plugin.skills_meta)
   ? plugin.skills_meta.length
   : Object.keys(plugin.skills_meta || {}).length;
-assert.equal(skillCount, 34, 'test fixture should expose all 34 MCP skills from plugin skills_meta');
+assert.equal(skillCount, 36, 'test fixture should expose all 36 MCP skills from plugin skills_meta');
 assert.match(
   source,
   /Available MCP skills.*\/rdc:\* command shorthands/,

package/git-sha.json

@@ -1,3 +0,0 @@
-{
-  "sha": "e634f9ffc42be06bccedfa3d6ab4e85bf79b5c70"
-}