GoingNinja Manual Knowledge Wiki logo
GoingNinja Manual Knowledge Wiki Lean MVP bootstrap documentation // Felix Rascher (WIP)

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

Show 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.&lt;product-domain&gt;"]
    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 --> Render

3. 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:

6. Sources