@cluesmith/codev 3.1.8 → 3.2.0

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.

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

@@ -24,7 +24,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the RESEARCH protocol: `codev/protocols/research/protocol.md`
+Follow the RESEARCH protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 ## RESEARCH Overview
 
@@ -83,3 +83,9 @@ wait
 2. Understand the research question from the architect
 3. Write the research brief (Phase 1)
 4. Wait for scope-approval before proceeding to investigation
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

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

@@ -11,7 +11,7 @@ You are running in SOFT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIKE protocol: `codev/protocols/spike/protocol.md`
+Follow the SPIKE protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 {{#if task}}
 ## Spike Question
@@ -60,3 +60,9 @@ If you encounter **pre-existing flaky tests** (intermittent failures unrelated t
 1. Read the SPIKE protocol document
 2. Understand the question you're investigating
 3. Start with research — don't jump straight to code
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}

package/skeleton/protocols/spike/protocol.md

@@ -52,7 +52,7 @@ The following 3-step workflow is **guidance only** — not enforced by porch. Fo
 ### Step 3: Findings
 
 - Write the findings document at `codev/spikes/<id>-<name>.md`
-- Use the template: `codev/protocols/spike/templates/findings.md`
+- Use the embedded template at the end of this protocol
 - Provide a clear feasibility verdict
 - Commit and notify the architect
 
@@ -120,3 +120,9 @@ When a spike finds something is not feasible:
 1. Document clearly in findings
 2. Close the related GitHub issue with a link to findings
 3. The findings become institutional knowledge
+
+## Template: findings.md
+
+Write the findings document using the following template:
+
+{{> protocols/spike/templates/findings.md}}

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

@@ -27,8 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
-Read and internalize the protocol before starting any work.
+Follow the SPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
 ## Baked Decisions
 
@@ -112,3 +111,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/spir/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/spir/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/spir/protocol.md

@@ -4,7 +4,6 @@
 >
 > Each phase has one build-verify cycle with 3-way consultation.
 
-> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
 
 ## Prerequisites
 
@@ -164,7 +163,7 @@ When filing an issue for SPIR, you can pin architectural decisions you don't wan
 - All consultation feedback incorporated directly into this document
 - Include a "Consultation Log" section summarizing key feedback and changes
 - Version control captures evolution through commits
-**Template**: `templates/spec.md`
+**Structure**: developed through the specify phase
 **Review Required**: Yes - Human approval AFTER consultations
 
 ### P - Plan (Structured Decomposition)
@@ -243,7 +242,7 @@ Each phase should be:
 - Include phase status tracking within this document
 - **DO NOT include time estimates** - Focus on deliverables and dependencies, not hours/days
 - Version control captures evolution through commits
-**Template**: `templates/plan.md`
+**Structure**: follows the plan template provided by the plan phase
 **Review Required**: Yes - Technical lead approval AFTER consultations
 
 ### I - Implement (Per Plan Phase)
@@ -508,8 +507,8 @@ Execute for each phase in the plan. Each phase follows a build-verify cycle.
    - Enhance documentation
 
 3. **Update Architecture Documentation**
-   - Update `codev/resources/arch.md` and `codev/resources/lessons-learned.md` with new modules, utilities, architectural changes, and durable engineering wisdom uncovered during this work
-   - Use the **`update-arch-docs` skill** (at `.claude/skills/update-arch-docs/SKILL.md`) to apply changes — the skill encodes the discipline for what NOT to include and the two-doc framing (arch.md owns system shape; lessons-learned.md owns durable engineering wisdom)
+   - Route new system-shape facts and durable wisdom by tier (Spec 987): behavior-changing + cross-cutting → the HOT `codev/resources/arch-critical.md` / `lessons-critical.md` (capped, always-injected; demote a weaker entry to cold if full); reference detail → the COLD `codev/resources/arch.md` / `lessons-learned.md`
+   - Use the **`update-arch-docs` skill** (at `.claude/skills/update-arch-docs/SKILL.md`) to apply changes — it encodes the hot/cold two-tier discipline (caps + cold-doc maps for the hot files; reference archive for the cold files) and what NOT to include
    - Follow guidance in the MAINTAIN protocol's Step 3 ("Sync Documentation") for structure, the "Lives where" routing matrix, and pruning checklists
    - Ensure both docs reflect current state
 
@@ -642,7 +641,7 @@ spir/1-user-authentication/database-schema
 
 ## Templates
 
-Templates for each phase are available in the `templates/` directory:
+Each phase has a template that ships in the package skeleton; the phase prompts deliver the structure you need, so you do not fetch these files directly:
 - `spec.md` - Specification template
 - `plan.md` - Planning template (includes phase status tracking)
 - `review.md` - Review and lessons learned template

package/skeleton/protocols/spir/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/resources/arch-critical.md

@@ -0,0 +1,17 @@
+# arch-critical.md — Always-On System-Shape Facts (HOT tier)
+
+<!-- HOT tier: capped facts + a bounded map of arch.md. Always injected into every porch
+phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 facts, <=12 map topics, <=35 lines.
+To add a fact, DEMOTE a weaker one into arch.md (displacement). MAINTAIN polices the cap
+and keeps the map in sync with arch.md's top-level sections.
+STARTER: replace the examples below with YOUR project's facts and arch.md sections. -->
+
+## Critical facts (consult before deciding)
+- <A system-shape fact that should change implementation choices — e.g. "all persistent state lives in X; never write it directly.">
+- <An invariant a contributor must not violate — e.g. "service A only talks to service B through the queue.">
+- <Keep to <=10, one line each; demote weaker facts into arch.md.>
+
+## Map of arch.md (consult when…)
+- <Top-level arch.md section> — consult when <situation>.
+- <Top-level arch.md section> — consult when <situation>.
+- <List your arch.md's top-level sections here; keep <=12, top-level only.>

package/skeleton/resources/lessons-critical.md

@@ -0,0 +1,17 @@
+# lessons-critical.md — Always-On Engineering Wisdom (HOT tier)
+
+<!-- HOT tier: capped lessons + a bounded map of lessons-learned.md. Always injected into
+every porch phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 lessons, <=12 map topics,
+<=35 lines. To add a lesson, DEMOTE a weaker one into lessons-learned.md (displacement).
+MAINTAIN polices the cap and keeps the map in sync with lessons-learned.md's sections.
+STARTER: a few universal lessons are seeded; add your project's as you learn them. -->
+
+## Critical lessons (consult before deciding)
+- Check for existing work (PRs, git history) before building from scratch.
+- "It compiled" / "tests pass" is not "it works" — verify the real user path before calling it done.
+- When stuck (2 failed hypotheses or ~30 min), get an outside perspective instead of guessing.
+- <Add your project's hard-won, cross-cutting lessons; keep <=10, one line each.>
+
+## Map of lessons-learned.md (consult when…)
+- <Top-level section> — consult when <situation>.
+- <List your lessons-learned.md's top-level sections here; keep <=12, top-level only.>

package/skeleton/roles/builder.md

@@ -79,8 +79,8 @@ In soft mode, you follow the protocol document yourself. The architect monitors
 cat codev/specs/XXXX-*.md
 cat codev/plans/XXXX-*.md
 
-# Read the protocol
-cat codev/protocols/spir/protocol.md
+# (The full protocol text is inlined in your spawn prompt under the
+#  "## Protocol Reference (full text)" heading; no need to fetch it.)
 
 # Start implementing
 ```

package/skeleton/templates/arch-critical.md

@@ -0,0 +1,17 @@
+# arch-critical.md — Always-On System-Shape Facts (HOT tier)
+
+<!-- HOT tier: capped facts + a bounded map of arch.md. Always injected into every porch
+phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 facts, <=12 map topics, <=35 lines.
+To add a fact, DEMOTE a weaker one into arch.md (displacement). MAINTAIN polices the cap
+and keeps the map in sync with arch.md's top-level sections.
+STARTER: replace the examples below with YOUR project's facts and arch.md sections. -->
+
+## Critical facts (consult before deciding)
+- <A system-shape fact that should change implementation choices — e.g. "all persistent state lives in X; never write it directly.">
+- <An invariant a contributor must not violate — e.g. "service A only talks to service B through the queue.">
+- <Keep to <=10, one line each; demote weaker facts into arch.md.>
+
+## Map of arch.md (consult when…)
+- <Top-level arch.md section> — consult when <situation>.
+- <Top-level arch.md section> — consult when <situation>.
+- <List your arch.md's top-level sections here; keep <=12, top-level only.>

package/skeleton/templates/arch.starter.md

@@ -0,0 +1,9 @@
+# Architecture
+
+<!-- STARTER: replace the "_No architecture documented yet._" line below with your
+project's architecture as it emerges (usually during a review phase). Delete this
+comment once the file has real content. -->
+
+This document evolves as the project grows. Update it during the review phase of any work that introduces or changes architectural patterns.
+
+_No architecture documented yet._

package/skeleton/templates/lessons-critical.md

@@ -0,0 +1,17 @@
+# lessons-critical.md — Always-On Engineering Wisdom (HOT tier)
+
+<!-- HOT tier: capped lessons + a bounded map of lessons-learned.md. Always injected into
+every porch phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 lessons, <=12 map topics,
+<=35 lines. To add a lesson, DEMOTE a weaker one into lessons-learned.md (displacement).
+MAINTAIN polices the cap and keeps the map in sync with lessons-learned.md's sections.
+STARTER: a few universal lessons are seeded; add your project's as you learn them. -->
+
+## Critical lessons (consult before deciding)
+- Check for existing work (PRs, git history) before building from scratch.
+- "It compiled" / "tests pass" is not "it works" — verify the real user path before calling it done.
+- When stuck (2 failed hypotheses or ~30 min), get an outside perspective instead of guessing.
+- <Add your project's hard-won, cross-cutting lessons; keep <=10, one line each.>
+
+## Map of lessons-learned.md (consult when…)
+- <Top-level section> — consult when <situation>.
+- <List your lessons-learned.md's top-level sections here; keep <=12, top-level only.>

package/skeleton/templates/lessons-learned.starter.md

@@ -0,0 +1,9 @@
+# Lessons Learned
+
+<!-- STARTER: replace the "_No lessons captured yet._" line below with durable, cross-cutting
+lessons as they emerge (usually during a review phase). Delete this comment once the file has
+real content. -->
+
+Durable engineering wisdom captured across the project's work. Update it during the review phase of any work that surfaces a generally-applicable pattern, gotcha, or constraint.
+
+_No lessons captured yet._