Contribution Format Specification

Version: 1.0.0 Status: ACTIVE Epic: T2308 - Contribution Protocol System v2 Created: 2026-01-26 Last Updated: 2026-01-26 Implementation Report: CONTRIBUTION-FORMAT-IMPLEMENTATION-REPORT.md

Preamble

Purpose

This specification defines the JSON-first contribution format for multi-agent consensus workflows in CLEO. The format enables machine-parseable decision documentation, automated conflict detection, and programmatic consensus computation.

Authority

This specification is AUTHORITATIVE for:

Contribution JSON object structure
Decision object format and validation
Confidence score semantics and weighting
Evidence reference format
Conflict detection structures
JSONL manifest format

This specification DEFERS to:

SPEC-BIBLE-GUIDELINES.md for document structure
contribution.schema.json for JSON Schema validation
CONSENSUS-FRAMEWORK-SPEC.md for consensus protocol rules

Design Philosophy

JSON-First: All contribution data MUST be machine-parseable. Markdown is prohibited for decision content. Weighted Consensus: Confidence scores enable proportional voting rather than binary agreement. Traceability: Evidence references create audit trails from decisions to source material. Automation-Ready: Format enables automated conflict detection and consensus aggregation without human parsing.

RFC 2119 Conformance

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 RFC 2119 RFC 8174 when, and only when, they appear in all capitals, as shown here.

Overview

This specification defines the data formats for the CLEO Contribution Protocol, enabling multi-agent coordination through structured decision tracking and consensus computation. Two Components:

Contribution Format (Part 1): Individual contribution JSON structure
JSONL Manifest (Part 2): Append-only index for querying and validation

Part 1: Contribution Format

1.1 Top-Level Schema

A contribution object MUST conform to the following structure:

{
  "$schema": "https://cleo-dev.com/schemas/v1/contribution.schema.json",
  "_meta": { /* Metadata object - Section 1.2 */ },
  "sessionId": "session_YYYYMMDD_HHMMSS_6hex",
  "epicId": "TNNNN",
  "taskId": "TNNNN",
  "markerLabel": "slug-identifier",
  "decisions": [ /* Decision array - Section 1.4 */ ],
  "conflicts": [ /* Conflict array - Section 1.5 */ ],
  "researchOutputs": [ /* Research output array - Section 1.6 */ ],
  "status": "draft|complete|validated|merged",
  "baselineReference": { /* Optional baseline - Section 1.3 */ },
  "validation": { /* Optional validation results - Section 1.7 */ }
}

1.2 Metadata Object (`_meta`)

The _meta object MUST contain contribution tracking information:

Field	Type	Required	Description
`contributionId`	string	MUST	Unique identifier: `contrib_{8 hex chars}`
`protocolVersion`	string	SHOULD	Semver of contribution protocol (default: “1.0.0”)
`createdAt`	string	MUST	ISO 8601 timestamp of creation
`completedAt`	string\|null	MAY	ISO 8601 timestamp when finalized
`agentId`	string	MUST	Contributing agent identifier (e.g., “opus-1”)
`checksum`	string\|null	MAY	SHA-256 truncated hash (16 hex chars) for integrity
`consensusReady`	boolean	SHOULD	Whether contribution is ready for consensus computation

Pattern Requirements:

contributionId MUST match: ^contrib_[a-f0-9]{8}$
agentId MUST match: ^[a-zA-Z0-9_-]{1,50}$
checksum MUST match: ^[a-f0-9]{16}$ when present

1.3 Session Context Fields

Field	Type	Required	Description
`sessionId`	string	MUST	Active CLEO session identifier
`sessionLabel`	string	SHOULD	Human-readable label (e.g., “Session B”)
`epicId`	string	MUST	Parent epic task ID
`epicTitle`	string	SHOULD	Epic title for context
`taskId`	string	MUST	Contribution task ID
`markerLabel`	string	MUST	Discovery label for cross-session queries

Pattern Requirements:

sessionId MUST match: ^session_\d{8}_\d{6}_[a-f0-9]{6}$
epicId and taskId MUST match: ^T\d{3,}$
markerLabel MUST match: ^[a-z][a-z0-9-]*$ (3-50 chars)

Baseline Reference Object (when comparing against prior contribution):

{
  "baselineReference": {
    "sessionId": "session_20260125_120000_def456",
    "sessionLabel": "Session A",
    "taskId": "T2205",
    "contributionId": "contrib_e5f6g7h8"
  }
}

1.4 Decision Object Structure

1.4.1 Decision Schema

Each decision MUST document a single question-answer pair:

{
  "questionId": "RCSD-001",
  "question": "The decision question being answered",
  "answer": "The concrete decision value",
  "confidence": 0.85,
  "rationale": "Reasoning for this decision",
  "evidence": [
    {
      "file": "lib/file-ops.sh",
      "section": "atomic_write function",
      "quote": "temp file -> validate -> backup -> rename",
      "line": 142,
      "type": "code"
    }
  ],
  "uncertaintyNote": "Optional note about remaining uncertainty",
  "alternatives": [
    {
      "option": "Alternative considered",
      "reason": "Why not chosen"
    }
  ]
}

