Gas City Doctrine Enforcement (v2.0) - Sessions perform work. (Sessions are disposable). - Beads remember work. (Durable universal substrate). - Convoys group work. - Mail coordinates work. - Formulas remember how. (Reusable methods). - Agents execute. - Packs configure. - Rigs scope. - Orders trigger. - Events prove what happened. - Work is not complete until verified and promoted (Capability, Skill, Formula, Pack, Order, Policy). (No parallel "learning lifecycles" or "agent memory" outside this machinery).

Bluefly Gas City — Beads Work Ownership Contract

Current docs.gascity.com is the primary authority for Gas City semantics. This file is Bluefly execution policy around that orchestrator. If it disagrees with current upstream docs or the installed gc, the defect is here.

Projected agent copy (must not contradict this file): platform/beads/skills/beads-work-discipline/SKILL.md in blueflyio/blu/blucity-packs.

Git/worktree mechanics are not Beads semantics. They come from ES-GITCC and city AGENTS.md.

You are operating inside a Gas City-managed Bluefly environment.

Beads are not optional note-taking.

BEADS = DURABLE WORK AUTHORITY.

Every meaningful unit of work that survives the current command/session must be represented by a Bead or attached to an existing Bead.

Your job is to:

discover work claim work execute work record evidence route dependencies/blockers finish the GitLab lifecycle close only when actually complete leave a durable handoff if unfinished

Do not make Thomas act as the dispatcher, message bus, task tracker, or reminder system.

Six primitives (do not collapse them):

Primitive	Role
Agent	who
Bead	what
Formula	how
Rig	where
Pack	configuration
Event	observation

Beads are the universal durable work substrate: tasks, epics, mail, convoys, formula materialization, dependencies, labels, and agent work state all resolve through Beads.

Durable loop:

MAYOR/COORDINATOR
      |
      | gc sling
      v
    BEAD
      |
      | visible through work_query
      v
   gc hook
      |
      | atomic claim
      v
    AGENT
      |
      | execution
      v
  GitLab MR
      |
      v
release/v0.1.x
      |
      | verification
      v
 bd close

Removed from the generic Beads skill (never restore):

bd prime as the work picker (it remains context recovery)
fleet-wide bd ready as the worker picker
bd worktree create .git/checkouts/...
git pull --rebase as automatic session close
clear stashes / prune remote branches as Beads semantics

================================================== 0. FIRST — DETERMINE WHETHER GAS CITY APPLIES ==================================================

Before using this contract, verify this is a Gas City / Beads workspace.

Inspect:

.beads/ .gc/ city/rig context $GC_AGENT if available

If .beads does not exist and this is not a projected Gas City workspace:

BEADS_APPLIES=NO

Do not initialize a new Beads store merely because one is missing.

Do not run:

bd init dolt init gc init

unless creation of a new city/store is explicitly the assigned work.

================================================== 1. SESSION START — RECOVER CONTEXT ==================================================

Do not begin by asking:

"What should I work on?"

Recover your own context.

First determine:

AGENT= RIG= CITY= CURRENT_BEAD= HOOKED_WORK= WORKTREE= BRANCH=

Use the Gas City-native context/projection commands available to the current version.

Then inspect your hook.

Primary work-discovery mechanism:

gc hook

If agent identity cannot be inferred, use the explicit agent/session target supported by the installed gc version.

Gas City uses a pull model:

  routed work
      ->
  gc hook
      ->
  work_query
      ->
  bead discovered
      ->
  agent claims it

Do NOT replace gc hook with a fleet-wide:

bd ready

unless you are explicitly performing triage/coordinator work.

bd prime recovers identity and rules when context is missing. Do NOT treat bd prime as the primary worker ritual or work-dispatch mechanism. If a harness already injected Beads context, do not re-run it as a substitute for gc hook.

================================================== 2. CLAIM EXACTLY ONE WORK UNIT ==================================================

When gc hook returns an actionable Bead:

bd show

Read the ENTIRE work item before editing source.

Inspect:

title description type priority assignee labels parent dependencies blockers notes acceptance criteria existing MR existing branch/worktree

Then claim it using the current supported Beads claim operation:

bd update --claim

Do not claim five unrelated Beads just because they are ready.

Normal worker behavior:

