@lifeaitools/rdc-skills 0.35.26 → 0.37.0

package/guides/review-gate.md

@@ -0,0 +1,133 @@
+# Review Gate — deterministic validators on the diff
+
+> The code-review gate used by `rdc:build` (step 9b), `rdc:fixit` (5.5),
+> `rdc:review` (8b), `rdc:release` and `rdc:overnight`. It runs the specific
+> validators over the changed files and finishes in one to two minutes.
+>
+> Approved: direct operator instruction — "we need to tune our code reviews to
+> be specific -- if you ran the validator for solid and lint etc... it should
+> take 1-2 minutes". 2026-09-21, Dave, in session.
+
+## Why this replaced the open-ended reviewer
+
+The previous default dispatched one `pr-review-toolkit:code-reviewer` agent to
+read the whole diff. On the PRT launch build (2026-09-21) four such passes took
+4 to 10 minutes and roughly 200–300k tokens each. Each one was a new judgment
+call, so two runs could not be compared.
+
+The gate below took **9.3 seconds** over the same build's 33 changed code files.
+It found two things that had shipped:
+
+- a SOLID regression: `investors/page.tsx` went from 96.3 to 85, on OCP;
+- 45 lint diagnostics in 14 touched files. Most were import order. Three were
+  accessibility defects: two buttons with no `type`, and an SVG with no title.
+
+A number that two runs agree on can block a merge. An opinion cannot.
+
+## The gate
+
+Run every step and report every result. A red step does not stop the others,
+because the reader needs the whole picture in one pass.
+
+```bash
+BASE=<ref the change is measured against>     # wave base sha, origin/develop, last release tag
+SCOPE=<package or app dir the change touches> # never the monorepo root
+CHANGED=$(git diff --name-only --diff-filter=d "$BASE" -- "$SCOPE" | grep -E '\.(ts|tsx|js|jsx|mjs|cjs)$')
+```
+
+| # | Check | Command | Blocks when |
+|---|---|---|---|
+| 1 | **FORM**: SOLID and boundaries | `rdc-solid-score "$SCOPE" --diff "$BASE" --format json` (add `--config <repo>/.solid-score.yml` if the repo has one) | `regressions`, `boundaryViolations` or `boundaryMisconfigured` is non-empty |
+| 2 | **LINT**: changed files only | the repo's own linter; fix first, then check: `npx biome check --write $CHANGED` then `npx biome check $CHANGED` (ESLint: `npx eslint --fix` then `npx eslint`) | the second command exits non-zero |
+| 3 | **TYPES** | `npx tsc --noEmit -p <package>/tsconfig.json`, once per touched package | exit non-zero |
+| 4 | **TESTS**, scoped | the touched package's own test command, e.g. `pnpm --filter <pkg> exec vitest run` | any failure |
+| 5 | **RENDERED UI**, if a route changed | the project's pinned `test:ui` Playwright spec against a fresh app-owned server (`rdc:review` step 9a) | any red assertion, or no harness |
+
+Read the scorer output fully:
+
+- `removedFiles` lists deletions. They are reported, not scored: a deleted file has no units left that can regress.
+- `unresolvedLanguages` lists files no plugin parses, such as `.css`. They are unmeasured, never passed.
+
+### Rules that keep it honest
+
+- **Lint is fixed, never baselined.** Diagnostics already in a touched file
+  are fixed in the same change. Run `--write` first, and most of them clear
+  mechanically. Do not add an ignore list or a count ratchet.
+- **SOLID is a ratchet by design.** `--diff` compares each unit with itself at
+  `$BASE`. OCP and LSP report `low` confidence, and that confidence is data. A
+  regression still blocks. The usual fix for an OCP drop is to move the
+  branching into a named module; for `investors/page.tsx` that means taking the
+  data read and FAQ shaping out into a loader.
+- **Stay inside the time budget by narrowing scope.** Changed files and touched
+  packages only. If the gate takes more than two minutes, it is scanning too
+  wide. Narrow `$SCOPE` rather than dropping a step.
+- **Never edit what a gate measures to turn it green.** A red check is either
+  fixed properly or reported as a finding.
+
+### New UI tests: prove them before trusting them
+
+Three lessons from the same build:
+
+- **Negative-control every new UI assertion.** Run it once against the broken
+  or old state and watch it go red. A test that has never failed has not
+  proved anything. The CTA-clipping spec was trusted only after it failed on
+  the old CSS.
+- **Measure settled layout.** Take bounding boxes after motion finishes, using
+  reduced motion or waiting for the animation to end. A panel measured
+  mid-slide reports the wrong size.
+- **Include a 1280×800 viewport.** A laptop screen is where a tall panel
+  clips its call-to-action. 1440 and 390 alone missed it.
+
+## When an LLM reviewer is still right
+
+Only for a **named question the validators cannot answer**, scoped to the
+files that question touches. Examples:
+
+- "Does this middleware bypass skip auth on any protected path?"
+- "Does any public string state a return figure?"
+
+```
+Agent({
+  subagent_type: "pr-review-toolkit:code-reviewer",
+  description: "<the question, in five words>",
+  prompt: "Answer one question about <files>: <question>. Read only those files.
+           Return CODE_REVIEW_COMPLETE with { critical_count, high_count, medium_count,
+           low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
+})
+```
+
+A reviewer asked to "review the diff" with no question is the pattern this
+guide retired. Critical and high findings from a named-question pass block, the
+same as a red gate step.
+
+## What is not in the default gate
+
+| Tool | Why it is not in the default gate | When to run it |
+|---|---|---|
+| `rdc-clean-code-score` | No `--diff`, so it reports absolute counts. On the PRT build it reported 475 findings in 17 files, 459 of them N4 "magic number" on SVG coordinates. Its default dead-export scope is the whole git repo, which ran out of 4 GB of heap on regen-root. | Advisory, in `rdc:full-analysis`. Always pass `--project-root <package dir>`; that run took 7.9 s. |
+| `rdc-architecture-score` | No `--diff`. With no `layers:` config, every file is `unclassified`, so it measures nothing. | When the repo declares layers. |
+| `rdc-duplication-score` | Absolute, not a delta. | Advisory. |
+
+## Review is not closure
+
+The gate replaces the per-wave LLM code review. It does **not** replace the
+validator.
+
+A non-epic work item still reaches `done` only through
+`update_work_item_status(..., 'done', ..., <validator session>, 'validator')`,
+and the database refuses an actor session equal to the item's own. A forked
+agent shares its parent's session id, so a fork cannot validate the parent's
+item. Dispatch a fresh agent for that.
+
+## Receipt
+
+Emit this line. The skill that ran the gate quotes it in the implementation
+report or review report:
+
+```
+REVIEW_GATE: { base, scope, files, solid: { regressions, boundaryViolations, removedFiles, unresolved },
+               lint: <exit>, tsc: <exit>, tests: "<N passed>", ui: "<spec + viewports> | n/a",
+               elapsed_s, verdict: "CLEAN|HAS_ISSUES" }
+```
+
+Under `RDC_TEST=1`: echo `[RDC_TEST] skipping review gate` and continue.

