@cleocode/cleo 2026.3.2 → 2026.3.6

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

@@ -1,309 +0,0 @@
-# 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

@@ -1,375 +0,0 @@
-# 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*