discern.toml — config reference

discern.toml holds your project's discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your 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 questions. 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↗Your project's own guide to how its software works and why, which your agents write and keep current. and deferred-work ledger. [scopes.instructions] carries the project brief, instruction sourcesInstruction source↗The file where your project writes its own instructions for coding agents., authored skills, and materialized skills directories. The [acceptance] example names only map, so agent-instruction changes require owner review. discern upgrade leaves existing named scopes as they are.

The project's name, its coding agents, and a few project-wide settings. The name heads every compiled instruction file, and the slug names each worktreeWorktree↗A separate copy of your project, on its own branch, where one task's work happens.'s site, database, and resources, so people and agents see one identity everywhere.

Git settings that every checkout of this repository shares. The trunkTrunk↗Your project's shared branch, usually main, where finished changes land. is the branch finished work lands on and the gateGate↗The full set of checks your project requires before a change counts as finished. checks against. The branch prefix names each task's branch, and ensure commands keep every checkout ready to use after its files change.

Where the project map lives. The map is the documentation your agents keep about how the project works, and discern map browses it. Other settings can refer to its folder as ${map.dir}, which ends in /, as in ${map.dir}**.

The instruction files discern compiles into each agent's file. You write your instructions once. discern refresh combines discern's built-in instructions with yours into one generated fileGenerated file↗A file discern builds for your coding agents: an agent file or a skill folder. per agent. Those files are committed, so every agent reads the same instructions, and the gate fails if one is edited by hand.

Where your own skills live, and which skills to leave out. A skillSkill↗A ready-made playbook that tells your agent how to handle a particular kind of task. is a reusable playbook your agents follow for one kind of task. discern copies its built-in skills into each agent's skills folder and links yours there, so edits to yours apply at once. A skill of yours with the same name as a built-in one replaces it.

discern skills list          see which skills your agents get
discern skills eject <name>  copy a built-in here so you can edit it

The commands the gate runs to check a change. A known name, such as test, has a fixed stageStage↗A group in the order the gate runs its work.; a custom [jobs.<name>] table sets its own. discern done runs the fix stage, then build, then the check and test stages side by side. It reports what each command returned, so a pass means your project's own checks passed.

Give a job one command, a list of commands run in order, or a table with
its own settings, such as test = { run = "npm test", timeout = 1200 }.
A long command can report its progress by printing lines such as
DISCERN_PROGRESS {"units":{"kind":"files","completed":3,"total":8}}
and discern shows the counts, and any failures reported, as it runs.
Leave a known job out until the project has that command. During setup,
your coding agent fills these in from what the repository already uses.

A custom job: any name of letters, digits, _, or -, with its stage and command set out.

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 this project doesn't have. Setup counts how many of the known jobs that apply to this project are configured. List a job here when the project has no such step, so setup doesn't count it as missing. The gate still runs only what [jobs] lists.

discern config set-job build --not-applicable   mark a job as absent
discern config set-job build --applicable       count it again

Named regions of the repository. A scope can run its own gate command when a change touches it, offer a preview, or mark its changes as neutral, meaning not code. Landing grants, checkpoints, and discern impact refer to scopes by name. A path that matches no scope counts as code.

A component with its own gate command and a read-only preview:

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

Committed files that one command generates. discern prepare reruns each generator and leaves the new files for you to commit. discern done reruns them too, and fails when the committed files differ from what they produce. A generated file can't drift from its source, and nobody needs to edit it by hand.

A generated reference: the same source always gives the same bytes:

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

Standing grants: scopes whose changes can land without asking you each time. Without a grant, landing needs your approval in the conversation, or a grant you give one task from the deskDesk↗The interactive view that opens when you run discern in your main checkout.. Widening a granted scope's paths widens its grant. The example grants documentation only, so you still review changes to agent instructions.

How discern creates and prepares task worktrees. Each task runs in its own checkout, so agents working side by side don't collide. The Git steps are the same for every project; the resources and setup commands below make a new worktree ready for this one.

Outside resources that each worktree gets its own copy of. Each worktree can have its own database, emulator, container, or queue, with a stable name. discern creates resources in the order listed and destroys them in reverse. It records how to destroy each one before creating it, so it can clean up a half-finished create, and discern worktree prune can clean up after a worktree deleted without discern.

Tokens discern replaces with this worktree's values in these commands:
  @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 database for each worktree, so test runs never clash:

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

A development site for each worktree, such as a container host, tunnel, or proxy entry:

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

Commands that prepare a task worktree for work. steps run once, when discern creates the worktree; ensure commands run on every pass, so each must be safe to repeat. Neither gets @token@ replacement. Put installs that every checkout needs, such as dependencies, in [repository].ensure, so the main checkout gets them after a landing too.

Limits on measured numbers, such as test coverage or bundle size, that the gate holds. Every discern done needs a current measurement for each standard. A branch can tighten a limit but can't loosen, redefine, or delete a standard the trunk has. discern reuses a measurement only while its inputs, commands, toolchain, and environment match. Hold a raw count for a number that should stay fixed, a rate through per for one that grows with the project, and give a total that drifts a margin.

The measuring command prints each reading as: DISCERN_METRIC <name> <number>
Set run to measure with a command, or producer to reuse a job's output.
An extract command reads that output, or the named artifact, on stdin.
Lock in a gain with `discern standards --pin`: it tightens the limit to
the measured value, keeping the margin as headroom, and commits it.

Line coverage held at or above a floor that only rises:

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

A bundle-size budget: shipped bytes are a real budget, so a raw count fits:

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

Lint warnings per 1,000 lines: a rate, so adding clean code never breaks 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>

Review questions your agent answers when a change matches a trigger. A trigger, such as a change to certain paths, decides when a question applies. Your agent answers it, and the answer goes into the Proof. A branch follows the checkpoint rules from the commit it started from, so editing these tables on a branch never changes that branch's own gate.

Name a built-in checkpoint here to turn it on with its own trigger, mode,
and question. A field you set under it replaces the built-in value.
Delete or comment out an entry to turn it off.

Paths the owner watches: stop holds discern done until the agent answers:

[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 cost 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 change that removes far more test code than it adds lowers protection:

[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 docs change with it, or the agent judges them 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 runs jobs, in discern done and the other commands that run them. Stopping at the first failure and a time limit for each job keep checks quick. A cap on test runs at once keeps them fair to every worktree of this repository.

Files that usually change together, found from Git history. When a change leaves out a file that usually changes with the ones it touches, discern names it. The finding is advice only, it adjusts to the repository's own history, and there are no thresholds to set. discern coupling shows it on demand.

Where your project's scripts live. discern scripts <name> runs the script with that name from the project root, with DISCERN_ROOT, DISCERN_TOML, DISCERN_SCRIPTS_DIR, and DISCERN_TRUNK set, and passes every argument through. A script can read other settings with discern config get.

A record of this project's setup and upgrades. discern writes these keys when it sets up or upgrades the project. They record the config format version and how setup went, so you never need to edit them.