Founder Preview Governance

The user-facing product label is INTERNAL BETA. This is a private product-status label; it does not create a beta branch, runtime, domain, database, schema, or separate release lane.

SheetBase has one private founder-preview runtime:

No beta runtime, domain, database, schema, or release lane exists. The Vercel slot name and production build mode are infrastructure labels; they do not mean SheetBase is publicly released.

Only the founder and a few informed Google OAuth test-email testers use this runtime. Do not invent public-user, public-readiness, or production-release claims.

Branch Rule

Feature PRs target main. Each feature branch is the founder-preview candidate.

Keep every PR draft until engineering verification passes. Do not merge to main without explicit founder approval. Founder manual testing happens after the automatic release and remains required before the related issue closes.

The historical beta branch is not a release or deployment lane. Do not open new feature PRs to it, require work to pass through it, or reconcile main with it.

An approved merge to main is the only release approval. Every merge, including documentation-only merges, automatically releases its exact merged tree through .github/workflows/release-internal-beta.yml.

ADMIN is a repository role, not a hardcoded username. CI derives it from the protected ADMIN_GITHUB_TOKEN and verifies repository-admin permission. When the merged commit is not attributed to that ADMIN, the first run skips all tests, backup, migration, build, and deployment work. It creates one empty ADMIN-attributed marker commit with the same tree and stops. The marker push starts the second workflow run, which performs the complete release.

Do not commit branch-specific diff assertions as permanent tests; enforce candidate scope with scripts/release-audit.mjs and PR-specific review evidence.

MCP authentication uses authenticateMcpRequest(): OAuth access tokens use Authorization: Bearer, API keys use x-api-key, and mixed credentials fail closed.

Mid-work discoveries

• If a discovery blocks the current issue, fix it inline and record it in the PR and commit.
• If a discovery is related but does not block the current issue, open a linked GitHub issue with Refs #<current-issue> and keep working.
• If a discovery is unrelated, open a GitHub issue, park it, and do not change the current diff.
• If a discovery is large or unclear, stop and ask the founder before proceeding.

Risk Classes

Every founder-preview candidate is classified before merge. --intent is declared by the agent; path buckets come from changed files.

Local Audit

Run the audit against main before requesting merge approval:

npm run release:audit -- \
  --target main \
  --intent release-governance \
  --base origin/main \
  --candidate HEAD

Use the candidate's actual intent. Add only individually reviewed risk waivers; do not waive UI, auth, package, MCP-write, database, or destructive risks in bulk.

The audit is local-only. It does not call GitHub, Vercel, Supabase, or other external services. It checks:

• clean worktree unless --allow-dirty is passed;
• candidate includes origin/main;
• changed files are bucketed by risk class;
• blocking path classes are surfaced;
• added write/destructive mutator signals are detected;
• MCP tool changes are paired with docs/skill updates or an explicit waiver.

Any changed MCP source path requires matched tool-contract evidence or an explicit reviewed waiver; the audit never infers semantic equivalence from source text.

Use JSON output for CI or handoff packets:

npm run release:audit -- \
  --target main \
  --intent read-only \
  --base origin/main \
  --candidate HEAD \
  --format json

Required Verification

Minimum verification for a founder-preview candidate:

git log -1 --format='%H %ae'
npm ci
npm test
npm run lint
node scripts/check-new-advisories.mjs --base-sha="$(git merge-base origin/main HEAD)"
npm run build
npm run skills:check
npm run release:audit -- --target main --intent release-governance --base origin/main --candidate HEAD
git diff --check origin/main...HEAD

If npm ci fails, repair and commit package-lock.json before evaluating later gates.

If a candidate changes MCP source, include matched tool-contract evidence or an explicit reviewed waiver.

Only reviewed backward-compatible expand migrations may enter the automatic path. Destructive, contract, or otherwise coordinated migrations stop for a separate founder decision.

Keep release and deployment rules in this document. Do not duplicate them in founder-owned or provider-specific instruction files.

Automatic Internal-Beta Release

GitHub Actions is the only publisher. Native Vercel Git publishing is disabled. The guarded sequence is:

approved merge to `main` -> empty ADMIN marker when needed -> second workflow run ->
exact tree and source-change gates -> read-only migration plan ->
conditional safe migration transaction -> exact archive build -> staged smoke ->
promotion -> canonical smoke -> founder acceptance

Code-only releases perform no database writes. A reviewed safe migration requires an encrypted backup, disposable restore rehearsal, transaction, locking, and exact ledger evidence. Destructive migrations stop.

The marker's tree must exactly match its parent. SOURCE_SHA records the approved merge and its real first parent remains the release-audit base, so the empty commit cannot hide the merged change. The workflow builds from a proven exact Git archive without .git, verifies the Brandtown project and team, verifies exact-SHA deployment metadata, and smoke-tests before promotion. Failure before promotion leaves the live runtime untouched. Failure after promotion restores and verifies the previous deployment.

Personal GitHub emails and Vercel usernames are not release identities. The ADMIN token owner is verified by repository permission, not by a username written in workflow code. Do not call this a public production release. A successful run ends awaiting-founder-acceptance; founder testing is the issue-closing gate.

Known Maintenance Warnings

These warnings do not block every preview candidate, but they must remain visible:

• local Vercel CLI may be behind the latest version;
• if Vercel reports missing variables from turbo.json, declare them on the task that consumes them;
• docs build may emit Fumadocs/Webpack cache warnings;
• standalone tsc can require generated Fumadocs source first;
• Google OAuth consent requires manual verification because browser automation may be blocked;
• npm ci may report node-domexception deprecation;
• npm ci failure is a release blocker; regenerate and review the lockfile instead of using npm install as the release install step;
• npm audit fix --force may introduce breaking dependency changes; review advisories and upgrade deliberately.

If a candidate touches the related area, promote the warning from parked maintenance to active review.