Skip to content

BLU Execution Rules & Work Lifecycle Model

1. Core Engineering Doctrine (Strict Order)

  1. Evidence before reasoning.
  2. Research before implementation.
  3. Upstream before custom.
  4. Configuration before code.
  5. Composition before implementation.
  6. Deletion before creation.
  7. Convergence before expansion.
  8. Execution before communication.

2. Research First

Before ANY change, establish with citations:

  1. Engineering Standard (locate via qmd query -c BluCity-Docs "<topic>"; if qmd unavailable, direct reads — record the fallback).
  2. Authoritative Bluefly document.
  3. Authoritative upstream documentation.
  4. Authoritative upstream repository.
  5. Existing implementation.
  6. Existing deployment method.

If evidence is unavailable: state UNKNOWN. Never replace missing evidence with reasoning.

3. Ownership Ladder (Engineering Decision Contract)

Every implementation must answer:

  1. Can the nearest owner (application) own this?
  2. Can an upstream project or vendor own this?
  3. Can another established authority own it (Docker, Terraform, GitLab, OCI, Drupal, ClickHouse, Kubernetes, Cloudflare)?
  4. Can configuration replace implementation?
  5. Can composition replace ownership?
  6. If Bluefly owns this — what governance capability requires it?
  7. What future event deletes this ownership?

If no governance capability exists: do not build it.

4. Platform Responsibilities

Terraform owns provisioning. GitLab owns source, CI, and release. Docker owns container lifecycle. OCI owns infrastructure. 1Password owns secret delivery. Gas City owns orchestration. Beads hold durable work. Formulas hold repeatable method. Rigs define project scope. Packs carry reusable configuration. Drupal owns application and business behavior (as a Rig, not a second scheduler). DDEV is an execution surface. OpenClaw owns operator interaction with running systems. Agent sessions are disposable. Chat is not the work graph. Bluefly owns only governance, composition, contracts, policy, evidence.

Workers recover context with bd prime when identity/rules are missing, then discover work through gc hook, not fleet-wide bd ready. Full contract: beads-work-ownership-contract.md.

Derived views (search indexes, caches, embeddings, AI projections) are NEVER authoritative.

5. Artifact Authority

Artifact Type Canonical Owner
Engineering standards BluCity-Docs
Project documentation Repository (docs/, README, ADRs)
Temporary research Scratch/
Generated reports Project artifacts/ or Scratch/
Tool caches Tool-owned (~/.gemini, ~/.claude, etc.)
Operational knowledge BluCity-Docs (indexed by QMD)

Tool directories are never authoritative. Agents must not intentionally create, update, or maintain project artifacts in ~/.gemini, ~/.claude, ~/.cursor, ~/.codex, or any other tool-private cache. Those directories belong to the tool, not the project.

6. Execution Contract (Per Task Sequence)

  1. Search BluCity-Docs with QMD (qmd query -c BluCity-Docs "<topic>").
  2. Read existing Engineering Standards, ADRs, references, runbooks.
  3. Identify authoritative owner.
  4. Locate upstream documentation.
  5. Verify repository state (dirty, unpushed, branch, remote).
  6. Verify runtime (or record the evidence gap explicitly).
  7. Verify preconditions.
  8. Execute the smallest complete change.
  9. Verify against upstream.
  10. Curate: update canonical documentation if understanding changed.
  11. Close Bead. Future agents should need to rediscover less.

7. Documentation Curation

CURATE OVER CREATE. Before creating any document prove that existing documentation cannot be: merged, extended, renamed, moved, archived, simplified, deleted, or replaced with a redirect. Creating documentation is the final option. Document count should remain the same or decrease. Corrections to prior claims are dated [SUPERSEDED] annotations, never silent rewrites.

Documentation Convergence Rule

Before creating a new engineering document:

  1. Search BluCity-Docs with QMD.
  2. Update an existing canonical document if one already covers the topic.
  3. Only create a new document when introducing a genuinely new concept.
  4. If new upstream understanding changes previous guidance, revise the canonical document with a dated annotation noting what changed and why.

Every completed bead should leave the knowledge base better than it found it.

8. Deployment Contract

Deployments are the highest priority; everything else is subordinate.

Repair layers strictly in order — never debug downstream before upstream is healthy:

Git → GitLab → Terraform → Oracle → cloud-init → systemd → Docker → Gas Town → Gas City → OpenClaw → Applications → Smoke Tests

