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

package/docs/RELEASE.md

@@ -1,42 +1,109 @@
-# Release preparation
+# Releases and publication
 
-The source is public at [stsepelin/checktrail](https://github.com/stsepelin/checktrail);
-`@stsepelin/checktrail@0.1.0-alpha.2` is published on npm. Its downloaded artifact
-matched the reviewed tarball with SHA-256
+The source is public at [stsepelin/checktrail](https://github.com/stsepelin/checktrail).
+The published preview is `@stsepelin/checktrail@0.1.0-alpha.4`.
+Its downloaded npm artifact and GitHub release asset match the reviewed SHA-256:
+
+```text
+4cc6dca5877b29cb452595c1c50233b0d377248f6f6e84e18ffe1b74b2031f8c
+```
+
+The [GitHub prerelease](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.4)
+and tag point to source commit `ebe7f5c114428aebc5084a2a33d38113cad13583` and include
+the same tarball plus `SHA256SUMS`. The [hosted release run](https://github.com/stsepelin/checktrail/actions/runs/35603451711)
+passed all jobs. The [MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.stsepelin%2Fchecktrail/versions/0.1.0-alpha.4)
+is active and matches `server.json`, with execution disabled. The Registry omits
+`isSecret: false`, whose schema default is false.
+
+Fresh public-registry installation verified CLI/library validation, generated
+npx startup with fresh/warm caches, onboarding, and MCP pass/fail/incomplete
+results, retained reports and execution denial. The exact artifact also passed
+offline installation, alpha.3 → alpha.4 → alpha.3 upgrade/rollback, the known UUID
+scope replay, Claude Code health/discovery and Codex direct MCP calls. A clean
+archive of the committed source, rebuilt with the same installed compiler and
+dependencies on the same host, produced an identical tarball. This does not
+establish cross-platform reproducibility.
+The [release record](measurements/release-alpha4.json) links these observations to
+the artifact; client profile limits remain in [CLIENTS.md](CLIENTS.md).
+
+## Alpha.5 candidate (unpublished)
+
+The current source metadata identifies `0.1.0-alpha.5`; it has not been published.
+Alpha.4 remains the public preview. Alpha.5 adds named per-check Go build-tag
+profiles in `checktrail.go-build.json`, with independent explicit exclusions.
+Native listing and execution use the same tags, including race and analyzer
+checks. Missing assignments, ambiguous declarations and stale exclusions cannot
+pass. Formatting still checks the full inventory. See [GO build profiles](GO-BUILD.md).
+
+Detailed plans/reports add optional `goBuild` profile/tag metadata. Summary output
+adds only `goBuildTagCount`, alongside the existing exclusion count. Older strict
+schema consumers must update before accepting these fields. Projects must choose
+between the new build-profile policy and the module-wide scope policy; combining
+both is rejected. Each selected check runs once. Repeated-check, cross-target and
+cross-compilation matrices remain unsupported.
+
+Alpha.4 does not understand the new build-profile sidecar. Rolling back preserves
+its bytes but does not apply its tags or exclusions. Revalidate after rollback;
+a project relying on profile-selected files can become incomplete. No claim of
+coverage transfers from one profile or package version to another.
+
+The installed MCP SDK 2.0.0 routing probe was repeated on 2026-09-22: standard
+Tasks remains unavailable and is not advertised by this candidate.
+
+The candidate also makes the task-retention regression deterministic by controlling
+its clock and checking the exact expiry boundary. Production retention logic is
+unchanged. CI action pins have been updated; npm dependency versions are unchanged.
+The source before release preparation passed all 13 [hosted jobs](https://github.com/stsepelin/checktrail/actions/runs/35614737518)
+after retrying an actionlint download that received HTTP 504. The release commit
+still needs its own hosted CI run. Candidate checks and artifact identity belong
+in the concrete release review; this section does not claim publication.
+
+## Alpha.4 scope
+
+Alpha.4 adds optional exact Go file exclusions in `checktrail.go-scope.json`.
+Native package evidence must account for each declared exclusion. Active, absent
+or otherwise unaccounted-for declarations cannot pass. Go formatting continues
+to cover the full source inventory, and race-test package discovery now uses the
+same `-race` constraints as execution. See [GO-SCOPE.md](GO-SCOPE.md).
+
+Detailed plan/report schemas add an optional `goScope` declaration and summaries
+add an optional `goExcludedFileCount`. Consumers that validate with older strict
+schemas must update their schemas before accepting these fields. The policy is
+opt-in; existing projects retain strict scope accounting. Dependencies are unchanged.
+
+Alpha.3 does not understand the new sidecar policy. The synthetic Go upgrade test
+verified that rollback keeps its bytes on disk but restores strict Go accounting:
+a project relying on exclusions becomes incomplete. Exclusions never establish
+validation of another platform or custom build-tag configuration. No cross-target
+execution is added.
+
+The installed MCP SDK routing probe was rechecked on 2026-09-21: standard Tasks
+remains unavailable; see [MCP-COMPATIBILITY.md](MCP-COMPATIBILITY.md). The release
+targets Node.js 22 or newer on macOS and Linux. The immutable tarball contains
+preparation-time candidate documentation; current source documentation records
+verified publication.
+
+## Distribution tags and previous releases
+
+`next` points to alpha.4. `latest` remains on alpha.1 because npm rejected its
+removal. Use exact versions; neither tag implies a stable release. Never republish
+an existing version. No credentials or automatic publishing workflow are stored here.
+
+The [alpha.3 prerelease](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.3)
+fixed the plain TypeScript adapter's unsupported `--noCheck` argument on the
+exercised TypeScript 4.9.5 profile, retaining the TypeScript 6.0.3 override and
+native file accounting. Vue and solution-build retain their separately verified
+versions; see [TYPESCRIPT.md](TYPESCRIPT.md). The [alpha.3 record](measurements/release-alpha3.json)
+preserves its source, artifact, CI and known mitt replay evidence.
+
+The [alpha.2 prerelease](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.2)
+introduced [setup and diagnosis](ONBOARDING.md), from source commit `4ce8398`.
+Its reviewed and downloaded artifact has 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.
+Its [hosted run](https://github.com/stsepelin/checktrail/actions/runs/35590670960)
+and fresh installation checks passed; its npm and Registry versions remain published.
+The historical alpha.2 [adoption record](PUBLIC-ADOPTION.md) remains unchanged;
+its initial failures are not rewritten as later-release successes.
 
 ## Prepared artifacts
 
@@ -54,8 +121,8 @@ outside the package allowlist until publication is verified.
   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. 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
+  exercised. The [hosted run at ebe7f5c](https://github.com/stsepelin/checktrail/actions/runs/35603451711)
+  passed all jobs for the alpha.4 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
@@ -91,7 +158,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.3.tgz \
+npm publish /absolute/path/reviewed-new-version.tgz \
   --tag next --access public --ignore-scripts --registry=https://registry.npmjs.org
 ```
 

package/docs/SETUP-SCOPES.md

@@ -0,0 +1,107 @@
+# Choose and understand setup coverage
+
+A repository can contain a runnable library, a documentation project and CI
+workflows. Each can need different tools. `init` proposes checks; `doctor` reports
+static setup gaps; only a trusted `run` produces validation evidence.
+
+Use the [installation guide](INSTALLATION.md) and inspect before writing:
+
+```sh
+checktrail init --root "$PWD"
+checktrail plan --root "$PWD" --detailed
+checktrail doctor --root "$PWD" --detailed
+```
+
+A `needs-selection` or `attention-required` result exits `2`. Read its JSON before
+choosing checks. These inspection commands do not run project scripts or install
+dependencies. Detailed output includes paths and may include absolute diagnostic paths.
+
+## A library with documentation and workflows
+
+Consider this original, generic repository:
+
+```text
+package.json                    scripts.test is "node --test"
+sum.test.js                     one passing Node test
+.github/workflows/verify.yml    a GitHub Actions workflow
+docs/requirements.txt           documentation dependencies
+docs/conf.py                    documentation configuration, no tests
+```
+
+Discovery identifies JavaScript and infrastructure at `.`, and Python at `docs`.
+The directory name does not prove that it is documentation, nor that it can be
+ignored: the operator knows its purpose. Checktrail does not infer a documentation
+build command from a Python manifest.
+
+`init` returns `needs-selection` for the Python project and writes nothing, even
+though the Node test command is recognized. Supplying a check for `.` does not
+select it for nested projects. For example, this explicit preview covers all three
+discovered ecosystems:
+
+```sh
+checktrail init --root "$PWD" \
+  --check '.#javascript.node-test' \
+  --check '.#infrastructure.actionlint' \
+  --check 'docs#python.unittest'
+```
+
+It produces a policy preview, but the choice of `unittest` is not evidence of tests
+in `docs`. If that policy is created with `--write`, `doctor --detailed` reports
+`unavailable-check` for `python.unittest`: no candidate test files were discovered.
+Choosing a runner merely to resolve setup selection does not validate documentation.
+Use a separately supported check or the project's own documentation build; keep
+that work outside Checktrail's coverage claim when no applicable adapter exists.
+
+## Prepare workflow validation separately
+
+`infrastructure.actionlint` is static workflow analysis. It does not execute CI
+jobs or validate their shell bodies. It needs both the prepared native executable
+and `checktrail.actionlint.json` beside the workflow repository root:
+
+```json
+{
+  "schemaVersion": 1,
+  "runnerLabels": [],
+  "variables": []
+}
+```
+
+The empty arrays declare no extra runner labels or configuration variables. Review
+actual workflow requirements before adopting those values. See [ACTIONLINT.md](ACTIONLINT.md)
+for the supported tool version, configuration, dependency checks and limitations.
+Without this configuration, diagnosis reports `unavailable-check`; without an
+executable on the effective PATH it also reports `missing-executable`. Prepare the
+tool explicitly, then repeat diagnosis. A successful Node test cannot supply this
+workflow evidence.
+
+## Interpret an intentionally narrowed policy
+
+After reviewing the desired scope, an operator may explicitly maintain a
+language-only policy. For the example above, it is:
+
+```json
+{
+  "schemaVersion": 1,
+  "projects": [{ "path": ".", "checks": ["javascript.node-test"] }]
+}
+```
+
+Edit an existing policy deliberately; `init --write` preserves it and cannot
+replace it or narrow its checks through `--check` arguments. Do not discard
+existing overlays, packs, environment requirements or workspace dependencies.
+
+With the language-only policy, the commands have different meanings:
+
+| Command                                                   | Result for this example                                                                             | Coverage                                               |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `checktrail doctor --root "$PWD" --detailed`              | `attention-required`, exit `2`; `unselected-project` for infrastructure at `.` and Python at `docs` | Workflow and documentation-project checks are omitted. |
+| `checktrail run --root "$PWD" --trust-project --detailed` | `passed`, exit `0`, if the Node test passes                                                         | The selected Node test only.                           |
+
+These results are consistent: validation passed its selected check while diagnosis
+reported broader discovered scope left unselected. `doctor` does not assess every
+possible check within a selected ecosystem either; selecting Node tests does not
+claim linting, typing, browser behavior or documentation coverage.
+
+Keep omitted work visible in your review and CI requirements. The
+[public adoption report](PUBLIC-ADOPTION.md) records these distinctions on pinned
+public projects; its historical results are not a claim about your repository.

package/docs/STATUS.md

@@ -3,17 +3,38 @@
 This is an experimental foundation with public source at
 [stsepelin/checktrail](https://github.com/stsepelin/checktrail).
 Check the [installation guide](INSTALLATION.md) for package availability and setup.
-The `0.1.0-alpha.2` preview is published on npm and active in the MCP Registry.
-The [hosted run at 4ce8398](https://github.com/stsepelin/checktrail/actions/runs/35590670960)
+The `0.1.0-alpha.4` preview is published on npm and active in the MCP Registry.
+The [hosted run at ebe7f5c](https://github.com/stsepelin/checktrail/actions/runs/35603451711)
 passed all jobs. The published tarball matched the reviewed artifact; fresh
 registry installation, CLI/library validation, generated npx startup and MCP
 execution/trust behavior were verified. Earlier toolchain evidence remains in
 `NATIVE-CI.md`; release details and tag limitations are in `RELEASE.md`.
-The GitHub alpha.2 prerelease includes the verified artifact and checksum.
-[Public adoption](PUBLIC-ADOPTION.md) records the published package on five pinned
-libraries, including incomplete coverage and a TypeScript 4.9.5 incompatibility.
+The GitHub alpha.4 prerelease includes the verified artifact and checksum.
+[Public adoption](PUBLIC-ADOPTION.md) records alpha.2 on five pinned libraries, including incomplete
+coverage and the TypeScript 4.9.5 incompatibility fixed in alpha.3.
 
-## Alpha.3 candidate (unpublished)
+## Alpha.5 candidate (unpublished)
+
+Package, engine and Registry metadata now identify `0.1.0-alpha.5`. The public
+preview remains alpha.4 until the candidate is approved, published and verified.
+
+- [Go build-tag profiles](GO-BUILD.md): each selected native check can use its own
+  named tags and exclusions. Listing and execution agree, formatting remains
+  whole-inventory, and missing or ambiguous assignments are unavailable. Each
+  check runs once; repeating checks across a target matrix is not implemented.
+
+## Alpha.4 release
+
+The [release record](measurements/release-alpha4.json) ties the published artifact
+to hosted CI, fresh installation, client profiles and upgrade/rollback checks.
+
+- [Go scope policy](GO-SCOPE.md): exact per-file declarations can acknowledge
+  native build-constraint exclusions. Go must confirm every exemption; stale
+  declarations and other omissions remain incomplete. Detailed reports retain
+  reasons and summaries show counts. Formatting still covers all source. Race
+  package listing now uses the same `-race` constraints as execution.
+
+## Alpha.3 release
 
 - [TypeScript compatibility](TYPESCRIPT.md): plain typechecking now passes the
   native 4.9.5 regression while retaining the 6.0.3 `noCheck` override and native
@@ -164,11 +185,10 @@ a general speedup/graph-completeness claim.
 
 ## Release preparation
 
-`server.json`, the npm package and the engine identify the unpublished
-`0.1.0-alpha.3` candidate. The currently published npm and Registry release is
-alpha.2. The candidate adds legacy TypeScript compatibility; publication requires
-its source commit to pass hosted CI and its exact tarball to pass release checks.
-Historical publication evidence and the candidate sequence are in `RELEASE.md`.
+`server.json`, the npm package and the engine identify the published
+`0.1.0-alpha.4` preview. Its source commit passed hosted CI, the published tarball
+matched the reviewed artifact, and fresh CLI/library/MCP installation checks passed.
+Publication evidence and the sequence for future releases are in `RELEASE.md`.
 
 ## Pinned pack distribution
 
@@ -526,15 +546,23 @@ performance claim follows from these samples.
 
 ## Next implementation work
 
-1. Broaden runtime matrices and native PHP tooling.
-2. Framework-specific scope and integration contracts.
-3. Framework integration and additional verified linter profiles.
-4. Additional ecosystem adapters and their native evidence.
-5. Semantic framework rules and native runtime collectors. Public check profiles,
-   finding ratchets and local private policy overlays are implemented; existing
-   private instruction files have not been migrated.
-6. Durable Tasks support after a compatible SDK passes the routing probe; the
-   lifecycle and persistence acceptance gates are in `MCP-COMPATIBILITY.md`.
+1. Extend the unreleased per-check [Go build-tag profiles](GO-BUILD.md) toward
+   repeated-check and target matrices only after their identities, aggregation
+   and native target evidence are defined. Existing profiles validate only each
+   selected check's configuration.
+2. Integrate standard MCP Tasks after a compatible SDK passes the routing probe.
+   Then verify negotiation, ordinary-call fallback, worker/store integration,
+   cancellation, restart and privacy together; see `MCP-COMPATIBILITY.md`.
+3. Extend independently authored evaluation cohorts to further implemented
+   language/rule families. Preserve frozen evidence and separate known-case
+   replays from independent measurements; see `ACCEPTANCE.md`.
+4. Broaden runtime/tool versions, framework contracts and native collectors only
+   with their own broken/fixed/near-miss evidence and required CI profiles;
+   see `LANGUAGES.md` and `NATIVE-CI.md`.
+5. Resolve the baseline, labeled public cases and adjudication for the planned
+   prior-workflow comparison; see `PRIOR-WORKFLOW-EVALUATION.md`. Existing private
+   instruction files have not been migrated, and publication does not establish
+   equal-or-better review quality.
 
 Complete dependency/tool/environment fingerprints, automatically inferred workspace graphs,
 remote/executable private plugins, native import-graph collection, remote serving, durable Tasks,

package/docs/TYPESCRIPT.md

@@ -1,8 +1,8 @@
 # TypeScript compiler compatibility
 
 The source checkout's `javascript.typescript` profile now supports the exercised
-TypeScript 4.9.5 and 6.0.3 configurations. This fix is included in the
-**unpublished alpha.3 candidate**. Published alpha.2 still passes an option that
+TypeScript 4.9.5 and 6.0.3 configurations. This fix is published in
+**0.1.0-alpha.3**. Published alpha.2 still passes an option that
 TypeScript 4.9.5 rejects. The original
 [public adoption record](PUBLIC-ADOPTION.md) remains unchanged as release evidence.
 Other compiler versions require their own native verification.

package/docs/measurements/go-scope-policy-replay.json

@@ -0,0 +1,91 @@
+{
+  "scope": "Known-case replay of an unreleased local package; excludes the JavaScript target without validating it; not an independent holdout",
+  "upstreamCommit": "2d3c2a9cc518326daf99a383f07c4d3c44317e4d",
+  "tarballSha256": "08069a85dc7863394a88218a1670a2e00381c7e176a1ae4c987ce8496a4c3e19",
+  "platform": "darwin",
+  "arch": "arm64",
+  "node": "v26.8.1",
+  "observations": [
+    {
+      "phase": "strict",
+      "outcome": "failed",
+      "checks": [
+        {
+          "id": "go.format",
+          "status": "failed"
+        },
+        {
+          "id": "go.vet",
+          "status": "inconclusive"
+        },
+        {
+          "id": "go.test",
+          "status": "inconclusive"
+        }
+      ],
+      "mcpCounts": [0, 0, 0]
+    },
+    {
+      "phase": "declared",
+      "outcome": "failed",
+      "checks": [
+        {
+          "id": "go.format",
+          "status": "failed"
+        },
+        {
+          "id": "go.vet",
+          "status": "passed"
+        },
+        {
+          "id": "go.test",
+          "status": "passed",
+          "tests": {
+            "total": 213,
+            "passed": 212,
+            "failed": 0,
+            "skipped": 1
+          }
+        }
+      ],
+      "mcpCounts": [0, 1, 1]
+    },
+    {
+      "phase": "failing-test",
+      "outcome": "failed",
+      "checks": [
+        {
+          "id": "go.format",
+          "status": "failed"
+        },
+        {
+          "id": "go.vet",
+          "status": "passed"
+        },
+        {
+          "id": "go.test",
+          "status": "failed",
+          "tests": {
+            "total": 214,
+            "passed": 212,
+            "failed": 1,
+            "skipped": 1
+          }
+        }
+      ],
+      "mcpCounts": [0, 1, 1]
+    }
+  ],
+  "baseCommit": "bc0b95a511706475df97d1472b4724b36dbc2848",
+  "goVersion": "go version go1.27.1 darwin/arm64",
+  "sources": {
+    "src/go-scope-policy.ts": "be40a2fa681fd5c320e36ea4608a972cb369e045227e1e3fd539f915444287f3",
+    "src/go-scope.ts": "cc85c48962b91ab4b88977a78f8bddc62e866f8d863c265ffe1b1cfd523a4895",
+    "src/adapters.ts": "ba2dab60ac9ecf20d9843285b614d62b4853f06972e2e27946fe0f8de01c4a61",
+    "src/evidence.ts": "477a82d4b40cb3480fa9d5b6ab2a0d41c06685f275fda0abb061219eb2a7a086",
+    "src/output.ts": "6befd79c5cc095137edd5b11c6f29622ffa22f9d924ed64152a085abef7da891",
+    "src/schemas.ts": "e5add92fee2727e50222757703c8dd786b72c6ebf2b40d1fcad4864961805ee2",
+    "src/types.ts": "c30a5c65903342148a7a07c210d6c0b5231295bbf7b1d94944a29c070289587c"
+  },
+  "harnessSha256": "acd5dcad4cc8fce8818963f48714cc8af8139720f64779a2dbc79d6fb4866c3f"
+}