@lifeaitools/rdc-skills 0.35.26 → 0.37.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.35.26",
+  "version": "0.37.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",
@@ -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/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v0.37.0 — review gates run the deterministic validators, in 1–2 minutes
+
+### Changed
+- The code-review step in `rdc:build` (9b), `rdc:fixit` (5.5), `rdc:review`
+  (8b), `rdc:release` and `rdc:overnight` now runs one deterministic gate,
+  `guides/review-gate.md`:
+  - `rdc-solid-score --diff <base>`;
+  - the repo linter on changed files (`--write`, then check);
+  - `tsc`;
+  - the touched package's tests;
+  - the UI spec when a route changed.
+
+  On the PRT launch build it took 9.3 s over 33 changed code files, where each
+  open-ended `pr-review-toolkit:code-reviewer` pass had taken 4–10 minutes. The
+  reviewer agent remains, but only for a named question the validators cannot
+  answer.
+- `rdc-clean-code-score` is documented as advisory. It has no `--diff`, and in a
+  monorepo it needs `--project-root <package>`; its default dead-export scope ran
+  out of 4 GB of heap on regen-root.
+
+### Fixed
+- `rdc-solid-score --diff` exited 2 on any diff that added a file. Git's
+  "exists on disk, but not in <ref>" wording was not recognized as absent at the
+  ref; it now is. A bad ref or a path-form mismatch is still rethrown.
+- `rdc-solid-score --diff` exited 2 with ENOENT on any diff that deleted a file.
+  Deletions are now split out with `--diff-filter=D` and reported in a new
+  `removedFiles` output field.
+- The README File Structure omitted `convo` (shipped in 0.36.0), which failed
+  `npm run test:acceptance`.
+
+---
+
 ## v0.35.11 — Design Review is explicit opt-in
 
 ### Changed

package/README.md

@@ -321,6 +321,7 @@ skills/
   co-develop/SKILL.md  (peer-aware Claude/Codex co-development)
   collab/SKILL.md      (bidirectional claude.ai ↔ Claude Code relay)
   convert/SKILL.md     (Office/Markdown conversion)
+  convo/SKILL.md       (attributed discussion that converges to a decision)
   deploy/SKILL.md      (Coolify ops: deploy, new, diagnose, audit)
   design/SKILL.md      (RDC/Studio design, Palette Library, Rampa CLI)
   edit/SKILL.md        (local website editor launcher)

package/commands/compare-compliance.md

@@ -8,4 +8,8 @@ description: rdc:compare-compliance <path> --diff <ref> — gate a change agains
 Use Skill tool with skill: "solid-validator", passing the path and a
 required `--diff <ref>` as args. Read `regressions` and `boundaryViolations`
 from the output — either non-empty means the change made compliance worse
-than the base ref, not merely "still imperfect."
+than the base ref, not merely "still imperfect." `removedFiles` lists what the
+change deleted; those are reported, never scored.
+
+This is step 1 of the review gate. For the whole gate (lint, tsc, tests and UI
+spec as well), follow `guides/review-gate.md`.

package/commands/quick-check.md

@@ -7,4 +7,6 @@ description: rdc:quick-check <path> — fast mechanical pass, SOLID score and bo
 
 Use Skill tool with skill: "solid-validator", passing the path as args.
 This is the mechanical-only subset — no judgment dispatch, meant to run in
-seconds during active editing. Use `full-analysis` before a merge.
+seconds during active editing. Before a merge, run the review gate in
+`guides/review-gate.md`, which takes one to two minutes. `full-analysis` is a
+deeper advisory pass, not the merge gate.

package/git-sha.json

@@ -1,3 +1,3 @@
 {
-  "sha": "31c8a8246ec68e424893534d7da36166f52a6f73"
+  "sha": "15c0b76b2fa48b6ab335478041940337a84da588"
 }

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.