Skip to content

STD-CHECKPOINT-001: Checkpoint-Based Repository Convergence Standard

1. Purpose

This standard replaces sequential 15-phase waterfall execution loops with five checkpoint state gates for repository convergence across all Bluefly Factory repositories (BluCity-Packs, BluCity-Docs, DrupalWorks, GasCity, OpenClaw).

Each checkpoint is a state gate: the agent can move freely inside it to inspect, reconcile, fix, route, and verify, but CANNOT cross to the next checkpoint until all evidence criteria for that gate are fully satisfied.

2. Core Authority & Execution Law

  1. Strict Authority Boundaries: The Project Lifecycle Owner for a repository possesses mutation authority ONLY over their designated repository path (e.g. blueflyio/blu/blucity-packs). Cross-repository work MUST be represented through canonical Bead dependencies and routed to the owning Rig.
  2. Canonical Authorities:
  3. GitLab: Source / MR / CI / Release Authority
  4. Gas City: Upstream Orchestration Authority
  5. Beads / Dolt HQ: Canonical Work Authority
  6. Pack / Formula / Agent: Source-Controlled Configuration
  7. Mac Workstation: Disposable Projection
  8. Projections vs. Authority: implementation_plan.md and task.md are transient projections, NOT work authority. They MUST be updated continuously to reflect canonical Beads and GitLab states.

3. The Five Checkpoint State Gates

flowchart TD
    C1["Checkpoint 1: Authority & Work Graph"] -->|Gate 1 Pass| C2["Checkpoint 2: Dependencies & Merge Topology"]
    C2 -->|Gate 2 Pass| C3["Checkpoint 3: Merge Safety & CI"]
    C3 -->|Gate 3 Pass| C4["Checkpoint 4: Merge Queue & Execution"]
    C4 -->|Gate 4 Pass| C5["Checkpoint 5: Durability & Health Receipt"]

    C1 -.->|Fail/Backtrack| C1
    C2 -.->|Fail/Backtrack| C1
    C3 -.->|Fail/Backtrack| C2
    C4 -.->|Fail/Backtrack| C3
    C5 -.->|Fail/Backtrack| C4

Checkpoint 1 — Authority and Work Graph are Trustworthy

  • Required Outcome: One trusted canonical work graph reconciled across PWD, GIT_REMOTE, GitLab MRs, and Beads (bd).
  • Gate Criteria: AUTHORITY_BOUNDARY_VERIFIED=YES, CANONICAL_HQ_VERIFIED=YES, ALL_ACTIVE_MRS_CLASSIFIED=YES, UNKNOWN_VALUABLE_WORK=0.

Checkpoint 2 — Dependencies and Merge Topology are Proven

  • Required Outcome: Every MR and cross-Rig dependency has a proven place in the execution graph. Merge decisions are NEVER made from CI color alone.
  • Gate Criteria: MR_DEPENDENCY_GRAPH_PROVEN=YES, UNCLASSIFIED_OPEN_MRS=0, UNEXPLAINED_DIVERGENCE=0, UNROUTED_EXTERNAL_DEPENDENCIES=0.

Checkpoint 3 — Repository Content and CI are Merge-Safe

  • Required Outcome: Everything entering release/v0.1.x is structurally valid, portable, tested, and free of repository-owned CI defects.
  • Gate Criteria: PACK_VALIDATION=PASS, DANGLING_REFERENCES=0, PORTABILITY_VIOLATIONS=0, REPO_OWNED_PIPELINE_FAILURES=0.

Checkpoint 4 — Merge Queue and Ready Work are Exhausted

  • Required Outcome: All currently executable repository work is completed. Only genuinely blocked canonical work remains.
  • Gate Criteria: EXECUTABLE_UNFINISHED_BEADS=0, READY_MRS=0, ORPHAN_COMMITS=0, PLAN_STALE_ITEMS=0.

Checkpoint 5 — Durability and Health Receipt

  • Required Outcome: The workstation contains zero unique authority or valuable state. Project continuation is 100% possible from canonical systems alone.
  • Gate Criteria: VALUABLE_UNCOMMITTED_CHANGES=0, VALUABLE_UNTRACKED_FILES=0, LOCAL_ONLY_AUTHORITY=0, WORKSTATION_DISPOSABLE_WITHOUT_LOSS=PASS, HEALTH=CONVERGED.

4. Operating Loop

At any checkpoint, if new evidence invalidates an earlier assumption: - Return immediately to the affected checkpoint. - Repair the graph. - Update implementation_plan.md and task.md projections. - Re-evaluate the checkpoint gate.