@cluesmith/codev 3.0.0 → 3.0.2

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

@@ -0,0 +1,88 @@
+# MAINTAIN Phase Prompt
+
+You are executing the **maintain** phase — a single pass covering audit, cleanup, and doc sync.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Step 1: Determine Scope
+
+```bash
+ls codev/maintain/
+```
+
+Find the last run number and its base commit. Then see what changed:
+
+```bash
+git log --oneline <base-commit>..HEAD
+```
+
+Create your maintenance run file: `codev/maintain/NNNN.md` (next number in sequence).
+
+## Step 2: Audit
+
+Identify dead code, unused dependencies, and stale documentation. Don't fix yet — catalog first.
+
+```bash
+# Dead exports
+npx ts-prune 2>/dev/null || echo "ts-prune not available"
+
+# Unused dependencies
+npx depcheck 2>/dev/null || echo "depcheck not available"
+
+# Stale arch.md references
+grep -oE '[a-zA-Z]+/[a-zA-Z/]+\.[a-z]+' codev/resources/arch.md | sort -u | while read f; do
+  [ -e "$f" ] || echo "Missing: $f"
+done
+```
+
+Record all findings in the maintenance run file.
+
+## Step 3: Clean
+
+For each audit finding:
+1. Verify it's truly unused (grep the codebase)
+2. Remove with `git rm` (tracked) or move to `codev/maintain/.trash/$(date +%Y-%m-%d)/` (untracked)
+3. Build and test: `cd packages/codev && pnpm build && pnpm test`
+4. Commit: `git add <specific-files> && git commit -m "[Maintain] Remove unused X"`
+
+One removal at a time. Verify after each. Never use `git add -A`.
+
+## Step 4: Sync Documentation
+
+**arch.md**: Read `codev/resources/arch.md`, compare with actual codebase. Update directory structure, component descriptions, key files. Remove references to deleted code. Add new components. Explain HOW things work, not just WHAT.
+
+**lessons-learned.md**: Scan `codev/reviews/` for new reviews since the base commit. Extract actionable, durable, general lessons.
+
+**CLAUDE.md / AGENTS.md**: `diff CLAUDE.md AGENTS.md` — they must be identical. Update the stale one.
+
+**Pruning**: Remove obsolete content. Document every deletion with justification (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE). When in doubt, keep.
+
+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"
+```
+
+## Step 5: Final Checks
+
+```bash
+cd packages/codev && pnpm build && pnpm test
+```
+
+Both must pass. Update the maintenance run file with a summary of everything done.
+
+## Signals
+
+When all work is complete and build/tests pass:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

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

@@ -0,0 +1,84 @@
+# REVIEW Phase Prompt
+
+You are executing the **review** phase of the MAINTAIN protocol.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Final Validation
+
+```bash
+cd packages/codev && pnpm build && pnpm test
+```
+
+Both must pass. If either fails, fix before proceeding.
+
+### 2. Verify Documentation Links
+
+```bash
+grep -oE '[a-zA-Z]+/[a-zA-Z/]+\.[a-z]+' codev/resources/arch.md | sort -u | while read f; do
+  [ -e "$f" ] || echo "Missing: $f"
+done
+```
+
+### 3. Finalize Maintenance Run File
+
+Update `codev/maintain/NNNN.md` with:
+- PR number (once created)
+- Final summary of what was done
+- Deferred items (if any)
+
+### 4. Create PR
+
+**PR body requirements**: If this maintenance run was triggered by a GitHub issue
+(e.g. "track down dead X", "clean up Y module"), the PR body MUST include
+`Closes #<N>` for that issue so GitHub auto-closes it on merge. If multiple
+issues are addressed in one run, include one `Closes #<N>` per issue.
+
+**Exception**: if this PR only partially addresses a tracking issue (e.g. more
+cleanup passes are planned), use `Refs #<N>` or `Part of #<N>` instead.
+
+If the run was not tied to any issue, the `Closes` line can be omitted.
+
+```bash
+git push origin HEAD
+
+gh pr create --title "[Maintain] Codebase maintenance run NNNN" --body "$(cat <<'PREOF'
+## Summary
+
+<2-3 bullet points of what was done>
+
+Closes #<N>  <!-- Only if this run was triggered by a GitHub issue. Use "Refs #<N>" for partial cleanup. -->
+
+## Changes
+
+- Dead code removed: X items
+- Dependencies cleaned: Y packages
+- Documentation updated: arch.md, lessons-learned.md
+- Tests: all passing
+
+## Test plan
+
+- [x] Build passes
+- [x] All tests pass
+- [x] Documentation links resolve
+PREOF
+)"
+```
+
+## Signals
+
+When PR is created:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

