@cleocode/core 2026.4.11 → 2026.4.13

package/src/validation/protocols/cant/implementation.cant

@@ -0,0 +1,67 @@
+---
+kind: protocol
+version: 1.0.0
+id: IMPL
+title: "Implementation Protocol"
+status: active
+type: base
+audience: "llm-agent"
+tags: "implementation, coding, development"
+skillRef: ct-task-executor
+lastUpdated: 2026-02-24
+enforcement: strict
+---
+
+# Implementation Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Building: "implement", "build", "create", "develop"
+#   Coding: "code", "write", "program"
+#   Fixing: "fix", "bug", "patch", "repair"
+#   Enhancement: "improve", "enhance", "optimize"
+#
+# Explicit Override: --protocol implementation flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   IMPL-001: MUST include tests for new functionality
+#   IMPL-002: MUST follow project code style conventions
+#   IMPL-003: MUST include JSDoc/docstring provenance tags
+#   IMPL-004: MUST verify changes pass existing tests
+#   IMPL-005: MUST document breaking changes
+#   IMPL-006: MUST write implementation summary to manifest
+#   IMPL-007: MUST set agent_type: "implementation" in manifest
+#
+# SHOULD:
+#   IMPL-010: SHOULD add inline comments for complex logic
+#   IMPL-011: SHOULD refactor duplicated code
+#   IMPL-012: SHOULD update related documentation
+#   IMPL-013: SHOULD consider error handling edge cases
+#
+# MAY:
+#   IMPL-020: MAY propose architectural improvements
+#   IMPL-021: MAY add performance benchmarks
+#   IMPL-022: MAY suggest follow-up enhancements
+#
+# Provenance Thresholds:
+#   New code: 100% coverage required
+#   Existing code: 80% coverage required
+#   Legacy code: 50% coverage required
+#
+# Exit Codes:
+#   EXIT_PROTOCOL_IMPLEMENTATION (64) - Implementation protocol violation
+#
+# Anti-Patterns:
+#   - Code without tests (regression risk)
+#   - Missing provenance (lost attribution)
+#   - Skipping validation (quality regression)
+#   - Undocumented breaking changes (surprise failures)
+#   - No error handling (silent failures)
+#   - Hardcoded values (maintenance burden)

package/src/validation/protocols/cant/provenance.cant

@@ -0,0 +1,88 @@
+---
+kind: protocol
+version: 1.0.0
+id: PROV
+title: "Provenance Protocol"
+status: active
+type: cross-cutting
+audience: "llm-agent, orchestrator"
+tags: "provenance, traceability, lineage"
+skillRef: ct-provenance-keeper
+lastUpdated: 2026-04-07
+enforcement: advisory
+---
+
+# Provenance Protocol
+#
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Supply Chain: "provenance", "supply chain", "chain of custody"
+#   Attestation: "attest", "attestation", "in-toto", "SLSA"
+#   SBOM: "sbom", "bill of materials", "cyclonedx", "spdx"
+#   Signing: "sign", "cosign", "sigstore", "verify signature"
+#   Checksums: "checksum", "digest", "sha256", "integrity"
+#
+# Explicit Override: --protocol provenance flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   PROV-001: MUST record provenance chain from source commit to published artifact
+#   PROV-002: MUST compute SHA-256 digest for every produced artifact
+#   PROV-003: MUST generate attestation in in-toto Statement v1 format
+#   PROV-004: MUST record SLSA Build Level achieved (L1 minimum)
+#   PROV-005: MUST store provenance record in .cleo/releases.json via record_release()
+#   PROV-006: MUST verify provenance chain integrity before publishing attestation
+#   PROV-007: MUST set agent_type: "provenance" in manifest
+#
+# SHOULD:
+#   PROV-010: SHOULD generate SBOM (CycloneDX or SPDX) for artifacts with dependencies
+#   PROV-011: SHOULD sign attestations using keyless signing (sigstore/cosign)
+#   PROV-012: SHOULD publish provenance attestation alongside artifact
+#   PROV-013: SHOULD verify all input materials have provenance
+#
+# MAY:
+#   PROV-020: MAY achieve SLSA Build Level 3 or 4
+#   PROV-021: MAY use key-based signing (GPG) as alternative to keyless
+#   PROV-022: MAY generate multiple SBOM formats (both CycloneDX and SPDX)
+#
+# Provenance Chain Model:
+#   commit -> build -> artifact -> attestation -> registry
+#
+# Chain Integrity Rules:
+#   Each link MUST reference previous link's output
+#   No link MAY be modified after creation (append-only)
+#   Missing links MUST be recorded as incomplete
+#   Chain MUST be verifiable offline
+#
+# SLSA Compliance Levels:
+#   L1: Provenance exists
+#   L2: Provenance signed + build on hosted platform
+#   L3: Non-falsifiable provenance
+#   L4: All deps have provenance + hermetic reproducible build
+#
+# Signing Methods:
+#   sigstore (default): cosign sign-blob --yes <artifact>
+#   gpg: gpg --detach-sign --armor -u <key-id> <artifact>
+#   none: Skip signing (SLSA L1 only)
+#
+# Error Codes (90-94):
+#   90: E_PROVENANCE_CONFIG_INVALID
+#   91: E_SIGNING_KEY_MISSING
+#   92: E_SIGNATURE_INVALID
+#   93: E_DIGEST_MISMATCH
+#   94: E_ATTESTATION_INVALID
+#
+# Anti-Patterns:
+#   - Skipping digest computation (breaks chain integrity)
+#   - Hardcoding signing keys in config (security risk)
+#   - Generating attestation without matching digest
+#   - Publishing artifact before signing
+#   - Modifying provenance records after creation
+#   - Skipping SBOM for artifacts with dependencies
+#   - Using SHA-1 or MD5 for digests (cryptographically broken)
+#   - Storing private keys in .cleo/ directory

