Skip to content

Maintenance Loop

Jump to bottom
Yuriy Orlov edited this page Aug 27, 2026 · 1 revision

Maintenance Loop

Knowledge rots as code moves; KAUT's answer is a loop that keeps repair cheaper than rot. Freshness is detected mechanically at read time (a git diff, no AI), code changes name the docs they owe an update, re-derivation gets a precise delta bundle instead of a blank page, and every write lands through a gate — agent-tier updates directly, owner-gated ones as drafts the owner reviews in batches. Telemetry closes the loop by recording whether the knowledge actually helped. Mechanism detail: docs/HANDBOOK.md §5 and §8b; the write gate and journal contract: SCHEMA.md §24 and §13.

Read side: verdicts at lookup, reading is repair

Every kaut lookup answer carries exactly one freshness verdict — healthy, stale, broken, tampered, disputed, or an ephemeral branch-advisory — computed at read time by comparing the doc's bound sources against git. Nothing is stored; when in doubt the engine errs toward stale (a false "re-check this" costs a quick verification; a false "all fresh" costs a confident mistake).

The verdict routes the reader's trust: healthy and precise → use directly; stale/broken → confirm in code first. And that confirm is the repair opportunity — reading is repair: a session that hits a stale doc and re-verifies the facts in code is already holding everything a repair needs. The discipline is to land that repair (or queue it as a draft) instead of walking away, so the next reader gets a healthy doc instead of repeating the same verification.

Change side: kaut touched 

node <engine>/kaut.mjs touched src/api/booking.ts src/stores/cart.ts

The change-site sensor: given the repo-relative files a session edited, it names every doc whose source bindings — doc-level or section-level — cover them. A non-empty answer is the session's update debt: update the doc (agent layer) or queue a draft (owner layer) before closing. Pure read; also available as the kaut_touched MCP tool.

Repairing cheaply: kaut refresh 

node <engine>/kaut.mjs refresh [<id>…]

For each doc, a re-derivation delta bundle: the target ref (the tracked main line's tip — re-derivation must never anchor to a branch or the working tree), the sources that changed since derivation with their git status, the sections those files hit, and dead patterns to re-bind. Row statuses:

  • current — no source drift; nothing to do
  • delta — sources changed; re-derive the flagged parts
  • mechanical — adapter-generated map; regenerate with kaut map, never hand-rewrite
  • wrong-repo-anchor — the anchor commit belongs to a different repo (harvest error); the diff is meaningless — re-derive fully
  • off-main-anchor — the anchor exists but is branch-anchored — re-derive fully
  • invalid — the doc fails the contract

The engine hands over the delta; the agent rewrites the prose; the write gate lands it.

The write gate

Every store write funnels through one commit chokepoint, where the layered write policy decides (SCHEMA.md §24):

  • Agent tier — updates to layers granted agent land directly: via kaut index from the CLI, or the kaut_write MCP tool. The Tier-A discipline: only facts the writing session actually verified (honor-system — the engine enforces the policy, not the verification).
  • Owner-gated — owner layers and novel doc ids are refused at the chokepoint and go through the draft queue instead: the session writes the complete updated doc and runs kaut draft <id> (or the kaut_draft MCP tool). The draft is contract-validated and anchor-checked at the queue door, committed durably, and never served to readers — lookups of the target doc only note that a draft is pending.
  • The owner lands batches — kaut review lists the queue, kaut review <id> shows the diff, kaut review --approve <id>… promotes and lands (the commit carries an owner-approved audit tag), --reject drops. One sitting replaces owner presence in every session; doctor warns while the queue is non-empty. These owner verbs are CLI-only — deliberately not exposed over MCP.

With no workspace policy configured the gate is inert (open-until-configured).

Telemetry: kaut note and kaut digest 

node <engine>/kaut.mjs note domains/search confirmed --note "invariant held on main"
node <engine>/kaut.mjs digest --since 2026-08-01

kaut note records how a doc the session used actually fared — trusted (used without reading code), confirmed (verified in code anyway), insufficient (didn't answer; fell back to code — the note that draws the coverage boundary), stale-misled (wrong and misleading). Honor-system, but it turns the journal's reach record into a value record.

kaut digest aggregates the per-store journals across a workspace: reach (lookups by mode and verdict — how often a read hit a stale doc), self-maintenance (writes by tier), value (the outcome distribution), top topics, per-store breakdown. This is the evidence for the honest question the system asks of itself: is it actually helping? (docs/HANDBOOK.md §12.)

The loop in one pass

  1. A session looks up a doc → the verdict says whether to trust or confirm.
  2. Stale or insufficient? The session confirms in code — and repairs: agent-tier via the write gate, owner-tier via a draft.
  3. The session edits code → kaut touched names the docs owed an update before closing.
  4. kaut refresh makes any re-derivation cheap and correctly anchored.
  5. The owner reviews the draft queue in one sitting.
  6. kaut note + kaut digest record whether any of it was worth it.

Clone this wiki locally