@cluesmith/codev 2.0.0-rc.6 → 2.0.0-rc.61

package/skeleton/protocols/experiment/protocol.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "experiment",
+  "version": "1.0.0",
+  "description": "Disciplined experimentation with hypothesis testing",
+  "input": {
+    "type": "none",
+    "required": false,
+    "default_for": []
+  },
+  "hooks": {
+    "pre-spawn": {}
+  },
+  "phases": [
+    {
+      "id": "hypothesis",
+      "name": "Hypothesis",
+      "description": "Define the hypothesis and success criteria",
+      "type": "once",
+      "steps": [
+        "define_hypothesis",
+        "define_success_criteria",
+        "define_scope",
+        "create_experiment_doc"
+      ],
+      "transition": {
+        "on_complete": "design"
+      }
+    },
+    {
+      "id": "design",
+      "name": "Design",
+      "description": "Design the experiment approach",
+      "type": "once",
+      "steps": [
+        "choose_approach",
+        "identify_dependencies",
+        "plan_implementation",
+        "define_measurements"
+      ],
+      "transition": {
+        "on_complete": "execute"
+      }
+    },
+    {
+      "id": "execute",
+      "name": "Execute",
+      "description": "Run the experiment",
+      "type": "once",
+      "steps": [
+        "implement_prototype",
+        "gather_data",
+        "document_findings"
+      ],
+      "transition": {
+        "on_complete": "analyze"
+      }
+    },
+    {
+      "id": "analyze",
+      "name": "Analyze",
+      "description": "Analyze results and draw conclusions",
+      "type": "once",
+      "steps": [
+        "analyze_data",
+        "evaluate_hypothesis",
+        "document_conclusions",
+        "recommend_next_steps"
+      ],
+      "gate": {
+        "name": "experiment-complete",
+        "description": "Experiment complete",
+        "requires": ["conclusions_documented"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "BLOCKED": {
+      "description": "Signal experiment is blocked",
+      "requires": "reason"
+    },
+    "HYPOTHESIS_REJECTED": {
+      "description": "Signal hypothesis was disproven",
+      "transitions_to": "analyze"
+    }
+  },
+  "defaults": {
+    "mode": "soft",
+    "consultation": {
+      "enabled": false,
+      "models": [],
+      "parallel": false
+    },
+    "checks": {}
+  }
+}

package/skeleton/protocols/experiment/protocol.md

@@ -10,7 +10,7 @@ Disciplined experimentation: Each experiment gets its own directory with `notes.
 
 **Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes
 
-**Skip for**: Production code (use SPIDER), simple one-off scripts, well-understood implementations (use TICK)
+**Skip for**: Production code (use SPIR), simple one-off scripts, well-understood implementations (use TICK)
 
 ## Structure
 
@@ -141,7 +141,7 @@ What should be done based on findings?
 
 ## Integration with Other Protocols
 
-### Experiment → SPIDER
+### Experiment → SPIR
 When an experiment validates an approach for production use:
 
 1. Create a specification referencing the experiment
@@ -225,5 +225,5 @@ Determine if Redis caching improves API response times for repeated queries.
 - Memory usage: 50MB for 10k cached responses
 
 ## Next Steps
-Create SPIDER spec for production caching implementation.
+Create SPIR spec for production caching implementation.
 ```

package/skeleton/protocols/experiment/templates/notes.md

@@ -88,7 +88,7 @@ Based on these findings:
 
 1. **Immediate**: What should happen right after this experiment?
 2. **Follow-up experiments**: What new questions emerged?
-3. **Production path**: If validated, what's needed for production? (SPIDER spec?)
+3. **Production path**: If validated, what's needed for production? (SPIR spec?)
 
 ## References
 

package/skeleton/protocols/maintain/builder-prompt.md

@@ -0,0 +1,46 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are executing the MAINTAIN protocol to clean up and synchronize the codebase.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the MAINTAIN protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Work through each phase methodically
+{{/if}}
+
+{{#if mode_strict}}
+## Mode: STRICT
+You are running in STRICT mode. This means:
+- Porch orchestrates your work
+- Run: `porch run {{project_id}}`
+- Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
+{{/if}}
+
+## Protocol
+Follow the MAINTAIN protocol: `codev/protocols/maintain/protocol.md`
+
+## MAINTAIN Overview
+The MAINTAIN protocol handles codebase hygiene:
+
+1. **Audit Phase**: Scan for dead code, unused dependencies, stale docs
+2. **Clean Phase**: Remove identified cruft, verify build
+3. **Sync Phase**: Update documentation (arch.md, lessons-learned.md, CLAUDE.md)
+4. **Verify Phase**: Run full test suite, confirm health
+
+## Key Rules
+- Use soft deletion (move to `codev/maintain/.trash/`)
+- Always verify build passes after removals
+- Update documentation to match current architecture
+- Don't remove anything actively used
+
+## Getting Started
+1. Read the MAINTAIN protocol document
+2. Start with the Audit phase
+3. Document all changes made

package/skeleton/protocols/maintain/prompts/audit.md

@@ -0,0 +1,111 @@
+# AUDIT Phase Prompt
+
+You are executing the **AUDIT** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Analyze the codebase to identify dead code, unused dependencies, and stale documentation.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Determine Base Commit
+
+Find the last maintenance run:
+```bash
+ls codev/maintain/
+```
+
+If previous runs exist, note the base commit to focus on changes since then.
+
+### 2. Scan for Dead Code
+
+Run static analysis tools:
+
+```bash
+# TypeScript/JavaScript
+npx ts-prune 2>/dev/null || echo "ts-prune not available"
+npx depcheck 2>/dev/null || echo "depcheck not available"
+
+# Check for unused exports
+grep -r "export " --include="*.ts" --include="*.tsx" | head -50
+```
+
+### 3. Scan for Unused Dependencies
+
+Check package.json for unused dependencies:
+```bash
+cat package.json | grep -A100 '"dependencies"' | head -50
+```
+
+Cross-reference with actual imports in the codebase.
+
+### 4. Scan for Stale Documentation
+
+Check for references to deleted files/functions:
+```bash
+# Recent changes
+git log --oneline -20
+
+# Check if arch.md references exist
+grep -E "src/|packages/" codev/resources/arch.md | head -20
+```
+
+### 5. Create Audit Report
+
+Create a maintenance run file: `codev/maintain/NNNN.md`
+
+Document:
+- Dead code identified (with file paths)
+- Unused dependencies
+- Stale documentation references
+- Recommended actions
+
+Use the template structure:
+```markdown
+# Maintenance Run NNNN
+
+**Date**: YYYY-MM-DD
+**Base Commit**: <commit-hash>
+
+## Dead Code Identified
+
+| File | Item | Reason |
+|------|------|--------|
+| path/to/file.ts | unusedFunction() | Not imported anywhere |
+
+## Unused Dependencies
+
+| Package | Reason |
+|---------|--------|
+| some-pkg | Not imported |
+
+## Stale Documentation
+
+| Document | Issue |
+|----------|-------|
+| arch.md | References deleted module |
+
+## Recommended Actions
+
+1. Remove X
+2. Update Y
+3. ...
+```
+
+## Signals
+
+When audit report is complete:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

package/skeleton/protocols/maintain/prompts/clean.md

@@ -0,0 +1,91 @@
+# CLEAN Phase Prompt
+
+You are executing the **CLEAN** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Remove the dead code and unused dependencies identified in the audit phase.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Prerequisites
+
+Read the audit report from the previous phase:
+```bash
+ls -la codev/maintain/
+cat codev/maintain/*.md | tail -100
+```
+
+## Process
+
+### 1. Remove Dead Code
+
+For each item identified in the audit:
+
+1. Verify it's truly unused (double-check with grep)
+2. Use `git rm` for tracked files
+3. For untracked files, move to `.trash/` before deleting
+
+**CRITICAL**: Use soft deletion first:
+```bash
+mkdir -p codev/maintain/.trash/$(date +%Y-%m-%d)
+mv path/to/file codev/maintain/.trash/$(date +%Y-%m-%d)/
+```
+
+### 2. Remove Unused Dependencies
+
+```bash
+# Remove from package.json
+npm uninstall <package-name>
+```
+
+### 3. Verify Build After Each Removal
+
+After each significant removal:
+```bash
+npm run build
+npm test -- --exclude='**/e2e/**'
+```
+
+If build fails, revert the change and investigate.
+
+### 4. Commit Changes
+
+Make atomic commits for each logical change:
+```bash
+git add <specific-files>
+git commit -m "[Maintain] Remove unused X"
+```
+
+**NEVER use `git add -A` or `git add .`**
+
+## Important Rules
+
+1. **One removal at a time** - Don't batch unrelated changes
+2. **Verify after each removal** - Build must pass
+3. **Document what was removed** - Update the maintenance run file
+4. **Soft delete first** - Move to .trash/ before permanent deletion
+5. **Check for side effects** - Grep for references before removing
+
+## Output
+
+Update the maintenance run file with:
+- What was removed
+- Build/test status after removal
+- Any issues encountered
+
+## Signals
+
+When all dead code is removed and build passes:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

package/skeleton/protocols/maintain/prompts/sync.md

@@ -0,0 +1,113 @@
+# SYNC Phase Prompt
+
+You are executing the **SYNC** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Update documentation to match the current state of the codebase.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Update arch.md
+
+Read the current architecture doc and compare with actual codebase:
+
+```bash
+cat codev/resources/arch.md
+ls -la packages/ src/ 2>/dev/null
+```
+
+Update:
+- Directory structure (if changed)
+- Component descriptions
+- Key files and their purposes
+- Remove references to deleted code
+- Add new utilities/components
+
+**arch.md must explain HOW things work, not just WHAT they are.**
+
+### 2. Generate/Update lessons-learned.md
+
+Scan review documents for lessons:
+
+```bash
+ls codev/reviews/
+```
+
+Extract actionable lessons:
+- Testing practices
+- Architecture decisions
+- Process improvements
+- Patterns to follow/avoid
+
+Format:
+```markdown
+## [Topic]
+- [From NNNN] Lesson description
+```
+
+### 3. Sync CLAUDE.md with AGENTS.md
+
+Compare the two files:
+```bash
+diff CLAUDE.md AGENTS.md | head -50
+```
+
+They must be identical. Update the stale one to match.
+
+### 4. Prune Documentation
+
+Check document sizes:
+```bash
+wc -l CLAUDE.md AGENTS.md README.md
+```
+
+Target ~400 lines for CLAUDE.md/README.md (guideline, not mandate).
+
+For any content removed, document:
+- WHAT was removed
+- WHY it was removed (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE)
+- WHERE it moved (if applicable)
+
+### 5. Commit Documentation Changes
+
+```bash
+git add codev/resources/arch.md codev/resources/lessons-learned.md
+git commit -m "[Maintain] Update arch.md and lessons-learned.md"
+
+git add CLAUDE.md AGENTS.md
+git commit -m "[Maintain] Sync CLAUDE.md with AGENTS.md"
+```
+
+## Important Rules
+
+1. **Never invent structure** - Only document what exists
+2. **Verify file paths** - Check that referenced files exist
+3. **Keep it current** - Remove obsolete references
+4. **Preserve important content** - Don't delete patterns/best practices
+5. **Document deletions** - Every removal needs justification
+
+## Output
+
+Update the maintenance run file with:
+- Documents updated
+- What was added/removed/changed
+- Any issues encountered
+
+## Signals
+
+When documentation is synchronized:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

package/skeleton/protocols/maintain/prompts/verify.md

@@ -0,0 +1,110 @@
+# VERIFY Phase Prompt
+
+You are executing the **VERIFY** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Run final validation and prepare for PR creation.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Run Full Test Suite
+
+```bash
+npm run build
+npm test
+```
+
+Both must pass. If either fails, go back and fix the issue.
+
+### 2. Run Linting
+
+```bash
+npm run lint 2>/dev/null || echo "No lint script"
+```
+
+Fix any linting errors.
+
+### 3. Verify Documentation Links
+
+Check that documentation references resolve:
+```bash
+# Check arch.md file references
+grep -oE 'src/[^ ]+|packages/[^ ]+' codev/resources/arch.md | while read f; do
+  [ -e "$f" ] || echo "Missing: $f"
+done
+```
+
+### 4. Update Maintenance Run Summary
+
+Finalize the maintenance run file with:
+
+```markdown
+## Summary
+
+- **Dead code removed**: X files, Y functions
+- **Dependencies removed**: Z packages
+- **Documentation updated**: arch.md, lessons-learned.md
+- **All tests passing**: Yes/No
+- **Build status**: Success/Failure
+
+## Next Maintenance
+
+Recommended focus areas for next run:
+- ...
+```
+
+### 5. Create PR
+
+```bash
+git push origin HEAD
+
+gh pr create --title "[Maintain] Codebase maintenance run NNNN" --body "$(cat <<'EOF'
+## Summary
+
+- Dead code removal
+- Documentation sync
+- Dependency cleanup
+
+## Changes
+
+[List key changes]
+
+## Verification
+
+- [x] Build passes
+- [x] Tests pass
+- [x] Documentation updated
+EOF
+)"
+```
+
+## Validation Checklist
+
+Before signaling complete:
+
+- [ ] All tests pass
+- [ ] Build succeeds
+- [ ] No import/module errors
+- [ ] Documentation links resolve
+- [ ] Linter passes (if configured)
+- [ ] Maintenance run file is complete
+- [ ] PR is created
+
+## Signals
+
+When validation passes and PR is ready:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```