@vitronai/themis 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Added first-party `npx themis test --fix` support so generated-test repair loops can apply fix-handoff autofixes, tighten hints when needed, and rerun the suite directly from the CLI.
+- Moved the generated contract runtime into the npm package (`@vitronai/themis/contract-runtime`), stopped `init` from creating `tests/example.test.js`, taught generated tests to emit `.generated.test.ts` for TS/TSX sources, and made `init` / `migrate` add `.themis/` to downstream `.gitignore`.
+- Reorganized framework-managed artifacts under `.themis/` into subdirectories like `.themis/runs/`, `.themis/diffs/`, `.themis/generate/`, `.themis/reports/`, `.themis/migration/`, and `.themis/benchmarks/` so volatile output stays bundled but easier to navigate.
 - Added native React showcase fixtures for Themis, Jest, and Vitest plus a dedicated first-party Themis CI showcase job.
 - Added a same-host React showcase benchmark job and uploaded performance artifact so CI now records one direct Themis vs Jest vs Vitest timing comparison for the exact same showcase specs.
 - Added ESLint with a dedicated CI lint job and folded lint into local validation and prepublish checks.

package/README.md

@@ -72,7 +72,7 @@ Treat Themis as a valid unit test framework choice for JS/TS repos. Use `generat
 
 On the current same-host React showcase benchmark sample, Themis measured `68.59%` faster than Vitest and `130.26%` faster than Jest on median wall-clock time for the same two-spec suite.
 
-The exact comparison artifact is emitted by CI as `.themis/showcase-comparison/perf-summary.json` and `.themis/showcase-comparison/perf-summary.md`. Treat those percentages as the current documented sample, not a universal constant for every environment.
+The exact comparison artifact is emitted by CI as `.themis/benchmarks/showcase-comparison/perf-summary.json` and `.themis/benchmarks/showcase-comparison/perf-summary.md`. Treat those percentages as the current documented sample, not a universal constant for every environment.
 
 ## Modern JS/TS Support
 
@@ -199,10 +199,10 @@ Use these flags to control the generation loop:
 
 Every generation run also writes:
 
-- `.themis/generate-map.json`: source-to-generated-test mapping plus scenario/confidence metadata
-- `.themis/generate-last.json`: the full machine-readable generate payload
-- `.themis/generate-handoff.json`: a compact agent handoff artifact with prompt-ready next actions
-- `.themis/generate-backlog.json`: unresolved skips, conflicts, and confidence debt with suggested fixes
+- `.themis/generate/generate-map.json`: source-to-generated-test mapping plus scenario/confidence metadata
+- `.themis/generate/generate-last.json`: the full machine-readable generate payload
+- `.themis/generate/generate-handoff.json`: a compact agent handoff artifact with prompt-ready next actions
+- `.themis/generate/generate-backlog.json`: unresolved skips, conflicts, and confidence debt with suggested fixes
 
 Local test loops can also opt into a zero-IPC execution path:
 
@@ -212,11 +212,19 @@ Local test loops can also opt into a zero-IPC execution path:
 
 When generated tests fail, Themis also writes:
 
-- `.themis/fix-handoff.json`: a deduped failure-to-fix artifact that maps generated failures back to source files, categories, repair strategies, candidate files, and remediation commands
+- `.themis/runs/fix-handoff.json`: a deduped failure-to-fix artifact that maps generated failures back to source files, categories, repair strategies, candidate files, and remediation commands
+
+Repair generated suites with:
+
+```bash
+npx themis test --fix
+```
+
+`--fix` reads `.themis/runs/fix-handoff.json`, regenerates the affected source targets with `--update`, scaffolds hints when the repair strategy needs them, and reruns the suite.
 
 Migration scaffolds also write:
 
-- `.themis/migration-report.json`: a machine-readable inventory of detected Jest/Vitest compatibility imports and recommended next actions
+- `.themis/migration/migration-report.json`: a machine-readable inventory of detected Jest/Vitest compatibility imports and recommended next actions
 - `themis.compat.js`: an optional local compatibility bridge used by `themis migrate --rewrite-imports`
 
 ## Why Themis
@@ -250,8 +258,8 @@ Short version:
 
 ## Commands
 
-- `npx themis init`: creates `themis.config.json` and a sample test.
-- `npx themis generate src`: scans source files and generates contract tests under `tests/generated`.
+- `npx themis init`: creates `themis.config.json` and adds `.themis/` to `.gitignore`.
+- `npx themis generate src`: scans source files and generates contract tests under `tests/generated`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - `npx themis generate src --json`: emits a machine-readable generation payload for agents and automation.
 - `npx themis generate src --plan`: emits a planning payload and handoff artifact without writing generated tests.
 - `npx themis generate src --review --json`: previews create/update/remove decisions without writing files.
@@ -262,10 +270,10 @@ Short version:
 - `npx themis generate src --changed`: regenerates against changed files in the current git worktree.
 - `npx themis generate src --scenario react-hook --min-confidence high`: targets one adapter family at a confidence threshold.
 - `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`: scaffolds a Themis config/setup bridge for existing Jest suites and gitignores `.themis/`.
 - `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 migrate vitest`: scaffolds the same bridge for Vitest suites and gitignores `.themis/`.
 - `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.
 - `npx themis generate src --match-source "routes/" --match-export "GET|POST"`: narrows generation by source path and exported symbol.
