@cluesmith/codev 3.1.9 → 3.2.1

package/skeleton/porch/prompts/review.md

@@ -137,17 +137,25 @@ Read the consultation output files from the project directory (`codev/projects/{
 
 **MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing.
 
-**Architecture Updates** (`codev/resources/arch.md`):
-1. Read the current `codev/resources/arch.md`
-2. Determine if this project introduced architectural changes worth documenting (new subsystems, data flows, design decisions, invariants, file locations)
-3. If yes: make the updates to arch.md and describe what you changed in the `## Architecture Updates` section of the review
-4. If no: write "No architecture updates needed" in the section with a brief explanation (e.g., "This was a template-only change with no new subsystems or data flows")
-
-**Lessons Learned Updates** (`codev/resources/lessons-learned.md`):
-1. Read the current `codev/resources/lessons-learned.md`
-2. Determine if this project produced generalizable lessons (patterns, anti-patterns, debugging insights, process improvements)
-3. If yes: add entries to lessons-learned.md and describe what you added in the `## Lessons Learned Updates` section of the review
-4. If no: write "No lessons learned updates needed" in the section with a brief explanation (e.g., "Straightforward implementation with no novel insights beyond existing entries")
+Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive:
+- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer.
+- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference.
+
+**Architecture Updates**:
+1. Read `arch-critical.md` (hot) and skim `arch.md` (cold).
+2. If this project produced a system-shape fact, route it:
+   - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate.
+   - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold).
+3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason.
+
+**Lessons Learned Updates**:
+1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold).
+2. If this project produced a durable lesson, route it:
+   - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full).
+   - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file.
+3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason.
+
+**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject.
 
 ### 2. Create Pull Request
 

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

@@ -24,7 +24,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the AIR protocol: `codev/protocols/air/protocol.md`
+Follow the AIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 ## Baked Decisions
 
@@ -73,3 +73,9 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
 1. Read the AIR protocol
 2. Review the issue details
 3. Implement the feature
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

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

@@ -27,8 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the ASPIR protocol: `codev/protocols/aspir/protocol.md`
-Read and internalize the protocol before starting any work.
+Follow the ASPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 ## Baked Decisions
 
@@ -111,3 +110,9 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
 1. Read the protocol document thoroughly
 2. Review the spec and plan (if available)
 3. Begin implementation following the protocol phases
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

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

@@ -74,41 +74,9 @@ After completing the plan draft, signal completion. Porch will run 3-way consult
 
 ## Output
 
-Create the plan file at `codev/plans/{{artifact_name}}.md`.
+Create the plan file at `codev/plans/{{artifact_name}}.md`, following the template below:
 
-Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
-
-### Plan Structure
-
-```markdown
-# Implementation Plan: {{title}}
-
-## Overview
-Brief summary of what will be implemented.
-
-## Phases
-
-### Phase 1: [Name]
-- **Objective**: [Single clear goal]
-- **Files**: [List of files to create/modify]
-- **Dependencies**: None
-- **Success Criteria**: [How to verify completion]
-- **Tests**: [What tests will be written]
-
-### Phase 2: [Name]
-- **Objective**: [Single clear goal]
-- **Files**: [List of files]
-- **Dependencies**: Phase 1
-- **Success Criteria**: [Verification method]
-- **Tests**: [Test approach]
-
-[Continue for all phases...]
-
-## Risk Assessment
-- [Risk 1]: [Mitigation]
-- [Risk 2]: [Mitigation]
-
-```
+{{> protocols/spir/templates/plan.md}}
 
 ## Signals
 

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

