docs: record merged-work lessons

[e54-bot]

Summary

First merged-work retrospective for this repository (backfill window 2026-10-05 → 2026-10-15, 54 merged PRs inspected, evidence from review threads, fix chains, and check-runs). Adds docs/LESSONS.md with six reusable failure classes, per the wrightkit-merged-work-retrospective skill.

Five classes recurred in independent merged PRs inside a rolling three-day window and are escalated for the owner to pick a prevention home:

• Refs Recurring defect class: sibling paths enforce weaker subsets of the same contract #451 — sibling paths enforce weaker subsets of the same contract (feat(lookup): answer canonical Workshop name, signature, and settings queries #378, feat(lookup): scoped child lookup via Catalog::lookup_within #386, feat(settings): warn on near-misses of declared settings members (#403) #406, feat(settings): carry blocks under catalogued keys as written #413, feat(settings): emit pass-through member blocks verbatim at resolved positions #424, fix(settings): unify non-leaf occurrence rejection in source_edit and write #435, fix(settings): reject hero settings members for slots the hero lacks #438, test(parser): cover surplus action arguments in canonical arity validation #439)
• Refs Recurring defect class: declared catalog surface does not parse back #452 — declared catalog surface does not parse back (fix(parser): resolve bare enum members whose spelling contains a colon #443, fix(catalog): declare surface signatures for player-variable index actions #445, fix(parser): parse every declared localized catalog spelling in its locale #449)
• Refs Recurring defect class: emitted text is not verified by reparse #453 — emitted text is not verified by reparse (fix(settings): emit an empty Verbatim member without a trailing space #398, fix(settings): keep a bare 'name:' member from consuming the next line #404, fix: adversarial audit — parser, emitter, settings, CLI defects incl. localized round-trip #433, test(lexer): pin BOM emission parity and span coordinates #436, test(roundtrip): pin reparse-equivalence and diagnostic text for the fidelity regressions #437)
• Refs Recurring defect class: retained-source bookkeeping misjudges provenance span validity and scope #454 — retained-source bookkeeping misjudges provenance span validity and scope (fix(program): prune provenance spans that do not resolve in attached file source #410, fix(program): audit only the attached file's spans when retaining source #418)
• Refs Recurring defect class: post-MSRV syntax caught only by the MSRV CI job #455 — post-MSRV syntax caught only by the MSRV CI job (fix: adversarial audit — parser, emitter, settings, CLI defects incl. localized round-trip #433, fix(parser): parse every declared localized catalog spelling in its locale #449)

The sixth entry (implementation PR self-authorizing a contract decision, #373) is a single incident and is recorded pointing at the existing workspace policy; no escalation.

Test plan

• Maintainer reads docs/LESSONS.md in under a minute; each entry names rule, why, prevention home, incidents
• Escalation issues Recurring defect class: sibling paths enforce weaker subsets of the same contract #451–Recurring defect class: post-MSRV syntax caught only by the MSRV CI job #455 link the same PRs the entries cite