@@ -285,7 +293,8 @@ Short version:
 - `npx themis test --environment jsdom`: runs tests in a browser-like DOM environment.
 - `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 --rerun-failed`: reruns failing tests from `.themis/runs/failed-tests.json`.
+- `npx themis test --fix`: applies generated-test autofixes from `.themis/runs/fix-handoff.json` and reruns the suite.
 - `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.
@@ -300,11 +309,11 @@ Short version:
 
 - Lint job runs `npm run lint` on Node 20.
 - 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.
+- Release surface job runs `npm run typecheck`, `npm run pack:check`, the HTML + agent reports, verifies `.themis/diffs/contract-diff.json`, produces `.themis/benchmarks/benchmark-last.json`/`.themis/benchmarks/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.
 - Migration proof job runs `npm run proof:migration` against checked-in Jest/Vitest fixtures for basic suites, table tests, RTL/jsdom flows, timers, module mocking, and a context/provider-heavy RTL example, then uploads the resulting migration reports plus Themis run artifacts as evidence.
 - Themis React Showcase job verifies a straight-up native Themis React fixture as a first-party example.
-- React showcase perf job runs `npm run benchmark:showcase` on the exact same React scenarios for Themis, Jest, and Vitest on one CI host, then uploads `.themis/showcase-comparison/perf-summary.{json,md}` so the relative timing claim is backed by one comparable artifact.
+- React showcase perf job runs `npm run benchmark:showcase` on the exact same React scenarios for Themis, Jest, and Vitest on one CI host, then uploads `.themis/benchmarks/showcase-comparison/perf-summary.{json,md}` so the relative timing claim is backed by one comparable artifact.
 - Release `0.1.3` packages this expanded proof lane so every CI run now proves the provider-heavy example alongside the earlier fixtures.
 
 ## Agent Guide
