@cluesmith/codev 3.0.0 → 3.0.2

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

@@ -30,7 +30,7 @@ The `-m` / `--model` flag is **always required** except for `consult stats`.
 -m, --model <model>         Model to use (required except stats)
 --prompt <text>              Inline prompt (general mode)
 --prompt-file <path>         Prompt file path (general mode)
---protocol <name>            Protocol: spir, aspir, air, bugfix, tick, maintain
+--protocol <name>            Protocol: spir, aspir, air, bugfix, maintain
 -t, --type <type>            Review type (see below)
 --issue <number>             Issue number (required in architect context)
 --output <path>              Save result to file

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/.claude/skills/update-arch-docs/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: update-arch-docs
+description: Audit, prune, and update the project's architecture documentation — `codev/resources/arch.md` and `codev/resources/lessons-learned.md`. Use this skill when running MAINTAIN's arch-doc step, or when asked to update / audit / prune `codev/resources/arch.md` or `codev/resources/lessons-learned.md`. The skill is opinionated about what NOT to include in these files (per-spec changelogs, exhaustive enumerations, aspirational state, duplicate meta-spec content) and ships two operating modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). It edits files directly via normal file-edit tooling and does not invoke destructive shell commands.
+---
+
+# update-arch-docs
+
+This skill maintains two governance documents:
+
+- `codev/resources/arch.md` — the project's architecture document.
+- `codev/resources/lessons-learned.md` — durable engineering wisdom extracted from reviews.
+
+It is invoked by the MAINTAIN protocol's documentation step, and ad-hoc whenever someone needs to update, audit, or prune either file. The skill is opinionated about *what does not belong* in these files. Use it whenever a doc change touches arch.md or lessons-learned.md, even if the change is just an addition.
+
+## What this skill does NOT do
+
+These are the patterns that have, in practice, caused arch.md and lessons-learned.md to grow without bound. Treat them as bright-line rejections during both audit-mode and diff-mode work.
+
+### In arch.md
+
+- **Per-file enumerations** that go stale the moment they're written. Document the *shape* of a directory and the handful of load-bearing files; do not list every file. `git ls-files` is authoritative; the doc is for orientation.
+- **Per-spec changelog sections** ("Spec 0042 added X, Spec 0073 changed Y"). Architecture is current state, not history. The git log + the spec/review documents own the changelog framing.
+- **Specs/plans tables** that mirror the contents of `codev/specs/` and `codev/plans/`. These are duplicative and rot quickly. Link to the directory; do not paginate it into the doc.
+- **Aspirational state** ("we plan to…", "in the next phase we'll…"). That belongs in the relevant meta-spec or roadmap doc, not in the architecture body. arch.md describes what *is*, not what *might be*.
+- **Date-stamped narrative** ("As of 2026-Q2, the system uses…"). Dates make the doc look fresh while making it harder to maintain. Use git log + commit dates for temporal context.
+- **Duplication of meta-spec content**. If a subsystem has its own meta-spec under `codev/architecture/<domain>.md` or under `codev/specs/`, arch.md should carry a 1-paragraph summary plus a pointer — not a copy.
+- **Retired-component graveyards**. When a component is removed, delete its section. `git log` retains history; an arch.md that describes things that no longer exist is misleading.
+
+### In lessons-learned.md
+
+- **Spec-narrow recipes** that only matter inside the originating feature ("In spec 0073 we found that the rate limiter needs X"). These belong in the spec's review document, not in lessons-learned.md. lessons-learned.md captures patterns that apply *across* specs.
+- **Multi-paragraph entries**. If a lesson needs more than 1–3 sentences to land, it is either two lessons fused together or it is documentation that belongs elsewhere.
+- **Duplicate adjacent entries**. Fold variations of the same lesson into one entry. Two entries that say the same thing are louder, not clearer.
+- **Spec-numbered narrative entries** ("Lesson from #0468:…"). Link to the review if needed; the lesson itself should be stated as a general principle.
+
+### In either file (process)
+
+- **Destructive shell commands**. The skill must not invoke `rm -rf`, `git rm`, or destructive `sed` scripts. All edits go through the normal Edit tool. The MAINTAIN PR diff is the human-confirmation step; that's enough.
+
+## arch.md vs. lessons-learned.md (two-doc framing)
+
+Treat the two files as siblings with different purposes. When in doubt about which file a fact belongs in, route by purpose:
+
+| Purpose | Goes in |
+|---|---|
+| Current system shape — services, transports, key mental models | `arch.md` |
+| Mechanism for a unique subsystem | `arch.md` (subsystem section) — or its own meta-spec if the mechanism is large enough to warrant one, with arch.md keeping a 1-paragraph summary + pointer |
+| Pointers ("see meta-spec X for details") | `arch.md` |
+| A durable engineering pattern that applies across multiple specs | `lessons-learned.md` |
+| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `arch.md` § "Verified-Wrong Assumptions" — *not* lessons-learned.md, because it's a property of the system, not a general pattern |
+
+The "system-shape surprise" routing is the one most often gotten wrong. If a future reader needs to know "the system *looks* like X but actually does Y", that is system shape and lives in arch.md. If they need to know "we learned that doing X is generally a bad idea", that is engineering wisdom and lives in lessons-learned.md.
+
+## Sizing by purpose, not by line count
+
+There is no line-count budget for either file. The right size for each section is determined by what the section needs to do. If a subsystem genuinely has unique mechanism that takes 80 lines to explain clearly, 80 lines is the right size. If a subsystem can be described in 5 lines and a pointer to a meta-spec, 5 lines is right.
+
+What's *wrong* is bulk that comes from any of the patterns in "What this skill does NOT do" above. Strip those, and the file's size will land where it belongs.
+
+When proposing a section, ask: "Could a future reader skip this section without losing anything load-bearing?" If yes, the section should not exist. The doc's purpose is orientation, not completeness.
+
+## Mode: diff-mode (apply a specific change)
+
+Use diff-mode when the request is specific: "add a section about the new caching layer," "update the Glossary entry for Tower," "remove the reference to the deleted dashboard-server."
+
+In diff-mode:
+
+1. Find the smallest section that needs to change.
+2. Apply the change via the Edit tool.
+3. If the change adds new content, run a quick sanity check against "What this skill does NOT do" before saving — make sure the new content is current state, not aspirational; not duplicative of a meta-spec; not a per-spec changelog entry.
+4. Surface the resulting diff for review.
+
+Diff-mode is fast. It is the right mode for ~80% of post-MAINTAIN documentation work.
+
+## Mode: audit-mode (identify what to cut)
+
+Use audit-mode when the request is general: "the doc feels stale," "MAINTAIN says it's time to prune," "review arch.md against the principles."
+
+In audit-mode:
+
+1. Read the file end-to-end.
+2. For each section in arch.md, run through the per-section pruning checklist (from the MAINTAIN protocol):
+   - Does it describe *current state*? If aspirational, the section moves to a meta-spec; the arch.md keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
+   - Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer.
+   - Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files.
+   - Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing.
+   - Is the component still alive? If retired, delete the section entirely.
+3. For each entry in lessons-learned.md, run the per-entry checklist:
+   - Is it cross-applicable beyond the spec that produced it? If no, remove (the lesson belongs in the spec's review).
+   - Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
+   - Is the topic section the right one? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home.
+   - Is it a duplicate of an adjacent entry? If yes, fold them.
+4. **When in doubt, KEEP.** This rule comes from the MAINTAIN protocol and applies in audit-mode too. A confident cut is better than three speculative ones. Bias toward fewer, higher-confidence proposals with clear rationale; do not chase a maximum cut count.
+5. Apply the cuts via the Edit tool — the skill does not produce a "candidate-cuts list and stop." The diff *is* the proposal. The MAINTAIN PR review is the human-confirmation step.
+6. Surface a short reason alongside each cut in the run file (`codev/maintain/NNNN.md`) so PR reviewers can evaluate intent ("removed because: per-spec changelog framing"; "compressed because: duplicates the orchestrator meta-spec").
+
+Audit-mode is slower than diff-mode and produces larger diffs. Reserve it for explicit audit invocations, not for routine doc updates.
+
+## Output contract
+
+The skill commits to the following:
+
+- It edits `codev/resources/arch.md` and `codev/resources/lessons-learned.md` directly via the Edit tool.
+- It does not invoke destructive shell commands (no `rm -rf`, no `git rm`, no destructive `sed`). File deletions happen only through Edit removing the relevant content; whole-file removal would be a structural change that is out of scope for this skill.
+- In audit-mode, every removal is paired with a one-line reason in the MAINTAIN run file's `## Audit Findings` section. Rationale lives there so reviewers can evaluate intent without re-deriving it from the diff.
+- The skill does not modify other files (specs, plans, reviews, source code). If a fact belongs somewhere else, the skill flags it; it does not move it.
+- The skill does not edit live arch.md or lessons-learned.md content as a side effect of being read or invoked — only when the user/MAINTAIN protocol explicitly asks for an update or audit.

package/skeleton/DEPENDENCIES.md

@@ -218,7 +218,7 @@ Ensure no firewall is blocking the ports (default: 4200-4299):
 lsof -i :4200
 
 # Clean up stale port allocations
-af ports cleanup
+afx ports cleanup
 ```
 
 ### gh authentication issues

package/skeleton/builders.md

@@ -1,6 +1,6 @@
 # Active Builders
 
-> **Note**: Builder status is now tracked automatically via SQLite database and the Tower dashboard. Use `af status` to check all builders. This file is retained as a reference for status values only.
+> **Note**: Builder status is now tracked automatically via SQLite database and the Tower dashboard. Use `afx status` to check all builders. This file is retained as a reference for status values only.
 
 ## Status Values
 
@@ -13,7 +13,7 @@
 ## Commands
 
 ```bash
-af status              # Check all builder statuses
-af spawn <id>          # Spawn a new builder
-af cleanup -p <id>     # Clean up a completed builder
+afx status              # Check all builder statuses
+afx spawn <id>          # Spawn a new builder
+afx cleanup -p <id>     # Clean up a completed builder
 ```

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

@@ -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
 
@@ -75,12 +87,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/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

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

@@ -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
 
@@ -74,7 +86,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/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