# Troubleshooting

> The problems people hit most, and what to do about each.

## "phpunit could not run: no phpunit.xml"

phpunit needs a config file at the project root. Add a `phpunit.xml.dist`
that points at your custom code's tests. Until then the gate says "could not
run" rather than passing.

## "tool missing"

A gate's tool is not installed where droost runs. On a Drupal site,
`composer require --dev drupal/core-dev` brings phpcs, phpstan and phpunit.
For the browser tests: `npm i -D @playwright/test` and
`npx playwright install chromium`. Then `/droost:workflow:continue`.

## The gates all say "labelled: it ran and examined nothing"

The run changed no file those gates read. Usually that is right (a change that
only touched config). If the run did build code, the code was probably already
changed in your working folder when the run began: droost does not count
changes it finds at the start as the run's own. Commit or stash leftover work
before starting a run.

## A gate keeps failing on old code

Record the old problems in a baseline, so new runs are judged only on what
they add: `droost workflow:baseline --measure`, then `droost
workflow:baseline` from your terminal. See
[On an existing site](https://droost.org/docs/existing-site.md).

## The agent says a command was refused

Some commands are yours: changing the level, waiving a gate, letting a run
finish on its own. The refusal gives the agent the exact command; run it
yourself, in your own terminal. Claude Code's `!` prefix is refused too,
because it has no terminal. See [The guard](https://droost.org/docs/how-it-works.md#the-guard).

## A run is stuck and I want to start over

```bash
droost workflow:reset --force
```

The run's record is kept in `droost/droost-workflow/history/`. If the run left
code behind, stash it or commit it before the next run. If it also changed the
site's database, put that back too.

## On DDEV, a quoted sentence arrives as separate words

`ddev exec` joins its arguments into one line. Use the
[`ddev droost` command](https://droost.org/docs/commands.md#on-ddev-ddev-droost), whose
`ExecRaw: true` passes them as typed.

## On DDEV, droost does not see a change I just made

If your DDEV project uses Mutagen, run `ddev mutagen sync` after a change on
the host. With direct bind mounts, files are already shared. Prefer
`ddev composer` so package resolution uses the project’s PHP environment.

## The parity gate fails on a page that looks right

Read the failure: it names the check and the text. Common causes:

- the reference was read on another platform (judge where it was read, or
  capture again);
- the client changed something the design shows (record it in
  `droost/parity/decided.json`);
- the page is not built yet (leave it out of `routes:` until it is).

## Codex (or another agent) ignores the phases

Only Claude Code has the guard's hooks. Other agents get droost's instructions
and the gates still run, but nothing stops an out-of-phase edit. The report
says "enforcement: advisory".