@stsepelin/checktrail 0.1.0-alpha.1

package/docs/JAVA.md

@@ -0,0 +1,79 @@
+# Java compilation
+
+`jvm.javac` compiles all inventoried `.java` files in a Maven/Gradle-discovered
+project as one classpath compilation. It requires a prepared full Temurin JDK
+25.0.4+7 and an explicit project-root `checktrail.java.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "release": 21,
+  "warningsAsErrors": true,
+  "classPath": []
+}
+```
+
+The supported release range is 8–25. The compiler uses UTF-8, all lint warnings,
+disabled annotation processing and no implicit source compilation. No Maven,
+Gradle, wrapper, dependency resolver or application test is run. Project trust
+is still required. The source and JAR parsers are native tools with the process
+user's privileges; this is not a sandbox.
+
+Dependencies are optional explicit `{ "path": "…jar", "sha256": "…" }` entries.
+Paths resolve from the project and must stay inside the operator root without
+symlink traversal. Hashes cover exact file bytes and are verified during planning,
+before compilation and afterwards. Prepared JARs may live in the excluded
+`.checktrail/` directory. They are limited to 128 entries, 32 MiB per JAR and
+128 MiB total. Duplicate paths, checksum mismatches, manifest `Class-Path`
+attributes and source-bearing JARs cannot produce a pass. Hashes establish byte
+identity, not publisher trust or a complete dependency provenance audit.
+
+Compiler options cannot be supplied through this configuration. `CLASSPATH`,
+`JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` and `_JAVA_OPTIONS` are protected and
+removed before invoking Java; PATH is fixed during planning. The owned compiler
+helper runs in a fresh temporary directory. Its file manager discards generated
+class bytes with a 32 MiB limit, so it writes no class files into the project.
+Native output is bounded to 1 MiB, diagnostics to 2,000 entries, the JVM heap to
+256 MiB and the prepared invocation to 100 KiB. Shared engine time and process
+group limits also apply; the heap bound is not a total process-memory bound.
+
+## Evidence and scope
+
+Structured diagnostics retain compiler codes, severity, messages and inventoried
+source locations. Native task events must account for each source parsed exactly
+once and every declared top-level type analyzed. Empty files and package metadata
+are valid near misses. Exactly one completed compilation event and no extra
+unparsed compiler output are required. Errors fail the check with incomplete
+findings; malformed or missing evidence cannot pass. Warnings remain visible and
+`warningsAsErrors` selects whether the compiler rejects them.
+
+The implementation uses the JDK [JavaCompiler API](https://docs.oracle.com/en/java/javase/25/docs/api/java.compiler/javax/tools/JavaCompiler.html)
+and [completed task events](https://docs.oracle.com/en/java/javase/25/docs/api/jdk.compiler/com/sun/source/util/TaskListener.html).
+The evidence establishes compilation under the declared settings. It does not
+establish that these settings equal a Maven/Gradle build, that omitted generated
+code is current, or that runtime behavior, packaging or tests work.
+
+Mixed Kotlin/Scala source, application `.kts` scripts and `module-info.java` are
+unavailable in this profile. Gradle build/settings `.kts` manifests are permitted
+as inert discovery files. JPMS, multi-module compilation, annotation processing,
+generated-source preparation, build plugins, framework semantics and JVM test
+runners remain separate work. Excluded source is not automatically discovered by
+the compiler; projects needing it must prepare an inventoried source or a pinned
+compiled dependency.
+
+## Reproduce native verification
+
+```sh
+npm run build
+docker build --file scripts/java-tools.Dockerfile --tag checktrail-java-test:25.0.4 scripts
+node scripts/verify-java-container.mjs
+```
+
+The helper requires the prepared image, verifies the native compiler, then runs
+synthetic broken/fixed/near-miss cases with the network disabled. It also installs
+a fresh package offline and exercises its library, CLI and MCP against the public
+Java example. The host npm cache must contain the locked production dependencies.
+The Dockerfile pins the multi-platform base image manifests. Local evidence is
+arm64 Linux; the separate hosted amd64 job passed at `52ba415` (see `NATIVE-CI.md`).
+Host macOS without a JDK
+reports the native cases as skipped, not verified.

package/docs/JEST.md

@@ -0,0 +1,36 @@
+# Jest validation
+
+Select `javascript.jest` explicitly in `checktrail.json`. Install Jest in the
+project or an ancestor `node_modules` directory inside the configured root.
+Planning only reads files; operator trust is required before loading Jest or
+project configuration. No package installation is attempted.
+
+The adapter uses installed Jest's `runCLI` API with the standard `jest-runner`
+and `jest-circus/runner`. It passes inventoried `.test`/`.spec` JS/TS files and
+JS/TS files under `__tests__` by exact path. Native configuration still controls
+matching and transformation; excluded planned files make the result incomplete.
+Custom runners, multi-project duplicate execution, and other filename conventions
+are outside the verified contract. TypeScript and ESM fixtures require their own
+configured loader/transform support; current native fixtures exercise CommonJS.
+
+Execution is serial and non-watching, with CI mode and snapshot updates disabled.
+Collection-only, list-only, changed-only and failed-only execution are disabled.
+Result processors are disabled so evidence comes from the native result, before
+user postprocessing. Coverage configuration remains active. Cache reuse is
+disabled; Jest and trusted project code may still create runtime cache files.
+This is not a sandbox or a guarantee that project code will not modify files.
+
+Evidence reconciles each file's assertion counters with aggregate counters and
+the exact planned file set. Interrupted, malformed, duplicate, missing and
+collection-only results cannot pass. Failures and import errors remain failures.
+There must be at least one passing assertion. **Any pending test makes an otherwise
+successful run incomplete**, including an intentional skip: Jest does not
+distinguish skipped assertions from assertions omitted by `.only` in this result.
+A `.only` that omits no assertions is not independently detected. Todo assertions
+are counted as skipped; they do not supply passing evidence.
+
+The native integration is verified with Jest 30.5.2. Compatibility with other
+versions requires native fixture runs; package presence alone does not establish
+support. See the official [Jest CLI documentation](https://jestjs.io/docs/cli)
+for collection and execution options and [configuration reference](https://jestjs.io/docs/configuration)
+for runners and transforms.

package/docs/JUNIT.md

@@ -0,0 +1,31 @@
+# JUnit report import
+
+Import an existing report through the public `importJUnit(xml)` library function
+or the CLI:
+
+```sh
+node dist/src/cli.js import-junit --root /path/to/project --input results.xml
+```
+
+The result is versioned JSON with `provenance: "imported-report"`. Its outcome
+describes the supplied report, not the current repository. Importing cannot
+establish source identity, execution time, freshness, scope coverage or whether
+the producer ran at all. Imported evidence does not change a validation result.
+Default CLI output omits case names and file paths; `--detailed` includes them.
+The input path must be relative and remain within the configured root.
+
+The supported XML shape is `testsuite` or nested `testsuites`/`testsuite` elements
+with concrete `testcase` entries. Suite test counts are required and aggregate
+failure/error/skip counters are reconciled when present. Counts are derived from
+leaf cases without double-counting parent suites. Duplicate case identities,
+conflicting states, unknown result elements, malformed XML, empty/all-skipped
+reports and inconsistent counters cannot pass. Failure/error entries fail.
+
+DOCTYPE/entity declarations are rejected. No external entities or resources are
+loaded. Input is limited to 8 MiB, nesting to 32 suites and cases to 100,000.
+Built-in XML escapes are decoded. Unrecognized dialects such as custom flaky-test
+elements remain incomplete until independently supported and tested.
+
+The [PHPUnit adapter](PHPUNIT.md) uses the same parser with additional requirements:
+the report must come from the bounded live process, account for every planned
+file and contain positive native assertion evidence.

package/docs/LANGUAGES.md

@@ -0,0 +1,113 @@
+# Language and ecosystem roadmap
+
+Capability levels are discovery, planning, execution, structured evidence,
+semantic rules, and integration validation. None implies the next. This file's
+initial scope column describes the experimental implementation. Node, Python,
+Go, TypeScript, ESLint, Vitest, Jest and vue-tsc execution have been exercised locally. PHP syntax
+has been verified separately in an isolated official Linux container. Tool versions and remaining gaps are tracked in `STATUS.md`.
+
+| Family                        | Project boundaries                                                      | Initial scope                                                                                                                                        | Subsequent native integrations                      | Important constraints                                                                                                   |
+| ----------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| JavaScript / TypeScript       | package.json                                                            | Discovery; Node/Vitest/Jest/Playwright tests; explicit local tsc/vue-tsc, solution references, ESLint and opt-in Vue Router/Nuxt SSR route contracts | framework scope profiles                            | ESLint JavaScript is exercised; parser/processor combinations need their own verification; TS tests need a loader/build |
+| Python                        | pyproject.toml, setup.py, requirements.txt                              | Discovery; unittest/pytest, Ruff/mypy and opt-in FastAPI/Django route inventories                                                                    | Pyright                                             | Never import setup.py for discovery; virtual environments, namespace packages and plugins matter                        |
+| Go                            | go.mod                                                                  | Discovery; gofmt, vet, tests, explicit race/Staticcheck/golangci-lint profiles; native scope accounting                                              | broader golangci-lint settings                      | Module/workspace boundaries, build tags, cgo, platform constraints and test caching                                     |
+| PHP                           | composer.json                                                           | Discovery; syntax, PHPStan, PHPUnit, Pest, Pint and opt-in Laravel assembly capture                                                                  | Larastan integration, PHP-CS-Fixer                  | Syntax is not type/test validation; runtime extensions, generated proxies and framework bootstrapping matter            |
+| Rust                          | Cargo.toml                                                              | Single-package Cargo check with locked offline dependencies and dep-info scope                                                                       | cargo fmt, clippy, test                             | Build scripts and proc macros execute code; feature/target matrix; offline dependencies                                 |
+| Java / Kotlin / Scala         | pom.xml, build.gradle, build.gradle.kts                                 | Explicit Java classpath compilation with native parse/analysis evidence; Kotlin/Scala discovery only                                                 | Maven/Gradle test, Checkstyle, SpotBugs, detekt     | Multi-module builds, wrappers, JVM versions, generated sources and plugins                                              |
+| C# / F# / Visual Basic / .NET | *.csproj, *.fsproj, *.vbproj, *.sln, *.slnx                             | Explicit C# compilation with native syntax/semantic evidence; F#/VB discovery only                                                                   | dotnet format, build, test                          | Restore policy, analyzers, target frameworks, generated code and TRX parsing                                            |
+| Ruby                          | Gemfile, *.gemspec                                                      | MRI syntax checking of Ruby source and DSL manifests                                                                                                 | RuboCop, RSpec, Minitest                            | Bundler versions and runtime config execute code                                                                        |
+| Swift                         | Package.swift                                                           | Native Swift grammar checking without manifest evaluation                                                                                            | swift build/test, SwiftLint                         | Manifest evaluation executes code; platform/SDK requirements                                                            |
+| C / C++                       | CMakeLists.txt, meson.build, compile_commands.json                      | Prepared Clang front-end checks with native source/header accounting                                                                                 | clang-format, clang-tidy, compiler checks, CTest    | Compilation database, toolchain and build configuration are required                                                    |
+| Infrastructure                | .github/workflows/*.yml or *.yaml, *.tf, Chart.yaml, kustomization.yaml | Static GitHub Actions analysis with explicit local inputs and native per-file evidence                                                               | terraform validate, helm lint/template, kubeconform | No workflow execution; remote actions are not downloaded; YAML aliases and merge keys require another profile           |
+
+Nuxt, Vue Router, FastAPI, Django and Laravel profiles have separately pinned framework compatibility gates
+and capture only their documented native assembly projections; see `FASTAPI.md`,
+`DJANGO.md`, `LARAVEL.md`, `VUE-ROUTER.md` and `NUXT.md`.
+
+Pint's macOS hosted check exposed a non-seekable cache-file failure. The adapter
+now uses a fresh regular file with runner-owned cleanup; the corrected macOS
+profile passed at `52ba415`. See `PINT.md` and `NATIVE-CI.md`.
+
+## Adapter contract
+
+Every adapter declares stable ID/version, detection markers, capabilities,
+supported OS/tool versions, check IDs, prerequisites, working-directory semantics,
+scope, timeout, whether execution is required, and evidence parser behavior.
+Keep language identity separate from framework packs and individual tool adapters.
+
+Every result accounts for failure, missing executable, invalid config, zero tests,
+all-skipped tests, partial output, timeout, cancellation and unexpected format.
+Use native JSON/XML where available. Human-readable output parsing needs pinned
+fixtures and a conservative fallback to inconclusive.
+
+Native tools are provided by the consumer's environment. Do not download a tool
+because a manifest mentions it. Use local package binaries and lockfile-compatible
+versions. Do not equate an executable's presence with adapter compatibility.
+
+## External implementations
+
+Operator-registered Node, Python, PHP and compiled native bundles share the
+[external adapter protocol](EXTERNAL-ADAPTERS.md). This permits checks written in
+different languages without changing the engine. It does not automatically add
+semantic support for the languages they inspect. Each adapter needs its own native
+regression cases, tool identities, platform profile and license provenance.
+
+## Monorepos and polyglot repositories
+
+Discover nested manifests without entering dependency caches or following symlinks.
+Keep relative project roots and assign files to the closest detected project root;
+avoid running a parent check over every child without reporting overlap.
+One directory can carry multiple ecosystems. Language detection must preserve all
+matches rather than selecting whichever marker happened to be visited first.
+
+Workspace dependencies are explicit policy inputs; completeness is a maintainer
+assertion, not inferred import analysis. Optional Git selection expands changed
+projects to their transitive consumers and retains whole-project checks. See
+`WORKSPACES.md`. This selection does not itself establish built-package or
+producer/consumer contract validation.
+
+## Promotion requirements
+
+An adapter is experimental until it has real toolchain integration tests on its
+advertised platforms, structured evidence tests, broken/fixed/near-miss fixtures,
+scope and exclusion documentation, and a maintainer able to reproduce failures.
+Framework-specific support is promoted separately. Recognition of a manifest
+is always reported as discovery, never as completed validation.
+
+The optional [review exchange](REVIEW-EXCHANGE.md) accepts selected inventoried
+UTF-8 source in any language. Its bounds, freshness and quotation checks do not
+add native analysis coverage or promote an ecosystem capability.
+
+Optional [task storage](TASK-STORAGE.md) retains projected engine reports from any
+adapter without adding language coverage. Its native storage profile is verified
+on macOS/Node 26.8.1 and Linux/Node 22.23.2; it is not MCP Tasks support.
+
+The [durable library worker](VALIDATION-TASKS.md) invokes the same adapter registry.
+Worker-specific lifecycle evidence currently uses native Node fixtures on those
+storage platforms; other adapters retain their existing separately verified profiles.
+
+The [external ESLint integration evaluation](EXTERNAL-EVALUATION.md) adds
+independently authored diagnostic cases for three JavaScript rule profiles. Its
+macOS/Linux results do not extend coverage to other parsers, plugins or languages.
+
+The [application-client checks](CLIENTS.md) exercise native Node evidence through
+Codex and tool discovery through Claude Code. They do not independently verify
+every adapter through either client.
+
+Exported Vue/Nuxt profile schemas use standard JSON Schema patterns for route
+prefixes and probe restrictions. Strict schema compilation and boundary fixtures
+verify those constraints separately from the native framework cases.
+
+The [external Ruff diagnostic cohort](EXTERNAL-RUFF-EVALUATION.md) adds native
+macOS/Linux comparisons for the selected Python rule families. Mixed files do not
+provide an independent clean-case denominator; the measurements verify diagnostic
+preservation by the wrapper.
+
+Ruby and Swift have dedicated CI definitions that require their named native
+regressions to pass. Their local execution is recorded in `RUBY.md` and `SWIFT.md`;
+both hosted jobs passed at `52ba415` (see `NATIVE-CI.md`). Other optional tests in the general suite can still
+skip, so its aggregate pass count is not evidence for every native profile.
+
+The prepared CI language profiles and native container helpers require exact
+regression names through `NATIVE-CI.md`. Their required results are separate from
+the optional skips allowed by a developer's general test suite.

package/docs/LARAVEL.md

@@ -0,0 +1,111 @@
+# Laravel runtime assembly profile
+
+`php.laravel-runtime` captures an explicitly selected Laravel testing assembly.
+A passed capture means its five declared projections were collected successfully.
+Use `compare-runtime` to detect changes against a reviewed inventory; capture alone
+does not decide whether a route, permission, schedule or binding is correct.
+
+The native fixture uses Laravel 13.32.0, PHP 8.5.6 and Node 22.23.2 on Linux.
+Other Laravel versions are rejected until their internal API contract is verified.
+The development tool installation is pinned in `scripts/laravel-tools/composer.lock`;
+the distributed package does not include Laravel or install it for consumers.
+
+Select the check in `checktrail.json`, and add `checktrail.laravel.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "assembly": "catalog-test-application",
+  "environment": "testing"
+}
+```
+
+The project needs inventoried `bootstrap/app.php` and a local `vendor/autoload.php`
+within the operator root. Planning validates paths and configuration without
+loading either. Execution uses the normal CLI/MCP operator trust gate.
+
+## Bootstrap and collection
+
+The collector loads the application, constructs its HTTP kernel, bootstraps the
+console kernel, initializes Artisan's command inventory, and resolves the
+scheduler. Artisan initialization is necessary for `withSchedule()` callbacks.
+It does not dispatch HTTP requests, run command handlers, invoke event listeners,
+evaluate schedule filters, or execute scheduled jobs. Bootstrap, command and
+controller constructors, service providers and Composer autoload files still run
+project code and can perform their own I/O. This is not a sandbox.
+
+The profile fixes `APP_ENV=testing` and `APP_DEBUG=false`, uses a fresh temporary
+directory for Laravel's configuration, route, event, package and service caches,
+and points Laravel's dotenv loader at that empty directory. Existing project
+dotenv files and compiled caches are not consumed by the collector's bootstrap.
+Operator-permitted environment variables still reach project code. Bootstrap that
+has already run, a different application base path, altered cache paths, or a
+non-testing resolved environment produces an error. Temporary cache files are
+removed on normal PHP shutdown; forced process termination can leave temporary
+files for the host's temporary-directory cleanup.
+
+| Collection | Recorded projection                                                                                                                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Routes     | Served domain/method/URI entries, name, handler identity, native expanded and sorted middleware, constraint/default hashes. Includes framework and package routes.                                            |
+| Middleware | HTTP kernel global stack, priority, groups and aliases, preserving stack order.                                                                                                                               |
+| Listeners  | Exact-event and wildcard registrations, callable identity, order and multiplicity.                                                                                                                            |
+| Schedules  | Command/callback identity, cron expression, repeat interval, timezone, environments, user, overlap/server/background/maintenance flags, output settings, callback identities, parameter and attribute hashes. |
+| Bindings   | Explicit global factories with shared/scoped flags, aliases, contextual bindings, and currently resolved instance classes or scalar hashes.                                                                   |
+
+Class factories wrapped by Laravel's container retain the actual concrete class
+identity. Generic closures retain relative source location and a hash of their
+source lines. Listener wildcard maps and scoped binding lists use reflection
+against the pinned framework version. Collection failures retain partial evidence
+and make the check incomplete. Empty served routes are incomplete; empty listeners
+or schedules can be legitimate. Collection entries, closure-source reads, output,
+execution time and source freshness are bounded by the collector and shared engine.
+
+## Boundaries
+
+This is a CLI testing assembly after eager deferred-provider loading and native
+introspection. It is not an HTTP request, queue worker, Octane or production
+assembly. Constructors resolved during inspection can affect the final container
+inventory. Collect before/after under equivalent runtime and environment settings.
+
+The projection does not serialize object state or closure captures, execute
+factories, infer automatic type bindings, or inventory container extenders, tags,
+method bindings and resolution hooks. It does not evaluate authorization, model
+relations, response schemas, job behavior or schedule eligibility. Callable identity
+is not a semantic proof of behavior. Instance state changes and closure-captured
+value changes can therefore leave the projection unchanged. Hashes of scalar
+configuration are not a secrecy guarantee.
+
+Laravel can replace a route registration under an existing method/domain/URI key;
+this collector records the final served collection, not discarded declarations.
+It does not classify duplicate listeners as bugs: inventory comparison preserves
+their multiplicity for review. Equivalent route languages and overlapping match
+patterns are not normalized. Custom router, route, event dispatcher, scheduler or
+scheduled-event classes are unsupported. Unsupported registration data or closure
+sources outside the project/local vendor directory also prevent a complete capture.
+
+Detailed reports include the `runtime` object and can contain application names,
+paths, schedule commands and callable identities. Summary reports omit it. Save
+the runtime objects to compare with the shared CLI/library/MCP runtime comparator;
+imported comparisons do not independently establish freshness of the current tree.
+
+## Reproduce native evidence
+
+Prepare the development-only locked Composer installation in
+`.checktrail/laravel-tools`, build the project, then run
+`node scripts/verify-laravel-container.mjs`. It uses installed Composer/PHP and
+Node images, reports their digests, disables container networking and creates
+synthetic fixture copies inside the container. The helper does not pull images.
+Hosted CI preparation is defined but has not been run remotely.
+
+The public fixture is `examples/frameworks/laravel`. Its tests inspect framework
+storage routes as well as application routes, distinguish middleware alias near
+misses, retain wildcard listeners and concrete binding classes, and compare
+changed/fixed listeners, schedules, bindings and route middleware. Separate cases
+exercise stale caches, dotenv exclusion, an actually empty native route collection,
+custom dispatchers and bootstrap errors. Tests assert the relevant failure reason
+or incomplete collection, rather than accepting any nonzero exit.
+
+References: [Laravel routing](https://laravel.com/docs/13.x/routing),
+[scheduling](https://laravel.com/docs/13.x/scheduling),
+[container bindings](https://laravel.com/docs/13.x/container). The pinned installed
+framework source and native fixtures determine this adapter's exact compatibility.

package/docs/MCP-COMPATIBILITY.md

@@ -0,0 +1,68 @@
+# MCP compatibility
+
+The server runs locally over stdio using the official TypeScript SDK. The tested
+current protocol is `2026-07-28`. Local operation is a deployment choice, not a
+separately named MCP standard. No account, HTTP listener, remote service or LLM
+provider is required.
+
+## Application clients
+
+Fresh offline package checks with Claude Code and Codex passed their documented
+legacy negotiation profiles. Claude Code health/tool discovery and Codex direct
+app-server tool calls are different coverage levels; see [CLIENTS.md](CLIENTS.md)
+for versions, the corrected schema warning, reproduction and recorded evidence.
+
+## Execution lifecycle
+
+`validation_run` executes asynchronously while its tool call remains pending.
+Other inspection calls remain responsive. A second validation is rejected while
+one is active. Request cancellation terminates the validation process group;
+stdin EOF, SIGINT and SIGTERM close the server connection and cancel active work.
+Mutation experiments share the validation execution slot and cancellation path;
+read-only guidance and planning remain responsive. Mutation results are advisory
+and returned directly, without a retained report ID. Reports from validation are
+kept in memory and disappear on restart. There is no durable job
+handle or restart recovery in the MCP server yet. A separate library-only
+[task store](TASK-STORAGE.md) now provides bounded persistence and process-crash
+recovery. Its [library worker](VALIDATION-TASKS.md) integrates execution and
+parent-disconnect cleanup; MCP protocol integration remains pending.
+
+Lifecycle integration tests exercise real child processes. They reproduced
+orphaned workers on EOF and signals before the shutdown handler was added. They
+also reproduced SDK 2.0.0 ignoring numeric request ID `0` when cancelling. The
+application now handles validation cancellation through the public notification
+registration API, using exact request-ID equality and the request's connection
+abort signal. String `"0"` must not cancel numeric `0`.
+
+## Standard Tasks extension: not implemented
+
+The current optional Tasks extension is `io.modelcontextprotocol/tasks`. It adds
+negotiated task results, polling, cancellation and durable handles. An asynchronous
+JavaScript function and an in-memory report ID do not implement that extension.
+The server does not advertise Tasks support.
+
+SDK 2.0.0 currently blocks modern `tasks/get` and `tasks/cancel` before registered
+extension handlers run. This was reproduced locally; `tasks/update` reaches its
+handler in the same probe. Upstream tracks the method-registry collision in
+[typescript-sdk#2598](https://github.com/modelcontextprotocol/typescript-sdk/issues/2598).
+
+Run `npm run probe:mcp-tasks` from the source checkout to repeat the routing probe. Exit `2` means one or
+more handlers were unreachable; exit `0` means routing works. A routing success
+does not establish Tasks conformance. The probe is separate from the ordinary
+check suite because this optional capability is not currently shipped.
+
+Before advertising Tasks, implement and verify:
+
+1. Negotiated extension capabilities and ordinary-call fallback for older clients.
+2. Connect the implemented local worker/store to the MCP execution slot. Native
+   persistence, cancellation, parent-disconnect cleanup and reopening are verified
+   independently; worker lifecycle and wire behavior must still be tested together.
+3. Standard task creation, get, update and cancellation wire contracts. Store the
+   handle before returning it; retain completed tool errors as completed results.
+4. Cancellation races, shutdown, reconnect, restart, expiry, missing IDs and
+   concurrent requests against a compatible client and SDK.
+5. Summary/detail projections that preserve the operator's privacy choice for
+   both task metadata and retained results.
+
+References: [core specification](https://modelcontextprotocol.io/specification/2026-07-28),
+[Tasks specification](https://tasks.extensions.modelcontextprotocol.io/specification/2026-07-28/tasks).

package/docs/MUTATIONS.md

@@ -0,0 +1,93 @@
+# Targeted mutation experiments
+
+`mutate`, `runMutations()` and MCP `mutation_experiment` execute an explicitly
+authored replacement recipe in temporary copies. They use the shared validation
+engine, require operator execution trust and return a separate advisory report.
+They never change a validation report's outcome or edit the original source.
+Executed project code retains the user's privileges and can access outside the
+copy: this is not a sandbox. Do not run untrusted code through this feature.
+
+```sh
+node dist/src/cli.js mutate --root examples/mutations --input mutations.json --trust-project --detailed
+```
+
+The public example subtracts instead of adding (caught by its assertion) and
+swaps addition operands (survives its integer test). A survivor is an observation,
+not automatically a missing test or a defect: equivalent mutations can survive.
+The engine does not generate mutations or decide their semantic validity.
+
+## Initial profile
+
+`node-flat-tests` accepts one JavaScript project at the root, with only
+`javascript.node-test` selected. The manifest must have no dependencies,
+development dependencies, optional dependencies or peer dependencies. Additional
+checks/projects, environment requirements, Git selection and operator overlays
+are unsupported. Only flat native Node tests are accepted; suites and nested
+tests do not yet have the required identity accounting. Other languages and
+framework runners remain separate work.
+
+Recipes use `schemas/mutation-recipe.schema.json`. Each mutation names an
+inventoried `.js`, `.mjs` or `.cjs` source file outside the selected test files,
+one literal `expected` string and different `replacement` text. Exactly one
+occurrence must match, including overlapping occurrences. Targets require valid
+UTF-8. Missing, ambiguous, unchanged and test-file targets are recorded invalid;
+malformed recipes, duplicate IDs and escaping paths are rejected before execution.
+Helpers can indirectly alter test behavior, so recipe review is still necessary.
+
+## Execution and evidence
+
+The engine snapshots only its bounded inventory and copies those files. Excluded
+dependencies, symlinks, secrets, caches and generated outputs are not copied.
+The report records original exclusions. File permissions, Git metadata and
+external resources are not reproduced; a copy is not a hermetic build identity.
+No tools or dependencies are installed. Original source is fingerprinted before
+and after the experiment, and a change or unreadable final source prevents
+`complete: true`.
+
+A fresh copy must first pass a baseline with non-skipped tests and complete native
+test identities. Every valid mutation receives another fresh copy, so no trial
+inherits files written by an earlier trial. The copied source also receives the
+engine's normal before/after fingerprint check.
+
+- `killed`: the same observed test identities complete and native assertion
+  failures occur. Node's error cause must identify `AssertionError` with
+  `ERR_ASSERTION`; string matching an error message is insufficient.
+- `survived`: the same observed tests pass with the changed source.
+- `inconclusive`: compilation/import/runtime errors, changed test identities,
+  partial evidence, skips, timeouts or copied-source changes prevent classification.
+- `invalid`: the requested edit does not satisfy the target contract.
+- `not-run`: baseline failure, cancellation or the total budget prevents execution.
+
+Identities include source-relative test file, name, line and column; matching
+counts alone are insufficient. Test assertions that deliberately catch errors
+remain assertions. Malicious or customized test code can forge evidence, as with
+ordinary trusted validation; this is not an attestation mechanism.
+
+Reports reconcile every requested mutation. `complete` means all requested trials
+were classified as killed or survived against unchanged original source; it does
+not mean the tests are adequate. CLI exits `0` for a complete experiment, even with
+survivors, and `2` for incomplete/error. There is no implicit mutation-score gate.
+Summary mode omits mutation IDs, file paths, individual runs and logs. Detailed
+mode adds bounded native run IDs, fingerprints, durations and counters without
+raw process output. No model is invoked and no source is uploaded by the engine.
+
+## Bounds and lifecycle
+
+Recipes are capped at 128 KiB, eight mutations and 4096 characters per expected
+or replacement string. Existing inventory bounds apply: 20,000 entries, 8 MiB per
+file, 64 MiB total. Copies run sequentially. The default total execution budget
+is 30 seconds, configurable up to 120 seconds; file inspection/copying and cleanup
+are cooperative filesystem operations rather than hard OS deadlines.
+
+MCP execution is disabled unless enabled at startup, shares the validation
+execution slot and responds to ordinary request cancellation. Library callers can
+supply an `AbortSignal`. Process groups are terminated by the shared runner.
+Normal completion, failure and cancellation remove copies in `finally`; abrupt
+process or machine termination can leave a private temporary directory. Ordinary
+async calls do not implement durable MCP Tasks.
+
+The regression suite exercises the public example, error classifications, invalid
+edits, failing/skipped/nested baselines, changed test identity, source preservation,
+cancellation and cleanup. These synthetic cases are not an independently held-out
+review-quality evaluation. Broader language support, mutation generation, impact
+selection and comparison with the prior review workflow remain pending.

package/docs/MYPY.md

@@ -0,0 +1,37 @@
+# Mypy validation
+
+Select `python.mypy` explicitly. The operator's `python3` must have mypy 2.3.1
+installed. Other versions are unavailable until verified: this adapter uses the
+native options API to detect per-module `ignore_errors`, in addition to the
+documented `mypy.api.run` entry point. Missing tools never trigger installation.
+Planning does not import mypy, plugins or project modules.
+
+The check passes all inventoried `.py` and `.pyi` files explicitly, records native
+source resolution, and reconciles the success summary with the complete planned
+file set. Global or effective per-module `ignore_errors` prevents passing. Errors
+fail; incomplete or unfamiliar output cannot pass. Unused inline ignore comments
+are reported, and untyped function bodies are checked. This is not strict mode:
+other rule exclusions and valid inline ignores follow the native configuration.
+
+Configuration is selected from project-local `mypy.ini`, `.mypy.ini`,
+`pyproject.toml` or `setup.cfg` in that order; without one the adapter uses an
+empty configuration. Parent/home settings are not loaded implicitly. Workspaces
+requiring external configuration need a future explicit policy option. Paired
+implementation/stub modules, namespace layouts and imported dependency coverage
+need their own integration fixtures; a duplicate-module error is not waived.
+
+Incremental reuse, cache writes and stub installation are disabled. Existing
+cache files are preserved. Trusted plugins and explicitly configured report
+generators can still have side effects. This is not a sandbox. Source mutation
+remains subject to the engine's post-run fingerprint check.
+
+Native tests passed with mypy 2.3.1 and Python 3.12.13 in a prepared Linux
+container. They exercise valid annotations, incompatible assignments, global and
+module-specific broad suppression, missing imports, unused ignores, configured
+stub installation prevention and cache preservation. The host lacks this mypy
+version, so its native test skips explicitly. The separate
+[Python container checks](PYTEST.md) reproduce these cases with no network and
+read-only synthetic source.
+
+See the official [mypy command-line reference](https://mypy.readthedocs.io/en/stable/command_line.html)
+for native checking and installation options.