@hublo/sentinel 1.1.0-alpha.3 → 1.1.0-alpha.5

package/README.md

@@ -4,7 +4,7 @@
 
 `sentinel` is a standalone, semver-versioned package (published to a registry, consumed by a repo as a normal dependency) that unifies a repo's tooling, config, and quality checks into one place, so projects stop copying config files everywhere and stop carrying a pile of duplicated tooling dependencies.
 
-> Status: **foundation + the TypeScript tool are shipped** (`@hublo/sentinel@0.1.0-alpha.x` on npm). The rest of this README is the design reference for the tools still to come, added one at a time on top of this foundation.
+> Status: **the foundation, the TypeScript tool and the lint tool are shipped** (`@hublo/sentinel` on npm). The rest of this README is the design reference for the tools still to come, added one at a time on top of this foundation.
 
 ---
 
@@ -19,7 +19,7 @@ A large monorepo accumulates:
 
 ## What it gives you
 
-**The shift:** instead of today's **big-bang** (change every project and every tool at once, untested in isolation), evolution is **app-scoped and versioned**, evolving a project is a **version bump**, a new/swapped tool is just a **new runner**, and a new stack a **new flavour**. No repo-wide edits.
+**The shift:** instead of today's **big-bang** (change every project and every tool at once, untested in isolation), evolution is **app-scoped and versioned**, evolving a project is a **version bump**, a new/swapped tool is just a **new runner**, and a new stack a **new preset**. No repo-wide edits.
 
 - **One source of truth for config** — every project just `extends @hublo/sentinel/...`; the actual rules live in one versioned place. Change a rule once, everyone gets it on the next version bump.
 - **One source of truth for tooling dependencies** — a project depends on `@hublo/sentinel`, not on a scattered pile of eslint / vitest / plugin devDeps. Bump one version and the whole toolchain moves, atomically, tested in isolation first.
@@ -43,23 +43,47 @@ A large monorepo accumulates:
 
 sentinel writes **standard config files** into a project (each just `extends` a sentinel preset) and runs the checks. Your editor and the tools read those **normal files natively**, they never call sentinel at runtime, so nothing is coupled to it or brittle.
 
-> **Shipped today:** only the **TypeScript** tool, so `--init` writes the `tsconfig` stub, and `--run`/`--report`/`--status` work for `--typescript`. The `eslint.config.js` / `--lint` / `--test` snippets below illustrate the end state; those subpaths (`@hublo/sentinel/lint/*`, …) land with their tool ticket.
+> **Shipped today:** the **TypeScript**, **lint** and **format** tools. The `--test` / `--build`
+> snippets below illustrate the end state and land with their own ticket.
 
 **Step 1 — put a module on sentinel** (once per module, by a dev; the files are committed). Run from the app dir; `--init` does it all, nothing is hand-edited:
 
 ```bash
-sentinel --init --typescript --flavour <react|nest|node>
+sentinel --init --preset <react|nest|node|svelte>   # every role sentinel ships
 pnpm install   # fetch what --init declared, then commit
 ```
 
+With no target named, `--init` adopts every role, in the order that makes the result correct:
+the linter's autofix runs, then the formatter runs **last** and formats everything every role
+wrote. Naming one target (`--init --lint`) adopts just that role and leaves the rest alone.
+
 `--init` writes the config stubs, the `typecheck`/`lint`/... scripts, and pins the `@hublo/sentinel` devDependency into the module (no manual `pnpm add`); it scaffolds a `package.json` for a `project.json`-only module. It also applies, once, the workspace prep that module needs at the root, only when the root's own config shows it is needed (e.g. an i18next singleton override when the repo runs a second TypeScript, a release-age allow-list when the repo uses that pnpm gate). See the [adoption cheat sheet](docs/typescript-adoption.md) for the full list.
 
 Those files are tiny, they just point at a sentinel preset. What gets committed:
 
