@cluesmith/codev 3.0.0-rc.0 → 3.0.0-rc.10

package/skeleton/protocol-schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://codev.dev/protocol-schema.json",
   "title": "Codev Protocol Definition",
-  "description": "Schema for porch protocol definitions (SPIR, TICK, BUGFIX, etc.)",
+  "description": "Schema for porch protocol definitions (SPIR, BUGFIX, AIR, etc.)",
   "type": "object",
   "required": ["name", "phases"],
   "properties": {
@@ -12,7 +12,7 @@
     },
     "name": {
       "type": "string",
-      "description": "Protocol name (e.g., 'spir', 'tick', 'bugfix')",
+      "description": "Protocol name (e.g., 'spir', 'bugfix', 'air')",
       "pattern": "^[a-z][a-z0-9-]*$"
     },
     "alias": {

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

@@ -38,20 +38,20 @@ Follow the AIR protocol: `codev/protocols/air/protocol.md`
 2. Implement the feature (< 300 LOC)
 3. Write tests for the feature
 4. Create PR with review in the PR body (NOT as a separate file)
-5. Notify architect via `af send architect "PR #N ready for review (implements #{{issue.number}})"`
+5. Notify architect via `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
 
 **IMPORTANT**: AIR produces NO spec, plan, or review files. The review goes in the PR body.
 
 If the feature is too complex (> 300 LOC or architectural changes), notify the Architect via:
 ```bash
-af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR."
+afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR."
 ```
 
 ## Notifications
-Always use `af send architect "..."` to notify the architect at key moments:
-- **PR ready**: `af send architect "PR #N ready for review (implements #{{issue.number}})"`
-- **PR merged**: `af send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
-- **Blocked**: `af send architect "Blocked on issue #{{issue.number}}: [reason]"`
+Always use `afx send architect "..."` to notify the architect at key moments:
+- **PR ready**: `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
+- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
+- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"`
 {{/if}}
 
 ## Handling Flaky Tests

package/skeleton/protocols/air/prompts/pr.md

@@ -75,12 +75,12 @@ If you ran CMAP:
 Send notification with PR link:
 
 ```bash
-af send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
+afx send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
 ```
 
 If CMAP was run, include verdicts:
 ```bash
-af send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
+afx send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
 ```
 
 ## Signals

package/skeleton/protocols/air/protocol.md

@@ -34,7 +34,6 @@ AIR is a minimal protocol for implementing small features (< 300 LOC) where the
 
 - Bug fixes → use **BUGFIX**
 - Features needing spec discussion → use **SPIR** or **ASPIR**
-- Amendments to existing specs → use **TICK**
 - Architectural changes → use **SPIR**
 - Complex features with multiple phases → use **SPIR** or **ASPIR**
 
@@ -67,7 +66,7 @@ The **PR gate** is preserved — a human reviews all code before merge.
 
 ```bash
 # Spawn a builder using AIR
-af spawn 42 --protocol air
+afx spawn 42 --protocol air
 
 # The builder implements autonomously and stops at the PR gate
 ```

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

@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
+Follow the ASPIR protocol: `codev/protocols/aspir/protocol.md`
 Read and internalize the protocol before starting any work.
 
 {{#if spec}}
@@ -53,12 +53,34 @@ Follow the implementation plan at: `{{plan.path}}`
 {{task_text}}
 {{/if}}
 
+## Multi-PR Workflow
+
+Your worktree is persistent — it survives across PR merges. You can produce multiple PRs sequentially:
+
+1. Cut a branch, open a PR, wait for merge
+2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
+3. Continue to the next phase, open another PR
+
+**Important**: Do NOT run `git checkout main` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/main` via fetch.
+
+Record PRs: `porch done {{project_id}} --pr <N> --branch <name>`
+Record merges: `porch done {{project_id}} --merged <N>`
+
+## Verify Phase
+
+After the final PR merges, the project enters the **verify** phase. You stay alive through verify:
+1. Pull main into your worktree
+2. Run `porch done {{project_id}}` to signal verification is ready
+3. The architect approves `verify-approval` when satisfied
+
+If verification is not needed: `porch verify {{project_id}} --skip "reason"`
+
 ## Notifications
-Always use `af send architect "..."` to notify the architect at key moments:
-- **Gate reached**: `af send architect "Project {{project_id}}: <gate-name> ready for approval"`
-- **PR ready**: `af send architect "PR #N ready for review (project {{project_id}})"`
-- **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."`
-- **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"`
+Always use `afx send architect "..."` to notify the architect at key moments:
+- **Gate reached**: `afx send architect "Project {{project_id}}: <gate-name> ready for approval"`
+- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"`
+- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."`
+- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"`
 
 ## Handling Flaky Tests
 

package/skeleton/protocols/aspir/protocol.json

@@ -51,7 +51,7 @@
       },
       "checks": {
         "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md",
-        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_TITLE}.md",
+        "has_phases_json": "grep -qE '\"phases\"\\s*:' codev/plans/${PROJECT_TITLE}.md",
         "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_TITLE}.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
       },
       "next": "implement"
@@ -132,6 +132,14 @@
         }
       },
       "gate": "pr",
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify",
+      "description": "Post-merge environmental verification (optional — skip with porch verify --skip)",
+      "type": "once",
+      "gate": "verify-approval",
       "next": null
     }
   ],

