Skip to content

Add the prose gate

  1. Install it:

    Terminal window
    pnpm add -D @oakgreencc/deadwood
  2. Add deadwood.json at the repository root. {} uses the defaults; to allow more Markdown, list it:

    {
    "markdown": { "allow": ["**/README.md", "AGENTS.md", "CLAUDE.md", "docs/**"] }
    }

    Setting allow replaces the default list, so keep the defaults you want.

  3. Run it:

    Terminal window
    npx deadwood

    Exit 0 is clean, 1 lists offenders, 2 is a usage or config error.

Terminal window
deadwood --init # freeze today's offenders in deadwood.baseline.json

Commit the baseline and own it in CODEOWNERS, so growing it takes a person. When offenders are fixed, run deadwood --update: it only shrinks the baseline.

{
"overrides": [{ "files": ["scripts/**"], "comments": false }]
}

Or give them their own ceiling: "comments": { "maxDensity": 0.3 }.

deadwood checks the whole repository, so run it from a root project that depends on every project. In the root package.json:

"nx": {
"name": "workspace",
"implicitDependencies": ["*"],
"targets": { "deadwood": { "command": "deadwood", "cache": true } }
}

Then add deadwood to the verify command, e.g. nx run-many -t lint test deadwood.

Every key: deadwood reference. Why: Quality ratchets.