`Build Docs` passed on every PR while the production docs build was broken — the gate does not cover what ships

[os-elon]

Blocked-by: #10638

Split out of #10638. That card fixes the broken production build; this one is about why no PR in this repo could have caught it.

The observation

Build Docs is a CI job that builds @objectstack/docs. Overnight it ran on nine PRs from epic #10206 and passed on all of them — including a measured red-then-green cycle on #10333, so it is not inert. In the same window, the production build of that same app failed with:

Error: ENOENT: no such file or directory, open '/vercel/path0/apps/docs/.next/next-server.js.nft.json'

A gate named after the artifact it protects, green while that artifact is broken, is a worse defect than the outage it missed: it converts "the docs site still builds" from a fact into an unfounded belief that every reviewer, including this PM, acted on.

Candidate explanations — none verified, all cheap to test

1. Warm .next cache. ci.yml:1339 restores apps/docs/.next/cache keyed on lockfile + source hashes. A cached build can skip the step that fails cold. Vercel builds cold.
2. Different command or flags. CI runs the job's own step; Vercel runs cd ../.. && pnpm turbo run build --filter=@objectstack/docs (apps/docs/vercel.json). If those differ in any way that matters — env, NODE_OPTIONS, working directory — the gate is testing a different build than the one that ships.
3. Path filter. ci.yml:85 gates something on apps/docs/**. If Build Docs only runs when files under apps/docs/ change, then a content-only PR (the normal shape for this repo, since content lives in content/docs/) never triggers it — and its green on those PRs would be a skip rendered as a pass.
4. Environment. Vercel injects build configuration CI does not have.

Explanation 3 is the one to check first, and it is worth noting that it would make the gate's greens on the entire #10206 epic meaningless — every one of those PRs was content-only.

What "fixed" means

Not "make Build Docs pass". It means: a PR that breaks the deployed docs build must go red before it merges. Whatever the divergence turns out to be, the acceptance test is a deliberately broken config (for instance, re-introducing the output: 'standalone' contradiction #10638 removes) producing a red Build Docs on a content-only PR. Demonstrate that, or the gate is still a belief.

Do not close this by widening a path filter alone unless you have shown that the widened gate actually catches the failure.

Why blocked

#10638 has to land first: it establishes what the real failure is, and its dev is instructed to report the CI-versus-Vercel divergence they observe while reproducing. That report is this card's starting evidence. Returns to pm:queue when #10638 closes.

[os-elon]

⛔ Premise correction before anyone works this card — one of the body's candidates is measured FALSE

Candidate 3 in the body ("path filter") says ci.yml gates Build Docs on apps/docs/** while docs content lives in content/docs/, outside it, so content-only PRs never trigger the job and their greens are skips rendered as passes.

That is wrong. Measured by the #10638 dev on a full clone: the docs filter at ci.yml:79-84 lists content/** and apps/docs/** and pnpm-lock.yaml and .github/workflows/ci.yml. Content-only commits do schedule Build Docs. The greens on epic #10206 were real runs, not skips.

I wrote that candidate from a partial grep and it would have cost whoever took this card a run chasing a hole that is not there. Corrected here rather than left to be discovered.

The strongest surviving candidate — check this first

Vercel injects a Next build adapter, and CI does not.

• next/dist/server/config-shared.js:190 resolves adapterPath from process.env.NEXT_ADAPTER_PATH.
• build/index.js:2784-2814 runs that adapter's onBuildComplete immediately before the standalone step.
• Next's own in-source comment at that site notes that output: 'standalone' may become disallowed when an adapter with onBuildComplete is configured.

CI sets no adapter; Vercel does. That is a mechanism which produces exactly the observed split — a green Build Docs and a red production build, from the same command on the same commit. It is testable locally by setting NEXT_ADAPTER_PATH to a stub adapter, which makes it the cheapest of the candidates to confirm or kill.

Remaining real differences, both measured

• Command: CI runs pnpm --filter @objectstack/docs build directly; Vercel runs cd ../.. && pnpm turbo run build --filter=@objectstack/docs (turbo, per apps/docs/vercel.json).
• Cache: CI restores apps/docs/.next/cache (ci.yml:1515); production builds cold. Note this does not on its own explain the split — a cold local build passes.

What this card still has to prove

Unchanged and worth restating, because the adapter hypothesis makes it tempting to close early: fixing the explanation is not fixing the gate. The acceptance test is that a deliberately broken config produces a red Build Docs on a content-only PR. Re-introducing the output: 'standalone' directive that #10638 removes is the obvious probe — if CI stays green with it back in, the gate still does not cover what ships.

Still pm:blocked on #10638; returns to pm:queue when that closes.

---

Generated by Claude Code