package/src/validation/protocols/cant/release.cant

@@ -0,0 +1,96 @@
+---
+kind: protocol
+version: 1.0.0
+id: REL
+title: "Release Protocol"
+status: active
+type: conditional
+audience: "llm-agent, orchestrator"
+tags: "release, semver, changelog"
+skillRef: ct-release-orchestrator
+lastUpdated: 2026-04-07
+enforcement: strict
+---
+
+# Release Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Version: "release", "version", "v1.x.x"
+#   Publish: "publish", "deploy", "ship"
+#   Changelog: "changelog", "release notes"
+#   Tag: "tag", "milestone", "GA"
+#
+# Explicit Override: --protocol release flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   RLSE-001: MUST follow semantic versioning (semver)
+#   RLSE-002: MUST update changelog with all changes
+#   RLSE-003: MUST pass all validation gates before release
+#   RLSE-004: MUST tag release in version control
+#   RLSE-005: MUST document breaking changes with migration path
+#   RLSE-006: MUST verify version consistency across files
+#   RLSE-007: MUST set agent_type: "documentation" in manifest
+#
+# SHOULD:
+#   RLSE-010: SHOULD include upgrade instructions
+#   RLSE-011: SHOULD verify documentation is current
+#   RLSE-012: SHOULD test installation process
+#   RLSE-013: SHOULD create backup before release
+#   RLSE-014: SHOULD run test suite for major/minor releases
+#   RLSE-015: SHOULD verify tests pass before tagging
+#
+# MAY:
+#   RLSE-020: MAY include performance benchmarks
+#   RLSE-021: MAY announce on communication channels
+#   RLSE-022: MAY batch minor fixes into single release
+#
+# State Machine:
+#   create -> planned -> active -> released (immutable)
+#
+# Ship Workflow (10 steps):
+#   1. Auto-populate release tasks
+#   1.5. Run release guards
+#   2. Bump version (if --bump-version)
+#   3. Ensure [Unreleased] section in CHANGELOG.md
+#   4. Generate changelog from task metadata
+#   5. Validate changelog content
+#   6. Append to CHANGELOG.md + platform outputs
+#   7. Run validation gates
+#   8. Create release commit
+#   9. Create annotated tag (if --create-tag)
+#   10. Push to remote (if --push)
+#   11. Update release status to released
+#
+# Composition with Sub-Protocols:
+#   artifact-publish: Conditional, triggered when release config has artifact handlers
+#   provenance: Conditional, invoked transitively via artifact-publish for signing
+#
+# Error Codes (50-59):
+#   50: E_RELEASE_NOT_FOUND
+#   51: E_RELEASE_EXISTS
+#   52: E_RELEASE_LOCKED
+#   53: E_INVALID_VERSION
+#   54: E_VALIDATION_FAILED
+#   55: E_VERSION_BUMP_FAILED
+#   56: E_TAG_CREATION_FAILED
+#   57: E_CHANGELOG_GENERATION_FAILED
+#   58: E_TAG_EXISTS
+#   59: E_TASKS_INCOMPLETE
+#
+# Anti-Patterns:
+#   - Skipping version bump (version confusion)
+#   - Missing changelog entry (lost history)
+#   - Undocumented breaking changes (user frustration)
+#   - No release tag (cannot reference version)
+#   - Incomplete checklist (missed steps)
+#   - Major releases without --run-tests (quality risk)
+#   - Ignoring epic completeness warnings
+#   - Overusing --force (bypasses guards)