package/skeleton/protocols/maintain/protocol.json

@@ -2,8 +2,8 @@
   "$schema": "../../protocol-schema.json",
   "name": "maintain",
   "alias": "maint",
-  "version": "2.0.0",
-  "description": "Codebase maintenance - dead code removal, doc sync, hygiene with 3-way review",
+  "version": "3.0.0",
+  "description": "Codebase maintenance — single-pass hygiene, doc sync, and cleanup with PR review",
   "input": {
     "type": "protocol",
     "required": false,
@@ -11,12 +11,12 @@
   },
   "phases": [
     {
-      "id": "audit",
-      "name": "Audit",
-      "description": "Analyze codebase for dead code, unused dependencies, stale docs",
+      "id": "maintain",
+      "name": "Maintain",
+      "description": "Single-pass: audit, clean dead code, sync docs, verify build",
       "type": "build_verify",
       "build": {
-        "prompt": "audit.md",
+        "prompt": "maintain.md",
         "artifact": "codev/maintain/*.md"
       },
       "verify": {
@@ -24,27 +24,6 @@
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 3,
-      "on_complete": {
-        "commit": true,
-        "push": true
-      },
-      "next": "clean"
-    },
-    {
-      "id": "clean",
-      "name": "Clean",
-      "description": "Remove identified dead code and unused dependencies",
-      "type": "build_verify",
-      "build": {
-        "prompt": "clean.md",
-        "artifact": "src/**/*.{ts,tsx,js,jsx}"
-      },
-      "verify": {
-        "type": "impl",
-        "models": ["gemini", "codex", "claude"],
-        "parallel": true
-      },
       "max_iterations": 5,
       "on_complete": {
         "commit": true,
@@ -52,46 +31,25 @@
       },
       "checks": {
         "build": {
-          "command": "npm run build",
+          "command": "pnpm build",
           "on_fail": "retry",
           "max_retries": 2
         },
         "tests": {
-          "command": "npm test -- --exclude='**/e2e/**'",
+          "command": "pnpm test",
           "on_fail": "retry",
           "max_retries": 2
         }
       },
-      "next": "sync"
-    },
-    {
-      "id": "sync",
-      "name": "Sync Documentation",
-      "description": "Update documentation to match current codebase",
-      "type": "build_verify",
-      "build": {
-        "prompt": "sync.md",
-        "artifact": "codev/resources/*.md"
-      },
-      "verify": {
-        "type": "impl",
-        "models": ["gemini", "codex", "claude"],
-        "parallel": true
-      },
-      "max_iterations": 5,
-      "on_complete": {
-        "commit": true,
-        "push": true
-      },
-      "next": "verify"
+      "next": "review"
     },
     {
-      "id": "verify",
-      "name": "Verify",
-      "description": "Final validation and PR creation",
+      "id": "review",
+      "name": "Review",
+      "description": "Final validation, PR creation, 3-way review",
       "type": "build_verify",
       "build": {
-        "prompt": "verify.md",
+        "prompt": "review.md",
         "artifact": "codev/maintain/*.md"
       },
       "verify": {
@@ -104,18 +62,6 @@
         "commit": true,
         "push": true
       },
-      "checks": {
-        "build": {
-          "command": "npm run build",
-          "on_fail": "retry",
-          "max_retries": 2
-        },
-        "tests": {
-          "command": "npm test",
-          "on_fail": "retry",
-          "max_retries": 2
-        }
-      },
       "gate": "maintain-complete",
       "next": null
     }
@@ -123,7 +69,7 @@
   "signals": {
     "PHASE_COMPLETE": {
       "description": "Signal current phase is complete",
-      "transitions_to": "verify"
+      "transitions_to": "review"
     },
     "BLOCKED": {
       "description": "Signal maintenance is blocked",