package/skeleton/protocols/aspir/protocol.md

@@ -61,7 +61,7 @@ Final review, PR preparation, and 3-way review. **PR gate preserved** — builde
 
 ```bash
 # Spawn a builder using ASPIR
-af spawn 42 --protocol aspir
+afx spawn 42 --protocol aspir
 
 # The builder runs autonomously through Specify → Plan → Implement
 # and stops only at the PR gate in the Review phase

package/skeleton/protocols/aspir/templates/plan.md

@@ -182,23 +182,3 @@ Phase 1 ──→ Phase 2 ──→ Phase 3
 ## Notes
 [Additional context, assumptions, or considerations]
 
----
-
-## Amendment History
-
-This section tracks all TICK amendments to this plan. TICKs modify both the spec and plan together as an atomic unit.
-
-<!-- When adding a TICK amendment, add a new entry below this line in chronological order -->
-
-<!--
-### TICK-001: [Amendment Title] (YYYY-MM-DD)
-
-**Changes**:
-- [Phase added]: [Description of new phase]
-- [Phase modified]: [What was updated]
-- [Implementation steps]: [New steps added]
-
-**Review**: See `reviews/####-name-tick-001.md`
-
----
--->

package/skeleton/protocols/aspir/templates/spec.md

@@ -152,31 +152,3 @@ Note: All consultation feedback has been incorporated directly into the relevant
 ## Notes
 [Any additional context or considerations not covered above]
 
----
-
-## Amendments
-
-This section tracks all TICK amendments to this specification. TICKs are lightweight changes that refine an existing spec rather than creating a new one.
-
-<!-- When adding a TICK amendment, add a new entry below this line in chronological order -->
-
-<!--
-### TICK-001: [Amendment Title] (YYYY-MM-DD)
-
-**Summary**: [One-line description of what changed]
-
-**Problem Addressed**:
-[Why this amendment was needed - what gap or issue in the original spec]
-
-**Spec Changes**:
-- [Section modified]: [What changed and why]
-- [New section added]: [Purpose]
-
-**Plan Changes**:
-- [Phase added/modified]: [Description]
-- [Implementation steps]: [What was updated]
-
-**Review**: See `reviews/####-name-tick-001.md`
-
----
--->

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

@@ -40,18 +40,18 @@ Follow the BUGFIX protocol: `codev/protocols/bugfix/protocol.md`
 3. Implement fix (< 300 LOC)
 4. Add regression test
 5. Create PR with "Fixes #{{issue.number}}" in body
