Trust CI Release Gates

Changes, CI and releases

Hard rule (AGENTS.md): all logic is in Rust. Logic is anything whose result is stored, sent to a runtime or PLC, or decides an engineering or operator outcome. TypeScript only presents (drawing, layout, mouse interaction, view state) and forwards requests to Rust. Never add logic in TypeScript. Existing TypeScript logic is debt to move into Rust, not to extend.

Before a push, read the diff for this: a change that adds or grows logic in TypeScript does not ship.

Changelog and versions

• Changelog: user-visible changes get an entry in CHANGELOG.md under ## [Unreleased], in ### Added, ### Changed or ### Fixed. User-visible means runtime behaviour, CLI flags and output, the standard library, tutorials and docs, and test harness behaviour. Purely internal changes need no entry.
• Version: a release-notable change bumps [workspace.package].version in Cargo.toml, unless the user says not to.
• VS Code versions: when the version changes, or when the extension's behaviour changes, set editors/vscode/package.json and the root version entries of editors/vscode/package-lock.json to the same version.
• Docs: keep tutorials, examples, specifications and coverage documents in line with what ships.

Plan the final validation

Before implementation is frozen, read the current workflows and guard scripts. In the existing task record, map each required job to its command, toolchain, targets/features, evidence and prerequisites. Distinguish the pinned/MSRV compiler from floating CI stable; record the actual versions used. Keep native Windows/macOS proof separate from Linux cross-compilation. Review new tests and their imports, feature gates and registrations as part of the full diff before spending the batch. For a related candidate, read the preceding failure ledger and its corrected commands, including compiler environment, temporary-path and platform prerequisites; carry those corrections into the new command map before freezing.

Choose the release path before scheduling commands. Once implementation is complete, perform the single final formatting and required generated-file preparation on the builder with the guard's exact toolchain and configuration, including touched include! fragments. This is the preparation phase of the planned batch, not a per-edit check or another full test run. Copy back and review its complete diff before the authorized commit. The exact-SHA guard then validates that clean committed source; its formatting step must leave the tree unchanged. Never restore formatter output during a running guard to make the final cleanliness check pass.

If an exact-SHA guard is required, commit only when authorized, then use prepare for the checks it already runs. Do not run just test-all once before the commit and again inside prepare merely to satisfy two descriptions of the same gate. Required scope batches remain distinct when explicitly authorized; their evidence cannot substitute for the exact-SHA artifact. A commit, rebase or source change requires evidence for the new candidate.

Before a push

