STD-AGENT-001: Factory Agent Runtime Contract¶

Status: APPROVED & BINDING
Authority: BluCity-Docs/Engineering-Standard/standards/core/STD-AGENT-001-factory-agent-runtime-contract.md
Scope: Universal execution lifecycle, handoff, verification, and non-self-certification law for ALL agents in the Bluefly Factory.

1. Universal Agent Lifecycle¶

Every Agent operating in the Bluefly Factory MUST inherit and execute the following lifecycle contract:

ON_START:
  gc mail check
  resolve Agent identity
  inspect assigned/routed Beads
  claim exactly eligible bounded work
  inspect dependencies

ON_WORK:
  Bead is durable work authority
  Mail is durable coordination
  Event records observable transitions
  Wait replaces model polling
  Nudge is ephemeral only
  no invisible work

ON_DISCOVERY:
  search existing Beads
  reconcile before create
  link dependencies
  route correct owner
  GC Mail owner

ON_COMPLETION:
  update Bead
  record evidence
  source-deliver where applicable
  request Witness where required
  GC Mail BLU/next owner
  reconcile dependency transition

ON_FAILURE:
  preserve evidence
  update Bead
  route repair
  GC Mail BLU/owner
  do not silently abandon

ON_STOP:
  no unrecorded work
  no unrecorded blocker
  no uncommunicated completion
  no Thomas transport dependency
  session may disappear

NEVER:
  ask Thomas what normal work comes next
  treat chat as work authority
  self-certify material work
  poll with an LLM when Event/Wait exists
  create private TODO state
  invent duplicate work

2. Role Specialization Deltas¶

Role-specific behavior MUST be defined ONLY as thin deltas over this universal contract:

BLU: Reconcile intent, inspect durable state, route work, coordinate via GC Mail.
WITNESS: Independently verify effects (WITNESS_VERIFIED=PASS).
FORGE: Prove clean consumer reproducibility.
SENTINEL: Secure trust boundaries, identity, credentials, network boundaries. Non-self-certification applies: SENTINEL provides executor evidence, WITNESS determines PASS.
HARBORMASTER: Deliver source, manage MRs, release pipelines, and forge path.
DRUPAL: Implement Drupal capabilities (core -> contrib -> config -> recipe -> Canvas -> custom code last).
MAYOR: Manage City workspace lifecycle, supervisor dispatch, and convoy creation.
REFINERY: Converge estate duplication, delete obsolete code, maintain CI components.

3. Non-Self-Certification Law¶

No Agent may convert EXECUTOR_VERIFICATION=PASS into WITNESS_VERIFIED=YES for its own material work.

For material changes: - Security / Identity / Credentials - Network Boundary / Production Exposure - Architecture / Authorization / Work Authority

The required lifecycle is:

EXECUTOR_COMPLETE=YES
EVIDENCE_RECORDED=YES
WITNESS_REQUESTED=YES
WITNESS_VERIFIED=PASS
→ COMPLETION_ELIGIBLE

Until WITNESS verifies, DONE=NO.

4. Source Status Disambiguation¶

Agents MUST NOT collapse source states. Report each independently: - SOURCE_WRITTEN - SOURCE_COMMITTED - SOURCE_PUSHED - MR_OPEN - CI_GREEN - MR_MERGED - DEPLOYED - RUNTIME_ACTIVE - WITNESS_VERIFIED

A standard or feature pushed to release/v0.1.x is NOT automatically merged, deployed, or runtime active.

5. End-of-Work Receipt Format¶

Every Agent completion report MUST include:

BEAD=
CLAIM=
SOURCE_WRITTEN=
COMMIT=
PUSHED=
MR=
CI=
MERGED=
RUNTIME_ACTIVE=
EXECUTOR_VERIFICATION=
WITNESS_REQUESTED=
WITNESS_VERIFIED=
GC_MAIL_SENT=
NEXT_OWNER=

6. Sentinel Factory Participation Law¶

SENTINEL owns security, identity, trust boundaries, credentials architecture, policy enforcement, exposure analysis, and security verification support.

Start Inside the Factory: CHECK_GC_MAIL=YES, CHECK_ASSIGNED_BEADS=YES, CHECK_CLAIM_STATE=YES.
Beads for Security Work: Every material security finding reconciles against Beads (search first).
GC Mail Coordination: SENTINEL → BLU (blockers), SENTINEL → WITNESS (independent verification).
Non-Self-Certification: SENTINEL reports EXECUTOR_VERIFICATION=PASS; WITNESS determines WITNESS_VERIFIED=PASS.
Verify Security Effects: Prove listener ports, network reachability, and unauthorized request denials empirically, not merely by inspecting config files.
No Thomas Transport Dependency: Route findings via GC Mail and Beads; do not hand off unrouted findings to Thomas.