Logbook

The logbookLogbook↗The local record of the project's use of discern. records local activity so you can inspect recurring failures, check durations, and changes in the way work gets finished. This reference defines its fields, reports, and storage controls.

Recording must be enabled to collect new evidence. Existing active or sealed history remains readable after recording stops. For help using findings, read Evidence and improvement.

With recording enabled and discern.toml readable, CLI verbs and MCP calls resolved to that project record local metadata. Effectful verbs add paired start and completion events with one invocation id. All worktrees share plain-text files in the repository's common Git administrative directory. The logbook excludes code, prompts, command output, and file contents.

An MCP call whose explicit path falls outside every discerndiscern↗A tool that installs and runs an agent development practice in a project. project returns no_project and records nothing. No project logbook or readable consent setting applies to that path.

• Read active history: discern patterns reports findings. For raw JSON lines, locate the common Git directory with git rev-parse --path-format=absolute --git-common-dir and read its discern/logbook/ month files. In the main checkout, the usual path is .git/discern/logbook/; a linked worktreeWorktree↗A separate working copy and branch for one effort.'s .git is a file pointing elsewhere.
• List and read sealed history: discern patterns archives, then discern patterns --logbook-file <filename>. Add --stats, --all, or --json as needed.
• Seal active history: discern patterns seal archives the current event lines for later reports and starts fresh active history. Preview the scopeScope↗A named set of project paths used to select work or policy. with --dry-run; application requires terminal confirmation.
• Delete active history: discern patterns reset permanently removes active history while preserving sealed archives. Preview with --dry-run; application requires terminal confirmation.
• Turn it off: set record_logbook = false under [project] in discern.toml. Recording stops. Existing active files remain until you archive or reset them.

Setting [project].record_logbook = false stops new evidence for every feature below. discern patterns can still read existing history.

• the practicePractice↗The connected way of working discern installs and the project carries between sessions. report (discern patterns): behavior, gateGate↗The configured checks a change must satisfy for ordinary completion.-fit, funnel, and trajectory findings over accumulated runs
• each worktree's last action and work in flight: the fleetFleet↗The project's collection of task worktrees. survey's last_action and running columns
• fleet activity times that include verb runs, so a long test run does not appear dormant
• configuration-change attribution and each standardStandard↗A held limit for a repeatable project measurement.'s limit history: the config-change and pin events
• tip-adoption counts: whether each shown tip's invited verb ran before that tip appeared again
• advisoryAdvisory↗A finding that suggests attention without blocking work. findings during work and merge-conflict recovery
• wait estimates when concurrent test runs queue, and contention readings
• the in-flight check on the contained-worktree offer; an installation with recording off uses a one-hour inactivity period
• recurring discern update and discern accept merge-conflict detection and mitigation
• observed checkpointCheckpoint↗A review question presented when a relevant kind of change occurs. economics (discern checkpoints)
• Logbook storage checks in discern doctor

Pattern findings classify family as trajectory, gate-fit, behavior, or funnel.

You can read the complete report on demand. Working commands also surface selected findings when they are relevant:

The working commands inspect at most the newest 200 events. patterns reads the full retained stream. Every route is advisory. Findings change no command outcome, exit code, failed gate stageStage↗A group in the order the gate runs work., score, Proof identity, or acceptance decision.

A finding's summary states the condition in plain language. Its observed field supplies the count, denominator, named subject, conditions, and material limitations. Shorter reports retain the same summary; open discern patterns when you need the underlying evidence.

discern patterns --stats summarizes recorded activity as counts and durations. Each rate includes its denominator so you can see how much evidence supports it.

discern patterns --stats

An accepted change is a successful accept, and its scale reads from the recorded change counts. Streaks count consecutive done runs in stream order. A cycle matches a start's created branch to the first later accept on it, the same way the funnel detector matches them. A cycle therefore needs both ends on record: an accept whose start predates the logbook counts as accepted without adding a cycle.

For the overlap reading, a branch is in flight from its first analyzed event to its last. A pause inside that window stays in flight. A branch stops counting after its last event, and the trunkTrunk↗The shared branch that accepted work joins, usually main. is not a change. The standards trend normalizes each standard to its own first reading, direction-adjusted so improvement is always positive. That shared scale lets a coverage floor and a byte-size ceiling average into one line, and lets "most improved" compare like-for-like. The Agents section uses the same cohort boundary as the detectors: the card counts identities below the reporting minimums without listing them, and always states the unattributed share.

A validation workflow run is an analyzed prepare, test, or done; recorded clean is its entry state. Complete, incomplete, and unattributed evidence share one run denominator. Current test and done writers always attach validation evidence. Older readable lines without it remain unattributed and cannot support a validation finding. At the standalone-test boundary, complete dirty validation counts tracked-only, untracked-only, mixed, or unclassified state without filenames. Full-Gate evidence follows mutating pre-groups, so a dirty entry remains unclassified instead of mixing moments.