1. Confirm the required job/command map against .github/workflows/ and the guard. A host just clippy or just test-all is not cross-platform parity.
2. The following checks must pass on the builder in the authorized batch. Count commands covered by prepare once; add only required checks it does not cover: just fmt, just clippy, just test-all, and applicable area checks below:
   • trust-lsp tests or dependency/config resolution: ./scripts/prepush_ci_gate.sh. It includes the test-path hygiene check and the Windows GNU check of trust-lsp's tests.
   • Runtime networking, mesh or TLS: RUSTFLAGS=-Dwarnings cargo check -p trust-runtime --all-targets and ./scripts/runtime_mesh_tls_stability_gate.sh --iterations 8.
   • Runtime CI contracts (crates/trust-runtime/tests/ci_cicd_contract.rs or tests/fixtures/ci/**): cargo test -p trust-runtime --test ci_cicd_contract --test config_schema_command --test registry_command.
   • Any trust-runtime change: ./scripts/check_runtime_cross_target_warnings.sh --install-missing --require-cross.
   • Docs Captures paths (editors/vscode/**, scripts/captures/**, capture assets or the capture workflow): python3 -m unittest scripts.tests.test_capture_lifecycle -v. The VS Code npm test does not replace it.
   • VS Code: npm run lint && npm run compile && npm test in editors/vscode.
   • Module splits, large-file waivers or xtask/config/full_map_policy.json: cargo run -p xtask -- architecture-doctor --full-map.
3. Check the push transport once, before the first push:
   • Record git remote get-url origin, git remote get-url --push origin and gh auth status --hostname github.com. Never print credentials.
   • An HTTPS OAuth token without the workflow scope cannot push .github/workflows/**. In that case, set the SSH push URL: git config remote.origin.pushurl git@github.com:johannesPettersson80/trust-platform.git.
   • Prove the SSH push URL works: git ls-remote --exit-code "$(git remote get-url --push origin)" HEAD.

Release candidates

These pushes go through the guard in this skill's scripts/:

• integration, release and main pushes;
• any branch whose workspace version differs from origin/main.

1. Prepare. Freeze one clean candidate and prepare its exact-SHA artifact in a clean builder worktree:

   python3 .codex/skills/trust-ci-release-gates/scripts/release_candidate_guard.py \
     prepare --remote-worktree '<clean exact-SHA trust-builder worktree>'

   • It records the required commands:
     • parity of AGENTS.md and .codex/skills/ with the primary checkout;
     • a clean candidate and base, and diff integrity;
     • bash scripts/supply_chain_gate.sh and bash scripts/architecture_safety_gate.sh;
     • the cross-target warnings;
     • just test-all on the builder;
     • MP-001 discovery/snapshot parity, reusing the native test binaries;
     • the capture lifecycle, when it applies.
   • Planner and catalog records are advisory.
   • Any commit, base movement or dirty checkout invalidates the artifact.
   • It needs 80 GiB free on the selected target filesystem on the builder.

2. Push once. The shared pre-push hook (scripts/pre-push, which git config core.hooksPath points at) rejects a release-sensitive push that has no passing artifact for the exact head and base. Never bypass it.

3. Wait for every required check. If any check fails, collect the whole failure set and every failed job log before editing: release_candidate_guard.py collect-failures --pr <number> --wait.

   • Keep the source frozen while results are being collected. Within an authorized batch, continue independent checks when safe; record dependent checks as unrun when prerequisites fail. Do not bypass a guard's failure or alter its control flow ad hoc.
   • Fix the complete known set, including defects in new tests, and review the full correction. Refreeze and run the consolidated correction batch only under the user's current authorization. Do not automatically rerun, or ask again when that authorization already exists.
   • Inspect native and VS Code job logs and *-retry-rescued.txt artifacts even when GitHub marks the job green. A passing automatic retry does not close the first failure: retain it, identify its cause and obtain the applicable correction/validation authorization before merge.
   • Never push corrections from partial results.

4. Merge only with release_candidate_guard.py check-merge --pr <number> --execute.

5. Release a version change.

   • Wait for main CI.
   • Push the annotated tag v<version> from the same main SHA.
   • Run release_candidate_guard.py verify-release --candidate-head <reviewed-head> --branch <candidate-branch>. It checks:
     • the tag;
     • the Release workflow;
     • GitHub Latest;
     • the assets and checksums;
     • the Marketplace version for darwin-arm64, darwin-x64, linux-arm64, linux-x64 and win32-x64.
   • If the main version guard expired only because the Release run was still going, wait for that run, then rerun the failed main jobs on the same SHA only under the current retry authorization. Never create another tag.

6. Clean up. verify-release then runs audit-post-merge.

   • Remove only the exact clean targets it lists.
   • Fetch with prune, and rerun the audit until it reports clean.
   • The handoff is incomplete while candidate branches, worktrees or unique commits remain.

After a second failed candidate, or two hours without merge readiness, report the complete blocker list, elapsed time and next action. Continue only within the current scope and retry authorization; this report is not a new permission gate when the user already authorized continued corrections.

Use precise readiness claims:

• Scope verified: the scope's required evidence passes for its recorded source identity.
• Guard passed / push-ready: the required exact-SHA artifact passes and push prerequisites hold.
• Merge-ready: current-head required GitHub checks and reviews pass and check-merge allows it.
• Released: verify-release confirms the tag, workflow, assets and Marketplace requirements.

A passing earlier scope or old-head CI cannot establish a later state. Report the active stage, actual elapsed time and remaining stages; do not describe unpushed corrections as GitHub results.

In PR text, Closes, Fixes and Resolves close an issue on merge; Addresses does not. Check that the intended issues are closed after the merge.