Check Gate Handbook

A specialized reference manual and textbook instructing AI agents on how to execute local workspace check-gates, observe the two-speed verification protocol, interpret gate failure diagnostics, and apply autonomous self-healing recipes.

Activation Boundary

Consult this textbook when:

• Executing bun scripts/check.ts during the Pre-response self-audit (./AGENTS.md Chapters 7 & 1).
• Diagnosing why a local check gate, clean-clone build, or submodule pointer verification failed.
• Confirming that all subprojects and orchestrators pass before reporting task completion.

Do NOT consult when:

• Only reading, searching, or exploring the codebase without making mutations.
• Authoring plans, proposals, or designs prior to implementation.

The Two-Speed Gate Protocol

Local verification operates at two distinct speeds to balance development velocity with release hermeticity:

Fast Loop (--quick)                     Full Pre-Flight Gate (Default)
Speed: 3 - 10 seconds                   Speed: 20 - 45 seconds
When: Active development iteration      When: Task completion / Pre-push
Runs:                                   Runs:
  [1] Code format verification            [1] Code format verification
  [2] Strict linter execution             [2] Strict linter execution
  [3] Fast unit/integration tests         [3] Fast unit/integration tests
  [4] Static cross-boundary contracts     [4] Static cross-boundary contracts
  [5] Tracked source & assets            [5] Tracked source & assets
                                          [6] Hermetic clean-clone sandbox
                                          [7] Runtime smoke / browser test

1. The Fast Loop (--quick)

Pass --quick as the first argument when validating intermediate code edits:

bun scripts/check.ts --quick
# Or for a specific submodule:
bun <submodule-path>/scripts/check.ts --quick

This executes all native linters, compilers, and static asset checks, but skips the clean-clone build and browser smoke tests, returning actionable feedback in seconds.

2. The Full Pre-Flight Gate

Always execute the unflagged gate before marking any code-modifying task [Completed]:

bun scripts/check.ts

This runs the full 6-slot pipeline, including cloning the committed tree into an isolated temporary directory to prove that uncommitted local files are not masking build breakages.

Workspace vs Submodule Topology

A check-gated repository organizes gates in a 2-tier hierarchy:

1. Workspace Root (bun scripts/check.ts):
   • Checks orchestrator invariants: submodule pointer freshness (git submodule status) and tracked credential leaks (git ls-files).
   • Delegates to each registered submodule's gate: <module>/scripts/check.ts --quick.
2. Codebase Submodule (bun <module>/scripts/check.ts):
   • Executes the component's native toolchain matrix (deduced autonomously via package manifests).
   • Validates compile-time asset tracking, the public funding ledger (.github/FUNDING.yml + DEPENDENCIES.md parity, offline), and performs the clean-clone test. The full (non---quick) lane adds funding-gate.ts --check --verify-links so every funding entry resolves (404/5xx fail, 403/429 warn as anti-bot walls). Skip the gate when gh repo view --json isPrivate -q .isPrivate prints true. Offline contract tests: bun scripts/funding-gate.test.ts.

Diagnostic Matrix: The 10 Failure Classes

When bun scripts/check.ts exits non-zero, identify the failure class and apply its self-healing recipe:

Autonomous Self-Healing Playbook

Do not halt or prompt the user for routine gate failures:

1. Never bypass failures with --no-verify: If the gate fails, the change is incomplete.
2. Untracked build inputs: Compare the error output with git status. If a newly created asset was forgotten, stage it immediately.
3. Submodule pointer bumps: Always check git submodule status after committing inside a submodule. If a + appears, commit the gitlink in the parent orchestrator before finishing.
4. Re-verify after healing: Always re-execute bun scripts/check.ts after applying a fix to guarantee exit code 0.

Reference Depth

• Script Anatomy & 6-Slot Skeleton: Detailed canonical bash patterns for orchestrators and submodules.
• Failure Diagnostic Matrix: Deep-dive failure scenarios and step-by-step remediation commands.