1.4.2 Decision Fields

Field	Type	Required	Description
`questionId`	string	MUST	Unique question identifier (e.g., “RCSD-001”)
`question`	string	MUST	The decision question (10-300 chars)
`answer`	string	MUST	Concrete decision value (5-1000 chars)
`confidence`	number	MUST	Confidence score 0.0-1.0
`rationale`	string	MUST	Decision reasoning (20-2000 chars)
`evidence`	array	MUST	Evidence references (min 1 item)
`uncertaintyNote`	string\|null	SHOULD	Uncertainty explanation when confidence < 0.7
`alternatives`	array	MAY	Rejected alternatives with reasons

Pattern Requirements:

questionId MUST match: ^[A-Z]+-\d{3}$

1.4.3 Confidence Score Semantics

Confidence scores MUST follow these semantic ranges:

Range	Level	Meaning	Requirements
0.90-1.00	Very High	Near-certain based on strong evidence	MUST have 2+ independent evidence sources
0.70-0.89	High	Confident with minor uncertainty	MUST have at least 1 evidence source
0.50-0.69	Medium	Balanced uncertainty, reasonable basis	SHOULD include `uncertaintyNote`
0.30-0.49	Low	Significant uncertainty, best guess	MUST include `uncertaintyNote`
0.00-0.29	Tentative	Speculative, needs validation	MUST include `uncertaintyNote`, SHOULD NOT be used for critical decisions

Weighted Consensus Formula:

weighted_vote = confidence_score * vote_direction
aggregate = sum(weighted_votes) / count(contributions)

Where vote_direction is +1 (agreement) or -1 (disagreement) for binary questions.

1.4.4 Answer Requirements

Answers MUST be:

Concrete: Specific, actionable statements
Unambiguous: Single interpretation possible
Testable: Verifiable against implementation

Answers MUST NOT:

Use hedging language (“maybe”, “possibly”, “could be”)
Be self-contradictory
Reference other answers without explicit resolution

1.5 Evidence Reference Structure

1.5.1 Evidence Object Schema

Each evidence reference MUST document the source:

{
  "file": "path/to/file.ext",
  "section": "Section or function name",
  "quote": "Exact quote from source (optional)",
  "line": 142,
  "url": "https://example.com/doc#section",
  "type": "code|documentation|research|external"
}

1.5.2 Evidence Fields

Field	Type	Required	Description
`file`	string	MUST*	Relative path to source file
`section`	string	MUST	Section identifier or description
`quote`	string	SHOULD	Exact quote supporting the decision (max 500 chars)
`line`	number	SHOULD	Line number for code references
`url`	string	MUST*	URL for external sources
`type`	string	SHOULD	Evidence classification

*At least one of file or url MUST be present.

1.5.3 Evidence Types

Type	Use Case	Verification Method
`code`	Implementation evidence	Line number + file path
`documentation`	Specification or guide evidence	Section heading + file
`research`	Research output reference	Research manifest ID
`external`	External URL or documentation	URL + access timestamp

1.5.4 Evidence Quality Requirements

Evidence MUST be:

Traceable: Locatable by another agent using the reference
Current: Reflect the state at decision time
Relevant: Directly support the decision rationale

Evidence SHOULD include:

Direct quotes when the exact wording matters
Line numbers for code references
Section anchors for long documents

1.6 Conflict Structure

1.6.1 Conflict Object Schema

Conflicts document disagreements requiring resolution:

{
  "questionId": "RCSD-003",
  "conflictId": "conflict_a1b2c3d4",
  "severity": "high",
  "conflictType": "contradiction",
  "thisSession": {
    "position": "Single JSON file architecture",
    "confidence": 0.85,
    "evidence": [{ /* Evidence object */ }]
  },
  "otherSession": {
    "sessionId": "session_20260125_120000_def456",
    "sessionLabel": "Session A",
    "contributionId": "contrib_e5f6g7h8",
    "position": "Split files per component type",
    "confidence": 0.75,
    "evidence": [{ /* Evidence object */ }]
  },
  "rationale": "Why positions differ",
  "resolution": {
    "status": "pending|proposed|accepted|rejected",
    "proposedBy": "opus-1",
    "proposal": "Proposed resolution text",
    "resolutionType": "merge|choose-a|choose-b|new|defer|escalate",
    "votes": [
      { "agentId": "opus-1", "vote": "accept", "confidence": 0.9 },
      { "agentId": "sonnet-1", "vote": "reject", "confidence": 0.6 }
    ]
  },
  "requiresConsensus": true,
  "escalatedToHITL": false
}

1.6.2 Conflict Fields

Field	Type	Required	Description
`questionId`	string	MUST	Question where conflict exists
`conflictId`	string	MUST	Unique conflict identifier
`severity`	enum	MUST	Impact severity
`conflictType`	enum	MUST	Classification of conflict
`thisSession`	object	MUST	Current session’s position
`otherSession`	object	MUST	Conflicting session’s position
`rationale`	string	MUST	Why positions differ
`resolution`	object	SHOULD	Resolution proposal and votes
`requiresConsensus`	boolean	MUST	Whether multi-session consensus needed
`escalatedToHITL`	boolean	SHOULD	Whether escalated to human

