@stsepelin/checktrail 0.1.0-alpha.1

package/docs/RELEASE.md

@@ -0,0 +1,115 @@
+# Release preparation
+
+The source is public at [stsepelin/checktrail](https://github.com/stsepelin/checktrail);
+the first preview is `0.1.0-alpha.1`. `server.json` describes the
+intended `io.github.stsepelin/checktrail` MCP registry identity and the matching
+`@stsepelin/checktrail` npm package. The npm and registry names are proposed
+metadata, not evidence of a published package or registry entry. Package publishing
+is configured for public access on npm's `next` tag. No credentials or automatic
+publishing workflow are stored in this repository.
+
+## Prepared artifacts
+
+- The npm package has an explicit file allowlist, public MIT license, documentation,
+  versioned schemas and data-only packs. Dependency notice auditing and repeated
+  tarball comparison are implemented in the local verification scripts.
+- `server.json` pins the package version and uses stdio. Its generated command
+  starts `serve` with a required operator-selected project root. Execution and
+  detailed output remain disabled; an operator can configure a trusted local
+  installation separately as documented in `README.md`.
+- `package.json` declares `mcpName` matching the registry identity. A regression
+  test reconciles package, lockfile, engine and registry versions, starts the
+  metadata-derived command through an SDK client, verifies root-private summary
+  output and requires execution to remain denied. The offline package smoke also
+  loads the installed metadata and verifies its actual startup command.
+- CI definitions cover the host suite and prepared native profiles. Local
+  containers and package checks are evidence only for the environments actually
+  exercised. All 13 hosted jobs passed at source baseline `52ba415`; the preview
+  release commit requires its own run. The local Claude Code health/discovery and
+  Codex direct app-server profiles have fresh-install evidence in `CLIENTS.md`.
+
+The metadata follows the official registry
+[publishing guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx)
+and the versioned
+[2025-12-11 schema](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json).
+Registry metadata schema versions are separate from the MCP wire protocol version.
+The official schema was downloaded and validated locally; its bytes are pinned
+by the verifier below, without bundling a copied schema in the package.
+
+```sh
+curl --fail --silent --show-error --location --max-time 30 \
+  https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json \
+  --output /tmp/checktrail-registry-schema.json
+node scripts/verify-registry-metadata.mjs /tmp/checktrail-registry-schema.json
+```
+
+The checker requires SHA-256
+`3fba09590c99f61735d234822279f4223fab9e300c0a81e81c91ab62a4114de0`.
+A changed schema must be reviewed before changing that pin. Schema validation
+does not establish namespace ownership or registry acceptance. The current metadata
+identifies this release as `preview` under publisher metadata. That label describes
+release maturity, not whether npm or the MCP Registry has accepted it.
+
+## Preview publication sequence
+
+The candidate review records the exact tarball SHA-256, file inventory, source
+manifest and test evidence. Keep it outside the package allowlist. Client checks
+must report the same tarball hash; repacking after an edit creates a new candidate.
+The source commit must pass hosted CI before publication.
+
+After explicit approval and npm authentication for the `@stsepelin` scope, publish
+the approved file, not a newly packed working tree:
+
+```sh
+npm publish /absolute/path/stsepelin-checktrail-0.1.0-alpha.1.tgz \
+  --tag next --access public --ignore-scripts --registry=https://registry.npmjs.org
+```
+
+Verify the registry version and dist-tag, download its tarball, compare its digest
+to the approved file, and repeat a fresh CLI/MCP installation check. This manual
+tarball path does not claim npm build provenance. See
+[npm publishing options](https://docs.npmjs.com/cli/v11/commands/npm-publish/).
+
+Only after npm publication and separate registry authentication, publish the
+reviewed `server.json` with the official `mcp-publisher` CLI. Verify the returned
+server name, version, npm identifier and execution-disabled startup arguments
+through the registry API. The registry verifies npm ownership using `mcpName`;
+local schema validation alone cannot establish acceptance. See the official
+[registry quickstart](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx).
+
+GitHub private vulnerability reporting is enabled. Use the channel linked in
+`SECURITY.md`. Tags and GitHub releases also require explicit authorization.
+
+## Before a concrete release
+
+1. Select the supported release scope and version using `LANGUAGES.md` and
+   `EXECUTION.md`. Reconcile npm, lockfile, engine and registry versions and replace
+   the development-candidate status only when appropriate. Do not advertise Tasks
+   until the standard wire/lifecycle gates in `MCP-COMPATIBILITY.md` pass.
+2. Run `npm run check`, `npm run format:check`,
+   `node scripts/audit-dependencies.mjs`, then
+   `node scripts/prepare-package-cache.mjs` with network access before
+   `node scripts/smoke-package.mjs` performs its fresh offline installation.
+   Run the corresponding native verification helpers for every advertised profile.
+   Record actual tool/platform results and explicit skips. Repeat registry schema
+   validation against its pinned bytes.
+3. Inspect the exact tarball and its SHA-256, its source revision, dependency/notice
+   report, package allowlist, public examples and documentation. The smoke helper
+   compares repeated packing of the same checkout and tests a fresh offline install;
+   it does not establish reproducibility across operating systems or compiler builds.
+4. Obtain the required explicit authorization for the concrete commits, remote
+   creation and push. Establish the public repository, vulnerability reporting,
+   maintainer ownership and hosted CI evidence. No local script performs these
+   actions as a side effect.
+5. Re-run the supported client profiles in `CLIENTS.md` against the exact release
+   candidate, and complete independent evaluation gates for
+   any effectiveness claims. Development fixtures do not prove equal or better
+   review quality than a prior workflow; see `EVALUATION.md`.
+6. Present the exact version, tarball digest, tested scope and known limitations
+   for package/release/registry publication authorization. Configure the chosen npm
+   publishing identity and provenance mechanism, then verify the published package
+   before registry registration. The registry's npm ownership check uses the
+   published package's `mcpName`; a local file cannot satisfy that external gate.
+
+No arbitrary adapter, broad framework/OS matrix or review-quality claim becomes
+verified through publication. Keep the compatibility record alongside the release.

package/docs/RENAMING.md

@@ -0,0 +1,55 @@
+# Checktrail naming
+
+Checktrail replaces the development name Repo Verifier before the first npm
+publication. The preview version remains `0.1.0-alpha.1`; the package identity and
+bytes change, so previous tarball hashes and approvals do not apply to this package.
+
+| Surface                 | Current identity                            |
+| ----------------------- | ------------------------------------------- |
+| GitHub                  | `stsepelin/checktrail`                      |
+| npm                     | `@stsepelin/checktrail`                     |
+| CLI and MCP server name | `checktrail`                                |
+| MCP Registry            | `io.github.stsepelin/checktrail`            |
+| Project policy          | `checktrail.json`                           |
+| Native profiles         | `checktrail.<profile>.json`                 |
+| Private local artifacts | `.checktrail/` and `.checktrail.local.json` |
+
+For an existing source checkout:
+
+1. Update the Git remote to `git@github.com:stsepelin/checktrail.git` and rebuild.
+2. Rename `repo-verifier.json` and each `repo-verifier.<profile>.json` to its
+   `checktrail` equivalent. The supported profiles are actionlint, django, dotnet,
+   fastapi, java, laravel, nuxt and vue-router. A remaining legacy policy or profile
+   causes planning to fail with a rename instruction; it cannot silently drop a
+   requirement and proceed with defaults. Remove duplicate old files when both
+   names exist.
+3. Update scripts, imports and MCP client registration using [INSTALLATION.md](INSTALLATION.md).
+   Registrations keep an absolute project root, so update that path if the
+   checkout directory was moved. Execution still requires explicit startup trust.
+4. Use `.checktrail/` for new reports and prepared development tools. Legacy
+   `.repo-verifier/` and `.repo-verifier.local.json` remain excluded from inventory
+   and Git to preserve the privacy of existing artifacts.
+
+Internal native-runner markers, temporary paths and runtime producer names now use
+Checktrail. Regenerate runtime captures with the new package when comparing them;
+old producer identities are not rewritten into new observations. The runner-owned
+temporary-directory environment variable is now `CHECKTRAIL_TEMP`.
+
+## Historical evidence
+
+Existing JSON measurements retain their original names, versions, hashes, URLs
+and observations. They describe the measured source and artifacts under the old
+name, not verification of a later Checktrail build. Old repository links may
+redirect after the GitHub rename.
+
+The original synthetic evaluation corpus is retained byte-for-byte at
+`measurements/evaluation-corpus-repo-verifier.json` so its recorded digests and
+case accounting remain independently checkable. `scripts/evaluation-corpus.json`
+is now `synthetic-evaluation-v2` with the new configuration filenames. The old
+measurements do not establish results for that revised corpus. Reproduction
+commands elsewhere in the documentation use current names; consult the recorded
+source identity to reproduce a historical run exactly.
+
+The pre-rename hosted CI baselines remain historical evidence. The rename commit
+requires its own hosted run, and the renamed package requires fresh installation
+and client checks before publication.

package/docs/REVIEW-EXCHANGE.md

@@ -0,0 +1,136 @@
+# Optional advisory review exchange
+
+Checktrail can prepare a bounded source context for a human, local reviewer or
+model-backed MCP client, then inspect a structured assessment returned by that
+reviewer. The engine does not invoke inference, select a provider, upload source,
+execute reviewer instructions or apply changes. This implements an exchange
+workflow; it does not establish review quality or independently verify a defect.
+
+Every receipt has `channel: advisory`, `automatedCoverage: false`,
+`claimsVerified: false` and `deterministicOutcomeChanged: false`. It has no
+validation outcome and cannot become a native finding, SARIF result or finding
+baseline through this API. A reviewer reporting no observations is not a passing
+validation result. Native validation continues through its existing engine.
+
+## Prepare a context
+
+Select exact files and public guidance topics in a JSON artifact:
+
+```json
+{
+  "schemaVersion": 1,
+  "files": ["catalog.mjs"],
+  "topics": ["test-lifecycle"]
+}
+```
+
+`examples/review` supplies an original synthetic source and selection. In a local
+checkout, prepare an ignored artifact directory before capturing the context:
+
+```sh
+mkdir -p examples/review/.checktrail
+node dist/src/cli.js review-context --root examples/review \
+  --input selection.json --detailed --allow-review-source \
+  > examples/review/.checktrail/context.json
+```
+
+The default output is a summary. `--detailed` alone still omits source and review
+prose for these commands. Source-enabled review output requires both `--detailed`
+and `--allow-review-source`. For MCP, these are server startup settings; tool
+arguments cannot grant access. The same gate protects imported assessment prose
+and quotations, which can themselves contain source or private information.
+Library callers use `createReviewContext()` and explicitly choose their output
+projection with `projectReviewContext()`.
+
+Contexts contain exact UTF-8 text, per-file byte digests, the bounded inventory's
+source fingerprint, selected public guidance, a fixed review instruction and a
+content digest identifying the complete context. Files and topics are sorted;
+duplicate selections fail. Source and comments are labeled untrusted data. They
+may contain misleading instructions; neither the collector nor importer executes
+them, and a consuming reviewer must maintain that boundary.
+
+Limits are 16 files, 64 KiB per file, 128 KiB combined source and 16 public topics.
+Sources must be inventoried regular files with normalized relative paths. Excluded
+secrets/dependencies/build output and symlinks cannot be selected. Binary NUL data
+and invalid UTF-8 are rejected. These exclusions are not a secret scanner: a
+credential embedded in an ordinary source file remains source. Enabled source
+output can reach the MCP client's provider according to that client's behavior.
+
+Context collection compares before/after inventory fingerprints. This detects
+ordinary concurrent edits but is not an atomic filesystem snapshot or protection
+against adversarial filesystem races. Fingerprints retain the inventory's limits
+for dependencies, external files and services. Saving output outside the ignored
+artifact directory can itself change the inventory; creating a new excluded
+directory after capture also changes the recorded exclusion list.
+
+## Receive an assessment
+
+The reviewer returns the [assessment schema](../schemas/review-assessment.schema.json),
+including the exact context digest, reviewer provenance, UTC creation time,
+per-file dispositions and optional observations with exact source quotations.
+Human reviewers declare a name; model reviewers declare provider, model and
+version. Those identities and the reported creation time are declarations, not
+verified credentials or measured execution evidence.
+
+Usage fields are input tokens, output tokens, elapsed milliseconds and cost in
+USD. Unknown values must be `null`, not zero. The engine labels every value
+`reviewer-declared`; it does not infer pricing or claim a model call occurred.
+Observations have a concern/suggestion label and at least one citation. IDs must
+be unique. Files outside the selected context and reversed line ranges are rejected.
+Out-of-bounds line numbers cannot match a quotation.
+There are at most 64 observations, eight citations per observation and 256 KiB
+of serialized assessment input.
+
+Save the assessment under the ignored artifact directory and inspect it:
+
+```sh
+node dist/src/cli.js review-receipt --root examples/review \
+  --context .checktrail/context.json \
+  --input .checktrail/assessment.json
+```
+
+`receiveReview()` and MCP `review_receipt` use the same implementation. MCP
+receives paths to local artifacts, not an arbitrary executable reviewer command.
+The CLI returns 0 for a current, structurally accepted receipt with matching
+quotations, and 2 for stale context, unmatched quotations or invalid input. Exit 0
+means the receipt was processed; it does not approve code or verify claims.
+
+The importer verifies the context's digest, captured bytes and current supported
+guidance/instruction version, then compares the recorded inventory and selected
+file bytes against current source. `freshness: current` only describes that
+comparison. A recomputed digest cannot make fabricated source bytes current.
+Older or modified instruction/catalogue contracts require an explicit migration;
+they are rejected rather than silently interpreted as this version.
+
+Citations use one-based inclusive line ranges. A quote must equal the complete
+selected lines joined with LF, excluding the delimiter after the final line.
+CR bytes in CRLF input are preserved. A matching quote establishes an anchor in
+the recorded context, not the truth of the surrounding claim. After source changes,
+a receipt can correctly say both `freshness: stale` and `citations.matched: 1`.
+
+Coverage counters distinguish selected, declared reviewed, declared not reviewed
+and unaccounted files. Missing dispositions stay visible; they are not silently
+counted as reviewed. These counters describe the reviewer's accounting, not proof
+that the reviewer inspected any file. Summaries omit paths, quotations, claims,
+observation IDs and arbitrary reviewer names; they retain counts, usage declarations
+and the opaque context digest. Detailed review output requires the source gate.
+
+## Evidence and remaining limits
+
+Tests exercise original synthetic contexts and assessments, exact quotation
+matching, stale and forged source, duplicate/out-of-scope inputs, binary and size
+limits, native CLI/MCP permissions and unchanged native validation outcomes.
+The package helper `node scripts/verify-review-container.mjs` runs the review tests
+and an offline fresh-install library/CLI/MCP workflow in a pinned Linux container
+with networking disabled and read-only source mounts. Status belongs in `STATUS.md`;
+a helper definition alone does not establish a successful run.
+
+Manual mutations removed the selected-file freshness check and replaced the review
+disclosure gate with ordinary detailed mode. The forged-source regression then
+incorrectly became current, and the MCP privacy regression exposed source without
+the grant. Both tests failed on those exact changes and passed after restoration.
+
+Synthetic model names in tests are labels, not evidence of inference. No independent
+held-out assessment, prior-workflow comparison, model accuracy, measured token
+cost or calibrated confidence is claimed by this feature. Those M5 evaluation
+requirements remain separate from correctness of the exchange protocol.

package/docs/RUBY.md

@@ -0,0 +1,50 @@
+# Ruby syntax profile
+
+`ruby.syntax` parses each inventoried `.rb`, `.rake` and `.gemspec` file, plus
+`Gemfile` and `Rakefile` DSL manifests. Project discovery uses Gemfile/gemspec
+boundaries, so nested projects receive separate checks. Extension matching is
+exact; backups and ERB/RBS files are not silently treated as Ruby source.
+
+Each file runs through installed MRI Ruby with `--disable-gems -c`, with `RUBYOPT`
+cleared to prevent injected preload flags. The native version probe uses the same
+environment and gem control. Source paths are individual literal arguments, never
+shell fragments. Planning only enumerates files. Execution retains the normal
+operator trust gate and shared time/output/source-freshness limits.
+
+Every planned process must complete with zero exit, exact `Syntax OK` output and
+empty stderr for a pass. Nonzero syntax-check exits fail; missing executables,
+warnings/ambiguous output, timeout, cancellation and changed source cannot create
+a passing aggregate. No test counts, type guarantees, gem-resolution guarantees
+or Rails boot coverage are reported. Ruby runtime code, including `BEGIN` blocks,
+is not evaluated by the native syntax-check flag; the fixtures assert this using
+file-write sentinels. Invoking an installed tool remains trusted process execution,
+not a sandbox or a guarantee about arbitrary wrappers on PATH.
+
+Verified native versions are MRI 4.0.7 on Alpine Linux and the available MRI
+2.6.10 on macOS. The older host version is compatibility evidence, not a runtime
+recommendation. Other Ruby implementations/version output formats, RSpec,
+Minitest, RuboCop, ERB/RBS checking and Rails integrations remain separate work.
+
+The public fixture is `examples/ruby`. Run it with installed Ruby:
+
+```sh
+node dist/src/cli.js run --root examples/ruby --trust-project
+```
+
+The native container suite is `node scripts/verify-ruby-container.mjs`. It uses
+already installed Ruby 4.0.7 and Node 22 images pinned by registry digest, records
+their identities, disables
+networking, and tests the public files in a temporary Linux copy. No gems are
+installed. Native cases cover broken/fixed methods, misleading literal text,
+per-file success evidence and top-level/BEGIN non-execution. Hosted CI evidence
+remains pending; local tests do not establish remote matrix results.
+
+Reference: [Ruby distributions and maintenance status](https://www.ruby-lang.org/en/downloads/).
+
+The dedicated Ruby CI job prepares those pinned images and invokes the same
+helper. `scripts/required-native-tests.json` identifies the exact native regression
+that must pass. The required-test runner rejects skips, TODOs, missing or duplicate
+required names, and failures elsewhere in the selected test file. A passing unit
+test cannot replace the native regression. This job definition and its local
+Linux/Node 22 execution are verified. The hosted job also passed at `52ba415`;
+see `NATIVE-CI.md` for the separate run evidence.

package/docs/RUFF.md

@@ -0,0 +1,39 @@
+# Ruff validation
+
+Select `python.ruff` explicitly and provide `ruff` and `python3` on the operator's
+PATH. The current identity profile probes both tools, even though the Ruff binary
+itself does not need Python. The
+adapter targets inventoried `.py` and `.pyi` files. It records native file
+selection, resolved settings for each file, and JSON diagnostics. No dependencies
+are installed. Planning does not execute Ruff or project configuration.
+
+Execution forces exclusion rules to apply even to explicit filenames; any
+excluded planned file prevents passing. Fixes, fix-only mode, unsafe fixes and
+cache reuse are disabled. A pre-existing cache is preserved. Errors in native
+configuration are execution errors, not successful checks. Diagnostics fail even
+if the tool unexpectedly exits zero. Malformed or truncated output is incomplete.
+
+The resolved settings must show at least one enabled rule not present in any
+per-file ignore entry. This conservative bound does not implement Ruff's glob
+matcher: a broad union of unrelated per-file ignores can make the result
+incomplete even when the native tool has active rules for a particular file.
+Inline suppression comments still follow native policy; suppression reconciliation
+is distinct from exact normalized-finding reconciliation in `FINDING-POLICY.md`. This check does not certify rule sufficiency.
+
+Native cases are verified with Ruff 0.16.8 in a prepared Linux container. They
+cover valid source, unused imports, undefined names, invalid syntax, excluded
+files, no enabled rules, broad per-file ignores, configured fix/fix-only settings,
+filenames with spaces and cache preservation. Settings output is a versioned
+text contract; unknown formats fail closed. Notebooks and other extensions are
+not included. One settings command per source file consumes the shared time and
+output budgets; large projects can require a future compact native integration.
+
+The [Python container verification steps](PYTEST.md) also run these native Ruff
+cases. Ruff absent from the host PATH causes an explicit native-test skip; it does
+not count as verification. See the official [Ruff configuration reference](https://docs.astral.sh/ruff/configuration/)
+for selection, exclusions and per-file settings.
+
+An [external Ruff integration cohort](EXTERNAL-RUFF-EVALUATION.md) additionally
+compares native and verifier diagnostics against pinned upstream snapshots on
+macOS and Linux. It measures diagnostic preservation for those files, not general
+review quality or a population false-positive rate.

package/docs/RUNTIME-INVENTORY.md

@@ -0,0 +1,56 @@
+# Runtime inventory comparison
+
+`compare-runtime` compares complete declared collections of routes, listeners,
+middleware, schedules and container bindings. It operates on local artifacts
+without loading the application. The same implementation is exported as
+`compareRuntimeInventories(before, after)` and exposed through MCP
+`runtime_comparison` with relative `before` and `after` paths.
+
+```sh
+checktrail compare-runtime --root /path/to/project \
+  --before before-runtime.json --after after-runtime.json --detailed
+```
+
+The versioned `runtime-inventory.schema.json` records producer name/version,
+assembly name/environment, source fingerprint, capture timestamp, and explicitly
+named collections. Every collection declares completeness and whether entry
+ordering matters. Entries have an exact key and flat attributes (strings,
+numbers, booleans, null, or ordered string arrays). This permits framework
+collectors to retain methods, paths, handlers, middleware, scheduling expressions,
+binding implementations and singleton flags without embedding executable code.
+
+Repeated registrations remain repeated entries. Comparison accounts for their
+multiplicity; it never deduplicates listeners before comparing them. Attributes
+are compared structurally, object property ordering is ignored, and attribute
+array ordering is preserved. Declared ordered collections detect a pure reorder
+even when every registration remains present. `orderChanged` specifically reports
+that pure-reorder case; other changes are reported through added/removed entries.
+A changed attribute counts as removing the previous registration and adding its
+replacement. Exact identifiers are used throughout.
+
+Both artifacts must name the same assembly, environment and producer. Versions
+and source fingerprints may differ, as expected when comparing revisions.
+Collection ordering modes must agree. Missing, incomplete or incompatible
+collections are unverified; their absent entries are not reported as removals.
+Unknown collection kinds, duplicates, unknown schema keys and malformed values
+are errors. Empty complete collections are comparable; an entirely empty profile
+is rejected. Limits are 8 MiB and 20,000 entries per artifact.
+
+The result is `passed` for matching complete declared collections, `failed` for
+known differences, and `incomplete` when remaining collections cannot be
+compared. Known changes take precedence over incompleteness, which remains visible
+in counts. `compared + unverified = collections`. Added/removed counts describe
+registrations, while changed counts describe collections. Detailed results include
+changed keys; summaries omit keys, attributes, assembly names and paths.
+
+This is imported evidence, labeled `imported-runtime-comparison`. A matching
+snapshot is not evidence of current source freshness, runtime capture correctness,
+authorization correctness or coverage of unlisted assembly categories. A producer
+must enumerate the actual runtime values, including package/default registrations,
+and claim completeness only for categories it can inspect. Collector execution
+belongs in a trusted isolated test environment. Native framework collectors and
+their compatibility matrices are separate implementation gates.
+
+Synthetic regressions cover every collection family, duplicate multiplicity,
+attribute/order changes, exact-name near misses, missing versus empty collections,
+partial evidence, artifact limits, CLI exit codes and MCP privacy/root boundaries.

package/docs/RUST.md

@@ -0,0 +1,74 @@
+# Rust compilation profile
+
+`rust.cargo-check` is the default check for an inventoried Cargo project. It uses
+installed Rust/Cargo 1.98.1 and requires an existing local `Cargo.lock`. Planning
+never invokes Cargo or build scripts. Validation needs the normal operator trust
+permission; Cargo build scripts and procedural macros can execute project code.
+
+The current profile supports one Cargo workspace member rooted at the discovered
+project. Multi-package workspaces and other toolchain versions remain unavailable
+until separately verified. Native fixtures run on Linux with the official
+`rust:1.98.1-alpine` image and Node 22.23.2. The container helper prints resolved
+image digests and disables networking. Host platforms beyond that fixture remain
+unverified for this profile.
+
+## Execution and scope
+
+The collector resolves native metadata with `--offline --locked --no-deps`, then
+runs `cargo check --all-targets --offline --locked --message-format=json` with
+fresh temporary target and build directories. Both native metadata directory
+values must confirm the overrides before compilation starts. Existing target
+directories are not reused. Incremental compilation and rustup's automatic
+toolchain installation are disabled. No dependency or lockfile installation is
+performed. These Cargo settings do not sandbox build scripts, macros or custom
+compiler wrappers; their network and filesystem privileges remain the operator's.
+
+Each inventoried `.rs` file must appear in fresh rustc dep-info dependencies. Each
+declared native target must have a matching artifact, with test-mode artifacts
+required where the target enables tests. Missing source, excluded feature targets,
+missing test-mode compilation and artifacts marked fresh/reused are incomplete
+evidence. No test bodies are executed and no test counters are reported. This does
+not prove every conditional branch or feature combination was compiled. Default
+Cargo features and the configured host/target apply; other feature/target matrix
+profiles are not implemented.
+
+Dep-info decoding supports ordinary paths, Unicode and escaped spaces. Newline,
+backslash, dollar, hash and colon in the inventoried source paths are outside this
+initial verified grammar. Malformed or unsupported dependency rules fail
+completeness rather than being guessed. The collector bounds native output, build
+inventory entries and dependency-file bytes; the shared process runner bounds
+time, cancellation and total output. Temporary output is removed on normal runner
+exit; forced termination can leave temporary files for host cleanup.
+
+Compiler error diagnostics fail the check. Their normalized code, message and
+available source location are retained; compilation errors are never eligible as
+complete baselinable analysis. Warnings remain visible but do not fail this
+compilation check. A nonzero Cargo exit without structured compiler-error evidence
+is an execution/configuration error. A passing result requires a successful final
+build event, complete target/source accounting and identified native tools.
+
+This is compiler checking, not linking, Clippy, formatting, test execution or a
+hermetic build guarantee. Dependency content, external files, custom wrappers and
+all environment effects are not fully fingerprinted. Users with non-default
+`CARGO_HOME`/`RUSTUP_HOME` locations can declare those environment requirements and
+grant them through the existing operator environment mechanism.
+
+## Reproduce
+
+With the pinned toolchain installed:
+
+```sh
+node dist/src/cli.js run --root examples/rust --trust-project
+```
+
+Change the module's numeric return to a string in a temporary copy to observe
+`rustc/E0308`. Add an unlinked Rust file to observe incomplete scope. The development
+native suite is `node scripts/verify-rust-container.mjs`; it uses already installed
+images and does not pull them. It verifies escaped-space paths, broken/fixed code,
+target/source accounting, preserved existing build output, unavailable workspaces
+and build-script source. The fixture contains a deliberately panicking test body
+to distinguish compilation from test execution.
+
+References: [Cargo check](https://doc.rust-lang.org/cargo/commands/cargo-check.html),
+[JSON messages](https://doc.rust-lang.org/cargo/reference/external-tools.html),
+[rustup environment controls](https://rust-lang.github.io/rustup/environment-variables.html).

package/docs/SARIF.md

@@ -0,0 +1,64 @@
+# SARIF export
+
+The CLI and library export existing detailed validation reports as SARIF 2.1.0:
+
+```sh
+checktrail run --root /path/to/project --trust-project --detailed > report.json
+checktrail export-sarif --root /path/to/project --input report.json > results.sarif
+```
+
+The input path is relative to the configured root and is subject to the normal
+bounded-read and path-escape checks. Export only reads the report: it neither
+executes project code nor establishes that a stored report still describes the
+current source. Preserve the original command's exit status in CI; exports also
+retain the report's passed/failed/incomplete exit convention.
+
+```js
+import { exportSarif, validate } from "@stsepelin/checktrail";
+const report = await validate(root, { trusted: true });
+const sarif = exportSarif(report);
+```
+
+ESLint, Ruff, PHPStan, Staticcheck, golangci-lint and TypeScript solution builds currently provide normalized source findings. Each has
+its native rule identifier, severity, message, repository-relative file and line
+when available. Columns are omitted until cross-tool character-unit behavior is
+verified. These findings appear only in detailed reports. CLI/MCP summary output
+continues to omit messages and paths.
+
+Each selected check becomes a SARIF run. Rule IDs include both the check and
+native rule ID, and locations use percent-encoded relative URIs with `%SRCROOT%`
+as their base ID. No absolute base directory, source snippets, commands, logs or
+environment values are exported. Native messages can still contain sensitive
+project information; SARIF is an explicitly requested detailed artifact.
+
+A completed analysis with source diagnostics has `executionSuccessful: true`
+even when it found violations. Tool errors, unavailable/skipped/inconclusive
+checks, source changes and failed checks without an explicit
+`findingsComplete: true` evidence marker produce
+error execution notifications and `executionSuccessful: false`. Generic command
+or test failures never become invented source findings. Passed checks without
+normalized diagnostics retain their status and indicate that normalized findings
+are unavailable. Run properties preserve the complete report's outcome, source
+and policy fingerprints, check status, test counts and labeled tool identities.
+Do not interpret an empty results array as proof that validation passed.
+
+Older reports without this optional marker remain readable, but failed checks
+cannot claim complete SARIF execution. A finding can remain visible even when
+file accounting or another native failure prevents complete analysis.
+
+The exporter validates the detailed report schema and rejects contradictions
+between its aggregate outcome and check statuses. It rejects absolute, escaping
+or non-normalized finding paths. Stale findings remain visible with failed
+execution metadata. Importing a report does not independently attest its origin.
+
+Tests validate exports against the unmodified OASIS supporting schema, pinned by
+SHA-256. That schema's language patterns require JavaScript regex compilation
+without the Unicode flag because they contain an unescaped closing bracket;
+the exporter does not emit a language field. Tests also exercise the real ESLint
+adapter, CLI round trips, failed/incomplete/stale/empty reports, URI encoding,
+message braces, schema rejection and unchanged summary privacy. The external
+schema and its OASIS notices are development fixtures and are excluded from the
+published package allowlist.
+
+References: [OASIS SARIF 2.1.0 specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html),
+[official supporting schema](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json).