# Validate a change

Validate source intent and release packaging before authorizing production. A dry run does not prove remote permissions, resource availability, or live application behavior.

## Prerequisites

Use the checked-in toolchain pins. Provider credentials are unnecessary for backend-free Terraform validation. Some app builds need external downloads or private package access; Pioneer uses `FIND_HOW_PACKAGES_READ_TOKEN` in GitHub Actions. Never work around an installation failure by committing a token.

1. Inspect the selected roots and apps against your branch's base.  
```sh  
node scripts/ci/select.mjs origin/main HEAD  
```  
This comparison sees committed changes. Before committing, also inspect `git diff` and ` git status --short`. The result separates infrastructure roots, apps to verify, and apps to deploy.
2. Format and check repository contracts.  
```sh  
make fmt  
make verify  
```  
These checks cover agent metadata, the catalog, release contracts, Terraform ownership, formatting, validation, and TFLint. They do not apply infrastructure or verify every application.
3. Verify each affected app. For the data service, run:  
```sh  
make app-verify APP=data  
```  
The command installs frozen dependencies and runs the app's checks. Plain Workers use shared TypeScript, discovered tests, and a Wrangler dry run. Framework apps use their own verification contract. Verify consumers listed by the selector even when they will not be redeployed.
4. For an application release or packaging change, inspect its package.  
```sh  
make app-package APP=data  
make app-release-check APP=data  
```  
Check the manifest's Worker names and migration bindings. Default `migrations/` directories and explicit migration directories are packaged when owned by the app. An app without local migrations may bind an existing database without becoming its schema owner.
5. Review `git status --short`, commit only intended source changes, and follow the [pull request workflow](/stormtrust/engineering/github/pull-request-workflow/). Confirm the required checks complete for the latest commit.

## Interpret failures

| Failure                                            | Action                                                                                   |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Frozen lockfile or package-manager mismatch        | Use the owning manifest and pin; review dependency changes together with its lockfile    |
| Missing private package access                     | Restore the approved package-read credential for the matching build                      |
| Docs build cannot fetch an upstream dependency     | Identify the failed host and retry after access recovers; keep the full build required   |
| Missing production identifier or denied API access | Inspect the trusted job's preflight and resource-resolution logs                         |
| Check passes locally but fails in Actions          | Compare commit, Node version, package owner, environment, and generated-file assumptions |

The docs contract includes the full vendored site build. A successful StormTrust-only check is not equivalent to that release verification.