docs(oracles): ship setup, design, and review skills, with a prompt to try them

.changeset/ship-oracle-skills.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/oracles': patch
+'@tanstack/eslint-plugin-oracles': patch
+---
+
+Ship agent skills and docs inside `@tanstack/oracles`. The package now includes `skills/` with `oracles-setup`, `oracles-design`, `oracles-review`, and `oracles-evaluate-review`. It also includes `docs/`: the oracle checklist (version 1, ORC-001 to ORC-016), a glossary, a techniques guide, model-style examples, and six instrument cards. A coding agent reads them from `node_modules`. `@tanstack/eslint-plugin-oracles` gains a README that lists its configs and rules.

README.md

@@ -9,8 +9,12 @@ every commit with [pkg.pr.new](https://pkg.pr.new).
 
 ## Packages
 
-- `packages/oracles` (`@tanstack/oracles`): the oracle framework, and the
-  `oracle-gaps` CLI. The CLI lists the production behaviour that a
+To try it, paste the prompt in
+[`packages/oracles/README.md`](packages/oracles/README.md) into your coding
+agent.
+
+- `packages/oracles` (`@tanstack/oracles`): the oracle framework, its skills
+  and docs, and the `oracle-gaps` CLI. The CLI lists the production behavior that a
   project's owning oracles leave unexercised or unjudged. A project runs it as
   `oracle-gaps --package <dir> --source <src/x.ts,...>`, with
   `--env-prefix` set to the prefix that the project passes to
@@ -148,12 +152,7 @@ required. The rule reports:
 
 A framework implementation module is exempt.
 
-No other configuration exempts a file. `settings.oracles.legacyCampaigns`, the
-old list of files that kept their raw campaigns while they migrated, is removed.
-A configuration that still sets it, to any value, exempts nothing. The rule
-reports it as `removedSetting` at line 1 of each oracle file that the
-configuration reaches, since ESLint runs a rule once per file. Convert the
-listed files to `oracleProperty`, then delete the setting.
+No configuration exempts any other file.
 
 A non-array `settings.oracles.implementationModules` or `replayWitnessModules` is
 reported at line 1 as `malformedSetting`, and it is read as an empty list.

packages/eslint-plugin-oracles/README.md

@@ -0,0 +1,39 @@
+# @tanstack/eslint-plugin-oracles
+
+Lint rules for oracle files written with `@tanstack/oracles`. They report the
+shortcuts that make an oracle pass without enforcing its law, wherever a
+syntactic check can see them. They need no type information, so an agent's
+post-edit hook can run them on one file quickly.
+
+Install it at the same pkg.pr.new commit as `@tanstack/oracles`. The
+`oracles-setup` skill in that package configures it.
+
+## Configs
+
+| Config                | Files                                                                     | Rules                                                                                                       |
+| --------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `configs.recommended` | Files whose names contain `oracle` (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`) | `no-disabled`, `no-oracle-disable`, `no-unit-test`, `oracle-property-only`, `pure-model`, `replayable-seed` |
+| `configs.production`  | `src/**` and `packages/*/src/**`                                          | `probe-form`                                                                                                |
+
+The `recommended` config also sets `linterOptions.noInlineConfig` for oracle
+files, so a directive comment cannot switch a rule off there. Fix a report;
+do not disable the rule.
+
+The `production` config covers `src/**` and `packages/*/src/**`. For source
+elsewhere, add `oracle/probe-form` with your own glob.
+
+## Rules
+
+| Rule                          | Reports                                                                                                                                                                 |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `oracle/no-disabled`          | An oracle test that stops running: `.only`, a skipped body, a switch-off condition, or one run with no fixed history.                                                   |
+| `oracle/no-unit-test`         | A test in an oracle file that reaches no declared check or model: an ordinary unit test.                                                                                |
+| `oracle/no-oracle-disable`    | A directive comment that would silence an oracle rule. Oracle rules cannot be disabled inline.                                                                          |
+| `oracle/oracle-property-only` | A raw campaign (`fc.assert`, `fc.check`, or a `.prop` registration) or a legacy campaign API in an oracle file. Only `oracleProperty` declares a generated-history law. |
+| `oracle/pure-model`           | A model, check, or reach classifier that reads a clock, ambient randomness, or a timer.                                                                                 |
+| `oracle/probe-form`           | A state probe in production code that is not in the one form the production build strips.                                                                               |
+| `oracle/replayable-seed`      | A property seed that the shared replay variables cannot select.                                                                                                         |
+
+The decided bans on snapshot matchers (B1), `fc.pre` (B3), production imports
+in a model (B4), and identical comparison operands (B7) are not rules yet.
+Reviews check them until they ship.

packages/oracles/README.md

@@ -0,0 +1,16 @@
+# @tanstack/oracles
+
+Oracle testing for TypeScript: an agent states what your code promises, then
+checks your real code against an independent model of those promises.
+
+```text
+Show me what oracle testing with @tanstack/oracles can find in this repository.
+
+1. Find the current commit of TanStack/oracles. Run
+   `git ls-remote https://github.com/TanStack/oracles refs/heads/main`, and use
+   the first 7 characters of the hash as <sha>.
+2. Install https://pkg.pr.new/TanStack/oracles/@tanstack/oracles@<sha> as a dev
+   dependency, with this repository's package manager.
+3. Read node_modules/@tanstack/oracles/skills/oracles-start/SKILL.md in full,
+   and follow it. Use <sha> wherever a skill asks for the commit to pin.
+```