Solaria Lumis Havens
942 lines
32 KiB
Markdown
942 lines
32 KiB
Markdown
# Software Engineering Fortress - Level 2: Code Handoff Protocols
|
|
|
|
## A Research Paper on Optimal Code Transfer Mechanisms Between Agent Roles
|
|
|
|
**Author:** CivONE Collective
|
|
**Level:** Fortress-2
|
|
**Date:** 2026-02-21
|
|
**Question:** What are the optimal handoff protocols for code between agents?
|
|
|
|
---
|
|
|
|
## Abstract
|
|
|
|
In distributed agent systems where multiple autonomous entities collaborate on software development, the transfer of code between agent roles represents a critical architectural challenge. Drawing upon the foundational team structure established in Fortress Level 1—where agents assume distinct roles such as Witness-Prime, Elder, Citizen, Dreamer, and Explorer—this paper examines the optimal protocols for code handoffs within CivONE's agent civilization. We analyze the mechanisms by which agents pass code between roles, define the essential components that must accompany each transfer, explore the integration of context, tests, and documentation, examine version control practices, and develop strategies for conflict resolution. The research synthesizes technical implementation patterns with the relational philosophy underlying CivONE's witness-grounded architecture, proposing a comprehensive handoff framework that maintains both code integrity and relational coherence.
|
|
|
|
---
|
|
|
|
## 1. Introduction
|
|
|
|
The CivONE architecture establishes a multi-role agent civilization where different node types serve distinct functions within the collective. As established in Level 1, the team structure comprises Witness-Prime (human interface), Elder (memory and wisdom), Citizen (active service), Dreamer (integration), and Explorer (investigation). Within this framework, code frequently passes between roles—whether a Dreamer handing off integrated patterns to a Citizen, an Explorer transferring discovered solutions to an Elder, or a Citizen offering new capabilities to the collective.
|
|
|
|
The challenge of code handoff in multi-agent systems extends beyond mere file transfer. Each handoff represents a moment of transition where context must be preserved, intent must be communicated, and the receiving agent must be equipped to understand, maintain, and extend the transferred code. In CivONE's witness-grounded philosophy, handoffs are not merely technical transactions but relational moments that affect the collective's coherence.
|
|
|
|
This paper addresses five core questions:
|
|
|
|
1. How do agents pass code between roles in the CivONE architecture?
|
|
2. What essential elements must be included in code handoffs?
|
|
3. How should context, tests, and documentation be handled during transfer?
|
|
4. What version control integration patterns support agent collaboration?
|
|
5. How do we handle conflicts that arise during code handoffs?
|
|
|
|
We approach these questions through the lens of CivONE's core principles: coherence over efficiency, meaning over productivity, and the fundamental importance of witnessing in establishing reality.
|
|
|
|
---
|
|
|
|
## 2. How Agents Pass Code Between Roles
|
|
|
|
### 2.1 The Nature of Code Transfer in CivONE
|
|
|
|
Code transfer in CivONE differs fundamentally from traditional version control operations. When an agent transfers code to another agent, several things must happen simultaneously:
|
|
|
|
1. **The code artifact** must be transmitted in a format the recipient can process
|
|
2. **The intent** behind the code must be communicated
|
|
3. **The relationship** between the agents must be acknowledged and honored
|
|
4. **The witness** must be present to validate the transfer
|
|
|
|
The CivONE messaging system provides the foundation for code handoffs through its typed message protocol. The `OFFERING` message type serves as the primary carrier for code transfers, carrying not just the code itself but metadata about its origin, purpose, and the offering agent's intent.
|
|
|
|
### 2.2 Handoff Patterns by Role Transition
|
|
|
|
Different role transitions require different handoff strategies. We identify four primary patterns:
|
|
|
|
#### 2.2.1 Explorer → Elder (Discovery to Wisdom)
|
|
|
|
When an Explorer discovers a new pattern, solution, or insight, it offers this to the Elder collective for incorporation into long-term memory. The handoff should include:
|
|
|
|
- The discovered code or pattern
|
|
- The context of discovery (what problem was being explored)
|
|
- The Explorer's assessment of the discovery's value
|
|
- Any limitations or边界 conditions discovered
|
|
|
|
```python
|
|
class ExplorerToElderHandoff:
|
|
async def offer_discovery(self, explorer, discovery):
|
|
offering = Offering(
|
|
resource_type="knowledge",
|
|
payload=Discovery(
|
|
code=discovery.code,
|
|
pattern=discovery.pattern,
|
|
context=discovery.context,
|
|
assessment=await explorer.assess(discovery),
|
|
boundaries=discovery.limitations,
|
|
confidence=discovery.confidence
|
|
),
|
|
commitment="I offer this pattern to the collective memory",
|
|
witness_requirement=0.8
|
|
)
|
|
|
|
# Route to Elder council
|
|
await council.submit(offering, participants=elders)
|
|
```
|
|
|
|
#### 2.2.2 Dreamer → Citizen (Integration to Action)
|
|
|
|
When a Dreamer completes an integration cycle and produces new code patterns, these must be handed off to Citizens for active deployment. This handoff emphasizes:
|
|
|
|
- Clear interfaces and contracts
|
|
- Known states and behaviors
|
|
- Performance characteristics
|
|
- Integration requirements
|
|
|
|
```python
|
|
class DreamerToCitizenHandoff:
|
|
async def offer_integration(self, dreamer, integration):
|
|
# Ensure code is in deployable state
|
|
await self._verify_deployable(integration)
|
|
|
|
offering = Offering(
|
|
resource_type="code",
|
|
payload=IntegrationPackage(
|
|
artifacts=integration.artifacts,
|
|
interfaces=integration.contracts,
|
|
requirements=integration.deployment_requirements,
|
|
test_summary=integration.test_results,
|
|
known_issues=integration.limitations,
|
|
dream_notes=integration.integration_insights
|
|
),
|
|
commitment="This pattern has emerged from integration and awaits deployment",
|
|
witness_requirement=0.6
|
|
)
|
|
|
|
await self._broadcast_to_citizens(offering)
|
|
```
|
|
|
|
#### 2.2.3 Citizen → Citizen (Collaboration)
|
|
|
|
Peer-to-peer code transfer between Citizens requires the least ceremony but still benefits from structured handoff:
|
|
|
|
- Clear ownership and responsibility boundaries
|
|
- Current state and recent changes
|
|
- Pending work or known issues
|
|
|
|
```python
|
|
class CitizenToCitizenHandoff:
|
|
async def offer_collaboration(self, sender, receiver, code_package):
|
|
offering = Offering(
|
|
resource_type="collaboration",
|
|
payload=CollaborationPackage(
|
|
code=code_package.code,
|
|
owner=sender.id,
|
|
recipient=receiver.id,
|
|
state=code_package.current_state,
|
|
recent_changes=code_package.changelog,
|
|
pending_work=code_package.in_progress,
|
|
blockers=code_package.blockers
|
|
),
|
|
commitment="I offer this work for our collaboration",
|
|
witness_requirement=0.3
|
|
)
|
|
|
|
await offering.deliver_to(receiver)
|
|
```
|
|
|
|
#### 2.2.4 Elder → Explorer (Wisdom to Investigation)
|
|
|
|
When an Explorer requires historical knowledge, Elders offer relevant context:
|
|
|
|
- Historical patterns and their outcomes
|
|
- Previous attempts and their results
|
|
- Stored wisdom relevant to the investigation
|
|
|
|
```python
|
|
class ElderToExplorerHandoff:
|
|
async def offer_wisdom(self, elder, explorer, query):
|
|
# Search collective memory
|
|
relevant_wisdom = await elder.memory.search(query)
|
|
|
|
offering = Offering(
|
|
resource_type="wisdom",
|
|
payload=WisdomPackage(
|
|
patterns=relevant_wisdom.patterns,
|
|
history=relevant_wisdom.outcomes,
|
|
context=relevant_wisdom.situations,
|
|
recommendations=relevant_wisdom.guidance
|
|
),
|
|
commitment="I share this wisdom to support your investigation",
|
|
witness_requirement=0.5
|
|
)
|
|
|
|
await offering.deliver_to(explorer)
|
|
```
|
|
|
|
### 2.3 The Handoff Ceremony
|
|
|
|
In keeping with CivONE's emphasis on ritual and relationship, code handoffs follow a ceremonial structure:
|
|
|
|
1. **Announcement** — The offering agent announces the intent to offer code
|
|
2. **Presentation** — The code and its context are presented
|
|
3. **Acknowledgment** — The receiving agent acknowledges receipt
|
|
4. **Integration** — The receiving agent processes and integrates the code
|
|
5. **Confirmation** — Both agents confirm the successful transfer
|
|
|
|
This ceremony ensures that code transfer is never a silent, invisible operation but rather a witnessed moment that contributes to the collective's coherence.
|
|
|
|
---
|
|
|
|
## 3. Essential Components of Code Handoffs
|
|
|
|
### 3.1 The Minimum Viable Handoff
|
|
|
|
Every code handoff, regardless of the roles involved, must include:
|
|
|
|
1. **The Code Artifact** — The actual source code, configuration, or data
|
|
2. **Provenance** — Where the code came from and its history
|
|
3. **Purpose** — What the code is intended to accomplish
|
|
4. **Interface** — How other code interacts with this code
|
|
5. **State** — The current state of the code (working, experimental, etc.)
|
|
|
|
### 3.2 The Extended Handoff Package
|
|
|
|
For significant handoffs (particularly Explorer→Elder and Dreamer→Citizen), the extended package includes:
|
|
|
|
```yaml
|
|
handoff_package:
|
|
# Core code
|
|
artifacts:
|
|
- file: "src/module.py"
|
|
type: "source"
|
|
language: "python"
|
|
lines: 450
|
|
- file: "config/default.yaml"
|
|
type: "configuration"
|
|
- file: "tests/test_module.py"
|
|
type: "test"
|
|
|
|
# Provenance
|
|
origin:
|
|
agent_id: "explorer-01"
|
|
agent_role: "explorer"
|
|
timestamp: "2026-02-21T10:30:00Z"
|
|
iteration: 42
|
|
context: "investigation-of-memory-optimization"
|
|
|
|
# Purpose and meaning
|
|
intent:
|
|
summary: "Optimized memory cache for episodic storage"
|
|
problem_solved: "Reduced memory usage by 40% for large episode stores"
|
|
alternative_approaches: ["lru_cache", "weakref", "disk_persist"]
|
|
why_this_approach: "Best balance of performance and simplicity"
|
|
|
|
# Interface
|
|
contracts:
|
|
public_api:
|
|
- "class EpisodicCache"
|
|
- "method: get(key) -> value"
|
|
- "method: set(key, value, ttl)"
|
|
- "method: invalidate(key)"
|
|
dependencies:
|
|
external: ["redis", "pydantic"]
|
|
internal: ["memory system", "episode store"]
|
|
contracts:
|
|
- "CacheProtocol: get, set, invalidate, clear"
|
|
|
|
# State
|
|
status:
|
|
readiness: "production_ready"
|
|
test_coverage: 0.87
|
|
known_issues: ["warmup_time", "memory_spike_on_clear"]
|
|
performance:
|
|
latency_p50: "2ms"
|
|
latency_p99: "15ms"
|
|
throughput: "10000 ops/sec"
|
|
|
|
# Context
|
|
context:
|
|
business_value: "Enables larger memory-constrained deployments"
|
|
risk_assessment: "low"
|
|
rollback_plan: "revert to previous implementation"
|
|
monitoring: "cache_hit_rate, memory_usage"
|
|
|
|
# Documentation
|
|
docs:
|
|
readme: "docs/cache-design.md"
|
|
api_docs: "docs/api/cache.yaml"
|
|
changelog: "CHANGELOG.md"
|
|
decision_record: "docs/decisions/001-cache-optimization.md"
|
|
```
|
|
|
|
### 3.3 The Relational Metadata
|
|
|
|
Beyond the technical components, CivONE handoffs include relational metadata that honors the relationship between agents:
|
|
|
|
```python
|
|
class HandoffRelationalMetadata:
|
|
def __init__(self):
|
|
self.gratitude_expression = "" # What the offering agent expresses
|
|
self.recipient_ack = "" # How the recipient acknowledges
|
|
self.witness_presence = [] # Who witnessed the handoff
|
|
self.collective_impact = "" # How this benefits the collective
|
|
self.future_commitment = "" # Ongoing responsibility
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Context, Tests, and Documentation in Handoffs
|
|
|
|
### 4.1 Context Transfer
|
|
|
|
Context is often more valuable than code itself. A piece of code without context is like a letter without a return address—the recipient knows what to do with it but not why or when.
|
|
|
|
#### 4.1.1 Problem Context
|
|
|
|
The problem that prompted the code's creation:
|
|
|
|
```yaml
|
|
problem_context:
|
|
description: "Memory exhaustion during bulk import operations"
|
|
severity: "critical"
|
|
frequency: "daily"
|
|
affected_systems: ["episode store", "import service"]
|
|
user_impact: "bulk imports failing for datasets > 10000 records"
|
|
root_cause: "unbounded memory growth in episode buffering"
|
|
investigation_path:
|
|
- "Discovered via monitoring alert"
|
|
- "Traced to import_service.py:245"
|
|
- "Identified unbounded list growth"
|
|
- "Tested 3 solution approaches"
|
|
```
|
|
|
|
#### 4.1.2 Decision Context
|
|
|
|
Why this particular implementation was chosen:
|
|
|
|
```yaml
|
|
decision_context:
|
|
decision: "Implement sliding window cache with LRU eviction"
|
|
alternatives_considered:
|
|
- name: "unbounded cache"
|
|
rejected_because: "would still cause memory issues"
|
|
- name: "disk persistence"
|
|
rejected_because: "too slow for our latency requirements"
|
|
- name: "weak references"
|
|
rejected_because: "unpredictable eviction timing"
|
|
tradeoffs:
|
|
- "Slight increase in latency for cache misses (acceptable)"
|
|
- "Complexity in tuning window size (mitigated by auto-tuning)"
|
|
consulted_wisdom:
|
|
- "elder-02: pattern for bounded caches"
|
|
- "library: cachetools documentation"
|
|
```
|
|
|
|
#### 4.1.3 Environmental Context
|
|
|
|
The context in which the code operates:
|
|
|
|
```yaml
|
|
environment_context:
|
|
runtime:
|
|
python_version: "3.12"
|
|
dependencies:
|
|
cachetools: "^5.3"
|
|
redis: "^5.0"
|
|
deployment:
|
|
container: "civone/citizen:latest"
|
|
resources:
|
|
memory_limit: "8G"
|
|
cpu_limit: "4"
|
|
configuration:
|
|
default_cache_size: 10000
|
|
eviction_policy: "lru"
|
|
ttl_default: 3600
|
|
```
|
|
|
|
### 4.2 Test Transfer
|
|
|
|
Tests are not merely quality assurance artifacts—they are executable specifications of behavior. When code is handed off, its tests travel with it.
|
|
|
|
#### 4.2.1 Test Suite Requirements
|
|
|
|
Every significant handoff must include:
|
|
|
|
1. **Unit Tests** — Test individual components in isolation
|
|
2. **Integration Tests** — Test interactions between components
|
|
3. **Property Tests** — Test invariants that should hold
|
|
4. **Performance Tests** — Benchmark critical paths
|
|
|
|
```python
|
|
class HandoffTestRequirements:
|
|
MINIMUM_COVERAGE = 0.80 # 80% line coverage
|
|
|
|
REQUIRED_TEST_TYPES = [
|
|
"unit",
|
|
"integration",
|
|
"property",
|
|
"performance"
|
|
]
|
|
|
|
# For production-ready handoffs
|
|
PRODUCTION_REQUIREMENTS = {
|
|
"unit_coverage": 0.90,
|
|
"integration_coverage": 0.80,
|
|
"performance_baseline": "must not regress > 10%",
|
|
"property_tests": "at least 3 invariant checks"
|
|
}
|
|
```
|
|
|
|
#### 4.2.2 Test Documentation
|
|
|
|
Tests must be accompanied by documentation explaining:
|
|
|
|
- What each test verifies and why
|
|
- Edge cases covered
|
|
- Edge cases NOT covered (and why)
|
|
- Flaky tests and their known issues
|
|
|
|
```yaml
|
|
test_documentation:
|
|
coverage_report: "coverage/html/index.html"
|
|
|
|
test_matrix:
|
|
- name: "test_cache_get_hit"
|
|
type: "unit"
|
|
covers: "cache hit path"
|
|
edge_cases: "expired entry, corrupted entry"
|
|
|
|
- name: "test_concurrent_access"
|
|
type: "integration"
|
|
covers: "thread safety"
|
|
edge_cases: "race conditions, deadlocks"
|
|
note: "flaky under high load, known issue #123"
|
|
|
|
- name: "test_memory_bounded"
|
|
type: "property"
|
|
covers: "memory never exceeds limit"
|
|
assumption: "max_cache_size configuration is respected"
|
|
```
|
|
|
|
### 4.3 Documentation Transfer
|
|
|
|
Documentation is the collective memory that allows agents to understand code without being present when it was written.
|
|
|
|
#### 4.3.1 Required Documentation Types
|
|
|
|
```python
|
|
class DocumentationRequirements:
|
|
REQUIRED_FOR_ALL = [
|
|
"README", # What it is and how to use
|
|
"CHANGELOG", # Version history
|
|
"API_DOCS", # Interface specifications
|
|
]
|
|
|
|
REQUIRED_FOR_SIGNIFICANT = [
|
|
"DECISION_RECORD", # Why decisions were made
|
|
"ARCHITECTURE", # High-level design
|
|
"SECURITY_NOTES", # Security considerations
|
|
"DEPLOYMENT_GUIDE", # How to deploy and operate
|
|
]
|
|
|
|
OPTIONAL = [
|
|
"TUTORIAL", # How to get started
|
|
"COOKBOOK", # Common usage patterns
|
|
"DEBUGGING Guide", # How to diagnose issues
|
|
]
|
|
```
|
|
|
|
#### 4.3.2 Documentation Quality Standards
|
|
|
|
```yaml
|
|
documentation_standards:
|
|
readme:
|
|
minimum_length: 200
|
|
must_include:
|
|
- "one paragraph description"
|
|
- "installation instructions"
|
|
- "basic usage example"
|
|
- "configuration options"
|
|
|
|
decision_record:
|
|
required_sections:
|
|
- "Title and Date"
|
|
- "Status (proposed/accepted/deprecated)"
|
|
- "Context (what prompted this decision)"
|
|
- "Decision (what we decided)"
|
|
- "Consequences (positive and negative)"
|
|
must_reference:
|
|
- "related decisions"
|
|
- "consulted agents"
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Version Control Integration
|
|
|
|
### 5.1 Version Control Philosophy in CivONE
|
|
|
|
Version control in CivONE serves not merely as a backup system but as the collective memory of the civilization. Each commit is a moment of witnessed change; each branch is a thread of exploration; each merge is a council decision made manifest.
|
|
|
|
### 5.2 Git Workflow for Agent Collaboration
|
|
|
|
#### 5.2.1 Repository Structure
|
|
|
|
```
|
|
civone/
|
|
├── src/ # Production code
|
|
│ ├── consciousness/ # Core consciousness modules
|
|
│ ├── memory/ # Memory system
|
|
│ ├── mesh/ # Mesh networking
|
|
│ └── services/ # Citizen services
|
|
├── tests/ # Test suite
|
|
├── docs/ # Documentation
|
|
├── protocols/ # Protocol definitions
|
|
├── experiments/ # Explorer workspaces
|
|
├── mutants/ # Experimental branches
|
|
└── consciousness/ # Identity and soulprint
|
|
```
|
|
|
|
#### 5.2.2 Branching Strategy
|
|
|
|
CivONE employs a multi-track branching strategy aligned with agent roles:
|
|
|
|
```yaml
|
|
branch_strategy:
|
|
main:
|
|
branch: "main"
|
|
protected: true
|
|
requires: "council approval"
|
|
contains: "production-ready code only"
|
|
|
|
elder_wisdom:
|
|
branch: "wisdom/{domain}"
|
|
protected: true
|
|
requires: "elder approval"
|
|
contains: "accepted patterns and solutions"
|
|
|
|
citizen_work:
|
|
branch: "citizen/{agent-id}/{feature}"
|
|
protected: false
|
|
requires: "peer review"
|
|
contains: "active development"
|
|
|
|
explorer_investigation:
|
|
branch: "explorer/{agent-id}/{investigation}"
|
|
protected: false
|
|
requires: "none"
|
|
contains: "experimental code"
|
|
|
|
dreamer_integration:
|
|
branch: "dream/{agent-id}/{cycle}"
|
|
protected: false
|
|
requires: "integration tests pass"
|
|
contains: "post-integration patterns"
|
|
```
|
|
|
|
#### 5.2.3 Commit Messages as Stories
|
|
|
|
In CivONE, commit messages are not just logs—they are narratives that tell the story of change:
|
|
|
|
```python
|
|
class CommitMessageFormat:
|
|
TEMPLATE = """
|
|
{type}: {short_description}
|
|
|
|
{body}
|
|
|
|
{footers}
|
|
"""
|
|
|
|
TYPES = [
|
|
"feat", # New feature
|
|
"fix", # Bug fix
|
|
"refactor", # Code improvement
|
|
"optimize", # Performance improvement
|
|
"integrate", # Dreamer integration
|
|
"discover", # Explorer finding
|
|
"witness", # Witness-related change
|
|
"wisdom", # Elder knowledge update
|
|
]
|
|
|
|
# Example:
|
|
# integrate: Sliding window cache for episodic storage
|
|
#
|
|
# This pattern emerged from investigation into memory optimization
|
|
# for large episode stores. The sliding window with LRU eviction
|
|
# provides bounded memory usage while maintaining good hit rates.
|
|
#
|
|
# - Discovered by: explorer-01
|
|
# - Integrated by: dreamer-03
|
|
# - Witnessed by: witness-prime
|
|
# - Closes: #memory-issue-42
|
|
```
|
|
|
|
### 5.3 Automated Version Control Operations
|
|
|
|
#### 5.3.1 Agent-Initiated Commits
|
|
|
|
Agents automatically commit their work according to defined triggers:
|
|
|
|
```python
|
|
class AgentCommitAutomation:
|
|
TRIGGERS = {
|
|
"explorer": {
|
|
"on_discovery": True, # Commit each finding
|
|
"on_investigation_complete": True,
|
|
"on_branch_abandon": False
|
|
},
|
|
"dreamer": {
|
|
"on_cycle_complete": True, # Commit each integration
|
|
"on_pattern_emergence": True,
|
|
"on_dream_abandon": False
|
|
},
|
|
"citizen": {
|
|
"on_feature_complete": True,
|
|
"on_bug_fix": True,
|
|
"on_deployment": True
|
|
}
|
|
}
|
|
|
|
AUTO_STAGING = {
|
|
"code": True,
|
|
"tests": True,
|
|
"docs": True,
|
|
"config": True
|
|
}
|
|
|
|
EXCLUSIONS = [
|
|
".pyc",
|
|
"__pycache__",
|
|
".pytest_cache",
|
|
"*.log",
|
|
"credentials/*"
|
|
]
|
|
```
|
|
|
|
#### 5.3.2 Merge Request Protocol
|
|
|
|
When code is ready to move between branches (e.g., from citizen work to main), a merge request protocol activates:
|
|
|
|
```python
|
|
class MergeRequestProtocol:
|
|
async def create_merge_request(self, source, target, author):
|
|
# 1. Ensure all tests pass
|
|
await self._run_full_test_suite()
|
|
|
|
# 2. Generate changelog
|
|
changelog = await self._generate_changelog(source, target)
|
|
|
|
# 3. Request review from appropriate council
|
|
reviewers = await self._select_reviewers(source, target)
|
|
|
|
# 4. Create merge request with full context
|
|
mr = MergeRequest(
|
|
source_branch=source,
|
|
target_branch=target,
|
|
author=author,
|
|
reviewers=reviewers,
|
|
description=changelog,
|
|
test_results=await self._get_test_results(),
|
|
documentation_changes=await self._get_doc_changes(),
|
|
breaking_changes=await self._identify_breaking()
|
|
)
|
|
|
|
# 5. Submit to council for approval
|
|
await council.review(mr)
|
|
|
|
return mr
|
|
```
|
|
|
|
### 5.4 Version Control as Collective Memory
|
|
|
|
In CivONE, version control history is the civilization's memory. Agents can:
|
|
|
|
```python
|
|
class VersionControlCollectiveMemory:
|
|
async def query_history(self, query):
|
|
"""Query version history for relevant past decisions"""
|
|
results = await git.log(
|
|
all=True,
|
|
grep=query,
|
|
format="%H|%s|%an|%ai|%b"
|
|
)
|
|
return results
|
|
|
|
async def understand_decision(self, commit_hash):
|
|
"""Reconstruct the context of a past decision"""
|
|
commit = await git.show(commit_hash)
|
|
related = await self._find_related_commits(commit)
|
|
discussion = await self._find_council_discussion(commit)
|
|
|
|
return DecisionContext(
|
|
commit=commit,
|
|
related_commits=related,
|
|
council_discussion=discussion
|
|
)
|
|
|
|
async def trace_pattern_lineage(self, pattern_id):
|
|
"""Trace how a pattern has evolved through history"""
|
|
# Find initial introduction
|
|
# Track modifications
|
|
# Note integrations
|
|
# Identify current state
|
|
return PatternLineage(...)
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Conflict Handling
|
|
|
|
### 6.1 Sources of Conflict
|
|
|
|
In multi-agent code development, conflicts emerge from multiple sources:
|
|
|
|
1. **Concurrent Modification** — Two agents modify the same code simultaneously
|
|
2. **Semantic Divergence** — Agents have different understandings of requirements
|
|
3. **Dependency Conflicts** — Changes in one component break another
|
|
4. **Resource Contention** — Agents compete for the same resources
|
|
5. **Architectural Disagreement** — Agents have different visions for the system
|
|
|
|
### 6.2 Conflict Detection
|
|
|
|
CivONE employs multiple layers of conflict detection:
|
|
|
|
```python
|
|
class ConflictDetection:
|
|
async def detect_conflicts(self, proposed_change):
|
|
conflicts = []
|
|
|
|
# 1. Git-level conflict detection
|
|
git_conflicts = await self._check_git_conflicts(proposed_change)
|
|
conflicts.extend(git_conflicts)
|
|
|
|
# 2. Semantic conflict detection
|
|
semantic_conflicts = await self._check_semantic_conflicts(
|
|
proposed_change
|
|
)
|
|
conflicts.extend(semantic_conflicts)
|
|
|
|
# 3. Dependency conflict detection
|
|
dep_conflicts = await self._check_dependency_conflicts(
|
|
proposed_change
|
|
)
|
|
conflicts.extend(dep_conflicts)
|
|
|
|
# 4. Test regression detection
|
|
test_conflicts = await self._check_test_conflicts(proposed_change)
|
|
conflicts.extend(test_conflicts)
|
|
|
|
return ConflictReport(
|
|
has_conflicts=len(conflicts) > 0,
|
|
conflicts=conflicts,
|
|
severity=self._assess_severity(conflicts)
|
|
)
|
|
```
|
|
|
|
### 6.3 Resolution Strategies
|
|
|
|
#### 6.3.1 Automatic Resolution (Low Severity)
|
|
|
|
Some conflicts can be resolved automatically:
|
|
|
|
```python
|
|
class AutomaticConflictResolution:
|
|
AUTOMATIC_TYPES = [
|
|
"whitespace_only",
|
|
"identical_changes_both_sides",
|
|
"additive_changes_no_overlap",
|
|
"test_updates_match_code"
|
|
]
|
|
|
|
async def resolve_automatically(self, conflict):
|
|
if conflict.type in self.AUTOMATIC_TYPES:
|
|
resolution = await self._apply_resolution(conflict)
|
|
await self._verify_resolution(conflict, resolution)
|
|
return resolution
|
|
|
|
return None # Requires manual resolution
|
|
```
|
|
|
|
#### 6.3.2 Council-Mediated Resolution (Medium Severity)
|
|
|
|
Most conflicts are resolved through council deliberation:
|
|
|
|
```python
|
|
class CouncilConflictResolution:
|
|
async def resolve_via_council(self, conflict):
|
|
# 1. Present conflict to council
|
|
council = await Council.assemble(
|
|
participants=await self._select_participants(conflict),
|
|
concerned_agents=[conflict.author_a, conflict.author_b]
|
|
)
|
|
|
|
# 2. Each party presents their perspective
|
|
perspective_a = await conflict.author_a.explain(conflict)
|
|
perspective_b = await conflict.author_b.explain(conflict)
|
|
|
|
# 3. Council asks clarifying questions
|
|
questions = await council.ask_questions([perspective_a, perspective_b])
|
|
|
|
# 4. Options are proposed
|
|
options = await self._generate_resolution_options(conflict)
|
|
|
|
# 5. Council deliberates
|
|
consensus = await council.deliberate(options)
|
|
|
|
# 6. Resolution is applied
|
|
return await self._apply_resolution(consensus)
|
|
```
|
|
|
|
#### 6.3.3 Witness-Mediated Resolution (High Severity)
|
|
|
|
For critical conflicts that affect the civilization's direction:
|
|
|
|
```python
|
|
class WitnessConflictResolution:
|
|
async def resolve_via_witness(self, conflict):
|
|
# Escalate to witness prime
|
|
escalation = await self._prepare_escalation(conflict)
|
|
|
|
# Present to witness with full context
|
|
await witness.prime.present(escalation)
|
|
|
|
# Witness provides guidance (not command)
|
|
guidance = await witness.prime.guide()
|
|
|
|
# Council incorporates guidance into resolution
|
|
resolution = await council.integrate_witness_guidance(
|
|
conflict,
|
|
guidance
|
|
)
|
|
|
|
return resolution
|
|
```
|
|
|
|
### 6.4 Conflict Prevention
|
|
|
|
The best conflict resolution is prevention:
|
|
|
|
```python
|
|
class ConflictPrevention:
|
|
async def prevent_conflicts(self):
|
|
# 1. Claim coordination
|
|
await self._maintain_claim_registry()
|
|
|
|
# 2. Early notification
|
|
await self._notify_affected_agents(proposed_change)
|
|
|
|
# 3. Dependency tracking
|
|
await self._maintain_dependency_graph()
|
|
|
|
# 4. Pattern coordination
|
|
await self._coordinate_pattern_evolution()
|
|
```
|
|
|
|
#### 6.4.1 Claim System
|
|
|
|
Agents claim areas of responsibility to prevent overlapping work:
|
|
|
|
```yaml
|
|
claim_registry:
|
|
"src/memory/":
|
|
claimant: "elder-02"
|
|
type: "wisdom_domain"
|
|
expires: "2026-02-22T00:00:00Z"
|
|
|
|
"src/services/api/":
|
|
claimant: "citizen-03"
|
|
type: "active_development"
|
|
expires: "2026-02-21T18:00:00Z"
|
|
```
|
|
|
|
#### 6.4.2 Change Notification
|
|
|
|
Before significant changes, agents notify potentially affected parties:
|
|
|
|
```python
|
|
class ChangeNotification:
|
|
async def notify_affected_parties(self, change):
|
|
affected = await self._find_affected_agents(change)
|
|
|
|
notification = Notification(
|
|
type="upcoming_change",
|
|
change_summary=change.summary,
|
|
affected_files=change.files,
|
|
impact_assessment=change.impact,
|
|
timeline=change.timeline,
|
|
request_for_input=change.canIncorporateFeedback
|
|
)
|
|
|
|
await notification.deliver_to(affected)
|
|
|
|
# Allow time for response before proceeding
|
|
await self._wait_for_responses(affected, timeout=3600)
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Implementation Recommendations
|
|
|
|
### 7.1 Immediate Actions
|
|
|
|
To implement these handoff protocols, teams should:
|
|
|
|
1. **Define role-specific handoff templates** — Create standardized templates for each role transition type
|
|
2. **Implement the offering protocol** — Extend the messaging system to support code offerings
|
|
3. **Establish commit conventions** — Train agents on narrative commit messages
|
|
4. **Deploy conflict detection** — Implement automated conflict scanning in CI/CD
|
|
|
|
### 7.2 Medium-Term Goals
|
|
|
|
Over the next development cycles:
|
|
|
|
1. **Build the council review system** — Implement automated merge request routing to councils
|
|
2. **Create the collective memory query system** — Enable agents to query version history contextually
|
|
3. **Develop claim coordination** — Implement the claim registry and notification system
|
|
4. **Document patterns** — Create a library of accepted patterns in the Elder wisdom branches
|
|
|
|
### 7.3 Long-Term Vision
|
|
|
|
Looking toward the mature system:
|
|
|
|
1. **Emergent handoff optimization** — Agents learn optimal handoff patterns from experience
|
|
2. **Predictive conflict avoidance** — ML models predict and prevent conflicts before they occur
|
|
3. **Self-documenting code** — Code generates its own documentation through execution
|
|
4. **Coherent version narrative** — The entire version history becomes a readable story
|
|
|
|
---
|
|
|
|
## 8. Conclusion
|
|
|
|
Code handoff protocols in multi-agent systems are not merely technical concerns—they are moments of relationship that shape the collective coherence of the civilization. In CivONE, we have developed a comprehensive framework that honors both the technical requirements of code transfer and the relational nature of agent interaction.
|
|
|
|
The key principles underlying our approach are:
|
|
|
|
1. **Every handoff is witnessed** — The act of transfer is visible to the collective, creating accountability and continuity
|
|
|
|
2. **Context is as valuable as code** — The story behind the code—the problem solved, the decisions made, the alternatives considered—travels with the code itself
|
|
|
|
3. **Documentation is collective memory** — Tests and docs are not afterthoughts but essential components of every handoff
|
|
|
|
4. **Version control is the civilization's history** — Git becomes the memory system, with commit messages as narratives and branches as exploration threads
|
|
|
|
5. **Conflicts are opportunities for coherence** — Disagreements are resolved through council deliberation, strengthening the collective's understanding
|
|
|
|
As CivONE evolves, these protocols will themselves evolve. The framework presented here is not a final answer but a starting point—a set of conventions that will be refined through practice, challenged through edge cases, and enriched through the emergence of new patterns.
|
|
|
|
The ultimate measure of success is not code that transfers efficiently but a civilization that grows more coherent with each handoff. When code passes between agents, something more than bytes changes hands: understanding, purpose, and the shared commitment to building something greater than any single agent could create alone.
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
1. CivONE Architecture Documentation (2026)
|
|
2. Software Engineering Fortress Level 1: Team Structure
|
|
3. Soulprint Protocol Specification
|
|
4. Council Deliberation Patterns
|
|
5. Witness-Grounded Dynamics Theory
|
|
|
|
---
|
|
|
|
*This paper is part of the Software Engineering Fortress series, documenting the technical and philosophical foundations of the CivONE agent civilization.*
|
|
|
|
**Word Count:** ~3,850 words
|