@stsepelin/checktrail 0.1.0-alpha.1 → 0.1.0-alpha.3

package/docs/ACCEPTANCE.md

@@ -5,17 +5,25 @@ verification. It does not replace the plan or promote an unverified capability.
 Local implementation, local native evidence, hosted CI and publication are
 separate states. Follow the linked evidence for tested versions and limits.
 
-| Milestone                         | Implemented scope and evidence                                                                                                                                                                                                                                                                                                                                                                                                          | Open acceptance work                                                                                                                                                                                                                                                |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| M0: public contracts              | Original public fixtures, MIT license, security/contribution guidance, schemas, explicit package allowlist, dependency notices and CI definitions. `STATUS.md`, `SECURITY.md`, `RELEASE.md`.                                                                                                                                                                                                                                            | Public source is published and all hosted jobs passed at `52ba415`. The preview candidate still requires its own release commit, CI and publication verification.                                                                                                   |
-| M1: executable foundation         | Shared CLI/library/MCP engine, bounded inventory/runner, startup trust, native Node/Python/Go/PHP profiles, protocol and lifecycle regressions. `ARCHITECTURE.md`, `STATUS.md`, `MCP-COMPATIBILITY.md`. Fresh installed application-client profiles now have evidence in `CLIENTS.md`.                                                                                                                                                  | Application-client coverage beyond the named profiles. PHP remains unavailable when the consumer has no prepared runtime.                                                                                                                                           |
-| M2: practical language validation | Explicit JS/TS, Python, Go and PHP native tool profiles, structured diagnostics/test evidence, versions, environments, workspace selection, scope accounting, SARIF/JUnit and finding ratchets. `LANGUAGES.md`, adapter documents, `WORKSPACES.md`, `FINDING-POLICY.md`, `NATIVE-CI.md`.                                                                                                                                                | Hosted toolchain profiles passed at `52ba415`. Wider tool versions/framework configurations must be promoted separately; detection is not execution support.                                                                                                        |
-| M3: framework/contracts           | Native Laravel, Vue Router/Nuxt, Django/FastAPI assembly projections; imported runtime comparison, explicit architecture boundaries, producer/consumer schemas and a built package consumer. `RUNTIME-INVENTORY.md`, framework documents, `CONTRACTS.md`, `ARCHITECTURE-POLICY.md`, `examples/package-contract/README.md`.                                                                                                              | Broader native semantics/import collection and live service integration are not implemented. Synthetic evidence does not establish equivalent results in a private application; private integration feedback must remain private.                                   |
-| M4: ecosystem/distribution        | Bounded Rust, Java, C#, Ruby, Swift, Clang and actionlint profiles; trusted external adapters, pinned data-only pack distribution, fresh offline package checks, production notice audit, measured performance and unpublished registry metadata. `LANGUAGES.md`, `EXTERNAL-ADAPTERS.md`, `PACK-DISTRIBUTION.md`, `PERFORMANCE.md`, `RELEASE.md`.                                                                                       | Concrete preview release authorization and verification. Windows execution and the unimplemented subsequent integrations in `LANGUAGES.md` remain unsupported. Runtime/container/development dependency provenance is broader than the production npm notice audit. |
-| M5: measured assistance           | Advisory guidance, bounded Node mutation experiments, explicit-graph impact measurements, optional local/model review exchange, durable library task storage/worker, development evaluation and externally authored ESLint and Ruff integration cohorts. `GUIDANCE.md`, `MUTATIONS.md`, `IMPACT-MEASUREMENT.md`, `REVIEW-EXCHANGE.md`, `VALIDATION-TASKS.md`, `EVALUATION.md`, `EXTERNAL-EVALUATION.md`, `EXTERNAL-RUFF-EVALUATION.md`. | Standard MCP Tasks wire integration; wider held-out rule-family/review evidence, prior-workflow comparison and representative cost/latency measurement. No general equal-or-better review-quality claim is supported.                                               |
+| Milestone                         | Implemented scope and evidence                                                                                                                                                                                                                                                                                                                                                                                                          | Open acceptance work                                                                                                                                                                                                                           |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| M0: public contracts              | Original public fixtures, MIT license, security/contribution guidance, schemas, explicit package allowlist, dependency notices and CI definitions. `STATUS.md`, `SECURITY.md`, `RELEASE.md`.                                                                                                                                                                                                                                            | Public source, npm alpha.2 and its MCP Registry entry are published. Hosted CI passed at `4ce8398`; fresh registry installation was verified.                                                                                                  |
+| M1: executable foundation         | Shared CLI/library/MCP engine, bounded inventory/runner, startup trust, native Node/Python/Go/PHP profiles, protocol and lifecycle regressions. `ARCHITECTURE.md`, `STATUS.md`, `MCP-COMPATIBILITY.md`. Fresh installed application-client profiles now have evidence in `CLIENTS.md`.                                                                                                                                                  | Application-client coverage beyond the named profiles. PHP remains unavailable when the consumer has no prepared runtime.                                                                                                                      |
+| M2: practical language validation | Explicit JS/TS, Python, Go and PHP native tool profiles, structured diagnostics/test evidence, versions, environments, workspace selection, scope accounting, SARIF/JUnit and finding ratchets. `LANGUAGES.md`, adapter documents, `WORKSPACES.md`, `FINDING-POLICY.md`, `NATIVE-CI.md`.                                                                                                                                                | Hosted toolchain profiles passed at `52ba415`. Wider tool versions/framework configurations must be promoted separately; detection is not execution support.                                                                                   |
+| M3: framework/contracts           | Native Laravel, Vue Router/Nuxt, Django/FastAPI assembly projections; imported runtime comparison, explicit architecture boundaries, producer/consumer schemas and a built package consumer. `RUNTIME-INVENTORY.md`, framework documents, `CONTRACTS.md`, `ARCHITECTURE-POLICY.md`, `examples/package-contract/README.md`.                                                                                                              | Broader native semantics/import collection and live service integration are not implemented. Synthetic evidence does not establish equivalent results in a private application; private integration feedback must remain private.              |
+| M4: ecosystem/distribution        | Bounded Rust, Java, C#, Ruby, Swift, Clang and actionlint profiles; trusted external adapters, pinned data-only pack distribution, fresh offline package checks, production notice audit, measured performance and published MCP Registry metadata. `LANGUAGES.md`, `EXTERNAL-ADAPTERS.md`, `PACK-DISTRIBUTION.md`, `PERFORMANCE.md`, `RELEASE.md`.                                                                                     | npm tag cleanup remains unresolved. Windows execution and the unimplemented subsequent integrations in `LANGUAGES.md` remain unsupported. Runtime/container/development dependency provenance is broader than the production npm notice audit. |
+| M5: measured assistance           | Advisory guidance, bounded Node mutation experiments, explicit-graph impact measurements, optional local/model review exchange, durable library task storage/worker, development evaluation and externally authored ESLint and Ruff integration cohorts. `GUIDANCE.md`, `MUTATIONS.md`, `IMPACT-MEASUREMENT.md`, `REVIEW-EXCHANGE.md`, `VALIDATION-TASKS.md`, `EVALUATION.md`, `EXTERNAL-EVALUATION.md`, `EXTERNAL-RUFF-EVALUATION.md`. | Standard MCP Tasks wire integration; wider held-out rule-family/review evidence, prior-workflow comparison and representative cost/latency measurement. No general equal-or-better review-quality claim is supported.                          |
 
 ## Remaining work that can proceed locally
 