A validation workflow cycle links recorded events on one branch under one config epoch. A successful start for a reused branch, a successful accept, or an epoch change closes it. After a clean green gate, a later dirty entry or different recorded HEAD begins another cycle. A run without an epoch stands alone.

A commit does not automatically end a cycle. Dirty pre-commit validation at one HEAD and the later clean done at its new committed HEAD stay in the same cycle. The test-first route begins dirty, the commit-first route begins clean, and an unknown first entry remains unattributed. The narrower pre-commit-to-clean-Gate count requires a dirty run, a later distinct recorded HEAD, and a clean green done on that later HEAD. Cycle construction uses the recorded stream only, so archived reports have the same result without consulting the current Git graph.

Each route reports cycles, branches, runs, successful and failed runs, cycles that reached a clean gate, cycles with a failure, and retries. A retry is every validation run after the first inside the same stream-defined cycle. The counts describe route shape; they do not prescribe an order or treat pre-commit testing as a defect.

Workflow cohort rows appear only when at least two identity cohorts clear the shared COHORT_MINIMUMS. Every speaking cohort carries cycle and run denominators, and the section retains below-minimum and unattributed cycle/run remainders. These task-confounded counts do not rank agents or imply capability.

Once the span holds 2 days, cadence sparklines sit beside the Accepted, gate, standards, Agents, and Breadth headings. Each listed agent carries its own usage series, and the shares render as filled bars beside their denominators. The same series ride the JSON (per_day, greens_per_day, trend, branches_per_day), capped at 24 points. A longer span folds whole days into each point and states the fold in series_days_per_point.

Stats uses the same analyzed population as the findings: CI runs, --dry-run previews, and setup-era events are excluded. Counts describe this project's recorded activity and assign no score, grade, or agent ranking. discern uses no external comparison corpus.

--json carries the counts as data.stats; the standards section is data.stats.standards. Over MCP discern_patterns takes stats: true. Without the flag the payload carries no stats key at all.

Stats is a separate counted projection of the same local evidence. It does not rewrite Pattern summaries or turn cohort counts into a comparison. Use the default discern patterns report when a finding's condition, evidence, limitation, and next action are the question.

A single accepted change keeps biggest and best day off the card, since either would restate the change itself, and streaks of one stay quiet. An empty logbook says there are no stats yet and suggests checking back.

seal preserves active history in an archive. reset permanently deletes active history. Both leave existing archives available.

discern patterns seal --dry-run
discern patterns reset --dry-run
discern patterns seal
discern patterns reset

The previews report the event count, date span, source files, bytes, and archive destination or deletion scope. They remain read-only under pipes, CI, --plain, --json, and --markdown.

Apply is a CLI-only owner action. It requires terminal input and output, operation outside CI and global --plain, and an explicit affirmative selection from a confirmation that defaults to Keep. Reset offers Keep or Delete; archive offers Keep or Archive. Pipes, --json, and --markdown apply refuse, and no flag or environment bypass exists. Declining preserves active history and existing archives. Other work can continue while you review. If active history changes before you confirm, rerun the command to review its current scope. Both actions refuse while active history contains another fresh unmatched invocation.

Archive atomically detaches logbook/, then copies the month shards' raw JSON Lines into a synced UTC-named file under logbook-archives/. A numeric suffix prevents collisions. epoch.json remains recorder state and is omitted. The final name is published atomically; only then is the detached source removed. A sealing failure leaves that source under logbook-recovery/ and reports its path.

A recorder arriving after detachment creates a fresh active directory. It never waits on the lifecycle lock, preserving fail-open recording. Archive and reset themselves record no logbook begin or completion, so one invocation cannot straddle the old and new histories. Reset targets only active logbook/; archives and other Git-admin state survive.

discern patterns archives
discern patterns --logbook-file logbook-20260811T143015Z.jsonl
discern patterns --stats --logbook-file logbook-20260811T143015Z.jsonl

The selector accepts one listed regular-file basename inside logbook-archives/. It rejects paths, traversal, symbolic links, directories, active month files, and names outside the archive format. Historical reports never modify the archive; their own event goes to the active logbook when recording is enabled. discern_patterns accepts the same optional selector. Operational readers always use active history.

The following fields describe stored JSON lines and how retained history is managed.

Each line contains names and numbers. It excludes code, prompts, command output, and file contents.

The current event schema major is 1. Readers skip an unknown major and tolerate additive fields. Every event has schema, at, optional writer, and a kind from the table below.

Invocation surface is cli or mcp. Completion outcome is ok, failed, partial, or refused. The lifecycle action names are seal and reset.

partial marks an error after an irreversible effect. crash appears only when discern encounters an unexpected throw and holds the error's class name, such as "TypeError", plus one trimmed code location. The logbook omits the message and stack. A saved crash report file holds the full error text. tip_ids appears only when the desk showed a tip and carries the registry id verbatim. The tip-adoption reader joins that id to the tip's declared verbs. The landing-authority detectors that read consent are covered in practice patterns. checkpoints carries the open-question and varianceVariance↗The owner's permission to land a change despite a stated unmet checkpoint. lifecycle as metadata — ids, conclusions, revision flags, definition and subject fingerprints, and elapsed times; the unmet rationale never lands here.

