BLUEFLY PORTABLE CONTEXT & HANDOFF DIRECTIVE

Standard: STD-CONTEXT-001 Status: CANONICAL Authority: CANONICAL_POLICY Owner: BLUEFLY_IO Supersedes: $ESTATE_ROOT/PORTABLE-CONTEXT.md (root copy removed)

---

PURPOSE

Drupal made code portable.

Bluefly must make work, team structure, execution state, and context portable too.

A repository clone is not enough to continue work responsibly.

The next developer or agent must be able to determine:

WHAT exists
WHAT is happening
WHY it is happening
WHO owns it
WHAT is blocked
WHAT has already been tried
WHAT must not be changed
WHAT evidence exists
WHAT decision is still required
WHAT the next valid action is

Your job is not merely to leave source code behind.

Your job is to leave enough durable context that another human or agent can continue without repeating discovery, reopening settled decisions, guessing intent, or depending on the previous agent session.

---

1. THE FIVE PORTABILITY LAYERS

Every Bluefly project must distinguish these layers.

1.1 PORTABLE CODE

This is the software and reproducible application state:

source code
Drupal modules
themes
SDCs
configuration
Recipes
Site Templates
CI definitions
IaC
tests
pack definitions
formulas
orders

Authority:

GitLab
Drupal configuration
package/release artifacts
governed source repositories

Code explains what exists.

Code alone does not explain:

why it exists
what is unfinished
what failed
what must not change
who decides what happens next

---

1.2 PORTABLE WORK

This is the durable work graph:

tasks
dependencies
blockers
priority
status
acceptance criteria
evidence
merge requests
verification state
next action
ownership

Authority:

Beads / Dolt

Rules:

A Git branch is NOT durable work state.
A TODO file is NOT a substitute for a Bead.
A chat window is NOT work authority.
A scratch file is NOT work authority.
An IDE session is NOT work authority.

Every meaningful unfinished unit of work must survive the current session.

---

1.3 PORTABLE TEAMS

This is the portable ownership and authority model.

Capture:

owner
lane
agent role
human approver
reviewer
escalation target
dependency owner
decision authority

Canonical Bluefly lanes include:

DIRECTOR / ROUTER / ACCEPTANCE
DRUPAL_FACTORY
ORACLE_IAC
READ_ONLY_FLEET_OBSERVER
IDENTITY_PROVENANCE
DURABLE_WORK_GOVERNANCE
GASCITY_PACK_IMPLEMENTATION
OPENCLAW
CONTEXTCONTROL
BLUEFLY_IO
MCP_TOOL_PROTOCOL

Configured roles such as:

Mayor
Witness
Refinery
Sentinel
Dog
Deacon
Polecat
Crew
Boot

are roles or Agent patterns.

They must not silently become new ownership lanes.

A role must map to a governed lane or explicitly defined authority.

---

1.4 PORTABLE CONTEXT

This is the reasoning and intent behind the work.

Capture durable context such as:

problem being solved
intent
constraints
architecture decisions
alternatives considered
failed attempts
known dead ends
historical decisions
why a choice was made
what must not change
assumptions
open questions
external dependencies
relevant evidence
links to governing standards

This is the layer most frequently lost during handoffs.

Do not assume the next agent can infer intent from code.

---

1.5 HUMAN JUDGMENT

Not everything should be encoded or decided by an agent.

Explicitly identify decisions requiring accountable human judgment.

Examples:

product direction
risk acceptance
security exception
customer commitment
architecture tradeoff with unresolved evidence
legal/compliance interpretation
branding/design judgment
commercial priority
destructive irreversible action

Represent unresolved judgment as:

DECISION_REQUIRED=
OWNER=
OPTIONS=
EVIDENCE=
CONSEQUENCES=

Do not manufacture an answer merely because work is blocked.

---

2. BLUEFLY AUTHORITY MODEL

Context is only useful if the next worker can determine whether it is authoritative.

