@stsepelin/checktrail 0.1.0-alpha.1

package/docs/NATIVE-CI.md

@@ -0,0 +1,96 @@
+# Required native CI evidence
+
+The ordinary test suite permits explicit skips for unavailable optional tools.
+That makes it useful on a developer machine, but its aggregate exit code cannot
+establish that a native adapter ran. CI's prepared profiles additionally use
+`node scripts/verify-required-native-tests.mjs PROFILE`.
+
+The [profile manifest](../scripts/required-native-tests.json) lists exact test
+names and files. The runner requires each listed test to pass exactly once,
+rejects any failure, skip or TODO in the selected files, and distinguishes a
+passing suite from a passing test. A similarly named test, a test in another
+file, or a passing unit test cannot stand in for a missing native regression.
+Expected names are fixed inputs; the runner does not discover its requirements
+from whichever tests happen to remain in the source tree.
+
+The main CI matrix prepares and requires `core`, `javascript`, `python`,
+`frameworks`, `go`, `php-tools`, `laravel` and `rust`. Dedicated container jobs
+require `clang`, `java`, `dotnet`, `actionlint`, `vue-router` and `nuxt`.
+Ruby and Swift have dedicated required-native jobs. The packaged review and
+durable-task helpers require `review` and `tasks` before their installed-package
+checks. The separate PHP syntax helper checks its exact successful TAP test name;
+the external-adapter helper already checks exact required native names for each
+of its different runtime containers.
+
+A tool version preflight remains useful but is not the acceptance condition.
+Installing the expected binary cannot compensate for a skipped, renamed, removed
+or failing required test. When intentionally renaming or replacing a regression,
+review its behavior and update the manifest with that change. Do not remove a
+requirement merely to make an unavailable toolchain green.
+
+The native profiles supplement the full suite; they do not replace linting,
+type checking, parser tests, privacy tests or package verification. Some selected
+files contain both native and unit cases, so `passed` counts in their summaries
+are test counts, not native-tool invocations. Profiles can overlap with the full
+suite. Do not add their pass counts together as independent coverage.
+
+Container helpers retain their existing prepared dependencies, network-disabled
+execution and read-only source mounts. They do not install tools while measuring.
+A main hosted job prepares dependencies before validation. Local container runs
+are evidence for their actual versions and platforms only; the GitHub Actions
+matrix requires its own successful run before being claimed as verified.
+
+The runner's regression tests exercise required-test absence, exact name/file
+identity, duplicates, skips, TODOs, suite-only matches and unrelated failures.
+Deleting its missing-test rejection makes the absent-test case fail. To diagnose
+a native assertion failure, rerun the named file directly with `node --test` in
+the same prepared runtime for the full assertion diagnostics.
+
+The [recorded local profile runs](measurements/required-native-profiles.json) retain
+requirement/helper digests, result accounting and available container/package
+identities for the expanded profiles. Each listed requirement passed in those
+runs. The unchanged Ruby/Swift paths have their separate local evidence in
+`RUBY.md` and `SWIFT.md`. These records do not claim that the hosted matrix ran,
+that all profiles ran in a single environment, or that overlapping counts are
+independent tests.
+
+## Fresh-runner package preparation
+
+`npm ci` installs from the repository lockfile but does not necessarily cache
+the registry metadata needed to resolve a new consumer's dependencies. Before
+packaged checks, CI runs `node scripts/prepare-package-cache.mjs` with network
+access. It packs the current build and installs it in a disposable consumer with
+lifecycle scripts disabled, using the same npm cache as the later smoke helpers.
+The disposable installation is removed; only the npm cache is reused.
+
+The smoke helpers still create fresh consumers and install with `--offline`.
+Native container checks still use `--network none`. Cache preparation is setup,
+not evidence that a package can be installed without previously cached dependencies.
+For local reproduction, run `npm run build`, the cache preparation script, then
+`node scripts/smoke-package.mjs`, keeping the same npm cache configuration.
+
+The [first hosted run](https://github.com/stsepelin/checktrail/actions/runs/35570317427)
+exposed this missing setup: Java, C#, actionlint, external adapters, Vue Router and
+Nuxt reached packaged installation after their native checks, then failed with
+`ENOTCACHED`. All three Linux main-matrix jobs reached the same failure after
+passing their full suites and required native profiles. Clang, Ruby and Swift
+jobs passed. The macOS main job failed separately because Pint attempted to seek
+within `/dev/null`; the adapter now uses a fresh regular cache file in a
+runner-owned directory, with cleanup asserted after successful and failed checks.
+See `PINT.md`. A later macOS assertion also needed canonical rather than aliased
+temporary paths; its fixture now exercises a symlinked root on every platform.
+All three fixes are included in the successful run below.
+
+## Successful hosted baseline
+
+[Run 35573066804](https://github.com/stsepelin/checktrail/actions/runs/35573066804)
+passed all 13 jobs at commit `52ba415dfc5cfcaab459dc648baaa864627f1642`.
+The [job and step record](measurements/hosted-ci-52ba415.json) retains the source
+identity, run URLs, outcomes and timestamps. The main matrix covered Linux Node
+22/24/26 and macOS Node 24; dedicated jobs covered Java, C#, Clang, actionlint,
+external adapters, Vue Router, Nuxt, Ruby and Swift.
+
+This establishes the configured profiles for that revision and those hosted
+environments. Optional skips in the general suite still do not count as native
+coverage. The `0.1.0-alpha.1` release metadata and documentation follow this
+baseline; the release commit needs its own CI run before publication.

package/docs/NUXT.md

@@ -0,0 +1,123 @@
+# Nuxt SSR testing assembly
+
+`javascript.nuxt-runtime` builds a fresh Nuxt SSR testing assembly and sends
+explicitly declared page requests through Nitro's in-process `localFetch`. An
+injected server-only plugin observes the actual Nuxt router at `app:rendered`,
+after plugins, initial navigation and rendering. The hook retains a reader; the
+collector invokes it only after the in-process request completes, including later
+awaited render hooks. This includes generated page
+routes and runtime registration; it does not reconstruct routes from filenames.
+No listening socket or external infrastructure is started by the collector.
+
+This experimental profile is version-gated to Nuxt/Kit/Vite-builder/Nitro-server
+4.5.2, Nitro 2.13.4, Vue 3.5.43 and Vue Router 5.3.1. Dependencies must be prepared
+inside the operator root. Fixture tooling has a separate lockfile in
+`scripts/nuxt-tools`; the production package does not install or redistribute that
+framework toolchain. Package metadata identifies tools, not an attestation of
+unaltered installed bytes or bundler aliases.
+
+## Request contract
+
+Select `javascript.nuxt-runtime` explicitly and add `checktrail.nuxt.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "assembly": "example.catalog",
+  "environment": "test",
+  "probes": [{ "path": "/", "matched": [{ "path": "/", "name": "index" }] }]
+}
+```
+
+The project must contain exactly one inventoried `nuxt.config.js`, `.ts`, `.mjs`,
+`.mts`, `.cjs` or `.cts`. Planning never loads it. Execution requires operator
+trust. Configuration, modules, Vite/Nitro plugins, server handlers, middleware,
+SSR plugins and page rendering execute project code with the user's privileges.
+They may perform their own I/O; the execution allowlist is not a sandbox.
+
+Each probe expects HTTP 200 and an exact ordered matched chain. Names may be null.
+At least one probe and one matched record per probe are required; at most 16
+unique request paths and 32 records per chain are allowed. Every final native
+route record, including aliases, must participate in a declared SSR request.
+Negative HTTP status contracts, redirects, client-only navigation and browser
+hydration are outside this profile. An unexpected HTTP status is a failed finding;
+missing capture remains incomplete even when HTTP 200 was returned.
+
+Every request gets a new Nuxt application through the built SSR renderer. The
+ordered route projection must remain identical across requests. Request-dependent
+registration is reported as incomplete rather than merged into an invented
+single assembly. Record indices, signatures, counts, matched identities and
+source identity are reconciled by the evidence parser. Empty, partial or malformed
+evidence cannot pass. Known request/route failures remain failed even when capture
+is also incomplete, with `findingsComplete: false`.
+
+## Assembly and projection boundaries
+
+The collector sets `NODE_ENV=test`, clears `NODE_OPTIONS`, disables Nuxt telemetry
+and devtools, and selects non-development SSR with the native Vite builder and
+Nitro's `nitro-prerender` preset. Nuxt dotenv loading is disabled. It uses a fresh
+canonical temporary build/output/cache directory owned by the shared runner;
+normal completion, timeout and cancellation remove that directory. Nuxt build-cache
+reuse, Chrome DevTools project metadata and the experimental TypeScript plugin
+are disabled. Project code can still
+read local files or change settings; this is a selected testing assembly, not a
+proof of production equivalence. The internal Nitro preset is pinned and tested.
+
+Probes use the synthetic host `checktrail.invalid`, without supplied credentials
+or cookies. Server route rules or handlers may intercept requests; a response
+without the instrumented SSR capture cannot establish route coverage. The check
+executes the selected SSR behavior but does not prove that middleware permissions,
+rendered content, data access or monetary calculations are correct. It does not
+validate all possible route parameters, browser state or deployment presets.
+
+Route entries use the [Vue Router projection](VUE-ROUTER.md): path/name, alias
+identity, view keys, bounded metadata/static redirect data, guard function names,
+child counts and global matcher flags. Function bodies and component behavior are
+not serialized. Unsupported data makes the collection incomplete. Captures are
+bounded to 2,048 native records, with shared process time/output limits. The planned
+scope identifies the Nuxt configuration entry; this is not per-source type checking,
+linting or an assertion that every source file was included by the build.
+
+Detailed reports retain the runtime inventory and request paths. Summary output
+omits them. Source fingerprints cover the engine inventory and retain its usual
+limits for dependencies, external services and ignored files. Runtime comparison
+can review changes in the captured projection under equivalent settings.
+
+## Reproduction
+
+Prepare the separate development fixture installation explicitly:
+
+```sh
+mkdir -p .checktrail/nuxt-tools
+cp scripts/nuxt-tools/package.json scripts/nuxt-tools/package-lock.json .checktrail/nuxt-tools/
+npm ci --prefix .checktrail/nuxt-tools --ignore-scripts --no-audit --no-fund
+npm run build
+node --test dist/test/nuxt.test.js
+```
+
+`node scripts/verify-nuxt-container.mjs` runs the native tests and a fresh offline
+package installation through library, CLI and MCP in a pinned Node 22 Alpine
+container with networking disabled and read-only source mounts. On macOS it needs
+a second prepared installation in `.checktrail/nuxt-linux-tools`, installed by
+that Linux image from the same lockfile, because native compiler bindings differ.
+On Linux it uses `.checktrail/nuxt-tools`. The helper requires Docker and the
+pinned image. `examples/nuxt` contains only original synthetic fixtures.
+
+Native regressions cover generated pages, asynchronous runtime registration,
+broken/fixed route contracts, uncovered records, HTTP failure, request-dependent
+assemblies, unsupported metadata, parser accounting and cancellation observed
+while startup is actually running. A lifecycle regression first reproduced a false
+pass when a later awaited `app:rendered` hook added an uncovered route; deferring
+the native read until request completion makes that case incomplete. The read-only
+package fixture also verifies that Chrome DevTools metadata is not written into
+the project dependency directory. Verification status belongs in `STATUS.md`;
+a defined helper or CI job is not evidence that it ran.
+
+A manual mutation removed the complete-record participation guard. The native
+uncovered-route regression failed because the result became passed instead of
+incomplete. Restoring the original evaluator restored the passing regression;
+subsequent container/package checks used the restored code.
+
+References: [Nuxt hooks](https://nuxt.com/docs/4.x/api/advanced/hooks),
+[Nuxt programmatic APIs](https://nuxt.com/docs/4.x/api/kit/programmatic).
+The pinned installed framework and native tests determine this profile's behavior.

package/docs/PACK-DISTRIBUTION.md

@@ -0,0 +1,98 @@
+# Pinned policy pack downloads
+
+`fetch-pack` explicitly downloads one data-only JSON policy pack from an
+operator-supplied HTTPS endpoint. It verifies the exact bytes against a separately
+trusted SHA-256 digest and validates the policy before making a local file
+available. Planning, validation and MCP do not download packs automatically.
+
+```sh
+checktrail fetch-pack --root /path/to/project \
+  --url https://policies.example.org/checks/core-1.0.0.json \
+  --sha256 REPLACE_WITH_TRUSTED_64_CHARACTER_SHA256 \
+  --output policies/core-1.0.0.json
+```
+
+This fictional URL and digest placeholder must be replaced. The parent directory
+must already exist under the selected root. The destination must be a normalized
+relative `.json` path; symbolic-link directories and existing destinations are
+rejected. The command returns pack identity, byte count and a `reference` object
+that can be added to a project's `packs` array in `checktrail.json`. It does not
+edit project policy or activate the downloaded checks.
+
+Library consumers can call:
+
+```js
+import { fetchPolicyPack } from "@stsepelin/checktrail";
+
+const downloaded = await fetchPolicyPack(projectRoot, {
+  url: endpoint,
+  sha256: expectedDigest,
+  output: "policies/core-1.0.0.json",
+  timeoutMs: 30_000,
+  signal: controller.signal,
+});
+```
+
+The digest establishes content integrity, not authorship. Obtain it through a
+trusted release or review process independent of the endpoint being checked.
+Updates require a new download destination and an explicit policy reference
+change. Unknown or inapplicable check IDs are rejected when the project resolves
+the downloaded pack, since downloading alone has no execution context.
+
+## Transport and storage
+
+The downloader sends a GET to the exact configured HTTPS endpoint, without a
+request body, authorization header, cookie, source file or project metadata.
+It uses Node's certificate/hostname verification and supports the operator's
+Node CA configuration. Certificate verification cannot be disabled by its options.
+Only HTTP 200 is accepted. Redirects are not followed, so the endpoint must serve
+the bytes directly. Encoded/compressed responses are rejected; the digest covers
+the received representation. Bodies are bounded to 64 KiB and response headers
+to 16 KiB. The total network deadline defaults to 30 seconds and permits at most
+120 seconds. SIGINT/SIGTERM or a library abort signal cancels an active transfer.
+
+URLs with user information or fragments are rejected. Signed query URLs can be
+used for private distribution, but command arguments may be visible to other
+local processes and URLs may appear in endpoint logs. The library avoids putting
+such a URL in CLI arguments. Returned metadata and normal download errors omit
+the endpoint and its response body. There is no credential store, token refresh,
+registry lookup or publisher-signature system.
+
+After transfer, the downloader checks the raw-byte digest, strict UTF-8, JSON
+schema and duplicate requirements. A leading byte-order mark is rejected to match
+the offline pack loader. It writes a private temporary file, syncs it and uses an
+exclusive hard link to publish complete bytes. Existing files—including a file
+created during the download—are never replaced. Temporary files are removed in
+normal completion and handled failure/cancellation. The destination has mode 0600.
+
+This requires a filesystem supporting hard links. Power-loss durability, cleanup
+after a process crash and containment of hostile concurrent filesystem changes
+are not guaranteed. The operator must trust the local destination environment.
+No downloaded code is executed by this operation. Executable external adapter
+distribution is separate; its local registration contract is documented in
+`EXTERNAL-ADAPTERS.md`.
+
+## Reproduce verification
+
+```sh
+npm run build
+node --test dist/test/fetch-pack.test.js
+```
+
+The tests require an installed `openssl` command to generate an ephemeral original
+certificate. They use an in-process loopback HTTPS server and explicitly trust
+that certificate in child clients through `NODE_EXTRA_CA_CERTS`. The untrusted
+certificate case must fail; production verification is never disabled. Tests
+exercise exact bytes, offline composition, malformed UTF-8/JSON, duplicate
+requirements, redirects, non-success status, body limits, truncated responses,
+timeouts, cancellation, output boundaries and simultaneous publication. Manual
+guard mutations confirmed that removing digest verification is caught, and replacing
+exclusive publication with an overwriting rename causes both competing writers to
+succeed and fails the race regression. The original guards were restored and the
+tests passed again.
+
+`scripts/verify-external-container.mjs` also runs these cases on Node 22 in the
+pinned Linux PHP/OpenSSL container, with external networking disabled. It repeats
+the CLI/library downloads against a fresh offline package installation. The local
+server remains reachable over container loopback. Hosted CI and a production
+private endpoint are separate, unverified deployment environments.

package/docs/PERFORMANCE.md

@@ -0,0 +1,71 @@
+# Performance measurements
+
+The benchmark creates original synthetic JavaScript projects, then measures the
+shared planning and validation engine in a fresh Node process for each sample.
+It makes no comparison with human review quality, another product or a private
+workflow. These are observations on particular machines and runtime artifacts,
+not a performance promise or CI speed budget.
+
+```sh
+npm run build
+node scripts/measure-performance.mjs > performance.json
+```
+
+The default is ten samples per case/operation; `--samples 5` through
+`--samples 30` selects a bounded sample count. Progress goes to stderr and the
+complete JSON goes to stdout only after all samples succeed. Temporary fixture
+creation and final cleanup are outside measured operations. No dependencies,
+services, accounts or network access are needed for these fixtures.
+
+## Workloads and accounting
+
+The harness defines a small single package, a single package with many small
+source modules, and a multi-package workspace. The exact project, module, file
+and byte counts are derived into each report. Every generated test imports all
+of its package's modules and asserts their combined value. Planning must report
+the expected files, projects and checks. Validation must report one passing,
+non-skipped test per project with unchanged source and no incomplete checks.
+A fast failure, empty plan or omitted test is rejected as a measurement.
+
+Cases rotate order between rounds. There is no warm-up exclusion and the
+filesystem cache is uncontrolled; a fresh process does not imply cold storage.
+Each worker has a 60-second bound and 64 KiB output limit. Validation also uses
+the engine's normal run limits. Each sample preserves raw timings, counters and
+the fixture fingerprint. Runtime artifacts, lockfile and harness digests must
+stay unchanged during measurement.
+
+- `wallMs`: elapsed time for launching and completing the fresh worker, including
+  module loading, the engine operation and waiting for native child processes.
+- `engineMs`: elapsed time around the requested engine operation, excluding
+  worker/module startup but including waits for child processes.
+- `engineCpuMs`: user plus system CPU consumed by the worker during the operation;
+  child-process CPU is excluded.
+- `enginePeakRssKiB`: the worker's lifetime peak resident memory, including startup;
+  child-process memory is excluded. This uses Node's documented
+  [resource usage API](https://nodejs.org/api/process.html#processresourceusage).
+
+Summaries include minimum, median, nearest-rank p95 and maximum. The median
+averages the middle two observations for an even sample count. With the default
+small sample count, p95 is the maximum observation; it is not a reliable estimate
+of production tail latency. Raw samples are retained for independent analysis.
+No confidence interval or statistical regression threshold is claimed.
+
+## Recorded evidence
+
+The snapshots in [measurements/](measurements/) identify their runtime, platform,
+architecture, available parallelism, timestamps and measured artifact hashes:
+
+- [macOS arm64, Node 26](measurements/performance-darwin-arm64-node26.json).
+- [Linux arm64, Node 22](measurements/performance-linux-arm64-node22.json).
+
+The Linux sample was run in the pinned Node container with networking disabled
+and the repository mounted read-only; fixtures lived in the container's temporary
+filesystem. These environments differ in OS, Node version and filesystem, so
+their timings should not be interpreted as an isolated comparison of any one
+variable. Neither snapshot is hosted CI or a Windows measurement.
+
+Native compiler/test matrices, large individual files, dependency-heavy builds,
+Git impact selection, long-running jobs, concurrent users and peak memory across
+whole process trees need separate performance evidence. Measurements do not
+establish detection quality or false-positive rates. The separate development
+corpus and its limited native comparisons are described in [EVALUATION.md](EVALUATION.md).

package/docs/PEST.md

@@ -0,0 +1,36 @@
+# Pest validation
+
+Select `php.pest` explicitly with Pest installed in `vendor` and a local
+`phpunit.xml` or `phpunit.xml.dist`. Planning reads paths only. Configuration is
+required because Pest otherwise creates temporary configuration, including during
+its version probe. Execution loads trusted project bootstrap code and plugins.
+
+The adapter uses `--ci` to run focused siblings, `--no-tia` to disable cached
+impact-result replay, and PHPUnit's full selection, no history, warning/risky
+failure and fresh JUnit flags. Pest writes progress to stdout; JUnit is streamed
+separately through stderr and parsed with bounded XML validation. Malformed or
+mixed output is incomplete. Every planned `*Test.php` file must have native case
+evidence, and passed cases need positive assertions. Native method suffixes in
+Pest's file attributes are removed before exact file comparison; filenames
+containing `::` are unavailable because that representation is ambiguous.
+
+Pest 5.2.1 with PHP 8.5.6 has been exercised in the installed official Composer
+Linux image with no network and synthetic sources created inside the container. Regression cases
+cover assertions, focused siblings, datasets, fixture failures, skipped/todo and
+empty suites, assertionless cases, missing snapshot rejection, multiple files,
+missing plugin metadata and configured always-on TIA. No source changes occurred.
+This does not establish Laravel integration, browser tests, parallel execution,
+ancestor-vendor workspace bootstrapping or compatibility with older Pest versions.
+The verifier does not select Pest automatically from PHP filenames.
+
+Prepare tools as documented in [PHPStan](PHPSTAN.md), then run
+`node scripts/verify-php-tools-container.mjs` after building. The locked development
+manifest allows only `pestphp/pest-plugin`; Composer uses that plugin to generate
+Pest's plugin inventory. Project scripts remain disabled. The native fixture
+prepares the mutation plugin's empty vendor cache directory before its
+run. This preparation is separate from consumer validation and never runs
+implicitly during planning or validation.
+
+Pest documents its [CI behavior](https://pestphp.com/docs/continuous-integration)
+and [CLI flags](https://pestphp.com/docs/cli-api-reference). Native tests, rather
+than those descriptions alone, establish the behavior advertised here.

package/docs/PHPSTAN.md

@@ -0,0 +1,48 @@
+# PHPStan validation
+
+Select `php.phpstan` explicitly. PHPStan must be installed under `vendor` in the
+project or an ancestor within the configured root. A local `phpstan.neon`,
+`phpstan.neon.dist` or `phpstan.dist.neon` is required, in that priority order.
+Planning only resolves paths; PHP, Composer autoloaders, configured bootstrap
+files and extensions execute only after operator trust.
+
+The adapter passes each inventoried PHP file explicitly and runs native debug
+mode with JSON formatting. Debug mode prints each analysed file and disables
+parallel analysis and result-cache reuse. A passing result needs every planned
+path exactly once and consistent native diagnostic totals. An excluded file with
+exit zero is incomplete. File/global diagnostics fail; unparseable execution
+errors are errors. Filenames containing newlines are unavailable because native
+debug paths are line-delimited. Configuration selects rule levels, extensions,
+baselines and suppressions; rule sufficiency and baseline reconciliation are
+separate capabilities.
+
+Verified native versions: PHPStan 2.2.14 and PHP 8.5.6, using the installed official
+Composer image. Synthetic fixtures pass valid return types, reject incompatible
+returns and bad configuration, and prevent an excluded file from yielding a
+passing result. Verification uses no network and creates synthetic fixtures inside Linux. The host has no PHP and explicitly skips this native test.
+
+Prepare pinned development dependencies separately, then run verification:
+
+```sh
+mkdir -p .checktrail/php-tools
+cp scripts/php-tools/composer.json scripts/php-tools/composer.lock .checktrail/php-tools/
+docker run --rm \
+  --mount "type=bind,src=$PWD/.checktrail/php-tools,target=/app" \
+  --workdir /app composer:2 install \
+  --no-interaction --no-scripts --prefer-dist --no-progress
+npm run build
+node scripts/verify-php-tools-container.mjs
+```
+
+The preparation command downloads locked development dependencies, enables only
+the pinned Pest plugin manager to generate its plugin inventory, and requires
+installed official Composer and Node 22 Alpine images. The verification script inspects that
+local images' digests and never pulls or downloads. It copies the Node executable
+from the installed Node image and runs the engine tests in the PHP container,
+where fixture creation and native execution share one filesystem. The repository
+is mounted read-only; temporary synthetic fixtures are writable inside the
+discarded container. This is development tooling, not container support in the verifier. Ordinary PHP syntax has a separate PHP
+8.4 verification script. Framework/Larastan integration is still unverified.
+
+See the official [PHPStan CLI reference](https://phpstan.org/user-guide/command-line-usage#--debug)
+for the native debug and result-cache behavior.

package/docs/PHPUNIT.md

@@ -0,0 +1,32 @@
+# PHPUnit validation
+
+Select `php.phpunit` explicitly. PHPUnit must be installed under `vendor` within
+the configured root. Candidate files end in `Test.php`; PHPT and other filename
+conventions need separate adapters. Planning does not execute PHP or autoloaders.
+
+The adapter invokes the installed PHPUnit and streams fresh JUnit XML to stdout.
+Normal console output is disabled to keep that stream unambiguous. Configured
+logging and test-run history recording are disabled; the adapter does not create
+or reuse a JUnit file. Native configuration, bootstrap, extensions, environment
+requirements and coverage configuration still apply. Trusted application code
+can have side effects, and missing prerequisites are not installed automatically.
+
+Native `--all` disables configuration-based test selection, while the explicit
+file list fixes this adapter's scope. Empty suites, risky tests and warnings
+cannot silently pass. The parser reconciles native suite/case counts, requires
+every planned file, and requires positive assertion counts for passing cases.
+This last check also rejects assertionless tests when native strictness is turned
+off. Skipped cases do not supply passing evidence. A zero-exit report omitting a
+planned file is incomplete. Native failures remain failures.
+
+Verified native versions are PHPUnit 13.3.4 and PHP 8.5.6. Fixtures exercise
+passing/failing assertions, exceptions, skips, empty files, assertionless tests
+with strictness disabled and multiple test files. Parser cases exercise omitted
+files, missing assertions, truncation and process failure. Project frameworks,
+inherited tests declared outside the planned files, alternate runners and older
+PHPUnit CLI versions remain unverified.
+
+The [PHP tooling preparation and container script](PHPSTAN.md) also run these
+fixtures. Verification uses an inspected local official Composer image, no
+network and synthetic fixtures created inside Linux. Host tests explicitly skip the native
+case when PHP or the prepared tools are absent.

package/docs/PINT.md

@@ -0,0 +1,41 @@
+# Pint validation
+
+Select `php.pint` explicitly with Pint installed under `vendor` within the
+configured root. This experimental adapter supports Pint 1.32.1. Other versions
+are incomplete until their internal integration and native fixtures are verified.
+Planning only resolves installed paths and inventoried non-Blade PHP files.
+`*.blade.php` templates are outside this check's scope.
+
+After operator trust, a small PHP integration boots the installed Pint PHAR and
+uses its native console command. A command-start listener records the native
+finder's exact files and resolved fixers. The normal native command then runs in
+`--test` mode with JSON agent reporting, no interaction, and a fresh regular cache
+file in the process runner's temporary directory. The runner removes that directory
+after completion, failure, timeout or cancellation; caches are never reused.
+Every planned file must be accounted for, and there must be active
+rules before a clean run can pass. Source syntax and style diagnostics fail.
+Empty rules, unexpected/missing/duplicate files, unsupported versions, malformed
+output and execution failures cannot pass. Explicit file arguments override
+Pint's finder exclusions; the native regression proves that an explicitly passed
+`notName` file is still checked. This follows native CLI path-override behavior.
+
+Blade/Prettier fixers are rejected before their dependency preparation runs.
+This adapter does not install dependencies, update code, run parallel fixing, or
+claim Blade support. Configured PHP rules, presets and local configuration
+inheritance remain native Pint behavior. The internal PHAR integration is
+version-gated because the public CLI JSON output lacks clean-file scope evidence.
+
+Native checks use Pint 1.32.1, PHP 8.5.6 and Node 22.23.2 in Linux. They cover
+valid formatting, style and syntax failures, unchanged source/cache files,
+explicitly selected excluded files, empty rules, invalid presets, blocked Blade
+integration and multiple files. Run `node scripts/verify-php-tools-container.mjs`
+after the [development preparation](PHPSTAN.md) and build. Synthetic fixtures
+are created in the container filesystem with networking disabled.
+
+The first macOS hosted run exposed that using `/dev/null` as a cache file fails
+when Pint seeks within it. The regular temporary file fixes that mechanism;
+the corrected hosted macOS suite and required profile passed at `52ba415`.
+The fixture now exercises a symlinked project root and compares canonical native
+paths on every platform. See `NATIVE-CI.md`.
+
+See [Pint's official documentation](https://laravel.com/framework/docs/pint).