Track O — Stage 3 upgrade operator runbook
Operator path for muse-only → muse+git-mirror using the kit ceremony
orchestrator. Ground truth: frozen
docs/archive/phases/PHASE-TRACK-O-O2-STAGE3-UPGRADE-CEREMONY.md (§O2.3–§O2.7).
This is not product unlock. Product Stage 3 one-click may wrap only
ok upgrade-regime after Track O / O3 build-verification → pass and the
§O2.6 checklist (explicit C6 consent; never auto C8).
Hard stops:
- Never edit only
vcs.regimein.overseer/config.yaml - Never
muse bridge git-export --git-dir . - Never
git push <remote> <main_branch> - Never merge
muse-mirror→mainwithout Tier-3 authorization (C8) - No live consumer
ok initfrom this runbook
Prerequisites (C0)
| Check | Notes |
|---|---|
Existing .overseer/config.yaml with vcs.regime: muse-only (or incomplete muse+git-mirror for repair) |
Wrong start (git-only / missing) → refuse; use greenfield ok init or a later freeze |
| Muse substrate usable for the tree | Required for later live bridge |
muse on PATH |
For C7 only |
Empty GitHub repo + git remote add for vcs.git.remote |
Product/operator work before C7; enforced by G8 |
Work on a feature branch.
Ceremony (C1–C8)
| Step | What | Writes? |
|---|---|---|
| C1 | Start-state gate (muse-only / complete / incomplete repair / refuse) | No |
| C2 | Complete VCS write preserving docs.* / repo.* |
Config |
| C3 | Footprint re-seed (ok sync composition) |
Bridge files + lock |
| C4 | Footprint present in lock + disk | No |
| C5 | Bridge dry-run gates G1–G8 (no live export) | No |
| C6 | Explicit consent before live | No |
| C7 | First live bridge via ./scripts/muse-bridge-deploy.sh |
Mirror + muse-mirror |
| C8 | Merge PR → main |
Tier 3 — stop |
Commands
Dry-run (default; product wrappers until live)
./cli/ok -C <repo> upgrade-regime --from muse-only --to muse+git-mirror --dry-run --json
Runs C0–C5 planning + G1–G8 report. Sets ready_for_live_bridge: true only when
all of G1–G8 pass. If G8 fails, footprint gates may still be OK separately.
Apply (config + footprint; no live bridge)
./cli/ok -C <repo> upgrade-regime --from muse-only --to muse+git-mirror --apply
Performs C2–C4 writes and C5 gates. Does not run C7 unless --live-bridge is also set.
Shared-asset conflict on hand-tuned bridge files → exit 4 without --force. With
explicit consent:
./cli/ok -C <repo> upgrade-regime --from muse-only --to muse+git-mirror --apply --force
--force never implies --include-preserved (living docs stay preserved).
Live bridge (C7 only after gates + consent)
./cli/ok -C <repo> upgrade-regime --from muse-only --to muse+git-mirror --apply --live-bridge -y
Requires G1–G8 pass and -y / --yes. Refuse --yes alone without gate success.
C7 failure does not auto-revert config/footprint to muse-only.
Idempotent re-run
Already muse+git-mirror with bridge footprint OK → exit 0, no rewrite.
Incomplete upgrade repair
Already muse+git-mirror but bridge files missing/mismatched → skip C2 when VCS already
complete; continue C3–C5.
After C5 / C7
- Confirm
ok status --check-footprint. - Open/update PR
muse-mirror→mainwhenghavailable (deploy script does this). - Stop before merge — C8 is Tier 3.
Day-to-day publish remains: feature work → safe bridge → PR, never push canonical main.
Cross-references
- Freeze:
docs/archive/phases/PHASE-TRACK-O-O2-STAGE3-UPGRADE-CEREMONY.md - Product contract:
docs/TRACK-O-NORMIE-CUSTODY-PRODUCT-CONTRACT.md - K7 dogfood:
docs/archive/phases/PHASE-K7-MUSE-GIT-MIRROR-DOGFOOD.md/docs/K7-DOGFOOD-OPERATOR-RUNBOOK.md - Funnel:
docs/archive/phases/PHASE-TRACK-O-O0-NORMIE-CUSTODY-FUNNEL.md§O0.3.3