Readers skip unknown schema versions, and fields are append-only. begin carries run identity. Completion adds outcome and duration_ms. Capped runs add waited_ms, including 0; uncapped and older events omit it. Readers derive execution as duration_ms - (waited_ms ?? 0) for priors and suite health. End-to-end statistics retain wall time. Other kinds are config-change, pin, prune, and completion. A completion line records one run's producer and landing observations with their durable identities. These advisory facts distinguish gate work, evidence reuse, waits, and landing; missing observations remain unknown. They supply no authority and no Proof.

For done, gate_ran: false means no gate work ran. This can reflect current-Proof reuse or a stop before execution, such as an unanswered checkpoint. Read the outcome and error alongside it. --rerun records rerun. Readers still recognize historical confirmed flags as evidence from older local logbooks; they do not expose that spelling as current input.

done and standalone test completion events add validation. state carries version, capture point, completeness, opaque keyed digests, counts/bytes, elapsed time, and failure categories. execution carries mode, writer, opaque config/setup/job-definition digests, job metadata, concurrency, and passed, failed, skipped, cancelled, or unavailable outcomes.

done captures after fix/build; test before its group. Blocks record boundary/not-reached. Complete state covers HEAD, index/checkout bytes, untracked files, and recursively clean submodules. Sparse/assume-unchanged state stays visible. Dirt, missing initialization, unreadability, unknown state, or a breached budget removes the digest.

.git/discern/validation-hmac-key is the regular 0600 key; unsafe targets make evidence incomplete. One 5-second deadline covers key, Git, files, submodules, cryptography, and execution; expiry records budget/time-limit without changing the verdict. Caps are 20,000 paths, 64 MiB, 1,000 jobs, and 1 MiB. Events exclude manifests, contents, commands, config/environment values, plain hashes, ignored files, services, clocks, randomness, runtime state, and concurrent processes. Older events without validation remain readable.

driver.agent_signals is an optional list of evidence derived when the event is recorded. It supplies no detected-agent verdict. Each item has an agent, a source, and the marker names that matched. Items can appear together. Their order is not a ranking.

The source explains the marker's lifetime:

• process-environment records names such as CODEX_THREAD_ID or GEMINI_CLI. Their values are never stored.
• mcp-client means the MCP client's declared name or title matched a known client name.
• host-filesystem is ambient machine state. The current /opt/.devin marker can persist after Devin's installation, so it does not mean Devin drove that invocation.

driver.spawned_by carries the parent invocation id when the gate's job runner spawned the run: readers classify these as automation and join child to parent.

For an MCP call, driver.mcp_client retains the declared name, optional title, and version, capped at 256 characters each. Readers classify it through the current catalog. A newly recognized name attributes old and new events on the next read without changing stored lines. Unknown clients remain visible.

The read-time view preserves non-MCP evidence and merges duplicate agent/source pairs. A current MCP match replaces stored MCP evidence from the same declarationDeclaration↗The agent's recorded answer to a checkpoint question.. Without a current match, stored MCP evidence remains. Independent sources that disagree leave the run unattributed.

MCP describes the client implementation. An editor, extension, or proxy may sit between discern and the coding agent. These signals can be absent, inherited, or faked. They never change output, instructions, setup, gate behavior, or landing authorityLanding authority↗Permission for a particular change to join the trunk..

discern writes the logbook under the Git administrative area, outside commits and ignore rules. discern sends no logbook data over the network. A write failure does not change the verb outcome; the verb continues without recording the event.

Doctor treats an enabled empty logbook as healthy, including on first use. Disabled, invalid, and write-denied states stay distinct. Unmatched begin events remain interruption or crash evidence and do not affect the storage-health result. Environmental denial warns and disables recording for the process; it does not block setup.

Events use month-stamped files (2026-07.jsonl), and rotation keeps the newest 24 months. A prune line records each removed month with counts by verb and outcome, including a separate partial count. These aggregate counts remain after removal of the raw lines.

The epoch fingerprint hashes behavior-relevant configuration section by section, with a standard's limit masked out. A pin leaves the fingerprint unchanged. An edit to a command, scope, input list, or other behavior-relevant setting changes it and adds a config-change line naming the section.

Logbook lifecycle describes confirmation, archive recovery, and historical selection. Historical selection is advisory: patterns and Stats may read a sealed file, but fleet activity, status, Proof hints, queue estimates, and work-in-flight checks always use the active logbook.

Tip-adoption episodes compare events only when the config epoch, discern writer release, and dominant MCP-client release match. A run on any branch, session, or surface can count. Another setup cannot resolve the episode. Missing setup evidence and the end of history stay censored.

• Trust and your data: the full network, telemetry, and execution contract.
• Files and ownership: the enforced footprint the logbook path belongs to.
• Why identity stays evidence rather than a verdict, and how the shared catalog supports it.

These sources define the stats calculation and its regression coverage.