ADR 0160: A local logbook of discern's own use, on by default, with advisory-only readers

Amendments.

• ADR 0393 — merge recovery: the shared update core records merge outcomes independently of invocation success. Update and acceptance recovery additionally project the recurring-file finding from bounded local evidence. The finding remains advisory.
• ADR 0166 — identity: the logbook now records source-labelled coding-agent identity signals when cheap hints exist. They remain evidence, never a vendor verdict, and never steer product behaviour. The rest of this decision is unchanged.
• ADR 0190 — cohorts: the provider-comparison deferral in this record's explicit nos is lifted — its stated condition, a cheap honest hint, is met — under standing conditions: facts beside denominators and never rankings, invocation-scoped cohort keys only, recorded per-cohort minimums, and the unattributed share always visible. Export, session replay, and guidance-amendment drafting stay deferred.
• ADR 0194 — landing consent: a successful accept event now records its consent source (conversation, standing-grant, or effort-grant) and the covering scope names for a standing grant. The local, metadata-only, evidence-first, and advisory boundaries below stand.
• ADR 0210 — invocation start: effectful verbs now append an automatic begin event, paired to their completion event by an invocation id. The local, metadata-only, non-interfering, and advisory boundaries below stand.
• ADR 0320 — first-run health: doctor treats enabled empty storage as healthy, distinguishes disabled, invalid, and write-denied states, and degrades environment-denied recording to a warning for the current process. Unmatched begin events remain interruption or crash evidence outside Doctor's storage-health result. Logbook availability never gates setup.

Status: accepted

Every discern surface answers the question "what is true now?" — status, doctor, improvement, and a done receipt are all point-in-time snapshots. The missing axis is time. discern keeps no memory of how agents drive it: the verbs they call and their order, what the gate fails on and how often, how long each step takes, how many loops a task needs before green.

That memory would answer the one question none of the existing verbs can. An owner watching agents drive discern oddly is looking at one of three distinct failures. The agents may be misusing discern (a guidance gap). The gate may be mis-fit for the stack (a configuration defect). Or discern itself may be confusing (a product defect). From the outside all three look identical — "something feels wrong". Agent-first development often makes the owner a novice in some layer of the stack, and that is precisely when they lean on agents most. Each failure mode has a distinct behavioural signature in a trace. None has any signature in a snapshot.

Much of the raw material already exists, transiently. The job runner times every gate step, and the durations flow through the result envelope into the rendered receipt — then evaporate. The storage pattern has precedent too: the per-worktree resource records (ADR 0025) are schema-versioned files under the git common dir. Every linked worktree shares that directory, and nothing in it lands in a commit or leaves the repository. A maintainer research note ("the journal", July 2026, private tier) assembled the full idea. This record adopts it, with amendments noted below.

Four forces bound the design:

• The trust posture is discern's identity. The trust page promises zero network calls and zero telemetry, and currently promises that discern measures nothing about usage. Any recording must demonstrably extend that promise — everything inspectable, deletable, local — or it erodes the product's central claim.
• Advisory readers must never gate. A heuristic over history will have false positives. ADR 0084 already established that a false positive which fails the gate is intolerable, and that it trains agents to ignore the whole surface. A wrong advisory costs a glance.
• discern.toml churns by design. Every standards pin rewrites a limit, so a longitudinal comparison keyed to a naïve config fingerprint would shatter history into useless slivers. The feature needs a drift model that separates real reconfiguration from the ratchet doing its job.
• The value is entirely retrospective. Whenever the analysis is first wanted, only data recorded before that moment can answer it — the strongest argument in the default-on/opt-in trade-off below.

The substrate: a logbook. One append-only, human-readable event log in JSON Lines under the git common directory, beside the resource records. Every workflow-verb invocation appends one event on completion: verb, surface (CLI or MCP), branch, HEAD, tree cleanliness, outcome, wall-clock duration, the per-step timings the gate already measures, diagnostic classes (rule id, tool, file path at most), and a config-epoch fingerprint. Each event carries a schema version. Readers tolerate unknown fields and unknown versions.

• Metadata, never payloads. No code, no prompts, no command output bodies, no file contents. The bar: the logbook is safe to read aloud.
• Local, forever. The git admin area never lands in a commit and needs no gitignore entry, and nothing transmits. An architectural test asserts the subsystem's module graph reaches no network API — the promise held by a check, in the manner of principle 13.
• Events attribute by branch name, not worktree path — attribution survives accept removing the worktree.
• Recording never interferes. Appends are single-line and atomic. A write failure never fails the verb. Overhead stays unmeasurable next to any gate step.

On by default, with the one switch it earns. A single toggle under [project] opts out, and a reset action deletes the accumulated history. Principle 9 — every subsystem is core, and a toggle exists only for what costs something when unused — applies here rather than bending: recording writes on every verb even when nobody ever reads the logbook, the same test [skills].exclude survived. Default-on deliberately reverses the research note's own first principle (opt-in, off by default). The value is retrospective, so opt-in guarantees an empty history at the first moment of need — and recording costs nothing the trust posture actually protects, because nothing leaves the machine. When this ships, the trust page changes: "no network, no telemetry" stays absolute, while "nothing measured" gains the logbook as its one named, inspectable, deletable exception.

One substrate, many readers — and every reader advises. Recording and interpreting are separate layers. Events are evidence. Interpretation lives in readers that improve release over release on the same accumulated history, so yesterday's logbook gets smarter as readers do. No reader ever touches ok, an exit code, or a gate stage — standards remain the only enforcement surface. Where a reader finds something enforcement-worthy, it proposes the structural move — a guidance line, a class guard, a [standards] stanza with today's value as the limit — and a human decides. That is the same discovery→enforcement bridge as ADR 0084, and the route that converts advice (which degrades, principle 10) into structure (which does not).

