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

package/README.md

@@ -4,7 +4,7 @@ Local code validation with a CLI, MCP tools, and evidence of what actually ran.
 
 Formerly Repo Verifier. See the [rename guide](docs/RENAMING.md) for existing source checkouts.
 
-**Published preview: 0.1.0-alpha.3.** Public source is available at
+**Published preview: 0.1.0-alpha.4.** Public source is available at
 [stsepelin/checktrail](https://github.com/stsepelin/checktrail).
 See [implementation status](docs/STATUS.md), the [plan](docs/PLAN.md) and the
 [language matrix](docs/LANGUAGES.md) before relying on an adapter.
@@ -20,13 +20,14 @@ acceptance work; [client checks](docs/CLIENTS.md) record actual application cove
 pinned libraries, including setup friction and compatibility gaps.
 Alpha.3 fixes the recorded [TypeScript 4.9.5 incompatibility](docs/TYPESCRIPT.md).
 The [setup scope guide](docs/SETUP-SCOPES.md) explains language, documentation and workflow coverage.
-The local checkout prepares **0.1.0-alpha.4**, adding explicit [Go scope exclusions](docs/GO-SCOPE.md)
-and matching race-test package discovery. Alpha.4 is not published yet.
+Alpha.4 adds explicit [Go scope exclusions](docs/GO-SCOPE.md) and matching
+race-test package discovery. Its [release record](docs/measurements/release-alpha4.json)
+includes package, client and upgrade/rollback verification.
 
-The [hosted matrix](https://github.com/stsepelin/checktrail/actions/runs/35597877167)
-passed at release commit `b0b447d` on Linux and macOS. The exact npm tarball and
+The [hosted matrix](https://github.com/stsepelin/checktrail/actions/runs/35603451711)
+passed at release commit `ebe7f5c` on Linux and macOS. The exact npm tarball and
 fresh CLI/MCP installations were verified. The
-[MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.stsepelin%2Fchecktrail/versions/0.1.0-alpha.3)
+[MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.stsepelin%2Fchecktrail/versions/0.1.0-alpha.4)
 is active; execution remains disabled by default.
 
 Checktrail discovers projects, plans registered checks, invokes native tools
@@ -188,6 +189,9 @@ selection with inventoried source; `go.staticcheck` adds explicit all-rule analy
 and normalized findings. See [Go scope](docs/GO-SCOPE.md). The constrained
 [`go.golangci-lint` profile](docs/GOLANGCI-LINT.md) accepts explicit native linter
 selection while disabling hidden issue filters and fixes.
+The alpha.5 source candidate adds [Go build-tag profiles](docs/GO-BUILD.md)
+with one explicit configuration per selected native check. Alpha.4 does not
+include this capability; a runnable example is in `examples/go-build`.
 
 `php.phpstan` combines per-file analysis accounting with native JSON diagnostics.
 See the [PHPStan contract](docs/PHPSTAN.md).

package/dist/src/adapters.js

@@ -1,3 +1,4 @@
+import { applyGoBuildPolicy } from "./go-build.js";
 import { applyGoScopePolicy } from "./go-scope-policy.js";
 import { actionlintCheck, workflowRoot } from "./actionlint.js";
 import { clangCheck } from "./clang.js";
@@ -356,6 +357,7 @@ export async function checksFor(source, project, requested) {
         if (explicit)
             checks.push(await golangciCheck(source, project));
         await applyGoScopePolicy(source, project, checks);
+        await applyGoBuildPolicy(source, project, checks);
         return checks;
     }
     if (project.adapter === "infrastructure") {

package/dist/src/evidence.js

@@ -173,6 +173,7 @@ function goTests(text, allowPackageFailures = false) {
 export function evaluate(check, processes, root) {
     const result = {
         ...(check.goScope ? { goScope: check.goScope } : {}),
+        ...(check.goBuild ? { goBuild: check.goBuild } : {}),
         ...(check.external ? { external: check.external } : {}),
         id: check.id,
         adapter: check.adapter,

package/dist/src/go-build.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import type { Check, Inventory, Project } from "./types.js";
+export declare const goBuildTagsSchema: z.ZodArray<z.ZodString>;
+export declare const goBuildSelectionSchema: z.ZodObject<{
+    profile: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const goBuildPolicySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    profiles: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tags: z.ZodArray<z.ZodString>;
+        checks: z.ZodArray<z.ZodEnum<{
+            "go.vet": "go.vet";
+            "go.test": "go.test";
+            "go.test-race": "go.test-race";
+            "go.staticcheck": "go.staticcheck";
+            "go.golangci-lint": "go.golangci-lint";
+        }>>;
+        excludedFiles: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type GoBuildSelection = z.infer<typeof goBuildSelectionSchema>;
+export declare function applyGoBuildPolicy(source: Inventory, project: Project, checks: Check[]): Promise<void>;

package/dist/src/go-build.js

@@ -0,0 +1,113 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { goScopePolicySchema } from "./go-scope-policy.js";
+import { readProjectFile } from "./inventory.js";
+const nativeCheck = z.enum([
+    "go.vet",
+    "go.test",
+    "go.test-race",
+    "go.staticcheck",
+    "go.golangci-lint",
+]);
+export const goBuildTagsSchema = z
+    .array(z
+    .string()
+    .max(64)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/))
+    .max(32);
+export const goBuildSelectionSchema = z.strictObject({
+    profile: z
+        .string()
+        .max(64)
+        .regex(/^[A-Za-z][A-Za-z0-9_-]*$/),
+    tags: goBuildTagsSchema,
+});
+export const goBuildPolicySchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    profiles: z
+        .array(z.strictObject({
+        name: goBuildSelectionSchema.shape.profile,
+        tags: goBuildTagsSchema,
+        checks: z.array(nativeCheck).min(1).max(5),
+        excludedFiles: goScopePolicySchema.shape.excludedFiles,
+    }))
+        .min(1)
+        .max(5),
+});
+export async function applyGoBuildPolicy(source, project, checks) {
+    const file = path.posix.join(project.path, "checktrail.go-build.json");
+    const scoped = checks.filter((check) => check.id !== "go.format");
+    try {
+        let entry;
+        try {
+            entry = await lstat(path.join(source.root, file));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        if (!entry.isFile() || !source.files.includes(file))
+            throw new Error("Go build policy must be an inventoried regular file");
+        try {
+            await lstat(path.join(source.root, project.path, "checktrail.go-scope.json"));
+            throw new Error("Use either Go build profiles or the module scope policy, not both");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const policy = goBuildPolicySchema.parse(JSON.parse(await readProjectFile(source.root, file)));
+        const profiles = new Map();
+        const names = new Set();
+        for (const profile of policy.profiles) {
+            if (names.has(profile.name))
+                throw new Error("Duplicate Go build profile name");
+            names.add(profile.name);
+            if (new Set(profile.tags).size !== profile.tags.length)
+                throw new Error("Duplicate Go build tag");
+            const paths = profile.excludedFiles.map((item) => item.path);
+            if (new Set(paths).size !== paths.length ||
+                paths.some((p) => !project.files.includes(p)))
+                throw new Error("Go build exclusions must name unique inventoried project files");
+            for (const id of profile.checks) {
+                if (profiles.has(id))
+                    throw new Error("A Go check can select only one build profile");
+                profiles.set(id, profile);
+            }
+        }
+        for (const check of scoped) {
+            const profile = profiles.get(check.id);
+            if (!profile) {
+                check.unavailableReason = "Selected Go check has no build profile";
+                continue;
+            }
+            check.goBuild = { profile: profile.name, tags: [...profile.tags] };
+            check.goScope = {
+                schemaVersion: 1,
+                excludedFiles: profile.excludedFiles,
+            };
+            for (const command of check.commands) {
+                if (command.executable === "go" ||
+                    command.executable === "staticcheck") {
+                    const index = command.args.indexOf("./...");
+                    if (index < 0)
+                        throw new Error("Unsupported Go build command");
+                    if (profile.tags.length)
+                        command.args.splice(index, 0, `-tags=${profile.tags.join(",")}`);
+                }
+                else if (check.id === "go.golangci-lint") {
+                    command.args[3] = JSON.stringify(profile.tags);
+                }
+                else
+                    throw new Error("Unsupported Go build command");
+            }
+        }
+    }
+    catch (error) {
+        for (const check of scoped)
+            check.unavailableReason =
+                error instanceof Error ? error.message : "Invalid Go build policy";
+    }
+}

package/dist/src/golangci-runner.js

@@ -1,3 +1,4 @@
+import { goBuildTagsSchema } from "./go-build.js";
 import { spawnSync } from "node:child_process";
 import { mkdtemp, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -31,9 +32,10 @@ const configuration = z.strictObject({
     formatters: z.record(z.string(), z.unknown()).optional(),
 });
 async function main() {
-    const [root, configFile, ...files] = process.argv.slice(2);
-    if (!root || !configFile || !files.length)
+    const [root, configFile, encodedTags, ...files] = process.argv.slice(2);
+    if (!root || !configFile || !encodedTags || !files.length)
         throw new Error("Invalid golangci-lint arguments");
+    const tags = goBuildTagsSchema.parse(JSON.parse(encodedTags));
     const version = spawnSync("golangci-lint", ["version", "--short"], {
         encoding: "utf8",
         maxBuffer: 8192,
@@ -63,6 +65,7 @@ async function main() {
             version: "2",
             run: {
                 tests: true,
+                "build-tags": tags,
                 "modules-download-mode": "readonly",
                 "relative-path-mode": "wd",
                 "issues-exit-code": 1,

package/dist/src/golangci.js

@@ -19,6 +19,7 @@ export async function golangciCheck(source, project) {
                     fileURLToPath(new URL("./golangci-runner.js", import.meta.url)),
                     source.root,
                     configs[0] ?? "",
+                    "[]",
                     ...files,
                 ],
                 cwd: project.path,

package/dist/src/output.js

@@ -22,6 +22,7 @@ export function projectPlan(plan, detailed) {
         excludedCount: plan.excluded.length,
         checks: plan.checks.map((check) => ({
             id: check.id,
+            ...(check.goBuild ? { goBuildTagCount: check.goBuild.tags.length } : {}),
             ...(check.goScope
                 ? { goExcludedFileCount: check.goScope.excludedFiles.length }
                 : {}),
@@ -44,6 +45,7 @@ export function projectReport(report, detailed) {
         sourceError: report.sourceError,
         checks: report.checks.map((check) => ({
             id: check.id,
+            ...(check.goBuild ? { goBuildTagCount: check.goBuild.tags.length } : {}),
             ...(check.goScope
                 ? { goExcludedFileCount: check.goScope.excludedFiles.length }
                 : {}),

package/dist/src/report-validation.d.ts

@@ -46,6 +46,10 @@ export declare function validatedReport(input: unknown): {
                 reason: string;
             }[];
         } | undefined;
+        goBuild?: {
+            profile: string;
+            tags: string[];
+        } | undefined;
         tests?: {
             total: number;
             passed: number;

package/dist/src/schemas.d.ts

@@ -1,3 +1,4 @@
+export { goBuildPolicySchema } from "./go-build.js";
 export { goScopePolicySchema } from "./go-scope-policy.js";
 export { externalManifestSchema, externalReferenceSchema, externalRequestSchema, externalResultSchema, } from "./external-adapter.js";
 export { actionlintConfigSchema } from "./actionlint.js";
@@ -58,6 +59,10 @@ export declare const reportSchema: z.ZodObject<{
                 reason: z.ZodString;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
+        goBuild: z.ZodOptional<z.ZodObject<{
+            profile: z.ZodString;
+            tags: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         status: z.ZodEnum<{
             error: "error";
             passed: "passed";
@@ -209,6 +214,7 @@ export declare const reportSummarySchema: z.ZodObject<{
             skipped: z.ZodNumber;
         }, z.core.$strict>>;
         goExcludedFileCount: z.ZodOptional<z.ZodNumber>;
+        goBuildTagCount: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     runId: z.ZodString;
     outcome: z.ZodEnum<{
@@ -272,6 +278,10 @@ export declare const planSchema: z.ZodObject<{
                 reason: z.ZodString;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
+        goBuild: z.ZodOptional<z.ZodObject<{
+            profile: z.ZodString;
+            tags: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         kind: z.ZodEnum<{
             format: "format";
             analysis: "analysis";
@@ -371,6 +381,7 @@ export declare const planSummarySchema: z.ZodObject<{
         }>;
         ready: z.ZodBoolean;
         goExcludedFileCount: z.ZodOptional<z.ZodNumber>;
+        goBuildTagCount: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     schemaVersion: z.ZodLiteral<1>;
     engineVersion: z.ZodString;

package/dist/src/schemas.js

@@ -1,3 +1,5 @@
+import { goBuildSelectionSchema } from "./go-build.js";
+export { goBuildPolicySchema } from "./go-build.js";
 import { goScopePolicySchema } from "./go-scope-policy.js";
 export { goScopePolicySchema } from "./go-scope-policy.js";
 import { externalIdentitySchema } from "./external-adapter.js";
@@ -127,6 +129,7 @@ export const reportSchema = z.strictObject({
         project: z.string(),
         scope: strings,
         goScope: goScopePolicySchema.optional(),
+        goBuild: goBuildSelectionSchema.optional(),
         status,
         reason: z.string(),
         processes: z.array(processResult),
@@ -169,6 +172,7 @@ export const reportSummarySchema = z.strictObject({
         status,
         tests: tests.optional(),
         goExcludedFileCount: count.optional(),
+        goBuildTagCount: count.optional(),
     })),
 });
 export const planSchema = z.strictObject({
@@ -191,6 +195,7 @@ export const planSchema = z.strictObject({
         project: z.string(),
         scope: strings,
         goScope: goScopePolicySchema.optional(),
+        goBuild: goBuildSelectionSchema.optional(),
         kind,
         parser: z.enum(PARSERS),
         commands: z.array(command),
@@ -211,6 +216,7 @@ export const planSummarySchema = z.strictObject({
         kind,
         ready: z.boolean(),
         goExcludedFileCount: count.optional(),
+        goBuildTagCount: count.optional(),
     })),
 });
 export const junitImportSchema = z.strictObject({

package/dist/src/types.d.ts

@@ -1,7 +1,8 @@
+import type { GoBuildSelection } from "./go-build.js";
 import type { GoScopePolicy } from "./go-scope-policy.js";
 import type { ExternalIdentity } from "./external-adapter.js";
 import type { RuntimeInventory } from "./runtime-inventory.js";
-export declare const VERSION = "0.1.0-alpha.4";
+export declare const VERSION = "0.1.0-alpha.5";
 export declare const PARSERS: readonly ["vue-router-json", "nuxt-json", "exit", "empty", "node-events", "unittest", "go-scope-test", "go-scope-analysis", "golangci-json", "staticcheck-json", "go-json", "typescript-build-json", "tsc-files", "eslint-json", "vitest-json", "playwright-json", "jest-json", "pytest-json", "fastapi-json", "django-json", "laravel-json", "rust-json", "clang-json", "java-json", "dotnet-json", "actionlint-json", "external-json", "ruby-syntax", "silent-syntax", "ruff-json", "mypy-json", "phpstan-json", "phpunit-junit", "pint-json"];
 export type Status = "passed" | "failed" | "unavailable" | "skipped" | "error" | "inconclusive";
 export type Outcome = "passed" | "failed" | "incomplete";
@@ -46,6 +47,7 @@ export interface ToolEvidence {
 }
 export interface Check {
     goScope?: GoScopePolicy;
+    goBuild?: GoBuildSelection;
     external?: ExternalIdentity;
     id: string;
     adapter: string;
@@ -118,6 +120,7 @@ export interface Finding {
 }
 export interface CheckResult {
     goScope?: GoScopePolicy;
+    goBuild?: GoBuildSelection;
     external?: ExternalIdentity & {
         tools?: {
             name: string;

package/dist/src/types.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.1.0-alpha.4";
+export const VERSION = "0.1.0-alpha.5";
 export const PARSERS = [
     "vue-router-json",
     "nuxt-json",

package/docs/ACCEPTANCE.md

@@ -7,7 +7,7 @@ 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, npm alpha.3 and its MCP Registry entry are published. Hosted CI passed at `b0b447d`; fresh registry installation was verified.                                                                                                  |
+| 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.4 and its MCP Registry entry are published. Hosted CI passed at `ebe7f5c`; 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.              |
@@ -21,9 +21,9 @@ JavaScript, TypeScript, Python, Go and PHP libraries. They expose an older
 TypeScript compiler-option incompatibility and workflow/documentation/platform
 coverage friction. The [alpha.3 compiler fix](TYPESCRIPT.md) now passes the
 known TypeScript 4.9.5 case. [Setup guidance](SETUP-SCOPES.md) distinguishes
-workflow/documentation coverage; an unreleased [Go scope policy](GO-SCOPE.md)
-accounts for explicitly acknowledged native exclusions. Broader target coverage
-remains follow-up work. The observations do not establish full upstream CI coverage or
+workflow/documentation coverage; the alpha.4 [Go scope policy](GO-SCOPE.md)
+accounts for explicitly acknowledged native exclusions. Unreleased [per-check build-tag profiles](GO-BUILD.md)
+add explicit tag selection; broader target coverage remains 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
@@ -53,10 +53,11 @@ 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, npm preview `0.1.0-alpha.3` and its MCP Registry entry are
-published. The [hosted run at b0b447d](https://github.com/stsepelin/checktrail/actions/runs/35597877167)
-passed all jobs, and fresh public installation was verified. Alpha.3 adds
-[legacy compiler compatibility](TYPESCRIPT.md) to the existing [setup commands](ONBOARDING.md). The [GitHub prerelease](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.3)
+The public repository, npm preview `0.1.0-alpha.4` and its MCP Registry entry are
+published. The [hosted run at ebe7f5c](https://github.com/stsepelin/checktrail/actions/runs/35603451711)
+passed all jobs, and fresh public installation was verified. Alpha.4 adds
+[explicit Go exclusions](GO-SCOPE.md) alongside [legacy compiler compatibility](TYPESCRIPT.md)
+and the [setup commands](ONBOARDING.md). The [GitHub prerelease](https://github.com/stsepelin/checktrail/releases/tag/v0.1.0-alpha.4)
 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

package/docs/CLIENTS.md

@@ -1,6 +1,6 @@
 # Application client compatibility
 
-The [alpha.3 release record](measurements/release-alpha3.json) repeats the named
+The [alpha.4 release record](measurements/release-alpha4.json) repeats the named
 profiles below against the exact published artifact. The original standalone
 snapshots predate the Checktrail rename and retain their original identities.
 A future release needs its own checks; see [RENAMING.md](RENAMING.md).
@@ -108,4 +108,4 @@ The runtime digest identifies the installed `dist/src` tree independently.
 These local checks satisfy only the named client profiles. Claude Desktop,
 Cursor, VS Code integrations, other client versions and target operating systems
 remain unverified. These original snapshots do not establish public installation or hosted CI;
-alpha.3 publication and hosted evidence are recorded separately in [RELEASE.md](RELEASE.md).
+alpha.4 publication and hosted evidence are recorded separately in [RELEASE.md](RELEASE.md).

package/docs/EXECUTION.md

@@ -21,6 +21,13 @@ an unavailable runtime or external service does not count as verification.
 
 ## M2
 
+- Alpha.5 candidate, unpublished: named per-check Go build-tag profiles with independent
+  exclusions, matching listing/execution settings, unchanged formatting scope,
+  strict missing/ambiguous assignment handling and summary privacy. Native
+  Go/Staticcheck/golangci-lint cases and CLI/library/MCP replay cover the selected
+  configuration; repeated-check and cross-target matrices remain pending.
+  See `GO-BUILD.md` and `examples/go-build`.
+
 - Implemented: explicit local TypeScript and ESLint adapters with file accounting.
 - Implemented: TypeScript project-reference solution validation using fresh
   in-memory declarations, source accounting and normalized compiler diagnostics.

package/docs/GO-BUILD.md

@@ -0,0 +1,106 @@
+# Go build-tag profiles (alpha.5 candidate)
+
+The source checkout supports named build-tag profiles in module-local
+`checktrail.go-build.json`. Published alpha.4 does not support this file. It
+selects additional Go build constraints for each check and keeps that check's
+exclusions explicit. It does not introduce cross-compilation or a target matrix.
+
+## Configure
+
+Continue selecting checks in `checktrail.json`. A build profile does not enable
+checks: `go.test-race`, Staticcheck and golangci-lint still need explicit selection.
+Use the [runnable synthetic example](../examples/go-build/checktrail.go-build.json)
+with [its check selection](../examples/go-build/checktrail.json), or configure:
+
+```json
+{
+  "schemaVersion": 1,
+  "profiles": [
+    {
+      "name": "integration",
+      "tags": ["integration"],
+      "checks": ["go.vet", "go.test"],
+      "excludedFiles": []
+    }
+  ]
+}
+```
+
+Every selected native Go check must be assigned exactly one profile. Missing
+assignments are unavailable; they never silently fall back to an untagged run.
+Profile names and check assignments must be unique. A profile may share its tags
+and exclusions across several checks; other profiles can use different settings.
+Unselected checks are not executed, even if a profile names them. Each check runs
+once. Repeating one check across several profiles is not implemented.
+
+Tags are an array of distinct ASCII identifiers matching
+`[A-Za-z_][A-Za-z0-9_]*`, each at most 64 characters, with at most 32 tags.
+An empty array adds no tags. Profile names start with an ASCII letter and allow
+letters, digits, underscores and hyphens, up to 64 characters. Up to five profiles
+can assign the five supported native checks. Unknown fields, malformed JSON,
+nonregular policy files and invalid exclusions make native checks unavailable.
+
+Each profile has its own `excludedFiles`, using the exact paths and nonblank
+reasons described in [Go scope](GO-SCOPE.md). Excluded files must still be
+inventoried and confirmed by native `IgnoredGoFiles`. An active or stale exclusion
+cannot pass. Listing a source file as excluded never suppresses an actual finding.
+Do not combine this file with `checktrail.go-scope.json`; their overlapping policy
+is rejected. To migrate, move exclusions into each applicable profile and remove
+the old scope policy after reviewing the complete configuration.
+
+## Execution and evidence
+
+Go listing, vet, tests and Staticcheck receive identical `-tags` settings within
+each check. Race tests also keep `-race` in listing and execution. Golangci-lint
+receives the profile tags in its generated configuration; its project's own
+`run.build-tags` remains unsupported to avoid a second source of settings.
+Existing protected Go settings, version checks and tool requirements still apply.
+
+Formatting checks the full inventory once and ignores build profiles. Native
+checks retain their whole inventory and reconcile selected and excluded files
+separately. Tests still need a passing test in each package; test counts and
+failures come from native events. A passing ordinary test does not cover a file
+selected only by the race profile. An exclusion's reason is an operator statement,
+not independent evidence that another check ran or covered it.
+
+Detailed plans/reports add `goBuild` with the profile name and tags alongside
+`goScope` with that profile's exclusions. Summary plans/reports expose only
+`goBuildTagCount` and `goExcludedFileCount`; names, tags and reasons remain private
+unless detailed output is enabled. Counts describe declarations, not proof of
+execution. Older strict report-schema consumers must update before accepting the
+new optional fields. The [policy schema](../schemas/go-build-policy.schema.json)
+defines the data shape; planning also checks duplicate assignments and inventoried
+file membership.
+
+Planning reads data only. Execution still requires CLI/library/operator startup
+trust. Policy files cannot set environment values or arbitrary command arguments.
+Tags do not set `GOOS`, `GOARCH`, the compiler version or enable race instrumentation;
+only the selected race check adds instrumentation. No unselected tag combinations
+or other operating systems are claimed as validated.
+
+## Reproduce
+
+From a built source checkout with Go and a supported race toolchain prepared:
+
+```sh
+node dist/src/cli.js plan --root examples/go-build --detailed
+node dist/src/cli.js run --root examples/go-build --trust-project --detailed --timeout-ms 120000
+node --test dist/test/go-build.test.js
+node scripts/verify-required-native-tests.mjs go
+```
+
+The example's ordinary profile selects the integration test and acknowledges the
+race-only test. The instrumented profile selects both. This demonstrates source
+selection; the arithmetic example does not itself demonstrate race detection.
+The separate [race regression](GO-RACE.md) exercises an actual data race.
+
+The native regression suite exercises tagged compiler errors and assertions,
+valid near misses, undeclared omissions, stale exclusions, missing assignments,
+independent ordinary/race settings, analyzer diagnostics, nonexecuting planning,
+summary privacy and CLI/MCP agreement. Standard schema checks cover the exported
+policy and report shapes. Prepared CI requires these named cases to run; unavailable
+native tools cannot satisfy the required profile.
+
+References: [Go build constraints](https://pkg.go.dev/cmd/go#hdr-Build_constraints),
+[Staticcheck CLI](https://staticcheck.dev/docs/running-staticcheck/cli/),
+[golangci-lint configuration](https://golangci-lint.run/docs/configuration/file/).

package/docs/GO-RACE.md

@@ -11,9 +11,11 @@ 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 makes undeclared excluded source and untested packages
-incomplete; see [Go scope](GO-SCOPE.md) for the unreleased explicit exclusion policy.
-The source checkout also passes `-race` to package listing so it uses the same build
-constraints as the tests. A build/OS matrix is not implemented.
+incomplete; see [Go scope](GO-SCOPE.md) for the explicit exclusion policy available since alpha.4.
+Alpha.4 also passes `-race` to package listing so it uses the same build
+constraints as the tests. The unpublished alpha.5 source candidate adds
+[per-check build-tag profiles](GO-BUILD.md), allowing race and ordinary tests to
+use different tags and exclusions. 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

package/docs/GO-SCOPE.md

@@ -27,10 +27,10 @@ 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.
 
-## Explicit exclusions in the source checkout (unreleased)
+## Explicit exclusions (alpha.4 and later)
 
-The source checkout adds `checktrail.go-scope.json` at each Go module root.
-Published alpha.3 does not support this policy yet. Opt in only after reviewing
+Alpha.4 adds `checktrail.go-scope.json` at each Go module root. Earlier releases
+do not support this policy. Opt in only after reviewing
 which files the intended native run leaves unverified:
 
 ```json
@@ -78,6 +78,10 @@ This policy does not introduce build-tag flags, cross-compilation, cross-target
 test execution or a build matrix. Use separately prepared native target runs for
 coverage outside the selected profile. Existing protected Go settings stay intact.
 
+The source checkout separately adds [per-check build-tag profiles](GO-BUILD.md).
+They use their own per-profile exclusions and cannot coexist with this module-wide
+policy. That capability is in the unpublished alpha.5 candidate; alpha.4 retains the behavior above.
+
 ## Known-case replay
 
 The [pinned public UUID replay](measurements/go-scope-policy-replay.json) uses the
@@ -91,6 +95,11 @@ The upstream tracked files and original policy were preserved; temporary scope
 policy and failing control were removed. The record identifies the tested tarball
 and runtime source hashes; adding this record changes later package bytes.
 
+The exact alpha.4 release candidate repeated this replay before publication; see
+the [release record](measurements/release-alpha4.json). Its synthetic upgrade test
+also confirms that rolling back to alpha.3 preserves the policy file but restores
+strict scope accounting: a project relying on exclusions becomes incomplete.
+
 ## Staticcheck
 
 Select `go.staticcheck` explicitly. It requires the installed `staticcheck`

package/docs/GOLANGCI-LINT.md

@@ -14,8 +14,8 @@ linters:
   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
+Other linters, nonempty custom settings, formatters and Go version/tag overrides
+in `.golangci.*` 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.
@@ -27,6 +27,9 @@ 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).
+The alpha.5 source candidate adds [Checktrail build-tag profiles](GO-BUILD.md).
+Those tags are passed to both package listing and the generated native config;
+`.golangci.*` still cannot supply a separate `run.build-tags` setting.
 
 Native `nolint` and Staticcheck ignore directives are currently unsupported and
 make the check incomplete. The wrapper scans Go comment boundaries, including