@cleocode/cleo 2026.2.5 → 2026.2.7

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

@@ -0,0 +1,346 @@
+# Testing Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Stage**: IVTR - T (Testing)
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Test Creation | "test", "write tests", "add tests" | New test development |
+| Test Execution | "run tests", "execute tests", "bats" | Test running |
+| Coverage | "coverage", "test coverage" | Coverage improvement |
+| Test Fixes | "fix test", "flaky", "failing test" | Test maintenance |
+
+**Explicit Override**: `--protocol testing` flag on task creation.
+
+**Lifecycle Position**: After Validation (V), before Release (R)
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| TEST-001 | MUST write tests using BATS framework for Bash |
+| TEST-002 | MUST place unit tests in `tests/unit/` |
+| TEST-003 | MUST place integration tests in `tests/integration/` |
+| TEST-004 | MUST achieve 100% pass rate before release |
+| TEST-005 | MUST test all MUST requirements from specifications |
+| TEST-006 | MUST write test summary to manifest |
+| TEST-007 | MUST set `agent_type: "testing"` in manifest |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| TEST-010 | SHOULD test edge cases and error paths |
+| TEST-011 | SHOULD include setup/teardown fixtures |
+| TEST-012 | SHOULD use descriptive test names |
+| TEST-013 | SHOULD document test rationale |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| TEST-020 | MAY add golden tests for output verification |
+| TEST-021 | MAY add performance benchmarks |
+| TEST-022 | MAY add stress tests for concurrency |
+
+---
+
+## Test Structure
+
+### Directory Layout
+
+```
+tests/
+├── unit/                    # Unit tests (isolated functions)
+│   ├── protocol-validation.bats
+│   ├── changelog-association.bats
+│   └── lifecycle-enforcement.bats
+├── integration/             # Integration tests (workflows)
+│   ├── release-ship.bats
+│   ├── commit-hook.bats
+│   └── backfill-releases.bats
+├── golden/                  # Golden output tests
+│   └── output-format.bats
+├── fixtures/                # Test data
+│   ├── sample-todo.json
+│   └── test-manifest.jsonl
+└── test_helper/             # BATS helpers
+    ├── bats-support/
+    └── bats-assert/
+```
+
+### BATS Test Template
+
+```bash
+#!/usr/bin/env bats
+
+load '../test_helper/bats-support/load'
+load '../test_helper/bats-assert/load'
+
+# =============================================================================
+# Test: feature-name.bats
+# Task: T####
+# Protocol: testing
+# =============================================================================
+
+setup() {
+    # Load functions to test
+    source "$BATS_TEST_DIRNAME/../../lib/feature.sh"
+
+    # Create test fixtures
+    export TEST_DIR=$(mktemp -d)
+}
+
+teardown() {
+    # Cleanup
+    rm -rf "$TEST_DIR"
+}
+
+@test "function_name should handle normal input" {
+    run function_name "normal input"
+    assert_success
+    assert_output --partial "expected"
+}
+
+@test "function_name should reject invalid input" {
+    run function_name ""
+    assert_failure
+    assert_output --partial "error"
+}
+
+@test "function_name should handle edge case" {
+    run function_name "edge case"
+    assert_success
+}
+```
+
+---
+
+## Test Categories
+
+### Unit Tests
+
+Test isolated functions without external dependencies.
+
+```bash
+@test "validate_research_protocol returns 0 for valid research" {
+    run validate_research_protocol "T2680"
+    assert_success
+}
+```
+
+### Integration Tests
+
+Test workflows involving multiple components.
+
+```bash
+@test "release ship should populate tasks and generate changelog" {
+    run cleo release create v0.99.0
+    run cleo release ship v0.99.0 --dry-run
+    assert_success
+    assert_output --partial "tasks populated"
+}
+```
+
+### Golden Tests
+
+Verify output format hasn't changed unexpectedly.
+
+```bash
+@test "cleo list output matches golden format" {
+    run cleo list --json
+    assert_success
+    diff <(echo "$output" | jq -S .) tests/golden/list-output.json
+}
+```
+
+---
+
+## Running Tests
+
+### All Tests
+
+```bash
+./tests/run-all-tests.sh
+```
+
+### Specific Suite
+
+```bash
+# Unit tests only
+bats tests/unit/*.bats
+
+# Integration tests only
+bats tests/integration/*.bats
+
+# Single file
+bats tests/unit/protocol-validation.bats
+```
+
+### With Coverage
+
+```bash
+# Run with TAP output for CI
+bats --tap tests/unit/*.bats > test-results.tap
+```
+
+---
+
+## Output Format
+
+### Test Summary
+
+```markdown
+# Test Report: T####
+
+**Date**: YYYY-MM-DD
+**Tester**: agent-id
+**Task**: T####
+
+## Summary
+
+- **Total Tests**: N
+- **Passed**: X
+- **Failed**: Y
+- **Skipped**: Z
+- **Pass Rate**: X%
+
+## Test Files Created
+
+| File | Tests | Status |
+|------|-------|--------|
+| tests/unit/feature.bats | 20 | PASS |
+| tests/integration/workflow.bats | 14 | PASS |
+
+## Coverage
+
+| Requirement | Tests | Covered |
+|-------------|-------|---------|
+| IMPL-001 | 3 | Yes |
+| IMPL-002 | 2 | Yes |
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Testing: [Feature Name]" \
+  --file "T####-test-report.md" \
+  --topics "testing,bats,quality" \
+  --findings "TESTS: N written,RESULT: X/Y passed,COVERAGE: Z requirements" \
+  --status complete \
+  --task T#### \
+  --not-actionable \
+  --agent-type testing
+```
+
+---
+
+## Integration Points
+
+### With Validation Protocol
+
+```
+Validation (V) ──► Testing (T)
+       │                │
+       │ Identifies     │ Writes tests for:
+       │ gaps           │ - Uncovered paths
+       │                │ - Edge cases
+       │                │ - Error handling
+```
+
+### With Release Protocol
+
+```
+Testing (T) ──► Release (R)
+       │              │
+       │ Gates:       │ Requires:
+       │ - 100% pass  │ - All tests pass
+       │ - Coverage   │ - No skipped tests
+```
+
+---
+
+## Exit Codes
+
+| Code | Constant | Description |
+|------|----------|-------------|
+| 0 | SUCCESS | All tests pass |
+| 1 | TEST_FAILURE | One or more tests failed |
+| 69 | EXIT_TESTS_SKIPPED | Tests were skipped |
+| 70 | EXIT_COVERAGE_INSUFFICIENT | Coverage below threshold |
+
+---
+
+## Best Practices
+
+### Test Naming
+
+```bash
+# Good: Describes behavior
+@test "populate_release_tasks should discover tasks in date window"
+
+# Bad: Too vague
+@test "test populate function"
+```
+
+### Fixtures
+
+```bash
+# Use fixtures for complex test data
+setup() {
+    cp tests/fixtures/sample-todo.json "$TEST_DIR/todo.json"
+}
+```
+
+### Isolation
+
+```bash
+# Each test should be independent
+setup() {
+    export TEST_DIR=$(mktemp -d)
+    export TODO_FILE="$TEST_DIR/todo.json"
+}
+
+teardown() {
+    rm -rf "$TEST_DIR"
+}
+```
+
+---
+
+## Cross-Cutting: Contribution Protocol
+
+When testing involves multi-agent work:
+
+1. **Record tester identity** in manifest
+2. **Attribute test authorship** via comments
+3. **Track test consensus** if multiple testers
+
+See: `protocols/contribution.md` for attribution requirements.
+
+---
+
+## References
+
+- **Test Framework**: [BATS](https://github.com/bats-core/bats-core)
+- **Existing Tests**: `tests/unit/`, `tests/integration/`
+- **Test Helpers**: `tests/test_helper/bats-support/`, `tests/test_helper/bats-assert/`
+- **Specification**: `docs/specs/PROTOCOL-ENFORCEMENT-SPEC.md`

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

@@ -0,0 +1,229 @@
+# Validation Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Stage**: IVTR - V (Validation)
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Verification | "validate", "verify", "check", "audit" | Correctness checking |
+| Quality | "quality", "qa", "review" | Quality assurance |
+| Compliance | "compliance", "conform", "standard" | Standards adherence |
+| Smoke Test | "smoke", "sanity", "basic test" | Initial verification |
+
+**Explicit Override**: `--protocol validation` flag on task creation.
+
+**Lifecycle Position**: After Implementation (I), before Testing (T)
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| VALID-001 | MUST verify implementation matches specification |
+| VALID-002 | MUST run existing test suite and report results |
+| VALID-003 | MUST check protocol compliance via `lib/protocol-validation.sh` |
+| VALID-004 | MUST document pass/fail status for each validation check |
+| VALID-005 | MUST write validation summary to manifest |
+| VALID-006 | MUST set `agent_type: "validation"` in manifest |
+| VALID-007 | MUST block progression if critical validations fail |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| VALID-010 | SHOULD verify edge cases identified in specification |
+| VALID-011 | SHOULD check for regressions in related functionality |
+| VALID-012 | SHOULD validate error handling paths |
+| VALID-013 | SHOULD measure against acceptance criteria |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| VALID-020 | MAY perform performance validation |
+| VALID-021 | MAY verify security constraints |
+| VALID-022 | MAY suggest additional test cases |
+
+---
+
+## Validation Checklist
+
+### Code Validation
+
+```bash
+# 1. Syntax check
+bash -n scripts/*.sh lib/*.sh
+
+# 2. Protocol compliance
+source lib/protocol-validation.sh
+validate_implementation_protocol "$TASK_ID"
+
+# 3. Run existing tests
+bats tests/unit/*.bats
+bats tests/integration/*.bats
+```
+
+### Specification Compliance
+
+| Check | Command | Pass Criteria |
+|-------|---------|---------------|
+| Spec exists | `ls docs/specs/*.md` | File present |
+| RFC 2119 keywords | `grep -E "MUST|SHOULD|MAY"` | Keywords present |
+| Implementation matches | Manual review | All MUST satisfied |
+
+### Exit Code Validation
+
+| Exit Code | Meaning | Action |
+|-----------|---------|--------|
+| 0 | All validations pass | Proceed to Testing |
+| 62 | Specification mismatch | Fix implementation |
+| 64 | Implementation protocol violation | Fix provenance |
+| 67 | Generic protocol violation | Review and fix |
+
+---
+
+## Output Format
+
+### Validation Report
+
+```markdown
+# Validation Report: T####
+
+**Date**: YYYY-MM-DD
+**Validator**: agent-id
+**Task**: T####
+**Epic**: T####
+
+## Summary
+
+- **Status**: PASS | FAIL | PARTIAL
+- **Checks Passed**: X/Y
+- **Critical Issues**: N
+
+## Detailed Results
+
+| Check | Result | Notes |
+|-------|--------|-------|
+| Syntax | PASS | No errors |
+| Tests | PASS | 48/48 pass |
+| Protocol | PASS | Compliance 95% |
+
+## Issues Found
+
+1. [Issue description]
+2. [Issue description]
+
+## Recommendations
+
+1. [Action item]
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Validation: [Feature Name]" \
+  --file "T####-validation-report.md" \
+  --topics "validation,qa" \
+  --findings "RESULT: X/Y checks passed,ISSUES: N found,STATUS: PASS|FAIL" \
+  --status complete \
+  --task T#### \
+  --actionable \
+  --agent-type validation
+```
+
+---
+
+## Integration Points
+
+### With Implementation Protocol
+
+```
+Implementation (I) ──► Validation (V)
+                           │
+                           ├── Run tests
+                           ├── Check compliance
+                           └── Verify spec match
+```
+
+### With Testing Protocol
+
+```
+Validation (V) ──► Testing (T)
+       │                │
+       │                ├── Write new tests
+       │                └── Full coverage
+       │
+       └── Identifies gaps for Testing to fill
+```
+
+### With lib/protocol-validation.sh
+
+The validation protocol uses these functions:
+
+| Function | Purpose | Exit Code |
+|----------|---------|-----------|
+| `validate_implementation_protocol()` | Check IMPL-* compliance | 64 |
+| `validate_specification_protocol()` | Check SPEC-* compliance | 62 |
+| `validate_protocol()` | Generic protocol check | 67 |
+
+---
+
+## Enforcement
+
+### Via lib/protocol-validation.sh
+
+```bash
+source lib/protocol-validation.sh
+
+# Validate a specific protocol
+validate_implementation_protocol "$TASK_ID" "$MANIFEST_ENTRY" "true"
+
+# Generic validation
+validate_protocol "implementation" "$TASK_ID" "$DATA"
+```
+
+### Exit Codes
+
+| Code | Constant | Description |
+|------|----------|-------------|
+| 62 | EXIT_PROTOCOL_SPECIFICATION | Spec validation failed |
+| 64 | EXIT_PROTOCOL_IMPLEMENTATION | Implementation validation failed |
+| 67 | EXIT_PROTOCOL_GENERIC | Generic validation failed |
+| 68 | EXIT_VALIDATION_INCOMPLETE | Validation not finished |
+
+---
+
+## Cross-Cutting: Contribution Protocol
+
+When validation involves multi-agent work:
+
+1. **Record validator identity** in manifest
+2. **Attribute findings** to validating agent
+3. **Track validation consensus** if multiple validators
+
+See: `protocols/contribution.md` for attribution requirements.
+
+---
+
+## References
+
+- **Specification**: `docs/specs/PROTOCOL-ENFORCEMENT-SPEC.md`
+- **Implementation**: `lib/protocol-validation.sh`
+- **Tests**: `tests/unit/protocol-validation.bats`

package/packages/ct-skills/skills/_shared/cleo-style-guide.md

@@ -0,0 +1,84 @@
+# CLEO Writing Style Guide
+
+## Core Principles
+
+Write like you're talking to a colleague. Be conversational, not formal. Get people what they need quickly. Know your audience and match the complexity.
+
+## Tone and Voice
+
+**Do:**
+
+- Use contractions ("can't" not "cannot")
+- Say "people" or "companies" instead of "users"
+- Be friendly but not peppy
+- Acknowledge limitations honestly ("that's on us, not them")
+- Jokes and Easter eggs are okay (permit them, don't suggest them)
+
+**Don't:**
+
+- Use exclamation points excessively
+- Rely on tired tropes about nerdiness
+- Use corporate jargon ("utilize", "offerings", "actionable insights")
+- Tell people something is cool (show them instead)
+
+## Structure and Clarity
+
+**Lead with the important stuff:**
+
+- Most important information first
+- Lead with the ask, then provide context
+- Cut text that adds little value (when in doubt, cut it)
+- Each paragraph should have one clear purpose
+
+**Make headings do the work:**
+
+- Convey your actual point, not just the topic
+- "Use headings to highlight key points" not "How to write a good heading"
+- Use sentence case, no punctuation except question marks
+- No links in headings unless entire heading is a link
+
+## Instructions and Examples
+
+**Tell people what to do:**
+
+- Give the action before explaining why
+- Put commands in execution order
+- Provide context, steps, and reasoning
+- Don't describe tasks as "easy" or "simple"
+
+**Answer unasked questions:**
+
+- Include answers to "dumb" questions you had when learning
+- Don't literally include the question, just give the answer
+
+## Formatting
+
+**Code vs. UI elements:**
+
+- Backticks for code, variable names, parameters only
+- **Bold** for UI elements and labels (e.g., "Click the **Save** button")
+- Don't use backticks or quotes for UI elements
+
+## Writing Mechanics
+
+- Limit pronouns when introducing new terms (repeat the term to reinforce it)
+- Ampersands only in proper nouns, never as substitute for "and"
+
+## Terminology Preferences
+
+Use familiar terms from tools people already know:
+
+- "Summarize" (like Excel) instead of "aggregate"
+- "Take a look at" instead of "reference"
+- "Filter" instead of technical database terms when appropriate
+
+## Red Flags
+
+Avoid these patterns:
+
+- Multiple exclamation points
+- Linking "here"
+- Bullet lists to explain (use prose)
+- Numbers that will change (guard against change)
+- Describing things as "easy" or "simple"
+- Stock photography-worthy content