The first reader: discern patterns. A noun, per the verb canon (ADR 0120): it answers a question. It runs a registry of named detectors, each a checkable predicate over the event stream. A detector carries evidence in plain counts (ADR 0063 — facts, not judgments), a scope, and a recommended next step: often a bundled skill (thrashing on a red gate points at the diagnosis skill), a guidance amendment, or a standard proposal. The v1 detector families: agent behaviour (done-thrash, skipped prepare loops, done on dirty trees, edits landing on the trunk, abandoned worktrees, anomalous verb sequences), gate fit (a dominant stage, duration creep, a fix stage that never changes anything, and divergent test outcomes on the same HEAD — a mechanical flake detector), and the task funnel (loops-to-green, start-to-accept cycle time).

Findings route to the surface whose scope they match. The receipt and done carry only findings about this branch and this run — capped at one line, never affecting the receipt's validity. The receipt's meaning is the gate is green, and diluting it trains people to skim. status carries session-scope findings. improvement and the verb itself carry project-scope ones. Detectors split into two tiers: inline-cheap (a glance at recent events for this branch, allowed to ride receipt and status) and batch (run only under the verb, so done never pays for longitudinal analysis). Audience follows surface. Agent-correcting findings fire where the agent is; owner-decision findings fire where the human is.

Config epochs attribute drift instead of discarding history. Each event stamps a fingerprint of the config's behaviour-relevant projection: each section hashed on its own, with volatile values masked out. The projection masks a standard's limit and keeps its command, inputs, and measure mode. A pin therefore changes no epoch. Pins land as first-class events instead, so the limit trajectory over time reads straight back out of the logbook — the ratchet, visible. A real change flips exactly one section hash, and the logbook records which. Trend detectors compare within an epoch. Across a boundary they attribute — "gate p95 rose at the change to the test command" — instead of falling silent.

Small-N honesty. Every detector declares its evidence threshold, and the report says "insufficient evidence" rather than extrapolating. A young logbook produces a short report, not a confident one.

The explicit nos: no network path, in any release, ever. No payloads. No dashboards and no anomaly detection models — named threshold predicates only. No cross-project aggregation. No committed or team-shared logbook (a human-reviewed excerpt a user chooses to paste into a bug report remains future work, deliberately deferred). No auto-promotion of any finding to enforcement. No agent-vendor attribution in v1 — comparing providers is a reader that can accrete later if a cheap, honest hint exists.

• The diagnostic ladder completes. doctor answers is the install valid, improvement answers is the setup best practice, patterns answers is the practice actually healthy — previously unanswerable, and the question a novice owner needs most, because the three identical-looking failure modes get distinct signatures and distinct remedies.
• Guidance edits become falsifiable. Loops-to-green per task is an eval with ground-truth labels — the gate itself. A guidance amendment becomes an experiment whose effect shows in the median, which closes discern's defining loop: the tool that compiles the agents' instructions can now observe those instructions failing and propose the revision.
• The trust page gets more nuanced, and that is a real cost. The absolutes survive — no network, no telemetry — but "nothing measured" now carries a named exception. The safeguards are structural: the no-network guard in the gate, the read-aloud content bar, one-command deletion, and the logbook joining the enforced footprint inventory. The rewording lands with the feature, not before; until then the page stays true.
• The event schema is a compatibility surface for the life of the feature. Versioned from the first event. Readers must keep old logbooks readable, since the substrate's whole design is that features accrete as readers — fleet views, session replay, config-fitness presets are future readers, not new stores.
• A toggle is a promise to test both states forever — accepted, as it was for [skills].exclude.
• Disk growth is real. Rotation bounded by size or age ships in v1, and pruning is loud, never silent.
• Concurrent appends share one file across parallel worktrees. Atomic single-line appends are the bet. A torn-line-tolerant reader (skip and count lines that fail to parse) is the backstop, and crash-safety of the append path needs a test, not an assumption.
• v1 can start imperfectly tuned without harming anyone. Because no reader blocks, detector thresholds can start conservative and tune on accumulated history — this repository dogfooding the logbook provides the first corpus.

• Opt-in, off by default — the research note's own first principle, reversed here after deliberate reconsideration. Opt-in protects from a harm this design doesn't commit (data leaving the machine) at the cost of the harm it does commit (an empty history whenever analysis is first wanted). The trust promises that matter — the logbook stays local and stays inspectable — hold either way.
• Fingerprint the whole config for epochs. Rejected: standards pins rewrite the file by design, so whole-file hashing fragments history precisely in the healthiest repositories — the ones ratcheting. Masked section-wise projection distinguishes the ratchet from real reconfiguration and names the section that moved.
• Per-worktree logbooks, unified at read time. Rejected: the git common dir gives one shared home with zero unification logic, mirroring where the resource records already live, and events self-attribute by branch. The cost is append contention on one file, bounded by that same atomic-append bet.
• Gate on behavioural findings. Rejected on ADR 0084's reasoning, permanently: a heuristic false positive that blocks a task is intolerable, and an agent policed by its own usage statistics learns to game the logbook rather than fix the pattern. Standards stay the only enforcement surface.
• stats as the reader verb. Rejected: stats promises numbers; the product is diagnosis — patterns, deviations, and the recommended next step. The verb canon wants the noun that names what you get.
• A committed logbook, for a team-shared record. Deferred, not rejected: it reopens every privacy and merge question this design closes, for a benefit (shared history) no current reader needs. If a team story emerges, a digest — reviewed, deliberate, human-mediated — is the shape to explore.