@cluesmith/codev 3.1.9 → 3.2.1

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._