# Adopt gradually without weakening checks

Review warning budgets, keep checks fresh, and distinguish health advice from readiness gates.


An existing repository can adopt conventions without hiding its current debt. Keep application tests and release checks in place, review each diagnostic, and tighten the baseline as you fix problems.

## Run the checker, not a cached result

```sh
npm exec -- nx show project megamono
npm exec -- nx run megamono:check --skip-nx-cache
```

Use your repository's package manager. `megamono health --profile=development` invokes the structural checker; it is not the advisory health-report executor.

New check targets use `cache: false`: configuration, sources, graph edges, and installed plugin bytes can all change the result. Re-running workspace initialization with the same reviewed adoption choices upgrades an intact managed target. Modified or ejected targets remain yours; explicitly set `cache: false` on those targets. A successful older cache entry is not fresh evidence.

## Record and lower warning budgets

The `adoption.ratchets` array in `megamono.json` records ceilings for structural warning categories. Merge reviewed entries into the existing configuration; do not replace the rest of the adoption settings. For example, a reviewed category with two existing warnings can have this entry:

```json
{
  "rule": "platform-boundary",
  "initialCount": 2,
  "targetSeverity": "error"
}
```

When the array is nonempty:

- A category above its `initialCount` fails the check.
- An unlisted structural category has a zero warning budget.
- Errors always fail, even below a warning ceiling.
- Fixing a warning permits lowering the ceiling. Review and commit that change explicitly; running the checker never rewrites the baseline.

An empty array keeps the existing severity-only behavior; it does not enable zero-warning enforcement. `targetSeverity` records the intended error policy, not permission to hide current errors.

These are **count-based**, not identity-aware baselines. Replacing one violation with another in the same category can pass. Review the actual findings in code review, not just the total.

## Preserve stricter lint rules

Managed ESLint defaults go before repository-owned flat-config entries, so your existing error severities and boundary options win. Regeneration updates intact managed sections; modified or ejected sections remain consumer-owned. Review the resulting configuration and run lint as well as the Megamono checker. A migration allowance should not silently weaken an existing error.

## Read health reports as advice

Find the target using `@megamono/plugin:health` in the resolved Nx configuration. Depending on adopted modules it can be on `megamono` or `megamono-docs`. Run that target to write `.megamono/health.json` (or its configured output).

Reports describe their scope explicitly:

| Field | Meaning |
| --- | --- |
| `purpose: "advisory"` | Findings need interpretation, not automatic changes. |
| `readiness: "not-assessed"` | This is not deployment certification. |
| `coverage` | Each family is completed, partial, or skipped, with reasons. |
| `gate.mode` / `gate.passed` | Report-only has a null gate result; `failOnFindings` evaluates selected findings. |

Zero findings does not mean skipped checks passed. Without docs adoption, full specification coverage is not assessed. Ratchet findings use the category `adoption-debt`; their legacy check family is still named `spec-drift` for compatibility.

Compatible dependency ranges may be deliberate, public peers should not be narrowed automatically, and externally consumed libraries may look orphaned in the local graph. Review those findings with the owning project. `failOnFindings` does not turn unavailable checks into passing ones.

## Keep CI and release policy separate

The checker's `--profile=development|migration|ci|release` selects package-source policy, not a readiness certification. Review `packageSources.profiles` against your installed schema and use the intended profile explicitly in automation. `CI=true` selects CI policy when no profile is supplied; do not carry a local migration exception into release jobs.

Continue with [adoption](/docs/workflows/adoption), [check options](/docs/actions/check), or [health-report options](/docs/actions/health).