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

Workflow And Proof

This page shows the shortest serious path through the system and the proof status behind its main claims.

For the current explicit product-case proof, see Product Proof.

Status vocabulary used on this page:

Status Meaning
proven_local run end-to-end on a developer machine
proven_live run against a live provider or live hosted surface
proven_template present in the generated repo template, but not yet run live
pending_live code path exists, but the live run is still missing
open_by_convention documented as a platform contract, but not yet behavior-proofed
open not yet implemented

1. Minimum Reality Tests

For this system to count as real, at least these tests must hold:

  1. a new project can be bootstrapped from goingninja-os
  2. the generated repo has a deterministic file contract
  3. tools start from repo files, not hidden shell state
  4. the same tool does not build and approve itself
  5. machine truth is stored in JSON
  6. human-readable state is rendered from that JSON
  7. tools can execute and exit cleanly in a headless CI environment without hanging on user prompts

If one of these fails, the system is still only a concept.1

2. Reproducible Local Bootstrap

The current reproducible path is the local deterministic bootstrap path.

Command used:

cd goingninja-os
./scripts/bootstrap-project.sh \
  --target /absolute/path/to/goingninja-project-example-dashboard \
  --project-name "Example Dashboard" \
  --repo-slug goingninja-project-example-dashboard \
  --skip-github \
  --skip-vercel \
  --skip-neon
2

This path proves six things:

  • the starter template copies cleanly
  • placeholders are replaced
  • state views are rendered
  • a git repository is initialized
  • an initial commit is created
  • bootstrap continuity is recorded in .execution/bootstrap.state.json

It does not yet prove live GitHub, Vercel, or Neon provisioning.

3. Bootstrap Output Evidence

The detailed generated skeleton already lives in Repo Structure and the lifecycle boundary already lives in Branches And Continuity. This page keeps only the proof-specific evidence:

  • a local generated repo can be created from the template without manual file reconstruction
  • the generated repo contains the deterministic state files and workflows named in the template contract
  • the global provider path has already reached pushed GitHub main and a Vercel deployment in READY

That is enough for this page because the proof question here is not "what files exist?" but "which proof claims are already backed by evidence?"

The important distinction is:

  • global provider capability can already be proven
  • the current Tagnova proof case still has its hosted continuity-preview execution pending as a bounded next step

4. Current Lifecycle Boundary

The lifecycle diagram lives in Branches And Continuity. This page keeps the proof boundary instead of redrawing the same flow.

Current implementation boundary:

Live today:

  • deterministic PR checks and post-merge rendering
  • GitHub repo creation and remote wiring
  • Vercel project creation, local linking, and production deployment
  • Tagnova public-reading proof up to local verification only

Target loop:

  • Claude blocking review and Gemini broad-read review inside the generated PR workflow

Current status of that target loop:

  • documented in goingninja-manual and audited externally, but not yet fully generated into each project repo

Missing builder-side component:

  • a committed startup wrapper for the current builder surface so that AGENTS.md is attached deterministically without hidden shell state

In the target loop, a failing branch should re-enter PR audit through a corrected branch commit, which triggers pr-audit.yml again through the pull_request event.

5. What The PR Audit Actually Contains Today

The generated pr-audit.yml already proves the minimum gate exists:

name: pr-audit

on:
  pull_request:
  workflow_dispatch:

jobs:
  deterministic-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: node ./scripts/check-project-state.mjs .

The current state of that workflow is:

  • deterministic project-state checks are real
  • Claude and Gemini workflow wiring is still placeholder text
  • direct edits to STATE.md, DELTA.md, and RISKS.md are not yet blocked at PR time
  • therefore the audit shape is real, but the full multi-tool CI proof is not yet complete

To become a real PR review surface, the future Claude/Gemini path also needs a small reporter layer that translates CLI output into GitHub-native comments and blocking checks. Local CLI output alone is not enough.

6. Claim To Status To Evidence

Claim Status Evidence
one canonical AGENTS.md anchors the shared repo contract across three tools open_by_convention generated repo contains AGENTS.md, CLAUDE.md, and GEMINI.md; startup boundaries for the current builder CLI and the reviewer CLIs are documented in Vendor Sources
JSON is machine truth and Markdown is rendered view proven_local generated repo contains STATE.json, DELTA.json, RISKS.json, rendered Markdown views, and scripts/render-state-views.mjs
rendered state is maintained by CI on main after merge proven_template generated repo contains .github/workflows/post-merge-state.yml
role split is declared and merge authority remains human-owned by contract open_by_convention AGENTS.md declares the role split and leaves merge authority to the human
blocking CI review prevents the builder from approving itself open Claude and Gemini review steps are still placeholder text in pr-audit.yml
bootstrap resumes after partial failure proven_local local bootstrap run produced .execution/bootstrap.state.json with resumable step booleans
bootstrap calls official CLIs rather than raw provider HTTP APIs proven_local bootstrap script calls gh, vercel, and neonctl; there is no mixed curl-based bootstrap layer
review tools run non-interactively in CI without hanging on prompts open headless wrapper is still missing for Claude and Gemini review steps

7. Proof Backlog

The remaining proof work is concrete and enumerable.

Goal Pass criteria Current status
GitHub repo creation from bootstrap repo is created, origin is correct, and the first main push succeeds proven_live
Vercel project creation and linking project is created, local repo is linked, and production reaches READY proven_live
Hosted continuity preview for the current product proof the active proof repo is reachable on its protected preview host pending_live
Neon project and database creation project and database resolve, and linked names in STATE.json are no longer pending pending_live
OS-first product repo can move from fresh bootstrap to confirmed brief, requirements, architecture, readiness, and plan active proof case reaches planning without treating a historical repo as source of truth proven_local
PR-time blocking of direct edits to rendered Markdown state PR fails when STATE.md, DELTA.md, or RISKS.md are edited directly open
Live multi-tool PR gating against live Claude and Gemini providers both review steps run, one failing branch is forced through a visible fix loop, and findings reach GitHub as comments and blocking checks open

Note: pr-audit.yml currently runs only deterministic checks. Claude and Gemini review steps and the CLI-to-GitHub reporter layer are still open proof items.

8. Sources

Notes

  1. Implementation. goingninja-os/scripts/bootstrap-project.sh, generated .github/workflows/pr-audit.yml, and generated .github/workflows/post-merge-state.yml.
  2. Implementation. goingninja-os/scripts/bootstrap-project.sh.