Glossary

If a result or guide uses an unfamiliar word, start here. Each definition explains its meaning and links to more detail.

Entries are alphabetical. Use the letters below or search this page for the word you need.

Jump to: A · C · D · E · F · G · I · L · M · N · O · P · Q · S · T · U · V · W

Land validated, authorized work on the trunk, the project's shared branch. From an effortEffort↗One task carried through implementation and review: the work a worktree, its branch, and its submission all belong to.'s worktreeWorktree↗A separate working copy and branch for one effort., discern accept records the effort's submission, the exact proven commit, and lands it when conversation consent or a recorded grant authorizes it: it fast-forwards the trunkTrunk↗The shared branch that accepted work joins, usually main., records the Proof noteProof note↗A durable copy of landed Proof, attached to the commit in Git., converges the main checkout, and removes the worktree, its resources, and its branch when the branch holds nothing beyond the landed submissionSubmission↗An effort's recorded request to land one exact commit.. When the trunk moved after the Proof, the landing composes and checks the combined code in an integration worktree and lands that exact proven commit; a second accept waits its turn and resumes on its own. Without authority it refuses, and the submission waits for the owner. See worktrees and landing authority.

A finding that suggests attention without blocking work. Coupling, patterns, impact, and improvement provide advice. The finding can prompt investigation; it is not itself a failed gate check.

An instruction file a coding agent reads when it works on the project. discern refresh generates AGENTS.md, CLAUDE.md, and GEMINI.md from the built-in instructions and your instruction source. These files are committed so a clone carries the instructions; AGENTS.md is the canonical copy the others import. Edit the authored source, then refresh the generated files. See agent instructions.

A review questionQuestion↗Something the agent is asked to judge about the project or a change. presented when a relevant kind of change occurs. A rule under [checkpoints] pairs a mechanical trigger with a question for the agent. In stop mode, the gate waits for a declared met or declared unmet conclusion; advise mode does not block it. An unmet conclusion needs an owner-authorized variance before landing. Committed policy preceding the change governs the question, including the recorded predecessor during candidate completion. discern checkpoints reports the applicable policy and question states. See checkpoints.

Files that have often changed together in the project's history. discern coupling uses that history to suggest related files the current change may have missed. The finding is advisory: past co-change is a reason to investigate, not proof that another file must change. See coupling.

The agent's recorded answer to a checkpointCheckpoint↗A review question presented when a relevant kind of change occurs. question. The agent uses discern done --met <id> for a satisfied question, or --unmet <id> --why "…" for an unmet question with a reason. The answer applies to the resolved question and matched content; a relevant change reopens it. Proof labels the answer declared met or declared unmet. The gateGate↗The configured checks a change must satisfy for ordinary completion. verifies that a required answer exists, not that the judgment is correct.

The agent has judged that the checkpoint question is satisfied for this change. This declaration applies to the question and content the agent examined. A relevant change reopens it. The conclusion is recorded judgment, not independent machine verification.

The agent has judged that a checkpoint question is not satisfied and has recorded why. The gate can still run. Proof carries the reason for the owner to review, while landing waits for an authorized variance. The rationale is kept out of the logbook.

An interactive view of the project's tasks and the actions available for them. Open it from the main checkout with bare discern or discern desk. It surveys the fleet, starts tasks, opens configured coding-agent CLIs found on PATH, and offers valid actions for the selected worktree. See the desk.

A tool that installs and runs an agent development practice in a project. One self-contained program handles setup and maintenance, isolated task worktrees, configured gate checks, project knowledge, and the completion and landing workflow.

The version of discerndiscern↗A tool that installs and runs an agent development practice in a project. you are running, shown by discern --version. Use discern releases to see what's new and check for updates. The installerInstaller↗The commands that set up and maintain discern in a project. updates the program; discern upgrade updates the project's setup to match.

One task carried through implementation and review: the work a worktree, its branch, and its submission all belong to. Results name an effort by its branch. An effort keeps one worktree across feedback and resumed sessions; the landing queue lists efforts by their submissions, and discern accept lands the selected effort's submitted commit on the trunk.

