Owner: software-architect
Last updated: 2026-05-13 UTC
Background: docs/architecture/queue-cpp-scaffold-review-2026-05-13.md (vcpkg incident 2026-05-13)
Applies to: Every new tier-1 C++ service scaffold PR (Queue Phase 2, Velvet rewrite, MQ-A rewrite, and any future service)
On 2026-05-13 UTC, three sequential vcpkg bugs surfaced during the Queue staging deploy because queue/vcpkg.json was authored without running vcpkg install against its pinned baseline. Each bug required a 20-minute Docker build to discover. This checklist prevents that pattern from recurring on the next C++ service.
The checklist is not optional. card-groomer verifies it is present and complete in the PR description before accepting a scaffold card.
Before opening any PR that touches queue/Dockerfile, queue/vcpkg.json, or queue/CMakeLists.txt, run bin/queue-local-build from repo root. A green build is required — the script exits non-zero on any vcpkg, cmake, or compile failure, giving you the exact error before the 20-minute staging deploy cycle.
Complete every item before opening the scaffold PR. Paste the checklist into your PR description with checkboxes checked.
[ ] vcpkg.json uses exact `version` constraints for all dependencies (not `version>=`)
— See ADR-0085.
[ ] builtin-baseline SHA is documented in queue/vcpkg-notes.md with the date it was
chosen (UTC).
[ ] vcpkg install ran clean in a fresh container at the pinned baseline.
Use the exact command:
docker run --rm -v $(pwd)/<service-dir>:/src gcc:13-bookworm bash -c "
apt-get update -qq && apt-get install -y -qq cmake ninja-build git curl zip unzip pkg-config ca-certificates &&
git clone https://github.com/microsoft/vcpkg.git /opt/vcpkg &&
/opt/vcpkg/bootstrap-vcpkg.sh -disableMetrics &&
/opt/vcpkg/vcpkg install --triplet x64-linux --x-manifest-root=/src/
"
Replace <service-dir> with your service directory.
Exit code must be 0. State the date of the run in the PR description.
[ ] All packages verified: no "version not in database" errors, no "feature not found"
errors from the vcpkg install run above.
[ ] Dockerfile uses full git clone (no --depth 1) for vcpkg.
Shallow clones cannot resolve a pinned builtin-baseline SHA.
[ ] vcpkg-notes.md added alongside vcpkg.json. Contents:
- builtin-baseline SHA
- Date of last clean vcpkg install run (UTC)
- For each direct dependency: one sentence on why it was chosen, which features
are enabled, and any features that were explicitly excluded and why.
[ ] CI vcpkg-manifest-check job (ADR-0087) is wired for the new service's
vcpkg.json and Dockerfile paths. If it is not yet wired, file a Card B
sub-card before the scaffold PR merges.
[ ] AddressSanitizer (-fsanitize=address) and UBSan (-fsanitize=undefined)
enabled in the CMake debug/CI build configuration.
[ ] No raw new/delete anywhere in the codebase. All resources RAII-managed.
Smart pointers (unique_ptr, shared_ptr) for heap allocation.
[ ] No raw char* for any string that carries PII or a credential. Use std::string.
No strcpy, sprintf, or gets.
[ ] Secrets read from Infisical at process startup. No secrets in CMakeLists.txt,
Dockerfile ARGs, or any committed file. check_no_credential_fields.sh covers
the new service directory.
Use exact version (e.g., "version": "7.9.2") for all dependencies. Not version>=. See ADR-0085.
The exact version to pin is the one vcpkg install resolves when you run the verification command above. Record it.
| Trigger | Action |
|---|---|
| New package needed that doesn't exist at current baseline | Bump baseline to a SHA where it exists. Re-run full vcpkg install. Update all exact version constraints to match. Standalone PR. |
| Security advisory requires dep upgrade | Emergency baseline bump. Same procedure. |
| Quarterly cadence (planned) | Bump to recent baseline. Re-verify. No urgency unless security-triggered. |
Baseline bumps are always standalone PRs. Never combine a baseline bump with feature work.
docs/architecture/queue-cpp-scaffold-review-2026-05-13.md — incident RCA and full discipline design