@@ -148,17 +148,25 @@ Read the consultation output files from the project directory (`codev/projects/{
 
 **MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing.
 
-**Architecture Updates** (`codev/resources/arch.md`):
-1. Read the current `codev/resources/arch.md`
-2. Determine if this project introduced architectural changes worth documenting (new subsystems, data flows, design decisions, invariants, file locations)
-3. If yes: make the updates to arch.md and describe what you changed in the `## Architecture Updates` section of the review
-4. If no: write "No architecture updates needed" in the section with a brief explanation (e.g., "This was a template-only change with no new subsystems or data flows")
-
-**Lessons Learned Updates** (`codev/resources/lessons-learned.md`):
-1. Read the current `codev/resources/lessons-learned.md`
-2. Determine if this project produced generalizable lessons (patterns, anti-patterns, debugging insights, process improvements)
-3. If yes: add entries to lessons-learned.md and describe what you added in the `## Lessons Learned Updates` section of the review
-4. If no: write "No lessons learned updates needed" in the section with a brief explanation (e.g., "Straightforward implementation with no novel insights beyond existing entries")
+Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive:
+- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer.
+- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference.
+
+**Architecture Updates**:
+1. Read `arch-critical.md` (hot) and skim `arch.md` (cold).
+2. If this project produced a system-shape fact, route it:
+   - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate.
+   - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold).
+3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason.
+
+**Lessons Learned Updates**:
+1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold).
+2. If this project produced a durable lesson, route it:
+   - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full).
+   - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file.
+3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason.
+
+**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject.
 
 ### 4b. Update Other Documentation
 

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

@@ -99,16 +99,16 @@ Iterations that could have been prevented with better builder behavior:
 
 ## Architecture Updates
 
-[What was added/changed in `codev/resources/arch.md`, or why no changes were needed.]
+[What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no changes were needed.]
 
-- Updated: [section name] — [what was added/changed]
+- Routed: [hot | cold] — [fact/section] — [what was added/changed; note any demotion if the hot file was full]
 - Or: "No architecture updates needed — [brief reason]"
 
 ## Lessons Learned Updates
 
-[What was added/changed in `codev/resources/lessons-learned.md`, or why no changes were needed.]
+[What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no changes were needed.]
 
-- Added: [category] — [lesson summary]
+- Routed: [hot | cold] — [category] — [lesson summary]
 - Or: "No lessons learned updates needed — [brief reason]"
 
 ## Technical Debt

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

@@ -25,7 +25,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the BUGFIX protocol: `codev/protocols/bugfix/protocol.md`
+Follow the BUGFIX protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
@@ -67,3 +67,9 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
 1. Read the BUGFIX protocol
 2. Review the issue details
 3. Reproduce the bug before fixing
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

package/skeleton/protocols/bugfix/protocol.md

