Skip to content

feat: lessons as a typed artifact with follow-through tracking #428

Description

@plind-junior

ClaimType already carries workflow and warning — the vocabulary of a procedural rule ("run mypy before pushing", "never git add -A here"). what's missing is the loop that makes such a rule earn its place: nothing records whether a surfaced rule was actually followed, and nothing warns at propose time when a near-identical rule already exists. so vouch can't distinguish a load-bearing convention that changes behavior from a stale one nobody heeds, and it accumulates duplicate near-restatements of the same rule.

this proposes a lesson-flavored claim with two additions: an append-only follow-through signal, and a propose-time repeat guard.

proposed surface

  • treat lesson as a claim subtype (either a new ClaimType.LESSON or a flag on workflow/warning claims) that resurfaces via retrieval like any approved claim.
  • kb.mark_lesson_followed(<claim_id>, followed: bool, context?) — appends an observation event to audit.log.jsonl. it does not edit the lesson; it records that the lesson was (or wasn't) applied in a given turn. these events feed the effectiveness scoring in chore(deps): bump actions/checkout from 4 to 6 #2 directly.
  • a repeat guard at propose time: when a proposed lesson strongly overlaps an existing approved lesson, surface the existing one loudly in the propose response (reuse find_similar_on_propose / feat: propose-time similarity warnings for duplicate claims #147) so the reviewer merges rather than duplicates.

four registration sites for mark_lesson_followed; tests/test_lessons.py. the follow-observation reuses audit.log_event — no new authoritative store.

review gate & scope

lessons are proposed and approved exactly like claims — no new write path. the follow-through events are append-only observations about usage, not edits to the lesson's text or status, so they can't mutate approved knowledge or bypass the gate; the worst case of a lost/replayed observation is a noisier effectiveness estimate, never a corrupted claim. the repeat guard only warns at propose time — it never auto-merges. local-first; observations live in the same append-only audit stream that's already authoritative.

acceptance criteria

  • a lesson artifact resurfaces through the normal retrieval path.
  • kb.mark_lesson_followed appends a followed/not-followed event to the audit log and edits nothing else.
  • proposing a lesson that strongly overlaps an approved lesson returns a loud similarity warning (via feat: propose-time similarity warnings for duplicate claims #147's path) without blocking.
  • follow-through events are consumable by the chore(deps): bump actions/checkout from 4 to 6 #2 effectiveness computation.
  • method registered in the four sites; test_capabilities passes.
  • tests/test_lessons.py covers the observe-not-edit invariant and the repeat-guard warning.
  • make check green.

related: #2 (effectiveness consumes follow-rate), #147 (propose-time similarity warnings), #314 (contradiction finder).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesthelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions