Prepare 1.0 stability release

AGENTS.md

@@ -211,10 +211,11 @@ seconds instead of the full run's minute — and the full run stays the gate.
   tests grow the numerator. Read the reasons before moving the number, and add
   one when you do — a gate whose verdict flips on which PHP built the run is
   measuring the environment, not the suite.
-  For the published `0.x` line, `minMsi: 92` is therefore the explicit release
-  policy: a single local run at 94.1% is evidence, not a new gate. Before the
-  `1.0` release, rerun a reproducible CI-like matrix and raise the threshold
-  only when it has stable headroom above the new value.
+  For the published `0.x` line, `minMsi: 92` was the explicit release policy.
+  The `1.0` release requires a reproducible CI-like matrix run on the candidate
+  and a documented threshold decision; a single local run is evidence, not a
+  new gate. Keep the configured threshold and its rationale together until the
+  escaped-mutant list has enough stable headroom for a measured increase.
 - **The only `&` in the package is in generated code, and that is deliberate.**
   Psalm cannot follow a reference into an object property and says so by name;
   the way out is not a suppression but moving the reference to where Psalm never
@@ -472,7 +473,7 @@ decided lives in this section and in `docs/scripts/check-integrity.mjs`.
 | **A new `@api` free function needs `make docs-api` too**, and a row in `llms.txt` | checks 2b and 7 — the class-only pipeline used to drop functions silently |
 | **A new PHPStan rule needs its row on `/api/rules` in the same PR** | check 9; the analyser packages have no other public contract |
 | **`MIGRATION.md` is generated** from `docs/src/guide/migrating-*.md`. Edit the pages, run `make docs-migration` | check via `docs:check:migration` |
-| **`docs/.api-workspace/composer.lock` is committed and moves with every satellite release.** A caret on 0.x pins a minor, so `^0.2` documented `understudy-psalm` 0.2.0 while 0.8.0 was out; bump the pin, `composer update` in the workspace, `make docs-api`, commit all three | `docs.yml` runs `composer outdated --direct --strict` there and goes red otherwise |
+| **`docs/.api-workspace/composer.lock` is committed and moves with every satellite release.** A caret on 0.x pins a minor; on 1.x it follows the stable major, but the lock still has to move after every satellite release. Bump the constraints, `composer update` in the workspace, `make docs-api`, commit all three | `docs.yml` runs `composer outdated --direct --strict` there and goes red otherwise |
 | **`make perf` means re-reading three files**: `perf/README.md`, `README.md`'s Performance table and `README.ru.md`'s. Keep the `<!-- #region site -->` markers and the `Taken YYYY-MM-DD` line | checks 10 and 11 |
 | **An `@include` that cannot resolve fails silently in VitePress** — the page renders as its heading and nothing else | check 12 |
 | **`{{` in prose needs `<code v-pre>`** | Vue interpolates it otherwise |

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.0.0 — 2026-09-27
+
+The stability release. The public `@api` surface is the same as `0.12.0`:
+there are no renamed, removed, or retyped public members. A project on
+`^0.12` upgrades by widening the constraint to `^1.0`. The compatibility
+policy in `README.md` and `README.ru.md` defines what is frozen from here on.
+
+- The four family satellites release their own `1.0.0` versions after this
+  engine release and require `rasuvaeff/understudy` `^1.0`.
+- Existing `VerificationFailure` fields and `FailureKind` cases are stable.
+  A new failure kind may be added in a minor release; consumers must keep a
+  default branch when matching the enum.
+- The family release order is engine first, then the satellites. The core CI
+  contract suite installs each satellite against this checkout through a path
+  repository claiming version `1.0.0`.
+
 ## 0.12.0 — 2026-09-19
 
 - **Fixed.** A specification closure is run exactly once. Since 0.11.0 the

README.md

@@ -983,6 +983,28 @@ in your test file already.
 
 It is a development dependency. Do not install it in production.
 
+## Compatibility policy
+
+The public contract is every class, interface, enum, exception, and free
+function marked `@api`. Types marked `@internal` are implementation details and
+may change in any release. The `1.x` line keeps the names, signatures, and
+readonly fields of the public API stable; constructors only gain optional
+parameters at the end. Removing, renaming, or retyping an existing public
+member is a major-version change.
+
+`VerificationFailure` fields and existing `FailureKind` cases are stable. A
+minor release may add a new failure kind or populate a new field, so code that
+matches `FailureKind` must include a default branch. Failure messages are prose
+and may be reworded in a minor release; consumers should use
+`VerificationFailed::failures()` for structured handling.
+
+The family releases in this order: `rasuvaeff/understudy` first, then
+`understudy-testo`, `understudy-psalm`, `understudy-phpunit`, and
+`understudy-phpstan`. Each satellite's 1.x line requires the core with a caret
+on the current major (`^1.0`). Supporting a newer PHP minor widens the PHP
+constraint in a patch release; dropping a supported PHP version is a major
+release.
+
 ## Examples
 
 Runnable scripts live in [examples/](examples/) — one per concept: the three

README.ru.md

@@ -981,6 +981,27 @@ SensitiveParameter)`, — так же, как PHP редактирует так
 
 Это dev-зависимость. В production её ставить не нужно.
 
+## Политика совместимости
+
+Публичный контракт — каждый класс, интерфейс, enum, exception и свободная
+функция с пометкой `@api`. Типы с пометкой `@internal` остаются деталями
+реализации и могут меняться в любом релизе. В линии `1.x` имена, сигнатуры и
+readonly-поля публичного API стабильны; конструкторы могут получать только
+необязательные параметры в конце. Удаление, переименование или изменение типа
+существующего публичного члена требует мажорной версии.
+
+Поля `VerificationFailure` и существующие кейсы `FailureKind` стабильны. В
+минорной версии может появиться новый кейс или новое заполненное поле, поэтому
+в `match` по `FailureKind` нужен `default`. Тексты ошибок являются прозой и
+могут меняться в минорной версии; для программной обработки используйте
+структуру `VerificationFailed::failures()`.
+
+Семейство выпускается в порядке: сначала `rasuvaeff/understudy`, затем
+`understudy-testo`, `understudy-psalm`, `understudy-phpunit` и
+`understudy-phpstan`. Линия `1.x` каждого satellite требует core через caret
+текущей мажорной версии (`^1.0`). Поддержка нового минора PHP расширяет
+constraint в patch-релизе; отказ от поддерживаемой версии PHP требует мажорной.
+
 ## Примеры
 
 Исполняемые скрипты — в [examples/](examples/), по одному на концепцию: три