fix: resolve docs audit residuals R.1–R.3 and retire audit (#124)

Closes May 2026 docs fact-check audit R.1–R.3. Adds MCP files/symbols resources, state-dir recipe resolution, function_params.owner_kind, docs/plans sweep, and dependency updates.

Author: SutuSebastian

.agents/lessons.md

@@ -1,10 +1,14 @@
 # Lessons
 
-Persistent log of corrections and insights from past sessions. Agents **must** check this file at the start of every session and append new lessons after corrections.
+Persistent log of corrections and insights from past sessions. Read when relevant; **encode durable lessons in rules/skills** — this file is a staging area, not an archive.
 
-## Format
+## Rules
 
-Each entry is a single bullet: `- **<topic>** — <lesson>`. Newest entries at the bottom.
+1. **Append only durable, non-obvious corrections** — not session trivia already captured in a rule, skill, or reference doc.
+2. **Prefer lifting** — when a lesson becomes policy, move it to `.agents/rules/` or the relevant skill and **delete** the bullet here (or supersede with one line pointing at the rule).
+3. **Keep entries atomic** — one lesson per bullet. One sentence.
+4. **No duplicates** — check before appending; merge or supersede instead.
+5. **Supersede, don't accumulate** — outdated lesson → replace with a new bullet citing what changed; don't leave both.
 
 ## Lessons
 

.agents/rules/agents-tier-system.md

@@ -28,7 +28,7 @@ Genuinely cross-cutting. Apply to every turn regardless of file:
 - `codemap` — STOP-before-grep
 - `concise-comments` — sweep your own new comments before reporting
 - `concise-reporting` — extreme concision in agent reports
-- `lessons` — read at session start, append after corrections
+- `lessons` — read when relevant; lift durable ones into rules/skills
 - `no-bypass-hooks` — never `--no-verify` on `git commit`
 - `pr-comment-fact-check` — fires the fact-check skill on PR-comment intent triggers
 - `preserve-comments` — never silently delete TODOs / commented-out code
@@ -45,7 +45,7 @@ Today's Tier-2 rules:
 
 - `agents-tier-system` (this rule) — auto-attaches when authoring under `.agents/**` or `.cursor/**`.
 - `docs-governance` — primes the docs framework when authoring under `docs/**` or `.agents/**` (paired with [`docs-governance` skill](../skills/docs-governance/SKILL.md)).
-- `plan-pr-inspiration-discipline` — primes plan-PR / recipe authoring with the open-spec inspection list when authoring under `docs/plans/**` or `templates/recipes/**`. The canonical inspection-sources table lives in the rule body itself (lifted from `research/non-goals-reassessment-2026-05.md § 4` in 2026-05; see [§ 7 Lifted to](../../docs/research/non-goals-reassessment-2026-05.md#7-lifted-to)).
+- `plan-pr-inspiration-discipline` — primes plan-PR / recipe authoring with the open-spec inspection list when authoring under `docs/plans/**` or `templates/recipes/**`. The canonical inspection-sources table lives in the rule body itself.
 
 ### Tier 3 — Discoverable skills (no rule)
 

.agents/rules/docs-governance.md

@@ -21,28 +21,28 @@ The canonical Rules (1–10) live in [`docs/README.md`](../../docs/README.md) 
 
 ## Five lifecycle types (universal)
 
-| Type          | Folder                                                | Closing                                                             |
-| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
-| **Reference** | root (`architecture.md`, `glossary.md`, etc.)         | Lives forever; kept current                                         |
-| **Roadmap**   | root (`roadmap.md`, single file)                      | Lives forever                                                       |
-| **Plan**      | `plans/<name>.md`                                     | **Delete + lift** when work ships (no "Slim & keep in plans/")      |
-| **Audit**     | `audit.md` (single) OR `audits/<topic>.md` (multi)    | Substrate variants — see skill                                      |
-| **Research**  | `research/<tool>.md` OR `research/<topic>-YYYY-MM.md` | Adopted (lift + delete) / Rejected (keep with status header) / Open |
+| Type          | Folder                                                | Closing                                                                                                     |
+| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Reference** | root (`architecture.md`, `glossary.md`, etc.)         | Lives forever; kept current                                                                                 |
+| **Roadmap**   | root (`roadmap.md`, single file)                      | Lives forever                                                                                               |
+| **Plan**      | `plans/<name>.md`                                     | **Delete + lift** when work ships (no "Slim & keep in plans/")                                              |
+| **Audit**     | `audit.md` (single) OR `audits/<topic>.md` (multi)    | Substrate variants — see skill                                                                              |
+| **Research**  | `research/<tool>.md` OR `research/<topic>-YYYY-MM.md` | Adopted → lift + **delete** (unless inbound cites require slim stub) / Rejected → status header only / Open |
 
 ## Top three disciplines
 
 1. **Anchor preservation** — slim READMEs keep cited rule numbers and section anchors. Grep before any slim: `rg "Rule [0-9]+" docs/` and `rg "<doc-path>(#[a-z-]+)?"`.
 2. **Anti-bloat meta-rule** — don't add a rule until there's content that needs it. Same for ownership-table rows.
-3. **Repo-level vs in-source** — repo-wide tool evaluations + adoption (oxlint, future plugins) live in `.agents/`, not as permanent `docs/research/` files. A `docs/research/` file may motivate the adoption, but the rule + skill earn the permanent home. Per-tool tracker notes (peer-tool comparisons, adoption-candidate logs) are an anti-pattern — peer-tool framing goes off-mission fast; positioning lives in [`docs/why-codemap.md`](../../docs/why-codemap.md) and [`research/non-goals-reassessment-2026-05.md`](../../docs/research/non-goals-reassessment-2026-05.md), not in tracker files.
+3. **Repo-level vs in-source** — repo-wide tool evaluations + adoption (oxlint, future plugins) live in `.agents/`, not as permanent `docs/research/` files. A `docs/research/` file may motivate the adoption, but the rule + skill earn the permanent home. Per-tool tracker notes (peer-tool comparisons, adoption-candidate logs) are an anti-pattern — peer-tool framing goes off-mission fast; positioning lives in [`docs/why-codemap.md`](../../docs/why-codemap.md), not in tracker files.
 
 ## Existence test (apply on every doc-touching PR)
 
 A file earns its place if it meets at least one of:
 
 1. Source code cites it (JSDoc, error message, comment grep-anchor)
 2. It documents durable policy unavailable elsewhere
-3. It tracks open work (audit findings, plan, roadmap items, evaluation)
-4. It carries unique historical context that `git log` + reference docs can't reconstruct
+3. It tracks open work (audit findings, in-flight plan, roadmap items, evaluation with unresolved items)
+4. Inbound source cites require a slim stub — deletion would orphan a live citation (not "interesting history")
 
 If none → fold + delete.
 

.agents/rules/lessons.md

@@ -1,14 +1,15 @@
 ---
-description: Read lessons at session start; append after corrections
+description: Read lessons when relevant; lift durable ones into rules/skills
 alwaysApply: true
 ---
 
 # Lessons Convention
 
 ## Rules
 
-1. **Read at session start** — At the beginning of every conversation, read `.agents/lessons.md` to avoid repeating past mistakes.
-2. **Append after corrections** — When the user corrects you or you discover a non-obvious mistake, append a bullet to the `## Lessons` section: `- **<topic>** — <lesson>`.
-3. **Keep entries atomic** — One lesson per bullet. Be concise (one sentence).
-4. **No duplicates** — Before appending, check if an equivalent lesson already exists.
-5. **Never delete lessons** — Only add. If a lesson becomes outdated, append a new one that supersedes it.
+1. **Read when relevant** — skim `.agents/lessons.md` when the task touches an area with past corrections; not a mandatory full read every session.
+2. **Append only durable, non-obvious corrections** — not session trivia already in a rule, skill, or reference doc.
+3. **Prefer lifting** — when a lesson becomes policy, move it to `.agents/rules/` or the relevant skill and remove the bullet here (or supersede with one line pointing at the rule).
+4. **Keep entries atomic** — one lesson per bullet. One sentence.
+5. **No duplicates** — merge or supersede instead of appending near-duplicates.
+6. **Supersede, don't accumulate** — outdated lesson → one replacement bullet; don't leave both.

.agents/skills/audit-pr-architecture/SKILL.md

@@ -196,10 +196,10 @@ This audit follows [docs/README.md Rule 6](../../../docs/README.md) (no inventor
 
 Once findings are shipped (or deferred to `roadmap.md`):
 
-1. **Update Status header**: `Status: Closed (YYYY-MM-DD) — N findings shipped on commits <hash>, <hash>, <hash>; M deferred to roadmap.md § <section>.`
-2. **Add to `roadmap.md` § Closed audits (pointers)** with a one-line summary.
-3. **Apply [`docs-governance`](../docs-governance/SKILL.md) § Closing an audit re-derivable test.** If the audit has no source-cites, no unique policy, no rejected-alternatives rationale → digest deferred items into `roadmap.md`, then **delete the audit file** (no tombstones). Otherwise slim per the keep-criteria.
-4. **Run [`docs-lifecycle-sweep`](../docs-lifecycle-sweep/SKILL.md)** if the closure changes the audit substrate (new topic file, retired old topic) so the rest of the audits/ folder stays evaluated.
+1. **Update Status header** (only if the file stays): `Status: Closed (YYYY-MM-DD) — N findings shipped; M deferred to roadmap.md § <section>.` Prefer the closure PR as the durable anchor — not a growing commit-hash list in the doc body.
+2. **If the audit file is deleted**, cite the shipping PR in the closure PR description — do not add tombstone rows or deleted-path recovery instructions in living docs (see [`docs/README.md` § Closing audits](../../../docs/README.md#closing-audits)).
+3. **Apply [`docs-governance`](../docs-governance/SKILL.md) § Closing an audit re-derivable test.** If the audit has no source-cites, no unique policy, no rejected-alternatives rationale → digest deferred items into `roadmap.md`, then **delete the audit file** (no tombstones). Otherwise slim to cited sections only — not full findings prose.
+4. **Run [`docs-lifecycle-sweep`](../docs-lifecycle-sweep/SKILL.md)** only when closure leaves other files in `docs/audits/` or `docs/research/` that fail the existence test — not as a mandatory post-step on every closure.
 
 ## Anti-patterns
 

.agents/skills/diagnose/SKILL.md

@@ -111,6 +111,6 @@ Required before declaring done:
 - [ ] All `[DEBUG-…]` instrumentation removed (`grep` the prefix)
 - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
 - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-- [ ] If the post-mortem yields a permanent insight, append a one-line entry to [`.agents/lessons.md`](../../lessons.md) per the lessons-rule discipline
+- [ ] If the post-mortem yields a permanent insight, **lift** it into `.agents/rules/` or the relevant skill; append to [`.agents/lessons.md`](../../lessons.md) only when it is not yet encoded elsewhere
 
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md) with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.