The part of discern that runs its workflow commands. Commands such as done, prepare, status, update, and accept use this TypeScript implementation, compiled into the program. It runs the jobs, scopes, standards, and worktree settings the project declares without prescribing a language or framework. The embedded tidy formatter operates on discern-owned surfaces. See engine internals.

The rules for which parts of a file discern may maintain. The categories are project-owned, shared, and generated, and they determine what discern upgrade may change. See files and ownership; the install surface lists the complete inventory.

The project's collection of task worktrees. The desk and discern status show it from the main checkout; discern status --all includes it from a task worktree. A listed worktree still belongs to its effort even when it is idle or clean. See worktrees.

The configured checks a change must satisfy for ordinary completion. discern done runs this workflow: preconditions, declared jobs, applicable scope gates, required standards, and required checkpoint declarations. Failures identify the check and the next action. Passing establishes the stated checks for the validated change, not permission to land it. See the quality gate.

A named check or operation scheduled by the gate. A project declares its jobs under [jobs]: the six known names format, build, lint, typecheck, test, and smoke derive their stage, while a custom name declares one. The run also schedules fired scope gates and standard measurements as labeled jobs. Covered in the quality gate.

A committed file that a declared command rebuilds from the project's sources. Declare its paths and deterministic generator under [generated.<name>] in discern.toml. The gate checks for drift. discern update resolves conflicts confined to declared generated paths by regenerating, and coupling excludes those paths from its evidence. discern's own generated files form a built-in group and need no separate declarationDeclaration↗The agent's recorded answer to a checkpoint question.. See the quality gate.

An agent instruction file or materialized skillSkill↗A reusable playbook that tells an agent how to handle a particular kind of task. that discern builds from an authored source. Edit the source and regenerate; direct edits to the generated copy can be replaced. The gate checks these outputs against their sources. See agent files and skills.

A review of the project as it exists now, using questions the agent judges. discern improvement serves these questions alongside rules for where project knowledge belongs. It can uncover existing weaknesses that a new-change checkpoint would not reach. The findings are advisory. See improvement.

The commands that set up and maintain discern in a project. They include setup, upgrade, doctor, and config. Some inspect and some change files; each runs and exits. The application does not need discern to run. See getting started.

The project's authored instructions for coding agents. Their paths are named by [instructions].sources (default discern/instructions.md). discern prepends its built-in instructions when compiling the agent files; your project instructions follow them. Covered in agent instructions.

A disposable worktree a landing creates for itself when the trunk moved after a submission's Proof. discern creates it from the exact submitted commit through the same setup a task worktree gets, brings the trunk in, proves the combined committed tree with the full gate, lands that exact proven commit, and removes the copy, its resources, and its integration/ branch. It is discern-owned — never an effort an agent may adopt — with its ownership and exact input recorded, not inferred from its name. A conflict or red combined check removes the copy and returns to the author with nothing landed; a copy whose owning process died is reclaimed by discern worktree prune, which never touches a live one. See worktrees.

Permission for a particular change to join the trunk. It can come from the current conversation, a standing scopeScope↗A named set of project paths used to select work or policy. grant on the trunk, or an effort grant recorded from the desk, which covers the effort's branch so any later green done on it is covered once its agent submits it. Acceptance checks the permission against the changed paths of the submitted commit. A passing Proof is evidence, not permission. See landing authority.

The local record of the project's use of discern. With recording enabled and a readable discern.toml, each CLI verb run and project-resolved Model Context Protocol (MCP) invocation adds metadata such as timing and outcome. It does not record code or command output. Worktrees share the record under .git; discern has no network path that sends it elsewhere. [project].record_logbook = false stops recording. See the logbook.

The project's account of how its software works and why. Agents maintain this documentation at [map].dir (default discern/map). You can read it to understand the project and correct what agents have recorded. The gate checks configured documentation requirements; authors remain responsible for its meaning. publish: false in a page's frontmatter withholds it from every published surface. Pointing [map].dir at existing docs is explicit consent to manage them.

A numbered step that updates a project's discern configuration format. discern upgrade runs the pending steps in order from one schema version to the next. Each step can be repeated without duplicating its intended effect. The command validates the updated configuration before recording the new version. See Upgrade discern.

The default directory for the project's authored discern content. The visible discern/ directory holds the map, your instruction source, authored skills, project scripts, the project brief, and the TODO.md ledger. Its contents are authored sources; configuration can place them elsewhere.

The record created when a stop checkpointStop / advise↗How a checkpoint presents its question. asks for judgment on an effort. It keeps the question and its current answer or unanswered state. discern done creates the record when a stop checkpoint fires. The record lives in the worktree's Git administrative area, survives session restarts, and tracks any later declaration or reopening. discern checkpoints reports its current state without changing it. See checkpoint state and declarations.

Findings about recurring behavior in the project's recorded use of discern. discern patterns reads the logbook for such patterns as repeated gate failures, avoidable workflow steps, and changes in standard measurements. Each finding states its supporting counts and a next step. It is advisory; when evidence is insufficient, it says so. See practice patterns.

Choosing a managed source location authorizes discern to maintain that content. The default source locations carry that permission; pointing a configuration key at another location gives it explicitly. This governs discern's managed content, not every command an agent or project job may run. See design principles and files and ownership.

The connected way of working discern installs and the project carries between sessions. Tasks use separate worktrees, configured gate checks, held standards, exact completion Proof, and owner-controlled landing authority. Bundled skills guide delegation, lasting project knowledge, and improvements that address a problem's cause. You direct the work and make the consequential decisions; your agents operate the workflow. See the practice.

The short R1-XXXX-XXXX-XX code recorded for a long operation and announced to MCP callers. discern progress <handle>, or the discern_progress tool, reads that operation back after a lost call: its phase, the counts and failures known so far, and the retained result. Human command output omits the startup announcement; discern progress without a handle finds the latest operation. It only reads; the C1 continuation that discern await returns is what resumes a wait. See progress and reconnect.

A runnable procedure the project supplies for its agents and maintainers. It lives under [scripts].dir (default discern/scripts), run as discern scripts <name> with DISCERN_* exported. Scripts occupy their own namespaceNamespace↗The default directory for the project's authored discern content., so built-in verb names stay legal.

A file whose ongoing contents belong to the project. discern may create an initial copy, but discern upgrade does not overwrite it. Examples include authored map pages, instructions, the deferred-work ledger, and skills in the namespace.

discern's completion evidence for the exact committed change it validated. discern done records machine results, held standards, and declared checkpoint judgments for the committed tip of the invoking worktree. The Proof lineProof↗discern's completion evidence for the exact committed change it validated. summarizes that evidence; discern status --verbose retrieves the full page. Evidence whose inputs are unchanged can be reused, but a later commit needs current validation. Proof does not grant landing authority. See the Proof.

A durable copy of landed Proof, attached to the commit in Git. The JSON record lives under refs/notes/discern. Its Dead Simple Signing Envelope (DSSE) binds the full commit and preserves the payload bytes for future signatures; current notes use an unsigned extension with an empty signatures array. Recording is local by default, fetching is opt-in, and publishing requires an explicit Git push. See Proof notes.

Something the agent is asked to judge about the project or a change. Checkpoints present questions when changes match their triggers; the improvement review asks them about existing work. A question can have a stable id and a teach note explaining why it matters. A checkpoint answer is declared met or declared unmet, kept separate from machine-verified results. See checkpoints.

The version number of the project's discern configuration format. [meta].schema_version identifies the current step in the migration sequence. It changes when an installation needs a format migrationMigration↗A numbered step that updates a project's discern configuration format.; a new discern release does not necessarily change it.

A named set of project paths used to select work or policy. A [scopes.<name>] entry declares path patterns and can provide a gate command for changes in that area. Unclassified paths still count as code changes, so missing classification does not skip them. discern map --export <name> can also use a scope as an ordered reading list. See the quality gate.