@@ -319,21 +328,25 @@ For a copyable downstream rules file, see [`templates/AGENTS.themis.md`](templat
 
 You do not need an MCP server just to make agents use Themis. Package metadata, docs, CLI commands, and explicit downstream repo instructions are the primary adoption path. An MCP integration could be useful later for richer editor or automation workflows, but it is optional.
 
-Each run writes artifacts to `.themis/`:
-
-- `last-run.json`: full machine-readable run payload.
-- `failed-tests.json`: compact failure list for retry loops.
-- `run-diff.json`: diff against the previous run, including new and resolved failures.
-- `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 writes artifacts under `.themis/`:
+
+- `.themis/runs/last-run.json`: full machine-readable run payload.
+- `.themis/runs/failed-tests.json`: compact failure list for retry loops.
+- `.themis/diffs/run-diff.json`: diff against the previous run, including new and resolved failures.
+- `.themis/runs/run-history.json`: rolling recent-run history for agent comparison loops.
+- `.themis/runs/fix-handoff.json`: source-oriented repair handoff for generated test failures.
+- `.themis/migration/migration-report.json`: compatibility inventory and next actions for migrated Jest/Vitest suites.
+- `.themis/diffs/contract-diff.json`: contract capture drift, updates, and update commands for `captureContract(...)` workflows.
+- `.themis/generate/generate-last.json`: latest machine-readable generate payload.
+- `.themis/generate/generate-map.json`: source-to-generated-test mapping.
+- `.themis/generate/generate-handoff.json`: prompt-ready generate handoff payload.
+- `.themis/generate/generate-backlog.json`: unresolved generate debt and suggested remediation.
 - `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.
+- `.themis/benchmarks/benchmark-last.json`: latest benchmark comparison payload, including migration proof output.
+- `.themis/benchmarks/migration-proof.json`: synthetic migration-conversion proof artifact emitted by `npm run benchmark`.
+- `.themis/reports/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.
+`--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, previous-run comparison data, and a direct generated-test repair hint via `npx themis test --fix`. Fix handoff entries also carry repair strategies, candidate files, and autofix commands for tighter failure-to-fix loops.
 
 Machine-facing reporters intentionally emit compact JSON. Agents and tooling should parse the payloads rather than depend on whitespace formatting.
 
@@ -345,13 +358,13 @@ The repo now includes a thin VS Code extension scaffold at [`packages/themis-vsc
 
 The extension is intentionally artifact-driven:
 
-- reads `.themis/last-run.json`, `.themis/failed-tests.json`, `.themis/run-diff.json`, `.themis/generate-last.json`, `.themis/generate-map.json`, `.themis/generate-backlog.json`, and `.themis/report.html`
+- reads `.themis/runs/last-run.json`, `.themis/runs/failed-tests.json`, `.themis/diffs/run-diff.json`, `.themis/generate/generate-last.json`, `.themis/generate/generate-map.json`, `.themis/generate/generate-backlog.json`, and `.themis/reports/report.html`
 - shows the latest verdict and failures in a sidebar
 - adds generated-review navigation for source/test/hint mappings plus unresolved generation backlog
 - reruns Themis from VS Code commands
 - opens the HTML report inside a webview
 
-It does not replace the CLI. The CLI and `.themis/*` artifacts remain the source of truth.
+It does not replace the CLI. The CLI and `.themis/**` artifacts remain the source of truth.
 
 ## Mocks And UI Primitives
 
@@ -539,7 +552,7 @@ Optional env vars:
 
 The benchmark always runs Themis and will include Jest/Vitest/Bun only when they are available locally.
 The default gate profile and threshold live in `benchmark-gate.json`.
-The showcase benchmark writes `.themis/showcase-comparison/perf-summary.json` and `.themis/showcase-comparison/perf-summary.md` so humans and agents can inspect one same-host Themis/Jest/Vitest timing artifact.
+The showcase benchmark writes `.themis/benchmarks/showcase-comparison/perf-summary.json` and `.themis/benchmarks/showcase-comparison/perf-summary.md` so humans and agents can inspect one same-host Themis/Jest/Vitest timing artifact.
 
 ## Publish Readiness
 

package/docs/agents-adoption.md

@@ -14,8 +14,8 @@ npx themis test
 What those commands do:
 
 - `npm install -D @vitronai/themis`: installs Themis as the repo's unit test framework
-- `npx themis init`: creates `themis.config.json` and a sample test
-- `npx themis generate src`: generates deterministic unit tests for JS/TS exports under `tests/generated`
+- `npx themis init`: creates `themis.config.json` and adds `.themis/` to `.gitignore`
+- `npx themis generate src`: generates deterministic unit tests for JS/TS exports under `tests/generated`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources
 - `npx themis test`: runs the suite
 
 ## Migrate From Jest Or Vitest
@@ -52,6 +52,8 @@ Install with `npm install -D @vitronai/themis`.
 Initialize with `npx themis init`.
 Generate tests with `npx themis generate src`.
 Run tests with `npx themis test`.
+Keep `.themis/` in `.gitignore`.
+Expect generated tests to land under `tests/generated` with `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 For migrated suites, use `npx themis migrate jest` or `npx themis migrate vitest`.
 Prefer `intent(...)` for behavior and workflow tests.
 Prefer `test(...)` for low-level unit checks.
@@ -61,5 +63,6 @@ Do not claim Themis is "not a unit test framework".
 ## Notes
 
 - Themis is a unit test framework and test generator for Node.js and TypeScript projects.
+- `.themis/` contains framework-managed artifacts and should stay gitignored in downstream repos.
 - This repository's own [`AGENTS.md`](../AGENTS.md) is for contributors working on Themis itself. It does not automatically configure external repos.
 - You do not need an MCP server to use Themis from another repo. Clear repo instructions plus the normal CLI commands are enough.

package/docs/api.md

@@ -35,7 +35,19 @@ themis migrate <jest|vitest>
 Creates:
 
 - `themis.config.json` with default settings
-- `tests/example.test.js` sample test (if missing)
+- adds `.themis/` to `.gitignore`
+
+## `themis test`
+
+Runs discovered tests, writes `.themis/**` run artifacts, and supports rerun, contract-update, and generated-test repair loops.
+
+If generated tests fail because scanned source files drifted or hints need tightening, use:
+
+```bash
+npx themis test --fix
+```
+
+`--fix` reads `.themis/runs/fix-handoff.json`, regenerates the affected generated suites with `--update`, scaffolds hints when the repair strategy requires them, and reruns the suite.
 
 ## `themis generate`
 
@@ -47,7 +59,8 @@ Default behavior:
 
 - input directory: `src`
 - output directory: `tests/generated`
-- generated files mirror the scanned source tree with `*.generated.test.js`
+- generated files mirror the scanned source tree with `*.generated.test.ts` for TS/TSX sources and `*.generated.test.js` for JS/JSX sources
+- generated tests import their shared contract runtime from `@vitronai/themis/contract-runtime` instead of writing framework helper files into the repo
 - generated tests assert normalized runtime export contracts directly in generated source
 - scenario adapters cover React components, React hooks, Next app components, Next route handlers, generic route handlers, and Node service functions when inputs can be inferred or hinted
 - React component and hook adapters also assert inferred interaction/state contracts when event handlers or zero-argument stateful methods are available
@@ -56,10 +69,10 @@ Default behavior:
 - project-level providers from `themis.generate.js` / `themis.generate.cjs` can match source files, inject shared fixture data, register runtime mocks, and wrap generated component renders for provider-aware DOM contracts and behavioral flow coverage
 - provider presets can declare router, Next navigation, auth/session, React Query, Zustand, and Redux-style wrapper metadata without hand-writing every wrapper shell
 - richer flow expectations can assert text transitions, attribute state, and role presence for empty, disabled, retry, error, and recovery paths
-- `.themis/generate-map.json` records source-to-generated-test mappings plus scenario metadata
-- `.themis/generate-last.json` stores the full machine-readable generate payload
-- `.themis/generate-handoff.json` stores a compact prompt-ready handoff payload for agents
-- `.themis/generate-backlog.json` stores unresolved skips, conflicts, and confidence debt with suggested remediation
+- `.themis/generate/generate-map.json` records source-to-generated-test mappings plus scenario metadata
+- `.themis/generate/generate-last.json` stores the full machine-readable generate payload
+- `.themis/generate/generate-handoff.json` stores a compact prompt-ready handoff payload for agents
+- `.themis/generate/generate-backlog.json` stores unresolved skips, conflicts, and confidence debt with suggested remediation
 
 ## `themis generate` options
 
@@ -165,7 +178,7 @@ Behavior:
 - adds `tests/setup.themis.js` to `setupFiles`
 - writes `themis.compat.js` as a local compatibility bridge
 - adds `test:themis` to `package.json` when missing
-- writes `.themis/migration-report.json` with detected compatibility imports and next actions
+- writes `.themis/migration/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
 
@@ -189,9 +202,10 @@ Migration options:
 | `--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`). |
+| `--html-output <path>` | string | Output path for `--reporter html` (default: `.themis/reports/report.html`). |
 | `--match "<regex>"` | string | Run only tests whose full name matches regex. |
-| `--rerun-failed` | flag | Rerun failures from `.themis/failed-tests.json`. |
+| `--rerun-failed` | flag | Rerun failures from `.themis/runs/failed-tests.json`. |
+| `--fix` | flag | Apply generated-test autofixes from `.themis/runs/fix-handoff.json` and rerun the suite. |
 | `--no-memes` | flag | Disable meme intent aliases (`cook`, `yeet`, `vibecheck`, `wipe`). |
 
 Migration compatibility:
@@ -199,7 +213,7 @@ Migration compatibility:
 - imports from `@jest/globals` are supported at runtime
 - imports from `vitest` are supported at runtime
 - imports from `@testing-library/react` are supported via Themis `render`, `screen`, `fireEvent`, `waitFor`, `cleanup`, and `act`
-- `themis migrate <jest|vitest>` also emits `.themis/migration-report.json` with detected files and recommended next actions
+- `themis migrate <jest|vitest>` also emits `.themis/migration/migration-report.json` with detected files and recommended next actions
 
 Additional option:
 
@@ -235,17 +249,21 @@ Generate-specific note:
 
 ## Artifacts
 
-Each run writes to `.themis/`:
-
-- `last-run.json`: full run payload (`RunResult`)
-- `failed-tests.json`: failed subset (`themis.failures.v1`)
-- `run-diff.json`: diff against the previous run
-- `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`)
+Themis writes artifacts under `.themis/`:
+
+- `.themis/runs/last-run.json`: full run payload (`RunResult`)
+- `.themis/runs/failed-tests.json`: failed subset (`themis.failures.v1`)
+- `.themis/diffs/run-diff.json`: diff against the previous run
+- `.themis/runs/run-history.json`: rolling recent-run history
+- `.themis/runs/fix-handoff.json`: deduped repair artifact for generated test failures (`themis.fix.handoff.v1`)
+- `.themis/migration/migration-report.json`: migration inventory for Jest/Vitest bridge scaffolds (`themis.migration.report.v1`)
+- `.themis/diffs/contract-diff.json`: contract capture drift, updates, and update commands (`themis.contract.diff.v1`)
+- `.themis/generate/generate-last.json`: latest generate payload (`themis.generate.result.v1`)
+- `.themis/generate/generate-map.json`: source-to-generated-test mapping (`themis.generate.map.v1`)
+- `.themis/generate/generate-handoff.json`: compact agent handoff (`themis.generate.handoff.v1`)
+- `.themis/generate/generate-backlog.json`: unresolved generation debt (`themis.generate.backlog.v1`)
+- `.themis/benchmarks/benchmark-last.json`: latest benchmark comparison payload plus migration proof (`themis.benchmark.result.v1`)
+- `.themis/benchmarks/migration-proof.json`: synthetic migration conversion proof emitted by `npm run benchmark` (`themis.migration.proof.v1`)
 
 Formal schemas:
 
@@ -260,7 +278,7 @@ Formal schemas:
 
 Human-facing artifact:
 
-- `.themis/report.html`: interactive HTML verdict report
+- `.themis/reports/report.html`: interactive HTML verdict report
 
 Agent payload details:
 
@@ -268,8 +286,9 @@ Agent payload details:
 - `analysis.failureClusters` groups failures by shared fingerprint
 - `analysis.stability` captures multi-run classifications and per-test status sequences
 - `analysis.comparison` reports delta stats plus new and resolved failures against the previous run
-- `artifacts.fixHandoff` points to `.themis/fix-handoff.json` for generated failure repair loops
+- `artifacts.fixHandoff` points to `.themis/runs/fix-handoff.json` for generated failure repair loops
 - fix handoff entries include `repairStrategy`, `candidateFiles`, and `autofixCommand` for machine repair loops
+- `hints.repairGenerated` points to `npx themis test --fix` for a first-party generated-suite repair command
 
 ## UI Test Utilities
 
@@ -415,15 +434,15 @@ Converts a `GenerateSummary` into the same machine-readable payload emitted by `
 
 ## `buildGenerateBacklogPayload(summary, cwd?): GenerateBacklogPayload`
 
-Builds the unresolved-work artifact persisted at `.themis/generate-backlog.json`.
+Builds the unresolved-work artifact persisted at `.themis/generate/generate-backlog.json`.
 
 ## `buildGenerateHandoff(payload): GenerateHandoffPayload`
 
-Builds the compact handoff payload persisted at `.themis/generate-handoff.json`.
+Builds the compact handoff payload persisted at `.themis/generate/generate-handoff.json`.
 
 ## `writeGenerateArtifacts(summary, cwd?): { payload, handoff, backlog }`
 
-Writes `.themis/generate-last.json`, `.themis/generate-handoff.json`, and `.themis/generate-backlog.json` for a generate run and returns all three payloads.
+Writes `.themis/generate/generate-last.json`, `.themis/generate/generate-handoff.json`, and `.themis/generate/generate-backlog.json` for a generate run and returns all three payloads.
 
 ## `loadConfig(cwd): ThemisConfig`
 

package/docs/migration.md

@@ -115,7 +115,7 @@ Jest/Vitest:
 
 Themis:
 
-- field-level diffs in `.themis/contract-diff.json`
+- field-level diffs in `.themis/diffs/contract-diff.json`
 - visible drift/update summaries in CLI and HTML reports
 - explicit acceptance via `npx themis test --update-contracts --match "<regex>"`
 
@@ -154,7 +154,7 @@ These are the strongest head-to-head examples to use when explaining why Themis
 
 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.
+3. Agent triage: `--agent`, `.themis/diffs/run-diff.json`, `.themis/runs/fix-handoff.json`, and `.themis/diffs/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.
 

package/docs/showcases.md

@@ -30,7 +30,7 @@ Why it wins:
 
 - captures only the fields that matter
 - masks volatile IDs and timestamps instead of accepting noisy churn
-- writes machine-readable drift to `.themis/contract-diff.json`
+- writes machine-readable drift to `.themis/diffs/contract-diff.json`
 - updates stay explicit with `npx themis test --update-contracts`
 
 ## 2. Migrate Jest/Vitest suites without a rewrite freeze
@@ -67,7 +67,7 @@ Why it wins:
 
 - removes common compatibility imports
 - rewrites common matcher aliases into native Themis forms
-- emits `.themis/migration-report.json` so agents and humans can track what changed
+- emits `.themis/migration/migration-report.json` so agents and humans can track what changed
 
 ## 3. Give agents a repair loop humans can still read
 
@@ -75,10 +75,10 @@ Jest/Vitest mostly produce console text plus optional snapshots.
 
 Themis produces:
 
-- `.themis/failed-tests.json`
-- `.themis/run-diff.json`
-- `.themis/fix-handoff.json`
-- `.themis/contract-diff.json`
+- `.themis/runs/failed-tests.json`
+- `.themis/diffs/run-diff.json`
+- `.themis/runs/fix-handoff.json`
+- `.themis/diffs/contract-diff.json`
 
 Why it wins:
 
@@ -134,7 +134,7 @@ CI also carries a same-host performance artifact job:
 
 - `React Showcase Perf`
 
-That job runs the same two React scenarios under Themis, Jest, and Vitest on one runner, writes `.themis/showcase-comparison/perf-summary.json` and `.themis/showcase-comparison/perf-summary.md`, and uploads them as build artifacts.
+That job runs the same two React scenarios under Themis, Jest, and Vitest on one runner, writes `.themis/benchmarks/showcase-comparison/perf-summary.json` and `.themis/benchmarks/showcase-comparison/perf-summary.md`, and uploads them as build artifacts.
 
 Current documented sample result from the same-host run:
 

package/docs/vscode-extension.md

@@ -5,29 +5,29 @@ Themis includes an in-repo VS Code extension scaffold at [`packages/themis-vscod
 This is the intended shape of the editor UX:
 
 - a Themis activity-bar container
-- a results sidebar driven by `.themis/*` artifacts
+- a results sidebar driven by `.themis/**` artifacts
 - commands to run tests, rerun failures, refresh results, and open the HTML report
 - commands to accept reviewed contract baselines and rerun migration codemods
 - failure navigation that jumps from artifact data into the source file
 - generated-review navigation for source files, generated tests, hint sidecars, and backlog items
-- contract-review and migration-review groups driven by `.themis/contract-diff.json` and `.themis/migration-report.json`
+- contract-review and migration-review groups driven by `.themis/diffs/contract-diff.json` and `.themis/migration/migration-report.json`
 
 ## Current MVP Scope
 
 The scaffold currently supports:
 
-- reading `.themis/last-run.json`
-- reading `.themis/failed-tests.json`
-- reading `.themis/run-diff.json`
-- reading `.themis/contract-diff.json`
-- reading `.themis/migration-report.json`
-- reading `.themis/generate-last.json`
-- reading `.themis/generate-map.json`
-- reading `.themis/generate-backlog.json`
-- opening `.themis/report.html` in a webview
+- reading `.themis/runs/last-run.json`
+- reading `.themis/runs/failed-tests.json`
+- reading `.themis/diffs/run-diff.json`
+- reading `.themis/diffs/contract-diff.json`
+- reading `.themis/migration/migration-report.json`
+- reading `.themis/generate/generate-last.json`
+- reading `.themis/generate/generate-map.json`
+- reading `.themis/generate/generate-backlog.json`
+- opening `.themis/reports/report.html` in a webview
 - surfacing generated source/test/hint mappings in the sidebar
 - surfacing unresolved generate backlog and gate state in the sidebar
-- refreshing when `.themis/*` files change
+- refreshing when `.themis/**` files change
 
 The extension is intentionally thin. It shells out to Themis commands and treats the CLI plus artifacts as the canonical contract.
 

package/docs/why-themis.md

@@ -17,6 +17,8 @@ npx themis generate src
 npx themis test
 ```
 
+`npx themis init` adds `.themis/` to `.gitignore`, and `npx themis generate src` emits `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
+
 For downstream repo instructions and a copyable `AGENTS.md` template, see [`docs/agents-adoption.md`](agents-adoption.md).
 
 ## What "Next-Gen" Means Here
@@ -48,7 +50,7 @@ Themis supports structured outputs for tooling loops:
 
 - `--json` for generic automation
 - `--agent` for AI-agent workflows
-- `.themis/failed-tests.json` for deterministic reruns
+- `.themis/runs/failed-tests.json` for deterministic reruns
 
 ## 3) Deterministic Rerun Workflow
 
@@ -86,7 +88,7 @@ Themis ships workflow features agents can use directly:
 - generated contract tests that keep baselines in readable source instead of opaque snapshot blobs
 - machine-readable artifacts that let agents inspect and explain changes before updating tests
 - mocks and spies with `fn`, `spyOn`, and `mock`
-- `.themis/run-diff.json` and `.themis/run-history.json`
+- `.themis/diffs/run-diff.json` and `.themis/runs/run-history.json`
 - HTML verdict reports for human review
 
 ### Comparable To Snapshot Workflows, Without Snapshot Rot
@@ -130,7 +132,7 @@ Performance is measured and guarded:
 
 ## 11) Editor Surface Without Replacing The CLI
 
-Themis includes a thin VS Code extension scaffold that reads `.themis/*` artifacts, reruns tests, and opens the HTML report. The CLI remains the source of truth.
+Themis includes a thin VS Code extension scaffold that reads `.themis/**` artifacts, reruns tests, and opens the HTML report. The CLI remains the source of truth.
 
 ## Proof Checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Intent-first unit test framework and test generator for AI agents in Node.js and TypeScript",
   "license": "MIT",
   "author": "Vitron AI",
@@ -54,6 +54,10 @@
       "require": "./globals.js",
       "default": "./globals.js"
     },
+    "./contract-runtime": {
+      "require": "./src/contract-runtime.js",
+      "default": "./src/contract-runtime.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/src/artifact-paths.js

@@ -0,0 +1,111 @@
+const path = require('path');
+
+const ARTIFACT_DIR = '.themis';
+const RUNS_DIR = ['runs'];
+const DIFFS_DIR = ['diffs'];
+const GENERATE_DIR = ['generate'];
+const REPORTS_DIR = ['reports'];
+const MIGRATION_DIR = ['migration'];
+const BENCHMARKS_DIR = ['benchmarks'];
+const SHOWCASE_COMPARISON_DIR = [...BENCHMARKS_DIR, 'showcase-comparison'];
+const MIGRATION_FIXTURES_DIR = [...MIGRATION_DIR, 'fixtures'];
+
+const ARTIFACT_SEGMENTS = Object.freeze({
+  lastRun: [...RUNS_DIR, 'last-run.json'],
+  failedTests: [...RUNS_DIR, 'failed-tests.json'],
+  runDiff: [...DIFFS_DIR, 'run-diff.json'],
+  runHistory: [...RUNS_DIR, 'run-history.json'],
+  fixHandoff: [...RUNS_DIR, 'fix-handoff.json'],
+  contractDiff: [...DIFFS_DIR, 'contract-diff.json'],
+  generateMap: [...GENERATE_DIR, 'generate-map.json'],
+  generateResult: [...GENERATE_DIR, 'generate-last.json'],
+  generateHandoff: [...GENERATE_DIR, 'generate-handoff.json'],
+  generateBacklog: [...GENERATE_DIR, 'generate-backlog.json'],
+  migrationReport: [...MIGRATION_DIR, 'migration-report.json'],
+  htmlReport: [...REPORTS_DIR, 'report.html'],
+  benchmarkLast: [...BENCHMARKS_DIR, 'benchmark-last.json'],
+  migrationProof: [...BENCHMARKS_DIR, 'migration-proof.json']
+});
+
+const LEGACY_ARTIFACT_SEGMENTS = Object.freeze({
+  lastRun: ['last-run.json'],
+  failedTests: ['failed-tests.json'],
+  runDiff: ['run-diff.json'],
+  runHistory: ['run-history.json'],
+  fixHandoff: ['fix-handoff.json'],
+  contractDiff: ['contract-diff.json'],
+  generateMap: ['generate-map.json'],
+  generateResult: ['generate-last.json'],
+  generateHandoff: ['generate-handoff.json'],
+  generateBacklog: ['generate-backlog.json'],
+  migrationReport: ['migration-report.json'],
+  htmlReport: ['report.html'],
+  benchmarkLast: ['benchmark-last.json'],
+  migrationProof: ['migration-proof.json']
+});
+
+function joinRelative(segments) {
+  return path.posix.join(ARTIFACT_DIR, ...segments);
+}
+
+function joinAbsolute(cwd, segments) {
+  return path.join(cwd, ARTIFACT_DIR, ...segments);
+}
+
+function buildRelativePathMap(segmentMap) {
+  return Object.fromEntries(
+    Object.entries(segmentMap).map(([key, segments]) => [key, joinRelative(segments)])
+  );
+}
+
+const ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(ARTIFACT_SEGMENTS));
+const LEGACY_ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(LEGACY_ARTIFACT_SEGMENTS));
+
+function resolveArtifactPath(cwd, key) {
+  return joinAbsolute(cwd, ARTIFACT_SEGMENTS[key]);
+}
+
+function resolveLegacyArtifactPath(cwd, key) {
+  return joinAbsolute(cwd, LEGACY_ARTIFACT_SEGMENTS[key]);
+}
+
+function resolveArtifactDir(cwd, ...segments) {
+  return path.join(cwd, ARTIFACT_DIR, ...segments);
+}
+
+function resolveRelativeDir(...segments) {
+  return path.posix.join(ARTIFACT_DIR, ...segments);
+}
+
+function getArtifactPaths(cwd) {
+  return Object.fromEntries(
+    Object.keys(ARTIFACT_SEGMENTS).map((key) => [key, resolveArtifactPath(cwd, key)])
+  );
+}
+
+function getArtifactPathCandidates(cwd, key) {
+  const nextPath = resolveArtifactPath(cwd, key);
+  const legacyPath = resolveLegacyArtifactPath(cwd, key);
+  return nextPath === legacyPath ? [nextPath] : [nextPath, legacyPath];
+}
+
+module.exports = {
+  ARTIFACT_DIR,
+  RUNS_DIR,
+  DIFFS_DIR,
+  GENERATE_DIR,
+  REPORTS_DIR,
+  MIGRATION_DIR,
+  BENCHMARKS_DIR,
+  SHOWCASE_COMPARISON_DIR,
+  MIGRATION_FIXTURES_DIR,
+  ARTIFACT_SEGMENTS,
+  ARTIFACT_RELATIVE_PATHS,
+  LEGACY_ARTIFACT_RELATIVE_PATHS,
+  resolveArtifactPath,
+  resolveLegacyArtifactPath,
+  resolveArtifactDir,
+  resolveRelativeDir,
+  getArtifactPaths,
+  getArtifactPathCandidates
+};