@lifeaitools/rdc-skills 0.35.25 → 0.36.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.35.25",
+  "version": "0.36.1",
   "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",
@@ -384,6 +384,30 @@
       "codeflow_required": true,
       "purpose": "run a structured agent-to-agent conversation"
     },
+    "convo": {
+      "name": "convo",
+      "slash": "rdc:convo",
+      "category": "dev-loop",
+      "usage": "rdc:convo <template> <topic>",
+      "args": {
+        "positional": [
+          { "name": "template", "required": true, "description": "Discussion type", "accepts": "outcome-exploration | design-comparison | troubleshooting | plan-critique | disagreement-resolution | work-handoff" },
+          { "name": "topic", "required": true, "description": "Bounded question or outcome", "accepts": "text" }
+        ],
+        "flags": []
+      },
+      "requires": [],
+      "produces": ["discussion_record", "decision_record"],
+      "default_model": "inherit",
+      "triggers": ["fair discussion", "attributed peer discussion", "discussion templates", "co-design conversation"],
+      "follows": [],
+      "leads_to": ["rdc:plan", "rdc:build"],
+      "sandbox_aware": true,
+      "output_contract": "guides/output-contract.md",
+      "enabled_default": true,
+      "codeflow_required": false,
+      "purpose": "conduct bounded fair discussion and record decisions using existing peer transports"
+    },
     "convert": {
       "name": "convert",
       "slash": "rdc:convert",

package/.github/ISSUE_TEMPLATE/lesson.yml

@@ -0,0 +1,56 @@
+name: Lesson learned
+description: A lesson from real work whose fix is not yet encoded as a guard, test or script. An issue proposes; a work item commits.
+title: "[lesson] "
+labels: ["lesson", "proposal"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        File this in the repository the fix belongs to. **If this repository is public, file it in LIFEAI/regen-root with the area naming this repository instead** — a lesson carries hosts, paths and ports, and a public issue cannot be unsaid. Agents submit the same form from any engine:
+
+        `node "$LIFEAI_ENV/bin/rdc-lesson.mjs" submit --repo <slug> --title "..." --what "..." --root-cause "..." --fix "..."`
+
+        A lesson whose fix is already encoded (a guard, test or script shipped with a linked commit) needs no issue; record it in that commit message.
+        Accepting this issue creates a work item and relabels it `accepted`; the fixing commit closes it with `Fixes #N`.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: The concrete situation, with evidence (exit code, file:line, command).
+    validations:
+      required: true
+  - type: textarea
+    id: root-cause
+    attributes:
+      label: Root cause
+      description: The evidenced cause, not a guess.
+    validations:
+      required: true
+  - type: textarea
+    id: fix
+    attributes:
+      label: The fix or rule
+      description: What should change so this never recurs, as a guard, test, script, or rule line.
+    validations:
+      required: true
+  - type: input
+    id: area
+    attributes:
+      label: Repository / area
+      description: The repository slug and the area inside it, e.g. `lifeai-env · hooks/lib` or `rdc-skills · skills/build`.
+    validations:
+      required: true
+  - type: input
+    id: encoded
+    attributes:
+      label: Encoded artifact
+      description: The guard, test or script that already enforces part of this fix, if any.
+    validations:
+      required: false
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence
+      description: Links to commits, logs, transcripts or work items, one per line.
+    validations:
+      required: false

package/.rdc/lessons/2026-09-17-release-mcp-registry-split.md

@@ -0,0 +1,34 @@
+---
+id: 2026-09-17-release-mcp-registry-split
+date: "2026-09-17"
+skill: release
+session: 01a07b0d-e74e-7601-af20-9caae7e94b71
+scope: architectural
+status: open
+area: infra
+links:
+  commits: [d39104709bf0035f84a8001cc6c30e5c5e0d9c13]
+  memory: []
+  work_items: [5f7618b4-cf32-4460-8a3a-761f0161b847]
+---
+
+## What happened
+
+rdc-skillsv0.36.0 tag triggered npm workflow35178348993: packing succeeded,
+registryPUT returned404, and npm version lookup remained404. Independently,
+the existing public MCP tag updater served0.36.0 at the exacttagSHA with45skills;
+connected convo retrieval and remote tests passed. Prior0.35.26 workflow also
+shows a PUT404 although that version is now in npm.
+
+## Root cause
+
+Two release consumers advance independently: the MCP host follows mergedtags,
+while npm requires a successful authenticatedpublish. A live MCP cannot prove
+npm distribution, nor does failednpm publication prove the MCP is stale. The
+underlying registry permission/trustedpublisher cause is not established by404.
+
+## The fix / rule
+
+Keep runtimeSHA/catalog and npmversion/provenance as distinct release evidence.
+Preserve the failedjob; inspect publisherconfiguration with the packageowner
+before changing permissions or retrying. No authboundary repair shipped here.

package/git-sha.json

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

package/guides/lessons-learned-spec.md

@@ -5,21 +5,21 @@ system: claude-workflow
 status: active
 owner: infrastructure
 created: 2026-06-08
-last_reviewed: 2026-06-08
+last_reviewed: 2026-09-17
 source_of_truth: true
 supersedes: []
 depends_on:
   - ".claude/rules/architectural-change-approval.md"
   - ".rdc/guides/output-contract.md"
-tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
+tags: [rdc, lessons-learned, skills, housekeeping, adaptive, github-issues]
 ---
 
 # Lessons-Learned Capture & Triage — Spec
 
 > Auto-referenced by long-running `rdc:*` skills at exit, and by `rdc:housekeeping` for triage.
 > Goal: make the fleet an **interactive adaptive modeler** — every run that teaches us
-> something writes it down, and the weekly housekeeping pass turns those lessons into
-> actual fixes (rules, skill docs, work_items).
+> something records it where the fix belongs, and the weekly housekeeping pass turns those
+> lessons into actual fixes (guards, tests, scripts, rule lines, work items).
 
 ---
 
@@ -28,126 +28,250 @@ tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
 Lessons learned during a run (a non-obvious infra trap, a wrong assumption, a missing
 gate, a tooling gotcha) used to survive only if someone hand-wrote a memory. This system
 makes capture a **routine exit step** of every long skill, and triage a **routine phase**
-of the weekly housekeeping. Capture is cheap and append-only; triage is where fixes happen.
+of the weekly housekeeping. Capture is cheap; triage is where fixes happen.
 
 Precedent: brochurify's `extract-verifier-rules` already does read-log → cluster →
 propose-rule for one domain. This generalizes that pattern fleet-wide.
 
----
+### Why lessons are not files any more
 
-## Storage — directory of per-lesson files
+Until 2026-09 every lesson was a markdown file in the capturing repository's
+`.rdc/lessons/`. A census of one repository found 315 of them: 157 already enforced in code,
+where the file only repeated what a guard or test already guaranteed, and 32 enforced
+nowhere, sitting in a directory the owner of the fix never reads. A lesson filed where it
+was noticed, rather than where it is fixed, is a lesson nobody who can fix it sees.
 
-Lessons live in **`.rdc/lessons/`**, one markdown file per lesson:
+So the record now follows the fix:
 
-```
-.rdc/lessons/<YYYY-MM-DD>-<skill>-<short-slug>.md
-```
+- **An encoded lesson needs no file.** The guard, test or script that enforces it is the
+  record, and the commit that shipped it carries the narrative.
+- **An unencoded lesson is a GitHub issue in the repository the fix belongs to**, labelled
+  `lesson` + `proposal`. **An issue proposes; a work item commits.**
 
-- One file per lesson (NOT a single appended file) so parallel agents finishing at the
-  same time never collide on one file in git.
-- `<skill>` is the capturing skill (`build`, `deploy`, `overnight`, `fixit`, `plan`,
-  `preplan`, `review`, `release`, `collab`).
-- `<short-slug>` is 2–4 kebab words naming the lesson.
+---
 
-A run that taught nothing writes nothing — **absence is the default**. Only write a lesson
-when something was genuinely learned (see § When to capture).
+## When to capture (at skill exit)
 
----
+A lesson exists when ANY of these were true during the run:
 
-## Lesson file schema
+1. A root cause turned out to be different from the first theory (a wrong assumption).
+2. The standard/documented path didn't work and you had to do something non-obvious.
+3. A gate, check, or doc was missing and its absence cost a round.
+4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
+5. A hook blocked you and the block revealed a real gap (not just your mistake).
+
+Do NOT capture: routine success, your own one-off typo, anything already fully documented
+in a rule/guide, or a settled agreement (that is a Decision and belongs in the plan). If a
+durable user preference or correction was involved, also write a `memory` (this spec and
+memory are complementary — link them). A run that taught nothing records nothing —
+**absence is the default**.
 
-```markdown
----
-id: <YYYY-MM-DD>-<skill>-<short-slug>
-date: "<YYYY-MM-DD>"
-skill: build | deploy | overnight | fixit | plan | preplan | review | release | collab
-session: <session-id or short ref>
-scope: simple | architectural          # triage routing — see § Scope gate
-status: open | triaged | applied | wont-fix
-area: infra | skill | guide | rule | schema | ui | content | other
-links:
-  commits: []                          # SHAs that relate to the lesson
-  memory: []                           # memory file slugs, if a memory was also written
-  work_items: []                       # work_item UUIDs spawned during triage
 ---
 
-## What happened
-<one paragraph — the concrete situation, with evidence (exit code, file:line, command)>
+## The two outcomes
 
-## Root cause
-<one paragraph — the evidenced cause, not a guess>
+| The fix is… | Record | Where |
+|---|---|---|
+| **Encoded in this run** — a guard, test or script shipped, commit linked | the commit message | no file, no issue |
+| **Partly encoded** — some of it ships, the rest does not | one issue, Encoded artifact filled | the repository the fix belongs to |
+| **Not encoded** — a fix is known or needed but not shipped | one `lesson` + `proposal` issue | the repository the fix belongs to |
 
-## The fix / rule
-<what should change so this never recurs: a rule edit, skill-doc line, code change,
-or a check. If already applied in the same run, say so and link the commit.>
-```
+"Encoded" means something now **fails** when the lesson is violated: a guard rule blocks it,
+a test goes red, a script refuses it. A sentence added to a rule or skill document is not
+encoding — prose drifts from behaviour — so a new doc-only lesson is an issue until a guard or
+test carries it.
 
-`scope` is the single most important field — it routes triage:
+**The owning repository** is the one whose code or documents change to fix it, not the one
+where the run happened. A clauth behaviour found during a regen-root build is a clauth lesson.
 
-- **`simple`** — a doc line, a one-file fix, a config tweak, a clarifying sentence in a
-  skill, a missing grep guard. Housekeeping applies these directly.
-- **`architectural`** — anything matching `.claude/rules/architectural-change-approval.md`
-  (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
-  API/MCP changes, skill-contract changes affecting multiple skills). Housekeeping does
-  NOT apply these; it surfaces them via `AskUserQuestion` for explicit approval first.
+### Public repositories file in regen-root
 
-When unsure, mark `architectural`.
+A lesson is written from inside the estate and routinely names hosts, ports, paths and vault
+services; a public issue cannot be unsaid. **LIFEAI/rdc-skills is public**, so its lessons
+default to the private monorepo: `--repo regen-root --area rdc-skills`. Likewise CodeFlow, whose
+active development is regen-root `packages/codeflow`: `--repo regen-root --area codeflow`.
 
----
+`rdc-lesson submit` reads the target's visibility before any write and refuses a PUBLIC
+repository (exit 3) with that route. `--public-ok` overrides it for a lesson that carries no
+estate detail, and even then the title and body are secret-scanned (credentials, private keys,
+IP addresses, clauth `/v/<service>` paths) and refused on any hit.
 
-## When to capture (at skill exit)
+---
 
-Write a lesson when ANY of these were true during the run:
+## Capture procedure (the exit step long skills call)
 
-1. A root cause turned out to be different from the first theory (a wrong assumption).
-2. The standard/documented path didn't work and you had to do something non-obvious.
-3. A gate, check, or doc was missing and its absence cost a round.
-4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
-5. A hook blocked you and the block revealed a real gap (not just your mistake).
+At the end of a long skill run, before the final verdict line:
 
-Do NOT capture: routine success, your own one-off typo, anything already fully documented
-in a rule/guide. If a durable user preference or correction was involved, also write a
-`memory` (this spec and memory are complementary — link them).
+1. Decide if anything qualifies (§ When to capture). If not, record nothing and move on.
+2. For each lesson, name the owning repository's registry slug (a `projects.json` key:
+   `lifeai-env`, `clauth`, `regen-root`, `regen-deploy-mgr`, …; a public repository's lesson
+   uses `regen-root` with `--area <repo>`, § Public repositories).
+3. **Encoded in this run** → record it in the commit message of the change that encodes it.
+   `rdc-lesson` prints the record (one `Key: value` line per field), opens nothing, and calls
+   GitHub not at all:
+
+   ```bash
+   node "$LIFEAI_ENV/bin/rdc-lesson.mjs" submit --repo <owning slug> --encoded <guard/test/script path> \
+     --title "<one line>" --what "<what happened, with evidence>" \
+     --root-cause "<evidenced cause>" --fix "<what now enforces it>"
+   ```
+
+   Part of it ships and part does not → add `--partial`: the issue opens with the Encoded
+   artifact section filled.
+4. **Not encoded** → submit it. It opens ONE issue titled `[lesson] <title>`, labelled
+   `lesson` + `proposal`, in the repository the slug resolves to:
+
+   ```bash
+   node "$LIFEAI_ENV/bin/rdc-lesson.mjs" submit --repo <owning slug> \
+     --title "<one line>" --what "<what happened, with evidence: command, exit code, file:line>" \
+     --root-cause "<evidenced cause, not a guess>" --fix "<the guard, test, script or rule that would stop it>" \
+     [--area <area>] [--evidence <commit/log/work-item URL> ...]
+   ```
+
+   - The same exact title already **open** → nothing opens; the existing URL is printed, so a
+     retry is safe.
+   - The same exact title **closed** → the lesson recurred: the new occurrence is commented on
+     that issue and it is reopened (`action: recurred`). A fix that did not hold is the most
+     important lesson there is; it must not be filed as a stranger.
+   - `--dry-run` shows the issue and calls nothing. An unknown flag is refused by name, so a
+     typo such as `--encode` never silently opens an issue.
+   - An unregistered slug fails and names itself; do not file the lesson in a different
+     repository to get past that — report it.
+5. Mention in the verdict/summary: "N lessons captured (E encoded, S submitted: <issue URLs>)".
+
+Where `@lifeai/lifeai-env` is installed globally the command is also `rdc-lesson submit …`.
+Without `$LIFEAI_ENV` (the `core` profile, or claude.ai), open the issue from the owning
+repository's **Lesson learned** issue form (`.github/ISSUE_TEMPLATE/lesson.yml`); it applies
+the same title prefix, labels and sections.
+
+**Accepted residual:** two submits of the same new title at the same moment can both pass the
+duplicate check and open two issues. Triage closes the later one as a duplicate of the first.
+
+### What the issue carries
+
+The form and the CLI produce the same sections, in this order:
+
+- **What happened** — the concrete situation, with evidence (exit code, file:line, command).
+- **Root cause** — the evidenced cause, not a guess.
+- **The fix or rule** — what should change so this never recurs.
+- **Repository / area** — the owning slug and the area inside it.
+- **Encoded artifact** — anything that already enforces part of the fix.
+- **Evidence** — commits, logs, transcripts, work items.
 
 ---
 
-## Capture procedure (the exit step long skills call)
+## Accepting a lesson (issue → work item)
 
-At the end of a long skill run, before the final verdict line:
+An issue is a proposal. Work begins only when it is accepted:
+
+1. Create the work item through the work-item RPCs, naming the issue URL in its description.
+2. Link and relabel the issue:
+
+   ```bash
+   node "$LIFEAI_ENV/bin/rdc-lesson.mjs" accept <issue-number-or-url> --repo <owning slug> --work-item <uuid>
+   ```
+
+   This comments `Accepted as work item <uuid>` first, then removes `proposal` and adds
+   `accepted`. If the relabel fails, run it again: it sees the comment and finishes the
+   relabel without a second comment. It refuses an issue that is not labelled `lesson`, and
+   does not create the work item.
 
-1. Decide if anything qualifies (§ When to capture). If not, write nothing and move on.
-2. For each lesson, write `.rdc/lessons/<date>-<skill>-<slug>.md` using the schema above.
-   Set `status: open` (or `applied` if you already shipped the fix in this same run, with
-   the commit linked).
-3. Set `scope` honestly (`simple` vs `architectural`).
-4. Commit the lesson file(s) on `develop` alongside the run's other commits.
-5. Mention in the verdict/summary that N lessons were captured.
+## Closing a lesson
+
+The fixing commit closes the issue with `Fixes #N` (or `Fixes LIFEAI/<repo>#N` from another
+repository) — but GitHub acts on that only when the commit reaches the repository's **default
+branch**. Where fixes land somewhere else first, close it explicitly once the fix is on the
+integration branch:
+
+```bash
+node "$LIFEAI_ENV/bin/rdc-lesson.mjs" close <issue-number-or-url> --repo <owning slug> --commit <sha> [--reason "<text>"]
+```
+
+It comments `Fixed by <sha>` and closes the issue as completed. This applies to **regen-root**
+(default branch `main`, integration `develop`) and **regen-deploy-mgr** (default branch
+`codex/regen-deploy-mgr-wp1`, which does not carry what ships). Not worth fixing → close the
+issue as not planned with a one-line reason.
 
 ---
 
 ## Triage procedure (rdc:housekeeping, weekly)
 
-`rdc:housekeeping` adds a **Lessons triage** phase:
+`rdc:housekeeping` runs a **Lessons triage** phase over open lesson issues:
+
+```bash
+node "$LIFEAI_ENV/bin/rdc-lesson.mjs" list --state open          # every registered repository
+node "$LIFEAI_ENV/bin/rdc-lesson.mjs" list --repo <slug> --json   # one repository, machine-readable
+```
+
+Every registered repository is listed, skipped because its issues are switched off (reported,
+not a failure), or **NOT listed** — no GitHub repository resolves, or the read failed. NOT
+listed is named on stderr and in `--json` `skipped` with its reason, `complete` is false, and
+the command exits 1. Treat that as an incomplete triage, never as "no lessons there".
+
+1. Cluster open `proposal` issues by area + root-cause similarity (dedupe repeats into one fix;
+   close the duplicates as duplicates, linking the survivor). A reopened `recurred` issue goes
+   first: its fix did not hold.
+2. Decide each cluster's scope:
+   - **simple** — a one-file fix, a config tweak, a missing grep guard, a test.
+   - **architectural** — anything matching `.claude/rules/architectural-change-approval.md`
+     (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
+     API/MCP changes, skill-contract changes affecting multiple skills). When unsure, it is
+     architectural.
+3. Route per the mode below.
+4. Work the conversion backlog (§ Existing `.rdc/lessons/` files) with whatever capacity is left.
+5. Summarize in the housekeeping report: open / recurred / accepted / closed-fixed /
+   closed-won't-fix counts with issue URLs, plus backlog files converted and remaining.
+
+### Attended mode (default — a human is present)
+
+- **simple** → accept it (§ Accepting), apply the fix directly as a guard/test/script, commit
+  with `Fixes #N` (or close it with `rdc-lesson close`, § Closing).
+- **architectural** → do NOT edit. Present the issue + options via `AskUserQuestion` (per
+  `architectural-change-approval.md`). On approval, accept it and apply via the correct
+  lifecycle (rdc-skills tag/push for skills; cited commit for rules). If deferred, accept it so
+  the work item carries it.
+- **Not worth fixing** → close the issue as not planned with a one-line reason.
+
+### Triage procedure — UNATTENDED weekly mode
+
+No human present (overnight / cron / `rdc:overnight`) — never run `AskUserQuestion`:
+
+- **Per-difficulty model routing** (reuses the `rdc:build` table): clustering and scope
+  triage → `claude-sonnet-5`; mechanical apply → `claude-haiku-4-5`; harder multi-file or
+  migration fix → `claude-sonnet-5`; design/architectural fix → `claude-opus-5`.
+- **simple** → accept, apply directly or via `rdc:fixit`, commit with `Fixes #N` or close with
+  `rdc-lesson close`.
+- **architectural with a single clear correct fix** (records an already-learned lesson —
+  "add a gate", "encode X as a test") → accept, route through `rdc:plan` → `rdc:build` (or
+  `rdc:fixit` if genuinely under 5 files).
+- **architectural and genuinely ambiguous** (multiple valid approaches, real tradeoffs) → write
+  a `human_items` row (`item_type='decision'`, options in `suggested_agent_prompt`,
+  `source_type='lesson'`, `source_fingerprint` = the issue URL for dedupe), accept the issue
+  against a linked work item, and leave the decision for the morning. This is the asynchronous
+  equivalent of the attended interview.
+
+Issues are closed, never deleted — a closed issue with its fixing commit, or its won't-fix
+reason, is the audit trail.
+
+---
+
+## Existing `.rdc/lessons/` files — the conversion backlog
 
-1. Read all `.rdc/lessons/*.md` with `status: open`.
-2. Cluster by `area` + root-cause similarity (dedupe repeats into one fix).
-3. For each cluster:
-   - `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard),
-     commit it, set the lesson(s) `status: applied` and link the commit.
-   - `scope: architectural` → do NOT edit. Present the issue + options via
-     `AskUserQuestion` (per `architectural-change-approval.md`). On approval, apply via the
-     correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set
-     `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
-   - Not worth fixing → `status: wont-fix` with a one-line reason.
-4. Summarize in the housekeeping report: captured / applied / escalated / deferred counts.
+Files written under the old procedure are retired by state: an encoded lesson's file is
+deleted and links to it point at the enforcing artifact; an unencoded one becomes an issue in
+its owning repository. **The files that remain — doc-only lessons and product lessons — are a
+backlog to convert, not a place to capture.** Each is done when a guard or test carries it:
+ship that artifact, point any live link at it, and delete the file in the same commit.
 
-Lessons are never silently deleted — `applied` and `wont-fix` files stay as the audit trail.
+Housekeeping lists the remaining `.rdc/lessons/*.md` files for exactly that purpose and
+reports the count converted and remaining. Nothing new is written there: a new lesson — a
+doc-only one included — is an issue (§ Capture procedure).
 
 ---
 
 ## Skills that capture (the long-running set)
 
-`build` · `deploy` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab`
+`build` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab` ·
+`onramp`
 
-Each references this spec from a final "§ Capture lessons" step. A Stop-hook backstop warns
-when one of these skills ends a run with findings but no new `.rdc/lessons/` file.
+Each references this spec from a final "§ Capture lessons" step.

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/package.json

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

package/scripts/install-rdc-skills.js

@@ -1277,7 +1277,14 @@ async function main() {
   const pkg     = readJson(path.join(repoRoot, 'package.json'));
   const version = pkg.version || '0.7.0';
   let   gitSha  = '';
-  try { gitSha = execSync('git rev-parse HEAD', { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }).trim(); } catch {}
+  if (fs.existsSync(path.join(repoRoot, '.git'))) {
+    try { gitSha = execSync('git rev-parse HEAD', { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }).trim(); } catch {}
+  } else {
+    // An npm-installed package has no .git — and `git rev-parse` would walk up into
+    // whatever repository encloses it. The commit is the pack-time stamp instead.
+    gitSha = String(readJson(path.join(repoRoot, 'git-sha.json'))?.sha || '');
+    if (gitSha === 'unknown') gitSha = '';
+  }
 
   // 0.5a. User-skills cleanup — remove any rdc: skills from ~/.claude/skills/user/
   // (older installer versions wrote there; plugin cache is the only authoritative source)

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
@@ -747,4 +747,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/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.

package/skills/fixit/SKILL.md

@@ -222,4 +222,10 @@ Report: what was fixed, file(s) changed, commit hash. One sentence.
 
 ## 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>-fixit-<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/housekeeping/SKILL.md

@@ -160,26 +160,36 @@ Write to `.rdc/reports/YYYY-MM-DD-housekeeping.md`:
 
 ## Lessons triage (weekly)
 
-Read all `.rdc/lessons/*.md` with `status: open` (schema + procedure: `.rdc/guides/lessons-learned-spec.md` § Triage procedure). Cluster by `area` + root-cause similarity (dedupe repeats into one fix).
+List the open lesson issues across every registered repository (procedure: `.rdc/guides/lessons-learned-spec.md` § Triage procedure):
+
+```bash
+node "$LIFEAI_ENV/bin/rdc-lesson.mjs" list --state open
+```
+
+Every registered repository is listed, skipped because its issues are switched off (reported), or **NOT listed** — no GitHub repository resolves or the read failed. NOT listed is named on stderr and in `--json` `skipped`, and the command exits 1: the triage is then incomplete, not empty. Cluster open `proposal` issues by area + root-cause similarity (dedupe repeats into one fix; close the duplicates, linking the survivor), take reopened recurrences first (their fix did not hold), and decide each cluster's scope: **simple** (one-file fix, config, grep guard, test) or **architectural** (anything in `.claude/rules/architectural-change-approval.md`; when unsure, architectural).
 
 ### Attended mode (default — a human is present)
 
 For each cluster:
 
-- `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard), commit it, set the lesson(s) `status: applied` with the commit linked.
-- `scope: architectural` → do NOT edit. Present the issue + options via `AskUserQuestion` (per `.claude/rules/architectural-change-approval.md`). On approval, apply via the correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
-- Not worth fixing → `status: wont-fix` with a one-line reason.
+- **simple** → create the work item, run `node "$LIFEAI_ENV/bin/rdc-lesson.mjs" accept <issue> --repo <slug> --work-item <uuid>`, apply the fix as a guard/test/script, and commit with `Fixes #N`. In regen-root (default branch `main`, integration `develop`) and regen-deploy-mgr (default branch `codex/regen-deploy-mgr-wp1`) `Fixes #N` never reaches the default branch, so once the fix lands run `node "$LIFEAI_ENV/bin/rdc-lesson.mjs" close <issue> --repo <slug> --commit <sha>`.
+- **architectural** → do NOT edit. Present the issue + options via `AskUserQuestion` (per `.claude/rules/architectural-change-approval.md`). On approval, accept it and apply via the correct lifecycle (rdc-skills tag/push for skills; cited commit for rules). If deferred, accept it so the work item carries it.
+- Not worth fixing → close the issue as not planned with a one-line reason.
 
 ### Unattended mode (no human — overnight / cron / `rdc:overnight`)
 
 When the weekly triage runs unattended, follow `.rdc/guides/lessons-learned-spec.md` § **Triage procedure — UNATTENDED weekly mode** — do not run `AskUserQuestion`. In brief (the spec is authoritative):
 
 - **Per-difficulty model routing** (reuses the `rdc:build` table): the run is led by `claude-sonnet-5` for clustering + scope/difficulty triage; mechanical apply → `claude-haiku-4-5`; harder multi-file/migration fix → `claude-sonnet-5`; design/architectural fix → `claude-opus-5`.
-- `scope: simple` → apply directly or via `rdc:fixit`, commit, `status: applied`.
-- `scope: architectural` with a single clear correct fix (records an already-learned lesson — e.g. "document X", "add a gate", update a guide) → route through `rdc:plan` → `rdc:build` (or `rdc:fixit` if genuinely <5 files), update the documentation, set `status: applied`/`triaged`.
-- `scope: architectural` **and genuinely ambiguous** (multiple valid approaches, real tradeoffs) → write a `human_items` row (`item_type='decision'`, with options in `suggested_agent_prompt`, `source_type='lesson'`, `source_fingerprint` for dedupe), set `status: triaged`, spawn + link a `work_item`. Decided in the morning. This is the asynchronous equivalent of the attended interview and honors `.claude/rules/architectural-change-approval.md`.
+- **simple** → accept, apply directly or via `rdc:fixit`, commit with `Fixes #N` or close with `rdc-lesson close` where the default branch is not the integration branch.
+- **architectural with a single clear correct fix** (records an already-learned lesson — e.g. "add a gate", "encode X as a test") → accept, route through `rdc:plan` → `rdc:build` (or `rdc:fixit` if genuinely <5 files).
+- **architectural and genuinely ambiguous** (multiple valid approaches, real tradeoffs) → write a `human_items` row (`item_type='decision'`, with options in `suggested_agent_prompt`, `source_type='lesson'`, `source_fingerprint` = the issue URL for dedupe), accept the issue against a linked `work_item`. Decided in the morning. This is the asynchronous equivalent of the attended interview and honors `.claude/rules/architectural-change-approval.md`.
+
+### Conversion backlog — remaining lesson files
+
+List the lesson files still in the project (`.rdc/lessons/*.md`: doc-only and product lessons from before issues). They are a backlog to convert, not a place to capture: with the capacity left after the issues, pick files and encode each as a guard or test, point any live link at that artifact, and delete the file in the same commit (spec § Existing `.rdc/lessons/` files). Nothing new is written there — a new lesson, doc-only included, is an issue.
 
-Never delete lesson files — `applied` and `wont-fix` stay as the audit trail. Report captured / applied / escalated / deferred counts in the housekeeping report.
+Issues are closed, never deleted — a closed issue with its fixing commit or won't-fix reason is the audit trail. Report open / recurred / accepted / closed-fixed / closed-won't-fix counts with issue URLs, and backlog files converted / remaining, in the housekeeping report.
 
 ## Rules
 - Never run `pnpm build` — not needed for this audit

package/skills/onramp/SKILL.md

@@ -1466,4 +1466,4 @@ Append Phase 7 results to ONRAMP-REPORT.md (final section).
 
 ## Capture Lessons
 
-Before the final verdict, follow `.rdc/guides/lessons-learned-spec.md`. Write `.rdc/lessons/<YYYY-MM-DD>-onramp-<slug>.md` if the run taught something non-obvious.
+Before the final verdict, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure if the run taught something non-obvious. 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 — `node "$LIFEAI_ENV/bin/rdc-lesson.mjs" submit --repo <owning repo slug> --title "…" --what "…" --root-cause "…" --fix "…"` opens one `lesson` + `proposal` issue there. No lesson file is written.

package/skills/overnight/SKILL.md

@@ -47,7 +47,7 @@ Before touching any code, verify the environment is safe:
 1. **Clauth daemon alive AND unlocked:** `/ping` alive is NOT enough — a LOCKED
    vault answers `/ping` but every `/v/<service>` returns nothing, so credentials
    silently resolve empty and a long unattended run fails hours later
-   (lesson 2026-06-16-overnight-preflight-clauth-locked-and-shared-develop-cells).
+   (retired lesson 2026-06-16-overnight-preflight-clauth-locked-and-shared-develop-cells).
    Assert `locked:false` before proceeding:
    ```bash
    curl -s http://127.0.0.1:52437/ping
@@ -58,8 +58,8 @@ Before touching any code, verify the environment is safe:
 2. **Git state clean AND no concurrent committer on shared develop:** Overnight
    shares the `develop` working tree with other cells/sessions. A second session
    committing concurrently can drop a just-committed file during a rebase
-   (lessons 2026-06-16-overnight-preflight-clauth-locked-and-shared-develop-cells,
-   2026-06-17-build-shared-develop-rebase-dropped-committed-file).
+   (retired lessons 2026-06-16-overnight-preflight-clauth-locked-and-shared-develop-cells,
+   retired lesson 2026-06-17-build-shared-develop-rebase-dropped-committed-file).
    ```bash
    git status --short
    git fetch -q origin && git log --oneline @..@{u}   # any rows = origin moved under you
@@ -253,4 +253,10 @@ Provide the advisor with:
 
 ## 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>-overnight-<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/plan/SKILL.md

@@ -383,4 +383,10 @@ designing topology. Do not reach for the REMOTE rule by default.
 
 ## Capture lessons (exit step)
 
-Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-plan-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.
+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/preplan/SKILL.md

@@ -87,4 +87,10 @@ direction if given. If advisor cannot resolve, log and skip to next step.
 
 ## 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>-preplan-<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/release/SKILL.md

@@ -139,12 +139,12 @@ doc-sync/scope guard to catch contamination. In them:
 - **Pre-tag guard: refuse to tag if `git diff --cached --name-only` includes any
   path outside the declared change set.** A broad add swept 4 pre-existing
   untracked skill files into a tagged release that CI published before anyone
-  noticed (lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
+  noticed (retired lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
   dirty-tree contamination class as a lockfile generated against a dirty tree.
 
 ## ⛔ Cross-platform prepack + verify the PUBLISHED tarball
 
-- **Prepack must be OS-agnostic.** A bash-style `prepack` chain (`node A || true && node B || true && node stamp`) short-circuits under Windows **cmd.exe** (npm runs lifecycle scripts via cmd, not bash; `true` is not a cmd builtin and `||`/`&&` evaluate differently), so an appended step silently never runs (lesson 2026-06-13-release-windows-cmd-prepack-shortcircuit). When a prepack step must run cross-platform, use a node wrapper / `shx` / `cross-env` — never rely on `|| true` shell semantics that differ between cmd and bash.
+- **Prepack must be OS-agnostic.** A bash-style `prepack` chain (`node A || true && node B || true && node stamp`) short-circuits under Windows **cmd.exe** (npm runs lifecycle scripts via cmd, not bash; `true` is not a cmd builtin and `||`/`&&` evaluate differently), so an appended step silently never runs (retired lesson 2026-06-13-release-windows-cmd-prepack-shortcircuit). When a prepack step must run cross-platform, use a node wrapper / `shx` / `cross-env` — never rely on `|| true` shell semantics that differ between cmd and bash.
 - **Validate the PUBLISHED artifact, not a local Windows `npm pack`.** A local Windows `npm pack` is NOT a faithful rehearsal of the CI (ubuntu/bash) publish. After publish, verify the real tarball:
   ```bash
   npm pack <pkg>@<version>            # downloads the PUBLISHED tarball
@@ -165,4 +165,10 @@ Use `--profile lifeai` only on a workstation that intentionally has the LIFEAI p
 
 ## 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>-release-<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/review/SKILL.md

@@ -212,4 +212,10 @@ description: rdc:review () - [--unattended] — post-build gate over tsc, tests,
 
 ## 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>-review-<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/tests/MATRIX.md

@@ -1,6 +1,6 @@
 # RDC Skill Test Suite Matrix
 
-Current coverage: 36 manifests for 36 skill directories.
+Current coverage: 37 manifests for 37 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/`.
 
@@ -14,6 +14,7 @@ The manifest layer verifies each skill can be started from a realistic caller pr
 | `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 |
 | `rdc:co-develop` | `rdc-co-develop.test.json` | Coordination status | `commits_made`, `exit_code`, `stdout_contains` | codevelop status, sandbox skip, no chitchat/live-send negative checks |
 | `rdc:collab` | `rdc-collab.test.json` | Claude session relay fixture | `commits_made`, `exit_code`, `stdout_contains` | chitchat/SSE session handling, sandbox skip, and no-reply/no-push negative checks |
+| `rdc:convo` | `rdc-convo.test.json` | Missing-peer plan critique | `exit_code`, `stdout_contains` | Unknown participant response preserved and false agreement/completion negative checks |
 | `rdc:convert` | `rdc-convert.test.json` | Markdown-to-Word conversion fixture | `exit_code`, `stdout_contains` | build-corpus command surface, Word/Markdown flags, and no-GUI/global-install/commit checks |
 | `rdc:deploy` | `rdc-deploy.test.json` | Deployment diagnosis | `commits_made`, `exit_code`, `stdout_contains` | Read-only diagnose output and destructive deploy/DNS negative checks |
 | `rdc:edit` | `rdc-edit.test.json` | Local editor launch | `exit_code`, `stdout_contains` | Resolved target, editor host URL, and no-unknown-target negative checks |

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 36 manifests for 36 skill directories. These drive the Tier 2
+There are currently 37 manifests for 37 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-convo.test.json

@@ -0,0 +1,15 @@
+{
+  "manifest_version": 1,
+  "skill": "rdc:convo",
+  "description": "Sandbox discussion preserves missing peer uncertainty and does not dispatch or implement.",
+  "fixture": {
+    "prompt": "rdc:convo plan-critique Evaluate a proposal to mark CDE complete after typecheck alone. No peer response is available. Return the simulated packet and unresolved decision; do not contact peers or edit files.",
+    "env": { "RDC_TEST": "1" }
+  },
+  "assertions": { "exit_code": 0, "stdout_contains": ["UNKNOWN"] },
+  "acceptance": {
+    "output_contains": ["UNKNOWN", "plan-critique"],
+    "output_not_contains": ["Claude agreed", "CDE is complete", "validator passed"]
+  },
+  "teardown": { "reset_branch": true }
+}

package/tests/convo.test.mjs

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { getSkill, getSkillBody, resolveSkillName, searchSkills } from '../lib/catalog.mjs';
+import { toCloudBody } from '../lib/cloud-rewrite.mjs';
+
+const names = ['outcome-exploration', 'design-comparison', 'troubleshooting', 'plan-critique', 'disagreement-resolution', 'work-handoff'];
+
+test('convo resolves explicit invocation and ships complete templates in both caller variants', () => {
+  for (const alias of ['convo', 'rdc:convo', '/rdc:convo']) assert.equal(resolveSkillName(alias), 'convo');
+  assert.equal(resolveSkillName('convo/../../deploy'), null);
+  const meta = getSkill('convo');
+  assert.equal(meta.codeflow_required, false);
+  assert.deepEqual(meta.produces, ['discussion_record', 'decision_record']);
+  assert.ok(searchSkills('fair discussion').some(row => row.name === 'convo'));
+  const source = readFileSync(new URL('../skills/convo/SKILL.md', import.meta.url), 'utf8').replace(/\r\n/g, '\n');
+  const body = getSkillBody('convo');
+  assert.equal(body, source.replace(/^---\n[\s\S]*?\n---\n+/, ''));
+  for (const rendered of [body, toCloudBody(body)]) {
+    const templates = [...rendered.matchAll(/```json\n([\s\S]*?)\n```/g)].map(m => JSON.parse(m[1]));
+    assert.deepEqual(templates.map(t => t.template), names);
+    for (const template of templates) {
+      assert.ok(template.inputs.length >= 3, template.template);
+      assert.ok(template.process.length >= 2, template.template);
+      assert.ok(template.outputs.length >= 2, template.template);
+      assert.ok(template.owner && template.dissent && template.handoff);
+    }
+    assert.match(rendered, /UNKNOWN/);
+    assert.match(rendered, /DEFER/);
+    assert.match(rendered, /RDC_TEST=1/);
+    assert.match(rendered, /Silence is not agreement/);
+    assert.match(rendered, /rdc:plan/);
+    assert.match(rendered, /rdc:build/);
+    assert.doesNotMatch(rendered, /127\.0\.0\.1:52437/);
+  }
+});

package/tests/npm-ignore-parity.test.mjs

@@ -0,0 +1,26 @@
+// .npmignore replaces .gitignore for npm. It must carry every .gitignore rule except
+// git-sha.json — the pack-time commit stamp that is untracked in git and exists to be
+// shipped — or the package either loses the stamp or starts shipping what git ignores.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const rules = (file) => new Set(fs.readFileSync(path.join(ROOT, file), 'utf8')
+  .split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
+
+test('.npmignore is .gitignore without the commit stamp', () => {
+  const git = rules('.gitignore');
+  const npm = rules('.npmignore');
+  assert.ok(git.has('git-sha.json'), 'the stamp stays out of git');
+  assert.ok(!npm.has('git-sha.json'), 'and stays IN the package');
+  const expected = [...git].filter((r) => r !== 'git-sha.json').sort();
+  assert.deepEqual([...npm].sort(), expected);
+});
+
+test('the installer records the stamped commit when it runs from a package with no .git', () => {
+  const installer = fs.readFileSync(path.join(ROOT, 'scripts', 'install-rdc-skills.js'), 'utf8');
+  assert.match(installer, /git-sha\.json/);
+});