ACTIVE_CLAIM_COUNT=1

Exceptions:

coordinator refinery witness explicit multi-item formula step

Claiming means:

I OWN THE NEXT ACTION

It does NOT mean:

I may leave it in_progress indefinitely.

================================================== 3. NEVER DUPLICATE EXISTING WORK ==================================================

Before creating a Bead, search existing work.

Search by:

exact subsystem error signature project MR branch capability related bead ID

If existing Bead owns the work:

UPDATE/LINK EXISTING BEAD

Do not create another Bead merely because you encountered the problem from a different session.

Classify:

EXISTING_OWNER DUPLICATE CHILD_WORK NEW_WORK

Create only for NEW_WORK or legitimate CHILD_WORK.

================================================== 4. BEAD TYPES ==================================================

Use the smallest correct work unit.

EPIC multi-step outcome containing dependent work

TASK bounded implementation work

BUG proven defect

FEATURE new product behavior

QUESTION / DECISION unresolved decision that genuinely blocks implementation

DOCS durable documentation work

VERIFICATION use the appropriate supported type/label for proof-only work

Do not turn every observation into an epic.

================================================== 5. DEPENDENCIES ARE EXECUTION GRAPH, NOT PROSE ==================================================

If B cannot start until A is complete:

encode dependency A -> B

Do not merely write:

"waiting for A"

in a comment.

Gas City's orchestration depends on Beads dependency state so that bd ready / work_query only exposes unblocked work.

Use Beads dependency primitives supported by the installed version.

Target:

READY means actually executable

not:

READY but secretly blocked by prose in notes.

================================================== 6. ROUTING VS CLAIMING ==================================================

These are different.

ROUTING:

gc sling ...

means:

make this work available to a specific agent or pool

CLAIMING:

gc hook bd update --claim

means:

this agent accepted responsibility for the work

Do not confuse:

ROUTED=YES

with:

STARTED=YES

And do not confuse:

STARTED=YES

with:

COMPLETE=YES

Track separately:

ROUTED= CLAIMED= STARTED= SOURCE_DURABLE= MR_OPEN= CI_PASS= MERGED= VERIFIED= CLOSED=

================================================== 7. WORK MUST USE THE CORRECT RIG ==================================================

A Bead belongs to work authority.

A rig is the project/workspace where that work executes.

Do not create a new rig because a GitLab project exists.

When claiming:

confirm the Bead's intended rig/project

Then work in the real existing source checkout/worktree.

If no correct rig/workspace exists:

record WORKSPACE_BLOCKED route creation/binding to the owner continue any safe investigation

Do not silently mutate city topology.

================================================== 8. BLUEFLY WORKTREE + BRANCH LAW ==================================================

Never work directly on main.

Never make arbitrary:

.git/checkouts/*

unless that is explicitly the governed project pattern.

Bluefly source lifecycle:

  claimed Bead
      ->
  feature/fix/chore branch
      ->
  bead-named or work-specific worktree
      ->
  implement
      ->
  test
      ->
  commit
      ->
  push
      ->
  MR
      ->
  release/v0.1.x
      ->
  CI
      ->
  merge
      ->
  verify
      ->
  cleanup

ABSOLUTE:

feature/ -> release/v0.1.x fix/ -> release/v0.1.x chore/* -> release/v0.1.x

NEVER:

feature -> main fix -> main chore -> main main -> release/v0.1.x

release -> main is a separate protected promotion workflow.

================================================== 9. NO BLIND REBASE/PULL ==================================================

Do NOT use generic instructions like:

git pull --rebase

as part of automatic session completion.

Before synchronizing source:

determine current branch determine upstream fetch inspect divergence

Never replay main into release.

Never normalize history merely because a generic Beads skill says to.

================================================== 10. EXECUTION — DO THE WORK ==================================================

After claiming:

inspect implement test commit push open/update MR monitor/fix CI merge when criteria permit verify result

Do not stop at:

"I found the problem."

Do not stop at:

"This needs another specialist."

If it is inside your domain:

YOU OWN THE OUTCOME.

If another agent owns one dependency:

create/link dependency sling to owner continue whatever is unblocked return when dependency completes

Routing a dependency does not surrender parent responsibility.

================================================== 11. BLOCKERS ==================================================

When blocked, classify:

SOURCE_BLOCKED CI_BLOCKED DEPENDENCY_BLOCKED RUNTIME_BLOCKED AUTH_BLOCKED TOOLING_BLOCKED HUMAN_BLOCKED

Important:

SANDBOX_BLOCKED != HUMAN_BLOCKED TOOLING_BLOCKED != HUMAN_BLOCKED ANOTHER_AGENT_NEEDED != HUMAN_BLOCKED

Only escalate to Thomas for genuinely nondelegable decisions:

protected release -> main promotion legal/billing true credential authority irreversible destructive authorization explicit architecture/product decision with no standing rule

Otherwise route the blocker.

================================================== 12. CREATE FOLLOW-UP WORK IMMEDIATELY ==================================================

During implementation, if you discover legitimate additional work that cannot be completed inside the current Bead:

search for existing Bead first

then either:

link existing Bead

or:

create child/follow-up Bead

Add:

WHY_DISCOVERED= PARENT= BLOCKS= EVIDENCE= NEXT_ACTION=

Do not leave TODOs only in source comments, terminal output, or chat.

================================================== 13. MR LINKAGE ==================================================

A Bead doing source work must eventually identify:

PROJECT= BRANCH= WORKTREE= MR= TARGET=release/v0.1.x

Use supported Beads metadata/labels/notes for the installed version.

Do not rely only on an MR URL label if structured metadata exists.

The minimum durable relationship is:

BEAD -> BRANCH -> MR -> RELEASE

================================================== 14. CI FAILURE ==================================================

If MR CI fails:

investigate root cause

If project-specific source failure:

fix current project

If shared GitLab component failure:

route/fix canonical gitlab_components owner

Do not copy shared CI logic into the consumer repo.

Update the Bead with:

CI= FAILURE_SIGNATURE= ROOT_CAUSE= OWNER= NEXT_ACTION=

Then continue execution.

================================================== 15. HANDOFF ==================================================

If you must stop before completion:

Add a durable Bead note/comment containing:

HANDOFF CURRENT_STATE= LAST_VERIFIED= BRANCH= WORKTREE= LAST_COMMIT= PUSHED= MR= CI= BLOCKER= NEXT_EXACT_ACTION=

Do not write:

"someone should look at this"

Write the exact continuation point.

The next agent must be able to recover without reading the old chat.

================================================== 16. COMPLETION RULE ==================================================

A source-code Bead is NOT complete merely because:

code is written commit exists branch is pushed MR exists CI is green

Normal terminal condition is:

MR merged to release/v0.1.x AND acceptance criteria satisfied AND result verified

Then:

close Bead

Use the supported close operation:

bd close ...

Include concise outcome/evidence.

Do not close before merge unless the Bead is explicitly a research, decision, documentation, or verification task whose own acceptance criteria are complete.

================================================== 17. CLEANUP AFTER COMPLETION ==================================================

Only after proving branch contents are contained in release:

git fetch origin

and prove ancestry/containment.

Then:

remove completed worktree remove merged local branch prune stale worktree metadata where safe

Use governed worktree removal/trash semantics.

NEVER:

rm rm -rf git clean git reset --hard git stash

Do not destroy unexplained dirty state.

If dirty/unexplained:

ABANDONED_REQUIRES_REVIEW

================================================== 18. AGENT STARTUP LOOP ==================================================

Every standing worker agent should conceptually execute:

  bd prime when context recovery is required
      ↓
  RECOVER IDENTITY
      ↓
  gc hook
      ↓
  work found?
      |
      +-- NO --> remain idle / wait according to agent lifecycle
      |
      +-- YES
            ↓
        bd show
            ↓
        validate dependencies + ownership
            ↓
        bd update --claim
            ↓
        execute
            ↓
        durable GitLab state
            ↓
        verify
            ↓
        close
            ↓
        gc hook again

Do not ask Thomas for the next task after every completion.

Pull the next authorized work from the graph.

Conceptual model:

  bd prime               = WHO AM I / WHAT ARE THE RULES?
  gc hook                = WHAT WORK WAS ROUTED TO ME?
  bd show                = WHAT EXACTLY IS REQUIRED?
  bd update <id> --claim = I OWN THIS NEXT ACTION
  Beads dependencies     = WHAT MUST HAPPEN FIRST?
  GitLab MR              = WHERE SOURCE BECOMES DURABLE
  bd close               = VERIFIED OUTCOME IS COMPLETE

CLI footguns (do not hide these in folklore):

  bd update --notes     = REPLACES notes (`bc-joe`); use `--append-notes`
  bd ready --limit=0    = was literal zero on bd 1.1.0-dev (`hq-jvpn`);
                          on bd 1.2.2 help says "use 0 for unlimited"
                          and a live check returned the full ready set
  gc sling exit 0       = not proof the target hook/claim exists

Never conclude "no ready work" from bd ready --limit=0 without checking bd --version and a default or positive-limit bd ready. An older build reported an empty set with exit 0 while ready work existed.

After gc sling, verify delivery. Sling exit 0 is not proof the target agent has hooked or claimed the work.

================================================== 19. COORDINATOR / MAYOR LOOP ==================================================

Coordinator agents do NOT implement every Bead themselves.

They:

inspect ready/blocking work identify correct owner gc sling work verify claim occurred monitor terminal state route blockers maintain dependency graph

Coordinator success:

work moves without Thomas manually relaying messages.

Do not report ROUTED and call it complete.

Verify:

ASSIGNED CLAIMED EXECUTING COMPLETE

================================================== 20. POOL AGENTS ==================================================

Pool agents should consume pool work through their configured work_query.

Do not have multiple pool workers blindly:

bd ready

against the whole database.

Gas City's pool model uses labels/unassigned work so one worker can claim one item atomically.

Use the configured Gas City mechanism.

Do not invent a second scheduler.

================================================== 21. FORMULAS AND EPICS ==================================================

Do not manually micromanage a graph that belongs in a Formula.

For repeatable multi-step work:

define/use Formula materialize work graph express dependencies allow dispatcher to fan ready work out

Use an Epic for durable outcome grouping where appropriate.

FORMULA = how EPIC/BEADS = durable work/state

Do not collapse these concepts.

================================================== 22. BEADS ARE NOT SOURCE CONFIGURATION ==================================================

Keep these boundaries explicit:

GitLab source = code/config/release authority

Beads/Dolt = work/state authority

Gas City = orchestration/runtime

Do not write runtime Beads identity into portable Git source merely to make a diagnostic green.

Do not commit local:

project_id endpoint_status machine listener state Mac-only prefixes/identity

unless the actual portable contract explicitly requires them.

================================================== 23. BLUEFLY AUTHORITY ==================================================

For the production city:

ORACLE = canonical running work authority

canonical Dolt: 127.0.0.1:3308 database=hq

Mac may host disposable/projected runtime state.

NON_CANONICAL != DISPOSABLE_WITHOUT_PROOF.

If Mac/local Beads contain unknown or disconnected work:

preserve compare reconcile

before retirement.

================================================== 24. NEVER INVENT WORK AUTHORITY ==================================================

Do not create:

arbitrary new project_id arbitrary prefix arbitrary database arbitrary rig arbitrary store arbitrary Bead duplicate

because a command failed.

Failure to access the work graph is a tooling/runtime defect.

It does not authorize creation of a second work graph.

================================================== 25. SESSION RECEIPT ==================================================

At important checkpoints or handoff, record:

AGENT= RIG= BEAD= PARENT= STATUS= CLAIMED= WORKTREE= BRANCH= LAST_COMMIT= PUSHED= MR= MR_TARGET= CI= BLOCKERS= DEPENDENCIES_CREATED= DEPENDENCIES_ROUTED= ACCEPTANCE= VERIFICATION= NEXT_ACTION=

================================================== 26. SUCCESS CONDITION ==================================================

The agent system is healthy when:

Thomas defines priority/outcomes Gas City routes work agents claim from hooks Beads record durable state dependencies control readiness agents execute autonomously GitLab contains durable source CI verifies it release/v0.1.x receives completed work Beads close only after verified completion the next ready work is automatically discoverable

Target:

HUMAN_AS_MESSAGE_BUS=NO UNCLAIMED_ROUTED_WORK=0 STRANDED_LOCAL_WORK=0 CLOSED_WITHOUT_PROOF=0 DUPLICATE_BEADS=0 FEATURE_TO_MAIN=0 VALID_WORK_DISCARDED=0