ci: validate every org's resources on every pull request

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: small — touches .github/workflows/ (a blast-radius path), and changes what customer forks see on their pull requests.

• Problem: nothing ran npm run validate before merge. apply, and so promotion, refuses to deploy a config with validation errors: a name over 40 characters, structured-output lockstep, duplicated prompts, the maxTokens floor, or the voice schema. That refusal came after merge: main held a config that wouldn't deploy, and promotion stopped until someone opened a fix PR. Plain push only warns, then can fail partway with an API 400. Each rule in the validator comes from a real mid-push failure (improvements.md membersOverrides.artifactPlan.structuredOutputIds is requiring UUID #8, Specifying handoff tools in a squad requires UUID to function correctly #9, fix(call): clear wrapped partial transcripts cleanly in npm run call #11, feat: simulation suite runner (npm run sim) #18, refactor: state schema with per-resource content hashes #19).
• Who it affects: every repository on this template, and especially multi-org repos that promote from main.
• What changes:
  • A new Validate resources job in ci.yml runs validate for every folder under resources/ on every pull request. It reports every failing org rather than stopping at the first.
  • No engine change. validate makes no network call; loading the engine's config only requires a key to be set, so the step sets a placeholder that is never sent. The job has no secrets, so it runs the same on forks and Dependabot PRs.
  • It's in ci.yml, not the PR check workflow, so every fork gets it without turning on PR checks. On this template, which has no org folders, it does nothing.
  • Docs:
    • the README quick start;
    • the AGENTS.md change loop: if the check fails, fix the errors and don't weaken the check;
    • the workflows guide: make it a required check;
    • the PR checks and troubleshooting guides;
    • improvements.md Add GitOps Support for Pronunciation Dictionaries with Versioned Updates #37.

Heads-up for forks: plain push only warned about these errors, so a repo may already carry some. The first PR after this lands will show them, whatever it changes. The troubleshooting guide covers it. apply already refused those configs, so this moves an existing failure earlier rather than adding a new one.

Evidence of value

tests/ci-validate-workflow.test.ts runs the job's real step, read from ci.yml, against copies of the starter example:

Case	Result
No org folders	passes, "nothing to validate"
Two valid orgs	passes, both validated
One org with a 41+ character assistant name, one valid	fails; both validated, the error names only the bad org and the reason ("Vapi caps at 40")
A folder that isn't a valid org name	fails, naming it
The job's secrets	none; checkout doesn't persist credentials; the only key is the placeholder

Mutation: making the loop ignore validate's exit code fails the two failure-case tests.

Testing plan

• npm test (514 tests) and npx tsc --noEmit pass.
• actionlint, from ci: lint workflows and test the PR check's key-sharing decision #75, lints the new job in this PR's CI.
• Not tested: a customer repo with real resources. The validator itself is unchanged, and apply already runs it on every deploy.

Refs TEST-141

🤖 Generated with Claude Code

[scott-lowe-vapi]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: identify every gitops API request with a User-Agent #78
• feat(validate): catch broken references and show findings on the PR #77
• ci: validate every org's resources on every pull request #76 👈 (View in Graphite)
• ci: lint workflows and test the PR check's key-sharing decision #75
• test(docs): check that doc links, commands and flags exist #74
• fix(cleanup): never delete resources matched by .vapi-ignore #73
• docs(agents): one compact guide for Claude, Codex and Cursor #72
• docs: edit the guides for new readers and fix inaccuracies #71
• docs: restructure the README into a short landing page and topic guides #70
• docs: prepare for public release: scrub internal names, fix examples, add community files #69
• feat(promotion): gate promotion out of an org on a passing check #66
• fix(promotion): commit the files of transitions that applied when a later one fails #65
• test(promotion): pin the exact files promoting an assistant writes to the target #68
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.