-```js
-// eslint.config.js — generated; overrides go through the sentinel allowlist, not inline
-import react from '@hublo/sentinel/lint/react'
-export default react
+```jsonc
+// .oxlintrc.json — generated. Adoption REPLACES eslint rather than sitting beside it, so
+// the module's eslint config is DELETED and this is the only linter config it keeps.
+// The RULES live in the preset, so a preset change arrives by reinstalling. `ignorePatterns`
+// cannot: it does not cross an `extends` boundary, so it is written here, which is what
+// makes the file correct for your editor and for `oxlint -c` on its own.
+{
+  "extends": ["./node_modules/@hublo/sentinel/oxlint/react.json"],
+  "ignorePatterns": ["**/dist/**", "**/node_modules/**", "..."],
+}
+```
+
+```jsonc
+// .oxfmtrc.json — generated, and the one config that is NOT a stub: oxfmt has no `extends`
+// and ignores the key silently, so the preset's values are written in. Anything the module
+// deliberately formats differently is declared in `$sentinel.local` and survives a re-init.
+{
+  "$sentinel": { "preset": "base", "version": "1.1.0", "local": [] },
+  "printWidth": 80,
+  "semi": false,
+  "singleQuote": true,
+  "sortImports": { "groups": ["builtin", "external", "internal", ["parent", "index"], "sibling"] },
+}
 ```
 
 ```jsonc
@@ -68,7 +92,7 @@ export default react
 {
   "extends": ["../../tsconfig.base.json", "@hublo/sentinel/tsconfig/react"],
   "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } },
-  "include": ["src"]
+  "include": ["src"],
 }
 ```
 
@@ -80,11 +104,15 @@ And the app's `package.json` scripts route every check through the one CLI (run
 // package.json
 {
   "scripts": {
-    "lint": "sentinel --run --lint",
-    "lint:fix": "sentinel --run --lint --fix",
+    // `lint` checks BOTH, the way `prettier --check . && eslint .` used to. In the :fix
+    // pair the formatter runs last: the linter's autofix rewrites code.
+    "lint": "sentinel --run --lint && sentinel --run --format",
+    "lint:fix": "sentinel --run --lint --fix && sentinel --run --format --fix",
+    "format": "sentinel --run --format",
+    "format:fix": "sentinel --run --format --fix",
     "typecheck": "sentinel --run --typescript",
-    "test": "sentinel --run --test"
-  }
+    "test": "sentinel --run --test",
+  },
 }
 ```
 
@@ -119,10 +147,14 @@ pnpm dlx @hublo/sentinel@<exact-version> --inspect --typescript --module <name>
 
 ## Docs & cheat sheets
 
+- [`docs/performance.md`](docs/performance.md) — the measured baseline (`pnpm bench`), so a regression is something you can see rather than argue about, and what is deliberately left unoptimised.
+- [`docs/using-sentinel.md`](docs/using-sentinel.md) — every verb for every role, scoping a run to some files, what a fully adopted module looks like, and how versions move between modules.
+- [`docs/lint-adoption.md`](docs/lint-adoption.md) — migrating a module from ESLint to Oxlint: the two steps, what `--init` writes and removes, the two react tiers, and the failures worth recognising.
+- [`docs/format-adoption.md`](docs/format-adoption.md) — migrating a module from Prettier to oxfmt: why this config is materialized rather than a stub, how a module keeps its own formatting, and what did not survive the move.
 - [`docs/typescript-adoption.md`](docs/typescript-adoption.md) — the adoption cheat sheet: the two adoption steps, the command model (verb x type x location), options, reading a report, and troubleshooting.
 - [`docs/typescript-traces.md`](docs/typescript-traces.md) — a **generated, versioned** reference of live command + output traces (every verb, option, config result and edge case) against the mock monorepo. Regenerate after CLI changes with `pnpm docs:traces`.
 
-## Architecture: `target → runner → flavour`
+## Architecture: `target → runner → preset`
 
 Every check is described by three layers:
 
@@ -130,12 +162,12 @@ Every check is described by three layers:
 | -------------------- | --------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
 | **target** (role)    | `--lint`, `--typescript`, … | the _kind_ of check, stable                 | `lint` `format` `typescript` `build` `test` `static-analysis` `runtime-analysis`       |
 | **runner** (adapter) | `--runner=<tool>`           | the _tool_ behind the target, swappable     | lint: `eslint`/`biome`/`oxlint` · types: `tsc`/`tsgo` · build: `vite` · test: `vitest` |
-| **flavour** (preset) | detected / `--flavour`      | the _variant_ per stack (strict by default) | `react` `nest` `node` (svelte declared, preset deferred)                               |
+| **preset** (preset)  | detected / `--preset`       | the _variant_ per stack (strict by default) | `react` `nest` `node` `svelte` (svelte: lint only, no tsconfig preset yet)             |
 
