@cleocode/cleo 2026.2.5 → 2026.2.6

package/packages/ct-skills/protocols/consensus.md

@@ -0,0 +1,309 @@
+# Consensus Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Decision Making | "vote", "decide", "choose", "select" | Multi-option choice |
+| Agreement | "consensus", "agree", "alignment" | Stakeholder coordination |
+| Conflict Resolution | "resolve", "dispute", "conflict" | Opposing positions |
+| Validation | "validate claim", "verify assertion" | Evidence-based judgment |
+
+**Explicit Override**: `--protocol consensus` flag on task creation.
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| CONS-001 | MUST use structured voting format |
+| CONS-002 | MUST document rationale for each position |
+| CONS-003 | MUST include confidence scores (0.0-1.0) |
+| CONS-004 | MUST cite evidence supporting positions |
+| CONS-005 | MUST flag conflicts with severity levels |
+| CONS-006 | MUST escalate to HITL when threshold not reached |
+| CONS-007 | MUST set `agent_type: "analysis"` in manifest |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| CONS-010 | SHOULD present multiple perspectives |
+| CONS-011 | SHOULD identify hidden assumptions |
+| CONS-012 | SHOULD document rejected alternatives |
+| CONS-013 | SHOULD include uncertainty notes for low confidence |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| CONS-020 | MAY propose compromise positions |
+| CONS-021 | MAY defer non-critical decisions |
+| CONS-022 | MAY request additional research |
+
+---
+
+## Output Format
+
+### Voting Structure
+
+```json
+{
+  "questionId": "CONS-001",
+  "question": "Decision question being answered",
+  "options": [
+    {
+      "option": "Option A description",
+      "vote": "accept|reject|abstain",
+      "confidence": 0.85,
+      "rationale": "Why this position",
+      "evidence": [{"file": "path", "section": "name", "type": "code"}]
+    }
+  ],
+  "verdict": "PROVEN|REFUTED|CONTESTED|INSUFFICIENT_EVIDENCE",
+  "consensusThreshold": 0.8,
+  "actualConsensus": 0.75
+}
+```
+
+### Verdict Thresholds
+
+| Verdict | Threshold | Evidence Requirement |
+|---------|-----------|---------------------|
+| **PROVEN** | 3/5 agents OR 50%+ weighted confidence | Reproducible evidence |
+| **REFUTED** | Counter-evidence invalidates | Counter-proof exists |
+| **CONTESTED** | 3/5 split after 2 challenge rounds | Document both sides |
+| **INSUFFICIENT_EVIDENCE** | Cannot reach verdict | Request investigation |
+
+### Conflict Structure
+
+```json
+{
+  "conflictId": "conflict_a1b2c3d4",
+  "severity": "critical|high|medium|low",
+  "conflictType": "contradiction|partial-overlap|scope-difference|priority-difference",
+  "positions": [
+    {"agentId": "opus-1", "position": "Position A", "confidence": 0.85},
+    {"agentId": "sonnet-1", "position": "Position B", "confidence": 0.75}
+  ],
+  "resolution": {
+    "status": "pending|proposed|accepted|rejected",
+    "resolutionType": "merge|choose-a|choose-b|new|defer|escalate"
+  }
+}
+```
+
+### File Output
+
+```markdown
+# Consensus Report: {Decision Title}
+
+**Task**: T####
+**Date**: YYYY-MM-DD
+**Status**: complete|partial|blocked
+**Agent Type**: analysis
+
+---
+
+## Decision Question
+
+{Clear statement of what needs to be decided}
+
+## Options Evaluated
+
+### Option A: {Name}
+
+**Confidence**: X.XX
+**Rationale**: {Why this option}
+**Evidence**: {Citations}
+**Pros**: {Advantages}
+**Cons**: {Disadvantages}
+
+### Option B: {Name}
+
+{Same structure}
+
+## Voting Matrix
+
+| Agent | Option A | Option B | Confidence | Notes |
+|-------|----------|----------|------------|-------|
+| opus-1 | Accept | - | 0.85 | {Rationale} |
+| sonnet-1 | - | Accept | 0.70 | {Rationale} |
+
+## Verdict
+
+**Result**: {PROVEN|REFUTED|CONTESTED|INSUFFICIENT_EVIDENCE}
+**Consensus**: {X}% weighted agreement
+**Recommendation**: {Final recommendation}
+
+## Conflicts
+
+{If any conflicts exist}
+
+## Next Steps
+
+1. {Action item}
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Consensus: Decision Title" \
+  --file "YYYY-MM-DD_consensus.md" \
+  --topics "consensus,decision" \
+  --findings "Verdict reached,Option A selected,80% confidence" \
+  --status complete \
+  --task T#### \
+  --actionable \
+  --agent-type analysis
+```
+
+---
+
+## Integration Points
+
+### Base Protocol
+
+- Inherits task lifecycle (start, execute, complete)
+- Inherits manifest append requirement
+- Inherits error handling patterns
+
+### Protocol Interactions
+
+| Combined With | Behavior |
+|---------------|----------|
+| research | Research provides evidence for voting |
+| specification | Consensus resolves spec ambiguities |
+| contribution | Consensus validates contributions |
+
+### HITL Escalation
+
+| Condition | Action |
+|-----------|--------|
+| Contested verdict (3/5 split) | Present conflict to user |
+| Critical severity conflict | Immediate escalation |
+| Insufficient evidence | Request user guidance |
+| Unanimous suspicious consensus | Verify with user |
+
+---
+
+## Example
+
+**Task**: Decide on codebase map architecture
+
+**Manifest Entry Command**:
+```bash
+cleo research add \
+  --title "Consensus: Codebase Map Architecture" \
+  --file "2026-01-26_arch-consensus.md" \
+  --topics "architecture,consensus,codebase-map" \
+  --findings "Single file selected over split,4/5 agents agree,Atomic operations priority" \
+  --status complete \
+  --task T2216 \
+  --epic T2204 \
+  --actionable \
+  --needs-followup T2217 \
+  --agent-type analysis
+```
+
+---
+
+## Integration
+
+### Implementation Location
+
+**Library**: `lib/contribution-protocol.sh`
+
+**Primary Function**: `contribution_compute_consensus(epic_id, [manifest_path])`
+- Loads complete contributions for epic
+- Groups decisions by question ID across contributions
+- Runs weighted voting per question
+- Classifies: unanimous/majority = resolved, split = unresolved
+- Flags unresolved questions for HITL review
+
+**Supporting Functions**:
+- `contribution_weighted_vote(votes_json)` - Calculates weighted consensus
+- `contribution_create_synthesis(consensus_json, epic_id)` - Creates Markdown synthesis
+
+### CLI Usage
+
+**Note**: No dedicated `cleo consensus` command exists yet. Consensus computation is invoked programmatically through the contribution workflow.
+
+**Programmatic Usage**:
+```bash
+source lib/contribution-protocol.sh
+
+# Compute consensus for an epic
+consensus=$(contribution_compute_consensus "T2679")
+
+# Extract resolved/unresolved questions
+resolved=$(echo "$consensus" | jq '.resolvedQuestions')
+unresolved=$(echo "$consensus" | jq '.unresolvedQuestions')
+```
+
+### Orchestrator Integration
+
+**Spawn Context**: When spawning consensus agents via orchestrator:
+
+```bash
+# Orchestrator detects consensus protocol from task labels
+protocol_type=$(_osp_skill_to_protocol "ct-validator")  # Returns "consensus"
+
+# Validates consensus requirements before spawn
+validate_consensus_protocol "$task_id" "$manifest_entry" "$voting_matrix" "false"
+
+# Blocks spawn if:
+# - Voting matrix has <2 options (CONS-001)
+# - Confidence scores invalid (CONS-003)
+# - Top confidence below 50% threshold (CONS-004)
+# - agent_type not "analysis" (CONS-007)
+```
+
+**Exit Codes**:
+- `EXIT_PROTOCOL_CONSENSUS` (61) - Consensus protocol violation
+- `EXIT_PROTOCOL_GENERIC` (67) - Generic protocol error
+
+### Validation Hook
+
+**Function**: `validate_consensus_protocol(task_id, manifest_entry, voting_matrix, strict)`
+
+**Location**: `lib/protocol-validation.sh`
+
+**Validates**:
+- CONS-001: ≥2 options in voting matrix
+- CONS-003: Confidence scores 0.0-1.0
+- CONS-004: Top confidence ≥50% threshold
+- CONS-007: agent_type = "analysis"
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why Avoid |
+|---------|-----------|
+| Accepting unanimous consensus without scrutiny | May indicate groupthink |
+| Skipping evidence citations | Decisions lack foundation |
+| Binary voting without confidence | Loses nuance |
+| Ignoring minority positions | May miss valid concerns |
+| Premature escalation | Wastes human attention |
+
+---
+
+*Protocol Version 1.0.0 - Consensus Protocol*