package/guides/work-contract.md

@@ -142,9 +142,35 @@ A session with **no contract** — one that only read, planned or answered — s
 gets the evidence checks: tracked changes it left uncommitted, and a claimed work
 item's open DoD. How its final message is worded is never judged.
 
+**Setting work aside.** A session ends one of three ways: the work is proved, it waits,
+or someone else takes it. Say which — never leave the Stop to repeat an open DoD:
+
+```bash
+# It waits: the database marks the item blocked, with the reason in its notes.
+node "$LIFEAI_ENV/bin/rdc-work.mjs" hold --work-item <uuid> --reason "<why it waits>" --session <id>
+# Pick it up later, from this session or any other: in_progress again, declared on the contract.
+node "$LIFEAI_ENV/bin/rdc-work.mjs" resume --work-item <uuid> --session <id>
+# Someone else takes it:
+node "$LIFEAI_ENV/bin/rdc-work.mjs" handoff --work-item <uuid> --to "<who takes it over>" \
+  --reason "<why this session is not finishing it>" [--note <handoff doc>] --session <id>
+```
+
+Only work the session holds — declared with `--work-item`, or claimed — can be set aside.
+A held item's open DoD stops holding the Stop **while the database says `blocked`**; a
+hold the database does not confirm lifts nothing and the Stop says so. A handed-off item
+shows as `[>] handed off … theirs now: <rows>`. Neither is ever counted as proof. Drop the
+rows this session will not prove, and commit or discard your own changes first — setting
+work aside moves the obligation, not unsaved work, and uncommitted changes still hold the Stop.
+
+The held Stop lists only what is still owed: proved and dropped rows are counted, not
+listed, and rows stale only because of a later edit in the same repository collapse to
+one line. An edit in a different repository does not stale this contract's proofs.
+
 Enforcement is bounded: a Stop held identically three times, or six times in a row,
 releases, and the unproved rows stay in the contract and in the compaction snapshot.
