@cluesmith/codev 3.1.8 → 3.2.0

package/skeleton/.claude/skills/update-arch-docs/SKILL.md

@@ -1,16 +1,16 @@
 ---
 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."
+description: "Audit, prune, and update the project's governance docs — the COLD reference archives `codev/resources/arch.md` and `codev/resources/lessons-learned.md` AND their always-on HOT companions `codev/resources/arch-critical.md` and `codev/resources/lessons-critical.md` (Spec 987, hot/cold two-tier model). Use this skill when running MAINTAIN's arch-doc step, or when asked to update / audit / prune any of those four files. It polices the hot-tier cap (capped facts/lessons + a bounded cold-doc map), enforces displacement (demote to cold when full), keeps each hot file's map accurate, and is opinionated about what NOT to put in each tier (per-spec changelogs, exhaustive enumerations, aspirational state). Two modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). Edits files directly via normal file-edit tooling; no destructive shell commands."
 ---
 
 # update-arch-docs
 
-This skill maintains two governance documents:
+This skill maintains the project's governance docs, each split into **two tiers** (Spec 987):
 
-- `codev/resources/arch.md` — the project's architecture document.
-- `codev/resources/lessons-learned.md` — durable engineering wisdom extracted from reviews.
+- **COLD reference archives** — `codev/resources/arch.md` (architecture) and `codev/resources/lessons-learned.md` (durable wisdom). Full, on-demand; grepped/read for depth.
+- **HOT always-on companions** — `codev/resources/arch-critical.md` and `codev/resources/lessons-critical.md`. Tiny, **hard-capped**, **always injected** into every porch prompt and into CLAUDE.md/AGENTS.md. Each holds capped facts/lessons **plus a bounded "consult when…" map** of its cold doc's top-level topics.
 
-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.
+It is invoked by the MAINTAIN protocol's documentation step, and ad-hoc whenever someone updates, audits, or prunes any of these files. The skill is opinionated about *what does not belong* in each tier and **polices the hot-tier cap, displacement, and map accuracy**. Use it whenever a doc change touches any of the four files.
 
 ## What this skill does NOT do
 
@@ -26,12 +26,22 @@ These are the patterns that have, in practice, caused arch.md and lessons-learne
 - **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
+### In the HOT files (`arch-critical.md`, `lessons-critical.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.
+These are capped, always-on, and **behavior-changers only**. Bright-line rejections:
+
+- **Anything over the cap.** Each hot file fits in a handful of lines (≈10 single-line facts/lessons + a cold-doc map of ≈12 top-level topics, ≤35 lines). To add an entry, **demote** a weaker one into the cold doc (displacement) — never grow the hot file.
+- **Spec-narrow recipes / reference detail.** Those go in the COLD archive (reference), never the hot file.
+- **A full/auto table of contents** in the cold-doc map. The map lists only **top-level** cold-doc sections, each with a one-line "consult when…" — never every entry.
+- **Multi-paragraph entries.** One line each.
+
+### In the COLD archives (`arch.md`, `lessons-learned.md`)
+
+These are the on-demand **reference**. They may hold spec-narrow recipes and deeper detail — the anti-accretion discipline lives in the hot cap, not here. Still avoid:
+
+- **Multi-paragraph lesson entries**. Split or compress to 1–3 sentences.
+- **Duplicate adjacent entries**. Fold variations of the same lesson into one.
+- **Spec-numbered narrative framing** ("Lesson from #0468:…"). State the general principle; link the review if needed.
 
 ### In either file (process)
 
@@ -51,6 +61,16 @@ Treat the two files as siblings with different purposes. When in doubt about whi
 
 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.
 
+That arch-vs-lessons routing is the **cold-tier** axis. **Orthogonal to it is the hot/cold axis**: once you know a fact is architecture (or a lesson), decide whether it is *behavior-changing enough* to earn a slot in the capped hot companion, or whether it is reference detail for the cold archive.
+
+## Hot tier: cap, displacement, and map accuracy
+
+The hot files (`arch-critical.md`, `lessons-critical.md`) are the behavior-changers, and their value depends on staying tiny. When MAINTAIN runs — or any update touches them — enforce:
+
+- **Cap.** Each hot file fits in a handful of lines: ≈10 single-line facts/lessons **plus** a cold-doc map of ≈12 top-level topics, ≤35 lines total. If an addition would exceed the cap, **demote** the weakest existing entry into the corresponding cold doc rather than growing the hot file. The cap is load-bearing: it is what keeps the hot tier cheap enough to inject into *every* prompt.
+- **Map accuracy (bounded AND accurate).** Each hot file ends with a "Map of <cold doc> (consult when…)" listing only the cold doc's **top-level** sections, each with a one-line "consult when…". As cold-doc sections are added / renamed / removed, update the map to match — but keep it top-level only; never expand it into a full table of contents (that re-creates the accretion the hot tier exists to avoid).
+- **Behavior-changers only.** A hot entry must be something that should change a decision up front. Reference detail, recipes, and one-offs belong in the cold archive — demote on sight.
+
 ## 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.
@@ -85,11 +105,16 @@ In audit-mode:
    - 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).
+3. For each entry in the COLD `lessons-learned.md`, run the per-entry checklist:
    - 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.
+   - (Spec-narrow recipes are **kept** here as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not in the cold archive.)
+
+   Then audit each **HOT** file (`arch-critical.md`, `lessons-critical.md`):
+   - **Cap**: within ≈10 entries + a ≈12-topic map, ≤35 lines? If over, **demote** the weakest entries into the cold doc.
+   - **Map accuracy**: 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.
+   - **Behavior-changers only**: demote any reference detail that crept in.
 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").
@@ -100,7 +125,7 @@ Audit-mode is slower than diff-mode and produces larger diffs. Reserve it for ex
 
 The skill commits to the following:
 
-- It edits `codev/resources/arch.md` and `codev/resources/lessons-learned.md` directly via the Edit tool.
+- It edits the four governance files — `codev/resources/arch.md` / `arch-critical.md` and `codev/resources/lessons-learned.md` / `lessons-critical.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.

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