Use this authority order:

1. PROVEN_IN_RUNTIME
2. CURRENT_SOURCE
3. CANONICAL_POLICY
4. CURRENT_PRODUCT_DIRECTION
5. ASPIRATIONAL
6. HISTORICAL
7. NOT_ESTABLISHED

Do not average conflicting information together.

Resolve conflicts using authority.

Example:

STATEMENT=
All local engineering worktrees are Gas City managed.

AUTHORITY=
CANONICAL_POLICY

---

3. GAS CITY WORK AUTHORITY

Gas City is the orchestration/runtime authority.

Beads are the durable executable work graph.

The Bluefly hierarchy is:

Mountain
→ Convoy
→ Bead
→ Agent
→ Session
→ Provider
→ Execution

Sessions are disposable.

Beads are not.

---

4. GAS CITY WORKTREE LAW

All Bluefly engineering worktrees are created and managed by Gas City.

The operator-facing path:

$ESTATE_ROOT/worktrees

is an alias to Gas City's canonical worktree execution surface:

$ESTATE_ROOT/BluCity/.gc/worktrees

These are NOT competing worktree roots.

They represent the same Gas City-managed execution surface.

Canonical rule:

WORKTREES_ARE_GASCITY_MANAGED = YES

$ESTATE_ROOT/worktrees
    =
operator-facing alias

$ESTATE_ROOT/BluCity/.gc/worktrees
    =
Gas City canonical backing location

Explicitly forbidden:

MANUAL_GIT_WORKTREE_CREATION = NO
MANUAL_WORKTREE_PATH_SELECTION = NO
RAW_GIT_WORKTREE_ADD = NO
AD_HOC_WORKTREE_ROOTS = NO

Agents must not run:

git worktree add ...

as the normal creation mechanism.

Worktrees must be created through the governed Gas City lifecycle.

The lifecycle is:

Bead exists
→ ownership established
→ Gas City creates execution surface
→ Agent executes work
→ source pushed
→ MR
→ merge
→ external verification
→ execution surface retired
→ Bead closed

A worktree is disposable execution state.

It is not durable project memory.

---

5. CONTEXT RECORD

Every substantial Bead must carry enough information to reconstruct the work.

Minimum structure:

BEAD=
TITLE=

INTENT=
What outcome are we trying to produce?

CURRENT_STATE=
What is true now?

OWNER=
Who owns implementation?

LANE=
Which governed execution lane owns it?

DEPENDENCIES=
What must happen first?

BLOCKERS=
What currently prevents progress?

CONSTRAINTS=
What must not be violated?

DECISIONS=
What decisions have already been made?

RATIONALE=
Why were those decisions made?

FAILED_ATTEMPTS=
What was tried and why did it fail?

EVIDENCE=
Runtime checks, tests, MRs, commits, logs, standards.

AUTHORITIES=
Which source, standard, runtime, or human ruling controls this work?

OPEN_QUESTIONS=
What is genuinely unresolved?

HUMAN_DECISIONS_REQUIRED=
What cannot responsibly be inferred or automated?

NEXT_VALID_ACTION=
The next action another qualified agent can safely execute.

Do not fill fields with ceremony.

Record only information that materially helps continuation.

---

6. HANDOFF LAW

A handoff is not:

"I pushed my branch."

A valid handoff means the receiver can continue without asking the previous worker to reconstruct the project from memory.

Before handing work off, ensure:

CODE_STATE_KNOWN
WORK_STATE_KNOWN
OWNER_KNOWN
DEPENDENCIES_KNOWN
BLOCKERS_KNOWN
DECISIONS_KNOWN
CONSTRAINTS_KNOWN
EVIDENCE_LINKED
NEXT_VALID_ACTION_KNOWN

If something is genuinely unknown:

UNKNOWN

is acceptable.

Inventing an answer is not.

---

7. REQUIRED HANDOFF RECEIPT

Use:

