Engineering wisdom is write-only: make lessons-learned.md consumed at decision time (or retire + route it)

[waleedkadous]

SPIR — methodology/mechanism fix. codev/resources/lessons-learned.md is effectively write-only: durable engineering wisdom accretes into it, but nothing consumes it at decision time, so it can't change agent behavior under load. From a downstream-adopter field report, verified against the codev framework.

Problem (verified in the codev framework, not just an adopter)

Every framework reference to lessons-learned.md is producer/prune-side:

• The SPIR/PIR review phase + porch/prompts/review.md write entries to it.
• The update-arch-docs skill + MAINTAIN audit/prune it.
• The porch checks only enforce that the review file has a ## Lessons Learned Updates section — not that anyone reads the lessons.

Nothing reads or injects it at design/spec time, and nothing enforces it. codev's own CLAUDE.md/AGENTS.md don't even carry the voluntary "grep it before designing" line some adopters add. So it's append-only accretion with no consumer — documentation that hopes to be grepped, which under load agents don't do. Concrete downstream failure: a boolean-vs-role auth design miss that a written lesson could never have prevented, because the file isn't read at decision time.

Goal

Make durable engineering wisdom actually consumed at the moment it would change a decision — or retire the file and route wisdom into surfaces that are consumed. Principle: wisdom only changes behavior if it lives in always-on context (role / CLAUDE.md), an executed protocol step, or an enforced check.

Two candidate directions (spec phase to resolve)

A. Inject at design time — surface relevant lessons-learned entries into protocol/role context at spec/design time, or fold them into protocol steps. Hard part: relevance retrieval — dumping the whole file into every spec re-creates the unbounded-accretion problem, so it needs tagging/matching.
B. Retire + route into consumed surfaces — route each lesson by type: behavioral rule → role file / CLAUDE.md or a protocol step; "don't do X" pattern → a prose-presence / contract test; design-time consideration → injected into the relevant design prompt.

Architect's lean: (B) with a dash of (A) — route by type, reserve design-time injection for genuinely design-sensitive wisdom. The spec phase should weigh both and decide; this is a real design fork, not a mechanical fix.

Scope notes

• Touches protocol prompts/steps (spec/plan/review), role files, possibly a retrieval/injection mechanism, and the MAINTAIN / update-arch-docs producer side.
• Same family as the broader codev-framework-feedback theme (cf. the multi-architect coordination layer, Multi-architect coordination layer for codev/afx (roster · board · dedup-at-spawn · lifecycle · bounded state · checkout isolation) #984) — but a distinct concern: this is the consumption mechanism for durable wisdom.
• The adopter cited a research doc arch-md-codev-framework-feedback.md flagging the append-accretion failure mode; that doc is not in this repo's codev/research/ (adopter-side) — re-derive the accretion analysis here if needed.