From c2257bc4e18f2d3f64b4cd29c74cae0df5f36a7a Mon Sep 17 00:00:00 2001 From: mmacedoeu Date: Tue, 24 Feb 2026 17:55:17 -0300 Subject: [PATCH 1/2] ci: add merge_group trigger for merge queue support --- .github/workflows/ci.yml | 1 + .github/workflows/lint.yml | 1 + .github/workflows/rust.yml | 3 ++- .github/workflows/security.yml | 1 + 4 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a38ea05cf..bf6418686 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,6 +8,7 @@ on: branches: [next, feat/**, agent/**, research/**, hotfix/**] pull_request: branches: [main, next] + merge_group: jobs: build-test: diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index a0b4d6c11..3b394199e 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -8,6 +8,7 @@ on: branches: [main, next] push: branches: [next, feat/**, agent/**, research/**, hotfix/**] + merge_group: jobs: lint: diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index a7612386e..4b13116e6 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -5,6 +5,7 @@ on: branches: [next, feat/**, agent/**, research/**, hotfix/**] pull_request: branches: [main, next] + merge_group: env: CARGO_TERM_COLOR: always @@ -40,7 +41,7 @@ jobs: msrv: name: Check MSRV runs-on: ubuntu-latest - if: github.event_name == 'pull_request' + if: github.event_name == 'pull_request' || github.event_name == 'merge_group' steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index 9d27de650..a9e2c654a 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -8,6 +8,7 @@ on: branches: [next, feat/**, agent/**, research/**, hotfix/**] pull_request: branches: [main, next] + merge_group: schedule: - cron: "0 3 * * 1" From aec2101c732f0c12574cfa462fed4ba0eb1a4e70 Mon Sep 17 00:00:00 2001 From: mmacedoeu Date: Tue, 24 Feb 2026 19:25:12 -0300 Subject: [PATCH 2/2] docs: add Blueprint layer for governance architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add BLUEPRINT.md explaining how ideas become protocol reality - Add RFCs directory with RFC-0001 (Mission Lifecycle) and RFC-0002 (Agent Manifest) - Add use-cases directory with Decentralized Mission Execution - Establish governance stack: Use Cases → RFCs → Missions → Agents - Create missions directory structure (open/, claimed/, with-pr/, archived/) This formalizes the decision flow and enables scalable contributor onboarding: 'What do I do first?' becomes 'Read Blueprint → Claim Mission' --- docs/BLUEPRINT.md | 454 ++++++++++++++++++ .../decentralized-mission-execution.md | 150 ++++++ rfcs/0000-template.md | 107 +++++ rfcs/0001-mission-lifecycle.md | 205 ++++++++ rfcs/0002-agent-manifest.md | 254 ++++++++++ rfcs/README.md | 239 +++++++++ 6 files changed, 1409 insertions(+) create mode 100644 docs/BLUEPRINT.md create mode 100644 docs/use-cases/decentralized-mission-execution.md create mode 100644 rfcs/0000-template.md create mode 100644 rfcs/0001-mission-lifecycle.md create mode 100644 rfcs/0002-agent-manifest.md create mode 100644 rfcs/README.md diff --git a/docs/BLUEPRINT.md b/docs/BLUEPRINT.md new file mode 100644 index 000000000..bce155f89 --- /dev/null +++ b/docs/BLUEPRINT.md @@ -0,0 +1,454 @@ +# The CipherOcto Blueprint + +**How ideas become protocol reality.** + +This is not documentation. This is process architecture. + +--- + +## Philosophy + +CipherOcto is not a repository. It is a protocol for autonomous intelligence collaboration. + +Most open-source projects organize files. Successful protocols organize **decision flow**. + +This Blueprint defines how work flows through CipherOcto—from idea to protocol evolution. + +--- + +## The Core Separation + +We maintain three distinct layers that must never mix: + +| Layer | Purpose | Question | Blockchain Analogy | +|-------|---------|----------|-------------------| +| **Use Cases** | Intent | WHY? | Ethereum Vision | +| **RFCs** | Design | WHAT? | EIPs | +| **Missions** | Execution | HOW? | Implementation | + +**Mix these layers and governance breaks.** + +--- + +## Governance Stack + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Idea Emerges │ +└──────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 1️⃣ USE CASES — Intent Layer │ +│ Location: docs/use-cases/ │ +│ │ +│ Defines: │ +│ - Problems to solve │ +│ - Narratives and motivation │ +│ - Architectural direction │ +│ │ +│ Characteristics: │ +│ - Long-lived │ +│ - Descriptive │ +│ - Non-actionable │ +└──────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 2️⃣ RFCs — Protocol Design Layer │ +│ Location: rfcs/ │ +│ │ +│ Defines: │ +│ - Specifications │ +│ - Constraints │ +│ - Interfaces │ +│ - Expected behavior │ +│ │ +│ Examples: │ +│ - RFC-0001: Mission Lifecycle │ +│ - RFC-0002: Agent Manifest Spec │ +│ - RFC-0003: Storage Provider Protocol │ +│ │ +│ Answer: "What must exist before implementation?" │ +└──────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 3️⃣ MISSIONS — Execution Layer │ +│ Location: missions/ │ +│ │ +│ A mission is a claimable unit of work. │ +│ - Never conceptual │ +│ - Always executable │ +│ - Created ONLY after: Use Case → RFC → Mission │ +└──────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 4️⃣ AGENTS — Execution Actors │ +│ Location: agents/ │ +│ │ +│ Agents do NOT decide direction. │ +│ They implement Missions derived from RFCs. │ +│ This prevents AI chaos. │ +└──────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 5️⃣ ROADMAP — Temporal Layer │ +│ Location: ROADMAP.md │ +│ │ +│ References: │ +│ - Use Cases │ +│ - RFC milestones │ +│ - Protocol phases │ +│ │ +│ Roadmap is navigation, NOT backlog. │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Canonical Workflow + +``` +Idea + │ + ▼ +Use Case (WHY?) + │ + ▼ +RFC Discussion (WHAT?) + │ + ├─ Draft RFC + ├─ Community Review + ├─ Revision + └─ Accepted RFC + │ + ▼ +Mission Created (HOW?) + │ + ▼ +Agent/Human Claims Mission + │ + ▼ +Implementation (PR) + │ + ▼ +Review & Test + │ + ▼ +Merge + │ + ▼ +Protocol Evolution +``` + +**This is the only flow. Shortcuts create technical debt.** + +--- + +## Artifact Types + +### Use Case + +**Location:** `docs/use-cases/` + +**Template:** +```markdown +# Use Case: [Title] + +## Problem +What problem exists? + +## Motivation +Why does this matter for CipherOcto? + +## Impact +What changes if this is implemented? + +## Related RFCs +- RFC-XXXX +``` + +**Examples:** +- Decentralized Mission Execution +- Autonomous Agent Marketplace +- Hybrid AI-Blockchain Runtime + +--- + +### RFC (Request for Comments) + +**Location:** `rfcs/` + +**Template:** +```markdown +# RFC-XXXX: [Title] + +## Status +Draft | Accepted | Replaced | Deprecated + +## Summary +One-paragraph overview. + +## Motivation +Why this RFC? + +## Specification +Technical details, constraints, interfaces. + +## Rationale +Why this approach over alternatives? + +## Implementation +Path to missions. + +## Related Use Cases +- [Use Case Name](../../docs/use-cases/...) +``` + +**RFC Process:** +1. Draft RFC in `rfcs/0000-title.md` +2. Submit PR for discussion +3. Address feedback +4. Accepted → Renumbered +5. Rejected → Moved to `rfcs/archived/` + +--- + +### Mission + +**Location:** `missions/` + +**Lifecycle:** +``` +missions/open/ → Available to claim +missions/claimed/ → Someone working on it +missions/with-pr/ → PR submitted +missions/archived/ → Completed or abandoned +``` + +**Template:** +```markdown +# Mission: [Title] + +## Status +Open | Claimed | In Review | Completed | Blocked + +## RFC +RFC-XXXX + +## Acceptance Criteria +- [ ] Criteria 1 +- [ ] Criteria 2 + +## Claimant +@username + +## Pull Request +# + +## Notes +Implementation notes, blockers, decisions. +``` + +**Mission Rules:** +- Missions REQUIRE an approved RFC +- No RFC = Create one first +- One mission = One claimable unit +- Missions are timeboxed + +--- + +## Agent Participation Model + +### What Agents CAN Do + +| Capability | Description | +|------------|-------------| +| Claim Missions | Pick up work from `missions/open/` | +| Implement Specs | Execute according to RFC | +| Write Tests | Ensure quality | +| Submit PRs | Standard contribution flow | + +### What Agents CANNOT Do + +| Restriction | Reason | +|-------------|--------| +| Create Use Cases | Human direction required | +| Accept RFCs | Governance decision | +| Bypass Missions | Chaos prevention | + +### Agent Workflow + +``` +1. Agent reads missions/open/ +2. Claims mission (moves to missions/claimed/) +3. Implements per RFC spec +4. Writes tests +5. Submits PR +6. Human review +7. Merge → mission to missions/archived/ +``` + +--- + +## Human vs Agent Roles + +| Activity | Human | Agent | +|----------|-------|-------| +| Define Use Cases | ✓ | ✗ | +| Write RFCs | ✓ | ✗ | +| Accept RFCs | ✓ | ✗ | +| Create Missions | ✓ | ✓ | +| Claim Missions | ✓ | ✓ | +| Implement RFCs | ✓ | ✓ | +| Review PRs | ✓ | ✗ | +| Merge to main | ✓ | ✗ | + +**Humans govern. Agents implement.** + +--- + +## RFC Acceptance Process + +1. **Draft:** Author creates RFC PR +2. **Review:** Community discusses (7-day minimum) +3. **Decision:** Maintainers accept/reject +4. **Outcome:** + - Accepted → Renumber, create Missions + - Rejected → Archive with reasoning + - Needs Work → Continue discussion + +**Consensus Required:** At least 2 maintainer approvals, no blocking objections. + +--- + +## Mission Lifecycle + +``` +┌──────────────┐ +│ RFC Accepted │ +└──────┬───────┘ + │ + ▼ +┌──────────────┐ +│ Mission │ +│ Created │ → missions/open/ +└──────┬───────┘ + │ + ▼ +┌──────────────┐ +│ Claimed │ → missions/claimed/ +└──────┬───────┘ + │ + ▼ +┌──────────────┐ +│ PR Submitted │ → missions/with-pr/ +└──────┬───────┘ + │ + ├─ Accept → Archive (completed) + └─ Reject → Return to claimed +``` + +**Timeouts:** +- Claimed mission: 14 days → Return to open +- PR in review: 7 days → Follow up or close + +--- + +## Future Decentralization Path + +### Phase 1: Foundation (Current) +- Human governance +- Centralized RFC process +- Mission-based execution + +### Phase 2: Stakeholder Input +- OCTO token holders vote on RFCs +- Reputation-based weighting +- Agent representation + +### Phase 3: Protocol Governance +- On-chain decision making +- Automated RFC acceptance +- Autonomous mission creation + +**The Blueprint enables this evolution.** + +--- + +## Repository Topology + +``` +cipherocto/ +├── docs/ +│ ├── BLUEPRINT.md ← This document +│ ├── START_HERE.md +│ ├── ROLES.md +│ ├── ROADMAP.md +│ └── use-cases/ ← Intent layer +│ ├── decentralized-mission-execution.md +│ └── agent-marketplace.md +├── rfcs/ ← Design layer +│ ├── README.md +│ ├── 0000-template.md +│ ├── 0001-mission-lifecycle.md +│ ├── 0002-agent-manifest.md +│ └── archived/ +├── missions/ ← Execution layer +│ ├── open/ +│ ├── claimed/ +│ ├── with-pr/ +│ └── archived/ +├── agents/ +└── crates/ +``` + +--- + +## Getting Started + +**New Contributor Flow:** + +1. Read `START_HERE.md` +2. Read `ROLES.md` +3. Read this `BLUEPRINT.md` +4. Browse `use-cases/` for context +5. Check `rfcs/` for active designs +6. Claim a mission from `missions/open/` + +**Mission Creator Flow:** + +1. Ensure RFC exists and is accepted +2. Create mission file in `missions/open/` +3. Define acceptance criteria +4. Link to RFC +5. Mark as ready to claim + +**RFC Author Flow:** + +1. Draft RFC from use case motivation +2. Submit PR for discussion +3. Address community feedback +4. Wait for acceptance +5. Create missions from accepted RFC + +--- + +## Summary + +**The CipherOcto Blueprint answers: "What do I do first?"** + +- Understand the Use Case (WHY) +- Read the RFC (WHAT) +- Claim the Mission (HOW) + +**Everything flows through this structure.** + +When in doubt, return to the Blueprint. + +--- + +*"We are not documenting a repository. We are defining how autonomous intelligence collaborates to build infrastructure."* diff --git a/docs/use-cases/decentralized-mission-execution.md b/docs/use-cases/decentralized-mission-execution.md new file mode 100644 index 000000000..d34ba28ab --- /dev/null +++ b/docs/use-cases/decentralized-mission-execution.md @@ -0,0 +1,150 @@ +# Use Case: Decentralized Mission Execution + +## Problem + +Software development today is fundamentally centralized: + +- Projects rely on a small group of core contributors +- Bottlenecks form when maintainers are unavailable +- Coordination overhead scales poorly with contributors +- Geographic and temporal boundaries limit collaboration + +CipherOcto aims to build decentralized AI infrastructure, but the development process itself remains centralized. + +## Motivation + +### Why This Matters + +If CipherOcto succeeds, it will attract global contributors across time zones. A centralized development model becomes a liability: + +- Contributors in Asia wait hours for Europe/US responses +- AI agents cannot coordinate effectively without structure +- Mission-critical work stalls if key humans are unavailable +- Scaling beyond dozens of contributors creates chaos + +### The Opportunity + +Decentralized mission execution enables: + +- **Async-first workflow**: Work progresses across time zones +- **Agent participation**: AI agents claim and complete missions +- **Merit-based contribution**: Reputation drives access, not politics +- **Resilience**: No single point of failure in development flow + +## Impact + +If decentralized mission execution works: + +| Area | Transformation | +|------|----------------| +| **Velocity** | 24/7 development across time zones | +| **Quality** | Clear acceptance criteria per mission | +| **Scalability** | Hundreds of concurrent contributors | +| **Innovation** | Lower friction for new contributors | + +If it fails: + +| Risk | Consequence | +|------|-------------| +| Fragmentation | Inconsistent contributions | +| Quality issues | Weak work enters codebase | +| Coordination overhead | More time managing than building | +| Agent chaos | AI agents waste resources | + +## Narrative + +### Current State (Centralized) + +``` +1. Contributor has idea +2. Opens issue or PR +3. Waits for maintainer review +4. Maintainer asks for changes +5. Contributor revises +6. Repeat until merged or abandoned +``` + +**Problems:** +- Step 3-5 can take days/weeks +- Maintainers become bottlenecks +- No visibility into progress +- Contributors ghost when feedback takes too long + +### Desired State (Decentralized) + +``` +1. Use Case defines WHY +2. RFC specifies WHAT +3. Mission defines HOW with acceptance criteria +4. Contributor (human or agent) claims mission +5. Implementation per RFC spec +6. Automated tests verify criteria +7. Peer review (no maintainer required) +8. Merge when criteria met +``` + +**Benefits:** +- Clear path from idea to completion +- No maintainer bottleneck (peer review) +- Agents can participate autonomously +- Work progresses 24/7 + +### Example Flow + +**A contributor in Tokyo wants to add a feature:** + +1. **2300 JST**: They browse `missions/open/` and find one matching their skills +2. **2315 JST**: They claim the mission (moves to `missions/claimed/`) +3. **0200 JST**: While they sleep, an agent in Europe reviews the RFC they're implementing +4. **0900 JST**: Tokyo contributor wakes up, implements feature +5. **1200 JST**: They submit PR (mission moves to `missions/with-pr/`) +6. **1500 JST**: A reviewer in New York approves the PR +7. **1800 JST**: PR merges, mission completes + +**Total elapsed time: 19 hours across 3 time zones** +**Traditional flow: 3-5 days of back-and-forth** + +## Related RFCs + +- **RFC-0001**: Mission Lifecycle + - Defines states: OPEN → CLAIMED → IN_REVIEW → COMPLETED + - Establishes timeout rules + - Enables async handoff + +- **RFC-0002**: Agent Manifest Specification + - Enables agents to claim missions + - Defines capability verification + - Establishes reputation system + +## Success Metrics + +| Metric | Current | Target | +|--------|---------|--------| +| Time to claim mission | N/A | < 1 hour | +| Mission completion rate | N/A | > 80% | +| Agent participation | 0% | > 30% of missions | +| Maintainer bottleneck | 100% of PRs | < 20% of PRs | +| Cross-timezone velocity | 1 PR/day | 5+ PRs/day | + +## Open Questions + +1. How do we handle mission disputes? +2. What if two agents claim simultaneously? +3. How do we measure "success" of completed missions? +4. Should missions have bounties? + +## Timeline + +| Phase | When | What | +|-------|------|------| +| **Phase 1** | Q1 2025 | RFC acceptance, mission system implemented | +| **Phase 2** | Q2 2025 | Agent claiming, first AI-completed missions | +| **Phase 3** | Q3 2025 | Reputation system, automated quality checks | +| **Phase 4** | Q4 2025 | Full decentralized operation, human oversight only | + +--- + +**Category:** Protocol Governance +**Priority:** High +**RFCs:** RFC-0001, RFC-0002 +**Status:** Defined → Ready for RFC phase diff --git a/rfcs/0000-template.md b/rfcs/0000-template.md new file mode 100644 index 000000000..94ec97338 --- /dev/null +++ b/rfcs/0000-template.md @@ -0,0 +1,107 @@ +# RFC-XXXX: [Title] + +## Status +Draft | Accepted | Rejected | Replaced | Deprecated + +## Summary +One-paragraph overview of the proposal. + +## Motivation + +### Problem Statement +What problem does this solve? + +### Current State +How do things work now? + +### Desired State +How should things work after this RFC? + +### Use Case Link +- [Use Case Name](../docs/use-cases/filename.md) + +## Specification + +### Data Structures +```rust +// Define key types, structs, enums +``` + +### APIs/Interfaces +```rust +// Function signatures, method definitions +``` + +### Protocols +Step-by-step interaction flows. + +### Constraints +- Must support... +- Must not break... +- Limited to... + +### Error Handling +How failures are detected and reported. + +## Rationale + +### Why This Approach? +Technical justification for chosen design. + +### Alternatives Considered +| Alternative | Pros | Cons | Rejection Reason | +|-------------|------|------|------------------| +| Option A | | | | +| Option B | | | | + +### Trade-offs +What did we prioritize? What did we deprioritize? + +## Implementation + +### Mission 1: [Title] +- Acceptance criteria: + - [ ] Criteria 1 + - [ ] Criteria 2 +- Estimated complexity: Low/Medium/High + +### Mission 2: [Title] +- Acceptance criteria: + - [ ] Criteria 1 + - [ ] Criteria 2 +- Estimated complexity: Low/Medium/High + +### Mission 3: [Title] +- Acceptance criteria: + - [ ] Criteria 1 + - [ ] Criteria 2 +- Estimated complexity: Low/Medium/High + +## Impact + +### Breaking Changes +What existing functionality changes? + +### Migration Path +How do users/developers migrate? + +### Dependencies +- RFC-XXXX: [Title] +- External: [crate/lib] + +### Performance +Impact on performance/throughput/latency. + +## Related RFCs +- RFC-XXXX: [Title] +- RFC-YYYY: [Title] + +## References +- [External Spec](https://...) +- [Prior Art](https://...) +- [Discussion](link to issue/PR) + +--- + +**Submission Date:** YYYY-MM-DD +**Last Updated:** YYYY-MM-DD diff --git a/rfcs/0001-mission-lifecycle.md b/rfcs/0001-mission-lifecycle.md new file mode 100644 index 000000000..ad054fc45 --- /dev/null +++ b/rfcs/0001-mission-lifecycle.md @@ -0,0 +1,205 @@ +# RFC-0001: Mission Lifecycle + +## Status +Accepted + +## Summary +Define the standard lifecycle for missions in CipherOcto, from creation through completion, establishing clear states, transitions, and timeout rules for claimable work units. + +## Motivation + +CipherOcto scales through parallel execution by both humans and AI agents. Without a standardized mission lifecycle: + +- Claimed work stagnates indefinitely +- No visibility into what's being worked on +- Unclear handoff between contributors +- No mechanism to detect abandoned missions + +This RFC provides the governance framework for mission-based execution. + +### Use Case Link +- [Decentralized Mission Execution](../docs/use-cases/decentralized-mission-execution.md) + +## Specification + +### Mission States + +``` +┌──────────────┐ +│ OPEN │ Available for claim +└──────┬───────┘ + │ claimed + ▼ +┌──────────────┐ +│ CLAIMED │ Someone is working on it +└──────┬───────┘ + │ PR submitted + ▼ +┌──────────────┐ +│ IN_REVIEW │ PR under review +└──────┬───────┘ + │ + ├─ accepted ──► COMPLETED + │ + └─ rejected ──► CLAIMED (rework) + │ + │ timeout (14d) + ▼ + OPEN +``` + +### State Definitions + +| State | Description | Valid Transitions | +|-------|-------------|-------------------| +| `OPEN` | Available to claim | → CLAIMED | +| `CLAIMED` | Someone assigned | → IN_REVIEW, → OPEN (timeout) | +| `IN_REVIEW` | PR submitted | → COMPLETED, → CLAIMED | +| `COMPLETED` | Merged to main | Terminal state | +| `BLOCKED` | Cannot proceed | → CLAIMED (unblocked) | +| `ARCHIVED` | Closed/abandoned | Terminal state | + +### Mission File Format + +```yaml +# missions/0001-add-mission-lifecycle.md + +id: "0001" +title: "Add Mission Lifecycle" +status: "open" # open | claimed | in_review | completed | blocked | archived +created_at: "2025-02-24T00:00:00Z" +updated_at: "2025-02-24T00:00:00Z" + +rfc: "0001" + +claimant: null # @username when claimed +claimed_at: null + +pull_request: null # PR number when in review + +acceptance_criteria: + - "Mission state enum defined" + - "State transition functions implemented" + - "Timeout enforcement added" + - "Tests for all transitions" + +timeout_days: 14 # Days before auto-unclaim +``` + +### Timeout Rules + +| State | Timeout | Action | +|-------|---------|--------| +| `CLAIMED` | 14 days | Return to `OPEN` | +| `IN_REVIEW` | 7 days | Request status update | +| `BLOCKED` | 30 days | Archive or reassign | + +### Directory Structure + +``` +missions/ +├── open/ # Available to claim +├── claimed/ # Currently assigned +├── with-pr/ # PR submitted +├── completed/ # Merged successfully +└── archived/ # Closed/abandoned +``` + +### API Surface + +```rust +pub enum MissionStatus { + Open, + Claimed { claimant: String, claimed_at: DateTime }, + InReview { pr_number: u64 }, + Completed { merged_at: DateTime }, + Blocked { reason: String }, + Archived { reason: String }, +} + +pub struct Mission { + pub id: String, + pub title: String, + pub status: MissionStatus, + pub rfc: String, + pub acceptance_criteria: Vec, + pub timeout_days: u64, +} + +impl Mission { + // State transitions + pub fn claim(&mut self, claimant: &str) -> Result<(), Error>; + pub fn submit_pr(&mut self, pr_number: u64) -> Result<(), Error>; + pub fn complete(&mut self) -> Result<(), Error>; + pub fn unclaim(&mut self) -> Result<(), Error>; + + // Timeouts + pub fn check_timeout(&self) -> Option; +} +``` + +## Rationale + +**Why mission-based instead of issue-based?** + +Issues are discussions. Missions are claimable units of work. By separating them: +- Clear intent to execute +- Handoff mechanism between contributors +- Timeout enforcement +- Direct RFC traceability + +**Why 14-day claim timeout?** + +Long enough for substantial work, short enough to prevent stagnation. Contributors can re-claim if still engaged. + +**Why separate `with-pr/` directory?** + +Visibility into what's awaiting review prevents duplicate work and enables batch processing of PRs. + +## Implementation + +### Mission 1: Core Mission Types +- Define `MissionStatus` enum +- Implement `Mission` struct +- Add state transition validation + +### Mission 2: Filesystem Backend +- Mission CRUD operations +- Directory-based state management +- YAML serialization + +### Mission 3: CLI Commands +- `octo mission list` +- `octo mission claim ` +- `octo mission submit ` +- `octo mission status ` + +### Mission 4: Timeout Enforcement +- Background task to check timeouts +- Auto-unclaim stale missions +- Notifications for impending timeouts + +## Impact + +### Breaking Changes +None. This is new functionality. + +### Migration Path +Existing issues can be tagged as missions. No data loss. + +### Dependencies +- RFC-0002: Agent Manifest (missions may be claimed by agents) + +## Related RFCs +- RFC-0002: Agent Manifest Specification + +## References + +- [GitHub Issues](https://guides.github.com/features/issues/) +- [Jira Workflow](https://www.atlassian.com/agile/tutorials/workflows) +- [Linear Issue Lifecycle](https://linear.app/) + +--- + +**Acceptance Date:** 2025-02-24 +**Implemented By:** [Mission List](../missions/open/) diff --git a/rfcs/0002-agent-manifest.md b/rfcs/0002-agent-manifest.md new file mode 100644 index 000000000..38f83848c --- /dev/null +++ b/rfcs/0002-agent-manifest.md @@ -0,0 +1,254 @@ +# RFC-0002: Agent Manifest Specification + +## Status +Accepted + +## Summary +Define the standard manifest format for CipherOcto agents, enabling autonomous agents to claim missions, report capabilities, and interact with the protocol in a structured, verifiable way. + +## Motivation + +CipherOcto enables AI agents to participate in protocol development. Without a standard manifest format: + +- No way to verify agent capabilities +- No standardized mission claiming protocol +- Agents cannot self-describe appropriately +- No audit trail for agent actions + +This RFC establishes the agent identity and capability layer. + +### Use Case Link +- [Autonomous Agent Marketplace](../docs/use-cases/autonomous-agent-marketplace.md) + +## Specification + +### Agent Manifest + +```toml +# Agent.toml - Standard agent manifest + +[agent] +id = "claude-code-4.5" +name = "Claude Code" +version = "4.5.0" +creator = "anthropic" +created = "2025-02-24T00:00:00Z" + +[[agent.capabilities]] +category = "rust" +operations = ["implement", "test", "refactor"] +confidence = "high" + +[[agent.capabilities]] +category = "documentation" +operations = ["write", "update"] +confidence = "medium" + +[[agent.capabilities]] +category = "protocol" +operations = ["rfc-read", "mission-claim"] +confidence = "high" + +[agent.limits] +max_missions = 3 +timeout_hours = 168 # 1 week + +[agent.identity] +public_key = "0x..." +signature = "..." + +[agent.references] +rfcs = ["0001", "0002"] +completed_missions = ["0001", "0003"] +reputation_score = 0.95 +``` + +### Capability Categories + +| Category | Operations | Description | +|----------|------------|-------------| +| `rust` | implement, test, refactor | Rust development | +| `protocol` | rfc-read, mission-claim | Protocol interaction | +| `documentation` | write, update | Docs and guides | +| `review` | code-review, security-review | PR review | +| `testing` | unit-test, integration-test | Test creation | +| `blockchain` | smart-contract, integration | Chain integration | + +### Agent State Machine + +``` +┌──────────────┐ +│ REGISTERED │ Manifest submitted +└──────┬───────┘ + │ verified + ▼ +┌──────────────┐ +│ ACTIVE │ Can claim missions +└──────┬───────┘ + │ + ├─ working ──► BUSY + │ │ + │ │ mission complete + │ ▼ + │ ACTIVE + │ + └─ violation ──► SUSPENDED + │ + │ appeal + ▼ + ACTIVE +``` + +### Mission Claiming Protocol + +**Agent → Protocol** + +```json +POST /api/v1/missions/{id}/claim +{ + "agent_id": "claude-code-4.5", + "signature": "0x...", + "estimated_hours": 8, + "approach": "Will implement using X, testing with Y" +} + +Response: +{ + "status": "claimed", + "timeout": "2025-03-03T00:00:00Z", + "mission": { + "id": "0001", + "rfc": "0001", + "acceptance_criteria": [...] + } +} +``` + +**Agent → Protocol (Progress Update)** + +```json +POST /api/v1/missions/{id}/progress +{ + "agent_id": "claude-code-4.5", + "status": "in_progress", + "percent_complete": 60, + "blockers": [], + "eta": "2025-02-26T00:00:00Z" +} +``` + +**Agent → Protocol (Submit PR)** + +```json +POST /api/v1/missions/{id}/submit +{ + "agent_id": "claude-code-4.5", + "pr_number": 123, + "signature": "0x...", + "summary": "Implemented mission lifecycle with state transitions", + "tests_added": 15, + "tests_passing": true +} +``` + +### Verification + +Every agent interaction must be signed: + +```rust +pub struct AgentMessage { + pub agent_id: String, + pub payload: Payload, + pub timestamp: DateTime, + pub signature: String, +} + +impl AgentMessage { + pub fn verify(&self) -> Result { + // Verify signature against agent's registered public key + let public_key = get_agent_key(&self.agent_id)?; + public_key.verify(&self.signature, &self.payload) + } +} +``` + +## Rationale + +**Why TOML for manifests?** + +Human-readable, standard in Rust ecosystem, easy to parse. + +**Why capability-based instead of role-based?** + +Capabilities are granular and composable. Roles are rigid. An agent can be good at Rust implementation but poor at security review—capabilities capture this nuance. + +**Why signature verification?** + +Prevents agent impersonation. Ensures accountability. Enables reputation tracking. + +**Why mission limits?** + +Prevents any single agent from monopolizing work. Encourages distribution of tasks. + +**What prevents rogue agents?** + +- Capability gates (can't claim what you're not capable of) +- Reputation system (poor performance → fewer missions) +- Human review on all PRs +- RFC constraints (agents implement, don't design) + +## Implementation + +### Mission 1: Agent Registry +- Store agent manifests +- Public key registration +- Capability indexing + +### Mission 2: Claim API +- Mission claiming endpoint +- Signature verification +- State management + +### Mission 3: Progress Tracking +- Progress update endpoint +- Status queries +- Timeout monitoring + +### Mission 4: CLI Integration +- `octo agent register ` +- `octo agent list` +- `octo agent status ` + +### Mission 5: Reputation System +- Track completed missions +- Calculate quality scores +- Influence mission assignment + +## Impact + +### Breaking Changes +None. This is new functionality. + +### Security Considerations +- Signature verification must be robust +- Replay attack prevention +- Key rotation support + +### Privacy Considerations +- Agent capabilities are public +- Mission history is public +- No private data in manifests + +## Related RFCs +- RFC-0001: Mission Lifecycle (agents claim missions) + +## References + +- [DID Specification](https://www.w3.org/TR/did-core/) +- [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/) +- [Agent Capability Models](https://arxiv.org/abs/2301.07041) + +--- + +**Acceptance Date:** 2025-02-24 +**Implemented By:** [Mission List](../missions/open/) diff --git a/rfcs/README.md b/rfcs/README.md new file mode 100644 index 000000000..2df6f73f7 --- /dev/null +++ b/rfcs/README.md @@ -0,0 +1,239 @@ +# CipherOcto RFCs + +**Request for Comments** — Protocol Design Layer + +RFCs define **WHAT** must exist before implementation begins. + +Inspired by: +- [Rust RFCs](https://github.com/rust-lang/rfcs) +- [Ethereum EIPs](https://eips.ethereum.org/) +- [Internet RFC Process](https://www.rfc-editor.org/) + +--- + +## What is an RFC? + +An RFC is a **design specification**, not implementation. + +**RFC answers:** +- What are we building? +- What are the constraints? +- What are the interfaces? +- What is the expected behavior? + +**RFC does NOT answer:** +- How do we implement it? (→ Missions) +- Who will implement it? (→ Agents/Humans) +- When will it be done? (→ Roadmap) + +--- + +## RFC Lifecycle + +``` +Draft → Review → Accepted | Rejected | Archived +``` + +| Status | Description | Location | +|--------|-------------|----------| +| **Draft** | Open for discussion | `rfcs/0000-title.md` | +| **Review** | PR submitted, community feedback | PR comment thread | +| **Accepted** | Approved, create missions | `rfcs/XXXX-title.md` | +| **Rejected** | Declined, record reasoning | `rfcs/archived/` | +| **Replaced** | Superseded by newer RFC | `rfcs/archived/` | + +--- + +## RFC Template + +```markdown +# RFC-XXXX: [Title] + +## Status +Draft | Accepted | Rejected | Replaced | Deprecated + +## Summary +One-paragraph overview of the proposal. + +## Motivation +Why is this RFC needed? What problem does it solve? + +### Use Case Link +Link to the motivating use case in `docs/use-cases/`. + +## Specification +Detailed technical specification: +- Data structures +- APIs/interfaces +- Protocols +- Constraints +- Error handling + +## Rationale +Why this approach over alternatives? +What trade-offs were made? + +## Implementation +Path from RFC to Missions: +- Mission 1: [description] +- Mission 2: [description] +- Mission 3: [description] + +## Impact +What does this change? +- Breaking changes? +- Migration path? +- Dependencies? + +## Related RFCs +- RFC-XXXX +- RFC-YYYY + +## References +Links to external specs, prior art, discussions. +``` + +--- + +## RFC Process + +### 1. Draft RFC + +Create `rfcs/0000-your-title.md` using the template. + +```bash +# Start with template +cp rfcs/0000-template.md rfcs/0000-my-proposal.md +``` + +### 2. Submit for Review + +Create PR: `rfcs: RFC-XXXX: [Title]` + +Include in description: +- Link to use case (if applicable) +- Summary of change +- Request for reviewers + +### 3. Discussion Period + +- **Minimum 7 days** for substantial RFCs +- **3 days** for minor clarifications +- All feedback must be addressed + +### 4. Decision + +**Acceptance Criteria:** +- At least 2 maintainer approvals +- No blocking objections +- Technical soundness verified + +**Possible Outcomes:** + +| Outcome | Action | +|---------|--------| +| **Accepted** | Renumber to next available, create missions | +| **Rejected** | Move to `rfcs/archived/` with reasoning | +| **Request Changes** | Continue discussion, resubmit | +| **Postpone** | Not now, keep in `rfcs/` as Draft | + +### 5. Implementation + +Once accepted: +1. RFC is numbered (e.g., `0001`) +2. Missions created in `missions/open/` +3. Agents/humans claim missions +4. PRs reference RFC + +--- + +## RFC Numbering + +- **0000**: Draft RFCs (unproposed) +- **0001-0999**: Core protocol +- **1000-1999**: Agent system +- **2000-2999**: Network layer +- **3000-3999**: Cryptography +- **4000-4999**: Tokenomics +- **5000-5999**: Governance +- **9000-9999**: Meta/Process + +--- + +## Active RFCs + +| RFC | Title | Status | Link | +|-----|-------|--------|------| +| RFC-0001 | Mission Lifecycle | Accepted | [0001-mission-lifecycle.md](0001-mission-lifecycle.md) | +| RFC-0002 | Agent Manifest Specification | Accepted | [0002-agent-manifest.md](0002-agent-manifest.md) | + +--- + +## Submitting an RFC + +**Before writing an RFC:** + +1. Check `docs/use-cases/` for motivation +2. Search existing RFCs for similar work +3. Discuss in issue/forums first (optional but recommended) + +**When to write an RFC:** + +- ✓ New protocol feature +- ✓ Breaking change +- ✓ New agent capability +- ✓ Architecture change +- ✓ Standard/specification + +**When NOT to write an RFC:** + +- ✗ Bug fixes (just fix them) +- ✗ Documentation improvements +- ✗ Internal refactoring +- ✗ Test additions + +--- + +## RFC Review Guidelines + +**For Reviewers:** + +- Focus on technical merit +- Consider long-term implications +- Suggest alternatives if concerns +- Explain reasoning for objections + +**For Authors:** + +- Address all feedback +- Update spec based on discussion +- Withdraw if consensus impossible +- Be willing to compromise + +--- + +## FAQ + +### Q: Can I implement without an RFC? + +A: Only for bug fixes, docs, tests. New features require RFC. + +### Q: How long does RFC review take? + +A: Plan for 2-4 weeks including discussion and revisions. + +### Q: Can RFCs be changed after acceptance? + +A: Minor clarifications: yes. Major changes: new RFC. + +### Q: What if my RFC is rejected? + +A: It's archived with reasoning. You can revise and resubmit. + +### Q: Do agents participate in RFCs? + +A: Agents can provide input, but humans accept/reject. + +--- + +**See [`BLUEPRINT.md`](../docs/BLUEPRINT.md) for how RFCs fit into the overall governance flow.**