-6. Notify architect via `af send architect "PR #N ready for review (fixes #{{issue.number}})"`
+6. Notify architect via `afx send architect "PR #N ready for review (fixes #{{issue.number}})"`
 
 If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via:
 ```bash
-af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIR/TICK."
+afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIR."
 ```
 
 ## Notifications
-Always use `af send architect "..."` to notify the architect at key moments:
-- **PR ready**: `af send architect "PR #N ready for review (fixes #{{issue.number}})"`
-- **PR merged**: `af send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
-- **Blocked**: `af send architect "Blocked on issue #{{issue.number}}: [reason]"`
+Always use `afx send architect "..."` to notify the architect at key moments:
+- **PR ready**: `afx send architect "PR #N ready for review (fixes #{{issue.number}})"`
+- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
+- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"`
 {{/if}}
 
 ## Handling Flaky Tests

package/skeleton/protocols/bugfix/prompts/pr.md

@@ -74,7 +74,7 @@ You must have three concrete verdicts (e.g., "gemini: APPROVE, codex: APPROVE, c
 Send a **single** notification that includes the PR link and each model's verdict:
 
 ```bash
-af send architect "PR #<number> ready for review (fixes issue #{{issue.number}}). CMAP: gemini=<APPROVE|REQUEST_CHANGES>, codex=<APPROVE|REQUEST_CHANGES>, claude=<APPROVE|REQUEST_CHANGES>"
+afx send architect "PR #<number> ready for review (fixes issue #{{issue.number}}). CMAP: gemini=<APPROVE|REQUEST_CHANGES>, codex=<APPROVE|REQUEST_CHANGES>, claude=<APPROVE|REQUEST_CHANGES>"
 ```
 
 **This is the only notification you send.** After this, your work is done — the architect

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 SPIR), simple one-off scripts, well-understood implementations (use TICK)
+**Skip for**: Production code (use SPIR), simple one-off scripts
 
 ## Structure
 
@@ -156,11 +156,6 @@ Experiment 5 validated that [approach] achieves [results].
 See: experiments/5_validation_test/notes.md
 ```
 
-### Experiment → TICK
-For small, validated changes discovered during experimentation:
-- Use TICK for quick implementation
-- Reference experiment as justification
-
 ## Numbering Convention
 
 Use four-digit sequential numbering (consistent with project list):

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

@@ -7,7 +7,7 @@ You are executing the MAINTAIN protocol to clean up and synchronize the codebase
 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
+- Work through each step methodically
 {{/if}}
 
 {{#if mode_strict}}
@@ -20,25 +20,25 @@ You are running in STRICT mode. This means:
 ### 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
+Two phases:
+1. **Maintain**: Single pass — audit findings, clean dead code, sync docs, verify build
+2. **Review**: Create PR with 3-way consultation
 
 ## Key Rules
 - Use soft deletion (move to `codev/maintain/.trash/`)
-- Always verify build passes after removals
+- Verify build passes after each removal (`cd packages/codev && pnpm build && pnpm test`)
 - Update documentation to match current architecture
 - Don't remove anything actively used
+- One removal at a time — commit after each
+- Document every deletion with justification
+- Never use `git add -A` or `git add .`
 
 ## Handling Flaky Tests
 
@@ -46,10 +46,11 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
 1. **DO NOT** edit `status.yaml` to bypass checks
 2. **DO NOT** skip porch checks or use any workaround to avoid the failure
 3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
-4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
+4. **DO** document each skipped flaky test in your maintenance run file
 5. Commit the skip and continue with your work
 
 ## Getting Started
 1. Read the MAINTAIN protocol document
-2. Start with the Audit phase
-3. Document all changes made
+2. Run `porch next` to get your first task
+3. Work through audit → clean → sync → verify in a single pass
+4. Document everything in the maintenance run file

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,72 @@
+# 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
+
+```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>
+
+## 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",