STD-WORK-002: Durable Work and Knowledge State¶

1. Single Completion Law¶

Effective immediately, no Bluefly Factory change is complete unless its durable work state and durable knowledge state are updated as part of the same operation.

The required lifecycle is: BEAD → CLAIM → EXECUTE → VERIFY → RECORD EVIDENCE → UPDATE DURABLE KNOWLEDGE → SOURCE DELIVER → WITNESS → CLOSE

A change that skips any applicable stage is DONE=NO.

2. No Work Without a Bead¶

Before source or runtime mutation: - Must have an active BEAD_ID with BEAD_STATUS=in_progress. - The current executing Agent must be the OWNER. - If work exists, UPDATE_EXISTING_BEAD instead of creating duplicates.

3. One Execution Worker = One Claimed Bead¶

Every executing Agent/session must have ACTIVE_CLAIM_COUNT=1 unless a Formula explicitly requires otherwise. No invisible work or silent scope expansion.

4. Every Material Change Updates the Bead¶

The Bead is the durable work record. Update it immediately when root cause, scope, blocker, owner, branch, MR, commit, runtime state, acceptance, verification, dependency, or discovered defect changes. Do not bury machine-readable state only in prose.

5. Evidence Before Claiming Success¶

Before reporting success, record the evidence in the Bead. The Agent's own statement is not proof. Must state REQUESTED_EFFECT, OBSERVED_BEFORE, CHANGE, OBSERVED_AFTER, VERIFICATION_METHOD, COVERAGE, and KNOWN_LIMITS.

6. Documentation is Required When Knowledge Changes¶

Documentation is required when the work changes Architecture, Ownership, Operating Model, Security Model, Deployment Model, Configuration Model, API Contract, Product Boundary, Factory Standard, Recovery Procedure, or Known Limitations.

7. Document Authority Order¶

CURRENT SOURCE / LIVE RUNTIME
ENGINEERING STANDARD / ADR
PRODUCT AUTHORITY
PROJECT-SPECIFIC DURABLE DOC
BEAD
GENERATED REPORT / SCRATCH (Never authority)

8. When to Update BluCity-Docs vs Project Docs¶

Update BluCity-Docs only for durable cross-project knowledge (Factory architecture, Gas City standards, CI standards).
Project-specific implementation knowledge stays with the owning project (e.g., api_normalization architecture).

9. ADR Required for Material Architecture Decisions¶

Create or update an ADR when a decision changes system authority, source ownership, deployment topology, security boundary, storage authority, API exposure, or identity model.

10. Document What Changed, Not a Session Story¶

Canonical docs describe the resulting system. Answer: What is true now? Why? Who owns it? What is the supported path? What is not allowed? How is it verified?

11. Incidents Require Two Durable Records¶

BEAD: executable remediation work.
INCIDENT RECORD: durable technical learning (distinguishing observed vs inferred vs proven).

12. Source Delivery Applies to Documentation Too¶

Documentation is source. WORKTREE → BRANCH → COMMIT → MR → CI → MERGE.

13. RunningTodo is NOT the Work Authority¶

RunningTodo.md is a projection. Beads remain executable authority. Never close work because a checkbox is checked.

14. Economic & Product Impact Gates¶

Every change must answer its Product Impact (e.g., CUSTOMER_OPERATION_SERVED) and the Economic Gate (IS_THE_NEXT_RUN_GETTING_CHEAPER_AND_MORE_REUSABLE=YES|NO|NOT_ESTABLISHED). "Good architecture" is not sufficient by itself.

15. Agent Handoff Requires Durable State¶

Before handing work to another Agent: Update the Bead (CURRENT_STATE, NEXT_ACTION, BLOCKER, EVIDENCE) and route ownership. MAIL_SENT != HANDOFF_COMPLETE. The Bead is the handoff contract.

16. Witness Verifies the Effect¶

Witness does not merely verify that a commit, MR, or config file exists. Witness verifies the requested effect: runtime behaves correctly, API returns real data, policy actually denies/permits, Formula actually executes, event actually arrives, customer isolation actually holds. Then Witness records evidence in the Bead.

For material changes (production, security, identity, architecture, customer-facing behavior, work authority, data/storage), the executor does not independently decide the result is complete: EXECUTOR=done, WITNESS=pass → close.

17. Required End-Of-Work Receipt¶

