Skip to content

Bluefly Work Record Emission Contract

Overview

This document defines how operations (Agents, Formulas, Orders) emit governed work records that conform to the bluefly.work-record.v1 schema, and how ContextControl consumes these records to render the factory state.

1. Emission Mechanism

Records MUST be emitted simultaneously to two durable stores: 1. Bead Notes: Embedded within the canonical Bead tracking the work, formatted as a JSON fenced code block. 2. Gas City Events: Broadcasted as an immutable gc event emit payload to enable real-time reactive supervision.

Format

The payload MUST be valid JSON conforming to the bluefly.work-record.v1 schema. In Bead Notes, the payload must be encapsulated as: 

{
  "record_type": "...",
  "state": { ... },
  "evidence": { ... }
}

2. Emission Points in the Governed Lifecycle

The governed-work-lifecycle Formula dictates the primary emission points:

  1. Intake (work-request-intake)
  2. Trigger: New Bead claimed or initialized.
  3. Record Type: request

  4. State: state.work = open

  5. Decision & Routing (blocked-work-route)

  6. Trigger: Agent handoffs, capability gaps, or architectural blockers.
  7. Record Type: decision

  8. State: state.work = blocked or open

  9. Reconciliation (delivery-reconcile)

  10. Trigger: CI pipelines run, or Merge Requests mutated.
  11. Record Type: progress

  12. State: state.work = in-progress, capturing MR states and pipeline status.

  13. Closure (receipt-on-close)

  14. Trigger: MR merged, verification passed.
  15. Record Type: receipt
  16. State: state.work = completed
  17. Evidence: MUST include wasGeneratedBy, wasDerivedFrom, and wasAttributedTo.

3. Projection Contract (ContextControl)

ContextControl acts as the projection and rendering layer for the Bluefly factory.

Consumption

  • It queries the active Bead graph.
  • It parses the Markdown notes to extract all json blocks matching the bluefly.work-record.v1 signature.
  • It listens to gc event stream for real-time updates.

Rendering

  • Work Timeline: Renders the sequence of request -> decision -> progress -> receipt.
  • Dependency Graph: Uses wasDerivedFrom links to draw the relationship between dependent Beads.
  • Verification Receipts: Highlights the final receipt record as the unforgeable proof of work, displaying attribution and tooling evidence directly to the operator.