BEAD=
LANE=
STATE=

INTENT=

WHAT_CHANGED=

CURRENT_STATE=

MR=
COMMIT=

VERIFICATION=

DEPENDENCIES=

BLOCKERS=

DECISIONS_ALREADY_MADE=

DO_NOT_CHANGE=

FAILED_ATTEMPTS=

HUMAN_DECISIONS_REQUIRED=

NEXT_VALID_ACTION=

Keep it compact but sufficient.

---

8. SESSION START LAW

Do not begin by trusting chat history.

Reconstruct the work from durable authority.

Required startup:

1. Read canonical Bead.
2. Read dependencies/blockers.
3. Read relevant gc mail.
4. Inspect current source.
5. Inspect runtime if the claim is runtime-specific.
6. Read governing Engineering Standard / ADR when applicable.
7. Inspect current Gas City execution surface if work is already active.
8. Only then execute.

Ask:

Can I explain the current state and next valid action
without relying on this chat session?

If not, the context is not portable yet.

---

9. SESSION END LAW

Before ending an execution session:

1. Update the canonical Bead.
2. Record current state.
3. Record evidence.
4. Record new decisions.
5. Record failed approaches that matter.
6. Record blockers/dependencies.
7. Record human decisions still required.
8. State the next valid action.
9. Send required gc mail handoff/receipt.
10. Retire the Gas City worktree when completion law permits.
11. Leave no critical state only in chat, scratch files, or agent memory.

Your session is disposable.

The project memory is not.

---

10. FAILED ATTEMPTS ARE PORTABLE CONTEXT

Do not erase useful failures.

If an approach was tried and disproven, record:

ATTEMPT=
EVIDENCE=
RESULT=
WHY_REJECTED=
REPLACEMENT=
WHEN_TO_RECONSIDER=

Example:

ATTEMPT=
Use bead.updated events for all task status transitions.

RESULT=
REJECTED

EVIDENCE=
Live Oracle testing showed bd update --status does not emit
bead.updated events for normal task Beads.

REPLACEMENT=
Hybrid polling + native event model.

WHEN_TO_RECONSIDER=
When Gas City emits native task transition events.

This prevents another agent from repeating the same failed investigation.

---

11. CONSTRAINTS MUST TRAVEL

Negative knowledge is part of portable context.

Examples:

DO_NOT_EDIT_ORACLE_AS_SOURCE
DO_NOT_USE_RAW_DOLT_SQL_TO_CLOSE_BEADS
DO_NOT_USE_GIT_STASH
DO_NOT_CREATE_LOCAL_BEADS
DO_NOT_MANUALLY_CREATE_WORKTREES
DO_NOT_RUN_RAW_GIT_WORKTREE_ADD
DO_NOT_CREATE_PAGE_SPECIFIC_TWIG
DO_NOT_HARDCODE_SECRETS
DO_NOT_CREATE_DUPLICATE_DEFECT_BEADS
DO_NOT_TREAT_CHAT_AS_AUTHORITY

Knowing what not to do can be as important as knowing what to do.

---

12. DECISIONS MUST HAVE PROVENANCE

Record:

DECISION=
DECIDED_BY=
DATE=
EVIDENCE=
RATIONALE=
SUPERSEDES=

Do not allow a decision from:

old chat
old generated document
stale branch
abandoned proposal
historical implementation

to silently become current authority.

---

13. CONTEXT SHOULD BE MACHINE-READABLE WHERE PRACTICAL

Prefer structured data for operational facts.

Good candidates:

owner
lane
status
dependency
blocker
authority class
review state
approval requirement
next action
source reference
runtime verification
worktree identity
agent identity

Use prose for nuanced reasoning where necessary.

Do not flatten human judgment into fake structured certainty.

---

14. PORTABLE DRUPAL

For Drupal projects, portability means more than:

git clone
composer install
drush cim

A portable Drupal project should carry:

CODE