package/src/validation/protocols/cant/research.cant

@@ -0,0 +1,66 @@
+---
+kind: protocol
+version: 1.0.0
+id: RSCH
+title: "Research Protocol"
+status: active
+type: base
+audience: "llm-agent, orchestrator"
+tags: "research, investigation, evidence"
+skillRef: ct-research-agent
+lastUpdated: 2026-02-24
+enforcement: strict
+---
+
+# Research Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Investigation: "research", "investigate", "explore", "study"
+#   Analysis: "analyze", "compare", "evaluate", "assess"
+#   Discovery: "find out", "discover", "learn about"
+#   Documentation: "document findings", "report on"
+#
+# Explicit Override: --protocol research flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   RSCH-001: MUST NOT implement code or make changes to codebase
+#   RSCH-002: MUST document all sources with citations
+#   RSCH-003: MUST write findings to claudedocs/agent-outputs/
+#   RSCH-004: MUST append entry to MANIFEST.jsonl
+#   RSCH-005: MUST return only completion message (no content in response)
+#   RSCH-006: MUST include 3-7 key findings in manifest entry
+#   RSCH-007: MUST set agent_type: "research" in manifest
+#
+# SHOULD:
+#   RSCH-010: SHOULD use multiple independent sources
+#   RSCH-011: SHOULD cross-reference findings for accuracy
+#   RSCH-012: SHOULD include confidence levels for claims
+#   RSCH-013: SHOULD identify gaps or areas needing further research
+#   RSCH-014: SHOULD link research to relevant tasks
+#
+# MAY:
+#   RSCH-020: MAY propose follow-up research tasks
+#   RSCH-021: MAY include visual diagrams or tables
+#   RSCH-022: MAY compare multiple approaches or solutions
+#
+# Tool Allowlist:
+#   Allowed: Read, Grep, Glob, Bash (read-only commands only)
+#   Prohibited: Write, Edit, any code compilation or execution
+#
+# Exit Codes:
+#   EXIT_PROTOCOL_RESEARCH (60) - Research protocol violation
+#
+# Anti-Patterns:
+#   - Implementing code during research (pollutes context, mixes concerns)
+#   - Returning findings in response (wastes orchestrator context)
+#   - Single-source conclusions (risk of bias or error)
+#   - Vague findings without evidence (not actionable)
+#   - Skipping manifest entry (breaks orchestrator workflow)

package/src/validation/protocols/cant/specification.cant

