ct-consensus-voter

Consensus Voter

Overview

Runs a structured vote across two or more agents on a decision question, records confidence and rationale per option, and emits a voting matrix that the rest of the pipeline can read. The skill enforces a configurable consensus threshold, detects contested verdicts, and escalates to HITL when evidence is insufficient.

Core Principle

Consensus requires evidence, rationale, and a threshold. Without all three, escalate.

Immutable Constraints

Voting Matrix Schema

Every consensus run produces a single JSON document that matches this shape:

{
  "questionId": "CONS-0042",
  "question": "Which ORM should the monorepo standardize on?",
  "options": [
    {
      "name": "drizzle-v1-beta",
      "confidence": 0.82,
      "rationale": "defineRelations unblocks the cascade query",
      "evidence": [
        { "file": "drizzle-release-notes.md", "section": "v1.0.0-beta", "type": "doc" },
        { "file": "packages/core/src/orchestration/protocol-validators.ts", "section": "validateArchitectureDecisionProtocol", "type": "code" }
      ]
    },
    {
      "name": "kysely",
      "confidence": 0.41,
      "rationale": "cleaner long-term abstraction but invalidates migrations",
      "evidence": [
        { "file": "kysely-docs.md", "section": "migrations", "type": "doc" }
      ]
    }
  ],
  "threshold": 0.5,
  "verdict": "PROVEN",
  "actualConsensus": 0.82,
  "conflicts": []
}

The full schema, including rarer verdicts and conflict records, is in references/matrix-examples.md.

Scoring Rules

Verdicts

Conflict Detection

A conflict exists when two options have confidence within 0.1 of each other and their rationales are mutually exclusive. The skill MUST record conflicts in the matrix:

{
  "conflicts": [
    {
      "conflictId": "c-0042-01",
      "severity": "high",
      "conflictType": "contradiction",
      "positions": [
        { "option": "drizzle-v1-beta", "confidence": 0.82 },
        { "option": "kysely", "confidence": 0.79 }
      ],
      "resolution": { "status": "pending", "resolutionType": "escalate" }
    }
  ]
}

Conflicts with severity: critical always escalate, regardless of top-option confidence. Severity is assigned by the skill based on the blast radius of each option (e.g., reversible tool choice = low; irreversible schema migration = high; security-impacting = critical).

HITL Escalation

The skill MUST escalate when:

1. Top option confidence < threshold.
2. Any conflict has severity: critical.
3. Top two options differ by less than 0.1 (contested).
4. Fewer than 2 options have evidence records.

On escalation:

1. Write the matrix to disk with verdict: CONTESTED or verdict: INSUFFICIENT_EVIDENCE.
2. Record the manifest entry with agent_type: "analysis" and verdict populated.
3. Exit with code 65 (HANDOFF_REQUIRED).
4. Do not attempt to re-run the vote in the same session.

Integration

Validate the matrix through cleo check protocol:

cleo check protocol \
  --protocolType consensus \
  --votingMatrixFile ./.cleo/rcasd/T4797/consensus/T4797-consensus.json \
  --taskId T4797

Exit code 0 = matrix is valid and verdict is PROVEN or REFUTED. Exit code 65 = HANDOFF_REQUIRED (contested or insufficient evidence). Exit code 61 = E_PROTOCOL_CONSENSUS (matrix shape is invalid).

This skill typically hands off to ct-adr-recorder on a PROVEN verdict so the decision can be formalized.

Anti-Patterns

Critical Rules Summary

1. Every vote MUST produce a voting matrix with at least 2 options.
2. Every option MUST carry confidence, rationale, and at least one evidence record.
3. The threshold is a hard gate; below it, escalate to HITL with exit 65.
4. Conflicts within 0.1 confidence MUST be flagged as CONTESTED.
5. Critical-severity conflicts always escalate, regardless of top-option confidence.
6. Manifest entry MUST set agent_type: "analysis" and include the verdict.
7. On PROVEN, hand off to ct-adr-recorder; on CONTESTED or INSUFFICIENT_EVIDENCE, hand off to HITL.
8. Always validate via cleo check protocol --protocolType consensus.

See also / References

This skill binds to the consensus LOOM lifecycle stage. Governing ADRs:

• ADR-015 — multi-contributor architecture — defines the consensus framework that this skill implements.
• ADR-023 — protocol validation dispatch — defines how consensus output is validated before downstream stages consume it.

LOOM coverage matrix: docs/skills/loom-coverage-matrix.md.