Release Governance

Sheetbase uses a two-branch release model:

Branch	Domain	Role
`main`	`https://sheetbase.flonest.app`	Production
`beta`	`https://beta.sheetbase.flonest.app`	Staging and trusted beta usage

main must be treated as production-sensitive. beta can contain broader product work, but a broad beta to main merge is not the normal production path.

Production Rule

Production releases must be candidate-based.

Create a narrow candidate branch from origin/main, apply only the approved release slice, audit that candidate, and open a PR to main.

Do not promote the full beta branch to main. A wholesale beta candidate is a break-glass exception only, requiring explicit human approval, a documented reason, and --allow-wholesale.

Risk Classes

Every candidate is classified before release. --intent is the purpose declared by the releasing agent; path buckets are derived from the files changed.

Class	Examples	Production posture
`read-only`	inspection/search/recon tools	Usually safe after tests, build, and path audit
`diagnostic`	better blocked-write messages, safer previews	Usually safe if successful behavior is unchanged
`mutator`	write behavior, snapshots, caches	Needs focused tests and beta confidence
`destructive`	row/column delete, move, insert, raw `batchUpdate`	Needs explicit approval and live test-sheet verification
`mcp-read`	read/search/inspect tool behavior	Usually safe after docs/skills sync and tests
`mcp-write`	write guards, rows/columns, safety helpers	Blocks production unless explicitly waived after beta verification
`ui`	landing, auth, dashboard, design system	Needs visual QA and auth smoke
`package`	dependency, lockfile, build config	Needs install, audit, tests, lint, build
`auth`	login, OAuth, session, proxy, Better Auth code	Production-impacting because beta and production share auth infrastructure
`db`	migrations, shared data model, direct database access	Production-impacting because beta and production share one Supabase database
`infra`	Next.js, TypeScript, lint, build, deploy config	Needs install, tests, lint, build, and deployment review
`skills`	published agent skills or skill bundle source	Needs `npm run skills:check` and source/mirror consistency review
`docs`	public docs and agent-facing docs	Needs docs build and consistency review
`release-governance`	audit scripts, release docs	Needs local audit tests and repo hygiene checks

Local Audit

Run the release audit before opening or merging release PRs:

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

For beta work:

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

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

clean worktree unless --allow-dirty is passed
origin/main is already contained in origin/beta for production preparation
candidate includes the selected base ref
production candidates are not wholesale origin/beta or branches created from an ahead origin/beta
changed files are bucketed by risk class
production-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

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 any release candidate:

npm test
npm run lint
npm audit --audit-level=moderate
npm run build
git diff --check

Package or build-system candidates also require a clean install:

npm ci

Skill changes require:

npm run skills:check

Production Promotion

Merging to main creates a production build in Vercel, but serving users still requires explicit approval.

After a main PR merges:

Verify Vercel reports the deployment ready for the merged commit.
Run basic HTTP smoke checks on the staged deployment.
Ask for explicit approval.
Promote with npx vercel promote <deployment-url> --yes.

Do not silently promote production. Do not use vercel alias set or Preview promotion as the normal production path.

Beta Reconciliation

After every main release, reconcile main back into beta.

The beta reconciliation PR should be ancestry-focused. If conflicts appear, preserve beta behavior and only apply the production release fix where beta still needs it.

The expected graph after reconciliation:

git rev-list --left-right --count origin/main...origin/beta
# expected: 0 <beta-only-count>

That means main is an ancestor of beta, and future release audits do not have to reason about duplicate production commits.

Known Maintenance Warnings

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

local Vercel CLI may be behind the latest version
docs build may emit Fumadocs/Webpack cache warnings
standalone tsc can require generated Fumadocs source first
npm ci may report node-domexception deprecation

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

Release Governance

On this page