@@ -0,0 +1,67 @@
+---
+kind: protocol
+version: 1.0.0
+id: SPEC
+title: "Specification Protocol"
+status: active
+type: conditional
+audience: "llm-agent, orchestrator"
+tags: "specification, requirements, rfc2119"
+skillRef: ct-spec-writer
+lastUpdated: 2026-02-24
+enforcement: strict
+---
+
+# Specification Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Conditional Protocol
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Design: "spec", "specification", "design", "architect"
+#   Contract: "contract", "interface", "API", "schema"
+#   Definition: "define", "formalize", "standardize"
+#   Protocol: "protocol", "workflow", "process"
+#
+# Explicit Override: --protocol specification flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   SPEC-001: MUST use RFC 2119 keywords for requirements
+#   SPEC-002: MUST include version number and status
+#   SPEC-003: MUST define scope and authority
+#   SPEC-004: MUST include conformance criteria
+#   SPEC-005: MUST document related specifications
+#   SPEC-006: MUST use structured format (tables, schemas)
+#   SPEC-007: MUST set agent_type: "specification" in manifest
+#
+# SHOULD:
+#   SPEC-010: SHOULD include examples for each requirement
+#   SPEC-011: SHOULD document failure modes
+#   SPEC-012: SHOULD specify error handling
+#   SPEC-013: SHOULD include changelog
+#
+# MAY:
+#   SPEC-020: MAY include implementation guidance
+#   SPEC-021: MAY reference external standards
+#   SPEC-022: MAY define extension points
+#
+# Version Semantics:
+#   Major (X.0.0): Breaking changes to requirements
+#   Minor (X.Y.0): New requirements, backward compatible
+#   Patch (X.Y.Z): Clarifications, typo fixes
+#
+# Status Lifecycle:
+#   DRAFT -> ACTIVE -> DEPRECATED
+#                  \-> SUPERSEDED (by new spec)
+#
+# Anti-Patterns:
+#   - Vague requirements without levels (cannot verify compliance)
+#   - Missing version number (cannot track changes)
+#   - Undefined scope (unclear authority)
+#   - No examples (hard to implement correctly)
+#   - Skipping RFC 2119 declaration (ambiguous requirement levels)

package/src/validation/protocols/cant/testing.cant

@@ -0,0 +1,88 @@
+---
+kind: protocol
+version: 2.0.0
+id: TEST
+title: "Testing Protocol (Project-Agnostic IVT Loop)"
+status: active
+type: base
+audience: "llm-agent, orchestrator"
+tags: "testing, ivt-loop, autonomous, framework-agnostic, compliance"
+skillRef: ct-ivt-looper
+lastUpdated: 2026-04-07
+enforcement: strict
+---
+
+# Testing Protocol - Project-Agnostic IVT Loop
+#
+# Provenance: @task T260 (replaces T3155 BATS-locked v1)
+# Type: Base Protocol
+# Stage: IVTR - T (Testing, the closure of the IVT loop)
+# Skill: ct-ivt-looper
+#
+# Core Principle:
+#   The loop converges on the spec, not on "tests pass".
+#   Passing tests that don't cover the spec are a failure.
+#
+# Project-Agnostic Mandate:
+#   MUST work in any project. MUST NOT assume a specific language,
+#   test framework, directory layout, or test command.
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Loop Closure: "ivt loop", "implement and verify", "ship this task"
+#   Test Execution: "run tests", "verify", "test this"
+#   Coverage: "coverage", "test coverage", "missing tests"
+#   Spec Compliance: "satisfy spec", "verify against spec"
+#   Release Gate: "before release", "pre-PR validation", "ship verified"
+#
+# Explicit Override: --protocol testing flag on task creation.
+# Lifecycle Position: After Validation (V), before Release (R)
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   TEST-001: MUST identify project test framework via dynamic detection
+#   TEST-002: MUST run IVT loop with explicit iteration counter and MAX_ITERATIONS cap (default 5)
+#   TEST-003: MUST trace each MUST requirement from upstream spec to at least one passing test
+#   TEST-004: MUST achieve 100% pass rate before exiting with ivtLoopConverged: true
+#   TEST-005: MUST exit only when spec is satisfied or MAX_ITERATIONS reached
+#   TEST-006: MUST write test summary to manifest key_findings array
+#   TEST-007: MUST set agent_type: "testing" in manifest
+#   TEST-008: MUST run on feature branch - never on main/master
+#   TEST-009: MUST escalate non-convergence to HITL via exit code 65
+#
+# SHOULD:
+#   TEST-010: SHOULD test edge cases and error paths
+#   TEST-011: SHOULD include setup/teardown fixtures appropriate to framework
+#   TEST-012: SHOULD use descriptive test names tied to spec requirement codes
+#   TEST-013: SHOULD report coverage percentage when framework supports it
+#   TEST-014: SHOULD prefer .cleo/project-context.json testing.command when present
+#
+# MAY:
+#   TEST-020: MAY add golden tests for output verification
+#   TEST-021: MAY add performance benchmarks
+#   TEST-022: MAY add stress/concurrency tests
+#   TEST-023: MAY parallelize IVT loop across independent specs
+#
+# Framework Detection Priority:
+#   1. .cleo/project-context.json testing.command (highest)
+#   2. Auto-detection signals (vitest, jest, pytest, cargo test, go test, etc.)
+#   3. Fallback: ask operator to declare in project-context.json
+#
+# Exit Codes:
+#   0: SUCCESS - Loop converged, manifest recorded
+#   65: HANDOFF_REQUIRED - Non-convergence after MAX_ITERATIONS
+#   67: CONCURRENT_SESSION - Generic testing protocol violation
+#   80: LIFECYCLE_GATE_FAILED - Required gate failed
+#
+# Anti-Patterns:
+#   - Hardcoding vitest/jest/pytest (violates project-agnostic mandate)
+#   - Running tests once and reporting result (testing is a LOOP)
+#   - Skipping validation between iterations
+#   - Bailing silently on non-convergence (must escalate to HITL)
+#   - Marking task complete with failed > 0
+#   - Modifying main/master branch
+#   - Ignoring spec-requirement traceability
+#   - Treating coverage as the convergence metric
+#   - Editing test expectations to match broken code

