CI & Quality Gates

The workflows distinguish deterministic repository checks from documentation deployment and opt-in live-provider verification.

What runs when

The Session Toolkit workflow also runs on PRs and main pushes. It packs current source once and tests the same archive on Node 22.0.0 and 24, without requiring an unpublished version or a matching release tag. The named input-selection step sets relevant=true|false before toolchain setup; that output gates archive and installed-consumer checks. PR archive and consumer checks skip only unrelated root README/contributor/instruction files, the separate documentation app and Markdown PJM notes; the contributor input map names the exact paths. All other changes run full. Package-tag pushes and manual release retries instead prepare and verify a clean source-bound release candidate; publication also requires the release-enable setting and protected npm environment. See RELEASING.md for the release gates.

Reproduce deterministic checks

From the repository root, with the documented Node and pnpm prerequisites:

pnpm install --frozen-lockfile
pnpm run build:check
pnpm run type-check
pnpm test
pnpm run validate
pnpm run smoke

Run build:check before repairing generated output so drift is visible. If the change intentionally affects installation units, edit canonical source and run pnpm run build, inspect the generated diff, then repeat the checks. See Generated installation units.

Draft PRs skip both Validate jobs, Docs CI and Session Toolkit archive/consumer jobs before runner allocation. All three normal PR workflows preserve their existing base-branch coverage and include ready_for_review. Opening, reopening, synchronizing or marking a PR ready runs the eligible checks, with the Toolkit input selection above still applied. Changing the base branch of a ready PR also runs them; title and body edits do not. Ignored edits use separate concurrency groups and distinct job-name expressions, so they cannot cancel pending checks or replace failed verification with a skipped check. GitHub can display the raw name expression for a skipped job; the normal verification names apply when those jobs run. The validate job still runs on every push to main.

PR-only policies are additional gates, not implied by the command set above. The local pre-push hook runs validate, build freshness, type checking, skill versions, and internal flags; it deliberately does not run tests or smoke. For their local behavior, see Hooks & Safety and Commit Conventions. Repository lint/format checks are changed-file scoped; do not format the entire tree to resolve a scoped PR failure.

Documentation build and deployment

The docs app has its own dependencies and lockfile, including its pinned OAT CLI. To reproduce Docs CI:

pnpm --dir documentation install --frozen-lockfile
PATH="$PWD/documentation/node_modules/.bin:$PATH" oat docs check --target-dir documentation
NEXT_PUBLIC_BASE_PATH=/skills pnpm --dir documentation build
git diff --exit-code -- documentation/index.md
pnpm --dir documentation run docs:format:check

The build includes generated MDX and inventory steps. Docs CI regenerates the committed documentation/index.md after the build and fails if it changed, so commit the regenerated inventory with the pages that changed it. Inspect their changes; never fix a generated inventory by hand. Also check the actual sidebar, links, images, and light/dark rendering: a successful export is not a visual review.

GitHub Pages must be configured to use GitHub Actions. Docs CI runs on pull requests that change documentation/**, the shared OAT config, or the Docs CI workflow, and only checks; the separate deployment workflow publishes. Its push filter includes changes under documentation/** and changes to the deployment workflow itself.

Live checks are opt-in

Ordinary tests use deterministic fixtures; the live submit test is skipped unless its live guard is enabled. pnpm run test:live-e2e enables that guard and requires an authenticated provider plus permission to spend quota. CONSENSUS_LIVE_SUBMIT_PROVIDER selects the provider.

The checked-in manual workflow provisions Codex or Claude on its GitHub-hosted runner. Selecting Cursor fails explicitly: it has no pinned provisioning path there. Cursor verification needs a separately prepared, authenticated environment; choosing the input does not automatically switch this workflow to a self-hosted runner.

Static checks and live submit E2E still do not replace all installation, permission, and workflow acceptance checks. Use Releases & Versioning for that boundary.