millionco__react-doctor/AGENTS.md

## General Rules

- MUST: Use @antfu/ni. Use `ni` to install, `nr SCRIPT_NAME` to run. `nun` to uninstall.
- MUST: Use TypeScript interfaces over types.
- MUST: Keep all types in the global scope.
- MUST: Use arrow functions over function declarations
- MUST: Never comment unless absolutely necessary.
  - If the code is a hack (like a setTimeout or potentially confusing code), it must be prefixed with // HACK: reason for hack
- MUST: Use kebab-case for files
- MUST: Use descriptive names for variables (avoid shorthands, or 1-2 character names).
  - Example: for .map(), you can use `innerX` instead of `x`
  - Example: instead of `moved` use `didPositionChange`
- MUST: Frequently re-evaluate and refactor variable names to be more accurate and descriptive.
- MUST: Do not type cast ("as") unless absolutely necessary
- MUST: Remove unused code and don't repeat yourself.
- MUST: Use `truffler` to find existing symbols before adding a utility, helper, type, or rule, and again after finishing a task to catch duplicates and dead code (see "Symbol Search & Deduplication").
- MUST: Always search the codebase, think of many solutions, then implement the most _elegant_ solution.
- MUST: Before adding or changing the **public surface** (CLI flags/commands, the score, config, the JSON report, package APIs, the GitHub Action, website, or terminal output), run the `product-thinking` pass (`.agents/skills/product-thinking/`): name the user's job, reuse before adding, wire one telemetry metric, add the compatibility artifacts, and set a kill metric. Lint rules use the rule pipeline instead.
- MUST: Put all magic numbers in `constants.ts` using `SCREAMING_SNAKE_CASE` with unit suffixes (`_MS`, `_PX`).
- MUST: Put small, focused utility functions in `utils/` with one utility per file.
- MUST: Use Boolean over !!.

## Symbol Search & Deduplication (truffler)

`@rayhanadev/truffler` (dev dependency) is fuzzy JS/TS symbol search powered by `oxc-parser`.
Use it to avoid duplicating existing code. The `find-similar-functions` skill
(`.agents/skills/find-similar-functions/`) carries the full workflow; the short version:

- WHEN PLANNING / SCOPING — before adding a utility, helper, type, constant, or rule, search
  for an existing symbol to reuse or extend. Derive a few queries from the behavior (proposed
  name + domain noun + verb), search the narrowest root first, then read the top matches before
  writing anything. It is how you reuse an existing helper instead of duplicating it, per "don't
  repeat yourself" and the one-utility-per-file `utils/` convention.
- AFTER FINISHING A TASK — re-run searches for the symbols you added to confirm you did not
  duplicate an existing helper, and delete any code your change superseded.

```bash
bunx @rayhanadev/truffler "<query>" packages --kind function,method,interface,type,constant --limit 20
```

Run it with `bunx @rayhanadev/truffler` (the published `bin` is a TypeScript entry Bun runs
directly, and the pinned dev dependency is reused rather than re-downloaded). Narrow `<query>`
and the root (e.g. `packages/core/src`) for precision; broaden only when nothing matches.

## Package Layout

```
packages/
  core/                          PRIVATE  the diagnostic engine
    src/
      types/                     PRIVATE shared cross-package TS types (DiagnoseOptions,
                                 ProjectInfo, JsonReport, …) — no runtime code
      project-info/              project discovery (discoverProject, findMonorepoRoot,
                                 framework detection, narrow Error subclasses thrown
                                 BEFORE the Effect runtime takes over)
      errors.ts                  tagged Schema.TaggedErrorClass leaves + ReactDoctorError union
      schemas.ts                 Diagnostic / Severity / JsonReport / buildDiagnosticIdentity
                                 (also exposed as `@react-doctor/core/schemas` subpath
                                 since the names overlap the TS types above)
      refs.ts                    Context.Reference for ambient env config
      run-inspect.ts             streaming orchestrator (the heart)
      build-diagnostic-pipeline  per-element filter pipeline (single source of truth)
      services/                  Context.Service implementations (Files, Git, Project,
                                 Config, Linter, Maintainability, Score, Reporter,
                                 Progress, NodeResolver, StagedFiles, SupplyChain)
                                 + LintPartialFailures
      ...                        rest of the lint / score / suppression engine
  api/                           PRIVATE  programmatic diagnose() (Effect.runPromise shell)
  react-doctor/                  PUBLISHED  CLI + public inspect() + bin
  oxlint-plugin-react-doctor/    PUBLISHED  the 100+ rules, owns the canonical
                                 `react-native-dependency-names.ts` (re-exported from
                                 core to break the rule-package ↔ core cycle)
  eslint-plugin-react-doctor/    PUBLISHED  ESLint mirror of the oxlint plugin
```

## Effect v4 Conventions

Built on `effect@4.0.0-beta.102`. See `tmp/effect/.patterns/effect.md` (cloned reference)
and `~/Developer/react-doctor-evals/src/` (the application that pioneered these patterns
for this codebase) for canonical examples.

### Imports

- ALWAYS: `import * as Schema from "effect/Schema"`, `import * as Effect from "effect/Effect"`,
  `import * as Cause from "effect/Cause"`, etc. — one module per import line.
- NEVER: `import { Schema, Effect } from "effect"` — the umbrella import inflates the
  type-resolution graph and contradicts what every other Effect codebase does.

### Errors

- Every fallible service fails with `ReactDoctorError` (`reason: Schema.Union([...])`)
- Each leaf is a `Schema.TaggedErrorClass<Self>()("Tag", { fields })` with a
  `get message()` getter (NOT `message =`) returning a human string.
- Opaque causes use `Cause.pretty(Cause.fail(this.cause))` in the message body.
- Renderers dispatch on `error.reason._tag`, NEVER on `error.message.includes(...)`.
- `formatReactDoctorError(error)` / `isReactDoctorError(error)` / `isSplittableReactDoctorError(error)`
  live in `core/src/errors.ts`. Use them; don't add new error-shape helpers.

### Error dispatch / recovery — v4 idioms

- **`Effect.catchReasons(errorTag, cases, orElse?)`** — the v4-canonical way to
  dispatch on a `Schema.TaggedErrorClass` reason union. Each entry catches one
  reason `_tag`; the optional `orElse` handles unmatched reasons. NEVER write
  manual `if (cause.reason instanceof X)` ladders inside a `catch` block — the
  Effect pipeline gives you exhaustive, type-safe narrowing for free. See
  `inspect.ts → restoreLegacyThrow` and `api/diagnose.ts` for the canonical
  shape.
- **`Effect.catchTag(tag, handler)`** — for a single tagged error (e.g.
  `Effect.catchTag("PlatformError", ...)` in `services/git.ts` to fold the
  `ChildProcess` platform error into a `ReactDoctorError`).
- **`Effect.catch`** (renamed from v3 `Effect.catchAll`) — for catch-all.
- **`Effect.die(error)`** — promote a recovered value into a defect that
  `runPromise` re-throws unchanged. Used in `catchReasons` handlers when the
  programmatic contract still wants the legacy `Error` class on the throw.
- **NEVER** `try/catch` inside `Effect.gen` (v4 hard rule). Wrap the sync
  throw in `Effect.try({ try, catch })` and recover via
  `Effect.orElseSucceed` / `Effect.catch` instead. See
  `render-summary.ts → printSummary` for the canonical shape.

### Generator hygiene

- **`return yield* Effect.fail(...)`** — terminal effects (Effect.fail,
  Effect.interrupt, Effect.die) must be `return yield*` so TypeScript sees
  the unreachable-code property. Bare `yield*` of a terminal lets unreachable
  code accumulate after it. See `services/git.ts` `diffSelection` for examples.
- **`Effect.gen({ self: this }, function* () { ... })`** — v4 changed the
  `self`-bound form. The plain `Effect.gen(function* () { ... })` form is
  unchanged; only class-method generators bound to `this` need the options
  object.
