@cluesmith/codev 3.0.0-rc.1 → 3.0.0-rc.11

package/skeleton/protocols/maintain/templates/maintenance-run.md

@@ -1,64 +1,33 @@
-# Maintenance Run NNN
+# Maintenance Run NNNN
 
-## Metadata
-- **Date**: YYYY-MM-DD
-- **Base Commit**: (commit hash at start)
-- **PR**: #NNN
-- **Scope**: full | code-only | docs-only
+**Date**: YYYY-MM-DD
+**Base Commit**: <hash>
+**PR**: #NNN
 
 ## Changes Since Last Run
 
-<!-- Auto-generated summary of commits since last maintenance -->
+<key commits or summary>
 
-```
-git log --oneline <last-maint-commit>..HEAD
-```
+## What Was Done
 
-## Tasks Completed
+### Dead Code Removed
+- <file>: <item> — <reason>
 
-### Code Hygiene
-- [ ] Dead code removal
-- [ ] Unused dependencies
-- [ ] Dependency updates
-- [ ] Test maintenance
+### Dependencies Cleaned
+- <package> — <reason>
 
-### Documentation
-- [ ] arch.md sync
-- [ ] lessons-learned.md generation
-- [ ] CLAUDE.md / AGENTS.md sync
-- [ ] Documentation pruning (obsolete content, size limits)
+### Documentation Updated
+- arch.md: <what changed>
+- lessons-learned.md: <what changed>
 
-### Framework
-- [ ] codev update
-- [ ] GitHub Issue status updates (close completed, update labels)
-
-## Findings
-
-<!-- Notable discoveries during maintenance -->
-
-## Documentation Changes
-
-<!-- REQUIRED: Log all documentation deletions/moves with justification -->
-
-### arch.md
-| Section | Action | Reason |
-|---------|--------|--------|
-| (example) | KEPT/MOVED/DELETED | (justification) |
-
-### CLAUDE.md
-| Section | Action | Reason |
-|---------|--------|--------|
-| (example) | KEPT/MOVED/DELETED | (justification) |
-
-### README.md
-| Section | Action | Reason |
-|---------|--------|--------|
-| (example) | KEPT/MOVED/DELETED | (justification) |
+### Documentation Changes Log
+| Document | Section | Action | Reason |
+|----------|---------|--------|--------|
 
 ## Deferred
 
-<!-- Items discovered but deferred to next run, with reason -->
+- <items found but not fixed, with reason>
 
 ## Summary
 
-<!-- Brief summary of what was accomplished -->
+<2-3 sentences>

package/skeleton/protocols/protocol-schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "name": {
       "type": "string",
-      "description": "Protocol identifier (e.g., 'spir', 'tick', 'bugfix')"
+      "description": "Protocol identifier (e.g., 'spir', 'bugfix', 'air')"
     },
     "version": {
       "type": "string",

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

@@ -37,7 +37,7 @@ Follow this 3-step workflow. You can skip or reorder steps as the investigation
 - Write findings to `codev/spikes/<id>-<name>.md` using the template
 - Provide a clear feasibility verdict: Feasible / Not Feasible / Feasible with Caveats
 - Commit the findings document
-- Notify the architect: `af send architect "Spike <id> complete. Verdict: [verdict]"`
+- Notify the architect: `afx send architect "Spike <id> complete. Verdict: [verdict]"`
 
 ## Key Principles
 

package/skeleton/protocols/spike/protocol.md

@@ -10,7 +10,7 @@ Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What wo
 
 **Use for**: Quick technical feasibility investigations, proof-of-concept explorations, "can we do X?" questions, evaluating approaches before committing to SPIR
 
-**Skip for**: Production code (use SPIR), formal hypothesis testing (use EXPERIMENT), bug fixes (use BUGFIX), well-understood implementations (use TICK)
+**Skip for**: Production code (use SPIR), formal hypothesis testing (use EXPERIMENT), bug fixes (use BUGFIX)
 
 ### Spike vs Experiment
 
@@ -25,8 +25,8 @@ Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What wo
 ## Spawning a Spike
 
 ```bash
-af spawn --task "Can we use WebSockets for real-time updates?" --protocol spike
-af spawn --task "What would it take to support SQLite FTS?" --protocol spike
+afx spawn --task "Can we use WebSockets for real-time updates?" --protocol spike
+afx spawn --task "What would it take to support SQLite FTS?" --protocol spike
 ```
 
 Spikes are always soft mode — no porch orchestration, no gates, no consultation.
@@ -83,7 +83,7 @@ POC code from the iterate step is committed to the spike branch alongside the fi
 
 In all cases, notify the architect:
 ```bash
-af send architect "Spike <id> complete. Verdict: [feasible/not feasible/caveats]"
+afx send architect "Spike <id> complete. Verdict: [feasible/not feasible/caveats]"
 ```
 
 ## Git Workflow

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

@@ -53,12 +53,35 @@ 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
+4. Repeat
+
+**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 in status.yaml: `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/spir/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/spir/protocol.json

@@ -53,7 +53,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}'"
       },
       "gate": "plan-approval",
@@ -135,6 +135,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/spir/protocol.md

@@ -9,10 +9,10 @@
 ## Prerequisites
 
 **Clean Worktree Before Spawning Builders**:
-- All specs, plans, and local changes **MUST be committed** before `af spawn`
+- All specs, plans, and local changes **MUST be committed** before `afx spawn`
 - Builders work in git worktrees branched from HEAD — uncommitted files are invisible
 - This includes `codev update` results, spec drafts, and plan approvals
-- The `af spawn` command enforces this (use `--force` to override)
+- The `afx spawn` command enforces this (use `--force` to override)
 
 **Required for Multi-Agent Consultation**:
 - The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`)

package/skeleton/protocols/spir/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/spir/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`
-
----
--->