@stsepelin/checktrail 0.1.0-alpha.1

package/docs/EXTERNAL-RUFF-EVALUATION.md

@@ -0,0 +1,85 @@
+# External Ruff integration evaluation
+
+This cohort checks whether the verifier preserves native Ruff diagnostics on
+externally authored Python fixtures. It does not measure general review quality
+or independently validate Ruff's own rules. The selected fixtures and expected
+snapshots come from Ruff's own test suite.
+
+The [declared plan](../scripts/external-ruff-plan.json) freezes the verifier and
+lockfile before source/snapshot inspection. It selects the primary non-preview
+fixture for F401 (unused imports), F821 (undefined names) and F841 (unused local
+variables), with a fixed upstream commit and explicit extraction exclusions.
+Filename resolution from the upstream tree is recorded in that plan. No case was
+replaced after its result was known.
+
+## Results and limits
+
+The [macOS report](measurements/external-ruff-darwin-arm64-node26.json) and
+[Linux report](measurements/external-ruff-linux-arm64-node22.json) retain the
+expected diagnostics, observations and independently recomputable comparisons.
+Both native Ruff and the frozen verifier match all expected primary diagnostics
+in the three selected files: 15 F401, 13 F821 and 16 F841. Neither run has missing
+or unexpected diagnostics, incomplete results or excluded files.
+
+These are three whole files containing mixed constructs, not 44 independent
+labeled programs. There is no separate clean-file denominator. No population
+false-positive rate or confidence interval follows from this sample. Rule code,
+filename, line and start column are compared; message prose, end positions and
+suggested fixes are not. The verifier's normalized findings preserve rule, file
+and line; the harness checks columns using the retained native JSON output.
+
+The worker receives only the source root, never the expected diagnostics. Each
+system's operation must preserve the source fingerprint. Native/worker order
+alternates between files. `wallMs` includes process startup and native execution;
+`engineMs` excludes worker import/startup. Preparation and cleanup are outside the
+measurement. Caches, scheduling and platform differences are uncontrolled, so
+these timings are observations rather than a representative overhead estimate.
+No model was called; model tokens and provider cost are zero. Machine and human
+costs are not measured. A prior review-workflow comparison remains separate work.
+
+## Reproduction
+
+Inputs are pinned by commit, byte length and SHA-256 in the
+[input manifest](../scripts/external-ruff-inputs.json). The preparation helper
+fetches only those public files, verifies every download before creating its
+output directory, and keeps the complete upstream license alongside the files.
+The source and snapshots remain ignored local inputs; public reports contain
+only diagnostic metadata and hashes. Ruff's upstream LICENSE includes its MIT
+license and third-party notices; retain the entire file when reproducing.
+
+From a checkout with the declared runtime artifacts and lockfile:
+
+```sh
+node scripts/prepare-external-ruff.mjs .checktrail
+node scripts/measure-external-ruff.mjs /prepared/input-directory /prepared/ruff
+node scripts/verify-external-ruff-container.mjs /prepared/input-directory /prepared/linux/ruff
+```
+
+Preparation needs network access; measurement downloads and installs nothing.
+Use Ruff 0.16.8. The executable must be named `ruff`. This frozen verifier also
+requires `python3` for tool identity; the harness checks that prerequisite before
+measuring any cases. The binary itself can run without Python. An initial
+container lacking Python was rejected during harness preparation and is not
+counted as a code-validation outcome.
+
+The macOS executable came from the upstream `ruff-aarch64-apple-darwin.tar.gz`
+release archive, verified against its published SHA-256
+`0ffa53899f2970d24f14fbed8d8265c87180b159b7100794d97a1527dc60fa79`.
+Both reports record their actual executable hashes, runtime versions and harness
+identity. The Linux wrapper uses local immutable image
+`sha256:50acdf79e4b3fcfafb4151579ac00b097382f64190481a1d69399efea05c9fed`,
+prepared using [external-tools.Dockerfile](../scripts/external-tools.Dockerfile).
+It disables networking and mounts the checkout, inputs and Ruff binary read-only.
+The image is local evidence, not a published reproducible image or hosted CI run.
+
+The harness rejects a runtime or lockfile that differs from the declaration,
+checks input and harness identities again after measurement, and fails on worker
+crashes rather than interpreting them as code results. Malformed process evidence
+is incomplete; unsupported snapshot contracts remain excluded rows for both
+systems. Tests exercise location/identifier boundaries, duplicate diagnostics,
+incomplete/excluded denominators and reconciliation of both recorded reports.
+
+A later verifier revision cannot be silently substituted into this frozen
+cohort. Reuse after implementation changes is regression evidence and must be
+labeled accordingly. See [the ESLint cohort](EXTERNAL-EVALUATION.md) for the
+separate earlier freeze and its preserved artifact.