-A run is `target × runner × flavour`, e.g. `sentinel --run --lint --runner=eslint` from the `host-admin` dir.
+A run is `target × runner × preset`, e.g. `sentinel --run --lint --runner=eslint` from the `host-admin` dir.
 
 - `--runner` is an **optional override on a central default**. `sentinel --lint` uses the configured default runner, so swapping a tool globally is a one-place change; `--runner=biome` overrides for a single run (great for benchmarking eslint vs biome vs oxlint, and for gradual migration).
-- The **flavour is detected** from the module's dependencies (deterministic: a framework dep → its flavour, else `node`), and **`--flavour` overrides it**. Detection can be wrong where deps are hoisted at the repo root (it returns `node`), so pass `--flavour` for `--init` (that is where the preset is chosen). `--run`/`--report` don't depend on it, they run the tool on the committed config.
+- The **preset is detected** from the module's dependencies (deterministic: a framework dep → its preset, else `node`), and **`--preset` overrides it**. Detection can be wrong where deps are hoisted at the repo root (it returns `node`), so pass `--preset` for `--init` (that is where the preset is chosen). `--run`/`--report` don't depend on it, they run the tool on the committed config.
 
 ### Adapters & the engine (ports & adapters)
 
@@ -143,14 +175,14 @@ A run is `target × runner × flavour`, e.g. `sentinel --run --lint --runner=esl
 
 - the **engine** (core) is tool-agnostic: it parses the CLI, resolves an adapter, and owns **all IO and repo structure**, finding the project root, reading, merging and writing files;
 - an **adapter** is the boundary to one tool (eslint, tsc, vitest, …). It carries the tool knowledge (how to run it, what its config means) and implements one contract (types in `src/core/types.ts`, optional base in `src/core/base-adapter.ts`);
-- a **context** is a plain data object the engine passes to an adapter for a run (`app`, `cwd`, optional `flavour`, `ci`, `fix`). It is data only, it never carries a filesystem capability.
+- a **context** is a plain data object the engine passes to an adapter for a run (`app`, `cwd`, optional `preset`, `ci`, `fix`). It is data only, it never carries a filesystem capability.
 
 `sentinel` does not reimplement tools. The contract:
 
-- **`appliesTo(flavour)`** — which flavours this adapter handles (resolution filters on it, so a React-only adapter is never picked for Nest)
-- **`plan(flavour)`** — PURE: returns a declarative `UpdatePlan` of file operations (used by `--init`). The adapter never touches the disk; the engine applies the plan.
+- **`appliesTo(preset)`** — which presets this adapter handles (resolution filters on it, so a React-only adapter is never picked for Nest)
+- **`plan(preset)`** — PURE: returns a declarative `UpdatePlan` of file operations (used by `--init`). The adapter never touches the disk; the engine applies the plan.
 - **`run(ctx)`** — invoke the tool's bin against the project (used by `--run`)
-- **`inspect(flavour)`** — the adapter's resolved base config (used by `--inspect`)
+- **`inspect(preset)`** — the adapter's resolved base config (used by `--inspect`)
 - **`report(ctx)`** — metrics (used by `--report`)
 
 **`--init` is a declarative plan, not file-writing inside the adapter.** The adapter describes intent as operations; the engine executes them:
@@ -170,7 +202,7 @@ So the tool-_meaning_ lives in the adapter and the read/merge/write _mechanics_
 ```mermaid
 flowchart LR
   CLI["sentinel --verb --target<br/>[--runner]"] --> D[dispatch]
-  D --> R["registry.resolve<br/>(target, flavour, runner)"]
+  D --> R["registry.resolve<br/>(target, preset, runner)"]
   R --> A["adapter<br/>eslint / tsc / vitest / ..."]
   A -->|"--run"| Run["tool binary on the project"]
   A -->|"--init"| Upd["declarative plan → engine writes"]
@@ -200,6 +232,80 @@ The rules live in `sentinel`. Each module keeps a **thin, generated stub** per t
 - **Per-module install** — `@hublo/sentinel` is added per module, so adoption is **gradual** (migrate lot by lot; a module can adopt sentinel while its neighbour still uses the old config). Root configs are removed only once the **last** module has migrated.
 - **Runner binaries** (`eslint`, `typescript`, `vite`, `vitest`, …) are **resolved from the adopting module** at run time (sentinel looks for the tool in the module, then falls back to `PATH`), so the editor and nx keep using the exact binary the project already installs. sentinel does **not** declare them as dependencies today, so it does not pin their versions: the module still owns its own `typescript`. Having sentinel dictate those versions (as peer dependencies, so the whole toolchain rides the sentinel version) is the intended end state, and it lands with the tool tickets that actually bundle a runner.
 
