Branches And Continuity
This page explains the default branch model, the write boundary between branch work and main, and the interruption path.
1. Default Branch Model
The default branch model is small and explicit.
| Stage | Where it happens | What it is for |
|---|---|---|
| bootstrap | local repo creation | create the first contract and the first rendered state |
local clone with local .git |
local worktree | implementation, local preview, decisions, JSON state updates |
| feature branch | branch work | commit the candidate change and push it for review |
| pull request | review boundary | deterministic checks now; multi-tool review later |
main before launch |
protected hosted preview boundary | deploy the current continuity state to www.preview.<product-domain> behind Cloudflare Access |
main after launch |
maintenance and live boundary | render Markdown state views from JSON and deploy the public host |
GitHub is the operational truth for branch movement and merge history.
2. Canonical Lifecycle
flowchart LR
Human["Human scope + merge owner"]
Local["Local clone + local git"]
Branch["Feature branch"]
PR["Pull request"]
Claude["Claude review target"]
Gemini["Gemini review target"]
Gate["Merge gate\ndeterministic today\nClaude and Gemini later"]
Main["main branch"]
Preview["Protected preview\nwww.preview.<product-domain>"]
Render["CI render on main"]
Human --> Local
Local --> Branch
Branch --> PR
PR -.blocking findings.-> Claude
PR -.broad notes.-> Gemini
PR --> Gate
Gate --> Main
Main --> Preview
Main --> RenderShow diagram source
flowchart LR
Human["Human scope + merge owner"]
Local["Local clone + local git"]
Branch["Feature branch"]
PR["Pull request"]
Claude["Claude review target"]
Gemini["Gemini review target"]
Gate["Merge gate\ndeterministic today\nClaude and Gemini later"]
Main["main branch"]
Preview["Protected preview\nwww.preview.<product-domain>"]
Render["CI render on main"]
Human --> Local
Local --> Branch
Branch --> PR
PR -.blocking findings.-> Claude
PR -.broad notes.-> Gemini
PR --> Gate
Gate --> Main
Main --> Preview
Main --> Render3. Lifecycle Writer Boundary
| Phase | Allowed writer | Allowed writes |
|---|---|---|
| bootstrap | bootstrap script | initial repo files, first rendered state, .execution/bootstrap.state.json |
| branch work | human and the current builder CLI | code, DECISIONS.md, STATE.json, DELTA.json, RISKS.json |
| PR audit | Claude Code, Gemini CLI, and deterministic CI steps | findings, comments, failing checks; not machine truth |
| post-merge render | CI on main |
STATE.md, DELTA.md, RISKS.md |
The file-by-file write contract lives in Repo Structure. This page only covers when each actor writes.
During PR review, machine truth still lives in STATE.json, DELTA.json, and RISKS.json. Rendered Markdown stays behind until post-merge CI on main. If a reviewer needs the current readable view before merge, they should inspect JSON directly or run the local renderer.
4. Interruption Handling
GoingNinja started from a simple requirement: work must survive interruption.
Two continuity files matter here:
.execution/bootstrap.state.json.execution/bootstrap.log
If bootstrap stops after GitHub setup but before Neon setup, the checkpoint file records the completed phases. The next run skips what already finished.
Idempotency rule:
- each phase is a no-op when its checkpoint boolean is already
true - each phase reruns when its checkpoint boolean is still
false - partially failed phases stay
false, so the next run retries them instead of inventing state
If the shell is lost, the recovery path is:
cd /path/to/goingninja-os
./scripts/load-global-providers.sh check
eval "$(./scripts/load-global-providers.sh exports)"
gh auth status
./scripts/bootstrap-project.sh ...
5. Current State
Described and implemented today:
- default branch is
main - generated repo includes
pr-audit.yml - generated repo includes
post-merge-state.yml - bootstrap continuity is encoded in
.execution/bootstrap.state.json - the global rule now treats
www.preview.<product-domain>behind Cloudflare Access as the canonical hosted pre-launch preview
Still open:
- the canonical open backlog lives in Workflow And Proof