package/packages/ct-skills/protocols/contribution.md

@@ -0,0 +1,375 @@
+# Contribution Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.1.1
+**Type**: Cross-Cutting Protocol
+**Applies To**: All RCSD-IVTR stages
+**Max Active**: 3 protocols (including base)
+
+> **Cross-Cutting Nature**: This protocol applies across ALL stages of RCSD-IVTR.
+> Unlike stage-specific protocols (research, consensus, etc.), contribution
+> tracking is active whenever multi-agent coordination or attribution is needed.
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Shared File Modification | Modifying CLAUDE.md, AGENTS.md, shared configs | Multi-session files |
+| PR Creation | "pull request", "PR", "merge request" | Code review workflow |
+| Cross-Session Work | Multiple agents on same epic | Coordination needed |
+| Audit Trail | Provenance, attribution, tracking | Accountability |
+
+**Explicit Override**: `--protocol contribution` flag on task creation.
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| CONT-001 | MUST follow commit message conventions |
+| CONT-002 | MUST include provenance tags in code comments |
+| CONT-003 | MUST pass all validation gates before merge |
+| CONT-004 | MUST document decisions with rationale |
+| CONT-005 | MUST flag conflicts with other sessions |
+| CONT-006 | MUST write contribution record to manifest |
+| CONT-007 | MUST set `agent_type: "implementation"` in manifest |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| CONT-010 | SHOULD include test coverage for changes |
+| CONT-011 | SHOULD link to related tasks and research |
+| CONT-012 | SHOULD document rejected alternatives |
+| CONT-013 | SHOULD request review for significant changes |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| CONT-020 | MAY batch related changes into single contribution |
+| CONT-021 | MAY defer documentation updates |
+| CONT-022 | MAY propose follow-up improvements |
+
+---
+
+## Output Format
+
+### Commit Message Format
+
+```
+<type>(<scope>): <summary>
+
+<body>
+
+<footer>
+
+Co-Authored-By: <agent-id> <noreply@anthropic.com>
+Task: T####
+Session: session_YYYYMMDD_HHMMSS_######
+```
+
+**Types**: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `perf`
+
+### Provenance Tag Format
+
+```javascript
+/**
+ * @task T####
+ * @session session_YYYYMMDD_HHMMSS_######
+ * @agent opus-1
+ * @date YYYY-MM-DD
+ */
+```
+
+```bash
+# Task: T####
+# Session: session_YYYYMMDD_HHMMSS_######
+# Agent: opus-1
+```
+
+### Contribution Record
+
+```json
+{
+  "$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": "feature-contrib",
+  "decisions": [
+    {
+      "questionId": "IMPL-001",
+      "question": "Decision made during implementation",
+      "answer": "Concrete decision value",
+      "confidence": 0.85,
+      "rationale": "Why this decision",
+      "evidence": [{"file": "path", "section": "name", "type": "code"}]
+    }
+  ],
+  "conflicts": [],
+  "status": "complete"
+}
+```
+
+### Validation Gates
+
+| Gate | Check | Required |
+|------|-------|----------|
+| Schema | JSON Schema validation | MUST pass |
+| Tests | All tests pass | MUST pass |
+| Lint | Code style compliance | SHOULD pass |
+| Security | No secrets committed | MUST pass |
+| Conflicts | No unresolved conflicts | MUST resolve |
+
+### File Output
+
+```markdown
+# Contribution: {Title}
+
+**Task**: T####
+**Date**: YYYY-MM-DD
+**Status**: complete|partial|blocked
+**Agent Type**: implementation
+
+---
+
+## Summary
+
+{2-3 sentence summary of contribution}
+
+## Changes
+
+### Files Modified
+
+| File | Type | Lines Changed |
+|------|------|---------------|
+| {path} | {added|modified|deleted} | +X/-Y |
+
+### Decisions Made
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| IMPL-001 | {Decision} | {Why} |
+
+## Validation Results
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| Tests | Pass | All 42 tests pass |
+| Lint | Pass | No warnings |
+| Schema | Pass | Valid JSON |
+
+## Conflicts
+
+{If any, document with resolution}
+
+## Review Checklist
+
+- [ ] Code follows style guide
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented)
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Contribution: Feature Name" \
+  --file "YYYY-MM-DD_contribution.md" \
+  --topics "contribution,feature" \
+  --findings "3 files modified,Tests passing,No conflicts" \
+  --status complete \
+  --task T#### \
+  --not-actionable \
+  --agent-type implementation
+```
+
+---
+
+## Implementation Integration
+
+### Automatic Tracking
+
+**Status**: Not yet implemented
+
+**Planned**: Integrate with `cleo complete` to automatically track contributions
+- Detect PR/merge commits in task completion
+- Extract contribution metadata from commit messages
+- Append to `.cleo/contributions/CONTRIBUTIONS.jsonl`
+- Link contribution to completed task
+
+**Future CLI**:
+```bash
+cleo complete T1234  # Auto-detects contribution if task has linked PR
+```
+
+### Manual Tracking
+
+**Status**: Not yet implemented
+
+**Planned**: Dedicated contribution tracking command
+
+**Future CLI**:
+```bash
+cleo contribution track --task T1234 --pr-number 456
+cleo contribution list --epic T2000
+cleo contribution show T1234-contrib
+```
+
+### Implementation Location
+
+**Library**: `lib/contribution-protocol.sh`
+
+**Key Functions** (for future integration):
+- `contribution_create()` - Record contribution metadata
+- `contribution_track_from_task()` - Extract contribution from task
+- `contribution_validate()` - Validate contribution structure
+- `contribution_compute_consensus()` - Compute consensus from contributions
+
+### Current State
+
+Contribution protocol is **specification-only** (no enforcement yet). Implementation tracking requires:
+1. Git integration for PR detection
+2. Contribution manifest system
+3. CLI commands for manual tracking
+4. Orchestrator integration for multi-agent contributions
+
+**Validation**: See `validate_contribution_protocol()` in `lib/protocol-validation.sh`
+- CONT-002: Provenance tags required
+- CONT-003: Tests must pass
+- CONT-007: agent_type = "implementation"
+- Exit code: `EXIT_PROTOCOL_CONTRIBUTION` (65)
+
+---
+
+## Integration Points
+
+### Base Protocol
+
+- Inherits task lifecycle (start, execute, complete)
+- Inherits manifest append requirement
+- Inherits error handling patterns
+
+### Protocol Interactions
+
+| Combined With | Behavior |
+|---------------|----------|
+| implementation | Contribution tracks implementation work |
+| consensus | Consensus resolves contribution conflicts |
+| release | Contribution records feed release notes |
+
+### Conflict Detection
+
+| Conflict Type | Detection | Resolution |
+|---------------|-----------|------------|
+| Same file edit | File path collision | Merge or choose |
+| Semantic conflict | Decision contradiction | Consensus protocol |
+| Dependency conflict | Breaking change | Escalate to HITL |
+
+---
+
+## Example
+
+**Task**: Implement session binding for multi-agent support
+
+**Commit**:
+```
+feat(session): Add session binding for multi-agent support
+
+Implements session isolation per agent with TTY binding
+for terminal-based sessions and env var fallback for
+headless operations.
+
+- Add session binding file management
+- Implement CLEO_SESSION env var support
+- Add session switch command
+
+Co-Authored-By: opus-1 <noreply@anthropic.com>
+Task: T2315
+Session: session_20260126_140000_abc123
+```
+
+**Manifest Entry**:
+```json
+{"id":"T2315-session-binding","file":"2026-01-26_session-binding.md","title":"Contribution: Session Binding","date":"2026-01-26","status":"complete","agent_type":"implementation","topics":["session","multi-agent","binding"],"key_findings":["TTY binding implemented","Env var fallback added","4 new tests"],"actionable":false,"needs_followup":[],"linked_tasks":["T2315","T2308"]}
+```
+
+---
+
+## Provenance Validation
+
+### Overview
+
+Contribution protocol inherits provenance requirements from implementation protocol (IMPL-003), with identical enforcement mechanisms.
+
+**Requirement**: CONT-002 = IMPL-003 (Provenance tags required)
+
+### Pre-Commit Hook
+
+Same as Implementation Protocol:
+- Extract @task tags from commit diff
+- Calculate provenance coverage: 100% new, 80% existing, 50% legacy
+- Block commit if thresholds not met
+- Exit code: `EXIT_PROTOCOL_CONTRIBUTION` (65)
+
+### Runtime Validation
+
+**Current**: Available via `validate_contribution_protocol()` in `lib/protocol-validation.sh`
+
+**Planned CLI**: `cleo contribution validate [--task TASK_ID]`
+
+**Checks**:
+- CONT-002: Provenance tags present
+- CONT-003: Tests pass
+- CONT-007: agent_type = "implementation"
+
+### Shared Thresholds
+
+Identical to implementation protocol:
+
+| Code Category | Provenance Requirement |
+|---------------|------------------------|
+| New code | 100% |
+| Existing code | 80% |
+| Legacy code | 50% |
+
+### Enforcement Points
+
+1. **Pre-commit**: Shared with implementation protocol
+2. **Pre-merge**: PR validation checks provenance
+3. **Runtime**: `cleo complete` validates contribution tasks
+4. **Orchestrator**: Validates before spawning contribution agents
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why Avoid |
+|---------|-----------|
+| Committing without provenance | Breaks audit trail |
+| Skipping validation gates | Quality regression |
+| Ignoring conflicts | Creates merge debt |
+| Large unfocused commits | Hard to review/revert |
+| Missing decision documentation | Lost context |
+
+---
+
+*Protocol Version 1.0.0 - Contribution Protocol*