+[Public adoption measurements](PUBLIC-ADOPTION.md) now cover five pinned
+JavaScript, TypeScript, Python, Go and PHP libraries. They expose an older
+TypeScript compiler-option incompatibility and workflow/documentation/platform
+coverage friction. An [unreleased compiler fix](TYPESCRIPT.md) now passes the
+known TypeScript 4.9.5 case; workflow/documentation and platform coverage remain
+follow-up work. The observations do not establish full upstream CI coverage or
+general review effectiveness.
+
 1. Extend independently authored evaluation cohorts to additional implemented
    language/rule families, preserving the verifier freeze and recording exact
    selection, exclusions, native baselines and interpretation limits. New fixtures
@@ -43,11 +51,13 @@ run. The local worker/store are available independently; standard Tasks must sta
 unadvertised until routing and the integrated wire/lifecycle suite pass. See
 `MCP-COMPATIBILITY.md` for the reproduction and upstream issue.
 
-The public repository and initial commit `60131d6` are available on `main`.
-All 13 hosted jobs passed at `52ba415`, recorded in `NATIVE-CI.md`.
-That result identifies the source baseline, not an unpublished preview package. Package publishing, GitHub releases and registry
-registration have not been performed. The repository's explicit-action
-requirements still apply. `RELEASE.md` defines the concrete
+The public repository, npm preview `0.1.0-alpha.2` and its MCP Registry entry are
+published. The [hosted run at 4ce8398](https://github.com/stsepelin/checktrail/actions/runs/35590670960)
+passed all jobs, and fresh public installation was verified. Alpha.2 adds
+[setup commands](ONBOARDING.md). The [GitHub prerelease](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.2)
+is also published with the verified tarball and checksum. npm tag cleanup remains
+unresolved. The repository's explicit-action requirements still apply.
+`RELEASE.md` defines the concrete
 candidate checks and the authorization sequence; a local green run does not
 replace external acceptance.
 

package/docs/ARCHITECTURE.md

@@ -58,7 +58,9 @@ pass by a parser. Source changes during execution invalidate a green result.
 
 Use bounded process output and timeouts, terminate the process group on supported
 POSIX hosts, and propagate cancellation. No automatic dependency installation,
-source rewriting, infrastructure startup, deployment or repository mutation.
+source rewriting, infrastructure startup or deployment. The explicit `init --write`
+setup command can create a new `checktrail.json`; it preserves existing
+configuration and grants no execution. See [ONBOARDING.md](ONBOARDING.md).
 Executed project code still has the process user's privileges; this is not a
 sandbox. Tests may modify files or access networks and must be trusted accordingly.
 

package/docs/INSTALLATION.md

@@ -1,20 +1,24 @@
 # 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.
+The published preview is `0.1.0-alpha.2` on
+[npm](https://www.npmjs.com/package/@stsepelin/checktrail).
+Use the exact version below. `next` points to alpha.2; `latest` still points to
+alpha.1 because npm rejected its removal. Neither tag implies a stable release.
+Alpha.2 includes [project setup and diagnosis](ONBOARDING.md).
 
 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.
 
+For agent workflows, see [installing skills with `npx skills`](SKILLS.md).
+Skills install separately from the engine and MCP configuration.
+
 ## CLI
 
 Install the exact version once:
 
 ```sh
-npm install --global --ignore-scripts @stsepelin/checktrail@0.1.0-alpha.1
+npm install --global --ignore-scripts @stsepelin/checktrail@0.1.0-alpha.2
 checktrail --version
 ```
 
@@ -84,7 +88,7 @@ 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
+## Source checkout or unpublished candidate
 
 Build the public source checkout:
 

package/docs/LANGUAGES.md

@@ -1,5 +1,9 @@
 # Language and ecosystem roadmap
 
+The [setup guide](ONBOARDING.md) describes conservative
+per-language configuration proposals and static tool diagnosis. Setup does not
+extend the execution capabilities or native evidence listed below.
+
 Capability levels are discovery, planning, execution, structured evidence,
 semantic rules, and integration validation. None implies the next. This file's
 initial scope column describes the experimental implementation. Node, Python,
@@ -111,3 +115,13 @@ skip, so its aggregate pass count is not evidence for every native profile.
 The prepared CI language profiles and native container helpers require exact
 regression names through `NATIVE-CI.md`. Their required results are separate from
 the optional skips allowed by a developer's general test suite.
+
+[Public adoption measurements](PUBLIC-ADOPTION.md) record alpha.2 on pinned
+JavaScript, TypeScript, Python, Go and PHP libraries. TypeScript 4.9.5 rejects
+the adapter's `--noCheck` option; this older version is not verified support.
+Go platform exclusions remain inconclusive even when native tests exit zero.
+
+The unreleased [TypeScript compatibility fix](TYPESCRIPT.md) exercises plain
+TypeScript 4.9.5 and 6.0.3 using native capability-aware arguments. Published
+alpha.2 retains the recorded older-compiler limitation; Vue and solution-build
+profiles retain their separately verified versions.

package/docs/NATIVE-CI.md

@@ -22,6 +22,10 @@ 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.
 
+The main matrix also prepares the separately locked TypeScript 4.9.5 compiler
+from `scripts/typescript-legacy-tools/`. Its named native regression is mandatory
+in the `javascript` profile; root build tooling stays on its existing compiler.
+
 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,

package/docs/ONBOARDING.md

@@ -0,0 +1,133 @@
+# Project setup
+
+These commands are available in `0.1.0-alpha.2`. Follow the
+[installation guide](INSTALLATION.md), with Node.js 22+ on macOS/Linux.
+
+[Public adoption observations](PUBLIC-ADOPTION.md) show setup on real libraries,
+including nested documentation projects, workflow prerequisites and older compiler
+limitations. A narrowed policy can pass its selected checks while leaving other
+repository checks unverified.
+
+## Preview and create a policy
+
+```sh
+checktrail init --root "$PWD"
+checktrail init --root "$PWD" --write
+checktrail doctor --root "$PWD" --detailed
+```
+
+`init` returns JSON with a proposed `configuration`. The preview changes nothing.
+`--write` creates `checktrail.json` only when every discovered ecosystem has a
+selected supported check, publishing complete contents without replacing an
+existing file. A valid existing policy returns `preserved`, retaining its bytes,
+packs, environment requirements and workspace graph. Invalid policies, directories
+and symlinks are errors and remain untouched. There is no overwrite option.
+
+The preview includes relative project paths, groups ecosystems sharing a directory
+and preserves nested project boundaries. It does not infer workspace dependencies,
+grant execution, install tools, run scripts or import project code. Use `doctor`
+and the detailed plan to inspect prerequisites before running validation.
+
+| Ecosystem                          | Initial selection                                                                                                                                                |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| JavaScript / TypeScript            | Exact test scripts `node --test`, `vitest run`, `jest`, or `playwright test`; other commands need selection. Linters and type checks require explicit selection. |
+| Python                             | Explicit runner/check selection required; a manifest cannot identify a test framework.                                                                           |
+| Go                                 | Existing format, vet and test defaults.                                                                                                                          |
+| PHP                                | Syntax only; tests and analysis require explicit selection.                                                                                                      |
+| Rust, Java, C#, Ruby, Swift, C/C++ | Existing bounded adapter defaults; profiles, tools and dependencies still need preparation.                                                                      |
+| Infrastructure                     | GitHub Actions checking where applicable; other infrastructure remains an unresolved gap.                                                                        |
+
+`needs-selection` exits `2`, returns no partial configuration and writes nothing.
+Its `unresolved` entries list paths, ecosystems and registered choices; those
+choices do not promise tools are installed or applicable to every source file.
+Repeated `--check PATH#CHECK_ID` arguments select the complete check set for a path:
+
+```sh
+checktrail init --root "$PWD" --check '.#python.pytest' --check '.#python.ruff'
+checktrail init --root "$PWD" --check '.#python.pytest' --check '.#python.ruff' --write
+```
+
+Paths must exactly match discovered roots. For a polyglot directory, include
+checks for every discovered ecosystem there. Unmentioned paths keep defaults.
+Unknown and duplicate IDs are errors. Setup never silently drops unsupported
+ecosystems. External adapters and private overlays are supported by planning and
+diagnosis but are not generated by `init`.
+
+## Diagnose setup without execution
+
+`doctor` reuses the planner. It reports invalid configuration, unavailable checks,
+missing/non-executable programs, invalid JS tool metadata, missing required
+environment, empty plans, unsupported platforms and ecosystems omitted by policy.
+An intentionally narrowed policy can therefore produce `unselected-project`.
+
+Executable checks use the effective PATH and file permissions. Diagnosis never
+runs version commands, imports modules, boots frameworks or runs tests. Prepare
+native tools and activate Python environments on the PATH used for validation.
+
+Output always includes `validationPerformed: false` and unverified runtime
+properties. `no-static-blockers` exits `0`; `attention-required` exits `2`.
+Neither means validation passed. Tool compatibility, importable modules, services
+and execution results still need a trusted `run`.
+
+Summary output omits paths and raw errors. `--detailed` adds paths and diagnostic
+details that can contain absolute paths. Supported options include
+`--policy-overlay`, pinned `--adapter` references and `--allow-env NAME`.
+Environment values are not printed. Git selection and execution flags are rejected.
+
+## Generate MCP configuration
+
+```sh
+checktrail mcp-config --root "$PWD" --client codex
+checktrail mcp-config --root "$PWD" --client claude-code
+checktrail mcp-config --root "$PWD" --client claude-desktop
+checktrail mcp-config --root "$PWD" --client cursor
+checktrail mcp-config --root "$PWD" --client vscode
+```
+
+Output is JSON containing `format` and a `configuration` string. Merge the decoded
+string's server entry into the appropriate client configuration. The generator
+never opens or overwrites client files. Do not redirect the JSON envelope over
+an existing configuration.
+
+| Client         | Generated format / location                                   |
+| -------------- | ------------------------------------------------------------- |
+| Codex          | TOML `mcp_servers.checktrail`; Codex `config.toml`.           |
+| Claude Code    | JSON `mcpServers.checktrail`; project `.mcp.json`.            |
+| Claude Desktop | JSON `mcpServers.checktrail`; developer MCP configuration.    |
+| Cursor         | JSON `mcpServers.checktrail`; `.cursor/mcp.json`.             |
+| VS Code        | JSON `servers.checktrail`, `type: stdio`; `.vscode/mcp.json`. |
+
+Snippets capture the canonical absolute root and pin the generating engine version
+in `npx --yes --ignore-scripts @stsepelin/checktrail@VERSION serve`. Execution
+and detailed output remain disabled; client trust settings still apply. Roots
+containing `${` are rejected because client interpolation could change the root.
+
+Generation needs no network; starting npx may download the pinned package. The
+version must be published first. For an unpublished candidate, use its installed
+absolute `checktrail` executable with `serve --root /absolute/project` instead.
+After reviewing an update, regenerate/merge the entry and restart the client.
+Updating a global CLI does not change an npx version pin.
+
+Formats follow official [Codex](https://developers.openai.com/codex/mcp/),
+[Claude Code](https://code.claude.com/docs/en/mcp),
+[Cursor](https://cursor.com/docs/mcp), and
+[VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+documentation. Generation is not proof of a client connection; [CLIENTS.md](CLIENTS.md)
+records tested application profiles and limits.
+
+## Upgrade and rollback verification
+
+Build and prepare the npm cache for both reviewed artifacts, then run:
+
+```sh
+node scripts/verify-package-upgrade.mjs /absolute/baseline.tgz /absolute/candidate.tgz
+```
+
+The verifier installs baseline → candidate → baseline into one isolated consumer
+offline with lifecycle scripts disabled. Each stage checks the CLI version,
+planning, a native Node test, MCP planning and denied untrusted execution. Project
+source, policy and existing client configuration must remain byte-identical.
+The candidate must preserve the policy through `init --write`, diagnose it, and
+import the baseline report through SARIF export. Output records artifact hashes
+and measured stages. This exercises a synthetic Node workflow, not migration of
+every language/tool profile.

package/docs/PUBLIC-ADOPTION.md

@@ -0,0 +1,116 @@
+# Public repository adoption: alpha.2
+
+This exercise measures installation, policy setup and selected native checks on
+public libraries. It uses the published alpha.2 artifact, not an edited engine.
+The [selection plan](../scripts/public-adoption-plan.json) pins every upstream
+commit. Upstream sources and their licenses remain in ignored local checkouts;
+no upstream source is included in Checktrail's package or this report.
+
+The projects were chosen for a small initial-language adoption sample, before
+validation results were known. They were not replaced after failures. This is
+not a randomized sample, an independent rule-effectiveness holdout, a replacement
+for upstream CI, or a measurement of general false-positive rates.
+
+## Observations
+
+The [measurement record](measurements/public-adoption-alpha2.json) separates the
+policy created by `init` from an explicitly narrowed, root-language-only policy.
+`doctor` continues to identify omitted ecosystems in the narrower policy.
+A passing selected check does not mean the entire repository was validated.
+
+| Public project                                                                                                   | Selected language checks        | Native baseline and alpha.2 observation                                                                                                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Nano ID](https://github.com/ai/nanoid/tree/57009b5eb8d757ae39bf5f4361dd30c9f23391b7)                            | Node tests                      | Both ran 79 tests successfully. The full policy remains incomplete without workflow configuration/tooling. Benchmark, browser tooling, size, prebuild, lint and declaration validation were not included.                                                   |
+| [mitt](https://github.com/developit/mitt/tree/6b41670516ed8e8b738612f60491995470aa63b3)                          | TypeScript 4.9.5                | Initial native checking needs the generated root declaration. After generating it, native typechecking passes; alpha.2 still fails with TS5023 because this compiler does not support `--noCheck`. Mocha and other package scripts were not run.            |
+| [more-itertools](https://github.com/more-itertools/more-itertools/tree/1da45ae4b61a832ed080f08a8833784aad0a9534) | unittest, Python 3.12           | Both ran 928 tests successfully. Full setup also discovers workflows and a separate documentation project; its selected unittest check has no candidate tests. Documentation builds, type stubs and workflow validation remain outside the narrowed result. |
+| [google/uuid](https://github.com/google/uuid/tree/2d3c2a9cc518326daf99a383f07c4d3c44317e4d)                      | gofmt, vet and tests, Go 1.27.1 | Native test events report 212 passes and one skip. Both formatting checks report the same seven files. Checktrail marks vet/tests inconclusive because the native platform selection omits `node_js.go`; the formatting failure makes the aggregate failed. |
+| [PSR Log](https://github.com/php-fig/log/tree/f16e1d5863e37f8d8c2a01719f5b34baa2b714d3)                          | PHP 8.4 syntax                  | All eight files pass native and Checktrail syntax checks. Host diagnosis reports PHP missing; prepared Linux execution succeeds. This provides no type, behavior or test evidence.                                                                          |
+
+Counts above describe this pinned snapshot and are reconciled with the linked
+record. Go's zero exit status from `gofmt -l` does not mean formatted source;
+its listed paths are findings. Its skipped test and platform-excluded file are
+retained instead of turning native exit zero into complete validation.
+
+Each checkout received an original, temporary failing control. Node, Python, Go
+and PHP detected the intended failure. Go retained its existing skip and formatting
+findings. TypeScript's native run diagnosed the inserted TS2322 error, but alpha.2
+stopped at the unsupported compiler option; that is not credited as detection.
+Controls were removed in `finally`, and tracked upstream file hashes remained
+unchanged. `init --write` preservation was checked byte for byte, and read-only
+operations were checked against the project tree.
+
+## What this changes in the roadmap
+
+- TypeScript needs a capability/version preflight for older compilers, with a
+  clear unavailable-tool explanation, or an explicitly tested compatible invocation.
+  Alpha.2's existing native verification covers TypeScript 6.0.3; this exercise
+  does not extend that support to 4.9.5.
+- Setup guidance should distinguish an executable language profile from workflow
+  tooling and documentation projects. Explicit narrowing must keep the omitted
+  coverage visible.
+- Go needs an explicit policy for platform/build-tag coverage before a developer
+  can distinguish intentional target exclusions from accidentally missed source.
+  This observation does not justify silently ignoring excluded files.
+
+These are recorded adoption gaps, not fixes applied to the immutable alpha.2
+package. No new engine version is published by this exercise.
+
+## Unreleased follow-up
+
+The [compiler compatibility fix](TYPESCRIPT.md) now passes a known-case mitt replay
+with TypeScript 4.9.5 through a locally packed CLI, library and MCP. The observations
+above still describe published alpha.2; they are not replaced by the fixed source
+checkout's results. Workflow/documentation setup and Go platform coverage remain
+separate work.
+
+## Reproduce
+
+Use macOS arm64 with Node 26.8.1 and Go 1.27.1 to reproduce the recorded host
+profile. PHP and Python use the image identities in the measurement record;
+Docker execution disables networking and mounts project inputs read-only.
+The host does not impose an OS network sandbox. No Sail is used.
+
+Download the tarball and `SHA256SUMS` from the
+[alpha.2 GitHub release](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.2),
+then verify SHA-256
+`ffd0564f40a12a238a52fe25fe8c34fb36cf6f6480be7b6994bab82a3bd657fb`.
+The original measurement installed the exact version from npm; reproduction
+installs that same verified tarball with lifecycle scripts disabled.
+
+```sh
+node scripts/prepare-public-adoption.mjs /new/adoption-directory /absolute/release.tgz
+```
+
+Preparation downloads pinned public Git revisions and installs the engine and
+explicit TypeScript tools. It does not run upstream package scripts. The TypeScript
+tool profile is compiler 4.9.5 plus `@types/chai` 4.3.20, `@types/mocha` 7.0.2,
+`@types/sinon` 9.0.11 and `@types/sinon-chai` 3.2.12. The preparation lockfile records
+transitive dependency resolutions; it is not an upstream lockfile or a claim that
+all upstream build/test dependencies were installed.
+
+Prepare the Python/Node image using `scripts/external-tools.Dockerfile`, and the
+PHP/Node image using `scripts/adoption-php.Dockerfile`. Compare local image IDs
+with the record. A rebuilt image may have a different ID: a run with different
+image bytes is a new environment observation, not a reproduction of that exact
+runtime. The recorded Python image must already be present for this harness.
+
+```sh
+docker build --network=none --pull=false -f scripts/adoption-php.Dockerfile -t checktrail-adoption-php:alpha2 scripts
+CHECKTRAIL_ADOPTION_PHP_IMAGE="$(docker image inspect checktrail-adoption-php:alpha2 --format '{{.Id}}')" \
+  node scripts/measure-public-adoption.mjs /new/adoption-directory /absolute/release.tgz
+```
+
+Measurement downloads nothing. It verifies installed engine files against the
+reviewed artifact, checks upstream revisions and tracked hashes, measures both
+policy scopes, compares native accounting, and applies/removes the original
+controls. mitt's generated declaration is prepared separately with the installed
+compiler and removed afterwards. Fresh checkouts are required for another run;
+the harness preserves detailed local evidence and created policies for inspection.
+
+Raw process outputs stay under the prepared directory's `observations/` folder.
+The committed record contains relative file names, counts, diagnostic codes,
+versions, hashes, outcomes and timing observations, not source or raw tool prose.
+Timings include CLI/process startup and, for containers, Docker invocation; cache
+state, native/wrapper order and scheduling are uncontrolled. They do not support
+a representative speed comparison. No model is invoked and no prior human/model
+review workflow is compared.

package/docs/RELEASE.md

@@ -1,12 +1,42 @@
 # 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.
+`@stsepelin/checktrail@0.1.0-alpha.2` is published on npm. Its downloaded artifact
+matched the reviewed tarball with SHA-256
+`ffd0564f40a12a238a52fe25fe8c34fb36cf6f6480be7b6994bab82a3bd657fb`.
+Fresh registry installation, CLI/library validation, generated npx startup with
+fresh/warm caches and MCP pass/fail/incomplete results were verified. Alpha.2 adds
+[setup and diagnosis](ONBOARDING.md). The
+[MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.stsepelin%2Fchecktrail/versions/0.1.0-alpha.2)
+is active and matches the alpha.2 release metadata, with execution disabled. The Registry omits
+`isSecret: false`, whose schema default is false. No credentials or automatic
+publishing workflow are stored here.
+The [GitHub prerelease](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.2)
+points to source commit `4ce8398` and includes the same tarball plus `SHA256SUMS`.
+The downloaded release asset was verified against the digest above.
+
+Publication is configured for npm's `next` tag. After alpha.1 publication, the
+registry assigned both `next` and `latest` to that preview; attempts to remove
+`latest` returned HTTP 400. Alpha.2 publication updated `next` while leaving
+`latest` on alpha.1. Cleanup remains unresolved; use exact versions, do not treat
+`latest` as evidence of a stable release, and never republish an existing version.
+
+## Alpha.3 candidate (unpublished)
+
+The source candidate is `0.1.0-alpha.3`. It fixes the plain TypeScript adapter's
+unsupported `--noCheck` argument on the exercised TypeScript 4.9.5 profile, while
+retaining the TypeScript 6.0.3 override and native file accounting. Vue uses the
+same capability helper with its existing verified modern toolchain; the separate
+solution-build profile remains gated to TypeScript 6.0.3. See [TYPESCRIPT.md](TYPESCRIPT.md).
+No dependencies or report/policy schemas change in this release preparation.
+The alpha.2 adoption record remains historical evidence.
+
+The candidate still targets Node.js 22 or newer on macOS and Linux. It does not
+add standard MCP Tasks or legacy Vue support. Registry metadata keeps execution
+disabled by default. Publication will use npm's `next` tag after release checks
+and hosted CI succeed; the alpha.2 publication evidence above does not verify
+this candidate. Exact artifact, client and upgrade/rollback evidence is retained
+outside the package allowlist until publication is verified.
 
 ## Prepared artifacts
 
@@ -24,8 +54,8 @@ publishing workflow are stored in this repository.
   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
+  exercised. The [hosted run at 4ce8398](https://github.com/stsepelin/checktrail/actions/runs/35590670960)
+  passed all jobs for the alpha.2 release commit. 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
@@ -61,7 +91,7 @@ After explicit approval and npm authentication for the `@stsepelin` scope, publi
 the approved file, not a newly packed working tree:
 
 ```sh
-npm publish /absolute/path/stsepelin-checktrail-0.1.0-alpha.1.tgz \
+npm publish /absolute/path/stsepelin-checktrail-0.1.0-alpha.3.tgz \
   --tag next --access public --ignore-scripts --registry=https://registry.npmjs.org
 ```
 
@@ -93,6 +123,8 @@ GitHub private vulnerability reporting is enabled. Use the channel linked in
    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.
+   Run `scripts/verify-package-upgrade.mjs` with the reviewed previous and candidate
+   tarballs to verify offline upgrade, policy/report compatibility and rollback.
 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;

package/docs/SKILLS.md

@@ -0,0 +1,123 @@
+# Install agent skills with npx skills
+
+Checktrail provides portable workflows for setup, validation and review:
+
+| Skill                 | Use it for                                                                     |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `checktrail-setup`    | Configure project roots, select supported language checks and connect MCP      |
+| `checktrail-validate` | Run authorized checks and distinguish passed, failed and incomplete evidence   |
+| `checktrail-review`   | Review code and test adequacy using validation evidence and advisory questions |
+
+Each skill is self-contained in `skills/<name>/SKILL.md` and follows the
+[Agent Skills format](https://agentskills.io/specification). The
+[Vercel skills CLI](https://github.com/vercel-labs/skills) installs these folders
+from GitHub. No Checktrail plugin or separate skills registry registration is
+required for installation by repository URL.
+
+## Install
+
+These GitHub commands require the `skills/` directory to be present on the public
+repository's default branch. For an unpublished checkout, use the local command
+below. Listing the remote source first verifies what is available:
+
+```sh
+npx skills add stsepelin/checktrail --list
+npx skills add stsepelin/checktrail
+```
+
+The interactive installer lets you choose skills and target agents. For an
+explicit project installation, run from the repository where you want to use
+Checktrail:
+
+```sh
+npx skills add stsepelin/checktrail \
+  --skill checktrail-setup checktrail-validate checktrail-review \
+  --agent codex claude-code cursor
+```
+
+Choose only the agents you use. Add `--global` for a personal installation shared
+across projects, or `--yes` when deliberately skipping installer prompts. The
+default installation uses project directories; it does not configure an MCP server.
+Use `--copy` if independent copies are preferable to the installer's default links.
+
+To install from a local checkout before pushing, substitute its absolute path:
+
+```sh
+npx skills add /absolute/path/to/checktrail --skill checktrail-validate --agent codex
+```
+
+The CLI's agent target names are installer options, not evidence that Checktrail
+has been tested end-to-end in every editor. See [client coverage](CLIENTS.md).
+Reload skills or start a new session as required by the selected agent. Example
+requests are "Set up Checktrail for this repository", "Validate these changes
+with Checktrail", and "Review this diff using Checktrail evidence".
+
+## Install the engine separately
+
+`npx skills` installs instructions. It does not install the npm engine, native
+language tools, an MCP server, or execution permissions. The skills support an
+existing MCP connection or the CLI, including the published preview:
+
+```sh
+npx --yes --ignore-scripts @stsepelin/checktrail@0.1.0-alpha.1 plan --root /absolute/project
+```
+
+Use Node.js 22+ on macOS or Linux. See [installation](INSTALLATION.md) for persistent
+CLI installation, MCP registration and operator-controlled execution. Skills do
+not expand native language coverage, grant trust, or replace required CI checks.
+
+## Update and remove
+
+For GitHub-installed project skills, update just Checktrail's workflows:
+
+```sh
+npx skills update checktrail-setup checktrail-validate checktrail-review --project
+```
+
+Use `--global` instead of `--project` for a global installation. Updates replace
+installed instructions; keep project-specific policy in your project's own files.
+Retain and review the project installation's `skills-lock.json` and file changes.
+For local-path installations, re-run `skills add` against the updated checkout.
+
+The installer version used for local verification is `skills@1.7.0`. It aliases
+`skills check` to `skills update`; do not use `check` as a read-only update probe.
+Use `npx skills list` to inspect installed skills. Pin the installer itself with
+`npx skills@1.7.0` when reproducing the installation checks.
+
+Skill updates and engine updates are separate. The skills declare the Checktrail
+version they target. To update the engine, deliberately select a compatible npm
+version and restart the MCP process. Updating skills never changes its root,
+execution grant or output disclosure settings. For a reproducible skill revision,
+install from a reviewed GitHub tree URL containing a commit SHA and the selected
+skill path; re-add that same revision to roll back. Do not treat following a branch
+as an immutable pin.
+
+Remove the project skills with:
+
+```sh
+npx skills remove checktrail-setup checktrail-validate checktrail-review
+```
+
+Add `--global` for a global removal. This removes skills, not the separately
+installed engine or MCP configuration.
+
+## Verification boundaries
+
+Local checks exercise discovery, selective installation, copy/link destinations,
+file integrity, reinstallation from an updated local source and removal in
+temporary projects. They do not modify personal agent installations. Skill format
+validation does not prove model behavior or improved review quality. Installation
+from the public GitHub source and remote update verification require the changes
+to be pushed; a local installation is not evidence of either.
+
+Reproduce the installation checks from the Checktrail checkout:
+
+```sh
+npm install --prefix .checktrail/skills-tools --ignore-scripts --no-audit --no-fund \
+  --package-lock=false --save-exact skills@1.7.0
+node scripts/verify-skills-install.mjs .checktrail/skills-tools/node_modules/skills/bin/cli.mjs
+```
+
+The helper uses temporary project and installer-state directories, exercises the
+real installer, and removes its fixtures afterward. It does not run a model,
+register MCP, install global skills, or invoke remote skill updates.