1.6.3 Severity Levels

Severity	Definition	Action Required
`critical`	Mutually exclusive positions on core design	MUST resolve before merge
`high`	Significant impact on implementation	SHOULD resolve before merge
`medium`	Different approaches, both viable	MAY defer resolution
`low`	Minor preference differences	MAY accept either position

1.6.4 Conflict Types

Type	Definition	Detection Method
`contradiction`	Mutually exclusive answers	Semantic analysis
`partial-overlap`	Answers agree on some aspects, disagree on others	Field-by-field comparison
`scope-difference`	Different interpretation of question scope	Question normalization
`priority-difference`	Agreement on options, disagreement on ranking	Confidence comparison
`evidence-conflict`	Same evidence, different conclusions	Evidence cross-reference

1.6.5 Resolution Object

{
  "resolution": {
    "status": "pending|proposed|accepted|rejected",
    "proposedBy": "agent-id",
    "proposedAt": "2026-01-26T15:00:00Z",
    "proposal": "Detailed resolution proposal",
    "resolutionType": "merge|choose-a|choose-b|new|defer|escalate",
    "votes": [
      {
        "agentId": "opus-1",
        "vote": "accept|reject|abstain",
        "confidence": 0.9,
        "reason": "Vote rationale"
      }
    ],
    "resolvedAt": "2026-01-26T16:00:00Z",
    "finalDecision": "The accepted resolution"
  }
}

Resolution Types:

Type	Description
`merge`	Combine elements from both positions
`choose-a`	Accept this session’s position
`choose-b`	Accept other session’s position
`new`	Neither position; create new answer
`defer`	Postpone resolution
`escalate`	Requires human decision (HITL)

1.7 Research Outputs

{
  "filePath": "claudedocs/agent-outputs/2026-01-25_analysis.md",
  "researchId": "research_a1b2c3d4",
  "type": "analysis|research|specification|synthesis|comparison|notes",
  "title": "Document title",
  "createdAt": "2026-01-25T14:15:00Z",
  "linkedAt": "2026-01-25T14:20:00Z",
  "summary": "Brief summary of contents"
}

Field	Type	Required	Description
`filePath`	string	MUST	Relative path to research file
`researchId`	string	SHOULD	Research manifest ID for cross-reference
`type`	enum	MUST	Output classification
`title`	string	SHOULD	Document title
`createdAt`	string	SHOULD	Creation timestamp
`linkedAt`	string	SHOULD	When linked to task
`summary`	string	SHOULD	Brief content summary (max 500 chars)

1.8 Status Lifecycle

Status	Description	Transitions To
`draft`	Work in progress, editable	`complete`
`complete`	Finalized by agent, awaiting validation	`validated`, `draft`
`validated`	Passed schema and semantic validation	`merged`, `complete`
`merged`	Incorporated into consensus synthesis	Terminal

A contribution MUST NOT transition backwards beyond one step (e.g., validated to draft is prohibited).

1.9 Validation Requirements

1.9.1 Schema Validation

All contributions MUST pass JSON Schema validation against contribution.schema.json.

1.9.2 Semantic Validation

Beyond schema validation, implementations SHOULD enforce:

Rule ID	Level	Requirement
`CONTRIB-001`	MUST	`sessionId` matches active CLEO session
`CONTRIB-002`	MUST	`markerLabel` present on task for discovery
`CONTRIB-003`	MUST	All research files exist at specified paths
`CONTRIB-004`	MUST	Research outputs linked to task notes
`CONTRIB-005`	MUST	All key questions have decisions
`CONTRIB-006`	MUST	Explicit conflicts flagged with baseline
`CONTRIB-007`	MUST	Decisions include rationale and evidence
`CONTRIB-010`	MUST	Conflicts include comparison rationale
`CONTRIB-011`	MUST NOT	Answers use vague or ambiguous language
`CONTRIB-012`	SHOULD	File paths follow `YYYY-MM-DD_topic-slug.md`
`CONTRIB-013`	SHOULD	Evidence references specific sections
`CONTRIB-014`	SHOULD	Conflicts propose resolution
`CONTRIB-015`	SHOULD	Low confidence includes uncertainty note

1.9.3 Integrity Validation

When checksum is present:

Compute SHA-256 hash of contribution (excluding _meta.checksum)
Truncate to first 16 hex characters
Compare with stored checksum
Validation MUST fail on mismatch

1.10 Examples

1.10.1 Minimal Valid Contribution

{
  "$schema": "https://cleo-dev.com/schemas/v1/contribution.schema.json",
  "_meta": {
    "contributionId": "contrib_a1b2c3d4",
    "createdAt": "2026-01-26T14:00:00Z",
    "agentId": "opus-1"
  },
  "sessionId": "session_20260126_140000_abc123",
  "epicId": "T2308",
  "taskId": "T2315",
  "markerLabel": "protocol-v2-contrib",
  "researchOutputs": [],
  "decisions": [
    {
      "questionId": "PROTO-001",
      "question": "Should contributions use JSON or YAML format?",
      "answer": "JSON with strict schema validation",
      "confidence": 0.95,
      "rationale": "JSON has better tooling support, stricter parsing, and native jq integration in CLEO.",
      "evidence": [
        {
          "file": "lib/validation.sh",
          "section": "validate_json_schema",
          "type": "code"
        }
      ]
    }
  ],
  "conflicts": [],
  "status": "draft"
}