- **`Effect.fnUntraced(function* () { ... })`** — prefer over a function
  whose body is `Effect.gen` when the function is called many times per
  operation (hot path). Cuts tracing overhead. Not currently used in this
  codebase — Git invocations and inspect-pipeline calls run once per scan,
  not in a hot loop.

### Services

- `Context.Service<Self, Interface>()("react-doctor/Name", { make: ... })` — short
  prefix in the identifier (matches react-doctor-evals' `rde/X` shape).
- Service method bodies use `Effect.fnUntraced` for hot paths, `Effect.sync` for
  one-liners. Test layers + orchestration use `Effect.gen`.
- **`Effect.fn("Service.method")`** for non-trivial methods so they surface as
  named spans in OTel traces. Production cost is zero when no tracer layer is
  provided; with `Otlp.layerJson(...)` users see one span per service call.
  Canonical eval pattern (`react-doctor-evals/src/Runner.ts` → every method).
- `Service.of({ ... })` everywhere inside `Layer.succeed` / `make:` — never
  `{ ... } as const`.
- `Layer.effect` when the service has init work (e.g. `Cache.make`); `Layer.succeed`
  when stateless.
- Method takes a single object arg when there are >1 parameters
  (e.g. `Files.readLines({ filePath, rootDirectory })`).

### Layer naming

- `layerNode` for the production Node.js implementation.
- `layerOf(value)` for the test layer that returns a pre-supplied value.
- `layerInMemory(Map)` for filesystem-shaped services backed by an in-memory tree.
- `layerCapture` for the test layer that records calls into a `Ref` exposed via a
  sibling `*Capture` service (e.g. `ReporterCapture`, `ProgressCapture`).
- `layerNoop` for the production layer that has void-return / discard semantics
  (Reporter, Progress). Analyzers (Linter, Maintainability) use `layerOf([])` instead.
- Implementation-specific names: `layerOxlint`, `layerHttp`, `layerOra(factory)`.

### Schemas

- Use `Schema.Class<Self>("Name")({ fields })` for wire records.
- Use `Schema.Literals(["a", "b"])` for unions of literals (plural), `Schema.Literal(1)`
  for single literals.
- `Schema.NullOr(X)` for `X | null`; `Schema.optional(X)` for `X?`.
- `Schema.brand("X")` via `.pipe()` for branded primitives.
- Schema for wire types (Diagnostic, JsonReport); interfaces for arg types
  (InspectInput, LintInput) — avoid runtime encode/decode cost on hot paths.

### Ambient config

- Env-var reads + cache paths go through `Context.Reference<T>("react-doctor/X", { defaultValue })`.
  See `core/src/refs.ts`. Tests override via `Layer.succeed(MyRef, ...)`.
- Secrets (API tokens, signing keys) should prefer `Config.redacted("ENV_NAME")` over
  `Context.Reference` so they auto-redact in logs / traces. Group with `Config.all({ ... })`
  at the service constructor when you need several. (Pattern from
  `react-doctor-evals/src/GitHub.ts` — not yet used in this codebase; document
  the convention so the first secret-shaped config does it right.)

### Observability

Telemetry is split across two backends, deliberately:

- **Axiom** takes traces and metrics — the per-run wide event, every
  `Effect.fn("Service.method")` span, and all counters/distributions. Axiom bills
  by ingested volume with no active-series limits, which is the model
  high-cardinality wide events want.
- **Sentry** takes crashes only. It keeps what it is good at: source-map
  symbolication (`scripts/sentry-sourcemaps.mjs`), issue grouping, and a
  quotable event id. Axiom has none of those.

Effect exposes a single `Tracer` reference, so the two are mutually exclusive
for spans: the CLI pins `tracesSampleRate: 0` and Sentry never records a span.

- Wrap the top-level entry of a multi-step operation in `Effect.withSpan("name", { attributes })`.
  See `core/src/run-inspect.ts → runInspect` for the canonical shape. Attribute
  keys use dotted namespacing (`inspect.directory`, `inspect.isCi`).
- Per-service-method spans come from `Effect.fn("Service.method")` — see Services section
  above. The two compose: `runInspect` is the parent span, every `Service.method` is a child.
- **Transport.** `core/src/observability.ts` owns three layers.
  `layerAxiomTraces` and `layerAxiomMetrics` are composed by hand rather than via
  `Otlp.layer`, because Axiom routes each signal to a different dataset through a
  different header (`X-Axiom-Dataset` vs `x-axiom-metrics-dataset`) and
  `Otlp.layer` passes one `headers` object to every signal. `layerObservability`
  merges them and picks the backend: a user-configured `REACT_DOCTOR_OTLP_*`
  endpoint wins over first-party Axiom, else Axiom, else `Layer.empty`.
  Serialization is **protobuf**, not JSON — Axiom's `/v1/metrics` accepts
  `application/x-protobuf` only. `OtlpSerialization.layerProtobuf` ships with
  Effect and adds no dependency.
- **Build the layer exactly once per process.** `cli/utils/telemetry-runtime.ts`
  builds it into a long-lived scope and shares the resulting `Context`; the run
  root span, the scan program, and the renderer all draw their tracer from it.
  Two reasons this is not optional. Child spans nest under the run span natively,
  with no `ExternalSpan` stitching. And Effect tracks delta-temporality state on
  the _metrics exporter instance_, so a second exporter starts with no previous
  snapshot and re-reports every counter's full value — silently doubling every
  metric. `shutdownTelemetry()` is memoized for the same reason: several exit
  paths can fire (a `--debug` user error flushes, then the top-level catch
  flushes again). A regression test in `core/tests/telemetry-payload.test.ts`
  pins the double-count behavior so a refactor that merges the layers fails loudly.
- **Exit flush.** Closing the telemetry scope is what ships buffered spans and
  metrics, bounded by `TELEMETRY_SHUTDOWN_TIMEOUT_MS` (1s — deliberately tighter
  than Sentry's 2s error flush). The periodic `TELEMETRY_EXPORT_INTERVAL_MS` is
  longer than any realistic run so the scope close is the only export. Note the
  metrics exporter passes `maxBatchSize: "disabled"` internally, which skips
  Effect's empty-buffer short-circuit — it POSTs on every scope close whether or
  not anything was recorded, so on a firewalled machine that request cannot fail
  fast.
- **Anonymization.** Telemetry must stay anonymized, and OTLP has **no**
  `beforeSend`-style hook — the safety net Sentry gave us for free had to be
  rebuilt. Two mechanisms now carry it:
  - `core/src/utils/make-scrubbing-tracer.ts` wraps the tracer so every span
    name, attribute value, and event payload passes through `anonymizeText`
    (home dir / username → `~`, then secrets and emails redacted) on the way to
    the exporter. It is applied inside `layerAxiomTraces`, so an attribute added
    later cannot bypass it.
  - `cli/utils/record-metric.ts` scrubs attribute values at the emit site, since
    metrics never touch the tracer.

  Call sites should still scrub at the source — `run-inspect.ts` wraps
  `inspect.directory` in `scrubSensitivePaths` — and the tracer is the backstop
  for the ones that don't. `scrub-sentry-event.ts` still runs as Sentry's
  `beforeSend` for crash reports. If you add a field to any payload, confirm it
  carries no username, hostname, IP, secret, or absolute path.

- **Sentry scope shape.** `cli/utils/build-sentry-scope.ts` is the one place that
  projects the run snapshot (and the scanned project, once known) into `tags` +
  `contexts`. Both `instrument.ts` (`initialScope`) and `report-error.ts` consume
  it, and `record-metric.ts` reprojects its `tags` onto every metric at emit
  time — so add new run-level metadata there, not at call sites. Project info is
  captured via `recordSentryProjectContext` (`with-run-span.ts`), which both
  remembers it for the lazy error path and sets it as root-span attributes.
- **Crash references + trace linkage.** `reportErrorToSentry` returns the Sentry
  event id; the CLI catch blocks thread it into `handleError` so it's printed as
  a user-quotable reference and added to the prefilled GitHub issue. Because
  spans now live in Axiom, Sentry's native trace linkage no longer reaches them —
  instead the crash is tagged with `axiomTraceId` and `runId`, so a Sentry issue
  pivots straight into the run's Axiom trace. `--debug` prints that same trace id.
- **Metrics.** `cli/utils/record-metric.ts` (`recordCount` / `recordDistribution`)
  writes into Effect's process-global `MetricRegistry`, which the OTLP exporter
  snapshots at flush. Both are guarded by `isTelemetryEnabled()` so they are true
  no-ops under `--no-score` / `--no-telemetry`, in tests, and for the
  `@react-doctor/api` library. Metric names live in the `METRIC` map in
  `cli/utils/constants.ts` (dotted, domain-grouped; high-cardinality dimensions
  go in attributes, never the name). Two constraints differ from Sentry:
  Effect metric attributes are **string-only**, so numbers and booleans are
  stringified (`null`/`undefined` are dropped, never coerced to `"null"`); and
  histograms need explicit bucket boundaries, so all distributions share
  `METRIC_DISTRIBUTION_BOUNDARIES`. Per-scan metrics (`scan.*`, `rule.fired`,
  `lint.failed`, …) are emitted by `cli/utils/record-scan-metrics.ts`;
  `rule.fired` is one high-cardinality counter keyed by
  `rule`/`plugin`/`category`/`severity` attributes (never a metric-name-per-rule).
- **The canonical run wide event.** The richest telemetry is one
  high-dimensionality wide event per scan, not a pile of narrow counters: the
  per-run root span (`with-run-span.ts`) is enriched with the full outcome by
  `cli/utils/build-run-event.ts` (`recordRunEvent`, plus the pure, testable
  `buildRunEventAttributes`). `inspect.ts` calls it on the success path (after
  `recordScanMetrics`) and, via a `try/catch` around the span body, on the
  failure path — so the event lands with an `outcome.status` (`clean`/`ok`/
  `blocked`/`error`), `outcome.exitCode`, and `outcome.errorTag` taxonomy even
  when the scan throws. The run + project base context is already on the span, so
  the event adds only what that doesn't — every attribute namespaced by concept
  via `withNamespace` (`cli/utils/with-namespace.ts`) so the keys tree up in the
  attribute browser: scan config (`scan.mode`, `scan.parallel`, `scan.workerCount`,
  `scan.rulesConfigured`/`scan.rulesDisabled`, `scan.ignoredTagCount`,
  `scan.hasCustomConfig`, … plus the `scan.fileCount` extent), the verdict
  (`outcome.wouldBlock`/`outcome.blocking`/`outcome.clean`/`outcome.skippedChecks`),
  findings (`diag.total`, `diag.errors`/`diag.warnings`, `diag.affectedFiles`,
  `diag.distinctRules`, `diag.topRule`, per-category `diag.category.*`),
  `score.value`/`score.label`/`score.available`, the `lint.*`/`maintainability.*`/
  `supplyChain.*` pass outcomes, `timing.*` durations, and the CI/PR specifics
  (`action.actorAssociation`, `action.runnerOs`, and the forwarded action knobs
  `action.comment`/`action.reviewComments`/`action.versionPin`). Typing matters
  for querying: numeric outcomes are numbers (so you can take `p75(score.value)`),
  dimensions are strings/bools (so they filter/group); `null` is dropped via
  `toSpanAttributes` so absent signals never become `"null"`. Query it with APL
  over the traces dataset and build dashboards there instead of pre-aggregating
  counters. Put new run-level dimensions on `build-run-context.ts` →
  `build-sentry-scope.ts` so they ride every event and metric; put per-scan
  outcome dimensions on the wide event (wrapped in `withNamespace`), **not** new
  counters — the `scan.completed`/`scan.duration`/`rule.fired` counters stay as
  the cheap floor alongside `cli.invoked`/`cli.error`. Score reachability is
  derivable (`!score.available && !lint.failed && !maintainability.failed && !scan.noScore`)
  and score latency is the `Score.compute` child span's duration, so neither
  needs a dedicated field. CI detection + the official-action marker and
  forwarded inputs live in `cli/utils/is-ci-environment.ts`; `action.yml` sets the
  `REACT_DOCTOR_GITHUB_ACTION` marker + `REACT_DOCTOR_ACTION_*` env on its scan
  step. Keep every attribute free of username, path, secret, and repo/owner identity.
- **Opt-out.** `cli/utils/is-telemetry-enabled.ts` is the single gate for every
  backend: `--no-score`, `--no-telemetry`, `REACT_DOCTOR_NO_TELEMETRY`, or a test
  run disables all of it. Blanking `SENTRY_DSN` alone no longer silences
  anything, so internal tooling that must not report (the evals harness, the
  benchmark environment, the delta-audit runner) sets `REACT_DOCTOR_NO_TELEMETRY`.
- **Credentials.** The Axiom ingest token is embedded in `cli/utils/constants.ts`
  (`AXIOM_INGEST_TOKEN`), mirroring the public Sentry DSN — but unlike a DSN it is
  a real credential, so it is minted **ingest-only and scoped to the two
  datasets**. It ships in the tarball and is therefore extractable: rotation means
  cutting a release, and an Axiom monitor on anomalous ingest volume is the
  detection. `cli/utils/resolve-axiom-telemetry-options.ts` resolves it (with
  `REACT_DOCTOR_AXIOM_TOKEN` / `_DOMAIN` / `_DATASET` overrides for local
  testing — deliberately prefixed, since the bare `AXIOM_*` names are Axiom's
  own and reading them would hijack the telemetry of anyone already running it)
  and returns `null` when unset, so an unconfigured build simply doesn't export.
  Core never reads these itself — keeping them CLI-side is what makes
  `@react-doctor/api` silent by construction rather than by a runtime guard.
- **runId.** `cli/utils/run-id.ts` mints one random `runId` per CLI run
  (process). It rides the Sentry `run` context and the wide event, and is a tag
  only on crash reports (where it links to the Axiom trace) — never a metric
  attribute, where a per-run unique value would explode counter cardinality. A
  workspace invocation scanning several projects shares one `runId`; the
  per-project span attributes disambiguate. Do not add a plaintext or hashed repo
  id to either backend.

### Console / logging

- ALWAYS: `import * as Console from "effect/Console"` and `yield* Console.log(...)` /
  `Console.warn(...)` / `Console.error(...)` from inside renderers, services, and any
  Effect-typed code. Effect's `Console` is a `Context.Reference` whose default sink is
  `globalThis.console`, so the production path is identical to a raw `console.log`
  while remaining swappable for tests / silent mode.
- NEVER: invent a parallel `Logger` / `LoggerWriter` abstraction. The historical custom
  Logger service was removed when the renderer pipeline went Effect-typed; the only
  remaining bridge is `cli/utils/cli-logger.ts`, a thin sync wrapper around
  `Effect.runSync(Console.X)` for imperative CLI helpers that aren't yet `Effect.gen`.
- Silent mode is `Effect.provideService(Console.Console, silentConsole)` (renderer
  pipeline) or `installSilentConsole()` (JSON mode, which monkey-patches the global
  console because the surrounding CLI command body is imperative). Both routes leave
  the underlying `Console.*` Effect intact — there is no `if (silent) return` check
  at any call site.

## Testing

Tests live alongside source in each package's `tests/` directory:

- `packages/core/tests/` — service tests + run-inspect orchestration tests
- `packages/api/tests/` — api shell tests
- `packages/react-doctor/tests/` — CLI + end-to-end fixture tests

Test framework is `vite-plus/test` (the existing vitest wrapper).

Run checks always before committing with:

```bash
pnpm test         # all packages
pnpm lint
pnpm typecheck
pnpm format       # use `format:check` to verify only
pnpm smoke:json-report   # validates the built CLI's JSON output against the schema
```

## Release authorization

- MUST: Discourage minor and major Changesets. Do not add one unless the user explicitly requests
  that release level. Patch Changesets may be added without a separate request when appropriate.
- MUST: Never merge a Changesets release PR, including any `changeset-release/*` branch, without
  fresh, explicit user confirmation for that exact PR and version immediately before the merge.
- General instructions to merge, ship, land, or babysit green PRs do not authorize merging a
  release/version PR. Treat merging a PR that triggers publication as publishing the release.
- MUST: Never publish packages, push or move release tags, or trigger, approve, rerun, or merge a
  release/publish workflow without fresh, explicit user confirmation for the exact versions and
  packages involved.
- Agents may prepare, validate, and babysit a release candidate, but must stop before the first
  publishing action and report the exact PR, versions, packages, tags, and workflows awaiting user
  approval.
- These confirmation requirements also apply to GitHub Action releases described below. Once the
  user explicitly approves a specific release, follow all required versioning and tag steps.

## GitHub Action versioning

The composite GitHub Action is **versioned independently from the npm packages**. "The action"
is `action.yml` (repo root) plus the scripts it shells out to (`scripts/ensure-json-report.mjs`,
`scripts/normalize-changed-files.mjs`, `scripts/render-github-action-comment.mjs`,
`scripts/resolve-package-spec.mjs`). Treat a change to any of those files as an action release,
and keep the list in sync with `ACTION_RELEASE_FILES` in
`scripts/recommend-action-version-bump.mjs` (the release guard).

- Two tag namespaces coexist — never conflate them:
  - npm packages — `react-doctor@X.Y.Z`, `eslint-plugin-react-doctor@X.Y.Z`,
    `oxlint-plugin-react-doctor@X.Y.Z` (created by Changesets in CI; see
    `.github/workflows/publish.yml`).
  - GitHub Action — `v`-prefixed semver `vX.Y.Z` plus a floating major `vN` (the GitHub Actions
    convention; the `v` prefix keeps these distinct from the unprefixed package tags above).
    Current: the `v2.x` line (check `git tag --list 'v*'` for the latest); `v2` → the same
    commit. The `v0.x` line is the pre-rebuild action; the `f4035fce` PR-reporting rebuild is
    `v1.0.0`.
- MUST: cut a tag on every commit that touches the action files. `feat(action)` → minor bump;
  everything else (`fix` / `refactor` / `chore` / `revert` / docs-only edits to `action.yml`) →
  patch bump. A breaking change to inputs/outputs or the runtime contract → major bump.
- MUST: after tagging a new `vX.Y.Z`, move the floating major `vN` to that same commit so
  `uses: millionco/react-doctor@vN` keeps resolving to the latest compatible release.
- Tags are GPG-signed annotated tags (`tag.gpgsign=true`), so a bare `git tag vX` will demand a
  message and fail in scripts. Always create/move with an explicit message:

```bash
# new release at the commit that changed the action
git tag -a v2.2.3 <commit> -m "react-doctor action v2.2.3"
# move the floating major (force-update only the vN pointer)
git tag -fa v2 <commit> -m "react-doctor action v2 (floating major -> v2.2.3)"
git push origin v2.2.3
git push --force origin v2   # the force applies to the moving major tag only
```

- MUST: never tell consumers to reference `@main` in docs/examples. `@main` runs whatever HEAD
  points to with `pull-requests: write` granted — a supply-chain risk (issue #299). Recommend a
  full commit-SHA pin with a trailing version comment for hardened CI
  (`uses: millionco/react-doctor@<sha> # v2.2.2`), or `@vN` for convenience.

## Reference reading

- `tmp/effect/.patterns/effect.md` — canonical Effect v4 idioms (cloned for reference,
  gitignored)
- `~/Developer/react-doctor-evals/src/` — sister application this codebase's runtime
  patterns are modeled on (Schemas.ts, Runner.ts, Worker.ts, errors.ts shapes)