[PIR #1011] Deliver framework files via resolver-aware channels (fresh-install class fix)

AGENTS.md

@@ -88,6 +88,14 @@ Codev resolves protocol files, prompts, agent definitions, and roles through a f
 
 **Implication for `codev update` and CLAUDE.md / AGENTS.md merges:** when an updated template references a protocol (e.g., PIR), do NOT drop the reference because `codev/protocols/<name>/` is absent locally. The protocol resolves via the package skeleton, and dropping the reference removes the protocol from the user's available-protocol list while it's still callable from the CLI.
 
+### Framework files in prompts: deliver, don't shell-fetch
+
+Protocol docs, role docs, and the shipped `codev/resources/` reference docs (`workflow-reference.md`, `risk-triage.md`, `commands/`) resolve through the four-tier lookup above and **default to the package skeleton**. A project may override any of them by checking a copy into `codev/...` (tier 2), but a fresh project won't have them on disk, so don't rely on it.
+
+So in any prompt, role doc, or instruction that drives a builder, don't `cat`/`cp` a framework file by literal `codev/...` path: a shell read bypasses the resolver and fails in fresh installs. Deliver the content instead (`protocol.md` is inlined into the spawn prompt; per-phase prompts and their templates arrive via porch). Mentioning a `codev/...` path in prose for orientation is fine; the rule is about *fetching*, not *referencing*. `codev/resources/arch.md` and `codev/resources/lessons-learned.md` are user-evolved project files, not framework files, so referencing those by path is correct too.
+
+`codev doctor` audits the skeleton for this.
+
 ### Protocol Verification (When You Don't Recognize a Protocol Name)
 
 If the user mentions a protocol name you don't immediately recognize, verify against the CLI before responding:

CLAUDE.md

@@ -88,6 +88,14 @@ Codev resolves protocol files, prompts, agent definitions, and roles through a f
 
 **Implication for `codev update` and CLAUDE.md / AGENTS.md merges:** when an updated template references a protocol (e.g., PIR), do NOT drop the reference because `codev/protocols/<name>/` is absent locally. The protocol resolves via the package skeleton, and dropping the reference removes the protocol from the user's available-protocol list while it's still callable from the CLI.
 
+### Framework files in prompts: deliver, don't shell-fetch
+
+Protocol docs, role docs, and the shipped `codev/resources/` reference docs (`workflow-reference.md`, `risk-triage.md`, `commands/`) resolve through the four-tier lookup above and **default to the package skeleton**. A project may override any of them by checking a copy into `codev/...` (tier 2), but a fresh project won't have them on disk, so don't rely on it.
+
+So in any prompt, role doc, or instruction that drives a builder, don't `cat`/`cp` a framework file by literal `codev/...` path: a shell read bypasses the resolver and fails in fresh installs. Deliver the content instead (`protocol.md` is inlined into the spawn prompt; per-phase prompts and their templates arrive via porch). Mentioning a `codev/...` path in prose for orientation is fine; the rule is about *fetching*, not *referencing*. `codev/resources/arch.md` and `codev/resources/lessons-learned.md` are user-evolved project files, not framework files, so referencing those by path is correct too.
+
+`codev doctor` audits the skeleton for this.
+
 ### Protocol Verification (When You Don't Recognize a Protocol Name)
 
 If the user mentions a protocol name you don't immediately recognize, verify against the CLI before responding:

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 ## Baked Decisions
 
@@ -73,3 +73,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 ## Baked Decisions
 
@@ -111,3 +110,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-skeleton/protocols/aspir/prompts/plan.md

@@ -76,7 +76,6 @@ After completing the plan draft, signal completion. Porch will run 3-way consult
 
 Create the plan file at `codev/plans/{{artifact_name}}.md`.
 
-Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
 
 ### Plan Structure
 

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 {{#if issue}}
 ## Issue #{{issue.number}}
@@ -67,3 +67,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 ## EXPERIMENT Overview
 The EXPERIMENT protocol ensures disciplined experimentation:
@@ -74,3 +74,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-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]"
@@ -222,3 +222,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}}

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 ## MAINTAIN Overview
 
@@ -54,3 +54,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 PIR has three phases:
 1. **plan** (gated by `plan-approval`) — write `codev/plans/{{artifact_name}}.md`, await human review
@@ -87,6 +86,14 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 ## RESEARCH Overview
 
@@ -83,3 +83,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 {{#if task}}
 ## Spike Question
@@ -60,3 +60,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-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}}

codev-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.{{#if protocol_reference}} The full protocol text is included below under **## Protocol Reference (full text)**.{{/if}}
 
 ## Baked Decisions
 
@@ -112,3 +111,11 @@ 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
+
+{{#if protocol_reference}}
+
+---
+
+## Protocol Reference (full text)
+
+{{protocol_reference}}{{/if}}

codev-skeleton/protocols/spir/prompts/plan.md

@@ -76,7 +76,6 @@ After completing the plan draft, signal completion. Porch will run 3-way consult
 
 Create the plan file at `codev/plans/{{artifact_name}}.md`.
 
-Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
 
 ### Plan Structure
 

codev-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
 

codev-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
 ```