[RevenuePuzzles]

Summary

This PR introduces lesson lifecycle management to prevent unbounded accumulation and ensure lessons stored in the GTM home are grounded in verifiable evidence. The changes are based on findings from the "Self-Evolving Coding Agents" survey (arXiv 2608.03392v4).

Changes

evidence.md — Lesson lifecycle and governance

• Lifecycle statuses: provisional → validated → retired
  • New lessons enter at provisional (one cited incident, one source)
  • Promotion to validated requires external evidence (second source, later outcome confirming prediction)
  • retired status for lessons that no longer apply, with reason preserved
• Usage tracking: Guidance for tracking which lessons are retrieved and applied
• Caps: Target ~30-50 active lines per file to prevent unbounded growth
• Retirement rules: 6-month review for provisional lessons without validation, unused lessons, or lessons contradicted by newer evidence

compound.md — Admission gating

• Cited incident requirement: Every lesson needs a verifiable source (conversation, result, quote, correction) — no "we think X" without evidence
• Consistency check strengthening: Check for contradictions and duplicates before writing; flag when over cap
• Lifecycle status assignment: New lessons enter at provisional; promotion needs external evidence

audit.md — Lifecycle health monitoring

• Lifecycle health check: Count lessons by status per file; flag files with mostly provisional lessons
• Size and cap monitoring: Report files over cap with retirement candidates
• Retirement candidates: Identify lessons flagged for removal with reasons

context-contract.md — Write safety reference

• Added reference to lifecycle rules and cited incident requirement

Research basis

Each change maps to specific findings from the survey:

Change	Paper finding	Citation
Lesson lifecycle with statuses	P11: "Every self-change gets an ID, a motivating trace, a predicted effect, an eval result, a status (candidate → active → revised / quarantined / retired), and an inverse"	§5.1, §9.2
Caps and retirement rules	P5: "Unbounded accumulation degrades retrieval until injecting skills is worse than injecting none... Keep a bounded active set. Track usage. Retire unused or zero-contribution items."	A:2605.19576, A:2608.05810
Cited incident requirement	P8: "A rule needs a cited, verifiable incident. Never prompt my reviewer with 'find what went wrong' without also allowing 'nothing went wrong'"	A:2607.13083
External validation for promotion	P9: "Weight lessons by external outcomes: tests passed, Emil accepted the result, a metric moved. Don't weight them by my own confidence."	A:2608.00017
Gating before commit	P6: "Defective skills contaminate the skills distilled after them, and post-hoc removal recovers only a little"	A:2608.05810, A:2608.25776

What I considered but deliberately left out

1. Automated usage tracking infrastructure: The survey suggests tracking usage counts, but adding a Python script or structured tracking would change the project's "plain Markdown" philosophy. Instead, I added lightweight annotation guidance that teams can adopt optionally.

2. Explicit lesson IDs: The survey's lesson record format (L-2026-10-18-01) is rigorous but would add friction to the human-readable Markdown files. The date + source in each line serves as a de facto ID.

3. Frozen eval set for measuring improvement: The survey recommends a held-out task set to measure whether the home actually improves outcomes. This would require significant infrastructure and is more appropriate for a follow-up that adds measurement tooling.

4. Conflict detection automation: The survey discusses checking consistency with existing libraries programmatically. This would require code changes; instead I strengthened the manual check instructions.

5. Per-client scoping enforcement: The context-contract already says "never let one client's data appear in another's home" but doesn't enforce it technically. Enforcement would need code changes beyond documentation.

Further recommendations (not implemented)

Prioritized list of improvements that could follow this PR:

1. Measurement framework (high value, medium effort): Add guidance for tracking whether campaigns that start from a populated home actually outperform fresh starts. This maps to P12: "Measure improvement across tasks, net of cost."

2. Structured lesson IDs (medium value, low effort): If teams want rigorous tracking, add a YAML-frontmatter option for lesson files with explicit IDs, creation dates, and validation history.

3. Automated conflict detection (medium value, higher effort): A Python script in scripts/ that parses the Markdown files and flags contradictions or duplicates before compound writes.

4. Retirement workflow (medium value, low effort): A new move (retire) specifically for reviewing and removing lessons, as a counterpart to compound.

5. Cross-home aggregation safeguards (high value for multi-client users): Technical enforcement that lessons from one client cannot leak into another's home, beyond the current documentation warning.

Testing

• python scripts/build.py --check passes
• All existing CI checks should pass (no behavior changes, only documentation/spec enhancements)