@cleocode/skills 2026.4.5 → 2026.4.7

package/skills/ct-artifact-publisher/references/artifact-types.md

@@ -0,0 +1,126 @@
+# Per-Artifact-Type Notes
+
+Detailed notes for each of the nine registered artifact types. Read the entry for the type you are shipping.
+
+## npm-package
+
+**Registry**: `https://registry.npmjs.org` (default) or a private registry.
+**Auth**: `NPM_TOKEN` env var, or OIDC trusted publishing in CI.
+**Default publish command**: `npm publish`
+**Version source**: `package.json:version`
+**Idempotency**: errors on duplicate version.
+
+### Edge cases
+
+- **Scoped packages**: `@scope/pkg` requires `--access public` to publish publicly.
+- **Provenance flag**: set `options.provenance: true` to emit SLSA L3 attestation via OIDC.
+- **Monorepo**: each workspace member is a separate artifact entry; order them by dependency chain (leaves first).
+- **Unpublish**: allowed within 72 hours, then rejected by registry policy.
+- **Dry-run**: `npm publish --dry-run` produces the tarball without pushing.
+
+## python-wheel
+
+**Registry**: `https://upload.pypi.org/legacy/` (default) or private.
+**Auth**: `TWINE_USERNAME=__token__`, `TWINE_PASSWORD=<pypi-api-token>`.
+**Default build**: `python -m build`
+**Default publish**: `twine upload dist/*`
+**Version source**: `pyproject.toml:project.version`
+
+### Edge cases
+
+- **Build backend**: `setuptools`, `hatchling`, `poetry`, `pdm` — all emit wheels into `dist/` but may differ on metadata. Validate the wheel with `twine check dist/*.whl` before upload.
+- **No unpublish**: PyPI does not allow unpublish. Yank via admin console only.
+- **Dry-run**: `twine upload --repository testpypi` is the de-facto dry-run target.
+
+## python-sdist
+
+Same registry/auth as python-wheel. Build command is `python -m build --sdist`. Produces `.tar.gz` source distributions. Usually shipped alongside a wheel, not standalone.
+
+## go-module
+
+**Registry**: `proxy.golang.org` (immutable).
+**Auth**: None — proxy publishes on git tag push.
+**Default build**: `go mod tidy`
+**Default publish**: tag push triggers the proxy.
+**Version source**: `go.mod:module` + git tag.
+
+### Edge cases
+
+- **Immutable**: once a version is cached by the proxy, it cannot be changed or removed.
+- **Retraction**: add a `retract` directive in `go.mod` for versions to flag as bad.
+- **Module path**: must match the repo URL; a rename requires a new module path.
+- **Major versions ≥ 2**: require the major suffix in the module path (`.../v2`).
+
+## cargo-crate
+
+**Registry**: `crates.io` (default).
+**Auth**: `CARGO_REGISTRY_TOKEN` env var.
+**Default build**: `cargo build --release`
+**Default publish**: `cargo publish`
+**Version source**: `Cargo.toml:package.version`
+
+### Edge cases
+
+- **Workspaces**: each publishable crate is a separate entry; order by dependency.
+- **`cargo publish --dry-run`**: required by ARTP-002; the skill MUST run this first.
+- **Yank**: `cargo yank --vers <version>` flags a version as unbuildable; no true unpublish.
+- **Rate limits**: crates.io throttles publishes; back off on 429.
+
+## ruby-gem
+
+**Registry**: `rubygems.org` (default).
+**Auth**: `GEM_HOST_API_KEY` env var.
+**Default build**: `gem build *.gemspec`
+**Default publish**: `gem push *.gem`
+**Version source**: `*.gemspec:version`
+
+### Edge cases
+
+- **Yank**: `gem yank <gem> -v <version>` removes from index (soft delete).
+- **Dry-run**: no native dry-run for `gem push`; simulate by building only.
+- **Signing**: RubyGems supports `--sign` with a cert; configure via the gemspec.
+
+## docker-image
+
+**Registry**: configurable — Docker Hub, GHCR, ECR, etc.
+**Auth**: `docker login` session, or OIDC federation for GHCR.
+**Default build**: `docker build -t <registry>:<tag> .`
+**Default publish**: `docker push <registry>:<tag>`
+**Version source**: tag string (not a manifest field).
+
+### Edge cases
+
+- **Multi-arch**: use `docker buildx` with `--platform linux/amd64,linux/arm64` and `--push` in one step.
+- **Digest**: `docker inspect --format='{{.Id}}' <image>` gives the content-addressed digest.
+- **Cosign signing**: delegate to ct-provenance-keeper; cosign keyless signs the image by digest.
+- **Overwrites**: Docker pushes silently overwrite the same tag; rely on digest tracking for integrity.
+- **Dry-run**: no native dry-run; `docker buildx build` without `--push` is the closest equivalent.
+
+## github-release
+
+**Registry**: `github.com/<owner>/<repo>/releases/<tag>`.
+**Auth**: `GITHUB_TOKEN` env var or OIDC.
+**Default build**: (none; artifacts are uploaded from disk)
+**Default publish**: `gh release create <tag> <files>`
+**Version source**: git tag.
+
+### Edge cases
+
+- **Idempotency**: errors if the tag already has a release unless `--discussion-category` or similar flags are used.
+- **Deletion**: `gh release delete <tag>` is a full rollback.
+- **Body**: pulled from the changelog section for the release version; include checksums in the body.
+- **Assets**: each uploaded file produces a separate downloadable URL.
+
+## generic-tarball
+
+**Registry**: configurable — any HTTP target or object store.
+**Auth**: custom per target.
+**Default build**: `tar czf <output> --exclude=.git .`
+**Default publish**: custom; the handler MUST provide one.
+**Version source**: computed from the release version, not from a manifest.
+
+### Edge cases
+
+- **Reproducibility**: set `--sort=name --owner=0 --group=0 --mtime='UTC 2020-01-01'` for deterministic tarballs.
+- **Exclude list**: always exclude `.git`, `node_modules`, `target`, `dist` (unless that's the payload), and any secret-bearing files.
+- **Checksum file**: emit `checksums.txt` alongside the tarball for distribution verification.

package/skills/ct-artifact-publisher/references/handler-interface.md

@@ -0,0 +1,187 @@
+# Handler Interface Pseudocode
+
+Every artifact handler is a triple of Bash functions with a strict contract. This file shows the interface and a full pseudocode example for implementing a new handler.
+
+## The Contract
+
+```bash
+{prefix}_validate(artifact_config_json) -> exit 0 | 1
+{prefix}_build(artifact_config_json, dry_run) -> exit 0 | 1
+{prefix}_publish(artifact_config_json, dry_run) -> exit 0 | 1
+```
+
+- `artifact_config_json` is a single entry from `release.artifacts[]`, passed as a JSON string.
+- `dry_run` is the literal string `"true"` or `"false"`.
+- All three functions return 0 on success, non-zero on failure.
+- None of the three MAY print credentials, write credentials to files, or pass credentials via command-line arguments.
+
+## Required Behavior
+
+### validate
+
+- Parse the config JSON.
+- Confirm every required tool is available on PATH (`command -v <tool>`).
+- Confirm the package manifest exists (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.).
+- Confirm the version in the manifest matches the release version.
+- Confirm credentials declared as required are present in the environment.
+- Return 0 if all checks pass, 1 otherwise.
+
+### build
+
+- Parse the config JSON.
+- If `dry_run == "true"`, log the build command and return 0 without running it.
+- Otherwise, run the build command and capture stdout/stderr.
+- Verify the expected output location exists and is non-empty.
+- Compute SHA-256 checksum of every output file and emit it to `stdout` in `<sha256>  <filename>` format.
+- Return 0 on success.
+
+### publish
+
+- Parse the config JSON.
+- If `dry_run == "true"`, log the publish command and return 0.
+- Otherwise, verify credentials are present in the environment.
+- Run the publish command.
+- Capture the registry response (URL, digest, published timestamp).
+- Emit the response as JSON on stdout for the pipeline to capture.
+- Return 0 on success.
+
+## Full Pseudocode Example: `my_custom` handler
+
+```bash
+# Example: publishing a custom tarball to a private registry.
+
+my_custom_validate() {
+    local config="$1"
+    local version
+    version=$(echo "$config" | jq -r '.version // empty')
+
+    # Tool availability
+    if ! command -v tar > /dev/null; then
+        echo "ERROR: tar not found on PATH" >&2
+        return 1
+    fi
+
+    if ! command -v curl > /dev/null; then
+        echo "ERROR: curl not found on PATH" >&2
+        return 1
+    fi
+
+    # Config shape
+    if [[ -z "$version" ]]; then
+        echo "ERROR: config missing .version" >&2
+        return 1
+    fi
+
+    local registry
+    registry=$(echo "$config" | jq -r '.registry // empty')
+    if [[ -z "$registry" ]]; then
+        echo "ERROR: config missing .registry" >&2
+        return 1
+    fi
+
+    # Credential check (env var name only; never echo the value)
+    local env_var
+    env_var=$(echo "$config" | jq -r '.credentials.envVar // empty')
+    if [[ -n "$env_var" ]] && [[ -z "${!env_var:-}" ]]; then
+        echo "ERROR: credential env var $env_var not set" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+my_custom_build() {
+    local config="$1"
+    local dry_run="$2"
+    local version
+    version=$(echo "$config" | jq -r '.version')
+    local output="build/my-project-${version}.tar.gz"
+
+    if [[ "$dry_run" == "true" ]]; then
+        echo "[dry-run] would run: tar czf $output --exclude=.git ."
+        return 0
+    fi
+
+    tar czf "$output" --exclude=.git --exclude=node_modules . || return 1
+
+    if [[ ! -s "$output" ]]; then
+        echo "ERROR: build output missing or empty: $output" >&2
+        return 1
+    fi
+
+    # Emit checksum for the pipeline to capture.
+    local digest
+    digest=$(sha256sum "$output" | awk '{print $1}')
+    echo "${digest}  ${output}"
+
+    return 0
+}
+
+my_custom_publish() {
+    local config="$1"
+    local dry_run="$2"
+    local version
+    version=$(echo "$config" | jq -r '.version')
+    local registry
+    registry=$(echo "$config" | jq -r '.registry')
+    local env_var
+    env_var=$(echo "$config" | jq -r '.credentials.envVar')
+    local output="build/my-project-${version}.tar.gz"
+
+    if [[ "$dry_run" == "true" ]]; then
+        echo "[dry-run] would POST $output to $registry"
+        return 0
+    fi
+
+    # NEVER echo or log the credential value itself.
+    if [[ -z "${!env_var:-}" ]]; then
+        echo "ERROR: credential env var $env_var is unset" >&2
+        return 1
+    fi
+
+    # Use a header file so the token never appears on the command line.
+    local header_file
+    header_file=$(mktemp)
+    printf "Authorization: Bearer %s\n" "${!env_var}" > "$header_file"
+
+    local response
+    response=$(curl -sS -H @"$header_file" \
+        -X POST \
+        -F "file=@${output}" \
+        "${registry}/packages") || {
+        rm -f "$header_file"
+        return 1
+    }
+
+    rm -f "$header_file"
+
+    # Emit structured response for the pipeline.
+    echo "$response"
+
+    return 0
+}
+```
+
+## Registering the Handler
+
+```bash
+source lib/release-artifacts.sh
+register_artifact_handler "my-custom-type" "my_custom"
+```
+
+After registration, a `release.artifacts[]` entry with `"type": "my-custom-type"` will invoke the three functions automatically during the pipeline.
+
+## Testing a Handler
+
+Every new handler MUST ship with BATS tests that cover:
+
+1. `validate` returns 1 on missing tools.
+2. `validate` returns 1 on missing config fields.
+3. `validate` returns 1 on missing credentials.
+4. `build` respects `dry_run`.
+5. `build` produces output and emits a valid SHA-256 checksum.
+6. `publish` respects `dry_run`.
+7. `publish` refuses to run with missing credentials.
+8. The full pipeline (`validate` → `build` → `publish` with `dry_run=true`) exits 0 end-to-end.
+
+Tests live in `tests/unit/release-artifacts-*.bats` alongside the existing handlers.

package/skills/ct-consensus-voter/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: ct-consensus-voter
+description: "Runs structured multi-agent voting for decision tasks with confidence scores, conflict detection, and HITL escalation when the threshold is not met. Use when two or more agents must vote on options: architecture choices, tool selection, policy decisions, when a task carries agent_type:analysis, or on phrases like 'reach consensus', 'vote on options', 'resolve the debate', 'pick the best approach'. Produces a voting matrix JSON, enforces the 0.5 threshold, flags ties within 0.1 confidence as contested and escalates to human tiebreak."
+---
+
+# 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
+
+| ID | Rule | Enforcement |
+|----|------|-------------|
+| CONS-001 | Vote MUST use the structured voting matrix format. | `validateConsensusProtocol` rejects entries with fewer than 2 options. |
+| CONS-002 | Every position MUST carry a rationale string. | Missing rationale rejects the entry. |
+| CONS-003 | Every confidence score MUST lie in `[0.0, 1.0]`. | Out-of-range scores fail validation. |
+| CONS-004 | Every position MUST cite at least one evidence record. | Bare votes are rejected; evidence is non-optional. |
+| CONS-005 | Conflicts MUST be flagged with a severity level (`critical` / `high` / `medium` / `low`). | A conflict without severity is a protocol violation. |
+| CONS-006 | The vote MUST escalate to HITL when the top option's confidence is below the threshold (default 0.5). | Exit code 65 (`HANDOFF_REQUIRED`). |
+| CONS-007 | Manifest entry MUST set `agent_type: "analysis"`. | Validator rejects any other value. |
+
+## Voting Matrix Schema
+
+Every consensus run produces a single JSON document that matches this shape:
+
+```json
+{
+  "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](references/matrix-examples.md).
+
+## Scoring Rules
+
+| Rule | Description |
+|------|-------------|
+| **Score range** | `confidence ∈ [0.0, 1.0]`; out-of-range scores are rejected. |
+| **Threshold** | Default 0.5. Can be overridden per task; MUST be recorded in the matrix. |
+| **Top option** | The option with the highest confidence; ties break by rationale length (deterministic). |
+| **Pass condition** | Top option confidence > threshold **and** no conflict has `severity: critical`. |
+| **Fail condition** | Top option confidence ≤ threshold, OR a critical conflict is present. |
+
+## Verdicts
+
+| Verdict | Condition | Action |
+|---------|-----------|--------|
+| `PROVEN` | Top option ≥ threshold + reproducible evidence | Write manifest, exit 0, hand off to ct-adr-recorder |
+| `REFUTED` | Counter-evidence invalidates the top option | Write manifest, exit 0, do not promote to ADR |
+| `CONTESTED` | Top two options within 0.1 confidence | Flag as contested, exit 65 (HITL tiebreak) |
+| `INSUFFICIENT_EVIDENCE` | No option reaches the threshold, OR fewer than 2 options have evidence | Exit 65, request additional research |
+
+## 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:
+
+```json
+{
+  "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`:
+
+```bash
+cleo check protocol \
+  --protocolType consensus \
+  --votingMatrixFile ./.cleo/consensus/CONS-0042.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
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Binary votes without confidence scores | Loses nuance (violates CONS-003) | Every position carries a score in `[0.0, 1.0]` |
+| Positions without evidence | Bare opinions cannot produce consensus (violates CONS-004) | Every position cites at least one file/section/type |
+| Accepting unanimous consensus uncritically | May indicate groupthink | The skill MUST still record rationale and check for hidden assumptions |
+| Skipping minority positions | Loses valid concerns | Record every option the agents considered, including rejected ones |
+| Premature escalation | Wastes human attention | Only escalate on the four listed conditions, not on every low-confidence vote |
+| Treating the threshold as advisory | Breaks CONS-006 | The threshold is a hard gate; below it, escalate |
+| Reusing a matrix across questions | Pollutes evidence chains | Each question gets its own `questionId` and its own matrix file |
+
+## 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`.

package/skills/ct-consensus-voter/manifest-entry.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "CLEO-only metadata -- add to packages/skills/skills/manifest.json",
+  "name": "ct-consensus-voter",
+  "version": "1.0.0",
+  "tier": 2,
+  "token_budget": 6000,
+  "protocol": "consensus",
+  "capabilities": {
+    "inputs": ["task-id", "question", "candidate-options"],
+    "outputs": ["voting-matrix", "manifest-entry"],
+    "dispatch_triggers": [
+      "reach consensus",
+      "vote on options",
+      "resolve the debate",
+      "pick the best approach",
+      "run consensus"
+    ],
+    "compatible_subagent_types": ["general-purpose"],
+    "chains_to": ["ct-adr-recorder", "ct-research-agent"],
+    "dispatch_keywords": {
+      "primary": ["consensus", "vote", "decide", "verdict"],
+      "secondary": ["confidence", "rationale", "evidence", "contested"]
+    }
+  },
+  "constraints": {
+    "max_context_tokens": 60000,
+    "requires_session": false,
+    "requires_epic": false
+  }
+}

package/skills/ct-consensus-voter/references/matrix-examples.md

@@ -0,0 +1,140 @@
+# Voting Matrix Examples
+
+Three worked examples covering the outcomes the skill must handle: a clean win, a contested verdict, and an escalation for insufficient evidence.
+
+## Example 1: Clean Win (PROVEN)
+
+Question: "Which lock file strategy should the Rust workspace use?"
+
+```json
+{
+  "questionId": "CONS-0101",
+  "question": "Which lock file strategy should the Rust workspace use?",
+  "options": [
+    {
+      "name": "single-workspace-lock",
+      "confidence": 0.91,
+      "rationale": "Single Cargo.lock at the workspace root guarantees consistent dependency resolution across all 14 crates and matches how cargo build --workspace expects dependencies.",
+      "evidence": [
+        { "file": "Cargo.toml", "section": "[workspace]", "type": "code" },
+        { "file": "cargo-docs/workspaces.md", "section": "Lock files", "type": "doc" }
+      ]
+    },
+    {
+      "name": "per-crate-locks",
+      "confidence": 0.23,
+      "rationale": "Per-crate lock files isolate version churn but fight the workspace resolver.",
+      "evidence": [
+        { "file": "cargo-docs/resolver.md", "section": "V2", "type": "doc" }
+      ]
+    }
+  ],
+  "threshold": 0.5,
+  "verdict": "PROVEN",
+  "actualConsensus": 0.91,
+  "conflicts": []
+}
+```
+
+Outcome:
+- `verdict == PROVEN` because top option confidence (0.91) > threshold (0.5) and no critical conflicts.
+- The skill exits 0 and hands off to `ct-adr-recorder` so the decision is formalized as an ADR.
+- The runner-up is recorded with rationale so the next reviewer knows what was rejected and why.
+
+## Example 2: Contested Verdict (CONTESTED)
+
+Question: "Which test framework should the new agent-runtime crate use?"
+
+```json
+{
+  "questionId": "CONS-0202",
+  "question": "Which test framework should the new agent-runtime crate use?",
+  "options": [
+    {
+      "name": "cargo-test-builtin",
+      "confidence": 0.74,
+      "rationale": "Built into the toolchain, zero additional dependencies, works with every CI runner out of the box.",
+      "evidence": [
+        { "file": "cargo-docs/testing.md", "section": "Writing tests", "type": "doc" }
+      ]
+    },
+    {
+      "name": "nextest",
+      "confidence": 0.72,
+      "rationale": "Parallel execution with isolated test processes is significantly faster on multi-core CI runners and surfaces flaky tests.",
+      "evidence": [
+        { "file": "nextest-rs/docs/index.md", "section": "Benefits", "type": "doc" },
+        { "file": "ci/bench-results.md", "section": "nextest vs cargo test", "type": "data" }
+      ]
+    }
+  ],
+  "threshold": 0.5,
+  "verdict": "CONTESTED",
+  "actualConsensus": 0.74,
+  "conflicts": [
+    {
+      "conflictId": "c-0202-01",
+      "severity": "medium",
+      "conflictType": "partial-overlap",
+      "positions": [
+        { "option": "cargo-test-builtin", "confidence": 0.74 },
+        { "option": "nextest", "confidence": 0.72 }
+      ],
+      "resolution": { "status": "pending", "resolutionType": "escalate" }
+    }
+  ]
+}
+```
+
+Outcome:
+- Top option is above threshold, BUT the runner-up is within 0.1 (0.74 - 0.72 = 0.02).
+- The skill flags the result as `CONTESTED` and exits 65 for HITL tiebreak.
+- The human reviewer picks one option or requests additional evidence.
+- Neither option is automatically promoted to an ADR.
+
+## Example 3: Insufficient Evidence (INSUFFICIENT_EVIDENCE)
+
+Question: "Should SignalDock adopt WebSockets instead of SSE for real-time updates?"
+
+```json
+{
+  "questionId": "CONS-0303",
+  "question": "Should SignalDock adopt WebSockets instead of SSE for real-time updates?",
+  "options": [
+    {
+      "name": "stay-on-sse",
+      "confidence": 0.44,
+      "rationale": "SSE works today and is simpler to scale behind HTTP/2 edge nodes, but we have no benchmarks under real agent load.",
+      "evidence": [
+        { "file": "signaldock/docs/transport.md", "section": "SSE", "type": "doc" }
+      ]
+    },
+    {
+      "name": "migrate-to-websockets",
+      "confidence": 0.39,
+      "rationale": "Bidirectional channel reduces polling round-trips but the migration cost and edge-proxy behavior under load are both unknown.",
+      "evidence": [
+        { "file": "mozilla-websocket-guide.md", "section": "Bidirectional", "type": "doc" }
+      ]
+    }
+  ],
+  "threshold": 0.5,
+  "verdict": "INSUFFICIENT_EVIDENCE",
+  "actualConsensus": 0.44,
+  "conflicts": []
+}
+```
+
+Outcome:
+- Neither option reaches the 0.5 threshold.
+- The skill marks the verdict `INSUFFICIENT_EVIDENCE` and exits 65.
+- The recommended next step is to run `ct-research-agent` to collect benchmarks under load, then re-run the vote.
+- Importantly, the skill does NOT guess a winner; it asks for more evidence.
+
+## Schema Notes
+
+- `questionId` is a unique identifier. Never reuse across questions, even for a rerun after new evidence — use a new id like `CONS-0303-r1`.
+- `threshold` is always recorded, even when it matches the default. Future readers must be able to see what gate applied.
+- `actualConsensus` is the top option's confidence, not a weighted average. Readers should not have to recompute it.
+- `conflicts` is always an array, even when empty. `conflicts: []` is clearer than a missing field.
+- `resolution.resolutionType` values: `merge`, `choose-a`, `choose-b`, `new`, `defer`, `escalate`. The skill never picks `merge` or `choose-*` itself; those are reviewer actions.

package/skills/ct-grade/references/token-tracking.md

@@ -116,5 +116,5 @@ For ct-grade specifically, both arms of an A/B test experience the same approxim
 - `src/core/metrics/token-estimation.ts` — CLEO's token estimation implementation
 - `docs/specs/CLEO-METRICS-VALIDATION-SYSTEM-SPEC.md` — Metrics system specification
 - `.cleo/setup-otel.sh` — OTel environment setup script
-- `packages/ct-skills/skills/ct-grade/scripts/token_tracker.py` — Token aggregation script
-- `packages/ct-skills/skills/ct-grade/scripts/generate_report.py` — Report generator (uses confidence labels)
+- `packages/skills/skills/ct-grade/scripts/token_tracker.py` — Token aggregation script
+- `packages/skills/skills/ct-grade/scripts/generate_report.py` — Report generator (uses confidence labels)

package/skills/ct-grade/scripts/run_all.py

@@ -25,7 +25,7 @@ from datetime import datetime
 from pathlib import Path
 
 SCRIPT_DIR = Path(__file__).parent.resolve()
-SKILL_DIR = SCRIPT_DIR.parent  # packages/ct-skills/skills/ct-grade/
+SKILL_DIR = SCRIPT_DIR.parent  # packages/skills/skills/ct-grade/
 
 
 # ---------------------------------------------------------------------------

package/skills/ct-grade-v2-1/manifest-entry.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "CLEO-only metadata — merge into packages/ct-skills/skills/manifest.json",
+  "_comment": "CLEO-only metadata — merge into packages/skills/skills/manifest.json",
   "name": "ct-grade",
   "version": "2.1.0",
   "tier": 2,