@vitronai/themis 0.1.0-beta.4 → 0.1.1

package/CHANGELOG.md

@@ -4,10 +4,18 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+## 0.1.1 - 2026-03-23
+
+### Changed
+
+- Updated the primary Themis brand mark in the README/package surface to use `src/assets/themisVerdictEngine.png` while keeping the existing report imagery for HTML-report references and report-specific documentation.
+
+## 0.1.0 - 2026-03-23
+
 ### Changed
 
 - Added a first-party `themis generate` / `themis scan` code-scan flow that generates deterministic contract tests for exported modules, React components, hooks, Next app/router files, route handlers, and Node services; emits richer machine-readable `--json` results for agents; writes `.themis/generate-map.json`, `.themis/generate-last.json`, `.themis/generate-handoff.json`, `.themis/generate-backlog.json`, and `.themis/fix-handoff.json`; supports project-level `themis.generate.js` providers, interaction/state adapters for React components and hooks, automatic `--write-hints` scaffolding, targeted regeneration, planning mode, scenario/confidence steering, review/update/clean workflows, strict quality gates, and backlog remediation commands; and fails generated tests with direct regeneration guidance when scanned sources drift.
-- Moved the package line from alpha to beta and defined beta compatibility expectations for CLI, artifacts, and the JS/TS package surface.
+- Promoted Themis to the first stable `0.1.0` release and defined the stable CLI, artifact, and JS/TS package surface as the public contract baseline.
 - Tightened npm/package positioning around Themis as an intent-first unit test framework for AI agents in Node.js and TypeScript.
 - Updated publish-facing docs to consistently frame Themis as an AI verdict engine for human and agent review loops.
 - Added `npm run pack:check` for npm publish payload validation.
@@ -30,6 +38,8 @@ All notable changes to this project are documented in this file.
 - Added config-level `testIgnore` discovery patterns so repos can keep generated output, fixture sandboxes, and other local test noise out of default suite runs deterministically.
 - Added an in-repo VS Code extension scaffold for artifact-driven result viewing, reruns, and HTML report opening.
 - Expanded the VS Code extension scaffold with generated-review navigation for source/test/hint mappings and unresolved generation backlog.
+- Expanded the VS Code extension scaffold with contract review and migration review actions backed by `.themis/contract-diff.json` and `.themis/migration-report.json`.
+- Added contract-capture options (`normalize`, `maskPaths`, `sortArrays`), richer contract diff summaries, migration codemods, showcase docs, release checklists, and CI proof artifacts for benchmark and migration comparisons.
 - Refreshed README, AGENTS, and supporting docs to match the current package scope, JS/TS feature set, artifact contracts, and extension surface.
 
 ## 0.1.0-alpha.1 - 2026-02-13

package/README.md

@@ -1,7 +1,7 @@
 # Themis
 
 <p align="center">
-  <img src="src/assets/themisLogo.png" alt="Themis logo mark" width="42" valign="middle">
+  <img src="src/assets/themisVerdictEngine.png" alt="Themis verdict engine mark" width="42" valign="middle">
   <a href="https://github.com/vitron-ai/themis/actions/workflows/ci.yml">
     <img src="https://img.shields.io/github/actions/workflow/status/vitron-ai/themis/ci.yml?branch=main&style=for-the-badge&label=THEMIS%20VERDICT%20PIPELINE&labelColor=111827&color=16a34a" alt="Themis verdict pipeline status" valign="middle">
   </a>
