@cluesmith/codev 3.1.9 → 3.2.0

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