@cleocode/core 2026.4.5 → 2026.4.7

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

@@ -0,0 +1,357 @@
+---
+id: IMPL
+title: Implementation Protocol
+version: 1.0.0
+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
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Building | "implement", "build", "create", "develop" | New functionality |
+| Coding | "code", "write", "program" | Software creation |
+| Fixing | "fix", "bug", "patch", "repair" | Issue resolution |
+| Enhancement | "improve", "enhance", "optimize" | Existing code |
+
+**Explicit Override**: `--protocol implementation` flag on task creation.
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| 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
+
+| Requirement | Description |
+|-------------|-------------|
+| 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
+
+| Requirement | Description |
+|-------------|-------------|
+| IMPL-020 | MAY propose architectural improvements |
+| IMPL-021 | MAY add performance benchmarks |
+| IMPL-022 | MAY suggest follow-up enhancements |
+
+---
+
+## Output Format
+
+### Provenance Tags
+
+**JavaScript/TypeScript**:
+```javascript
+/**
+ * @task T####
+ * @session session_YYYYMMDD_HHMMSS_######
+ * @agent opus-1
+ * @date YYYY-MM-DD
+ * @description Brief description of the function
+ */
+function implementedFunction() {
+    // Implementation
+}
+```
+
+**Bash**:
+```bash
+# =============================================================================
+# Function: function_name
+# Task: T####
+# Session: session_YYYYMMDD_HHMMSS_######
+# Agent: opus-1
+# Date: YYYY-MM-DD
+# Description: Brief description
+# =============================================================================
+function_name() {
+    # Implementation
+}
+```
+
+**Python**:
+```python
+def implemented_function():
+    """
+    Brief description.
+
+    Task: T####
+    Session: session_YYYYMMDD_HHMMSS_######
+    Agent: opus-1
+    Date: YYYY-MM-DD
+    """
+    # Implementation
+```
+
+### Test Requirements
+
+| Test Type | When Required | Coverage |
+|-----------|---------------|----------|
+| Unit | New functions | MUST cover happy path |
+| Integration | New workflows | SHOULD cover end-to-end |
+| Edge Case | Complex logic | SHOULD cover boundaries |
+| Regression | Bug fixes | MUST reproduce issue |
+
+### Code Style Checklist
+
+| Language | Style Guide | Enforcement |
+|----------|-------------|-------------|
+| Bash | CLEO style (4 spaces, snake_case) | `shellcheck` |
+| JavaScript | ESLint config | `eslint` |
+| TypeScript | TSConfig strict | `tsc --noEmit` |
+| Python | PEP 8 | `flake8`, `black` |
+
+### File Output
+
+```markdown
+# Implementation: {Feature/Fix Title}
+
+**Task**: T####
+**Date**: YYYY-MM-DD
+**Status**: complete|partial|blocked
+**Agent Type**: implementation
+
+---
+
+## Summary
+
+{2-3 sentence summary of implementation}
+
+## Changes
+
+### Files Modified
+
+| File | Action | Description |
+|------|--------|-------------|
+| `path/to/file.sh` | Modified | Added validation function |
+| `path/to/new.sh` | Created | New utility module |
+
+### Functions Added
+
+| Function | File | Purpose |
+|----------|------|---------|
+| `validate_input()` | file.sh | Input validation |
+
+### Functions Modified
+
+| Function | File | Change |
+|----------|------|--------|
+| `process_data()` | file.sh | Added error handling |
+
+## Tests
+
+### New Tests
+
+| Test | File | Coverage |
+|------|------|----------|
+| `test_validate_input` | tests/unit/file.bats | Input validation |
+
+### Test Results
+
+```
+Running tests/unit/file.bats
+ ✓ validate_input accepts valid input
+ ✓ validate_input rejects empty input
+ ✓ validate_input handles special characters
+
+3 tests, 0 failures
+```
+
+## Validation
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Tests pass | PASS | All 42 tests pass |
+| Lint clean | PASS | No shellcheck warnings |
+| No regressions | PASS | Existing tests unchanged |
+
+## Breaking Changes
+
+{If any, document migration path}
+
+## Follow-up
+
+- {Suggested improvements}
+- {Technical debt items}
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Implementation: Feature Name" \
+  --file "YYYY-MM-DD_implementation.md" \
+  --topics "implementation,feature" \
+  --findings "3 functions added,Tests passing,No breaking changes" \
+  --status complete \
+  --task T#### \
+  --not-actionable \
+  --agent-type implementation
+```
+
+---
+
+## Integration Points
+
+### Base Protocol
+
+- Inherits task lifecycle (start, execute, complete)
+- Inherits manifest append requirement
+- Inherits error handling patterns
+
+### Protocol Interactions
+
+| Combined With | Behavior |
+|---------------|----------|
+| specification | Spec defines implementation requirements |
+| contribution | Implementation triggers contribution record |
+| release | Implementation changes tracked for release |
+
+### Workflow Sequence
+
+```
+1. Read task requirements (cleo show T####)
+2. Start task (cleo start T####)
+3. Implement changes with provenance tags
+4. Write/update tests
+5. Run validation (tests, lint)
+6. Document changes in output file
+7. Append manifest entry
+8. Complete task (cleo complete T####)
+9. Return completion message
+```
+
+---
+
+## Example
+
+**Task**: Implement session binding for multi-agent support
+
+**Manifest Entry Command**:
+```bash
+cleo research add \
+  --title "Implementation: Session Binding" \
+  --file "2026-01-26_session-binding-impl.md" \
+  --topics "session,binding,multi-agent" \
+  --findings "TTY binding implemented,Env var fallback added,4 new tests passing" \
+  --status complete \
+  --task T2400 \
+  --epic T2392 \
+  --not-actionable \
+  --agent-type implementation
+```
+
+**Return Message**:
+```
+Implementation complete. See MANIFEST.jsonl for summary.
+```
+
+---
+
+## Provenance Validation
+
+### Pre-Commit Hook
+
+**Location**: `.git/hooks/commit-msg` (installed via `git config core.hooksPath .cleo/hooks`)
+
+**Logic**:
+1. Extract @task tags from commit diff
+2. Count new functions/classes
+3. Calculate provenance coverage
+4. Apply thresholds:
+   - **New code**: 100% coverage required
+   - **Existing code**: 80% coverage required
+   - **Legacy code**: 50% coverage required
+5. Block commit if thresholds not met
+
+**Exit Code**: `EXIT_PROTOCOL_IMPLEMENTATION` (64) on violation
+
+### Runtime Validation
+
+**Command** (planned): `cleo provenance validate [--task TASK_ID]`
+
+**Current State**: Validation available via protocol library
+
+```bash
+# Programmatic validation
+source lib/protocol-validation.sh
+result=$(validate_implementation_protocol "T1234" "$manifest_entry" "false")
+```
+
+**Checks**:
+- IMPL-003: `@task T####` tags in new functions
+- Git diff analysis for provenance coverage
+- Agent type = "implementation" (IMPL-007)
+
+### Thresholds
+
+| Code Category | Provenance Requirement | Rationale |
+|---------------|------------------------|-----------|
+| **New code** | 100% | Fresh code must be attributable |
+| **Existing code** | 80% | Modifications should track origin |
+| **Legacy code** | 50% | Gradual attribution improvement |
+
+**Detection**:
+- New code: Lines with `^+` in git diff, no prior history
+- Existing code: Modified files with prior commits
+- Legacy code: Files >6 months old or >100 commits
+
+### Enforcement Points
+
+1. **Pre-commit**: Blocks commits lacking provenance
+2. **Pre-push**: Warns on aggregate provenance score <70%
+3. **Runtime**: `cleo complete` validates IMPL-003 for implementation tasks
+4. **Orchestrator**: Validates before spawning implementation agents
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why Avoid |
+|---------|-----------|
+| 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 |
+
+---
+
+*Protocol Version 1.0.0 - Implementation Protocol*