@@ -32,6 +32,7 @@ It is built to be the best test loop for agent workflows: deterministic reruns,
 - [Publish Readiness](#publish-readiness)
 - [Why Themis](docs/why-themis.md)
 - [API Reference](docs/api.md)
+- [Showcase Comparisons](docs/showcases.md)
 - [Release Policy](docs/release-policy.md)
 - [Publish Guide](docs/publish.md)
 - [Contributing](CONTRIBUTING.md)
@@ -42,6 +43,8 @@ It is built to be the best test loop for agent workflows: deterministic reruns,
 - Best-in-class unit testing for AI agents in Node.js and TypeScript
 - Deterministic execution with fast rerun loops
 - Agent-native JSON and HTML reporting
+- Structured contract workflows instead of opaque snapshot files
+- Incremental migration path from Jest/Vitest without rewriting everything on day one
 - AI verdict engine for human triage and machine automation
 
 ## Modern JS/TS Support
@@ -60,7 +63,7 @@ Themis is built for modern Node.js and TypeScript projects:
 
 ## Visuals
 
-- Real Themis brand mark: [`src/assets/themisLogo.png`](src/assets/themisLogo.png)
+- Real Themis brand mark: [`src/assets/themisVerdictEngine.png`](src/assets/themisVerdictEngine.png)
 - HTML verdict report art: [`src/assets/themisReport.png`](src/assets/themisReport.png)
 - Background art used by the report: [`src/assets/themisBg.png`](src/assets/themisBg.png)
 
@@ -121,6 +124,8 @@ Generated files land under `tests/generated` by default. Each generated test:
 
 Themis also supports per-file generation hints with sidecars like `src/components/Button.themis.json` so humans and agents can provide props, component flows, args, route requests, and route context. When those sidecars do not exist yet, `--write-hints` can scaffold them automatically from the current source analysis.
 
+This is the core alternative to snapshot-driven testing: generated and hand-written tests assert normalized contracts in readable source, so diffs stay reviewable and updates stay intentional.
+
 For repo-wide generation defaults, add `themis.generate.js` or `themis.generate.cjs` at the project root. Providers in that file can match source paths, supply shared props/args/flow plans, register runtime mocks for generated UI scenarios, and wrap generated component renders so generated DOM contracts run inside the same provider shells humans use in app tests. Providers can also declare preset wrapper metadata for router, Next navigation, auth/session shells, React Query, Zustand, and Redux-style app state patterns, including route history/state, query status, auth permissions, and store selector/action metadata.
 
 For CI and agent loops, Themis can also enforce generation quality instead of only writing files. Strict runs emit a structured backlog, fail on unresolved scan debt, and hand back exact remediation commands.
@@ -169,9 +174,17 @@ Migration scaffolds also write:
 
 See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators, and community messaging.
 
+Short version:
+
+- Themis aims to deliver the benefits people reach for in snapshots, without snapshot rot.
+- Prefer explicit, normalized contracts over broad output dumps.
+- Keep changes reviewable through source assertions, machine-readable artifacts, and diff-oriented rerun workflows.
+- See [`docs/showcases.md`](docs/showcases.md) for direct Jest/Vitest comparison examples.
+
 ## Reference Docs
 
 - API reference: [`docs/api.md`](docs/api.md)
+- Migration guide: [`docs/migration.md`](docs/migration.md)
 - Release policy: [`docs/release-policy.md`](docs/release-policy.md)
 - Publish guide: [`docs/publish.md`](docs/publish.md)
 - VS Code extension notes: [`docs/vscode-extension.md`](docs/vscode-extension.md)
@@ -182,6 +195,7 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 - Generate backlog schema: [`docs/schemas/generate-backlog.v1.json`](docs/schemas/generate-backlog.v1.json)
 - Fix handoff schema: [`docs/schemas/fix-handoff.v1.json`](docs/schemas/fix-handoff.v1.json)
 - Failures artifact schema: [`docs/schemas/failures.v1.json`](docs/schemas/failures.v1.json)
+- Contract diff schema: [`docs/schemas/contract-diff.v1.json`](docs/schemas/contract-diff.v1.json)
 - Changelog: [`CHANGELOG.md`](CHANGELOG.md)
 - Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
 - Security: [`SECURITY.md`](SECURITY.md)
@@ -202,6 +216,7 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 - `npx themis generate app --scenario next-route-handler`: focuses generation on Next app router request handlers.
 - `npx themis migrate jest`: scaffolds a Themis config/setup bridge for existing Jest suites.
 - `npx themis migrate jest --rewrite-imports`: rewrites matched Jest/Vitest/Testing Library imports to a local `themis.compat.js` bridge file.
+- `npx themis migrate jest --convert`: applies codemods for common Jest/Vitest matcher/import patterns so suites move closer to native Themis style.
 - `npx themis migrate vitest`: scaffolds the same bridge for Vitest suites.
 - `npx themis generate src --require-confidence high`: enforces a quality bar for all selected generated tests.
 - `npx themis generate src --files src/routes/ping.ts`: targets one or more explicit source files.
@@ -223,6 +238,7 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 - `npx themis test --stability 3`: runs the suite three times and classifies each test as `stable_pass`, `stable_fail`, or `unstable`.
 - `npx themis test --match "intent DSL"`: runs only tests whose full name matches regex.
 - `npx themis test --rerun-failed`: reruns failing tests from `.themis/failed-tests.json`.
+- `npx themis test --update-contracts --match "suite > case"`: accepts reviewed `captureContract(...)` changes for a narrow slice of the suite.
 - `npx themis test --no-memes`: disables meme phase aliases (`cook`, `yeet`, `vibecheck`, `wipe`).
 - `npx themis test --lexicon classic|themis`: rebrands human-readable status labels in `next/spec` reporters.
 - `npm run validate`: runs test, typecheck, and benchmark gate in one command.
@@ -230,6 +246,12 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 - `npm run benchmark:gate`: fails when benchmark performance exceeds the configured threshold.
 - `npm run pack:check`: previews the npm publish payload.
 
+## CI & Release Proof
+
+- Compatibility job runs `npm test` on Node 18 and 20.
+- Release surface job runs `npm run typecheck`, `npm run pack:check`, the HTML + agent reports, verifies `.themis/contract-diff.json`, produces `.themis/benchmark-last.json`/`.themis/migration-proof.json`, and uploads all of the artifacts for later inspection.
+- Perf gate job runs `npm run benchmark:gate` with `BENCH_MAX_AVG_MS=2500` to guard against regressions before publishing.
+
 ## Agent Guide
 
 See [`AGENTS.md`](AGENTS.md) for the AI-agent test authoring contract used in this repository.
@@ -242,7 +264,10 @@ Each run writes artifacts to `.themis/`:
 - `run-history.json`: rolling recent-run history for agent comparison loops.
 - `fix-handoff.json`: source-oriented repair handoff for generated test failures.
 - `migration-report.json`: compatibility inventory and next actions for migrated Jest/Vitest suites.
+- `contract-diff.json`: contract capture drift, updates, and update commands for `captureContract(...)` workflows.
 - `themis.compat.js`: optional local compat bridge for rewritten migration imports.
+- `benchmark-last.json`: latest benchmark comparison payload, including migration proof output.
+- `migration-proof.json`: synthetic migration-conversion proof artifact emitted by `npm run benchmark`.
 - `report.html`: interactive HTML verdict report.
 
 `--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, previous-run comparison data, and a direct pointer to `.themis/fix-handoff.json` so AI agents can jump from generated failures to exact regeneration commands. Fix handoff entries also carry repair strategies, candidate files, and autofix commands for tighter failure-to-fix loops.
@@ -283,7 +308,21 @@ test('captures a stable UI contract', () => {
 });
 ```
 
-Themis intentionally avoids first-party snapshot-file workflows. Prefer direct assertions, generated contract tests, and explicit flow expectations over large opaque snapshots.
+Contract capture for reviewable baselines:
+
+```js
+test('captures a stable response contract', () => {
+  const payload = {
+    status: 'ok',
+    flags: ['fast', 'deterministic']
+  };
+
+  captureContract('status payload', payload);
+  expect(payload.status).toBe('ok');
+});
+```
+
+Themis intentionally avoids first-party snapshot-file workflows. Prefer direct assertions, generated contract tests, and explicit flow expectations over large opaque snapshots. The goal is comparable baseline coverage with better reviewability: normalized contracts, focused assertions, machine-readable artifacts, and intentional updates instead of broad snapshot re-acceptance.
 
 Available globals:
 

package/docs/api.md

@@ -1,6 +1,6 @@
 # Themis API Reference
 
-This document defines the public API surface for Themis `0.1.0-beta.0`.
+This document defines the public API surface for Themis `0.1.0`.
 
 ## CLI
 
@@ -24,6 +24,8 @@ Creates:
 
 Scans a source directory and writes generated Themis unit-layer tests.
 
+Themis uses generation and explicit assertions as a contract-first alternative to snapshot-heavy workflows. The goal is comparable baseline coverage with more reviewable diffs, more intentional updates, and stronger machine-readable artifacts for agents.
+
 Default behavior:
 
 - input directory: `src`
@@ -138,6 +140,8 @@ Project-level provider modules are supported via `themis.generate.js` or `themis
 
 Scaffolds an incremental migration bridge for existing Jest or Vitest suites.
 
+This command is designed for incremental adoption, not forced rewrites. Teams can keep existing suites running under Themis first, then move touched tests toward native Themis contracts and `intent(...)` flows over time.
+
 Behavior:
 
 - writes or updates `themis.config.json`
@@ -146,10 +150,12 @@ Behavior:
 - adds `test:themis` to `package.json` when missing
 - writes `.themis/migration-report.json` with detected compatibility imports and next actions
 - relies on built-in runtime compatibility for `@jest/globals`, `vitest`, and `@testing-library/react`
+- preserves a path to replace snapshot-heavy suites with direct assertions and generated contract tests instead of porting snapshot files as-is
 
 Migration options:
 
 - `--rewrite-imports`: rewrites matched imports from `@jest/globals`, `vitest`, and `@testing-library/react` to the local `themis.compat.js` bridge
+- `--convert`: removes common framework imports and rewrites common Jest/Vitest matcher patterns (`it`, `toStrictEqual`, `toContainEqual`, `toBeCalled*`) into Themis-native forms
 
 ## `themis test` options
 
@@ -163,6 +169,7 @@ Migration options:
 | `--environment node\|jsdom` | string | Override the configured test environment. |
 | `--isolation worker\|in-process` | string | Select worker isolation or a zero-IPC in-process execution mode. |
 | `--cache` | flag | Enable file-level result caching for in-process local loops. |
+| `--update-contracts` | flag | Accept updated `captureContract(...)` baselines for the selected tests. |
 | `-w`, `--watch` | flag | Rerun the selected suite when watched project files change. |
 | `--stability <N>` | positive integer | Run selected tests `N` times and classify stability (`stable_pass`, `stable_fail`, `unstable`). |
 | `--html-output <path>` | string | Output path for `--reporter html` (default: `.themis/report.html`). |
@@ -185,10 +192,18 @@ Execution note:
 
 - `--watch --isolation in-process --cache` is the fastest local rerun mode
 - `--isolation worker` remains the safer mode for CI and global-heavy suites
+- `--watch` is intended for short edit-run-review loops for both humans and AI agents
 
 Snapshot note:
 
-- Themis no longer supports first-party snapshot files or `-u` update flows. Prefer direct assertions and generated contract tests.
+- Themis no longer supports first-party snapshot files or `-u` update flows.
+- Prefer direct assertions, generated contract tests, and explicit flow expectations.
+- The intended replacement is comparable outcome with better reviewability: normalized contracts, readable source assertions, diff-oriented artifacts, and intentional regeneration.
+- `captureContract(name, value)` writes a normalized baseline under `.themis/contracts/`, fails on drift by default, and pairs with `--update-contracts` for explicit acceptance.
+- `captureContract(name, value, options)` also supports:
+  - `normalize(value)`: rewrite volatile payloads before persistence
+  - `maskPaths: string[]`: replace selected JSON-style paths such as `$.requestId`
+  - `sortArrays: true`: sort normalized array values for order-insensitive contracts
 
 ## Exit behavior
 
@@ -211,6 +226,9 @@ Each run writes to `.themis/`:
 - `run-history.json`: rolling recent-run history
 - `fix-handoff.json`: deduped repair artifact for generated test failures (`themis.fix.handoff.v1`)
 - `migration-report.json`: migration inventory for Jest/Vitest bridge scaffolds (`themis.migration.report.v1`)
+- `contract-diff.json`: contract capture drift, updates, and update commands (`themis.contract.diff.v1`)
+- `benchmark-last.json`: latest benchmark comparison payload plus migration proof (`themis.benchmark.result.v1`)
+- `migration-proof.json`: synthetic migration conversion proof emitted by `npm run benchmark` (`themis.migration.proof.v1`)
 
 Formal schemas:
 
@@ -221,6 +239,7 @@ Formal schemas:
 - `docs/schemas/generate-backlog.v1.json`
 - `docs/schemas/fix-handoff.v1.json`
 - `docs/schemas/failures.v1.json`
+- `docs/schemas/contract-diff.v1.json`
 
 Human-facing artifact:
 

package/docs/migration.md

@@ -0,0 +1,167 @@
+# Migrating From Jest And Vitest
+
+Themis is designed for incremental migration. Start by running existing suites under the Themis runtime, then convert touched tests toward native contracts and `intent(...)` flows as you work.
+
+## Fast path
+
+```bash
+npx themis migrate jest
+npx themis migrate jest --rewrite-imports
+npx themis migrate jest --convert
+npx themis test
+```
+
+Use `vitest` instead of `jest` for Vitest suites.
+
+## Migration modes
+
+- `themis migrate <jest|vitest>`: scaffold config, setup, compat bridge, and migration report.
+- `--rewrite-imports`: point framework imports at `themis.compat.js`.
+- `--convert`: remove common Jest/Vitest imports and rewrite common matcher/test patterns into Themis-native forms.
+
+## Before And After
+
+### 1. Runtime bridge first
+
+Jest/Vitest:
+
+```js
+import { describe, test, expect } from '@jest/globals';
+
+describe('math', () => {
+  test('adds', () => {
+    expect(1 + 1).toBe(2);
+  });
+});
+```
+
+Themis after `migrate`:
+
+```js
+describe('math', () => {
+  test('adds', () => {
+    expect(1 + 1).toBe(2);
+  });
+});
+```
+
+The suite keeps running, but Themis owns the runner, artifacts, rerun loop, and agent payloads.
+
+### 2. Matcher codemods
+
+Jest/Vitest:
+
+```js
+import { it, expect } from '@jest/globals';
+
+it('tracks calls', () => {
+  const worker = fn();
+  worker('ok');
+
+  expect({ status: 'ok' }).toStrictEqual({ status: 'ok' });
+  expect([1, 2]).toContainEqual(2);
+  expect(worker).toBeCalledTimes(1);
+});
+```
+
+Themis after `migrate --convert`:
+
+```js
+test('tracks calls', () => {
+  const worker = fn();
+  worker('ok');
+
+  expect({ status: 'ok' }).toEqual({ status: 'ok' });
+  expect([1, 2]).toContain(2);
+  expect(worker).toHaveBeenCalledTimes(1);
+});
+```
+
+### 3. Snapshot replacement
+
+Jest/Vitest snapshot flow:
+
+```js
+test('renders summary', () => {
+  const view = renderSummary();
+  expect(view).toMatchSnapshot();
+});
+```
+
+Themis contract flow:
+
+```js
+test('renders summary', () => {
+  const view = renderSummary();
+
+  captureContract('summary view', {
+    heading: view.heading,
+    counts: view.counts,
+    flags: view.flags
+  });
+
+  expect(view.heading).toBe('Summary');
+});
+```
+
+This keeps the baseline machine-readable and reviewable instead of hiding it in an opaque blob.
+
+### 4. Better drift review
+
+Jest/Vitest:
+
+- large snapshot diffs
+- broad “accept all changes” update flow
+
+Themis:
+
+- field-level diffs in `.themis/contract-diff.json`
+- visible drift/update summaries in CLI and HTML reports
+- explicit acceptance via `npx themis test --update-contracts --match "<regex>"`
+
+### 5. Behavior-first UI coverage
+
+Jest/Vitest often converges on DOM dumps or shallow expectations:
+
+```js
+test('button snapshot', () => {
+  const { container } = render(<Button />);
+  expect(container).toMatchSnapshot();
+});
+```
+
+Themis pushes behavior and contract intent:
+
+```js
+test('button interaction contract', async () => {
+  render(<Button />);
+
+  fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+
+  captureContract('button state', {
+    text: screen.getByRole('button', { name: 'Saved' }).textContent
+  });
+
+  await waitFor(() => {
+    expect(screen.getByText('Saved')).toBeInTheDocument();
+  });
+});
+```
+
+## Showcase Examples
+
+These are the strongest head-to-head examples to use when explaining why Themis is better for AI-agent loops:
+
+1. Snapshot replacement: `captureContract(...)` plus `--update-contracts` gives baseline capture without snapshot churn.
+2. Codemod migration: `themis migrate --convert` moves common Jest/Vitest matcher syntax toward native Themis without a manual rewrite pass.
+3. Agent triage: `--agent`, `.themis/run-diff.json`, `.themis/fix-handoff.json`, and `.themis/contract-diff.json` give machines structured rerun and repair inputs.
+4. Human review: next reporter and HTML report now surface contract drift alongside failures, instead of burying meaning in raw output.
+5. Generated coverage: `themis generate src` adds source-driven contract tests next to migrated suites, so adoption improves coverage instead of merely changing runners.
+
+## Recommended rollout
+
+1. Run `themis migrate <jest|vitest>`.
+2. Add `--rewrite-imports` if you want local explicit compat imports.
+3. Add `--convert` to normalize the easy matcher/import cases immediately.
+4. Replace snapshots with `captureContract(...)` or explicit assertions in files you touch.
+5. Use `themis generate src` to add source-driven coverage in parallel with migrated suites.

package/docs/publish.md

@@ -16,6 +16,8 @@ This guide covers publishing Themis to npm.
 3. Confirm the public messaging still matches the project:
    - best-in-class unit test framework for AI agents in Node.js and TypeScript
    - AI verdict engine for human and agent review loops
+   - contract-first alternative to snapshot-heavy test maintenance
+   - incremental migration path from Jest/Vitest with fast watch-mode rerun loops
 4. Run:
 
 ```bash

package/docs/release-checklist.md

@@ -0,0 +1,28 @@
+# Release Checklist
+
+This checklist tracks the release work for Themis `0.1.0` and future stable milestone cuts.
+
+## Documentation polish
+
+- confirm README, API reference, and VS Code docs clearly describe the stable story
+- publish [`docs/showcases.md`](docs/showcases.md) with migration/comparison examples
+- surface release expectations in [`docs/release-policy.md`](docs/release-policy.md)
+- link to this checklist from the release policy and README so the team knows the remaining steps
+
+## Gates & proof
+
+- `npm test`
+- `npm run typecheck`
+- `npm run benchmark`
+- `npm run benchmark:gate`
+- verify `.themis/benchmark-last.json` and `.themis/migration-proof.json` are up to date
+
+## Release actions
+
+- confirm the release version (current target `0.1.0`)
+- bump `package.json` and `packages/themis-vscode/package.json`
+- update `docs/api.md` version header
+- run `npm pack` / `npm publish --dry-run` if publishing
+- tag `v0.1.0` and push the tag
+- update the changelog/release notes for the stable release
+- announce `0.1.0` with the improved story and benchmarks

package/docs/release-policy.md

@@ -4,17 +4,17 @@ This document defines release expectations for Themis.
 
 ## Current Stage
 
-Current line: `0.1.0-beta.x`
+Current line: `0.1.x`
 
-Beta means:
+Stable means:
 
-- the core CLI, artifact, and JS/TS package shape should be considered mostly stable
-- compatibility remains a deliberate goal across beta builds
-- breaking changes are still possible, but they should be uncommon and called out clearly
+- the core CLI, artifact, and JS/TS package shape are the public contract
+- compatibility remains a deliberate goal across stable patch releases
+- breaking changes require intentional version bumps and migration notes
 
 ## Versioning Model
 
-Themis follows semantic versioning semantics with pre-release tags:
+Themis follows semantic versioning:
 
 - `0.1.0-alpha.N`: unstable early pre-release
 - `0.1.0-beta.N`: pre-release with mostly stable product shape
@@ -22,7 +22,7 @@ Themis follows semantic versioning semantics with pre-release tags:
 - `0.1.x`: backward-compatible fixes and minor enhancements
 - `0.2.0+`: intentional breaking changes with migration notes
 
-## Compatibility Rules During Beta
+## Compatibility Rules During Stable
 
 - CLI flags should remain stable unless a clear product issue requires change.
 - Programmatic API should prefer additive changes over renames or removals.
@@ -32,7 +32,7 @@ Themis follows semantic versioning semantics with pre-release tags:
 ## Deprecation Policy
 
 - New deprecations are documented in `CHANGELOG.md`.
-- Deprecated APIs should keep at least one pre-release cycle before removal when practical.
+- Deprecated APIs should keep at least one stable release cycle before removal when practical.
 - Meme aliases can be disabled any time with `--no-memes`; strict environments should use this flag.
 
 ## Quality Gates
@@ -41,8 +41,11 @@ Before publishing:
 
 - `npm test`
 - `npm run typecheck`
+- `npm run benchmark`
 - `npm run benchmark:gate`
 
+Release prep steps for major milestones are tracked in [`docs/release-checklist.md`](docs/release-checklist.md).
+
 ## Publishing Policy
 
 - Publish target: npm public package `@vitronai/themis`.

package/docs/roadmap.md

@@ -0,0 +1,18 @@
+## Next-phase focus
+
+1. **Provider/flow depth**
+   - Expand `generate` detection to infer React Query usage, router contexts, and persisted store slices so generated tests wrap components/hooks with accurate provider shells.
+   - Surface async DOM flows in `tests/generated/*` with multi-stage user journeys, empty/loading/error states, and configurable timing fixtures so the runner can validate realistic UI transitions instead of static renders.
+   - Add documentation (and optionally VS Code actions) that show how to hook a project-level `themis.generate.js` or `.themis.json` provider configuration for shared auth/session/React Query clients.
+
+2. **Migration helpers**
+   - Improve `themis migrate` to rewrite Jest/Vitest imports to the generated compatibility module, create prompt-ready diff artifacts, and log a migration report.
+   - Build a VS Code pane or CLI summary showing both the original Jest test and the new generated Themis contract, highlighting the migration delta in code and behavior.
+   - Provide a recipe in `docs/migration.md` for teams to adopt Themis incrementally, including a helper to wrap Jest tests inside Themis-generated asserts.
+   - Add a native contract-capture workflow that gives teams snapshot-comparable baseline coverage without reviving snapshot-file maintenance.
+
+3. **Proof/polish**
+   - Document how to run the generator in "plan" mode for React/Next flows, share the artifact URLs, and point to the new `tests/fixtures/react-app` coverage as proof that CI-enforced flows now run cleanly under the real dependency graph.
+   - Consider adding benchmark entries showing the generator/migration loop time compared to Jest baseline.
+
+These steps keep widening the gap versus Jest/Vitest and ensure our agent-and-human workflow stays irresistible.

package/docs/schemas/agent-result.v1.json

@@ -25,7 +25,7 @@
     "artifacts": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["lastRun", "failedTests", "runDiff", "runHistory", "fixHandoff"],
+      "required": ["lastRun", "failedTests", "runDiff", "runHistory", "fixHandoff", "contractDiff"],
       "properties": {
         "lastRun": {
           "type": "string"
@@ -41,6 +41,9 @@
         },
         "fixHandoff": {
           "type": "string"
+        },
+        "contractDiff": {
+          "type": "string"
         }
       }
     },
@@ -50,7 +53,7 @@
     "hints": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["rerunFailed", "targetedRerun", "diffLastRun", "repairGenerated"],
+      "required": ["rerunFailed", "targetedRerun", "diffLastRun", "repairGenerated", "reviewContracts"],
       "properties": {
         "rerunFailed": {
           "type": "string"
@@ -63,6 +66,9 @@
         },
         "repairGenerated": {
           "type": "string"
+        },
+        "reviewContracts": {
+          "type": "string"
         }
       }
     }