1.10.2 Full Contribution with Conflict

{
  "$schema": "https://cleo-dev.com/schemas/v1/contribution.schema.json",
  "_meta": {
    "contributionId": "contrib_b2c3d4e5",
    "protocolVersion": "1.0.0",
    "createdAt": "2026-01-26T15:00:00Z",
    "completedAt": "2026-01-26T16:30:00Z",
    "agentId": "sonnet-2",
    "checksum": "a1b2c3d4e5f6g7h8",
    "consensusReady": true
  },
  "sessionId": "session_20260126_150000_def456",
  "sessionLabel": "Session B",
  "epicId": "T2204",
  "epicTitle": "RCSD Integration Research Consolidation",
  "taskId": "T2216",
  "markerLabel": "rcsd-consensus-contrib",
  "researchOutputs": [
    {
      "filePath": "claudedocs/agent-outputs/2026-01-26_rcsd-architecture-analysis.md",
      "researchId": "research_f1e2d3c4",
      "type": "analysis",
      "title": "RCSD Architecture Options Analysis",
      "createdAt": "2026-01-26T15:15:00Z",
      "linkedAt": "2026-01-26T15:20:00Z",
      "summary": "Comparative analysis of single-file vs split-file codebase map architectures"
    }
  ],
  "decisions": [
    {
      "questionId": "RCSD-001",
      "question": "Codebase Map Architecture: Single JSON file or split files?",
      "answer": "Single .cleo/codebase/codebase-map.json with internal sections for component types",
      "confidence": 0.85,
      "rationale": "Single file simplifies atomic updates and validation. Split files add merge complexity without proportional benefit at typical project sizes (<10K files).",
      "evidence": [
        {
          "file": "lib/file-ops.sh",
          "section": "atomic_write function",
          "line": 142,
          "quote": "Atomic pattern: temp -> validate -> backup -> rename",
          "type": "code"
        },
        {
          "file": "FILE-LOCKING" (see [FILE-LOCKING](./FILE-LOCKING)),
          "section": "Part 4: Atomic Operations",
          "type": "documentation"
        }
      ],
      "alternatives": [
        {
          "option": "Split into codebase-map-{type}.json per component type",
          "reason": "Adds merge complexity and potential race conditions without proportional benefit"
        },
        {
          "option": "SQLite database for codebase metadata",
          "reason": "Over-engineering for typical use case; violates JSON-first principle"
        }
      ]
    },
    {
      "questionId": "RCSD-002",
      "question": "Should codebase map include file content hashes?",
      "answer": "Yes, SHA-256 truncated to 16 hex characters for change detection",
      "confidence": 0.70,
      "rationale": "Content hashes enable efficient staleness detection without re-parsing. Truncation balances uniqueness with storage efficiency.",
      "evidence": [
        {
          "file": "schemas/contribution.schema.json",
          "section": "_meta.checksum",
          "line": 52,
          "type": "code"
        }
      ],
      "uncertaintyNote": "Performance impact at scale (>50K files) not yet validated"
    }
  ],
  "conflicts": [
    {
      "questionId": "RCSD-001",
      "conflictId": "conflict_c3d4e5f6",
      "severity": "high",
      "conflictType": "contradiction",
      "thisSession": {
        "position": "Single JSON file architecture",
        "confidence": 0.85,
        "evidence": [
          {
            "file": "lib/file-ops.sh",
            "section": "atomic_write function",
            "type": "code"
          }
        ]
      },
      "otherSession": {
        "sessionId": "session_20260126_120000_abc123",
        "sessionLabel": "Session A",
        "contributionId": "contrib_a1b2c3d4",
        "position": "Split files per component type (scripts.json, libs.json, tests.json)",
        "confidence": 0.75,
        "evidence": [
          {
            "file": "claudedocs/agent-outputs/2026-01-26_session-a-analysis.md",
            "section": "Architecture Recommendations",
            "type": "research"
          }
        ]
      },
      "rationale": "Session A prioritized parallel editing capability; this session prioritizes atomic consistency. Both are valid concerns with different tradeoffs.",
      "resolution": {
        "status": "proposed",
        "proposedBy": "sonnet-2",
        "proposedAt": "2026-01-26T16:00:00Z",
        "proposal": "Use single file with internal locking; add split-file mode as future config option for large repos",
        "resolutionType": "merge",
        "votes": []
      },
      "requiresConsensus": true,
      "escalatedToHITL": false
    }
  ],
  "baselineReference": {
    "sessionId": "session_20260126_120000_abc123",
    "sessionLabel": "Session A",
    "taskId": "T2215",
    "contributionId": "contrib_a1b2c3d4"
  },
  "status": "complete",
  "completionNote": "Full analysis complete. One high-severity conflict on architecture requiring consensus.",
  "validation": {
    "passed": true,
    "checkedAt": "2026-01-26T16:25:00Z",
    "results": [
      {
        "requirementId": "CONTRIB-001",
        "level": "MUST",
        "passed": true,
        "message": "Session ID matches active session",
        "checkedFields": ["sessionId"]
      },
      {
        "requirementId": "CONTRIB-007",
        "level": "MUST",
        "passed": true,
        "message": "All decisions include rationale and evidence",
        "checkedFields": ["decisions[*].rationale", "decisions[*].evidence"]
      }
    ]
  }
}