package/docs/FASTAPI.md

@@ -0,0 +1,73 @@
+# FastAPI route inventory profile
+
+The opt-in `python.fastapi-routes` check imports an explicitly configured local
+application, enters its native lifespan, captures the flat route table after
+startup, exits the lifespan, and checks exact duplicate protocol/method/path
+registrations. The verified profile is FastAPI 0.141.1 with Starlette 1.6.0 on
+Python 3.12.13 in an isolated Linux container. Other framework versions are
+unavailable until their collector behavior is verified.
+
+Select the check in `checktrail.json` and provide this project-local file:
+
+```json
+{
+  "schemaVersion": 1,
+  "module": "app",
+  "attribute": "app",
+  "assembly": "catalog-api",
+  "environment": "isolated-test"
+}
+```
+
+Save it as `checktrail.fastapi.json`. `module` must resolve to exactly one
+inventoried Python module or package in that project. `attribute` is a simple
+attribute name, not an expression or a factory invocation. The value must be a
+FastAPI application. Planning validates this configuration without importing it.
+
+Execution requires normal operator trust. Import and lifespan code can access
+networks, services and files; configure an isolated test environment and supply
+required environment names through the existing operator permissions. The
+environment label in this profile is descriptive, not a sandbox guarantee. The
+engine does not install packages, run an HTTP server or send HTTP requests.
+
+The supported concrete route classes are native FastAPI `APIRoute` and
+`APIWebSocketRoute`, and Starlette `Route` and `WebSocketRoute`. Framework default
+documentation/OpenAPI routes are included, not inferred from application source.
+At least one FastAPI HTTP/WebSocket application route is required. Mounts,
+host-based routing, custom route classes and other arrangements outside this flat
+profile make the capture incomplete. Any known exact duplicate still fails while
+the incomplete runtime collection remains visible.
+
+HTTP and WebSocket identities are distinct, even for an HTTP method literally
+named `WEBSOCKET`. Methods and paths match exactly: different HTTP methods, path
+suffixes and trailing slashes are not collapsed. This detects exact duplicate
+registrations only; it does not resolve overlapping path patterns, redirects,
+host constraints or precedence between parameterized and literal routes.
+
+Detailed check results include a `runtime` artifact compatible with
+`compareRuntimeInventories`. Capture preserves registration order, multiplicity,
+route names, handler identities, schema visibility and dependency callable
+identities. Each dependency list is a deterministic depth-first traversal. It does
+not include dependency arguments, security scopes, response models, middleware
+state or handler bodies; changes to those require other checks. Completeness
+refers to this declared projection of the flat route table, not all application
+behavior. Summary output omits the inventory and raw application logs.
+
+The collector reconciles native route counts with per-entry registration indices
+before accepting an artifact. Unsupported callables, import/startup/shutdown
+failures, malformed evidence and execution limits prevent a pass. Normal stdout
+from application startup/shutdown is redirected to the bounded stderr log so it
+cannot corrupt the structured output. Source and policy fingerprints are verified
+after execution by the shared engine. Check scope names the import entry file;
+this is runtime assembly inspection, not type or syntax checking of all Python.
+
+Native fixtures verify correct routes, duplicate registrations, HTTP/WebSocket
+near misses, framework defaults, startup-added duplicates, successful cleanup,
+shutdown failure, a documentation-only app and unsupported mounts. Parser tests
+exercise source/assembly identity, native registration accounting and incomplete
+evidence. Reproduce prepared Linux tests with
+`node scripts/verify-framework-container.mjs`; the pinned preparation requirements
+are in `scripts/framework-tools.requirements.txt`. Hosted CI remains unexecuted.
+
+References: [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/),
+[Starlette routing](https://www.starlette.io/routing/).

package/docs/FINDING-POLICY.md

@@ -0,0 +1,67 @@
+# Exact finding policy
+
+Baselines and exceptions reconcile normalized source findings against a supplied
+validation report. They do not change that report. `outcome` describes policy
+reconciliation; `validationOutcome` retains native validation. A comparison can
+pass while native analysis still fails on explicitly accepted findings.
+
+```sh
+checktrail create-baseline --root /path/to/project --input report.json \
+  --owner maintainer --reason "Tracked compatibility work" --detailed > baseline.json
+checktrail compare-findings --root /path/to/project --input report.json \
+  --baseline baseline.json --previous-baseline prior-baseline.json
+```
+
+All input paths are relative to the configured root and use bounded reads with
+path-escape rejection. These commands execute no project code and write only to
+stdout. Baseline creation requires a detailed, internally consistent report with
+conclusive checks and source evidence. The default creation output is a summary;
+`--detailed` emits the artifact. Comparison exits 0 for passed, 1 for failed and
+2 for incomplete. Preserve the validation command's own exit status separately.
+
+The library exports `createFindingBaseline(report, {owner, reason, kind?,
+expiresAt?})` and `compareFindings(report, baseline, {previousBaseline?, now?})`.
+Use `kind: "exception"` for explicit exceptions and an ISO UTC `expiresAt` when
+needed. Every entry requires an owner and reason. Expiration at or before the
+comparison clock fails. The CLI currently creates baseline entries; use the
+library or edit the schema-validated artifact to attach exception metadata.
+
+An identity includes the exact check, project, native rule, repository-relative
+file, line, severity and SHA-256 of the JSON-encoded diagnostic message. The ID
+hashes that ordered identity. Patterns are never expanded: an asterisk matches
+only a literal asterisk. Moving a finding or changing its message produces a new
+identity and makes the previous entry stale. Identical repeated findings retain
+an exact occurrence count. Forged IDs and duplicate entries are rejected.
+
+Each baseline entry is matched, stale, expired, changed in occurrence count, or
+unverified. Those five counts sum to the number of baseline entries. `current`
+and `new` count finding occurrences; `expanded` and `modified` count entries
+relative to a supplied previous baseline. Explicit maximum entry and exception
+counts are enforced. With a previous baseline, added identities, changed review
+metadata and raised limits fail. Removing an entry is allowed, but any surviving
+finding then becomes new. The previous artifact is operator supplied; the engine
+does not fetch it from Git or attest its provenance.
+
+Only parsers that establish complete native analysis expose
+`findingsComplete: true` for a failed check. Scope omissions, compile/loading
+errors, unparsed failures and older reports without the marker cannot be waived.
+Test failures cannot be converted into source exceptions. Missing checks and
+unknown tool identities prevent reconciliation from passing. A known policy
+failure takes precedence over incompleteness, while unverified counts remain
+visible. Stale entries fail even when another finding still fails the same check.
+
+`sourceVerified` means the supplied report records matching before/after source
+fingerprints without a source error. It does **not** mean comparison inspected
+current files, nor that an imported artifact is authentic. Obtain a fresh run
+when freshness matters. Fingerprint exclusions still apply.
+
+MCP `finding_comparison` accepts a retained `runId`, local `baseline` and optional
+`previousBaseline`. It cannot change root, trust, detail mode or clock. Summary
+output omits finding identities, paths and messages; detailed output includes
+entry IDs and statuses. The bounded in-memory report store still expires on
+restart. Baseline files are local policy artifacts and can contain project paths.
+
+Synthetic tests cover native ESLint findings, partial repairs, near-miss IDs,
+occurrence counts, stale/expired entries, limits, expansion, missing/partial
+evidence, CLI artifacts and MCP boundaries. Baselines do not claim semantic
+equivalence when source or native diagnostic wording changes.

package/docs/GO-RACE.md

@@ -0,0 +1,19 @@
+# Go race checking
+
+Select `go.test-race` explicitly. It runs `go test -race -json -count=1 ./...`
+with cgo enabled, automatic toolchain/dependency downloads disabled, and module
+edits disabled. The race detector writes to captured stderr and keeps its failing
+exit status. Native JSON evidence still requires completed, non-skipped tests.
+Defaults remain gofmt, vet and ordinary uncached tests; race instrumentation adds
+cost and requires the operator to select this check.
+
+The native fixture runs two workers repeatedly updating one shared counter. The
+unprotected version must fail with an actual `DATA RACE` diagnostic; atomic
+updates must pass and yield the exact combined count. A passing run cannot
+establish freedom from races on paths it did not execute. Native package/file evidence now makes excluded source and untested packages
+incomplete; see [Go scope](GO-SCOPE.md). A build/OS matrix is not implemented.
+
+A supported Go race platform and C compiler are required. Compilation and runtime
+errors are retained in detailed output; no compiler, library or toolchain is
+installed automatically. See the official [Go race detector documentation](https://go.dev/doc/articles/race_detector)
+for requirements and runtime coverage limits.

package/docs/GO-SCOPE.md

@@ -0,0 +1,63 @@
+# Go scope and Staticcheck
+
+`go.vet`, `go.test`, `go.test-race` and `go.staticcheck` first run native
+`go list -json ./...`. A passing result requires the union of native Go, cgo and
+internal/external test source files to exactly match the inventoried Go files.
+Malformed package output, missing packages, duplicate/unexpected files and load
+errors prevent completeness. Real diagnostic/test failures retain their failure
+status even when scope is incomplete.
+
+Files excluded by build tags, OS/architecture suffixes or Go directory conventions
+remain unverified. The current policy has no build-matrix or per-file exception
+contract, so such projects are conservatively incomplete. This includes intentional
+`testdata` Go files if they are inventoried but not compiled. Do not treat that as
+a source defect or remove valid platform-specific code to obtain a passing run.
+
+Test checks additionally require a passing native test in every selected package.
+An untested package, or one containing only skipped tests, cannot borrow evidence
+from a tested sibling. This proves package participation, not statement/branch
+coverage or assertion quality. Formatting still checks all inventoried Go files
+directly and does not require package selection.
+
+Go commands use `GOPROXY=off`, `GOTOOLCHAIN=local`, `GOFLAGS=-mod=readonly`,
+`GOWORK=off`, `GOENV=off` and an empty `GOCACHEPROG`. This keeps module validation
+independent of a surrounding workspace, persisted Go settings and custom cache
+programs. Cross-module workspace builds need a separate explicit profile. Native
+compiler/analyzer caches may be used; test result caching remains disabled.
+Dependencies and toolchains must be prepared separately.
+
+## Staticcheck
+
+Select `go.staticcheck` explicitly. It requires the installed `staticcheck`
+executable on the operator PATH. It runs with JSON diagnostics, all checks,
+test analysis, failure for all diagnostics, and surfaced ignored diagnostics.
+The command-level check selection overrides project `checks = ["-all"]`; inline
+ignored findings are retained as notes and still fail validation. Configured
+exact finding exceptions and baseline reconciliation are available separately in
+`FINDING-POLICY.md`; native source-suppression interpretation remains tool-specific.
+
+Normalized diagnostics carry native rule IDs and root-relative file/line evidence
+and can be exported to SARIF. Compiler diagnostics fail without inventing a source
+finding; malformed configuration/runtime errors are incomplete. Successful empty
+diagnostic output requires complete native package evidence and tool identity.
+
+Native evidence currently covers Go 1.27.1 and Staticcheck 2026.2.1 (module v0.8.1)
+on macOS arm64. Synthetic fixtures include a discarded pure-function result, its
+returned-value fix, disabled rule configuration, inline suppression, malformed
+configuration, excluded files, package test participation and native race checks.
+Hosted CI and other OS/tool combinations still require their own runs.
+
+Prepare the pinned development tool explicitly:
+
+```sh
+mkdir -p .checktrail/go-tools/bin
+GOBIN="$PWD/.checktrail/go-tools/bin" go install honnef.co/go/tools/cmd/staticcheck@v0.8.1
+npm run build
+node --test dist/test/go-scope.test.js dist/test/staticcheck.test.js
+```
+
+Preparation may download dependencies. Validation never performs that installation.
+
+References: [Go package listing](https://pkg.go.dev/cmd/go#hdr-List_packages_or_modules),
+[Staticcheck CLI](https://staticcheck.dev/docs/running-staticcheck/cli/),
+[Staticcheck source](https://github.com/dominikh/go-tools/tree/v0.8.1).

package/docs/GOLANGCI-LINT.md

@@ -0,0 +1,64 @@
+# Configured golangci-lint profile
+
+Select `go.golangci-lint` with exactly one project-local `.golangci.yml`,
+`.golangci.yaml` or `.golangci.json`. This initial profile verifies golangci-lint
+2.13.2 and supports selection of `errcheck`, `govet`, `ineffassign`, `staticcheck`
+and `unused`, using their native defaults. Choose `standard` or `none` for the
+default group, with explicit enable/disable lists. The always-on native type
+checker does not count as an enabled configured linter.
+
+```yaml
+version: "2"
+linters:
+  default: none
+  enable: [govet, staticcheck, unused]
+```
+
+Other linters, nonempty custom settings, formatters and Go build-version/tag
+profiles are incomplete until separately verified. This is deliberately a
+constrained profile, not support for every golangci-lint configuration. YAML
+duplicates, unsupported tags and excessive aliases are rejected. Planning only
+discovers the local config and source; parsing/native execution occurs with trust.
+
+The wrapper creates a temporary native configuration retaining linter selection.
+It disables fixes, change-only filtering, exclusion presets/paths/rules, generated
+file exclusion, issue-count limits and line deduplication. It forces test analysis,
+read-only module resolution, absolute JSON locations and no extra output files.
+Output and native analyzer cache use a fresh temporary directory, removed after
+normal completion. Existing project config and output paths are not rewritten.
+Native Go source accounting follows [the shared contract](GO-SCOPE.md).
+
+Native `nolint` and Staticcheck ignore directives are currently unsupported and
+make the check incomplete. The wrapper scans Go comment boundaries, including
+quoted/raw-string handling; matching text in strings or unrelated comments does
+not count as a suppression. A future exception policy must reconcile actual
+findings before these directives can be accepted. Tests and native tools remain
+trusted executable code, without a sandbox guarantee.
+
+Passing requires native JSON, at least one supported configured linter, no
+diagnostics or warnings, and complete package/file evidence. Diagnostics become
+normalized findings and fail. Unknown/duplicate active linters, omitted source,
+malformed evidence, runtime/configuration errors or missing tools are incomplete.
+
+Native synthetic tests cover a discarded return value and its fix; clean source;
+configured issue filtering/fixing/output paths; no active linters; rejected custom
+settings; real and literal suppression text; excluded Go source; and malformed
+YAML. The suite verifies original source bytes and absent output artifacts.
+Current evidence is Go 1.27.1 / golangci-lint 2.13.2 on macOS arm64.
+
+Development preparation is separate from validation:
+
+```sh
+mkdir -p .checktrail/go-tools/bin
+GOBIN="$PWD/.checktrail/go-tools/bin" go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
+npm run build
+node --test dist/test/golangci.test.js
+```
+
+Preparation may download dependencies. Consumer validation requires an installed
+binary on the operator PATH and never installs it. The hosted profile passed
+at `52ba415`; see `NATIVE-CI.md`.
+
+References: [CLI](https://golangci-lint.run/docs/configuration/cli/),
+[configuration](https://golangci-lint.run/docs/configuration/file/),
+[verified source version](https://github.com/golangci/golangci-lint/tree/v2.13.2).

package/docs/GUIDANCE.md

@@ -0,0 +1,46 @@
+# Advisory review guidance
+
+`guidance`, `retrieveGuidance()` and MCP `review_guidance` retrieve built-in review
+questions. They do not run project code, call a model, fetch references, inspect
+behavior or produce automated findings. Every response has `channel: advisory`
+and `automatedCoverage: false`; it has no validation outcome. An empty selection
+means no catalogue trigger matched, not that the project needs no review.
+
+```sh
+node dist/src/cli.js guidance --root examples/javascript
+node dist/src/cli.js guidance --root examples/javascript --topic package-consumers --detailed
+```
+
+Normal CLI/MCP retrieval plans the project without execution and selects questions
+by exact check IDs. Explicit topics add guidance. Each item matches if at least
+one check or topic matches; overlap returns the item once. Selection is ordered
+by the bundled catalogue. It is a deterministic lookup, not relevance ranking or
+source-code analysis. The catalogue's content digest and each item's version
+identify the actual guidance used.
+
+Available topics: `test-lifecycle`, `analysis-scope`, `package-consumers`,
+`python-imports`, `framework-assembly`, `execution-depth`. Guidance contains public
+references for further reading; those references are not claims that a selected
+project has a defect. Framework-specific references can illustrate a question
+whose application must be checked against the actual framework.
+
+Library callers can supply `{ schemaVersion: 1, checks: [], topics: [] }` directly.
+CLI `--input context.json` uses the same bounded schema and cannot be combined
+with `--topic`. Such inputs are declarations, not evidence that checks ran.
+Unknown well-formed check IDs match nothing; unknown topics, duplicate identifiers,
+unknown keys and oversized contexts fail. Input is capped at 16 KiB, 100 check IDs
+and 16 topics. No repository-supplied prose or executable guidance packs are loaded.
+
+Summary output includes the public question text, IDs, versions and references.
+It omits context and matched triggers. Detailed output includes both. Neither
+projection includes source excerpts, file paths or logs. Which questions were
+selected can still reveal aspects of a project's tooling.
+
+Native CLI and MCP tests verify execution-free retrieval, exact prefix/suffix
+boundaries, deterministic selection, non-mutable catalogue state and output
+controls. These are retrieval correctness tests. They do not establish improved
+review quality, defect detection rates or equivalence to another review workflow.
+
+For a selected-source context and an externally produced assessment, use the
+separate [review exchange](REVIEW-EXCHANGE.md). It reuses this catalogue but does
+not convert guidance or reviewer prose into automated findings.

package/docs/IMPACT-MEASUREMENT.md

@@ -0,0 +1,97 @@
+# Measuring Git selection impact
+
+The impact harness compares a full validation run with Git-selected validation on
+the same source snapshot and project policy. It measures whether failing checks
+are retained, which checks are omitted, disagreement between shared checks and
+the actual execution cost. This is a post-implementation synthetic development
+evaluation, not held-out evidence or a proof that a consumer's graph is complete.
+
+```sh
+npm run build
+node scripts/measure-impact.mjs > impact.json
+node scripts/verify-impact-container.mjs > impact-linux.json
+```
+
+Run these measurements sequentially without other test/build workloads. The
+container helper requires prepared, digest-pinned Node and Composer images; it
+copies the Node executable into private temporary storage and mounts it read-only
+alongside the checkout. The Composer image supplies Git. Measurement containers
+have external networking disabled. No project or dependency installation occurs
+during the measured operations.
+
+## Cases and checks
+
+`scripts/impact-corpus.json` freezes original case labels and expected selection
+before measurement. `scripts/impact-fixture.mjs` creates temporary repositories
+with fictional identities and a native Node test in each project:
+
+- `core` exports a value; `service` re-exports it; `web` consumes that export.
+  Service and web assertions check the value. Core only asserts its numeric type,
+  deliberately making consumer coverage necessary for detecting a wrong number.
+- `utility` has an independent value contract.
+- `other` reads a root settings file and an unowned shared module, exercising
+  conservative global fallback when either input changes.
+
+Cases cover a broken and valid producer edit, a leaf assertion defect, an
+independent defect, simultaneous changed owners, an explicitly incomplete graph,
+root/unowned changes, no changes and a deliberately misdeclared graph. Dependency
+edges are ordered against the transitive chain so closure must revisit them.
+The engine receives only the root and immutable synthetic base commit; expected
+labels are never passed to the worker.
+
+Every case first runs an unchanged full baseline and requires every native test to
+pass. After applying the edit, the harness runs fresh full and selected workers in
+alternating order, with repeated pairs. It verifies exact project sets, outcomes,
+positive test counts and named native assertion failures. An unrelated runtime
+failure does not count as the intended contract defect. Source and policy
+fingerprints must match across each pair, and source plus harness/runtime/corpus
+identities must remain unchanged throughout measurement.
+
+## What the observations mean
+
+The [macOS/Node 26 observations](measurements/impact-darwin-arm64-node26.json) and
+[Linux/Node 22 observations](measurements/impact-linux-arm64-node22.json) agree on
+selection and assertion outcomes in this corpus. Correct declarations retained
+the observed failing consumers. The explicit incomplete declaration retained the
+full run. Global and unowned changes also retained full validation.
+
+The deliberately misdeclared graph omitted the service-to-core dependency while
+asserting `complete: true`. Git selection ran only core and passed; full validation
+found the service and web assertions failing. The measurement retains this case
+and its missed failures in a separate group. This demonstrates a real limitation:
+selection relies on the maintainer's declared dependency graph and does not infer
+or verify every native import. Use full validation when that assertion cannot be
+supported. No confidence in graph completeness follows from a passing selected run.
+
+Each summary reconciles full failures into retained failures, omitted failures and
+changed results among checks run by both modes. Unexpected failures and incomplete
+check executions are reported separately. All expected case/repetition pairs must
+exist exactly once; malformed, missing or duplicate observations fail validation.
+Raw check/test/assertion evidence remains alongside the aggregates. Replacing
+transitive closure with a single edge pass was manually verified to omit web and
+fail the native consumer regression; the original code was restored and the test
+passed again. Snapshot tests
+recompute metrics and match the frozen corpus instead of trusting copied totals.
+
+## Timing and provenance
+
+Reports record raw full/selected wall time, worker engine time, engine CPU and peak
+RSS, native Node/Git identities, source/policy fingerprints and hashes of the corpus,
+harness, compiled engine artifacts and package lock. The report omits source text,
+raw native logs, absolute paths and temporary worktree identities. SHA-256 identifies
+the measured build; it does not attest a publisher or pin every system library.
+
+`wallMs` includes fresh worker startup/import and native execution. `engineMs` starts
+after worker imports. Engine CPU/RSS excludes native child resource use. Fixture
+creation, baseline preparation and cleanup are outside paired timings; baseline
+run measurements are stored separately. Git inspection has an execution cost, so
+fewer checks do not by themselves demonstrate reduced latency. The fixtures have
+small tests and are not representative of production suites.
+
+Repetitions are repeated observations of the same defects, not additional
+independent defect cases. Summary retention fractions use check executions and
+show their denominators; timing ratios are descriptive sums, not confidence
+intervals or promised speedups. Filesystem caches and host scheduling remain
+uncontrolled. macOS/Linux observations are separate environment profiles, not an
+isolated operating-system comparison. No prior private workflow, model tokens,
+provider cost or independent held-out corpus is measured here.

package/docs/INSTALLATION.md

@@ -0,0 +1,102 @@
+# Install the preview
+
+The first preview version is `0.1.0-alpha.1`, intended for npm's `next` tag.
+Check the [npm package page](https://www.npmjs.com/package/@stsepelin/checktrail)
+for availability. The registry commands below require that version to be published;
+before publication, use the source checkout or a reviewed local tarball.
+
+Use Node.js 22 or newer on macOS or Linux. Windows execution is not supported.
+Install each project's compilers, linters and test runners separately; Checktrail
+does not download them. Missing tools produce incomplete results.
+
+## CLI
+
+Install the exact version once:
+
+```sh
+npm install --global --ignore-scripts @stsepelin/checktrail@0.1.0-alpha.1
+checktrail --version
+```
+
+From the project you want to inspect:
+
+```sh
+checktrail plan --root "$PWD" --detailed
+```
+
+Planning only reads files. To execute checks on a project you trust:
+
+```sh
+checktrail run --root "$PWD" --trust-project --detailed
+```
+
+Exit `0` means the selected checks passed, `1` means at least one failed, and `2`
+means evidence is incomplete, execution is untrusted, or input is invalid. A passing
+result covers only the checks and files listed in the report. Native checks run
+with your user privileges; the tool is not a sandbox.
+
+## Claude Code
+
+From the project directory, register a read-only server scoped to that project:
+
+```sh
+claude mcp add --transport stdio --scope local checktrail -- \
+  checktrail serve --root "$PWD"
+claude mcp get checktrail
+```
+
+Restart the client if it is already running. Ask it to call `validation_plan` to
+inspect the selected checks. The tested Claude Code surface is connection and
+tool discovery; model-driven tool use is not part of the recorded measurement.
+
+## Codex CLI
+
+From the project directory:
+
+```sh
+codex mcp add checktrail -- checktrail serve --root "$PWD"
+codex mcp get checktrail
+```
+
+The server configuration is saved in your Codex configuration. Its root is the
+absolute directory captured when you run this command. Use a different server
+name for another project rather than expecting the root to follow your working
+directory. Restart an existing client session to load the configuration.
+
+Both clients need `checktrail` on their PATH. If the client cannot find it,
+use the absolute executable path reported by `command -v checktrail` in place
+of the second `checktrail` in the registration command. The first is the server
+name. Existing client policies may restrict which MCP servers can run.
+
+## Enable validation execution
+
+The examples above disable execution. To run tests and tools, remove the read-only
+entry (`claude mcp remove --scope local checktrail` or
+`codex mcp remove checktrail`) and repeat its registration command with
+`--allow-execution` after the root argument. Only enable this for a trusted project.
+An MCP tool call cannot grant itself this permission.
+
+Summary output is the default. Add `--detailed` to the server command only when
+the client may receive file paths, commands and raw diagnostics. An MCP client
+may forward the returned information to its model provider.
+
+Validation uses asynchronous calls and supports cancellation. Standard MCP Tasks
+is not advertised; the durable worker is a separate library API. See
+[client coverage](CLIENTS.md) and [MCP compatibility](MCP-COMPATIBILITY.md).
+
+## Before npm publication
+
+Build the public source checkout:
+
+```sh
+git clone https://github.com/stsepelin/checktrail.git
+cd checktrail
+npm ci --ignore-scripts
+npm run build
+node dist/src/cli.js plan --root examples/javascript --detailed
+```
+
+For a reviewed local package, replace the registry package argument in the install
+command with the absolute path to its `.tgz` file. The package's release review
+supplies its SHA-256; verify it before installing. This installs the same CLI and
+MCP entry point without requiring npm publication.