@cluesmith/codev 3.0.0-rc.9 → 3.0.1

package/skeleton/.claude/skills/porch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: porch
-description: Protocol orchestrator CLI — drives SPIR, ASPIR, AIR, TICK, and BUGFIX protocols via a state machine. ALWAYS check this skill before running any `porch` command. Use when you need to check project status, approve gates, signal phase completion, or manage protocol state. Also use when a builder asks about gate approvals or phase transitions.
+description: Protocol orchestrator CLI — drives SPIR, ASPIR, AIR, and BUGFIX protocols via a state machine. ALWAYS check this skill before running any `porch` command. Use when you need to check project status, approve gates, signal phase completion, or manage protocol state. Also use when a builder asks about gate approvals or phase transitions.
 ---
 
 # porch - Protocol Orchestrator
@@ -31,7 +31,7 @@ Gates are human-only approval checkpoints. The `--a-human-explicitly-approved-th
 |------|----------|------|
 | `spec-approval` | SPIR | After spec is written |
 | `plan-approval` | SPIR | After plan is written |
-| `pr` | SPIR, TICK, AIR | After PR is created |
+| `pr` | SPIR, AIR | After PR is created |
 
 ```bash
 porch approve 42 spec-approval --a-human-explicitly-approved-this

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/prompts/pr.md

@@ -15,15 +15,27 @@ Create a pull request with the review embedded in the PR body, optionally run CM
 
 ### 1. Create the Pull Request
 
-Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan:
+Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan.
+
+**PR body requirements**: The PR body MUST include `Closes #<N>` (where `<N>` is
+the driving issue number) so GitHub auto-closes the issue on merge. If the PR
+closes multiple issues (e.g. duplicates consolidated), include one `Closes #<N>`
+per issue. Without this, GitHub will not auto-close the issue.
+
+**Exception**: if this PR only partially addresses the issue, use `Refs #<N>`
+or `Part of #<N>` instead of `Closes` — the issue stays open until a
+follow-up PR closes it.
+
+**Note**: substitute the real issue number for `<N>` — do not leave the
+placeholder or any `{{...}}` template tag in the committed PR body.
 
 ```bash
-gh pr create --title "[Air #{{issue.number}}] feat: <brief description>" --body "$(cat <<'EOF'
+gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the feature>
 
-Implements #{{issue.number}}
+Closes #<N>  <!-- Substitute <N> with the real issue number -->
 
 ## What Changed
 

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**
 

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

@@ -53,11 +53,33 @@ 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 `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}} complete. PR merged. Ready for cleanup."`
+- **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/prompts/review.md

@@ -181,11 +181,22 @@ Before PR:
 porch consultation reviews the actual PR, and the architect can review a real PR
 when the pr gate fires.
 
+**PR body requirements**: The PR body MUST include `Closes #<N>` (for feature issues)
+or `Fixes #<N>` (for bug issues) for the driving GitHub issue. If the PR closes
+multiple issues (e.g. duplicates consolidated), include one keyword per issue.
+Without this, GitHub will not auto-close the issue on merge.
+
+**Exception**: if this PR only partially addresses the issue (e.g. one phase of a
+multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #<N>`
+or `Part of #<N>` instead. The issue stays open until the follow-up PR closes it.
+
 ```bash
 gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
 ## Summary
 [Brief description of the implementation]
 
+Closes #<N>  <!-- Replace <N> with the driving issue number, or use "Refs #<N>" for partial fixes -->
+
 ## Changes
 - [Change 1]
 - [Change 2]

package/skeleton/protocols/aspir/protocol.json

@@ -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/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

@@ -44,7 +44,7 @@ Follow the BUGFIX protocol: `codev/protocols/bugfix/protocol.md`
 
 If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via:
 ```bash
-afx 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

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

@@ -15,15 +15,27 @@ Create a pull request, run CMAP review, and address feedback.
 
 ### 1. Create the Pull Request
 
-Create a PR that links to the issue:
+Create a PR that links to the issue.
+
+**PR body requirements**: The PR body MUST include `Fixes #<N>` (where `<N>` is
+the driving issue number) so GitHub auto-closes the issue on merge. If the PR
+fixes multiple issues (e.g. duplicates consolidated), include one `Fixes #<N>`
+per issue. Without this, GitHub will not auto-close the issue.
+
+**Exception**: if this PR only partially addresses the issue, use `Refs #<N>`
+or `Part of #<N>` instead of `Fixes` — the issue stays open until a
+follow-up PR closes it.
+
+**Note**: substitute the real issue number for `<N>` — do not leave the
+placeholder or any `{{...}}` template tag in the committed PR body.
 
 ```bash
-gh pr create --title "Fix #{{issue.number}}: <brief description>" --body "$(cat <<'EOF'
+gh pr create --title "Fix #<N>: <brief description>" --body "$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the bug and fix>
 
-Fixes #{{issue.number}}
+Fixes #<N>  <!-- Substitute <N> with the real issue number -->
 
 ## Root Cause
 

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

@@ -46,6 +46,21 @@ The EXPERIMENT protocol ensures disciplined experimentation:
 - Document findings regardless of outcome
 - Separate experiment artifacts from production code
 
+## If You Open a PR
+
+Most experiments are committed to a branch without a PR, but if you do open one
+to integrate findings and the experiment was triggered by a GitHub issue:
+
+**PR body requirements**: The PR body MUST include `Closes #<N>` (for feature
+issues) or `Fixes #<N>` (for bug issues) for the driving issue so GitHub
+auto-closes it on merge. If the PR closes multiple issues, include one keyword
+per issue.
+
+**Exception**: if this PR only partially addresses the issue (e.g. experiment
+validates an approach but production implementation is deferred), use
+`Refs #<N>` or `Part of #<N>` instead — the issue stays open until a follow-up
+PR closes it.
+
 ## Handling Flaky Tests
 
 If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):

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,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",