ADR-0202shipped

Turn-Level Mandatory Knowledge Writes (Force/Enforce/Verify)

Status

Accepted

Context

ADR-0199 established system knowledge retrieval direction, but live audit on March 3, 2026 confirmed write-side enforcement was weak:

  • joelclaw knowledge sync only indexed ADR + skill docs.
  • lesson, pattern, and failed_target queries were sparse/empty in practice.
  • Turn-level writes were not enforced across gateway and non-loop system-agent turns.

Per ADR-0200, this is a cross-cutting concern and must ship with Force + Enforce + Verify, not policy text alone.

Decision

For every tool-using or otherwise meaningful turn, the system must do exactly one of:

  1. Write a knowledge note, or
  2. Record an explicit knowledge.skip reason.

This is non-optional for eligible turns.

Canonical turn-write contract

All producers use one contract (knowledge/turn.write.requested) with these fields:

  • context: source, agent, channel, session, turnId, turnNumber
  • content: summary, optional decision, optional evidence[]
  • usefulness: usefulnessTags[]
  • optional skip: skipReason ∈
    • routine-heartbeat
    • duplicate-signal
    • no-new-information

Force / Enforce / Verify mapping

Force

  • CLI surface: joelclaw knowledge note ... (canonical operator entrypoint)
  • Gateway: default-on turn capture in central turn-end flow
  • System agents: at least one loop stage emits same contract (agent-loop-implement)

Enforce

  • Write processor (knowledge-turn-write) validates payload semantics:
    • summary required unless skip reason present
    • invalid skip reasons are rejected
  • Eligible turn policy is encoded in runtime flow (not advisory docs)

Verify

  • OTEL lifecycle events for write attempts:
    • knowledge.turn_write.started
    • knowledge.turn_write.completed
    • knowledge.turn_write.skipped
    • knowledge.turn_write.failed
  • Eligibility telemetry:
    • knowledge.turn_write.eligible
  • Scheduled compliance watchdog compares eligible turns vs accounted outcomes and alerts on drift.

Implementation scope in this ADR

Implemented now:

  1. joelclaw knowledge note command added.
  2. Gateway turn-end flow emits contract events by default (capture or explicit skip).
  3. Agent-loop implement stage emits same write contract.
  4. knowledge-turn-write function writes turn notes to system_knowledge and emits OTEL lifecycle events.
  5. knowledge-watchdog now checks turn-write compliance drift.

Consequences

  • Write volume increases by design; filtering/ranking is a downstream concern.
  • Missing INNGEST_EVENT_KEY or dispatch failures now produce observable compliance drift instead of silent data loss.
  • Knowledge index includes turn_note records, improving retrieval context over time.

Follow-ups / known gaps

  1. Expand system-agent coverage beyond agent-loop-implement to all major stage handlers.
  2. Add richer relevance scoring and post-capture filtering for high-volume turn notes.
  3. Add dashboard views for eligible vs accounted trend over time.

2026-03-04 Reality Check

Status updated to shipped.

What’s running

  • packages/system-bus/src/inngest/functions/knowledge-turn-write.ts — Inngest function handling knowledge/turn.write.requested events
  • packages/gateway/src/knowledge-turn.ts — gateway emits knowledge/turn.write.requested per eligible turn
  • Registered in host function set (index.host.ts)
  • Skip reasons (routine-heartbeat, duplicate-signal, no-new-information) enforced at write processor
  • OTEL events: knowledge.turn_write.started/completed/skipped/failed

Gap: compliance watchdog not yet checking turn-write rate

  • knowledge-watchdog (ADR-0199) checks collection health but not turn-write eligible vs accounted ratio
  • Needs a scheduled compliance check per ADR-0202 spec