+## What a preset does not enforce
+
+A preset that silently enforces less than the config it replaced is worse than no preset, so
+every rule that is not enforced carries a reason and is listed by `sentinel --inspect --lint`:
+
+| State          | Meaning                                                              | Can it be switched on?          |
+| -------------- | -------------------------------------------------------------------- | ------------------------------- |
+| **deferred**   | scheduled for a later migration wave                                 | yes, on schedule                |
+| **disabled**   | a decision: it argues with the architecture, or only false-positives | yes, by revisiting the decision |
+| **downgraded** | it runs and reports, it just cannot fail the build                   | yes, once the debt is paid      |
+
+A small number of rules sit outside those three states, because the preset cannot carry them at
+any severity. They are documented here rather than reported by `--inspect`: oxlint validates
+rule and plugin names when it **parses** a config, so naming one would make the config fail to
+parse and the module would lint nothing at all. They are still recorded as data in the preset,
+so the tests can count every rule a module enforces and fail on anything unaccounted for.
+
+### Rules the presets do not carry (nest, react)
+
+| Rule                         | Why                                                                                                                                                                                                       |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `typescript/member-ordering` | oxlint has no native rule, and the preset deliberately does not host `@typescript-eslint/eslint-plugin`: a plugin costs a dependency, a load step and a pass over every file, which is not worth one rule |
+| `no-invalid-this`            | no oxlint equivalent, and hosting does not help (the rule crashes on every file under oxlint's plugin API). Its coverage moves to TypeScript's `noImplicitThis`                                           |
+| `no-octal`                   | no oxlint equivalent                                                                                                                                                                                      |
+| ~15 stylistic rules          | formatting, which the formatter owns. They move to **oxfmt**, deliberately the last step of the migration, so nothing enforces them in between                                                            |
+
+The formatting group is the only one that will ever shrink; the rest are settled losses.
+
+`no-return-await` is **not** in that table, despite having no oxlint rule of that name. It is
+deprecated in ESLint core and oxlint ships the typescript-eslint successor, so the presets carry
+`typescript/return-await` with the `never` option, which is what the old rule meant. It is held
+at `warn`: both modules set the old rule to error, but it was never actually reporting (the nx
+lint target expanded to 2 files of 2888), and running it over every file finds 9 real violations
+on bff-admin and 5 on host-admin. Fix those and it can be raised.
+
+### Rules with no oxlint equivalent (svelte)
+
+Oxlint parses a `.svelte` file's `<script>` block and **not its template**. Measured on oxlint
+1.77 with a component carrying a violation in each half: the `<script>` violation is reported,
+and `{@html}`, `{@debug}` and duplicate style properties in the template produce nothing.
+Adding a svelte plugin does not fix this, because the missing piece is the **parser**, not the
+rule implementations.
+
+So sixteen rules the two svelte modules enforce today have **no oxlint equivalent**. Fourteen
+read the template:
+
+`svelte/comment-directive` · `svelte/no-at-debug-tags` · **`svelte/no-at-html-tags`** ·
+`svelte/no-dupe-else-if-blocks` · `svelte/no-dupe-style-properties` ·
+`svelte/no-dynamic-slot-name` · `svelte/no-inner-declarations` ·
+`svelte/no-not-function-handler` · `svelte/no-object-in-text-mustaches` ·
+`svelte/no-shorthand-style-property-overrides` · `svelte/no-unknown-style-directive-property` ·
+`svelte/no-unused-svelte-ignore` · `svelte/system` · `svelte/valid-compile`
+
+and two core rules oxlint does not implement: `no-dupe-args` (TypeScript rejects duplicate
+parameter names anyway) and `no-octal`.
+
+**The one worth knowing about is `svelte/no-at-html-tags`**, an XSS guard that fires on the
+modules today. Adopting the svelte lint preset gives that check up.
+
+These rules are **absent from the generated config rather than set to `off`**, and that is
+forced, not stylistic. Oxlint rejects an unknown rule or plugin when it _parses_ a config, even
+when the value is `off`:
+
+```console
+$ oxlint -c '{"rules": {"svelte/no-at-html-tags": "off"}}'
+Failed to parse oxlint configuration file.
+  x Plugin 'svelte' not found
+```
+
+Listing them as disabled would not weaken the config, it would stop the config from parsing and
+the module would lint nothing at all. They are recorded as data in the preset (`uncovered`), so
+the preset tests can count every rule the modules enforce and fail on anything unaccounted for,
+and they are documented here for the developers who own those modules.
+
 ## Composition & precedence
 
 A repo often has a base config that is **structural**, not just tooling, e.g. a
@@ -264,11 +370,11 @@ A command **composes** three axes: **verb + type + location**.
 ```
 sentinel <verb> [type] [options]
 
-VERBS      --run       execute the target's tool
-           --inspect   show the resolved configuration (incl. deferred rules)
-           --report    metrics and health
-           --status    adoption + conformity (coverage + drift), read from configs
-           --init    generate/apply the config stubs (writes; one module only)
+VERBS      --run       execute the target's tool (--json for metrics + diagnostics)
+           --inspect   the resolved configuration, what is deferred, adoption + drift
+           --init      generate/apply the config stubs (writes; one module only)
+           --report    deprecated → --run --json
+           --status    deprecated → --inspect
 
 TYPES      --lint  --format  --typescript  --build  --test
            --static-analysis  --runtime-analysis  --arch
@@ -278,27 +384,55 @@ LOCATION   in a MODULE dir      → that module (do NOT pass --module)
            at the workspace ROOT → --module <name> (one) · --ci (affected) · else all
 
 OPTIONS    --module <name>    from the root: scope to one module
-           --flavour <name>   override the detected stack preset (react, nest, ...)
+           --preset <name>   override the detected stack preset (react, nest, ...)
            --runner <tool>    override the default runner
            --ci               from the root: affected only; non-zero exit on failure
            --fix              auto-fix where applicable
            --dry-run          preview a --init without writing
            --json             machine-readable output (report / inspect / status / --dry-run)
+           -- <tool options>  --run only: pass the rest to the tool itself (one type)
 
 EXAMPLES   sentinel --run --typescript                        # in a module → that module
-           sentinel --report --typescript --module bff-admin  # from root  → one module
-           sentinel --report                                  # from root  → all types, all modules
-           sentinel --status --typescript                     # from root  → adoption coverage
-           sentinel --status --ci                             # from root  → fail CI on drift
-           sentinel --init --typescript --flavour react     # write stubs for the current module
+           sentinel --run --typescript -- --noImplicitAny     # ask tsc a question of your own
+           sentinel --run --typescript --module bff-admin     # from root  → one module
+           sentinel --run --json                              # from root  → all types, machine output
+           sentinel --inspect --typescript                    # from root  → adoption coverage
+           sentinel --inspect --ci                            # from root  → fail CI on drift
+           sentinel --init --typescript --preset react     # write stubs for the current module
 ```
 
 `--run`/`--inspect`/`--report`/`--status` share one context rule (developer from a
 module, or from the root for a name / affected / all); `--init` writes, so it targets
 one module only (adopting every module at once is refused, adopt gradually).
 
+### Asking the tool your own question (`--`)
+
+Everything after `--` goes to the tool, not to sentinel. It applies to `--run` only, and
+needs exactly one type named, since one tool's options are not another's:
+
+```bash
+sentinel --run --typescript -- --noImplicitAny    # what would this deferred rule cost?
+sentinel --run --lint -- --deny-warnings          # what would zero warnings take?
+```
+
+This exists because a preset **defers** rules to keep first adoption non-breaking, and
+`--inspect` can only say that a rule is deferred. "Deferred" is honest, and it is not the
+answer anyone wants: the question is how much debt is behind it. Rather than sentinel
+modelling that question one flag at a time, the tool's own options are forwarded, so
+anything the tool can already answer is one command away.
+
+Two things to know:
+
+- **A modified run always says so**, on stderr and in the `--json` envelope (`toolArgs`).
+  These options can weaken a check as easily as strengthen it, and `--run` is what CI
+  calls, so a green result must never be mistakable for a clean standard check.
+- **For TypeScript it changes how tsc is invoked**, because build mode refuses compiler
+  options (`error TS5094`). Sentinel switches to project mode and checks each project the
+  solution `references`, since the solution itself holds no files. Emit is forced off, so a
+  question about the code never writes build output.
+
 **`--status` — adoption + conformity.** A cheap, workspace-wide read (no tool run, no
-flavour guessing): for each module it reads the committed `tsconfig` `extends` chain and
+preset guessing): for each module it reads the committed `tsconfig` `extends` chain and
 reports whether it is **adopted** (extends a sentinel preset), which preset, and whether
 it is **conformant** (drift-free, a re-`update` would change nothing), plus a coverage
 footer. This is the **drift guard** as a command, `--status --ci` exits non-zero when an