-A defect in the gate itself — an unreadable contract, an error — reports and never holds.
+A released or resolved checklist is shown once, not after every later turn; a changed
+one is shown again. A defect in the gate itself — an unreadable contract, an error —
+reports and never holds.
 
 ## Target resolution — never assume regen-root
 

package/hooks/require-work-item-on-commit.js

@@ -156,6 +156,17 @@ function isGitCommit(command) {
 function extractCommitMessage(command) {
   const cmd = String(command || '');
 
+  // `-m "$(cat <<'EOF' … EOF)"` / `-m "$(cat <<-'EOF' … EOF)"`: the plain -m
+  // regexes below match the FIRST unrelated quote inside the substitution
+  // (the opening `'` of `<<'EOF'` reads as a closing delimiter to the
+  // non-greedy pattern) and return early with literal shell text as the
+  // "message" -- before the heredoc fallback ever runs. This is the same
+  // defect class the 2026-08-29 fix addressed for a bare heredoc, just one
+  // wrapper layer further out: detect the substitution shape first and
+  // extract from its OWN heredoc body.
+  const mSub = cmd.match(/-m\s+"\$\(\s*cat\s+<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1\s*\n([\s\S]*?)\n[ \t]*\2\s*\)"/);
+  if (mSub) return { message: mSub[3], readable: true };
+
   const msgMatch = cmd.match(/-m\s+["']([^"']+)["']/s) ||
                    cmd.match(/-m\s+"([\s\S]+?)"\s*(?:&&|$)/);
   if (msgMatch) return { message: msgMatch[1], readable: true };

package/package.json

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

package/scripts/solid-score.mjs

@@ -141,6 +141,23 @@ function walk(dir, exclude, out = []) {
   return out;
 }
 
+/**
+ * Does this `git show <ref>:<path>` stderr mean "the file is not at <ref>"?
+ *
+ * Git words it two ways, and the common one was missing until 2026-09-21:
+ *   - `fatal: path 'p' does not exist in 'ref'`        — absent at ref AND on disk
+ *   - `fatal: path 'p' exists on disk, but not in 'ref'` — a NEW file in the
+ *     working tree, i.e. every `--diff` over a change that adds a file
+ * Matching only the first made `--diff` crash on any diff with a new file.
+ * Anything else (a bad ref, a path-form mismatch) is not "absent" and must be
+ * rethrown, so a real error never passes silently as a new unit.
+ */
+export function isAbsentAtRef(stderr) {
+  const msg = String(stderr ?? '');
+  if (!msg.includes('fatal: path')) return false;
+  return msg.includes('does not exist in') || msg.includes('exists on disk, but not in');
+}
+
 /** Score a file's text as it existed at a given git ref, without touching the working tree. */
 function scoreAtRef(repoRoot, filePath, ref, weights) {
   const relPath = relative(repoRoot, filePath).split('\\').join('/');
@@ -151,10 +168,9 @@ function scoreAtRef(repoRoot, filePath, ref, weights) {
     // `git show` fails both when the file is genuinely new at `ref` AND for
     // unrelated reasons (a path-form mismatch, a bad ref). Collapsing both
     // into "it's new" hides the second case — the exact class of silent
-    // path-form bug found three times in this file already tonight. Only a
-    // "does not exist" message is treated as new; anything else is rethrown.
-    const msg = String(err.stderr ?? err.message ?? '');
-    if (msg.includes('does not exist in') || msg.includes('fatal: path') && msg.includes('does not exist')) return null;
+    // path-form bug found three times in this file already. Only git's two
+    // "not at this ref" messages are treated as new; anything else is rethrown.
+    if (isAbsentAtRef(err.stderr ?? err.message)) return null;
     throw err;
   }
   const plugin = pluginFor(filePath);
@@ -237,6 +253,7 @@ async function main() {
   }
 
   let files;
+  let removedFiles = [];
   if (diffRef) {
     // `git diff --name-only <ref> -- <path>` (no `...HEAD`) compares `<ref>`
     // directly against the WORKING TREE — committed history AND uncommitted
@@ -244,8 +261,16 @@ async function main() {
     // diff` form, so they're unioned in separately. Before this fix, only
     // `<ref>...HEAD` (committed history alone) was scored — a dirty tree
     // with real regressions scored zero files and exited 0.
-    const committed = execFileSync('git', ['diff', '--name-only', diffRef, '--', targetPath], { cwd: repoRoot, encoding: 'utf8' })
+    //
+    // Deleted paths are split out by git's own account (`--diff-filter=D`),
+    // not by an existsSync guess, so a path-form bug can never pass as a
+    // deletion. A deleted file has no current units and so nothing that can
+    // regress; before 2026-09-21 it reached extractUnits and crashed the gate
+    // with ENOENT. It is reported in `removedFiles`, never dropped silently.
+    const nameOnly = (filter) => execFileSync('git', ['diff', '--name-only', `--diff-filter=${filter}`, diffRef, '--', targetPath], { cwd: repoRoot, encoding: 'utf8' })
       .split('\n').filter(Boolean);
+    const committed = nameOnly('d');
+    removedFiles = nameOnly('D');
     const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '--', targetPath], { cwd: repoRoot, encoding: 'utf8' })
       .split('\n').filter(Boolean);
     files = [...new Set([...committed, ...untracked])]
@@ -285,7 +310,7 @@ async function main() {
   const boundaryViolations = boundaryFindings.filter((f) => !f.satisfied);
 
   const output = {
-    results, regressions, boundaryFindings, boundaryViolations, boundaryMisconfigured, unresolvedLanguages,
+    results, regressions, removedFiles, boundaryFindings, boundaryViolations, boundaryMisconfigured, unresolvedLanguages,
     config: { weights: config.weights, diff: config.diff, boundaryRuleCount: (config.boundaries ?? []).length },
     configPath, configLoaded,
     parser: parserName,
@@ -312,6 +337,10 @@ async function main() {
       console.log('\nREGRESSIONS:');
       for (const r of regressions) console.log(`  ${r.file} :: ${r.unit} — ${r.reason} ${JSON.stringify(r)}`);
     }
+    if (removedFiles.length) {
+      console.log(`\n${removedFiles.length} file(s) deleted since ${diffRef} — no units left to score:`);
+      for (const f of removedFiles) console.log(`  ${f}`);
+    }
     if (unresolvedLanguages.length) {
       console.log(`\n${unresolvedLanguages.length} file(s) matched no registered language plugin — skipped, not silently passed:`);
       for (const f of unresolvedLanguages) console.log(`  ${relative(repoRoot, f)}`);

package/scripts/validate-publish-manifests.js

@@ -72,7 +72,7 @@ for (let i = 0; i < args.length; i++) {
 /**
  * Resolve the regen-root monorepo checkout this run should validate against.
  *
- * 2026-07-26 (lesson 2026-07-26-deploy-worktree-validator-root): hardcoding
+ * 2026-07-26 (retired 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

package/skills/build/SKILL.md

@@ -390,7 +390,7 @@ Read the task title and description, then:
    ### ⛔ 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:
+   the same shared tree (retired 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
@@ -572,7 +572,7 @@ Read the task title and description, then:
      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).
+     `/health` 200 is a proxy, not coverage (retired 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
@@ -644,27 +644,30 @@ Read the task title and description, then:
 
     ⛔ **NO wave may dispatch until the previous wave's code-review pass clears.** Memory `feedback_code_review_per_wave.md` — Davesend 2026-05-24 incident.
 
-    Dispatch ONE `pr-review-toolkit:code-reviewer` agent with the wave's merged diff:
-
-    ```
-    Agent({
-      subagent_type: "pr-review-toolkit:code-reviewer",
-      description: "Wave <N> code review",
-      prompt: "Review the diff `git diff <wave-base-sha>..HEAD` on develop.
-               Focus on: bugs, logic errors, security vulnerabilities, project-convention adherence
-               (.claude/rules/*, CLAUDE.md). Apply confidence-based filtering — high-confidence
-               findings only. Report severity per finding: critical | high | medium | low.
-               Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
-               low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
-    })
-    ```
-
-    **Severity gate (default — high+ blocks):**
-    - `critical` or `high` findings → reopen affected work items to `todo` with finding text in notes; fix in a new wave before continuing
-    - `medium` or `low` findings → append to each work item's `implementation_report.flags`; do NOT reopen; validator sees them
-    - Zero findings → log `CODE_REVIEW: CLEAN` and proceed to next wave
-
-    Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and proceed.
+    Run the deterministic review gate in `guides/review-gate.md` over the wave's
+    merged diff, with `BASE=<wave-base-sha>` and `SCOPE` set to each package or
+    app the wave touched. That covers `rdc-solid-score --diff`, the repo linter on
+    changed files, `tsc`, scoped tests, and the UI spec when a route changed. It
+    takes one to two minutes; an open-ended reviewer agent took 4–10.
+    Approved: direct operator instruction — "we need to tune our code reviews to be
+    specific -- if you ran the validator for solid and lint etc... it should take 1-2
+    minutes". 2026-09-21, Dave, in session.
+
+    Dispatch `pr-review-toolkit:code-reviewer` only for a **named question** the
+    validators cannot answer, scoped to the files it touches (the guide's
+    "When an LLM reviewer is still right" section). Never dispatch it with a bare
+    "review the diff".
+
+    **Gate outcome:**
+    - A red gate step, or a critical/high finding from a named-question pass →
+      reopen the affected work items to `todo` with the `REVIEW_GATE` receipt and
+      the failing output in notes. Fix in a new wave before continuing.
+    - Medium/low findings from a named-question pass → append them to each work
+      item's `implementation_report.flags`. Do not reopen; the validator sees them.
+    - All steps green → log the `REVIEW_GATE` receipt with `verdict: "CLEAN"` and
+      proceed to the next wave.
+
+    Under `RDC_TEST=1`: echo `[RDC_TEST] skipping review gate` and proceed.
 
 10. **Mandatory validator gate (runs after ALL waves complete — before any work item closes):**
 
@@ -747,4 +750,10 @@ NEVER run pnpm build or pnpm turbo. Use npx vitest run only.
 
 ## 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>-build-<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.
+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 — record each lesson where its fix belongs:
+
+- **Fix encoded in this run** (a guard, test or script shipped, commit linked): the lesson goes in that commit's message. No file, no issue.
+- **Fix not encoded**: submit it to the repository the fix belongs to, which opens one `lesson` + `proposal` issue there (an identical title opens nothing):
+  `node "$LIFEAI_ENV/bin/rdc-lesson.mjs" submit --repo <owning repo slug> --title "…" --what "…" --root-cause "…" --fix "…"`
+
+No lesson file is written. Note "N lessons captured (E encoded, S submitted)" with the issue URLs in your verdict/summary. A run that taught nothing records nothing — absence is the default.

package/skills/clean-code-analyzer/SKILL.md

@@ -65,6 +65,12 @@ matches the numeric-suffix heuristic) alongside real hits (`data`, `temp`,
    `bin.rdc-clean-code-score`; falls back to
    `node <rdc-skills-install-path>/scripts/clean-code-score.mjs`.)
 
+   **In a monorepo, always pass `--project-root <package or app dir>`.** Without
+   it, the dead-export scan walks the whole git repo. On regen-root that ran out
+   of 4 GB of heap after 18 s (exit 134); scoped to `apps/prtrust` it took 7.9 s.
+   This scorer has no `--diff` and reports absolute counts, so it is advisory,
+   not part of the merge gate (`guides/review-gate.md`).
+
 2. **Read `results`** — per-unit findings for N1 (cryptic names), N2 (heuristic
    meaningless-distinction names, low confidence), N4 (magic numbers), N7
    (generic class/function names), F1 (>20 statements), F2 (>3 params), E1

package/skills/collab/SKILL.md

@@ -462,7 +462,7 @@ An agreement is a **Decision**. Route it by kind:
 |---|---|
 | Settled decision, constraint, or policy | The governing document — plan / ARCHITECTURE.md / rule. AKG ingests from there. |
 | Work to perform | `insert_work_item` via RPC, per `.claude/rules/work-items-rpc.md` |
-| A genuine hard-won episode (a wrong theory, a surprising infra behaviour) | `.rdc/lessons/` per `guides/lessons-learned-spec.md` |
+| A genuine hard-won episode (a wrong theory, a surprising infra behaviour) | A `lesson` issue in the repository the fix belongs to, per `guides/lessons-learned-spec.md` |
 | A stated, unresolved disagreement | Escalate — Step 6 |
 
 **Do not file a settled agreement as a lesson.** That is the single most common
@@ -576,8 +576,12 @@ and avoids acting on a misread premise (lesson
 ## Capture lessons (exit step)
 
 Before the final verdict line, follow `guides/lessons-learned-spec.md` § Capture
-procedure. Write a lesson only for a genuine **episode** — a first root-cause
+procedure. Record a lesson only for a genuine **episode** — a first root-cause
 theory that proved wrong, a documented path that did not work, a surprising
-tool/infra behaviour. **A settled agreement is not a lesson** (see Step 5). Set
-`scope` and `status`; commit alongside the run's other commits; note "N lessons
-captured" in the verdict. A run that taught nothing writes nothing.
+tool/infra behaviour. **A settled agreement is not a lesson** (see Step 5). A
+lesson whose fix shipped as a guard, test or script this run goes in that
+commit's message; any other lesson is submitted to the repository the fix
+belongs to, as one `lesson` + `proposal` issue:
+`node "$LIFEAI_ENV/bin/rdc-lesson.mjs" submit --repo <owning repo slug> --title "…" --what "…" --root-cause "…" --fix "…"`.
+No lesson file is written. Note "N lessons captured" with the issue URLs in the
+verdict. A run that taught nothing records nothing.

package/skills/convo/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: convo
+description: "rdc:convo — fair attributed discussion using six reusable templates, shared sources, explicit dissent and durable decisions; not an implementation dispatch."
+---
+
+> **OUTPUT CONTRACT:** `guides/output-contract.md`. Show the selected template,
+> discussion progress and decision boundary, not transport logs.
+> **Sandbox contract:** Under `RDC_TEST=1`, do not contact live peers or mutate
+> external state. Return a labeled simulated discussion packet; absent peer
+> responses remain UNKNOWN, never simulated agreement.
+
+# rdc:convo — shared deliberation, explicit decisions
+
+Invoke `rdc:convo <template> <topic>`. Templates: `outcome-exploration`,
+`design-comparison`, `troubleshooting`, `plan-critique`,
+`disagreement-resolution`, `work-handoff`.
+All six templates are included here so MCP callers receive the complete contract.
+Use for a requested discussion, co-design or second opinion. Ordinary questions
+do not need a peer round. Implementation stays in `rdc:plan` / `rdc:build`.
+
+## Shared contract — applies to every template
+
+1. Preserve the user's exact outcome, scope and permissions. Choose the closest
+   template; announce a template switch without resetting the round count.
+   Default budget: at most three completed rounds, up to 600 words per peer per
+   round, equal opportunity to respond. These are defaults, not authority to
+   shorten content the user explicitly requested. Finish early when resolved.
+2. Name participants by actual engine/person and session identity; use UNKNOWN
+   for unavailable identity or version. Roles (proposer, challenger, recorder,
+   decision owner) come from the task, not the engine brand. A workflow layer is
+   context, not a participant. No automatic Claude-supervisor/Codex-worker split.
+3. Build one source packet: verbatim user scope; template id and skill version
+   (plugin version and/or repository revision, never guessed);
+   repository/revision or document version; explicit file excerpts and observation
+   list with as-of times; assumptions; authorized decision owner; recorder and
+   record destination; round budget. Hash the exact UTF-8 packet with SHA-256.
+   Send identical bytes to each peer and the hash separately. Each echoes the
+   received hash; if it can independently hash the bytes, record that separately.
+   A mismatch pauses decision-making until corrected; do not count an echo as an
+   independent integrity check. Reissue a changed packet with a new hash to all.
+4. Use an existing verified transport: `rdc:co-develop` for addressed peer turns,
+   or `rdc:collab` for an already available native/relay participant. Load the
+   selected transport procedure. Reuse its send/reply and session correlation,
+   not its default role or write permissions. A person's reply in the current
+   user session is also a valid transport for that person. This contract grants no
+   implementation, commit, deployment, approval or task-completion authority.
+   Do not create another queue, scheduler or transport. Never invent a reply.
+5. Every turn carries discussion/session id, turn id, reply-to id, participant,
+   round, packet hash and as-of. Replies distinguish AGREE, AMEND, DISAGREE,
+   UNKNOWN and DEFER per point, with reasons and source references. Observed facts,
+   supplied-source analysis and inference stay distinct. Preserve exact peer text;
+   recorder summaries are separate and attributed. Silence is not agreement.
+   A supplied-source peer review is not a claim the peer ran tests or read files.
+6. Missing or delayed replies: inspect the same live process/session/turn handle.
+   A polling timeout is not terminal and does not authorize another dispatch.
+   Continue independent work while a confirmed live call runs. Report
+   PEER_UNAVAILABLE only after a terminal result or missing handle is established;
+   retain its evidence and unresolved points. Never replace a missing participant
+   with the coordinator's answer. Stop debate at its agreed budget, recording
+   unresolved positions rather than manufacturing consensus. An authorized
+   decision owner may close as UNRESOLVED while a call remains live, recording
+   its pending turn and handle. That does not mean PEER_UNAVAILABLE, cancel the
+   call, or authorize re-dispatch; the owner retains responsibility for its result.
+7. The user may name the recorder; otherwise the existing authorized coordinator
+   records within the task's project. Only that recorder writes the discussion
+   artifact, at the established project decision/report location. No authorized
+   destination means return the record inline without a file write. Retain turns
+   append-only within the record; later corrections reference the original turn.
+   Share only task-relevant, authorized sources; omit credentials and unrelated
+   private content. A durable decision contains the packet/version, attributed
+   turns, accepted and rejected proposals with reasons, dissent, uncertainty,
+   decision owner, artifact owner, next action and evidence required.
+8. Label the outcome AGREED, DECIDED_WITH_DISSENT, UNRESOLVED or PEER_UNAVAILABLE.
+   Only explicit assent supports AGREED. An authorized owner may decide without
+   consensus, retaining the other position. A disagreement never grants new
+   authority. For reversible in-scope decisions use existing delegation; ask the
+   user or authorizing principal
+   only when authorization or a material choice is genuinely missing.
+9. Handoff proposes a bounded plan/build brief with accepted constraints, exact
+   artifacts, ownership and failing acceptance checks. If execution is already
+   authorized, the coordinator continues through the existing governed workflow;
+   otherwise request that authority. Discussion does not close work items or
+   advance Flowable stages. In CDE-Zoe, save durable decisions/artifacts to the
+   authorized blackboard/project; retain conversation as transcript, not fabricated
+   workflow state. An unavailable persistence route is reported as unsaved.
+
+## Templates
+
+Select one block and fill its inputs. The shared contract above supplies identity,
+fairness, authority, recording and termination; do not duplicate or override it.
+
+### outcome-exploration
+```json
+{
+  "template": "outcome-exploration",
+  "inputs": ["Exact desired change and beneficiary", "Company/program/project/topic scope, unknowns explicit", "Constraints and available observations"],
+  "process": ["Separate purpose and outcome from proposed implementation", "Compare observable success and non-goals; expose missing assumptions"],
+  "outputs": ["Outcome brief with acceptance evidence", "Non-goals and unresolved scope questions"],
+  "owner": "Authorized outcome owner; recorder names the brief owner",
+  "dissent": "Keep competing interpretations and whose evidence would distinguish them",
+  "handoff": "rdc:plan with the accepted outcome; unresolved material scope remains explicit"
+}
+```
+
+### design-comparison
+```json
+{
+  "template": "design-comparison",
+  "inputs": ["Accepted outcome and current architecture revision", "Candidate designs including reuse/no-change where viable", "Constraints and evaluation evidence"],
+  "process": ["Evaluate each candidate against the same outcome criteria", "Challenge assumptions, interfaces and failure/recovery behavior; state costs without invented numbers"],
+  "outputs": ["Chosen design or unresolved alternatives with rationale", "Required PRODUCT.md, DESIGN.md, WORKFLOW.md and plan changes, as applicable"],
+  "owner": "Authorized design decision owner; one owner per artifact",
+  "dissent": "Preserve rejected alternatives and the observation that could reopen the decision",
+  "handoff": "rdc:plan or existing design stage; no build admission from discussion alone"
+}
+```
+
+### troubleshooting
+```json
+{
+  "template": "troubleshooting",
+  "inputs": ["Observed symptom, time and exact affected surface", "Expected behavior and last known revision", "Logs/probes with secrets removed and hypotheses labeled"],
+  "process": ["Distinguish measured failure from theories", "Choose a discriminating safe probe and compare its actual result; do not repeat failed guesses"],
+  "outputs": ["Supported cause or remaining hypotheses", "Scoped repair proposal and regression that would fail before repair"],
+  "owner": "Investigation owner; separately named repair owner",
+  "dissent": "Retain contrary observations and unresolved causal claims",
+  "handoff": "Existing fix/build workflow for authorized repair; no service restart merely because observation timed out"
+}
+```
+
+### plan-critique
+```json
+{
+  "template": "plan-critique",
+  "inputs": ["User outcome and exact plan revision", "Checklist inputs, processing, outputs and evidence", "Architecture boundaries, dependencies and current implementation"],
+  "process": ["Trace each user requirement to a deliverable and failing check", "Challenge missing handoffs, recovery and unsupported claims; avoid padding the checklist"],
+  "outputs": ["Accepted plan amendments with exact affected sections", "Uncovered requirements and verification gaps"],
+  "owner": "Plan owner records amendments; independent reviewer retains attribution",
+  "dissent": "Keep disputed acceptance criteria and the evidence needed to resolve them",
+  "handoff": "rdc:plan amendment, then rdc:build only under existing authorization and admission"
+}
+```
+
+### disagreement-resolution
+```json
+{
+  "template": "disagreement-resolution",
+  "inputs": ["Exact disputed point and attributed positions", "Shared evidence and conflicting assumptions", "Decision owner, constraints and remaining round budget"],
+  "process": ["Each peer states the other's position for correction before rebuttal", "Identify a discriminating observation or explicit tradeoff; record an owner decision if consensus is absent"],
+  "outputs": ["Agreement, decision with dissent, or unresolved point", "Reopening condition and smallest next evidence step"],
+  "owner": "Existing authorized decision owner, never a winner inferred from engine identity",
+  "dissent": "Retain each final position; no majority vote or silence masquerading as assent",
+  "handoff": "Bounded evidence task or authorized plan decision; escalation only for a genuinely missing authority"
+}
+```
+
+### work-handoff
+```json
+{
+  "template": "work-handoff",
+  "inputs": ["Accepted outcome, decisions and unresolved constraints", "Exact repository, revision, work item and artifact locations", "Completed evidence, remaining work and permission boundaries"],
+  "process": ["Receiver restates scope, dependencies and next executable action", "Reconcile gaps without relabeling unverified work as complete"],
+  "outputs": ["Accepted handoff brief with one writer per artifact", "Remaining checks and restart instructions with current process handles if relevant"],
+  "owner": "Sender owns provenance; named receiver accepts future work explicitly",
+  "dissent": "Receiver lists unsupported claims, unavailable inputs and declined scope",
+  "handoff": "rdc:build for implementation or rdc:plan for unresolved planning; discussion never substitutes for review or validator closure"
+}
+```
+
+## Exit check
+
+- [ ] Selected template and shared packet identified.
+- [ ] Each peer's received-hash echo recorded; mismatches resolved before deciding.
+- [ ] Actual responses attributed; disagreement and uncertainty retained.
+- [ ] Outcome labeled AGREED, DECIDED_WITH_DISSENT, UNRESOLVED or PEER_UNAVAILABLE.
+- [ ] Decision owner and artifact owner explicit; no implied permission expansion.
+- [ ] Record saved through an authorized route, or explicitly unsaved.
+- [ ] Next action handed to the existing workflow; no false completion claim.

package/skills/deploy/SKILL.md

@@ -100,8 +100,8 @@ than glossed:
 The removed prose also carried real, hard-won operational knowledge — the
 `next start` `BUILD_ID` crash-loop, the `media.place.fund` hotlink referer
 allowlist, the `<head>` metadata audit, the lockfile-importer trap on a first
-promote to `main`. That knowledge is in git history for this file and in the
-named `.rdc/lessons/` entries it cited. **It was removed from here because prose
+promote to `main`. That knowledge is in git history for this file, including the
+lessons it cited. **It was removed from here because prose
 that duplicates behaviour drifts from it** — not because it stopped being true.
 Where such a check belongs in the pipeline, it belongs in the program or in the
 manager, where it runs, rather than in a document that hopes to be read.