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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions