discern.toml — config reference

discern.toml holds your project's discerndiscern↗A tool that installs and runs an agent development practice in a project. settings. Use this page to check what a setting does, which values it accepts, and what happens when you leave it out. Your agent can make the edit for you once you have decided what should change.

Start with jobs for checks, worktree for task workspaces, standards for measured limits, or checkpoints for review questionsQuestion↗Something the agent is asked to judge about the project or a change.. The tables below cover every public setting and come from the schema discern uses to validate your file.

The named-table sections ([jobs.<name>] for custom jobs, [scopes.<name>], [generated.<name>], [worktree.resources.<name>], [standards.<name>], [checkpoints.<name>]) are repeatable: declare as many as you like, each with its own <name>.

A Default is the value discern uses when you omit a key. An em dash means there is no schema default; it does not mean an empty value. A table marked <name> lets you choose a name, such as [standards.coverage]. Other table and key names must match the reference.

The published JSON Schema is the external machine-readable contract. For editing and validation recovery, see Configuration and setup troubleshooting.

Fresh setup seeds [scopes.map] with the mapMap↗The project's account of how its software works and why. and deferred-work ledger. [scopes.instructions] carries the project brief, instruction sources, authored skills, and materialized skills directories. The [acceptance] example names only map, so agent-instruction changes require owner review. Upgrade leaves existing named scopes unchanged; owners of earlier installs split their scopeScope↗A named set of project paths used to select work or policy. manually to adopt this boundary.

The project's identity and the paths discern keeps for it. The name and slug appear in worktreeWorktree↗A separate working copy and branch for one effort., branch, and site names and in every compiled instruction file, so agents and humans see one identity everywhere.

Policy every checkout of this repository shares. The trunkTrunk↗The shared branch that accepted work joins, usually main. is where accepted work lands and where the gate compares from. Branch naming and convergence commands keep the main checkout and every linked worktree usable after their tracked tree changes.

Where the project map lives. The map is the documentation tree agents maintain and discern map browses. Its location also feeds the ${map.dir} reference other sections use.

The instruction sources discern compiles into each agent's file. You write instructions once. discern refresh compiles discern's built-in instructions plus your sources into one generated fileGenerated file↗An agent instruction file or materialized skill that discern builds from an authored source. per agent, committed so every agent reads the same page and no generated file is edited by hand.

Where your authored skills live, and which skills to leave out. A skillSkill↗A reusable playbook that tells an agent how to handle a particular kind of task. is a focused, reusable playbook. discern materializes its bundled skills plus yours into each agent's skills directory; a skill of yours with the same name as a built-in replaces it.

discern skills list          the effective set, and your overrides
discern skills eject <name>  copy a built-in here to customize it

The commands the gate runs, in one namespaceNamespace↗The default directory for the project's authored discern content.. A known name derives its stage; a custom [jobs.<name>] table declares one. discern done runs the fix stage, then build, then check and test in parallel, and reports what each command returned, so done means the project's own bar was met.

A value is one command, a list run in order, or a table giving the job
its own time budget: test = { run = "npm test", timeout = 1200 }.
A long-running command may report its own progress while it runs: print
DISCERN_PROGRESS {"units":{"kind":"files","completed":3,"total":8}}
lines and discern presents the counts, and any reported failures, live.
Leave a known job unwired until its command exists; `discern setup` has
your coding agent fill these from repository evidence.

A custom job. Its name is open, but its stage and command are explicit.

A custom job: any name, an explicit stage, and its command:

[jobs.licenses]
stage    = "check"
run      = "./scripts/check-licenses.sh"
provides = "license-audit"

Known jobs that do not apply to this project. Setup measures how many applicable known jobs are wired. A lifecycle the project does not have is declared here, so the measure counts what exists; the gate's schedule still comes from [jobs].

discern config set-job build --not-applicable   declare one
discern config set-job build --applicable       restore it

Named regions of the repository. A change inside a scope can skip the gate, run its own gate, or offer a preview. A path that matches no scope counts as code and runs every stage.

A sub-component with its own self-contained gate and a read-only preview:

[scopes.native]
paths   = ["native/**"]
gate    = "make -C native check"
preview = "make -C native preview"

Committed artifacts that one generator owns. discern prepare and discern done rerun each generator and fail when the committed bytes differ, so a generated file cannot drift from its source and nobody edits it by hand.

A reference written from source; the same tree yields the same bytes:

[generated.reference]
paths = ["reference/**"]
run   = "tool write-reference --source source/ --output reference/"

Standing grants for landing without a conversation. Landing needs the owner's acceptance in the conversation unless a scope is named here. Widening a named scope widens its grant; the example grants documentation alone and keeps agent instructions owner-reviewed.

The isolated-worktree workflow. Each effortEffort↗One task carried through implementation and review: the work a worktree, its branch, and its submission all belong to. runs in its own checkout, so parallel agents never collide. The git mechanics are generic; the resources and setup commands below are what make a fresh worktree ready for this project.

External resources provisioned per worktree. Give each worktree a deterministic database, emulator, container, or queue handle. Resources are created top to bottom and destroyed bottom to top. discern records intent before create, cleans uncertain partial state before retry, and lets discern worktree prune reclaim a vanished worktree's recorded state.

Runtime tokens, expanded per worktree when a command runs:
  @db@            a database-name-safe identity
  @site@          a DNS-safe dev-server site or host name
  @port@          the deterministic dev-server port
  @project_slug@  the project slug
  @dir@           this worktree's root
  @worktree@      this worktree's base handle (slug-id)
  @resource@      this resource's handle (slug-id-name)

A per-worktree database, so test runs never clash:

[worktree.resources.db]
create  = "createdb -T @project_slug@_template @db@"
destroy = "dropdb --if-exists @db@"

A per-worktree dev-server site: a container vhost, a tunnel, a proxy entry:

[worktree.resources.dev_server]
create  = "link-site @site@ @port@"
destroy = "unlink-site @site@"

Commands that ready a linked worktree. steps run once at creation. ensure runs on every pass, including session start and discern update, so each command must be idempotent. Checkout-generic installs belong in [repository].ensure so acceptance converges the trunk too.

Quality numbers that can never get worse. Every discern done requires current readings for each standard and refuses a limit looser than the trunk's. Producers run once for their consumers, and reusable evidence must match the declared inputs, policy, toolchain, and environment. Hold a raw count for an invariant, a rate through per for a quality that scales, and give a total that grows with the product a margin.

A producer or extractor reports a number: DISCERN_METRIC <name> <number>
Set run for an inline producer, or producer for an existing selector.
An extract command receives captured output or the named artifact on stdin.
Lock in a gain with `discern standards --pin`; a hand-edited limit cannot
tell a gain from a loosening.

Line coverage at or above a rising floor:

[standards.coverage]
direction = "up"
limit     = 80
run       = "your-coverage-tool"  # DISCERN_METRIC coverage <percent>

A bundle-size budget: shipped bytes are a true budget, so a raw count is right:

[standards.bundle]
metric    = "bundle_bytes"
direction = "down"
limit     = 500000
run       = "printf 'DISCERN_METRIC bundle_bytes %s\\n' \"$(wc -c < dist/app.js)\""

Lint density: a rate, so clean code can be added without breaching it:

[standards.lint_density]
metric    = "warnings"
direction = "down"
per       = { lines = "src/**" }   # discern counts the lines itself
scale     = 1000                   # warnings per 1,000 lines
limit     = 5
run       = "your-linter --count"  # DISCERN_METRIC warnings <count>

Change-triggered review rules. A deterministic trigger decides when a change makes a question relevant; the agent answers the question and the answer travels with the Proof. The configuration at an effort's merge-base governs, so editing these tables on a branch never changes that branch's own gate.

Naming a shipped checkpoint enables it with its built-in trigger, mode,
and question; a field set beneath it overrides the built-in. Delete or
comment out an entry to disable it.

Regions the owner watches; stop holds discern done for a stated risk:

[checkpoints.sensitive-paths]
paths = ["src/auth/**", "migrations/**"]
question = """
This change touches a region the owner marked sensitive. What could break
or leak if this is wrong, what protects against that, and what should a
reviewer look at first?
"""

A new dependency is a liability the owner carries; point paths at the manifest:

[checkpoints.new-dependency]
paths = ["package.json"]
mode  = "advise"
question = """
This change edits a dependency manifest. For each dependency added or
upgraded: is it worth the liability it adds, against writing the small part
you need? State what it buys.
"""

A deleted or skipped test is a lowered guard:

[checkpoints.shrinking-tests]
paths             = ["tests/**"]
deletion_dominant = true
mode              = "advise"
question = """
This change removes clearly more test than it adds. Is every removed or
skipped case re-covered elsewhere, or is the narrowed protection intended?
Say which in the commit body.
"""

An interface changed; its contract docs moved too, or were judged unaffected:

[checkpoints.interface-review]
paths          = ["src/api/**"]
unless_changed = ["docs/api/**"]
question = """
A changed interface is described in its docs before it lands: new entry
points state their failure modes; changed contracts note what callers must
revisit.
"""

How discern done runs its parallel stages. Fail-fast, a per-command time budget, and a cap on concurrent test runs keep the gate fast for one agent and fair across a fleet of worktrees sharing one machine.

Co-change detection from git history. Files that habitually change together point at a sibling the current change may be missing. CouplingCoupling↗Files that have often changed together in the project's history. is read-only advice that calibrates itself to the repository, with no thresholds to tune; discern coupling reads it on demand.

Where your executable project scripts live. discern scripts <name> resolves the name literally, runs it from the project root with DISCERN_ROOT, DISCERN_TOML, DISCERN_SCRIPTS_DIR, and DISCERN_TRUNK, and forwards every argument. Other config stays available through discern config get.

Project setup and adoption evidence. discern writes these keys while setting up or upgrading the project. They record schema and setup evidence; nothing here needs hand-editing.