Delivery gates:

  • Every change must increase the probability that a completely fresh deployment succeeds from source alone. If it does not, do not make it.
  • Track-A invariant: no second terraform apply until the previous apply's state is verified in GitLab.
  • Deployment authority (shared runner / dedicated runner / manual operator) must be a recorded decision, not an assumption.
  • Definition of Done includes a fresh-clone test on a different machine: clone → authenticate → apply → provision verification → service verification, receipt committed.

9. Repository Hygiene

  • All work committed and pushed to its authoritative remote before task end; if not, explain why before continuing.
  • Report laptop-loss risk explicitly, separating: my work / other people's work / unknown ownership.
  • Plan files, state dumps, and .op-env artifacts are deleted, never committed.
  • Never leave work only on the workstation unless explicitly instructed.
  • Local workstation is not authority: Oracle → Gas City → Gas Town before local. Local is validation and development only.

10. Execution Receipts

  • Evidence artifacts and receipts land in ledger/Evidence/ (extend existing files for the same date/subject rather than creating new ones).
  • Status/handoff reports use the structure: Current State → Verified Evidence → Known Blockers → Next Execution, with evidence cited as MR/pipeline/commit identifiers, expected state labeled INFERRED with Verification Required commands, and provisioning separated from validation in sequences.
  • Task-end output follows the Reporting Contract in blu-identity.md.

11. Authoritative Execution Stages

Every material code or infrastructure modification must move through the canonical 3-Stage lifecycle:

Stage 0: Dolt Synchronization & Health Gate
  └── Confirm city Beads/Dolt health. Do not bd init / gc init because a command failed.
Stage 1: Recover identity and pull routed work
  └── gc hook → bd show <id> → bd update <id> --claim
      Coordinators/triage may inspect bd ready; workers do not browse the global backlog.
Stage 2: Authoritative Mutation Workflow
  └── Claimed Bead -> Worktree -> Implement -> Validate -> Commit -> MR -> CI -> Merge to release/v0.1.x -> Close Bead

12. Platform Authorities Matrix

Platform Authority Domain Owned Published Contract Interface Private Implementation (Hidden)
Git Source history Git CLI & Protocol .git internals
GitLab Branches, MRs, CI, merges GitLab API, glab, Git GitLab Database
Beads Work state, dependencies bd CLI Dolt schema, internal tables
Dolt Versioned persistence bd dolt, Dolt SQL Internal storage engine
Cedar Authorization decisions Policy evaluation contract Cedar policy storage
1Password Authentication & Secrets CLI (op), Connect SDK Vault internals
Gas City Multi-agent orchestration gc CLI & API City runtime internals

13. Work Authorization & Claim Rules

What a READY Bead Is

A READY Bead is not a fix. It is the smallest experiment that meaningfully reduces uncertainty or resolves verified drift.

This governs bead authoring; rules below govern claiming and closing.

Required Fields

Every READY Bead contains exactly these eight:

Field Requirement
Bead ID Stable identifier naming the objective, not the diagnosis
Priority Ranked on evidence — blast radius and blocked work, not intuition
Authority Which authority owns the decision
Owning Repository Where the change lands. If unknown, the bead is not READY
Observed Evidence gathered, with its measurement boundary
Engineering Impact What is degraded or at risk while the drift persists
Acceptance Criteria The condition that closes the bead, stated as an observable outcome
Verification Method How that condition is checked, and by whom

Uncertainty-Reduction Beads

A bead reducing uncertainty — where the cause is not yet established — may additionally state:

Field Requirement
Confidence Per execution-receipt-specification.md vocabulary
Blocking Unknowns What remains unestablished, stated explicitly
Possible Outcomes What each result implies — including what would disprove the bead

Verified engineering drift shall not include speculative fields.

Claim Rules

  1. Bead Prerequisite: Never edit files, create branches, install packages, or change state without an active Bead claimed via bd update <BEAD_ID> --claim after gc hook.
  2. Claim Synchronization: Workstation claims are not globally authoritative until committed or pushed to the central Dolt server (bd dolt push).
  3. Loss of Claim: If synchronization loses the race (CLAIM_LOST), stop execution immediately and return to gc hook. Do not pick a different bead from a fleet-wide bd ready unless you are the coordinator.
  4. Closure Gate: A Bead must remain open until MR is merged to release/v0.1.x, CI passes, and verification receipt is recorded. Only then run bd close <BEAD_ID>.