@geonosis/doctor 1.3.0 → 2.0.0

package/README.md

@@ -55,6 +55,29 @@ npm and pnpm alike.
 A declared range this check cannot read is a **FAIL**, not a pass. A version it cannot judge is a
 refusal.
 
+#### A geonosis bin a git hook cannot start
+
+Every committed hook — `lefthook.yml`, `.husky/*`, `.githooks/*` — is read, and a line running a
+geonosis bin through `pnpm`, `npx`, `bunx` or `yarn` is a **FAIL** naming the direct call that
+replaces it.
+
+A git hook's PATH is not the shell's: no nvm shim, no corepack shim, nothing a version manager put
+there. dielime's first hooked commit was "refused" on 2026-08-30 and the ledger never ran — `pnpm`
+was not found, and the sentence its author read was a version manager's failure wearing a gate's
+refusal costume. That is the worst shape a gate has, because it is indistinguishable from the gate
+working. `node_modules/.bin/<bin>` is linked by every package manager and needs nothing on PATH.
+
+A hook file naming no geonosis bin is a **SKIP** with the sentence, never a vacuous OK.
+
+The FAIL names what the fix costs elsewhere: knip's lefthook plugin does not resolve
+`node_modules/.bin/<bin>` back to the package that ships it, so taking this refusal makes knip call
+that dependency unused. The line carries the `ignoreDependencies` entry that answers it, to be added
+in the same commit — a consumer told to do one thing by one gate and undo it by another does
+neither (#176).
+
+It is a `loaded` line, not a `drift` one: it reads a committed file and nothing else, and
+during.day's fast tier runs `--only loaded`, so as a drift line it fired in CI and never locally.
+
 ## The options a rule actually runs under
 
 Every reader here that consumes a rule's configuration reads `overrides[]` as well as `rules`, and
@@ -169,6 +192,26 @@ nowhere in it is a FAIL — claiming evidence and shipping none is worse than cl
 It is read for the config beside `geonosis.json` and no other: a nested config sets different
 options, and asking one config's fixtures to answer for another's would report firing nowhere.
 
+#### The engine a rule presumes (#159)
+
+A rule that reaches ONE engine carries it in its own metadata — `presumes: { engine, packages }` —
+and this asks the manifests from the config's directory up to the root whether any of those packages
+is declared. during.day ran three Medusa rules at `error` over sagaflow trees: the default step
+factory is `createStep`, sagaflow has none, and the possible findings were zero. Enabled-with-no-
+engine and clean are the identical green.
+
+A **WARN**, because which rules a repo enables is the repo's decision and the two actions — drop the
+rule from that config, or install the engine — are the reader's. A plugin too old to declare any
+presumption answers with none, and says nothing.
+
+#### What the number is evidence about (#160)
+
+The `exercised` line says, on the same line as its number, that the firing happened in the corpus
+and in the probes and **says nothing about this tree**. "17 enabled, 17 exercised" was read as
+liveness in a consumer; three of those 17 could never fire on the surface that repo writes, and its
+own `--prove` plant was green in a spelling its code does not use. Nobody goes looking for the
+denominator of a green, so it goes where the green is.
+
 ### `baseline` — a number that may only shrink, against another ref
 
 A ratchet lowers its **own** baseline whenever a number shrinks; that is what locks a win in, and it
@@ -210,6 +253,17 @@ runs `bun ./scripts/vitest-strict.ts` reads as neither, and that consumer's wrap
 exemplary fix — it spawns vitest with `--reporter=json`, reads the report, and fails on a missing
 one. The verdict is right and the sentence understates it.
 
+#### A falsification nothing runs
+
+`geonosis-ratchet --prove` plants each counter's known-bad input and requires the counter to read
+it — a gate that has never been seen red has not been shown to measure (D-029). The ratchet is
+strict about this where the flag runs, and until now nothing asked whether the flag is ever run: a
+prove that lives in the release ritual is run by the release that remembers it, and a counter can
+spend a release reading zero off a mis-escaped match (#140, measured in a consumer).
+
+A repo with counters and no `--prove` in any verify tier, script or workflow is a **WARN** naming a
+tier it already declares. A repo with no ratchet configured gets no line at all.
+
 ### `drift` — the gate that is no longer there
 
 The other four ask whether a gate measures what it names. This one asks whether it still runs.
@@ -224,6 +278,9 @@ The other four ask whether a gate measures what it names. This one asks whether
 | workspace bins | FAIL | a script calling a bin THIS repo's own workspaces declare, with no `node_modules/.bin/<name>` at the root. pnpm links a workspace bin only for the packages that depend on it: dielime's `@dielime/gate-tools` had to become an explicit root devDependency before the gate scripts could find it, and naming that took a debugging session. External commands are not judged — that would be a guess |
 | plugin directories | FAIL | a manifest directory under the roots `no-unregistered-plugin-dir` names that the registry never mentions. SKIP when the rule is not configured — the roots are the repo's, read from the rule it already wrote, never a list invented here |
 | `publicHoistPattern` | FAIL / SKIP | a pattern in `pnpm-workspace.yaml` with no root `node_modules` link for a workspace package it matches. pnpm dropped one during an **unrelated** `add`, then answered "Already up to date" to every install afterwards over a clean `git status` — the tree was fixed only by deleting `.modules.yaml` and `.pnpm-workspace-state-v1.json`, which the line carries verbatim. Only workspace packages are judged, because one exists on disk by construction and a missing link for it cannot be "the install never ran"; the root package is never asked about, since no package manager puts a repo's root inside its own `node_modules`. A pattern matching no workspace package is SKIP, never a pass |
+| `@geonosis/observability` | WARN | it is declared in a manifest here and **no source file imports it** — installed is not composed. The kit ships the sink adapter and the reference consumer sent production errors nowhere, because nothing at its composition root ever built one; from outside the process that reads exactly like a project with nothing to report (#165). No line at all in a repo that never installed it |
+| an `allowBuilds` entry | WARN | a platform-split package allowed by ONE platform name. pnpm 11.5.1 writes this file itself when it refuses a build script, and what it writes is the platform of the machine that ran the install — so every other platform refuses the install by the name that is missing, on somebody else's machine (#188, measured here). How many a family publishes is the registry's answer, so the line names the family and the shape rather than a count it would have to guess |
+| a workspace's `lint` script | WARN / SKIP | the file set the script covers, against the one a committed hook lints. during.day's `apps/web` script covered `src` and not `__tests__`, so the pre-commit hook — which lints whatever is STAGED — was the first door ever to read a moved test file, and it found violations the package gate had never seen (#172). The line names the globs left to the hook alone. SKIP when no committed hook lints staged files: there is no second file set to be narrower than |
 | the law | WARN / SKIP | its measured length against `geonosis.json` → `law.maxLines`. **SKIP when the repo declares no ceiling** — during.day read "1,104 lines against a ceiling of 200" for a number it never chose, which is unactionable in both directions. The length is still printed, because that is the number a repo declares against |
 | `.claude/settings.json` | WARN | nothing under `enabledPlugins` enables the kit's plugin, so the gates run and the method does not (D-041). The **user-scope** `~/.claude/settings.json` is read too and acknowledged as "installed elsewhere — not this repo's to declare": both source repos got this WARN while the plugin was installed machine-wide. The key is read, never the word `geonosis` appearing somewhere in the file |
 | `geonosis.json` blocks | WARN | a block whose package **no manifest declares** — nothing reads it, and a stale `node_modules` copy is named as what a previous install left behind; a block whose package is declared and does not resolve — run the install; or a **declared** package with no block, running on defaults nobody chose |
@@ -238,20 +295,6 @@ The "installed with no block" direction is scoped to **direct** dependencies. `@
 a package they never installed is noise — which is how a reader learns to skip the section (#61). A
 transitive presence gets an OK line naming where it came from, and no demand.
 
-#### A geonosis bin a git hook cannot start
-
-Every committed hook — `lefthook.yml`, `.husky/*`, `.githooks/*` — is read, and a line running a
-geonosis bin through `pnpm`, `npx`, `bunx` or `yarn` is a **FAIL** naming the direct call that
-replaces it.
-
-A git hook's PATH is not the shell's: no nvm shim, no corepack shim, nothing a version manager put
-there. dielime's first hooked commit was "refused" on 2026-08-30 and the ledger never ran — `pnpm`
-was not found, and the sentence its author read was a version manager's failure wearing a gate's
-refusal costume. That is the worst shape a gate has, because it is indistinguishable from the gate
-working. `node_modules/.bin/<bin>` is linked by every package manager and needs nothing on PATH.
-
-A hook file naming no geonosis bin is a **SKIP** with the sentence, never a vacuous OK.
-
 ### `observability` — a sink nobody can reach
 
 The exporter named by the `observability` block in `geonosis.json`: is a sink configured, is its