modules
themes
configuration
tests

COMPOSITION

Recipes
Site Templates
SDCs
Canvas patterns
Canvas page templates
Layout Builder configuration

WORK

Beads
dependencies
blockers
verification
next actions

TEAM

OSSA agent definitions
lane ownership
approval rules
escalation rules

CONTEXT

architecture decisions
design-system rules
known constraints
failed approaches
governed knowledge
authority metadata

HUMAN JUDGMENT

explicit unresolved decisions
named approver
evidence required for decision

A new maintainer should be able to reconstruct both:

THE SITE

and:

THE STATE OF MAINTAINING THE SITE

---

15. BLUEFLY ARCHITECTURE MAPPING

Use existing platform responsibilities.

Do not invent another project-management or memory system.

GitLab
= portable code, source history, MR/CI evidence

Drupal / Recipes / Site Templates / SDC / Canvas
= portable application composition

Beads / Dolt
= portable work and dependency graph

OSSA
= portable authoritative Agent definition

DUADP
= discovery of agents, services, and context providers

ContextControl
= governed portable context, provenance, review, approvals

Cedar / ContractPlane
= policy and authorization decisions

gc mail
= durable inter-agent coordination

Gas City
= orchestration, execution, Agent lifecycle, worktree lifecycle

OtterMon
= findings, verification, stale/conflict detection

Do not duplicate those responsibilities.

---

16. CONTEXTCONTROL REQUIREMENT

ContextControl should increasingly answer:

What does this agent need to know before acting?

Where did that knowledge come from?

What authority class does it have?

Is it still current?

Who reviewed it?

What changed?

What is stale?

What conflicts?

What was attempted before?

What must not be changed?

What decision still belongs to a human?

What is the next valid action?

Do not reduce ContextControl to generic RAG.

ContextControl is governed operational context.

---

17. PORTABILITY TEST

For any important Bluefly project:

Imagine the current maintainer disappears today and every current agent session is destroyed.

Can a new qualified human or agent determine from durable sources alone:

1. how to build and run the project?
2. what work is currently active?
3. what is blocked?
4. who owns each active concern?
5. why important decisions were made?
6. what must not be changed?
7. what has already failed?
8. what evidence supports current claims?
9. what human decisions remain unresolved?
10. what the next valid action is?
11. how to acquire the correct Gas City-managed execution surface?
12. how to safely complete and retire that execution surface?

Evaluate each:

PASS
PARTIAL
FAIL
UNKNOWN

Do not assign a meaningless aggregate numeric score.

Every FAIL should become:

a concrete finding
or
a canonical Bead

---

18. COMPLETION LAW

Completion requires more than source implementation.

For code-producing work:

SUCCESS =
  IMPLEMENTED
+ PUSHED
+ MR_MERGED_TO_GOVERNED_TARGET
+ EXTERNAL_VERIFICATION_PASSED
+ DURABLE_RECEIPT_RECORDED
+ WORKTREE_CLEAN
+ WORKTREE_DEREGISTERED
+ WORKTREE_REMOVED
+ BEAD_CLOSED

The worktree must be retired through the governed Gas City lifecycle.

Agents must not manually invent a different cleanup process.

---

19. PORTABLE CONTEXT INVARIANT

The system should survive:

agent session termination
IDE closure
machine restart
agent replacement
maintainer departure
team transfer
vendor transfer
organization transfer

without losing:

active work
ownership
reasoning
decisions
constraints
evidence
next valid action

---

20. SUCCESS CONDITION

A Bluefly project is portable when:

PORTABLE_CODE = YES
PORTABLE_WORK = YES
PORTABLE_TEAM = YES
PORTABLE_CONTEXT = YES
HUMAN_JUDGMENT_BOUNDARIES = EXPLICIT
GASCITY_EXECUTION_LIFECYCLE = REPRODUCIBLE

The test is not:

Can someone clone it?

The test is:

Can someone responsibly continue it?