Protocol Enforcement

Dual-layer enforcement architecture with pre-commit hooks and runtime validation for CLEO protocols

Protocol Enforcement Specification

Version: 1.0.0 Status: ACTIVE Created: 2026-01-28 Author: Protocol Specification Agent (T2688)

---

RFC 2119 Conformance

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

---

Part 1: Preamble

1.1 Purpose

This specification defines the dual-layer enforcement architecture for CLEO protocols: pre-commit hooks (fast feedback) and runtime validation (comprehensive coverage). It addresses the protocol compliance gap identified in Wave 0 research (22% average enforcement across 7 protocols, 100 total requirements).

1.2 Authority

This specification is AUTHORITATIVE for:

• Enforcement architecture (ENFC-001 to ENFC-010)
• Validation function signatures (VFUNC-*)
• Protocol violation exit codes (60-67)
• Bypass policies and audit trails (BYPS-*)
• Testing requirements for enforcement (TEST-*)

---

Part 2: Enforcement Architecture (ENFC-*)

2.1 Dual-Layer Design

ID	Requirement	Rationale
ENFC-001	Protocol enforcement MUST use both pre-commit hooks AND runtime validation	Layered defense
ENFC-002	Enforcement layers MUST share validation logic via lib/protocol-validation.sh	Single source of truth
ENFC-003	Pre-commit hooks MUST be bypassable via --no-verify flag	Emergency escape hatch
ENFC-004	Runtime validation MUST be non-bypassable for critical requirements	Safety net
ENFC-007	Protocol violations MUST use exit codes 60-67	Distinguishable from system errors

2.2 Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         ENFORCEMENT LAYERS                        │
└─────────────────────────────────────────────────────────────────┘
                                │
         ┌──────────────────────┴──────────────────────┐
         │                                             │
         ▼                                             ▼
┌─────────────────────┐                     ┌─────────────────────┐
│   PRE-COMMIT HOOKS  │                     │  RUNTIME VALIDATION │
│   (Fast Feedback)   │                     │  (Comprehensive)    │
├─────────────────────┤                     ├─────────────────────┤
│ • commit-msg        │                     │ • cleo complete     │
│ • pre-commit        │                     │ • scripts/*.sh CLI  │
│ • Bypassable        │                     │ • Non-bypassable    │
└──────────┬──────────┘                     └──────────┬──────────┘
           │                                           │
           └──────────────┬────────────────────────────┘
                          │
                          ▼
           ┌───────────────────────────────┐
           │   lib/protocol-validation.sh  │
           │   (Shared Validation Logic)   │
           └───────────────────────────────┘

---

Part 3: Protocol-Specific Exit Codes

Exit Code	Protocol	Description	Retryable
60	research.md	Research protocol violation	No
61	consensus.md	Consensus protocol violation	Yes
62	specification.md	Specification protocol violation	No
63	decomposition.md	Decomposition protocol violation	No
64	implementation.md	Implementation protocol violation	No
65	contribution.md	Contribution protocol violation	No
66	release.md	Release protocol violation	Yes
67	(reserved)	Future protocol additions	TBD

Rationale: Exit codes 60-67 distinct from:

• 1-22: System/operational errors
• 100+: Special status codes

---

Part 4: Protocol Validation Requirements

4.1 Research Protocol Validation

Requirement	Check	Severity
RSCH-001	No code changes detected	error
RSCH-006	Key findings count between 3-7	error
RSCH-007	agent_type: "research" in manifest	error

4.2 Implementation Protocol Validation

Requirement	Check	Severity
IMPL-003	Provenance tags @task T#### present	error
IMPL-004	Tests pass	error
IMPL-007	agent_type: "implementation" in manifest	error

4.3 Release Protocol Validation

Requirement	Check	Severity
RLSE-001	Version follows semver	error
RLSE-002	Changelog entry exists	error
RLSE-003	All tests pass	error

---

Part 5: Bypass Policy (BYPS-*)

5.1 Bypass Mechanisms

ID	Requirement	Use Case
BYPS-001	Pre-commit hooks MUST be bypassable via --no-verify	Emergency hotfixes
BYPS-002	Runtime validation MUST NOT be bypassable for MUST requirements	Safety net
BYPS-003	Bypass usage MUST be logged to .cleo/bypass-log.json	Audit trail

5.2 Bypass Log Format

{
  "timestamp": "2026-01-28T08:45:00Z",
  "commit": "abc123def456",
  "operation": "commit",
  "hook": "commit-msg",
  "user": "keaton",
  "justification": "emergency",
  "violations": [
    {"requirement": "IMPL-003", "severity": "error", "message": "Missing @task tag"}
  ]
}

---

Part 6: Success Metrics

Baseline (Wave 0):

• Average enforcement: 22%
• Orphaned code: 3250 lines

Target (Post-Wave 3):

• Average enforcement: 40%
• Orphaned code: 0 lines

Target (Long-term):

• Average enforcement: 70%
• Full hook + runtime integration

---

References

• COMMIT-TASK-ENFORCEMENT: Commit-msg hook
• PROTOCOL-MISALIGNMENT-CORRECTIONS: Protocol corrections
• PROJECT-LIFECYCLE: RCSD pipeline