@@ -0,0 +1,78 @@
+# BUGFIX Protocol
+
+> Lightweight, issue-driven protocol for minor bug fixes. **Investigate → Fix → PR**, with a single `pr` gate before merge. No spec or plan artifacts: the GitHub issue is the spec, and the review goes in the PR body.
+
+## When to Use
+
+Use BUGFIX when a bug is reported as a GitHub Issue and:
+
+- The reproduction is clear (or inferable) and the root cause is isolated
+- The fix is small (guideline: < 300 LOC net diff) and contained to one area
+- No architectural changes or new design decisions are needed
+
+Escalate to **SPIR** (or another heavier protocol) instead when:
+
+- It is actually a feature request, not a bug
+- The root cause reveals a deeper architectural issue
+- The fix needs design review, spans multiple components, or clearly exceeds ~300 LOC
+
+## Phases
+
+```
+investigate → fix → pr
+```
+
+### Investigate
+
+Read the issue, reproduce the bug, and identify the root cause. Confirm the fix fits BUGFIX scope. If it does not, signal `BLOCKED` and recommend escalation to the architect (`afx send architect "..."`). No code in this phase.
+
+### Fix
+
+Apply the minimal change that resolves the root cause, and add a regression test that fails without the fix and passes with it. Keep it focused: do not refactor surrounding code, do not fix unrelated bugs (file separate issues), do not add features. Run the build and tests (porch's `checks` block runs `npm run build` and `npm test`).
+
+Commit with the issue-driven format:
+
+```
+[Bugfix #<N>] Fix: <what was fixed>
+[Bugfix #<N>] Test: <regression test added>
+```
+
+### PR (gated by `pr`)
+
+1. Push the branch and open a PR with `gh pr create`. The body includes Summary, Root Cause, Fix, and Test Plan, plus `Fixes #<N>` so the issue auto-closes on merge.
+2. Run a multi-agent CMAP review on the PR (Gemini, Codex, Claude) and record each verdict. Address or rebut any `REQUEST_CHANGES`; add a regression test if a real defect surfaced.
+3. Notify the architect: `afx send architect "PR #<M> ready for review (fixes #<N>). CMAP: gemini=..., codex=..., claude=..."`.
+4. Run `porch done <id>` to request the `pr` gate, then wait. **The merge is gated by porch state, never by typed prose in your pane.**
+5. The human reviews the PR and the CMAP results on GitHub, then approves the gate: `porch approve <id> pr --a-human-explicitly-approved-this`.
+6. porch wakes the builder with a merge task. Merge with `gh pr merge --merge` (do **not** pass `--delete-branch`: the builder is checked out on this branch in a worktree), then run `porch done <id>` and notify the architect that it is merged and ready for cleanup.
+
+## Gate
+
+BUGFIX has one human gate, `pr`, on the merge step. It exists so the merge trigger is structured porch state (approved or not), not free-text typed into the builder's pane. This eliminates the self-merge bug class: a builder cannot infer authorization from ambiguous input.
+
+## Multi-Agent Consultation
+
+A single CMAP pass at the PR (Gemini, Codex, Claude). There is no per-phase consultation: the issue is the spec and the fix is small, so review effort concentrates on the final PR.
+
+## Scope
+
+The < 300 LOC threshold is a **guideline**, measured as net diff (additions + deletions) anchored at the merge-base with the default branch. A well-contained 350-LOC fix is fine; a 200-LOC fix smeared across ten files may warrant escalation.
+
+## Escalation
+
+If, mid-fix, the change outgrows BUGFIX (architectural impact, multiple components, unclear root cause after investigation, or more than ~300 LOC), notify the architect with specifics and recommend escalating to SPIR. Do not silently expand scope.
+
+## Branch Naming
+
+```
+builder/bugfix-<issue-number>-<slug>
+```
+
+## Edge Cases
+
+| Scenario | Action |
+|---|---|
+| Cannot reproduce | Document the attempts in an issue comment, ask the reporter for detail, notify the architect |
+| Fix outgrows scope (architectural / multi-component / > ~300 LOC) | Notify the architect, recommend escalation; do not proceed |
+| Unrelated test failures | Out of scope: note them for the architect, do not fix them here |
+| Multiple bugs in one issue | Fix only the primary bug; file separate issues for the rest |

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

@@ -24,7 +24,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the EXPERIMENT protocol: `codev/protocols/experiment/protocol.md`
+Follow the EXPERIMENT protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 ## EXPERIMENT Overview
 The EXPERIMENT protocol ensures disciplined experimentation:
@@ -74,3 +74,9 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
 1. Read the EXPERIMENT protocol document
 2. Define your hypothesis clearly
 3. Follow the phases in order
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

package/skeleton/protocols/experiment/protocol.md

@@ -37,7 +37,7 @@ mkdir -p experiments/1_experiment_name
 cd experiments/1_experiment_name
 
 # Initialize notes.md from template
-cp codev/protocols/experiment/templates/notes.md notes.md
+touch notes.md   # then fill it from the embedded template at the end of this protocol
 ```
 
 Or ask your AI assistant: "Create a new experiment for [goal]"
@@ -85,33 +85,6 @@ git add experiments/1_experiment_name/
 git commit -m "[Experiment 1] Brief description of findings"
 ```
 
-## notes.md Template
-
-See `templates/notes.md` for the full template. Key sections:
-
-```markdown
-# Experiment ####: Name
-
-**Status**: In Progress | Complete | Disproved | Aborted
-
-**Date**: YYYY-MM-DD
-
-## Goal
-What are you trying to learn?
-
-## Time Investment
-Wall clock time vs active developer time
-
-## Code
-- [experiment.py](experiment.py) - Brief description
-
-## Results
-What happened? What did you learn?
-
-## Next Steps
-What should be done based on findings?
-```
-
 ## Best Practices
 
 ### Keep It Simple
@@ -222,3 +195,9 @@ Determine if Redis caching improves API response times for repeated queries.
 ## Next Steps
 Create SPIR spec for production caching implementation.
 ```
+
+## Template: notes.md
+
+Create `notes.md` with the following content:
+
+{{> protocols/experiment/templates/notes.md}}

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

@@ -23,7 +23,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the MAINTAIN protocol: `codev/protocols/maintain/protocol.md`
+Follow the MAINTAIN protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 ## MAINTAIN Overview
 
@@ -54,3 +54,9 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
 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
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

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

@@ -51,9 +51,9 @@ 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.
+**arch.md / arch-critical.md** (Spec 987 two-tier): Read both, compare with actual codebase. Route behavior-changing invariants to the HOT `arch-critical.md` (respect its cap + keep its cold-doc map accurate); reference detail to the COLD `arch.md` (directory structure, component descriptions, key files, removals). 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.
+**lessons-learned.md / lessons-critical.md** (two-tier): Scan `codev/reviews/` for new reviews since the base commit. **Route** each lesson — behavior-changing + cross-cutting → HOT `lessons-critical.md` (cap + displacement); reference recipe → COLD `lessons-learned.md`. Audit the hot caps + maps via the `update-arch-docs` skill.
 
 **CLAUDE.md / AGENTS.md**: `diff CLAUDE.md AGENTS.md` — they must be identical. Update the stale one.
 
@@ -61,8 +61,9 @@ One removal at a time. Verify after each. Never use `git add -A`.
 
 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"
+git add codev/resources/arch.md codev/resources/arch-critical.md
+git add codev/resources/lessons-learned.md codev/resources/lessons-critical.md
+git commit -m "[Maintain] Update governance docs (hot + cold tiers)"
 ```
 
 ## Step 5: Final Checks

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

@@ -57,7 +57,7 @@ Closes #<N>  <!-- Only if this run was triggered by a GitHub issue. Use "Refs #<
 
 - Dead code removed: X items
 - Dependencies cleaned: Y packages
-- Documentation updated: arch.md, lessons-learned.md
+- Documentation updated: arch.md / arch-critical.md, lessons-learned.md / lessons-critical.md (hot + cold tiers; hot caps + cold-doc maps policed)
 - Tests: all passing
 
 ## Test plan

package/skeleton/protocols/maintain/protocol.md

@@ -7,8 +7,8 @@ MAINTAIN is a single-pass maintenance protocol for keeping codebases healthy. Th
 **Core Principle**: Do the work in one pass. Don't over-ceremonialize housekeeping.
 
 **Key Documents** MAINTAIN keeps current:
-- `codev/resources/arch.md` - Architecture documentation
-- `codev/resources/lessons-learned.md` - Extracted wisdom from reviews
+- `codev/resources/arch.md` (COLD reference) + `codev/resources/arch-critical.md` (HOT, always-injected) — Architecture, two tiers (Spec 987)
+- `codev/resources/lessons-learned.md` (COLD reference) + `codev/resources/lessons-critical.md` (HOT, always-injected) — Engineering wisdom, two tiers
 
 The two governance docs are siblings with **different purposes**: `arch.md` owns system shape (services, transports, mental models, verified-wrong assumptions about *this* system); `lessons-learned.md` owns durable engineering wisdom that applies *across* specs. Use the routing matrix below to decide where each fact belongs.
 
@@ -18,8 +18,10 @@ The two governance docs are siblings with **different purposes**: `arch.md` owns
 |---|---|
 | Current system shape (services, transports, key mental models) | `codev/resources/arch.md` |
 | Mechanism for a unique subsystem | `codev/resources/arch.md` (subsystem section) OR a meta-spec under `codev/architecture/<domain>.md` if the mechanism is large enough to warrant its own doc |
-| A durable engineering pattern that applies across multiple specs | `codev/resources/lessons-learned.md` |
-| A spec-narrow fix recipe (only relevant inside the originating feature) | Spec review only — does NOT belong in `lessons-learned.md` |
+| A durable engineering pattern that applies across multiple specs | `codev/resources/lessons-learned.md` (COLD reference) |
+| A **behavior-changing, cross-cutting** rule (should change how the next project is built) | `codev/resources/lessons-critical.md` (HOT, capped) — demote to `lessons-learned.md` if full |
+| A **behavior-changing, cross-cutting** architecture invariant (a future builder must know up front) | `codev/resources/arch-critical.md` (HOT, capped) — demote to `arch.md` if full |
+| A spec-narrow fix recipe (reference detail) | `codev/resources/lessons-learned.md` (COLD) — kept as reference; **never** the hot file |
 | A system-shape surprise verified-wrong in production ("looks like X but isn't") | `codev/resources/arch.md` § "Verified-Wrong Assumptions" |
 | Aspirational architectural direction (where we want to go) | The relevant meta-spec or roadmap doc, NOT `arch.md` body |
 | A changelog entry ("we shipped X in spec Y on date Z") | `git log` + the spec/review document — NOT `arch.md`, NOT `lessons-learned.md` |
@@ -113,7 +115,7 @@ The `update-arch-docs` skill (at `.claude/skills/update-arch-docs/SKILL.md`) is
 
 #### Step 3a: Audit documentation
 
-Invoke the `update-arch-docs` skill in **audit-mode**. The skill reads `codev/resources/arch.md` and `codev/resources/lessons-learned.md` end-to-end against the discipline below and produces a candidate-cuts list (with reasons) recorded in the run file (`codev/maintain/NNNN.md`) under a new `## Audit Findings` section before any edits land.
+Invoke the `update-arch-docs` skill in **audit-mode**. The skill reads all four governance files — `codev/resources/arch.md` / `arch-critical.md` and `codev/resources/lessons-learned.md` / `lessons-critical.md` — end-to-end against the discipline below, applies the cuts via the Edit tool, and records each cut's reason in the run file (`codev/maintain/NNNN.md`) under a `## Audit Findings` section. The diff plus the recorded reasons **is** the proposal; the architect's PR review is the human-confirmation step (consistent with the skill's audit-mode).
 
 **Per-arch.md-section pruning checklist** — for each section in `arch.md`, ask:
 - Does it describe **current state**? If aspirational, the section moves to a meta-spec; `arch.md` keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
@@ -122,21 +124,27 @@ Invoke the `update-arch-docs` skill in **audit-mode**. The skill reads `codev/re
 - 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.
 
-**Per-lessons-learned.md-entry pruning checklist** — for each entry, ask:
-- Is it cross-applicable beyond the spec that produced it? If no, remove (the lesson belongs in the spec's review).
+**Per-COLD-`lessons-learned.md`-entry pruning checklist** — for each entry, ask:
 - Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
 - Is the topic section the right home? 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.
+- (Spec-narrow recipes are **kept** as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not the cold archive.)
+
+**Per-HOT-file checklist** (`arch-critical.md`, `lessons-critical.md`) — audit the cap and map:
+- Within the cap (≈10 entries + a ≈12-topic map, ≤35 lines)? If over, **demote** the weakest entries into the cold doc.
+- Does every map topic name a real top-level cold-doc section, and is any new/renamed section reflected? Fix drift; keep the map top-level only.
+- Is every entry still behavior-changing? Demote reference detail into the cold archive.
 
 **Sample audit prompt** (paste into the skill invocation if you want a baseline checklist run):
 
 ```
-Audit codev/resources/arch.md and codev/resources/lessons-learned.md against the
-discipline in the update-arch-docs skill. For each section/entry, run the per-
-arch.md-section and per-lessons-learned.md-entry pruning checklists from the
-MAINTAIN protocol (Step 3a). Produce a candidate-cuts list with one-line reasons.
-Bias toward fewer, higher-confidence cuts ("when in doubt, KEEP"). Record the
-findings in the current run file's ## Audit Findings section before applying.
+Audit all four governance files — codev/resources/arch.md + arch-critical.md and
+lessons-learned.md + lessons-critical.md — against the discipline in the
+update-arch-docs skill. For each cold section/entry run the cold pruning checklists,
+and for each hot file check the cap, displacement, and map accuracy (Step 3a).
+Apply the cuts with one-line reasons. Bias toward fewer, higher-confidence
+cuts ("when in doubt, KEEP"). Record each cut's reason in the current run
+file's ## Audit Findings section as you go — the diff plus those reasons is the proposal.
 ```
 
 **When in doubt, KEEP.** This rule is preserved from the older Step 3. A confident cut is better than three speculative ones. The audit pass is a *proposal*; the architect's PR review confirms it.
@@ -145,14 +153,14 @@ findings in the current run file's ## Audit Findings section before applying.
 
 Apply the audit decisions from Step 3a, plus any additive content needed.
 
-**arch.md**: Compare documented structure with actual codebase. Update:
+**arch.md / arch-critical.md**: Compare documented structure with actual codebase. Route behavior-changing invariants to `arch-critical.md` (HOT — respect the cap + keep its map accurate); reference detail to `arch.md` (COLD). Update:
 - Directory structure
 - Component descriptions (explain HOW things work, not just WHAT)
 - Key files and their purposes
 - Remove references to deleted code (per Step 3a audit findings)
 - Add new components/utilities
 
-**lessons-learned.md**: Scan `codev/reviews/` for new reviews since last run. Extract lessons that are actionable, durable, and general. Apply Step 3a's per-entry cuts.
+**lessons-learned.md / lessons-critical.md**: Scan `codev/reviews/` for new reviews since last run. **Route** each new lesson by tier — behavior-changing + cross-cutting → `lessons-critical.md` (HOT; respect the cap, demote a weaker entry to cold if full); reference recipe / spec-narrow → `lessons-learned.md` (COLD). Apply Step 3a's per-entry cuts and keep each hot file's cold-doc map accurate.
 
 For specific additive changes, invoke `update-arch-docs` in **diff-mode** — it applies the smallest section update needed.
 
@@ -192,13 +200,13 @@ Each run creates `codev/maintain/NNNN.md`:
 
 ## Audit Findings
 
-Recorded by Step 3a (Audit documentation) before any edits land. One line per candidate cut.
+Recorded by Step 3a (Audit documentation) as the cuts are applied — one line per cut, with its reason. The diff plus these reasons is the proposal; the architect's PR review is the gate.
 
-### arch.md
-- <section-name>: <reason for proposed cut/compression>
+### arch.md (cold) / arch-critical.md (hot)
+- <section or hot entry>: <reason for cut / compression / demotion>
 
-### lessons-learned.md
-- <entry>: <reason>
+### lessons-learned.md (cold) / lessons-critical.md (hot)
+- <entry>: <reason; note hot→cold demotions and any cold-doc-map fixes>
 
 ## What Was Done
 
@@ -207,8 +215,8 @@ Recorded by Step 3a (Audit documentation) before any edits land. One line per ca
 - Removed `some-package` dependency — zero imports
 
 ### Documentation Updated
-- arch.md: Added VS Code extension section, removed old dashboard-server refs
-- lessons-learned.md: Extracted 3 lessons from reviews 653, 672
+- arch.md / arch-critical.md: Added VS Code extension section + removed old dashboard-server refs (cold); routed 1 invariant to the hot tier, demoted 1 stale entry to cold
+- lessons-learned.md / lessons-critical.md: Extracted 3 lessons from reviews 653, 672 (cold); promoted 1 behavior-changer to the hot tier, refreshed its cold-doc map
 
 ### Documentation Changes Log
 | Document | Section | Action | Reason |

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

@@ -17,8 +17,8 @@
 - <package> — <reason>
 
 ### Documentation Updated
-- arch.md: <what changed>
-- lessons-learned.md: <what changed>
+- arch.md (cold) / arch-critical.md (hot): <what changed; note any demotions + map fixes>
+- lessons-learned.md (cold) / lessons-critical.md (hot): <what changed; note any demotions + map fixes>
 
 ### Documentation Changes Log
 | Document | Section | Action | Reason |

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

@@ -27,8 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the PIR protocol: `codev/protocols/pir/protocol.md`
-Read and internalize the protocol before starting any work.
+Follow the PIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 PIR has three phases:
 1. **plan** (gated by `plan-approval`) — write `codev/plans/{{artifact_name}}.md`, await human review
@@ -87,6 +86,12 @@ If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch
 
 ## Getting Started
 
-1. Read the PIR protocol document (`codev/protocols/pir/protocol.md`)
+1. Read the PIR protocol (provided inline in this prompt).
 2. Run `porch next {{project_id}}` to see what to do next
 3. Begin work
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

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

@@ -58,13 +58,13 @@ Output of `git log main..HEAD --oneline`:
 
 ## Architecture Updates
 
-What changed in `codev/resources/arch.md` (or why no changes were needed). If this PR introduced or modified an architectural pattern, document it here AND update `arch.md` in this same commit. If no architectural updates are needed (typical for small fixes), write a single line explaining why: "No arch changes — this PR fixes a typo without affecting module boundaries."
+What you routed where, across the **two tiers** (Spec 987): **HOT** = `codev/resources/arch-critical.md` (tiny, hard-capped, always-injected) for a behavior-changing cross-cutting fact (demote a weaker entry into `arch.md` if the hot file is full); **COLD** = `codev/resources/arch.md` for reference detail. Update the file(s) you routed to in this same commit. If nothing qualifies, write a single line explaining why: "No arch changes — this PR fixes a typo without affecting module boundaries."
 
-Use the `update-arch-docs` skill if available (`.claude/skills/update-arch-docs/SKILL.md`) — it encodes the discipline for what NOT to include in arch docs.
+Use the `update-arch-docs` skill if available (`.claude/skills/update-arch-docs/SKILL.md`) — it encodes the discipline for what NOT to include in arch docs and how the hot/cold tiers relate.
 
 ## Lessons Learned Updates
 
-What durable engineering wisdom emerged from this PR (or why no lessons were captured). Same pattern as Architecture Updates: if something is worth recording in `codev/resources/lessons-learned.md`, update both files in this commit. If not, explain why: "No lessons captured — change was mechanical."
+What durable wisdom emerged, routed by tier: **HOT** `codev/resources/lessons-critical.md` for a behavior-changing cross-cutting rule (cap + displacement); **COLD** `codev/resources/lessons-learned.md` for a spec-narrow recipe/reference tip. Update the file(s) you routed to in this commit. If nothing qualifies: "No lessons captured — change was mechanical."
 
 ## Things to Look At During PR Review
 
@@ -85,7 +85,7 @@ List any tests you skipped due to pre-existing flakiness, with file:line refs an
 
 ### 2. Update Architecture / Lessons Docs (if applicable)
 
-If your "Architecture Updates" or "Lessons Learned Updates" section calls out real changes, update `codev/resources/arch.md` and/or `codev/resources/lessons-learned.md` accordingly. Use the `update-arch-docs` skill if it's available.
+If your "Architecture Updates" or "Lessons Learned Updates" section routed real changes, update the tier you chose — `arch-critical.md` / `lessons-critical.md` (hot, capped) or `arch.md` / `lessons-learned.md` (cold) — accordingly. Use the `update-arch-docs` skill if it's available.
 
 If neither doc needs updating, your review file's sections still need to explain why — the porch `checks` block enforces section presence.
 
@@ -93,9 +93,11 @@ If neither doc needs updating, your review file's sections still need to explain
 
 ```bash
 git add codev/reviews/{{artifact_name}}.md
-# Add arch.md / lessons-learned.md only if you changed them
-git add codev/resources/arch.md           # only if changed
-git add codev/resources/lessons-learned.md  # only if changed
+# Add the governance file(s) you routed to, only if changed
+git add codev/resources/arch-critical.md      # hot — only if changed
+git add codev/resources/lessons-critical.md   # hot — only if changed
+git add codev/resources/arch.md               # cold — only if changed
+git add codev/resources/lessons-learned.md    # cold — only if changed
 git commit -m "[PIR #{{issue.number}}] Review + retrospective"
 git push
 ```

package/skeleton/protocols/pir/protocol.md

@@ -98,7 +98,7 @@ porch approve <id> dev-approval --a-human-explicitly-approved-this
 
 The builder:
 1. Writes `codev/reviews/<id>-<slug>.md` with **Summary**, **Architecture Updates**, **Lessons Learned Updates**, plus the supporting sections (Files Changed, Commits, Test Results, Things to Look At, How to Test Locally).
-2. Updates `codev/resources/arch.md` and/or `codev/resources/lessons-learned.md` if real changes need recording. If not, the review file's sections state "no changes needed" with a one-line explanation (the porch `checks` block enforces section presence, not content).
+2. Routes new facts/wisdom by tier (Spec 987) — HOT `codev/resources/arch-critical.md` / `lessons-critical.md` (capped) or COLD `codev/resources/arch.md` / `lessons-learned.md` (reference) — if real changes need recording. If not, the review file's sections state "no changes needed" with a one-line explanation (the porch `checks` block enforces section presence, not content).
 3. Commits the review file (and arch / lessons updates if any) and pushes
 4. Opens a PR with `gh pr create`; PR body is the review file content + `Fixes #<N>`. Records the PR with `porch done <id> --pr <M> --branch <name>`.
 5. Runs `porch done <id>` — porch's `verify` block runs 3-way consultation (Gemini, Codex, Claude; type=impl) as a **single advisory pass** (`max_iterations: 1`); consultation outputs land in `codev/projects/<id>-*/`. There is no iterate-until-APPROVE loop: whatever the verdicts, porch records them and advances to the `pr` gate. A `REQUEST_CHANGES` is not auto-re-reviewed — the builder addresses or rebuts it, adds a regression test if it's a real defect, and escalates it in the architect notification so the human verifies it at the `pr` gate. Outcomes are not auto-appended to the PR body; reviewers with the worktree read them from the projects dir.