Skip to content

MODES.md

Latest commit

 

History

History
46 lines (41 loc) · 3.04 KB

MODES.md

File metadata and controls

46 lines (41 loc) · 3.04 KB
Raw

Verbosity modes

ai-codekeep is silent by default in any repo that hasn't opted in — no mode file means off. Set the mode with /ai-track-mode <level> or node bin/ledger.mjs mode <level>.

Every mode uses at most two trailer lines, ever: the compact Ai-Codekeep-Ledger: field-value trailer, and a plain-text Change-Reason: line. What escalates across modes is which fields go into that one trailer value — never a growing wall of separate lines. See docs/DATA-MODEL.md for the exact field grammar.

Mode Commit trailer Ledger detail Inline code comments Merge summary Blocks on missing reason / new hotspot?
off none none none none no
minimal Ai-Codekeep-Ledger: ai=N only, no Change-Reason line file entry, no history never none no
standard (default once enabled) Ai-Codekeep-Ledger: ai=N;class=...;incident=... + Change-Reason: full history + risk score never one-paragraph AI-share delta, informational no — falls back to Change-Reason: unspecified
verbose same fields as standard full history provenance comment on newly AI-written blocks only, never on edits to existing human code full hotspot diff, informational no — same fallback as standard
audit same fields plus model=...;session=... full history, per-hunk on all touched blocks full report + risk trend, blocking yes — asks the user before committing/merging

Design intent

  • Escalating a mode should only ever add detail, never change the meaning of an existing field, so old ledger entries stay valid after a mode change.
  • Inline code comments are opt-in and start disabled even at standard because they're the part of this system most likely to rot — a comment saying "AI wrote this" next to a line a human has since rewritten twice is actively misleading. The ledger's history array is the source of truth; comments are a convenience surfaced only when a team has explicitly asked for one.
  • off must be fully inert: no files created, no trailers added, no prompting. A repo that hasn't run ai-codekeep mode <level> at least once should be indistinguishable from a repo that never installed the skill.
  • Only audit ever blocks a commit or merge. Interrupting the developer to ask for a reason, or halting a merge over a hotspot, is a real flow/ cognitive-load cost — reserving it for the one mode a team explicitly chose for that tradeoff, rather than defaulting to it at standard, follows the DevEx framework's warning against taxing flow for the sake of a metric.
  • The trailer never grows past two lines, even at audit. It exists only to get data into .ai-codekeep/ledger.json — a commit message with a wall of provenance trailers is exactly the squash-merge/clean-history disruption this system is supposed to avoid causing in adopting teams. If you want richer detail than audit's two lines give you, that detail belongs in the ledger, not in a longer trailer.