Settings | Droost

droost/droost.yml, the one settings file: the level, who drives and who finishes a run, the gates, and the retries.

Every setting droost has for your project is in one file, droost/droost.yml. droost init writes it once and never overwrites it.

It is a file, not site configuration, for three reasons: the agent can read it even when the site is broken; every agent reads the same file; and a change to it shows up in code review as a diff. While a run is open, the guard refuses edits to it, so a change applies to the next run.

The main settings

preset: custom        # the level
mode: agentic         # agentic | interactive
# lead: human-led     # human-led | autonomous (unset: autonomous in agentic mode)
enforcement: soft     # hard | soft | off
require_run: hard     # hard | soft | off
max_gate_retries: 2

These are the lines droost init writes.

Setting	What it decides
`preset`	the level: how much each run must prove (below)
`mode`	`agentic`: the agent moves the run along itself. `interactive`: it stops at each step for you
`lead`	who may finish a run: you (`human-led`) or the agent (`autonomous`). Unset, an agentic run is autonomous
`enforcement`	how the guard holds a run to its step: `hard` blocks, `soft` warns once, `off` drops the step rules (the walls, `require_run`, the protected files and your commands still hold)
`require_run`	whether edits to `modules/custom` and `themes/custom` need a run open: `hard` blocks, `soft` warns, `off` allows
`max_gate_retries`	how many times a failing check is retried in place before its step stops (2 means one try plus two retries)

Setting lead: here decides it for runs from now on. To change it for one run that is already open, run droost workflow:lead <lead> (making a run autonomous needs your own terminal).

Levels

The level is how strict each run is. Two things never change with it: the agent always writes a spec, and it always has to look at the code first.

Level	In plain words
`low`	Code style, light static analysis and browser verification. No PHP tests required, no reviewer. For trying droost out.
`medium`	A run that changes a class must also change a PHPUnit test. A second agent reviews each change.
`high`	Stronger code analysis. The guard blocks out-of-step edits, and a critical review finding holds the run. Every check runs again at the end. A good default.
`xhigh`	Adds test coverage, mutation testing, and JavaScript and CSS linting.
`max`	Everything on, at the strictest settings. Test suites must exist: an empty one fails.
`custom`	Your `gates:` list decides everything. What `init` writes.

A file that names no level is held to max.

What a level decides, and what your file does. A setting written out in the file beats the level. The file init writes spells out several, including enforcement: soft, phpstan's level: 6, mutation and coverage off, the seeker and max_gate_retries. To let a level decide one of them, delete its line. droost workflow:status lists the ones still overriding it.

How the checks run differs by level. At every level the code checks read only the files the run changed. At low and medium, each check also runs just once, in the step that owns it, and the test suites run only the tests the run changed; a test failure sends the run back to code, up to 2 times at low and 3 at medium. From high up, and at custom, the code checks run again at test and every check runs again at complete.

Change the level in your own terminal:

tools/droost/vendor/bin/droost workflow:effort xhigh --preview   # what would change
tools/droost/vendor/bin/droost workflow:effort xhigh

A run keeps the level it started with.

Gates

Each built-in check is listed under gates:. The level sets them; what you write here is applied on top, one gate at a time:

gates:
  phpcs:      { standard: "Drupal,DrupalPractice" }
  phpstan:    { level: 6, paths: "web/modules/custom,web/themes/custom" }
  playwright: { on: true, required: true }
  parity:     { on: true, scope: frame }

Every gate takes on, mode (block or report) and timeout. Gates lists them all; your own go here too (Make it yours).

phpcs, phpstan and phpunit cannot be switched off here, except at custom. At low the level itself turns phpunit off, and the report says "off by preset low", never "passed".

Everything else

Setting	Where
`seekers:`	Gates
`rules:`	Make it yours
`hooks:`, `walls:`, `operator_only:`, `panel:`	Hooks and walls
`work_item:`	Tickets
`baseline:`	Gates

Near-miss spellings of known settings are rejected. Unknown top-level keys are allowed for project extensions; check workflow:status to see the resolved configuration.