A file with parts maintained by discern and parts maintained by the project. The ownership registry classifies as shared any registered path where discern manages a delimited region or fixed scaffold while preserving project content around it. The registered project paths table contains the complete inventory.

A reusable playbook that tells an agent how to handle a particular kind of task. Skills use SKILL.md files. discern ships bundled skills prefixed discern-; you can add your own under [skills].dir or override a bundled skill with the same name. discern refresh makes the selected set available to configured agents, discern skills list shows it, and [skills].exclude omits named skills. See skills.

A group in the order the gate runs work. The stages are fix, build, check, or test. A known job's name determines its stageStage↗A group in the order the gate runs work.; a custom job declares one explicitly.

A held limit for a repeatable project measurement. A [standards] entry sets a floor that may rise or a ceiling that may fall. The gate checks the limit and protected measurement definition against the preceding committed policy; an ordinary branch cannot weaken or delete them. Completion requires every standardStandard↗A held limit for a repeatable project measurement., using applicable evidence or a new measurement. discern standards --pin captures a gain; discern prepare requests no measurements. A weaker limit needs the separate owner-approved proposal process. See standards.

How a checkpoint presents its question. stop waits for a recorded conclusion before the gate runs; advise presents the question without blocking. Stop is the default mode. Heuristic built-in triggers use advise. A declared unmet answer allows checks to run, but still needs the owner's variance before landing.

An effort's recorded request to land one exact commit. discern accept queue records it without starting a landing; discern accept records it and starts landing. Both select the effort from its worktree or with --target, naming its branch, the committed revision, and the Proof that covers it, and store the submission beside the effort grant under the worktree's Git administration so no branch can forge it. A later explicit submission from the same effort replaces it; a later commit or Proof alone does not. A landing consumes it, and dropping the worktree removes it. The landing queue lists submissions with honored Proof that have not landed, pre-authorized ones first; a green run its agent never submitted is absent and lands only by the owner's explicit act. See landing authority.

discern's formatter for its configured Markdown and TOML surfaces. discern tidy formats the map, deferred-work ledger, and instruction sources as Markdown, and discern.toml as TOML. Fresh installations run it through the format job; removing that command opts out. See format discern-owned surfaces.

A short practical suggestion shown below the desk status. The deskDesk↗An interactive view of the project's tasks and the actions available for them. chooses a tip once per session and records its id in the logbook. The yellow Tip label distinguishes it from task status; its advice does not change what the selected task may do. Advice delivered to agents remains in command results. See desk tips.

The shared branch that accepted work joins, usually main. [repository].trunk selects it. Tasks bring its changes into their own worktrees with discern update; discern accept fast-forwards it to a submitted, proven, authorized commit.

Bring newer work into the current task's worktree. discern update merges the latest trunk into the task branch and refreshes generated files. With --from <ref>, it can bring in another explicit source, including unlanded work. The result names overlapping files for the agent to re-read, because a successful merge does not prove the combined behavior is right. See worktrees.

The owner's permission to land a change despite a stated unmet checkpoint. It covers the exact current declaration and landed commit, without changing the policy for future work. The agent records the owner's explicit current-conversation approval with discern accept --confirmed --variance <id>. Standing and effort grants do not cover variances. See checkpoints.

A separate working copy and branch for one effort. discern start creates it so task edits stay apart from the main checkout and other efforts. Review and resumed sessions continue the same effort; a worktree changes only through the operation run in it, and no operation installs another revision into it. A landing removes the worktree, its resources, and its branch when the branch holds nothing beyond the landed submission. Each worktree has a derived port and declared resources; discern enter opens a child shell in a selected checkout. See worktrees.

A supporting service or other resource prepared separately for one worktree. Examples include a test database, emulator, or container. [worktree.resources.<name>] declares its create and destroy commands. Worktree setup ensures the declared resource exists, and lifecycle cleanup removes it when appropriate. discern worktree prune can reclaim positively identified orphaned resources. See worktree resources.