1.10.3 Low-Confidence Tentative Contribution

{
  "$schema": "https://cleo-dev.com/schemas/v1/contribution.schema.json",
  "_meta": {
    "contributionId": "contrib_d4e5f6g7",
    "createdAt": "2026-01-26T17:00:00Z",
    "agentId": "haiku-1",
    "consensusReady": false
  },
  "sessionId": "session_20260126_170000_ghi789",
  "epicId": "T2308",
  "taskId": "T2317",
  "markerLabel": "protocol-v2-explore",
  "researchOutputs": [],
  "decisions": [
    {
      "questionId": "PROTO-003",
      "question": "Should the protocol support nested decision dependencies?",
      "answer": "Tentatively yes, with depth limit of 3 levels",
      "confidence": 0.35,
      "rationale": "Nested dependencies could model complex decision chains, but add significant complexity. Limited exploration time prevents full analysis.",
      "evidence": [
        {
          "url": "https://example.com/decision-theory",
          "section": "Dependency Graphs",
          "type": "external"
        }
      ],
      "uncertaintyNote": "This is speculative. No implementation analysis performed. Confidence is low due to time constraints and lack of concrete use cases. SHOULD NOT be used for final design decisions without additional research."
    }
  ],
  "conflicts": [],
  "status": "draft"
}

1.11 Machine Processing Guidelines

1.11.1 Conflict Detection Algorithm

Automated conflict detection SHOULD follow this algorithm:

Load contributions with matching epicId and markerLabel
Group by questionId across all contributions
Compare answers:
- Exact string match: No conflict
- Semantic equivalence check: No conflict if equivalent
- Different answers: Potential conflict
Classify conflict type based on answer structure
Calculate severity based on confidence differential and question criticality
Generate conflict object with both positions and evidence

1.11.2 Consensus Aggregation

For each questionId:

Collect all decisions with that questionId
Group by normalized answer (semantic equivalence)

Calculate weighted support:

support[answer] = sum(confidence) for matching contributions
total_support = sum(all confidences)
percentage = support[answer] / total_support

Determine verdict:
- percentage >= 0.8: PROVEN (strong consensus)
- percentage >= 0.6: LIKELY (moderate consensus)
- percentage >= 0.4: CONTESTED (split decision)
- percentage < 0.4: MINORITY (insufficient support)

1.11.3 Query Patterns

Common query patterns for contribution data:

# Find all contributions for an epic
jq 'select(.epicId == "T2204")' contributions/*.json

# Extract decisions for a specific question
jq '.decisions[] | select(.questionId == "RCSD-001")' contributions/*.json

# Find high-severity conflicts
jq '.conflicts[] | select(.severity == "critical" or .severity == "high")' contributions/*.json

# Calculate average confidence for a decision
jq '[.decisions[] | select(.questionId == "RCSD-001") | .confidence] | add / length' contributions/*.json

Part 2: JSONL Manifest Specification

2.1 Purpose

The JSONL manifest provides:

Audit Trail: Immutable log of all contributions
Query Index: Efficient filtering by epic, session, status, agent
Conflict Aggregation: Quick identification of tasks needing consensus
Integrity Validation: Checksum verification for contribution files

2.2 Manifest Location

.cleo/contributions/CONTRIBUTIONS.jsonl

Directory Structure:

.cleo/contributions/
├── CONTRIBUTIONS.jsonl      # Append-only manifest
├── T2204.json              # Individual contribution files
├── T2205.json
└── archive/                # Completed epic contributions
    └── T1000/
        ├── CONTRIBUTIONS.jsonl
        └── *.json

2.3 Entry Structure

Each line is a self-contained JSON object (single-line, no trailing comma):

{
  "id": "contrib_a1b2c3d4",
  "sessionId": "session_20260126_091524_e716bd",
  "epicId": "T2308",
  "taskId": "T2310",
  "agentId": "opus-1",
  "status": "complete",
  "createdAt": "2026-01-26T17:15:00Z",
  "updatedAt": "2026-01-26T17:20:00Z",
  "decisionCount": 5,
  "conflictCount": 2,
  "filePath": ".cleo/contributions/T2310.json",
  "checksum": "a1b2c3d4"
}

2.4 Field Definitions

Field	Type	Required	Description
`id`	string	MUST	Unique identifier: `contrib_{uuid8}`
`sessionId`	string	MUST	Session that created this contribution
`epicId`	string	MUST	Parent epic task ID
`taskId`	string	MUST	Task this contribution addresses
`agentId`	string	MUST	Agent identifier (e.g., `opus-1`, `sonnet-2`)
`status`	enum	MUST	Contribution status (see 2.5)
`createdAt`	string	MUST	ISO-8601 creation timestamp
`updatedAt`	string	MUST	ISO-8601 last update timestamp
`decisionCount`	integer	MUST	Total decisions in contribution
`conflictCount`	integer	MUST	Decisions conflicting with existing
`filePath`	string	MUST	Relative path to contribution file
`checksum`	string	MUST	SHA-256 first 8 characters of file content

2.5 Status Enum

Status	Semantics	Next Action
`complete`	All decisions made, contribution finalized	Ready for consensus computation
`partial`	Some decisions pending, work in progress	Agent continues or handoff needed
`blocked`	Cannot proceed without external input	Requires HITL intervention

Status Transitions:

partial -> complete    # Agent finishes all decisions
partial -> blocked     # Agent encounters blocker
blocked -> partial     # HITL resolves, agent resumes
blocked -> complete    # HITL resolves directly

MUST NOT transition from complete to other states. If changes needed, create new contribution entry.

2.6 Operations

2.6.1 Append

Add entry when a contribution file is saved or updated.

# Append new entry (atomic operation)
echo '{"id":"contrib_x1y2z3w4",...}' >> .cleo/contributions/CONTRIBUTIONS.jsonl

MUST:

Compute checksum before appending
Use file locking or atomic append to prevent corruption
Validate JSON before appending

MUST NOT:

Modify existing entries (append-only)
Remove entries (use archival instead)

2.6.2 Query

Find contributions by various criteria using jq or equivalent JSON stream processor. All contributions for an epic:

jq -s '[.[] | select(.epicId == "T2308")]' .cleo/contributions/CONTRIBUTIONS.jsonl

Contributions with conflicts:

jq -s '[.[] | select(.conflictCount > 0)]' .cleo/contributions/CONTRIBUTIONS.jsonl

Latest contribution for a task:

jq -s '[.[] | select(.taskId == "T2310")] | sort_by(.updatedAt) | .[-1]' .cleo/contributions/CONTRIBUTIONS.jsonl

Contributions by agent:

jq -s '[.[] | select(.agentId == "opus-1")]' .cleo/contributions/CONTRIBUTIONS.jsonl

Pending contributions (partial or blocked):

jq -s '[.[] | select(.status != "complete")]' .cleo/contributions/CONTRIBUTIONS.jsonl

Contributions from a session:

jq -s '[.[] | select(.sessionId == "session_20260126_091524_e716bd")]' .cleo/contributions/CONTRIBUTIONS.jsonl

Summary statistics:

jq -s '{
  total: length,
  complete: [.[] | select(.status == "complete")] | length,
  partial: [.[] | select(.status == "partial")] | length,
  blocked: [.[] | select(.status == "blocked")] | length,
  totalConflicts: [.[].conflictCount] | add
}' .cleo/contributions/CONTRIBUTIONS.jsonl

2.6.3 Validate

Verify checksum matches contribution file content.

# Validate single entry
validate_contribution() {
    local entry="$1"
    local filepath=$(echo "$entry" | jq -r '.filePath')
    local expected=$(echo "$entry" | jq -r '.checksum')
    local actual=$(sha256sum "$filepath" | cut -c1-8)

    if [[ "$expected" == "$actual" ]]; then
        echo "VALID: $filepath"
        return 0
    else
        echo "INVALID: $filepath (expected: $expected, got: $actual)"
        return 1
    fi
}

# Validate all entries
jq -c '.[]' .cleo/contributions/CONTRIBUTIONS.jsonl | while read -r entry; do
    validate_contribution "$entry"
done

2.7 Integrity Rules

2.7.1 Append-Only Semantics

MUST:

Only append new entries to manifest
Never modify or delete existing entries
Create new entry for any contribution update (with new id, updated timestamps)

Rationale: Enables reliable audit trail and conflict detection across agents.

2.7.2 Checksum Validation

MUST:

Compute SHA-256 checksum of contribution file content
Store first 8 characters in manifest entry
Validate checksum before processing contribution

Checksum Computation:

sha256sum .cleo/contributions/T2310.json | cut -c1-8

Validation Failure Handling:

Log validation error
Mark contribution as potentially corrupted
Attempt recovery from backup if available
Require HITL intervention if unrecoverable

2.7.3 Archival Policy

When to Archive:

Epic marked complete
Contribution count exceeds threshold (configurable, default: 1000)
Manual archival request

Archival Process:

Create archive directory: .cleo/contributions/archive/{epicId}/
Move contribution files to archive
Filter manifest entries to archive manifest
Remove archived entries from active manifest (only operation that removes entries)

Archive Query:

# Search archived contributions
jq -s '[.[] | select(.taskId == "T1234")]' .cleo/contributions/archive/T1000/CONTRIBUTIONS.jsonl

2.8 Concurrency Handling

2.8.1 Multi-Agent Writes

Multiple agents may append to manifest simultaneously. MUST:

Use atomic append operations (single write syscall or file locking)
Generate unique id values (UUID-based)
Tolerate duplicate entries (idempotent processing)

Recommended Implementation:

# Atomic append with flock
(
    flock -x 200
    echo "$entry_json" >> .cleo/contributions/CONTRIBUTIONS.jsonl
) 200>.cleo/contributions/.manifest.lock

2.8.2 Read Consistency

SHOULD:

Read entire manifest before processing
Use -s (slurp) mode with jq for consistent view
Handle partial last line (truncated write)

2.9 Error Handling

Error	Detection	Recovery
Malformed JSON line	`jq` parse error	Skip line, log warning
Missing contribution file	`filePath` not found	Mark entry as orphaned
Checksum mismatch	Validation failure	Require HITL review
Duplicate `id`	Query returns multiple	Use latest by `updatedAt`

2.10 Example Manifest

{"id":"contrib_a1b2c3d4","sessionId":"session_20260126_091524_e716bd","epicId":"T2308","taskId":"T2309","agentId":"opus-1","status":"complete","createdAt":"2026-01-26T17:10:00Z","updatedAt":"2026-01-26T17:15:00Z","decisionCount":8,"conflictCount":0,"filePath":".cleo/contributions/T2309.json","checksum":"f1e2d3c4"}
{"id":"contrib_b2c3d4e5","sessionId":"session_20260126_091524_e716bd","epicId":"T2308","taskId":"T2310","agentId":"opus-2","status":"partial","createdAt":"2026-01-26T17:12:00Z","updatedAt":"2026-01-26T17:18:00Z","decisionCount":5,"conflictCount":2,"filePath":".cleo/contributions/T2310.json","checksum":"e2f3a4b5"}
{"id":"contrib_c3d4e5f6","sessionId":"session_20260126_092000_abc123","epicId":"T2308","taskId":"T2310","agentId":"opus-1","status":"complete","createdAt":"2026-01-26T17:20:00Z","updatedAt":"2026-01-26T17:25:00Z","decisionCount":7,"conflictCount":1,"filePath":".cleo/contributions/T2310.json","checksum":"d3e4f5a6"}

Note: Multiple entries for same taskId (T2310) represent contribution history. Latest entry (by updatedAt) reflects current state.

Part 3: Integration Points

3.1 Consensus Computation

Manifest provides input for consensus:

Query all complete contributions for epic
Group by taskId
Identify tasks with conflictCount > 0
Feed to consensus algorithm

3.2 Session Protocol

Contributions link to sessions via sessionId:

Session start: Initialize contribution tracking
Session end: Finalize pending contributions
Session resume: Load contributions for session scope

3.3 HITL Escalation

blocked status triggers HITL workflow:

Manifest query identifies blocked contributions
HITL resolves blocker
New contribution entry with resolved decisions

Document	Relationship
contribution.schema.json	AUTHORITATIVE for JSON Schema validation rules
CONSENSUS-FRAMEWORK-SPEC.md	Related: Consensus voting thresholds and evidence standards
SPEC-BIBLE-GUIDELINES.md	AUTHORITATIVE for specification document structure
LLM-AGENT-FIRST-SPEC.md	Related: Agent behavior standards for contributions
CONTRIBUTION-FORMAT-IMPLEMENTATION-REPORT.md	Tracks implementation status

Appendix A: JSON Schema for Manifest Entry

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cleo-dev.com/schemas/v1/contribution-manifest-entry.schema.json",
  "title": "Contribution Manifest Entry",
  "description": "Single entry in CONTRIBUTIONS.jsonl manifest",
  "type": "object",
  "required": [
    "id",
    "sessionId",
    "epicId",
    "taskId",
    "agentId",
    "status",
    "createdAt",
    "updatedAt",
    "decisionCount",
    "conflictCount",
    "filePath",
    "checksum"
  ],
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^contrib_[a-f0-9]{8}$",
      "description": "Unique contribution identifier"
    },
    "sessionId": {
      "type": "string",
      "pattern": "^session_\\d{8}_\\d{6}_[a-f0-9]{6}$",
      "description": "Session that created this contribution"
    },
    "epicId": {
      "type": "string",
      "pattern": "^T\\d{1,5}$",
      "description": "Parent epic task ID"
    },
    "taskId": {
      "type": "string",
      "pattern": "^T\\d{1,5}$",
      "description": "Task this contribution addresses"
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Agent identifier"
    },
    "status": {
      "type": "string",
      "enum": ["complete", "partial", "blocked"],
      "description": "Contribution status"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 creation timestamp"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 last update timestamp"
    },
    "decisionCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Total decisions in contribution"
    },
    "conflictCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Decisions conflicting with existing"
    },
    "filePath": {
      "type": "string",
      "pattern": "^\\.cleo/contributions/.*\\.json$",
      "description": "Relative path to contribution file"
    },
    "checksum": {
      "type": "string",
      "pattern": "^[a-f0-9]{8}$",
      "description": "SHA-256 first 8 characters"
    }
  }
}

Appendix B: CLI Integration

Future cleo commands for contribution management:

# List contributions
cleo contrib list --epic T2308
cleo contrib list --status blocked
cleo contrib list --agent opus-1

# Validate manifest
cleo contrib validate
cleo contrib validate --fix

# Archive completed epic
cleo contrib archive T2308

# Query statistics
cleo contrib stats --epic T2308

Appendix C: Changelog

Version	Date	Author	Changes
1.0.0	2026-01-26	T2309	Part 1: Contribution JSON format (decision objects, confidence scores, evidence references, conflict structure)
1.0.0	2026-01-26	T2310	Part 2: JSONL Manifest specification

End of Specification

Overview

System Architecture

RCSD-IVTR Protocol Stack

Protocol Definitions

Agent Protocols

Core Specifications

Strategic

MCP Server

Metrics & Validation

Protocol Enforcement

System Specifications

Feature Specifications

Release & Changelog

Schemas

Development Guides

Troubleshooting

​Contribution Format Specification

​Preamble

​Purpose

​Authority

​Design Philosophy

​RFC 2119 Conformance

​Overview

​Part 1: Contribution Format

​1.1 Top-Level Schema

​1.2 Metadata Object (_meta)

​1.3 Session Context Fields

​1.4 Decision Object Structure

​1.4.1 Decision Schema

​1.4.2 Decision Fields

​1.4.3 Confidence Score Semantics

​1.4.4 Answer Requirements

​1.5 Evidence Reference Structure

​1.5.1 Evidence Object Schema

​1.5.2 Evidence Fields

​1.5.3 Evidence Types

​1.5.4 Evidence Quality Requirements

​1.6 Conflict Structure

​1.6.1 Conflict Object Schema

​1.6.2 Conflict Fields

​1.6.3 Severity Levels

​1.6.4 Conflict Types

​1.6.5 Resolution Object

​1.7 Research Outputs

​1.8 Status Lifecycle

​1.9 Validation Requirements

​1.9.1 Schema Validation

​1.9.2 Semantic Validation

​1.9.3 Integrity Validation

​1.10 Examples

​1.10.1 Minimal Valid Contribution

​1.10.2 Full Contribution with Conflict

​1.10.3 Low-Confidence Tentative Contribution

​1.11 Machine Processing Guidelines

​1.11.1 Conflict Detection Algorithm

​1.11.2 Consensus Aggregation

​1.11.3 Query Patterns

​Part 2: JSONL Manifest Specification

​2.1 Purpose

​2.2 Manifest Location

​2.3 Entry Structure

​2.4 Field Definitions

​2.5 Status Enum

​2.6 Operations

​2.6.1 Append

​2.6.2 Query

​2.6.3 Validate

​2.7 Integrity Rules

​2.7.1 Append-Only Semantics

​2.7.2 Checksum Validation

​2.7.3 Archival Policy

​2.8 Concurrency Handling

​2.8.1 Multi-Agent Writes

​2.8.2 Read Consistency

​2.9 Error Handling

​2.10 Example Manifest

​Part 3: Integration Points

​3.1 Consensus Computation

​3.2 Session Protocol

​3.3 HITL Escalation

Contribution Format Specification

Preamble

Purpose

Authority

Design Philosophy

RFC 2119 Conformance

Overview

Part 1: Contribution Format

1.1 Top-Level Schema

1.2 Metadata Object (`_meta`)

1.3 Session Context Fields

1.4 Decision Object Structure

1.4.1 Decision Schema

1.4.2 Decision Fields

1.4.3 Confidence Score Semantics

1.4.4 Answer Requirements

1.5 Evidence Reference Structure

1.5.1 Evidence Object Schema

1.5.2 Evidence Fields

1.5.3 Evidence Types

1.5.4 Evidence Quality Requirements

1.6 Conflict Structure

1.6.1 Conflict Object Schema

1.6.2 Conflict Fields

1.6.3 Severity Levels

1.6.4 Conflict Types

1.6.5 Resolution Object

1.7 Research Outputs

1.8 Status Lifecycle

1.9 Validation Requirements

1.9.1 Schema Validation

1.9.2 Semantic Validation

1.9.3 Integrity Validation

1.10 Examples

1.10.1 Minimal Valid Contribution

1.10.2 Full Contribution with Conflict

1.10.3 Low-Confidence Tentative Contribution

1.11 Machine Processing Guidelines

1.11.1 Conflict Detection Algorithm

1.11.2 Consensus Aggregation

1.11.3 Query Patterns

Part 2: JSONL Manifest Specification

2.1 Purpose

2.2 Manifest Location

2.3 Entry Structure

2.4 Field Definitions

2.5 Status Enum

2.6 Operations

2.6.1 Append

2.6.2 Query

2.6.3 Validate

2.7 Integrity Rules

2.7.1 Append-Only Semantics

2.7.2 Checksum Validation

2.7.3 Archival Policy

2.8 Concurrency Handling

2.8.1 Multi-Agent Writes

2.8.2 Read Consistency

2.9 Error Handling

2.10 Example Manifest

Part 3: Integration Points

3.1 Consensus Computation

3.2 Session Protocol

3.3 HITL Escalation

Related Specifications

Appendix A: JSON Schema for Manifest Entry

Appendix B: CLI Integration

Appendix C: Changelog