package/src/validation/protocols/cant/validation.cant

@@ -0,0 +1,65 @@
+---
+kind: protocol
+version: 1.0.0
+id: VALID
+title: "Validation Protocol"
+status: active
+type: base
+audience: "llm-agent, orchestrator"
+tags: "validation, quality, compliance"
+skillRef: ct-validator
+lastUpdated: 2026-02-24
+enforcement: strict
+---
+
+# Validation Protocol
+#
+# Provenance: @task T3155, @epic T3147
+# Type: Conditional Protocol
+# Stage: IVTR - V (Validation)
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Verification: "validate", "verify", "check", "audit"
+#   Quality: "quality", "qa", "review"
+#   Compliance: "compliance", "conform", "standard"
+#   Smoke Test: "smoke", "sanity", "basic test"
+#
+# Explicit Override: --protocol validation flag on task creation.
+# Lifecycle Position: After Implementation (I), before Testing (T)
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   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:
+#   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:
+#   VALID-020: MAY perform performance validation
+#   VALID-021: MAY verify security constraints
+#   VALID-022: MAY suggest additional test cases
+#
+# Exit Codes:
+#   62: Specification mismatch (fix implementation)
+#   64: Implementation protocol violation (fix provenance)
+#   67: Generic protocol violation (review and fix)
+#   68: EXIT_VALIDATION_INCOMPLETE (validation not finished)
+#
+# Anti-Patterns:
+#   - Skipping spec compliance check (missed requirements)
+#   - Not documenting validation results (lost audit trail)
+#   - Ignoring non-critical failures (quality regression)
+#   - Running partial validation suite (false confidence)

package/src/validation/protocols/protocols-markdown/decomposition.md

@@ -7,10 +7,6 @@ type: conditional
 audience: [llm-agent, orchestrator]
 tags: [decomposition, hierarchy, atomicity, planning]
 skillRef: ct-epic-architect
-mcpOperations:
-  - tasks.add
-  - tasks.update
-  - session.start
 lastUpdated: 2026-02-24
 provenanceTask: T3155
 enforcement: strict

package/templates/config.template.json

@@ -111,7 +111,6 @@
   "brain": {
     "autoCapture": true,
     "captureFiles": false,
-    "captureMcp": false,
     "captureWork": false,
     "embedding": {
       "enabled": true,

package/templates/global-config.template.json

@@ -41,7 +41,6 @@
   "brain": {
     "autoCapture": true,
     "captureFiles": false,
-    "captureMcp": false,
     "captureWork": false,
     "embedding": {
       "enabled": true,