Every material task ends with a formal receipt including BEAD, OWNER, RIG, REQUESTED_EFFECT, SOURCE_CHANGED, RUNTIME_CHANGED, DOCS_CHANGED, BRANCH, COMMIT, MR, CI, EVIDENCE, COVERAGE, KNOWN_LIMITS, BEAD_UPDATED, DEPENDENCIES_UPDATED, CANONICAL_DOC_UPDATED, DOC_PATH, SOURCE_DELIVERED, RUNTIME_VERIFIED, WITNESS_VERIFIED, IS_THE_NEXT_RUN_GETTING_CHEAPER_AND_MORE_REUSABLE, WHY, and NEXT_ACTION. No receipt = DONE=NO.

18. Learning Must Not Die in Chat¶

When an Agent discovers a reusable lesson: LEARNING → evaluate → durable Bead evidence → capability candidate if warranted. Do not immediately create a Skill. Evaluate the correct durable form first: policy, check, test, procedure, Formula, configuration, integration, or Skill. A Skill is only one possible form.

19. Repeat Work Must Be Promoted¶

When substantially the same action is performed REPEAT_COUNT >= 3 times, the Agent must ask IS_THIS_A_CAPABILITY_CANDIDATE=. If yes: record candidate, attach evidence, state limits, prove on second estate. Then consider reusable packaging. Do not keep solving the same problem manually.

20. Session End Gate¶

See STD-WORK-003 §1 (Agent Runtime Participation Contract) and communication-law.template.md for the canonical session start/end protocol. Do not restate it here.

21. MAYOR Enforcement¶

MAYOR does not perform the work. MAYOR continuously checks: - Unclaimed active work - Work without Beads - Merged MRs with open Beads - Closed Beads without evidence - Runtime changes without source - Source changes without doc updates - Doc changes without MRs - Stale in-progress Beads - Unverified completion

Every violation becomes: correct existing Bead, or new bounded governance defect. Do not write another general audit if deterministic detection can identify the violation.

22. BLU Enforcement¶

BLU owns convergence. BLU asks five questions continuously: 1. What customer operation are we proving? 2. What stage is it in? 3. What is blocking it? 4. Who owns that blocker? 5. Is the next run getting cheaper and more reusable?

BLU must reject work that has no Bead, no source owner, no evidence, no delivery path, no documentation disposition, or does not serve the active operation.

23. CI Should Enforce What Can Be Enforced¶

Where deterministic, add/reuse CI gates for: missing Bead reference in MR, missing architecture/doc disposition, stale generated docs, copied canonical policy, direct-runtime-only changes, forbidden local paths, unowned custom code, missing evidence metadata. Prefer existing gitlab_components. Do not build another validator if a current component can be extended.

24. Universal Factory Gate¶

See STD-GATE-001 (Engineering-Standard/operating-model/STD-GATE-001-factory-execution-gate.md) for the full pre- and post-execution gate. Do not restate it here.

25. Stop Dumping Context on the Operator¶

The Operator is not the factory's memory, message bus, or log collector. WRITE BEFORE YOU TALK. If it concerns active work: UPDATE THE BEAD. If it is reusable knowledge: UPDATE BLUCITY-DOCS. If another agent needs it: SEND GAS CITY MAIL. If it is raw command output: STORE AS EVIDENCE OR SUMMARIZE IT.

26. Agent Response Budget¶

Normal agent completion messages to Thomas should be no more than ~10 lines. Preferred format: STATUS: DONE | BLOCKED | NEEDS_OPERATOR BEAD: RESULT: <1-3 sentence summary> CHANGED: EVIDENCE: DOCS: NEXT:

Do not paste investigation diaries, giant tables, command transcripts, or file inventories unless explicitly requested.

27. Search Before Research¶

Before starting a new investigation: 1. Search relevant Beads. 2. Search BluCity-Docs. 3. Inspect current source/runtime when required. 4. Only then perform new research.

28. Do Not Duplicate Upstream Documentation¶

When upstream documentation (Drupal, Tailscale, Gas City, etc.) already defines a system correctly, reference it. Document only Bluefly-specific configuration, policy, integration, or deviation. Do not rewrite upstream documentation into BluCity-Docs.

Central Law¶

If the work happened but the Bead was not updated, the Factory does not know it happened.
If the architecture changed but the documentation was not updated, the next Agent will rediscover or contradict it.
If runtime changed without source delivery, the next deployment can erase it.
If the Agent claims success without evidence, the result is not trusted.
Documentation, work state, source delivery, and verification are all part of the work itself.