@@ -320,14 +454,14 @@ src/
   core/
     types.ts                 # the adapter contract, pure types (Adapter, FileOperation, UpdatePlan)
     base-adapter.ts          # optional convenience base class for adapters
-    domain.ts                # vocabulary + derived types (verbs, targets, flavours)
+    domain.ts                # vocabulary + derived types (verbs, targets, presets)
     settings.ts              # tunables (workspace-root marker, ...)
-    registry.ts              # register + flavour-aware resolve
+    registry.ts              # register + preset-aware resolve
     dispatch.ts              # verb → adapter method
     apply-plan.ts            # the engine's filesystem port (applies --init operations)
   roles/<config-role>/       # lint, format, typescript, build, test
     adapters/<runner>/       # one adapter per tool (implements the contract)
-    flavours/<stack>/        # config presets per stack (react, nest, svelte, ...)
+    presets/<stack>/        # config presets per stack (react, nest, svelte, ...)
   roles/{static-analysis,runtime-analysis}/   # analysis roles
     configs/                 # fixed configs (internal, not exported)
     runners/                 # one runner per sub-tool (duplication, complexity, ...)
@@ -336,9 +470,18 @@ tests/                       # unit tests + tests/e2e (runs the built dist binar
 .github/workflows/           # ci.yml (PR checks) + publish.yml (manual, version-input publish)
 ```
 
-Subpath exports (in `package.json`) expose presets to consumers. Shipped today:
-`@hublo/sentinel/tsconfig/react` · `.../tsconfig/nest` · `.../tsconfig/node`. Other
-subpaths (e.g. `.../lint/react`) land with their tool ticket.
+Presets reach consumers two different ways, decided by the tool rather than by us:
+
+- **tsconfig, as subpath exports**: `@hublo/sentinel/tsconfig/react` · `.../tsconfig/nest` ·
+  `.../tsconfig/node`. tsc resolves `extends` through the `exports` map.
+- **oxlint, as physical paths at the package root**: `oxlint/react.json`, `oxlint/nest.json`,
+  `oxlint/node.json`, `oxlint/svelte.json`, referenced as
+  `./node_modules/@hublo/sentinel/oxlint/<preset>.json`. Oxlint resolves every `extends`
+  entry as a PATH and never as a package specifier, so it never consults `exports` and the
+  physical layout IS the contract. The same is true of `jsPlugins`, which is why the local
+  Hublo plugin ships beside them in `plugins/`.
+
+Presets for the remaining tools land with their own ticket.
 
 ## FAQ
 
@@ -358,7 +501,7 @@ Yes. Per app (app A defaults to eslint, app B to biome), or even in the same app
 Most tools expose `extends` or a plugin mechanism to compose config, so the stub just points at the sentinel preset. For the rare tool that doesn't, sentinel exposes the config **directly**, it generates the full config from its preset (still one source, drift-checked).
 
 **What does an nx `project.json` look like?**
-nx is a **task runner**: it just runs the target's script. So `project.json` barely changes, the lint / test / typecheck targets run the `package.json` scripts (which call sentinel), or stay nx-inferred. nx keeps the graph, affected set, and cache; sentinel provides the config + execution.
+nx is a **task runner**: it just runs the target's script, so the command belongs in `package.json` and nx infers a target from it (verified: it does this even when the module also has a `project.json`). Adoption therefore REMOVES the role's target from `project.json`, leaving every other one alone, and writes only what nx alone needs (cache inputs) into the `nx` block of `package.json`. Each role a module adopts decouples one more thing from nx and shrinks that file. nx keeps the graph, affected set, and cache; sentinel provides the config + execution.
 
 ## Roadmap