From 639ed8aab3df864b0906243efc240a4c81496442 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:27:23 +1000
Subject: [PATCH 01/14] chore(porch): 1011 init pir

---
 .../status.yaml                                | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml

diff --git a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
new file mode 100644
index 000000000..1a8d94b9a
--- /dev/null
+++ b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
@@ -0,0 +1,18 @@
+id: '1011'
+title: agent-farm-inline-protocol-md-
+protocol: pir
+phase: plan
+plan_phases: []
+current_plan_phase: null
+gates:
+  plan-approval:
+    status: pending
+  dev-approval:
+    status: pending
+  pr:
+    status: pending
+iteration: 1
+build_complete: false
+history: []
+started_at: '2026-06-08T02:27:23.467Z'
+updated_at: '2026-06-08T02:27:23.468Z'

From a09f706ab74121c9f8a4aeee8e41e7a2f74b184a Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:30:56 +1000
Subject: [PATCH 02/14] [PIR #1011] Plan draft

---
 .../1011-agent-farm-inline-protocol-md-.md    | 148 ++++++++++++++++++
 codev/state/pir-1011_thread.md                |  14 ++
 2 files changed, 162 insertions(+)
 create mode 100644 codev/plans/1011-agent-farm-inline-protocol-md-.md
 create mode 100644 codev/state/pir-1011_thread.md

diff --git a/codev/plans/1011-agent-farm-inline-protocol-md-.md b/codev/plans/1011-agent-farm-inline-protocol-md-.md
new file mode 100644
index 000000000..e1bc6c605
--- /dev/null
+++ b/codev/plans/1011-agent-farm-inline-protocol-md-.md
@@ -0,0 +1,148 @@
+# PIR Plan: Inline `protocol.md` into the builder prompt at spawn
+
+## Understanding
+
+Spec 618 correctly moved framework files (protocols, roles, resources) out of user
+projects and into the embedded package skeleton, resolved at runtime via the four-tier
+resolver (`.codev/` → `codev/` → cache → skeleton). The resolver works.
+
+The remaining bug is **consumer-side**: every protocol's `builder-prompt.md` tells the
+builder to read `codev/protocols/<name>/protocol.md` — a literal path that does not exist
+on disk in a fresh post-618 install (the file lives only in the embedded skeleton, reachable
+through the resolver but *not* through a raw `cat`). So a freshly-spawned builder runs the
+`cat`, gets "No such file", and wastes 1–3 minutes hunting before proceeding without the
+protocol meta-doc (workflow overview, gate semantics, when-to-use guidance).
+
+The per-phase prompts (delivered via `porch next` JSON, resolver-mediated) already cover the
+actionable per-phase work, so they are *not* affected. The gap is purely the one-time meta-doc.
+
+Verified in this worktree:
+
+- `codev-skeleton/protocols/*/builder-prompt.md` contain literal `codev/protocols/<name>/protocol.md`
+  instructions — confirmed in all 10 protocol templates (e.g. `spir/builder-prompt.md:30`,
+  `pir/builder-prompt.md:30` and `:90`).
+- `loadBuilderPromptTemplate()` at `packages/codev/src/agent-farm/commands/spawn-roles.ts:99-108`
+  loads `builder-prompt.md` via `resolveCodevFile()` but never reads `protocol.md`.
+- `resolveCodevFile()` (`packages/codev/src/lib/skeleton.ts`) reaches the embedded skeleton
+  correctly. The resolver is not the bug.
+
+## Proposed Change
+
+Extend `loadBuilderPromptTemplate()` to additionally resolve `protocols/<name>/protocol.md`
+via `resolveCodevFile()` and append its full text to the returned template under a clearly
+delimited heading. The builder then has the meta-doc in its initial prompt context for the
+whole session — read once, never re-shipped per phase, and the builder never runs a shell
+command that bypasses the resolver.
+
+Concretely, after loading the `builder-prompt.md` template and before returning it:
+
+```ts
+let template = readFileSync(templatePath, 'utf-8');
+
+const protocolDocPath = resolveCodevFile(
+  `protocols/${protocolName}/protocol.md`,
+  config.workspaceRoot,
+);
+if (protocolDocPath) {
+  template +=
+    `\n\n---\n\n## Protocol Reference (full text)\n\n` +
+    readFileSync(protocolDocPath, 'utf-8');
+} else {
+  logger.debug(`No protocol.md found for ${protocolName}; spawning without inlined reference`);
+}
+return template;
+```
+
+### Locked plan-gate decisions
+
+1. **Delimiter / heading.** Append after a horizontal rule under an H2:
+   `\n\n---\n\n## Protocol Reference (full text)\n\n<contents>`. The `---` + distinct heading
+   keeps the meta-doc visually separate from the per-phase instructions above it, so the two
+   don't blur in the builder's context. (Matches the issue's proposed wording.)
+
+2. **Missing `protocol.md` → silently skip, no error**, with a `logger.debug` note. This is
+   safe because `validateProtocol()` runs *earlier* in the spawn flow and already `fatal()`s
+   if **both** `protocol.json` and `protocol.md` are absent. So reaching `loadBuilderPromptTemplate`
+   with a missing `protocol.md` implies `protocol.json` exists — a malformed-but-registered
+   protocol, not a typo. Spawning without the inline (rather than aborting) is the right
+   degradation. (Satisfies acceptance criterion #2.)
+
+3. **Unconditional — no config flag.** The inline cost is ~90–660 lines of markdown delivered
+   once at spawn; there is no scenario where a user wants the builder to *not* have its own
+   protocol doc. A flag would be dead configuration.
+
+### Where the inline happens relative to `renderTemplate()`
+
+`buildPromptFromTemplate()` passes the returned template through `renderTemplate()`, which does
+handlebars substitution, collapses `\n{3,}` → `\n\n`, and trims. Inlining inside
+`loadBuilderPromptTemplate()` (per the issue and acceptance criterion #1) means the appended
+`protocol.md` also passes through `renderTemplate()`. This is **verified safe today**: a grep
+confirms **zero `{{` occurrences across all 8 skeleton `protocol.md` files**, so the substitution
+pass is a no-op on the appended text. The only transformation is the newline-collapse, which is
+harmless for markdown (single blank lines between blocks are preserved). See Risks for the
+forward-looking consideration.
+
+## Files to Change
+
+- `packages/codev/src/agent-farm/commands/spawn-roles.ts:99-108` — extend
+  `loadBuilderPromptTemplate()` to resolve and append `protocol.md` under the
+  `## Protocol Reference (full text)` delimiter; `logger.debug` when absent. (~12 LOC.)
+- `packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts` — in the skeleton-fallback
+  `describe` block (which already builds a temp skeleton with `spir/builder-prompt.md`), add a
+  `protocol.md` to the temp skeleton and assert that `buildPromptFromTemplate(...)` output
+  contains both the rendered template text **and** the `## Protocol Reference (full text)`
+  heading plus the protocol.md body. Add a second assertion: when no `protocol.md` exists in
+  the skeleton, the prompt still builds and simply omits the reference section (covers criterion
+  #2). (~25 LOC of test.)
+
+No changes to: the resolver, porch, any CLI surface, per-phase prompts, or the
+`builder-prompt.md` templates themselves (the literal `cat` instruction can stay — the inlined
+copy makes it redundant rather than wrong, and rewriting 10 templates is out of scope per the
+issue).
+
+## Risks & Alternatives Considered
+
+- **Risk: a future `protocol.md` containing `{{...}}`** (e.g. a protocol doc that documents the
+  prompt-templating syntax) would be mangled by `renderTemplate()`.
+  *Mitigation / chosen position:* none of the 8 current docs contain handlebars (verified), and
+  this is a documented invariant. If a protocol doc ever needs literal `{{`, the one-line fix is
+  to move the append from `loadBuilderPromptTemplate()` (pre-render) into
+  `buildPromptFromTemplate()` (post-render), delivering `protocol.md` verbatim. I am *not* doing
+  that now to keep the change minimal and matching acceptance criterion #1, but flagging it as
+  the known escape hatch.
+- **Alternative: append post-render in `buildPromptFromTemplate()`.** More future-proof against
+  the handlebars risk, but spreads the prompt-assembly logic across two functions and diverges
+  from the issue's stated design (criterion #1 names `loadBuilderPromptTemplate`). Rejected as
+  premature; the escape hatch above covers it if ever needed.
+- **Risk: prompt bloat.** SPIR's `protocol.md` is 657 lines (~2K tokens). Delivered once at
+  spawn, not per phase — acceptable, and far cheaper than the per-phase re-injection the issue
+  explicitly rejected.
+- **Alternative: restore framework file copying on init/update** (the #738 "Option 2"). Out of
+  scope by the issue's own framing; reverses Spec 618. Not considered here.
+
+## Test Plan
+
+**Unit (automated, runs in `npm test` → `@cluesmith/codev`):**
+
+- New test in `spawn-roles.test.ts` skeleton-fallback block: temp skeleton gets a
+  `spir/protocol.md` with sentinel content; assert `buildPromptFromTemplate()` output contains
+  the rendered template, the `## Protocol Reference (full text)` heading, and the sentinel.
+- New test: temp skeleton with **no** `spir/protocol.md`; assert the prompt builds without error
+  and does **not** contain the `## Protocol Reference` heading (covers criterion #2).
+- All existing `spawn-roles.test.ts` cases continue to pass unchanged.
+
+**Build / typecheck:** `npm run build` from the worktree root (routes to
+`pnpm --filter @cluesmith/codev build`).
+
+**Manual (for the human at the `dev-approval` gate):**
+
+- Inspect the generated prompt directly. Quickest path: run the new unit test and read the
+  asserted output, or add a throwaway `console.log` of `buildPromptFromTemplate(...)` for a
+  protocol and confirm the protocol meta-doc is appended under the delimiter.
+- Optional end-to-end: in a scratch `codev init` project (no local `codev/protocols/`), spawn a
+  builder and confirm its initial prompt contains the protocol meta-doc — i.e. the builder no
+  longer needs to `cat` a non-existent file. (This is the symptom the fix exists for.)
+
+Note: `.codev/config.json` here has no `worktree.devCommand`, so `afx dev` is not applicable —
+this is a spawn-time prompt-assembly change, not a running-app change. The `dev-approval` review
+is "read the diff + run the unit test", which is appropriate for this class of change.
diff --git a/codev/state/pir-1011_thread.md b/codev/state/pir-1011_thread.md
new file mode 100644
index 000000000..65f76454f
--- /dev/null
+++ b/codev/state/pir-1011_thread.md
@@ -0,0 +1,14 @@
+# PIR #1011 — inline protocol.md into builder prompt at spawn
+
+## Plan phase (2026-06-08)
+
+Read issue #1011, PIR protocol, and the target code. Investigation findings:
+
+- Target: `loadBuilderPromptTemplate()` in `packages/codev/src/agent-farm/commands/spawn-roles.ts:99-108`.
+- The returned template flows through `renderTemplate()` in `buildPromptFromTemplate()` (handlebars substitution + `\n{3,}→\n\n` collapse + trim).
+- Verified: **zero `{{` occurrences across all 8 `codev-skeleton/protocols/*/protocol.md`** files, so appending protocol.md before render is safe today (no accidental substitution).
+- `validateProtocol()` already fatals earlier in the spawn flow if BOTH `protocol.json` and `protocol.md` are missing — so by the time we inline, a missing `protocol.md` means the json exists; silently skipping is correct.
+- Tests live in `packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts`; the skeleton-fallback `describe` block (issue #706) is the natural home for the new inline-behavior test.
+- Plan-gate decisions locked: (1) `---` + `## Protocol Reference (full text)` delimiter, (2) silently skip + debug log when protocol.md absent, (3) unconditional (no config flag).
+
+Plan written to `codev/plans/1011-agent-farm-inline-protocol-md-.md`. Awaiting plan-approval gate.

From a7680c9ec0c5247aee68d79cb3bc3863f64eb235 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:31:06 +1000
Subject: [PATCH 03/14] chore(porch): 1011 plan-approval gate-requested

---
 codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
index 1a8d94b9a..083ab9238 100644
--- a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
+++ b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
@@ -7,6 +7,7 @@ current_plan_phase: null
 gates:
   plan-approval:
     status: pending
+    requested_at: '2026-06-08T02:31:06.250Z'
   dev-approval:
     status: pending
   pr:
@@ -15,4 +16,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-08T02:27:23.467Z'
-updated_at: '2026-06-08T02:27:23.468Z'
+updated_at: '2026-06-08T02:31:06.251Z'

From f591dba2f7586a7962235ce61a0067317efb7eb0 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:52:55 +1000
Subject: [PATCH 04/14] chore(porch): 1011 plan-approval gate-approved

---
 .../projects/1011-agent-farm-inline-protocol-md-/status.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
index 083ab9238..7ad2876a2 100644
--- a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
+++ b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
@@ -6,8 +6,9 @@ plan_phases: []
 current_plan_phase: null
 gates:
   plan-approval:
-    status: pending
+    status: approved
     requested_at: '2026-06-08T02:31:06.250Z'
+    approved_at: '2026-06-08T02:52:55.657Z'
   dev-approval:
     status: pending
   pr:
@@ -16,4 +17,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-08T02:27:23.467Z'
-updated_at: '2026-06-08T02:31:06.251Z'
+updated_at: '2026-06-08T02:52:55.658Z'

From 9c4a44514999b6b82f8644298719cfdad45377f2 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:53:06 +1000
Subject: [PATCH 05/14] chore(porch): 1011 implement phase-transition

---
 .../projects/1011-agent-farm-inline-protocol-md-/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
index 7ad2876a2..f99aa40db 100644
--- a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
+++ b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
@@ -1,7 +1,7 @@
 id: '1011'
 title: agent-farm-inline-protocol-md-
 protocol: pir
-phase: plan
+phase: implement
 plan_phases: []
 current_plan_phase: null
 gates:
@@ -17,4 +17,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-08T02:27:23.467Z'
-updated_at: '2026-06-08T02:52:55.658Z'
+updated_at: '2026-06-08T02:53:06.467Z'

From d814851fbd0f233b211d72f1f9eaf2fcc603fbeb Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:56:00 +1000
Subject: [PATCH 06/14] [PIR #1011] Inline protocol.md into builder spawn
 prompt

---
 .../agent-farm/__tests__/spawn-roles.test.ts  | 39 +++++++++++++++++++
 .../src/agent-farm/commands/spawn-roles.ts    | 30 ++++++++++++--
 2 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts b/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts
index e955d222f..2fbba9d70 100644
--- a/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts
+++ b/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts
@@ -363,6 +363,45 @@ describe('spawn-roles', () => {
       expect(prompt).toContain('SPIR prompt for a v3 feature');
     });
 
+    it('inlines protocol.md content under a Protocol Reference delimiter (issue #1011)', async () => {
+      const fs = await import('node:fs');
+      const path = await import('node:path');
+      fs.writeFileSync(
+        path.join(skeletonRoot, 'protocols', 'spir', 'protocol.md'),
+        '# SPIR Protocol\n\nMETA_DOC_SENTINEL: gate semantics and when-to-use guidance.',
+      );
+
+      const ctx: TemplateContext = {
+        protocol_name: 'SPIR',
+        mode: 'strict',
+        mode_soft: false,
+        mode_strict: true,
+        input_description: 'a v3 feature',
+      };
+      const prompt = buildPromptFromTemplate(makeConfig(), 'spir', ctx);
+
+      // Still carries the rendered builder-prompt template...
+      expect(prompt).toContain('SPIR prompt for a v3 feature');
+      // ...plus the inlined protocol meta-doc under a clear delimiter heading.
+      expect(prompt).toContain('## Protocol Reference (full text)');
+      expect(prompt).toContain('META_DOC_SENTINEL: gate semantics and when-to-use guidance.');
+    });
+
+    it('builds the prompt without error and omits the reference when protocol.md is absent (issue #1011)', () => {
+      // The skeleton-fallback beforeEach creates spir/ with no protocol.md.
+      const ctx: TemplateContext = {
+        protocol_name: 'SPIR',
+        mode: 'strict',
+        mode_soft: false,
+        mode_strict: true,
+        input_description: 'a v3 feature',
+      };
+      const prompt = buildPromptFromTemplate(makeConfig(), 'spir', ctx);
+
+      expect(prompt).toContain('SPIR prompt for a v3 feature');
+      expect(prompt).not.toContain('## Protocol Reference (full text)');
+    });
+
     it('local codev/protocols/ takes precedence over skeleton', async () => {
       const fs = await import('node:fs');
       const path = await import('node:path');
diff --git a/packages/codev/src/agent-farm/commands/spawn-roles.ts b/packages/codev/src/agent-farm/commands/spawn-roles.ts
index 807aff34d..f434fcad0 100644
--- a/packages/codev/src/agent-farm/commands/spawn-roles.ts
+++ b/packages/codev/src/agent-farm/commands/spawn-roles.ts
@@ -101,10 +101,34 @@ function loadBuilderPromptTemplate(config: Config, protocolName: string): string
     `protocols/${protocolName}/builder-prompt.md`,
     config.workspaceRoot,
   );
-  if (templatePath) {
-    return readFileSync(templatePath, 'utf-8');
+  if (!templatePath) {
+    return null;
   }
-  return null;
+  let template = readFileSync(templatePath, 'utf-8');
+
+  // Inline protocol.md so the builder has the protocol meta-doc in its initial
+  // context instead of fetching it. Post-Spec-618 fresh installs don't copy
+  // protocol files locally; the resolver finds protocol.md in the embedded
+  // skeleton (tier 4), but the builder-prompt's literal `cat codev/protocols/...`
+  // instruction can't — it would hit an empty path and waste turns hunting.
+  // Delivering it inline at spawn means the builder never runs a shell command
+  // that bypasses the resolver, and the meta-doc is in early conversation
+  // context for the whole session (read once, never re-shipped per phase).
+  const protocolDocPath = resolveCodevFile(
+    `protocols/${protocolName}/protocol.md`,
+    config.workspaceRoot,
+  );
+  if (protocolDocPath) {
+    template += `\n\n---\n\n## Protocol Reference (full text)\n\n` +
+      readFileSync(protocolDocPath, 'utf-8');
+  } else {
+    // Missing protocol.md is not fatal here: validateProtocol() runs earlier in
+    // the spawn flow and already aborts if both protocol.json and protocol.md
+    // are absent. Reaching this point means the json exists; spawn proceeds
+    // without the inline reference rather than failing.
+    logger.debug(`No protocol.md found for ${protocolName}; spawning without inlined reference`);
+  }
+  return template;
 }
 
 /**

From 0a7fcbbd3c2cf54ae14f7410ca0de030dab380ba Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:56:40 +1000
Subject: [PATCH 07/14] chore(porch): 1011 dev-approval gate-requested

---
 codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
index f99aa40db..a413abd24 100644
--- a/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
+++ b/codev/projects/1011-agent-farm-inline-protocol-md-/status.yaml
@@ -11,10 +11,11 @@ gates:
     approved_at: '2026-06-08T02:52:55.657Z'
   dev-approval:
     status: pending
+    requested_at: '2026-06-08T02:56:40.545Z'
   pr:
     status: pending
 iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-08T02:27:23.467Z'
-updated_at: '2026-06-08T02:53:06.467Z'
+updated_at: '2026-06-08T02:56:40.546Z'

From b64328f2383b7d8fe9fd190419314e9322b95a37 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 12:57:05 +1000
Subject: [PATCH 08/14] [PIR #1011] Update thread log: implement phase

---
 codev/state/pir-1011_thread.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/codev/state/pir-1011_thread.md b/codev/state/pir-1011_thread.md
index 65f76454f..cf2a2a699 100644
--- a/codev/state/pir-1011_thread.md
+++ b/codev/state/pir-1011_thread.md
@@ -12,3 +12,12 @@ Read issue #1011, PIR protocol, and the target code. Investigation findings:
 - Plan-gate decisions locked: (1) `---` + `## Protocol Reference (full text)` delimiter, (2) silently skip + debug log when protocol.md absent, (3) unconditional (no config flag).
 
 Plan written to `codev/plans/1011-agent-farm-inline-protocol-md-.md`. Awaiting plan-approval gate.
+
+## Implement phase (2026-06-08)
+
+plan-approval approved. Implemented per plan:
+
+- `spawn-roles.ts`: `loadBuilderPromptTemplate()` now resolves `protocol.md` via `resolveCodevFile()` and appends it under `\n\n---\n\n## Protocol Reference (full text)\n\n`. Missing protocol.md → `logger.debug` + skip (validateProtocol already fatals earlier if both json+md absent).
+- `spawn-roles.test.ts`: 2 new tests in the skeleton-fallback block — (1) inlines protocol.md under the delimiter with a sentinel body, (2) builds without error and omits the heading when protocol.md is absent.
+
+Build ✓ (root `npm run build`), full suite ✓ (3260 passed, 13 pre-existing skips — none mine). Committed + pushed. At dev-approval gate.

From 46a18c0de0c557c751608a45951af271fa05cab3 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 13:31:38 +1000
Subject: [PATCH 09/14] [PIR #1011] Revise plan for expanded framework-file
 class scope (A.1/A.2/A.3)

---
 .../1011-agent-farm-inline-protocol-md-.md    | 265 +++++++++---------
 1 file changed, 135 insertions(+), 130 deletions(-)

diff --git a/codev/plans/1011-agent-farm-inline-protocol-md-.md b/codev/plans/1011-agent-farm-inline-protocol-md-.md
index e1bc6c605..6ab23f4f8 100644
--- a/codev/plans/1011-agent-farm-inline-protocol-md-.md
+++ b/codev/plans/1011-agent-farm-inline-protocol-md-.md
@@ -1,148 +1,153 @@
-# PIR Plan: Inline `protocol.md` into the builder prompt at spawn
+# PIR Plan: Deliver framework files via resolver-aware channels (fresh-install class fix)
+
+> **Scope note (2026-06-08):** Issue #1011 was expanded mid-plan from "inline protocol.md
+> at spawn" to the whole class of framework-file literal-path references reachable from
+> builder-side consumers (sub-cases A.1 / A.2 / A.3). This plan supersedes the original
+> narrow version. Patch 1 (A.1) is already implemented and sitting at the `dev-approval`
+> gate; this revision adds Patch 2 (A.2) and the A.3 disposition. The project-bootstrap gap
+> (`codev/resources/` not created on init) is explicitly **out of scope** (separate issue).
 
 ## Understanding
 
-Spec 618 correctly moved framework files (protocols, roles, resources) out of user
-projects and into the embedded package skeleton, resolved at runtime via the four-tier
-resolver (`.codev/` → `codev/` → cache → skeleton). The resolver works.
+Spec 618 moved framework files into the package skeleton (resolver tier 4). The resolver
+(`resolveCodevFile`, `skeleton.ts:63`) reaches them correctly. The bug is **consumer-side**:
+prompts, role docs, and protocol docs reference framework files by **literal path**, which a
+raw shell `cat`/`cp` cannot resolve when the file lives only in the embedded skeleton (fresh
+post-618 installs). The builder hits "No such file" and wastes turns hunting.
+
+Three observed sub-instances:
+
+- **A.1 — protocol meta-doc.** All 9 `builder-prompt.md` files instruct `codev/protocols/<name>/protocol.md`; `roles/builder.md:83` has a literal `cat codev/protocols/spir/protocol.md`.
+- **A.2 — template references.** 4 references to `codev/protocols/<name>/templates/<file>`:
+  - `spir/prompts/plan.md:79`, `aspir/prompts/plan.md:79` — "Use the plan template … if available"
+  - `experiment/protocol.md:40` — `cp codev/protocols/experiment/templates/notes.md notes.md`
+  - `spike/protocol.md:55` — "Use the template: `…/templates/findings.md`"
+- **A.3 — workflow-reference.** `spir/protocol.md:7` (`> Quick Reference: See codev/resources/workflow-reference.md …`). Once A.1 delivers protocol.md inline, this pointer rides along and itself bypasses the resolver.
+
+### Key investigation finding (drives decision #2)
+
+The 4 A.2 references are **heterogeneous**:
+- `spir`/`aspir` plan prompts **already embed** a self-contained `### Plan Structure` block
+  (`spir/prompts/plan.md:81+`) — a *different, simpler* layout than the 184-line canonical
+  `templates/plan.md`. The "if available" pointer is **redundant chrome**, not load-bearing.
+- `experiment` (`notes.md`, 97 lines) and `spike` (`findings.md`, 67 lines) reference
+  **genuine content** with no inline equivalent in their protocol.md.
+
+This is why **explicit-embed (B) is correct and auto-detect (A) is wrong**: an auto-inliner
+would deliver the 184-line canonical plan template *on top of* the prompt's existing
+`### Plan Structure`, giving the builder two conflicting plan layouts. A human embedder drops
+the redundant pointer and embeds only genuine content; a regex cannot make that distinction.
+
+## Locked Decisions (the 5 plan-gate decisions)
+
+**1 — Delimiter / heading format.**
+- Patch 1 (protocol.md): `\n\n---\n\n## Protocol Reference (full text)\n\n<contents>` (already implemented).
+- Patch 2 embeds (experiment/spike): under a clearly fenced sub-section adjacent to the
+  reworded instruction, e.g.:
+  ```
+  > The following is the embedded copy of the <name> template, delivered inline so you do
+  > not need to fetch a file. Recreate the target file from this content.
+
+  <!-- BEGIN EMBEDDED TEMPLATE: protocols/<name>/templates/<file> -->
+  <template contents>
+  <!-- END EMBEDDED TEMPLATE: protocols/<name>/templates/<file> -->
+  ```
+  The `BEGIN/END … <path>` sentinels double as the anchor for the drift-guard test (below).
+
+**2 — A.2 mechanism: Option B (explicit-embed). [agree with architect, strengthened]**
+Sub-handled by reference kind (per the investigation finding):
+- `spir/prompts/plan.md:79` + `aspir/prompts/plan.md:79` → **drop the redundant pointer line**
+  (the prompt's `### Plan Structure` is already self-contained). No embed.
+- `experiment/protocol.md:40` → reword the `cp` step to "create `notes.md` from the embedded
+  template below" + embed `notes.md` content under the sentinel block.
+- `spike/protocol.md:55` → reword to "use the embedded template below" + embed `findings.md`.
+Rationale beyond the architect's (static refs / simple runtime / readable prompts): auto-detect
+would double-deliver a conflicting plan layout for spir/aspir. B also turns out *cheaper* than
+the 40–100-line estimate feared — the 184-line plan template is dropped, not duplicated; only
+`notes.md` (97) + `findings.md` (67) are embedded.
+
+**3 — A.3 disposition: Option 2 (strip). [agree with architect]**
+Remove the `> Quick Reference: See codev/resources/workflow-reference.md …` line from
+`spir/protocol.md`. Informational chrome the protocol works fine without; stripping removes a
+known fail-source at zero risk. The `roles/architect.md:5` reference (architect-side consumer)
+stays out of scope.
+
+**4 — Resolve-failure behavior: silently skip + `logger.debug` (no stderr warn).**
+Rationale: (a) `validateProtocol()` already `fatal()`s earlier if both `protocol.json` and
+`protocol.md` are absent, so the Patch-1 inline never silently no-ops in practice; (b) A.2 is
+explicit-embed (no runtime resolution to fail); (c) the A.2 source phrasing is literally
+"if available" — absence is a *normal, expected* state there, so a warning would be noise.
+
+**5 — Inline is always-on, not config-gated.** No scenario wants a builder without its own
+protocol doc; a flag would be dead configuration. State it; no flag added.
 
-The remaining bug is **consumer-side**: every protocol's `builder-prompt.md` tells the
-builder to read `codev/protocols/<name>/protocol.md` — a literal path that does not exist
-on disk in a fresh post-618 install (the file lives only in the embedded skeleton, reachable
-through the resolver but *not* through a raw `cat`). So a freshly-spawned builder runs the
-`cat`, gets "No such file", and wastes 1–3 minutes hunting before proceeding without the
-protocol meta-doc (workflow overview, gate semantics, when-to-use guidance).
+## Proposed Change
 
-The per-phase prompts (delivered via `porch next` JSON, resolver-mediated) already cover the
-actionable per-phase work, so they are *not* affected. The gap is purely the one-time meta-doc.
+### Patch 1 — Spawn-time protocol.md inline (A.1) — DONE, at dev-approval
 
-Verified in this worktree:
+`loadBuilderPromptTemplate()` (`spawn-roles.ts`) resolves `protocols/${protocolName}/protocol.md`
+via `resolveCodevFile` and appends it under the Protocol Reference delimiter; `logger.debug`
++ skip when absent. Protocol-agnostic — covers all 9 `builder-prompt.md` refs and the
+`roles/builder.md:83` cat (the builder already holds the content when it would have cat'd; per
+decision, the illustrative cat line in the role doc is left as-is, not edited).
 
-- `codev-skeleton/protocols/*/builder-prompt.md` contain literal `codev/protocols/<name>/protocol.md`
-  instructions — confirmed in all 10 protocol templates (e.g. `spir/builder-prompt.md:30`,
-  `pir/builder-prompt.md:30` and `:90`).
-- `loadBuilderPromptTemplate()` at `packages/codev/src/agent-farm/commands/spawn-roles.ts:99-108`
-  loads `builder-prompt.md` via `resolveCodevFile()` but never reads `protocol.md`.
-- `resolveCodevFile()` (`packages/codev/src/lib/skeleton.ts`) reaches the embedded skeleton
-  correctly. The resolver is not the bug.
+### Patch 2 — Template embeds (A.2) — explicit-embed, markdown-only (0 LOC code)
 
-## Proposed Change
+- Drop the redundant template pointer in `spir/prompts/plan.md` and `aspir/prompts/plan.md`.
+- Embed `notes.md` into `experiment/protocol.md` (reword the `cp` step).
+- Embed `findings.md` into `spike/protocol.md` (reword the use-template step).
 
-Extend `loadBuilderPromptTemplate()` to additionally resolve `protocols/<name>/protocol.md`
-via `resolveCodevFile()` and append its full text to the returned template under a clearly
-delimited heading. The builder then has the meta-doc in its initial prompt context for the
-whole session — read once, never re-shipped per phase, and the builder never runs a shell
-command that bypasses the resolver.
-
-Concretely, after loading the `builder-prompt.md` template and before returning it:
-
-```ts
-let template = readFileSync(templatePath, 'utf-8');
-
-const protocolDocPath = resolveCodevFile(
-  `protocols/${protocolName}/protocol.md`,
-  config.workspaceRoot,
-);
-if (protocolDocPath) {
-  template +=
-    `\n\n---\n\n## Protocol Reference (full text)\n\n` +
-    readFileSync(protocolDocPath, 'utf-8');
-} else {
-  logger.debug(`No protocol.md found for ${protocolName}; spawning without inlined reference`);
-}
-return template;
-```
-
-### Locked plan-gate decisions
-
-1. **Delimiter / heading.** Append after a horizontal rule under an H2:
-   `\n\n---\n\n## Protocol Reference (full text)\n\n<contents>`. The `---` + distinct heading
-   keeps the meta-doc visually separate from the per-phase instructions above it, so the two
-   don't blur in the builder's context. (Matches the issue's proposed wording.)
-
-2. **Missing `protocol.md` → silently skip, no error**, with a `logger.debug` note. This is
-   safe because `validateProtocol()` runs *earlier* in the spawn flow and already `fatal()`s
-   if **both** `protocol.json` and `protocol.md` are absent. So reaching `loadBuilderPromptTemplate`
-   with a missing `protocol.md` implies `protocol.json` exists — a malformed-but-registered
-   protocol, not a typo. Spawning without the inline (rather than aborting) is the right
-   degradation. (Satisfies acceptance criterion #2.)
-
-3. **Unconditional — no config flag.** The inline cost is ~90–660 lines of markdown delivered
-   once at spawn; there is no scenario where a user wants the builder to *not* have its own
-   protocol doc. A flag would be dead configuration.
-
-### Where the inline happens relative to `renderTemplate()`
-
-`buildPromptFromTemplate()` passes the returned template through `renderTemplate()`, which does
-handlebars substitution, collapses `\n{3,}` → `\n\n`, and trims. Inlining inside
-`loadBuilderPromptTemplate()` (per the issue and acceptance criterion #1) means the appended
-`protocol.md` also passes through `renderTemplate()`. This is **verified safe today**: a grep
-confirms **zero `{{` occurrences across all 8 skeleton `protocol.md` files**, so the substitution
-pass is a no-op on the appended text. The only transformation is the newline-collapse, which is
-harmless for markdown (single blank lines between blocks are preserved). See Risks for the
-forward-looking consideration.
+### A.3 — strip the workflow-reference pointer from `spir/protocol.md`.
+
+### Tree scope: edit **both** `codev-skeleton/` (the shipped source, required for the
+fresh-install fix + the repro test) **and** the local `codev/` copies (this repo dogfoods;
+its `codev/` shadows the skeleton, so leaving it stale would drift our own instance). Patch 1
+needs no markdown edits in either tree (resolver-mediated code).
 
 ## Files to Change
 
-- `packages/codev/src/agent-farm/commands/spawn-roles.ts:99-108` — extend
-  `loadBuilderPromptTemplate()` to resolve and append `protocol.md` under the
-  `## Protocol Reference (full text)` delimiter; `logger.debug` when absent. (~12 LOC.)
-- `packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts` — in the skeleton-fallback
-  `describe` block (which already builds a temp skeleton with `spir/builder-prompt.md`), add a
-  `protocol.md` to the temp skeleton and assert that `buildPromptFromTemplate(...)` output
-  contains both the rendered template text **and** the `## Protocol Reference (full text)`
-  heading plus the protocol.md body. Add a second assertion: when no `protocol.md` exists in
-  the skeleton, the prompt still builds and simply omits the reference section (covers criterion
-  #2). (~25 LOC of test.)
-
-No changes to: the resolver, porch, any CLI surface, per-phase prompts, or the
-`builder-prompt.md` templates themselves (the literal `cat` instruction can stay — the inlined
-copy makes it redundant rather than wrong, and rewriting 10 templates is out of scope per the
-issue).
+- `packages/codev/src/agent-farm/commands/spawn-roles.ts` — Patch 1 (done).
+- `packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts` — Patch 1 tests (done) + no new code path for Patch 2.
+- `{codev-skeleton,codev}/protocols/spir/prompts/plan.md` — drop redundant template pointer.
+- `{codev-skeleton,codev}/protocols/aspir/prompts/plan.md` — drop redundant template pointer.
+- `{codev-skeleton,codev}/protocols/experiment/protocol.md` — embed `notes.md`, reword `cp`.
+- `{codev-skeleton,codev}/protocols/spike/protocol.md` — embed `findings.md`, reword.
+- `{codev-skeleton,codev}/protocols/spir/protocol.md` — strip workflow-reference line (A.3).
+- `packages/codev/src/.../__tests__/` — new content-guard test (see Test Plan).
 
 ## Risks & Alternatives Considered
 
-- **Risk: a future `protocol.md` containing `{{...}}`** (e.g. a protocol doc that documents the
-  prompt-templating syntax) would be mangled by `renderTemplate()`.
-  *Mitigation / chosen position:* none of the 8 current docs contain handlebars (verified), and
-  this is a documented invariant. If a protocol doc ever needs literal `{{`, the one-line fix is
-  to move the append from `loadBuilderPromptTemplate()` (pre-render) into
-  `buildPromptFromTemplate()` (post-render), delivering `protocol.md` verbatim. I am *not* doing
-  that now to keep the change minimal and matching acceptance criterion #1, but flagging it as
-  the known escape hatch.
-- **Alternative: append post-render in `buildPromptFromTemplate()`.** More future-proof against
-  the handlebars risk, but spreads the prompt-assembly logic across two functions and diverges
-  from the issue's stated design (criterion #1 names `loadBuilderPromptTemplate`). Rejected as
-  premature; the escape hatch above covers it if ever needed.
-- **Risk: prompt bloat.** SPIR's `protocol.md` is 657 lines (~2K tokens). Delivered once at
-  spawn, not per phase — acceptable, and far cheaper than the per-phase re-injection the issue
-  explicitly rejected.
-- **Alternative: restore framework file copying on init/update** (the #738 "Option 2"). Out of
-  scope by the issue's own framing; reverses Spec 618. Not considered here.
+- **Risk: embedded template drifts from canonical `templates/*.md`.** Mitigation: a unit test
+  asserts the embedded block (between the `BEGIN/END EMBEDDED TEMPLATE` sentinels) byte-matches
+  the canonical template file. Drift fails CI. Applies to `notes.md` and `findings.md`.
+- **Alternative: A.2 = auto-detect (Option A).** Rejected — would double-deliver a conflicting
+  plan layout for spir/aspir (see finding) and needs traversal in two channels (porch
+  `loadPromptFile` + spawn inline). B is simpler, correct, and human-discriminating.
+- **Risk: residual single failed `cat`.** With Patch 1 leaving the builder-prompt's "read
+  protocol.md" instruction intact (per the rejected-alternative "drop the instructions" —
+  ruled out for per-protocol audit cost), an eager builder *could* still `cat` once before
+  noticing the inlined copy. Accepted: the content's presence prevents the multi-minute *hunt*
+  (the actual symptom); the clear `## Protocol Reference` delimiter (decision #1) mitigates
+  "louder than the per-phase prompt" confusion. Flagged for the dev-approval check.
+- **Observed but out of scope:** additional *relative-path* template refs inside protocol.md
+  (`spir/protocol.md:215` `templates/spec.md`, `:301` `templates/plan.md`,
+  `experiment/protocol.md:90` `templates/notes.md`). Relative + informational; not in the
+  architect's enumerated A.2 set. Left as-is unless you want them folded in.
 
 ## Test Plan
 
-**Unit (automated, runs in `npm test` → `@cluesmith/codev`):**
-
-- New test in `spawn-roles.test.ts` skeleton-fallback block: temp skeleton gets a
-  `spir/protocol.md` with sentinel content; assert `buildPromptFromTemplate()` output contains
-  the rendered template, the `## Protocol Reference (full text)` heading, and the sentinel.
-- New test: temp skeleton with **no** `spir/protocol.md`; assert the prompt builds without error
-  and does **not** contain the `## Protocol Reference` heading (covers criterion #2).
-- All existing `spawn-roles.test.ts` cases continue to pass unchanged.
-
-**Build / typecheck:** `npm run build` from the worktree root (routes to
-`pnpm --filter @cluesmith/codev build`).
-
-**Manual (for the human at the `dev-approval` gate):**
-
-- Inspect the generated prompt directly. Quickest path: run the new unit test and read the
-  asserted output, or add a throwaway `console.log` of `buildPromptFromTemplate(...)` for a
-  protocol and confirm the protocol meta-doc is appended under the delimiter.
-- Optional end-to-end: in a scratch `codev init` project (no local `codev/protocols/`), spawn a
-  builder and confirm its initial prompt contains the protocol meta-doc — i.e. the builder no
-  longer needs to `cat` a non-existent file. (This is the symptom the fix exists for.)
-
-Note: `.codev/config.json` here has no `worktree.devCommand`, so `afx dev` is not applicable —
-this is a spawn-time prompt-assembly change, not a running-app change. The `dev-approval` review
-is "read the diff + run the unit test", which is appropriate for this class of change.
+**Automated (in `npm test` → `@cluesmith/codev`):**
+- Patch 1 (exist): protocol.md inlined under the delimiter; omitted without error when absent.
+- A.2 content guard (new): load `spir/prompts/plan.md` + `aspir/prompts/plan.md` from the
+  skeleton; assert the dead template-path pointer is **absent** and the self-contained
+  `### Plan Structure` is **present**. Load `experiment/protocol.md` + `spike/protocol.md`;
+  assert the embedded template block is present **and byte-matches** the canonical
+  `templates/notes.md` / `templates/findings.md` (drift guard).
+- A.3 guard (new): assert `spir/protocol.md` no longer references `workflow-reference.md`.
+
+**Build:** `npm run build` from worktree root.
+
+**Manual (dev-approval, load-bearing — repro from issue):** fresh `codev init` in a tmp dir,
+spawn a test PIR builder, run through plan + implement; confirm (a) no file-hunting for
+protocol.md OR templates, (b) the builder still follows per-phase prompts (inlined material
+not "louder"), (c) per-phase templates land in the right phase. PR-diff review can't catch these.

From f8848a64ead79202b12a0d24792c9955a27a0cdd Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 13:44:08 +1000
Subject: [PATCH 10/14] [PIR #1011] Revise plan to three-layer scope
 (delivery/cleanup/enforcement)

---
 .../1011-agent-farm-inline-protocol-md-.md    | 251 +++++++++---------
 1 file changed, 126 insertions(+), 125 deletions(-)

diff --git a/codev/plans/1011-agent-farm-inline-protocol-md-.md b/codev/plans/1011-agent-farm-inline-protocol-md-.md
index 6ab23f4f8..14e07f30a 100644
--- a/codev/plans/1011-agent-farm-inline-protocol-md-.md
+++ b/codev/plans/1011-agent-farm-inline-protocol-md-.md
@@ -1,153 +1,154 @@
 # PIR Plan: Deliver framework files via resolver-aware channels (fresh-install class fix)
 
-> **Scope note (2026-06-08):** Issue #1011 was expanded mid-plan from "inline protocol.md
-> at spawn" to the whole class of framework-file literal-path references reachable from
-> builder-side consumers (sub-cases A.1 / A.2 / A.3). This plan supersedes the original
-> narrow version. Patch 1 (A.1) is already implemented and sitting at the `dev-approval`
-> gate; this revision adds Patch 2 (A.2) and the A.3 disposition. The project-bootstrap gap
-> (`codev/resources/` not created on init) is explicitly **out of scope** (separate issue).
+> **Scope history (2026-06-08):** #1011 grew from "inline protocol.md at spawn" → a
+> framework-file class fix → its current **three-layer** form (Delivery / Cleanup /
+> Enforcement). This plan tracks the three-layer body. Patch 1 (Layer 1 / A.1) is already
+> implemented and at the `dev-approval` gate; this revision folds in the rest. `codev read`
+> CLI is **explicitly rejected** — not proposed. Project bootstrap of `codev/resources/` is
+> **#1012** (out of scope here).
 
 ## Understanding
 
-Spec 618 moved framework files into the package skeleton (resolver tier 4). The resolver
-(`resolveCodevFile`, `skeleton.ts:63`) reaches them correctly. The bug is **consumer-side**:
-prompts, role docs, and protocol docs reference framework files by **literal path**, which a
-raw shell `cat`/`cp` cannot resolve when the file lives only in the embedded skeleton (fresh
-post-618 installs). The builder hits "No such file" and wastes turns hunting.
-
-Three observed sub-instances:
-
-- **A.1 — protocol meta-doc.** All 9 `builder-prompt.md` files instruct `codev/protocols/<name>/protocol.md`; `roles/builder.md:83` has a literal `cat codev/protocols/spir/protocol.md`.
-- **A.2 — template references.** 4 references to `codev/protocols/<name>/templates/<file>`:
-  - `spir/prompts/plan.md:79`, `aspir/prompts/plan.md:79` — "Use the plan template … if available"
-  - `experiment/protocol.md:40` — `cp codev/protocols/experiment/templates/notes.md notes.md`
-  - `spike/protocol.md:55` — "Use the template: `…/templates/findings.md`"
-- **A.3 — workflow-reference.** `spir/protocol.md:7` (`> Quick Reference: See codev/resources/workflow-reference.md …`). Once A.1 delivers protocol.md inline, this pointer rides along and itself bypasses the resolver.
-
-### Key investigation finding (drives decision #2)
-
-The 4 A.2 references are **heterogeneous**:
-- `spir`/`aspir` plan prompts **already embed** a self-contained `### Plan Structure` block
-  (`spir/prompts/plan.md:81+`) — a *different, simpler* layout than the 184-line canonical
-  `templates/plan.md`. The "if available" pointer is **redundant chrome**, not load-bearing.
-- `experiment` (`notes.md`, 97 lines) and `spike` (`findings.md`, 67 lines) reference
-  **genuine content** with no inline equivalent in their protocol.md.
-
-This is why **explicit-embed (B) is correct and auto-detect (A) is wrong**: an auto-inliner
-would deliver the 184-line canonical plan template *on top of* the prompt's existing
-`### Plan Structure`, giving the builder two conflicting plan layouts. A human embedder drops
-the redundant pointer and embeds only genuine content; a regex cannot make that distinction.
+Spec 618 moved framework files into the package skeleton (resolver tier 4). `resolveCodevFile`
+(`skeleton.ts:63`) reaches them. The bug is **consumer-side**: prompts, role docs, and protocol
+docs reference framework files by **literal path**, which a raw shell `cat`/`cp` can't resolve
+when the file lives only in the embedded skeleton (fresh post-618 installs). The builder hits
+"No such file" and wastes turns. Three sub-instances: A.1 (protocol.md from 9 builder-prompts +
+`roles/builder.md:83` cat), A.2 (4 template refs), A.3 (workflow-reference inside `spir/protocol.md`).
+
+### Investigation findings that drive the decisions
+
+1. **A.2 references are heterogeneous.** `spir`/`aspir` `prompts/plan.md` already embed a
+   self-contained `### Plan Structure` block (a *simpler, different* layout than the 184-line
+   canonical `templates/plan.md`) — the template pointer is **redundant chrome**. Only
+   `experiment` (`notes.md`, 97L) and `spike` (`findings.md`, 67L) are **genuine content**.
+2. **`bugfix` ships no `protocol.md` in the skeleton** (only `protocol.json` + prompts), yet its
+   `builder-prompt.md:28` references one, and the local `codev/` tree carries a real **548-line**
+   `bugfix/protocol.md` that was *never tracked in the skeleton*. So Patch 1 cannot inline for
+   bugfix, and after Layer 2 drops the pointer, bugfix would have **no meta-doc at all** in fresh
+   installs. See "Open sub-decision" below — this needs an explicit call.
+3. **Embedded `notes.md`/`findings.md` contain zero `{{`**, so inlining them through
+   `renderTemplate` (they ride inside `experiment`/`spike` `protocol.md`) is collision-safe.
 
 ## Locked Decisions (the 5 plan-gate decisions)
 
 **1 — Delimiter / heading format.**
-- Patch 1 (protocol.md): `\n\n---\n\n## Protocol Reference (full text)\n\n<contents>` (already implemented).
-- Patch 2 embeds (experiment/spike): under a clearly fenced sub-section adjacent to the
-  reworded instruction, e.g.:
+- Patch 1 (protocol.md): `\n\n---\n\n## Protocol Reference (full text)\n\n<contents>` (done).
+- Patch 2 embeds (experiment/spike): a `## Template` section near the reworded instruction,
+  with drift-anchor sentinels that use the **skeleton-relative** path (no `codev/` prefix, so the
+  Layer 3 doctor grep does not self-flag them):
   ```
-  > The following is the embedded copy of the <name> template, delivered inline so you do
-  > not need to fetch a file. Recreate the target file from this content.
-
+  ## Template
+  > Embedded copy of the <name> template — delivered inline; recreate the target file from this.
   <!-- BEGIN EMBEDDED TEMPLATE: protocols/<name>/templates/<file> -->
   <template contents>
   <!-- END EMBEDDED TEMPLATE: protocols/<name>/templates/<file> -->
   ```
-  The `BEGIN/END … <path>` sentinels double as the anchor for the drift-guard test (below).
-
-**2 — A.2 mechanism: Option B (explicit-embed). [agree with architect, strengthened]**
-Sub-handled by reference kind (per the investigation finding):
-- `spir/prompts/plan.md:79` + `aspir/prompts/plan.md:79` → **drop the redundant pointer line**
-  (the prompt's `### Plan Structure` is already self-contained). No embed.
-- `experiment/protocol.md:40` → reword the `cp` step to "create `notes.md` from the embedded
-  template below" + embed `notes.md` content under the sentinel block.
-- `spike/protocol.md:55` → reword to "use the embedded template below" + embed `findings.md`.
-Rationale beyond the architect's (static refs / simple runtime / readable prompts): auto-detect
-would double-deliver a conflicting plan layout for spir/aspir. B also turns out *cheaper* than
-the 40–100-line estimate feared — the 184-line plan template is dropped, not duplicated; only
-`notes.md` (97) + `findings.md` (67) are embedded.
-
-**3 — A.3 disposition: Option 2 (strip). [agree with architect]**
-Remove the `> Quick Reference: See codev/resources/workflow-reference.md …` line from
-`spir/protocol.md`. Informational chrome the protocol works fine without; stripping removes a
-known fail-source at zero risk. The `roles/architect.md:5` reference (architect-side consumer)
-stays out of scope.
-
-**4 — Resolve-failure behavior: silently skip + `logger.debug` (no stderr warn).**
-Rationale: (a) `validateProtocol()` already `fatal()`s earlier if both `protocol.json` and
-`protocol.md` are absent, so the Patch-1 inline never silently no-ops in practice; (b) A.2 is
-explicit-embed (no runtime resolution to fail); (c) the A.2 source phrasing is literally
-"if available" — absence is a *normal, expected* state there, so a warning would be noise.
 
-**5 — Inline is always-on, not config-gated.** No scenario wants a builder without its own
-protocol doc; a flag would be dead configuration. State it; no flag added.
+**2 — Patch 2 mechanism: Option B (explicit-embed). [agree, strengthened]**
+Sub-handled by reference kind (finding #1): drop the redundant pointer in `spir`/`aspir`
+plan prompts (no embed — prompt already self-contained); embed `notes.md`/`findings.md` into
+`experiment`/`spike` `protocol.md`. Rationale beyond the architect's: auto-detect (A) would
+inline the 184-line canonical plan template *on top of* the existing `### Plan Structure`,
+delivering two conflicting layouts. B is correct, not just simpler; and cheaper than feared
+(~164 embedded lines, the big template dropped not duplicated).
 
-## Proposed Change
-
-### Patch 1 — Spawn-time protocol.md inline (A.1) — DONE, at dev-approval
-
-`loadBuilderPromptTemplate()` (`spawn-roles.ts`) resolves `protocols/${protocolName}/protocol.md`
-via `resolveCodevFile` and appends it under the Protocol Reference delimiter; `logger.debug`
-+ skip when absent. Protocol-agnostic — covers all 9 `builder-prompt.md` refs and the
-`roles/builder.md:83` cat (the builder already holds the content when it would have cat'd; per
-decision, the illustrative cat line in the role doc is left as-is, not edited).
-
-### Patch 2 — Template embeds (A.2) — explicit-embed, markdown-only (0 LOC code)
-
-- Drop the redundant template pointer in `spir/prompts/plan.md` and `aspir/prompts/plan.md`.
-- Embed `notes.md` into `experiment/protocol.md` (reword the `cp` step).
-- Embed `findings.md` into `spike/protocol.md` (reword the use-template step).
-
-### A.3 — strip the workflow-reference pointer from `spir/protocol.md`.
-
-### Tree scope: edit **both** `codev-skeleton/` (the shipped source, required for the
-fresh-install fix + the repro test) **and** the local `codev/` copies (this repo dogfoods;
-its `codev/` shadows the skeleton, so leaving it stale would drift our own instance). Patch 1
-needs no markdown edits in either tree (resolver-mediated code).
+**3 — A.3 disposition: Option 2 (strip). [agree]**
+Remove the `> Quick Reference: See codev/resources/workflow-reference.md …` line from
+`spir/protocol.md`. Informational chrome; zero-risk removal. `roles/architect.md:5` stays out.
+
+**4 — Missing-framework-file behavior: silently skip + `logger.debug` (no stderr warn).**
+The skip is a **routine, by-design state**: `bugfix` has no skeleton `protocol.md`, so Patch 1's
+resolve returns null and skips on every bugfix spawn (`validateProtocol` only `fatal()`s when
+*both* json and md are absent). A stderr warn would fire on every bugfix spawn about an
+intentionally-absent file. A.2 = embed (no runtime resolution to fail). Skip + debug it is.
+
+**5 — Doctor check semantics: warn-not-error, skeleton-only initially. [agree]**
+`codev doctor` greps for resolver-bypassing **absolute** literal paths only —
+`cat codev/(protocols|roles|resources)/…` and backtick-wrapped `` `codev/(protocols|roles|resources)/…` `` —
+and reports `status: 'warn'` (never `'fail'`) with a pointer to the convention. Skeleton dir only
+for now (user `codev/` customizations are theirs; flagging them risks noise). Scope matches
+Layer 2's sweep so a post-sweep skeleton is clean. Relative-path refs (`templates/x.md`,
+`spir/protocol.md:215/301`, `experiment/protocol.md:90`) are a lower-severity class **not**
+targeted (kept out of both the sweep and the grep) — noted as observed-out-of-scope.
+
+## Open sub-decision (needs your call — finding #2)
+
+`bugfix` is the one protocol whose meta-doc isn't in the skeleton. Options:
+- **(i) Ship `bugfix/protocol.md` into the skeleton** (copy the existing 548-line `codev/` doc).
+  Makes Layer 1 cover bugfix uniformly; Layer 2 sweep then safe. *Recommended* — every other
+  protocol ships its `protocol.md`; the absence reads as an oversight. Cost: +548 lines in the
+  published skeleton.
+- **(ii) Treat bugfix as intentionally meta-doc-less**: drop the pointer (Layer 2), inline nothing,
+  rely on `builder-prompt.md` + phase prompts being self-contained. Cost: bugfix builders lose the
+  548-line protocol context that our own instance has.
+- **(iii) Split to a separate skeleton-completeness issue**; here, just don't regress bugfix.
+I'll default to **(i)** unless you say otherwise.
+
+## Proposed Change (three layers)
+
+**Layer 1 — Delivery.**
+- *Patch 1 (A.1, done):* `loadBuilderPromptTemplate()` inlines `protocol.md` under the delimiter.
+- *Patch 2 (A.2):* Option B embeds (per decision 2) — markdown only, 0 LOC code.
+
+**Layer 2 — Cleanup (skeleton sweep).**
+- Drop the `Follow the <X> protocol: \`…protocol.md\`` line from all 9 `builder-prompt.md`
+  (PIR has two refs: `:30` and the `:90` getting-started line — both go; keep PIR's 3-phase
+  breakdown). The protocol text is already in context via Patch 1.
+- `roles/builder.md:83`: replace the `cat codev/protocols/spir/protocol.md` example with a note
+  that the protocol is inlined in the spawn prompt under `## Protocol Reference`.
+- A.2 literal paths leave the four prompts by construction (decision 2).
+- A.3: strip per decision 3.
+
+**Layer 3 — Enforcement.**
+- *Convention doc:* add a "Framework files: never reference by literal `codev/…` path" section to
+  **both** `AGENTS.md` and `CLAUDE.md` (kept in sync, per repo policy).
+- *Doctor audit:* add a check to `doctor()` (`packages/codev/src/commands/doctor.ts:539`) mirroring
+  the existing `CheckResult`/`printStatus` pattern (decision 5 semantics).
+
+### Tree scope
+Edit **both** `codev-skeleton/` (shipped source; required for the fix + repro test) and the
+local `codev/` copies (this repo dogfoods; its `codev/` shadows the skeleton). Patch 1 needs no
+markdown edits in either tree.
 
 ## Files to Change
 
-- `packages/codev/src/agent-farm/commands/spawn-roles.ts` — Patch 1 (done).
-- `packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts` — Patch 1 tests (done) + no new code path for Patch 2.
-- `{codev-skeleton,codev}/protocols/spir/prompts/plan.md` — drop redundant template pointer.
-- `{codev-skeleton,codev}/protocols/aspir/prompts/plan.md` — drop redundant template pointer.
-- `{codev-skeleton,codev}/protocols/experiment/protocol.md` — embed `notes.md`, reword `cp`.
-- `{codev-skeleton,codev}/protocols/spike/protocol.md` — embed `findings.md`, reword.
-- `{codev-skeleton,codev}/protocols/spir/protocol.md` — strip workflow-reference line (A.3).
-- `packages/codev/src/.../__tests__/` — new content-guard test (see Test Plan).
+- `packages/codev/src/agent-farm/commands/spawn-roles.ts` (+ `__tests__/spawn-roles.test.ts`) — Patch 1 (done).
+- `{codev-skeleton,codev}/protocols/{spir,aspir}/prompts/plan.md` — drop redundant template pointer (Patch 2 + Layer 2).
+- `{codev-skeleton,codev}/protocols/{experiment,spike}/protocol.md` — embed template, reword (Patch 2).
+- `{codev-skeleton,codev}/protocols/*/builder-prompt.md` (all 9) — drop protocol.md pointer (Layer 2).
+- `{codev-skeleton,codev}/roles/builder.md` — fix the cat example (Layer 2).
+- `{codev-skeleton,codev}/protocols/spir/protocol.md` — strip A.3 line (Layer 2).
+- `AGENTS.md`, `CLAUDE.md` — convention section (Layer 3).
+- `packages/codev/src/commands/doctor.ts` (+ `src/__tests__/doctor.test.ts`) — audit check (Layer 3).
+- (If sub-decision (i)) `codev-skeleton/protocols/bugfix/protocol.md` — new, copied from `codev/`.
 
 ## Risks & Alternatives Considered
 
-- **Risk: embedded template drifts from canonical `templates/*.md`.** Mitigation: a unit test
-  asserts the embedded block (between the `BEGIN/END EMBEDDED TEMPLATE` sentinels) byte-matches
-  the canonical template file. Drift fails CI. Applies to `notes.md` and `findings.md`.
-- **Alternative: A.2 = auto-detect (Option A).** Rejected — would double-deliver a conflicting
-  plan layout for spir/aspir (see finding) and needs traversal in two channels (porch
-  `loadPromptFile` + spawn inline). B is simpler, correct, and human-discriminating.
-- **Risk: residual single failed `cat`.** With Patch 1 leaving the builder-prompt's "read
-  protocol.md" instruction intact (per the rejected-alternative "drop the instructions" —
-  ruled out for per-protocol audit cost), an eager builder *could* still `cat` once before
-  noticing the inlined copy. Accepted: the content's presence prevents the multi-minute *hunt*
-  (the actual symptom); the clear `## Protocol Reference` delimiter (decision #1) mitigates
-  "louder than the per-phase prompt" confusion. Flagged for the dev-approval check.
-- **Observed but out of scope:** additional *relative-path* template refs inside protocol.md
-  (`spir/protocol.md:215` `templates/spec.md`, `:301` `templates/plan.md`,
-  `experiment/protocol.md:90` `templates/notes.md`). Relative + informational; not in the
-  architect's enumerated A.2 set. Left as-is unless you want them folded in.
+- **Drift:** embedded `notes.md`/`findings.md` vs canonical. Mitigation: unit test asserts the
+  `BEGIN/END EMBEDDED TEMPLATE` block byte-matches the canonical file. Drift fails CI.
+- **Doctor false positives:** scoping the grep to absolute `codev/…` paths (decision 5) keeps it
+  aligned with the sweep; relative refs intentionally not matched.
+- **Auto-detect (Patch 2 = A):** rejected — double-delivers a conflicting plan layout (finding #1).
+- **`codev read` CLI / restore copying / per-`next` injection:** rejected per the issue's table.
+- **Residual cat:** eliminated for protocol.md — Layer 2 removes the pointer outright (the earlier
+  "leave the instruction" stance is reversed by Layer 2).
 
 ## Test Plan
 
-**Automated (in `npm test` → `@cluesmith/codev`):**
-- Patch 1 (exist): protocol.md inlined under the delimiter; omitted without error when absent.
-- A.2 content guard (new): load `spir/prompts/plan.md` + `aspir/prompts/plan.md` from the
-  skeleton; assert the dead template-path pointer is **absent** and the self-contained
-  `### Plan Structure` is **present**. Load `experiment/protocol.md` + `spike/protocol.md`;
-  assert the embedded template block is present **and byte-matches** the canonical
-  `templates/notes.md` / `templates/findings.md` (drift guard).
-- A.3 guard (new): assert `spir/protocol.md` no longer references `workflow-reference.md`.
+**Automated (`npm test` → `@cluesmith/codev`):**
+- Patch 1 (exist): protocol.md inlined under delimiter; omitted-without-error when absent.
+- A.2 guard (new): `spir`/`aspir` `plan.md` no longer reference the template path and still carry
+  `### Plan Structure`; `experiment`/`spike` `protocol.md` embed-block byte-matches the canonical
+  template (drift guard).
+- Layer 2 guard (new): no `builder-prompt.md` references `protocol.md`; `roles/builder.md` has no
+  `cat codev/protocols/…`; `spir/protocol.md` has no `workflow-reference.md`.
+- Layer 3 doctor (new, in `doctor.test.ts`): clean skeleton → check `ok`; a fixture with a
+  deliberate literal path → check `warn` (negative test).
 
 **Build:** `npm run build` from worktree root.
 
-**Manual (dev-approval, load-bearing — repro from issue):** fresh `codev init` in a tmp dir,
-spawn a test PIR builder, run through plan + implement; confirm (a) no file-hunting for
-protocol.md OR templates, (b) the builder still follows per-phase prompts (inlined material
-not "louder"), (c) per-phase templates land in the right phase. PR-diff review can't catch these.
+**Manual (dev-approval, load-bearing — issue repro):** fresh `codev init` in a tmp dir, spawn a
+test builder, run plan + implement + review; confirm (a) no file-hunting for protocol.md OR
+templates, (b) per-phase prompts still followed (inlined material not "louder"), (c) templates
+land in the right phase, (d) `codev doctor` catches a deliberately-introduced literal-path ref.

From c0350a79110fd1edb293cde5c95ad93633ec6da1 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 13:50:30 +1000
Subject: [PATCH 11/14] [PIR #1011] Resolve bugfix sub-decision (drop pointer);
 file doc hygiene as #1013

---
 .../1011-agent-farm-inline-protocol-md-.md    | 39 ++++++++++++-------
 codev/state/pir-1011_thread.md                |  6 +++
 2 files changed, 32 insertions(+), 13 deletions(-)

diff --git a/codev/plans/1011-agent-farm-inline-protocol-md-.md b/codev/plans/1011-agent-farm-inline-protocol-md-.md
index 14e07f30a..8a2d0b27e 100644
--- a/codev/plans/1011-agent-farm-inline-protocol-md-.md
+++ b/codev/plans/1011-agent-farm-inline-protocol-md-.md
@@ -72,18 +72,29 @@ Layer 2's sweep so a post-sweep skeleton is clean. Relative-path refs (`template
 `spir/protocol.md:215/301`, `experiment/protocol.md:90`) are a lower-severity class **not**
 targeted (kept out of both the sweep and the grep) — noted as observed-out-of-scope.
 
-## Open sub-decision (needs your call — finding #2)
-
-`bugfix` is the one protocol whose meta-doc isn't in the skeleton. Options:
-- **(i) Ship `bugfix/protocol.md` into the skeleton** (copy the existing 548-line `codev/` doc).
-  Makes Layer 1 cover bugfix uniformly; Layer 2 sweep then safe. *Recommended* — every other
-  protocol ships its `protocol.md`; the absence reads as an oversight. Cost: +548 lines in the
-  published skeleton.
-- **(ii) Treat bugfix as intentionally meta-doc-less**: drop the pointer (Layer 2), inline nothing,
-  rely on `builder-prompt.md` + phase prompts being self-contained. Cost: bugfix builders lose the
-  548-line protocol context that our own instance has.
-- **(iii) Split to a separate skeleton-completeness issue**; here, just don't regress bugfix.
-I'll default to **(i)** unless you say otherwise.
+## bugfix sub-decision — RESOLVED: drop the dead pointer, embed nothing (finding #2)
+
+`bugfix` is the one protocol whose `protocol.md` isn't in the skeleton (`codev/` has a tracked
+548-line copy that was never shipped). Layer 2 drops its `builder-prompt.md:28` pointer like the
+other 8 — and for bugfix that is correct on its own merits, **not** a content loss, because:
+
+- The pointer is a **dead path** in fresh installs regardless (no skeleton `protocol.md`).
+- The builder's actionable guidance is **already delivered** via bugfix's phase prompts
+  (`investigate.md` / `fix.md` / `pr.md`, 264 lines, porch-delivered): grep confirms the
+  300-LOC scope, escalation criteria, mandatory regression test, and `Fixes #N` / PR-body
+  structure are all present there.
+- The content **unique** to `protocol.md` is overwhelmingly *not* builder-actionable —
+  architect-facing phases (spawn / integration-review / cleanup), the ASCII workflow diagram,
+  comparison tables, plus material that's gone **stale** vs porch orchestration (manual
+  `afx send "Merge it"` merge flow, manual architect CMAP, the deprecated projectlist section).
+  Inlining it would add noise, not signal.
+
+So: **no skeleton `bugfix/protocol.md` is added here, and nothing is embedded.** The doc's
+skeleton-absence + staleness is a real but orthogonal content-hygiene gap, filed as **#1013**
+(not absorbed into this plumbing fix). This also makes visible a latent property of Layer 1 —
+protocol docs are mixed-audience (builder + architect) yet Layer 1 inlines the whole doc; for
+the 8 protocols that have one we inline as-is per the architect's design, and bugfix simply has
+nothing to inline.
 
 ## Proposed Change (three layers)
 
@@ -121,7 +132,9 @@ markdown edits in either tree.
 - `{codev-skeleton,codev}/protocols/spir/protocol.md` — strip A.3 line (Layer 2).
 - `AGENTS.md`, `CLAUDE.md` — convention section (Layer 3).
 - `packages/codev/src/commands/doctor.ts` (+ `src/__tests__/doctor.test.ts`) — audit check (Layer 3).
-- (If sub-decision (i)) `codev-skeleton/protocols/bugfix/protocol.md` — new, copied from `codev/`.
+
+(bugfix gets only the Layer 2 pointer-drop — no skeleton `protocol.md` added; see the resolved
+sub-decision above. Doc hygiene tracked in #1013.)
 
 ## Risks & Alternatives Considered
 
diff --git a/codev/state/pir-1011_thread.md b/codev/state/pir-1011_thread.md
index cf2a2a699..513b45461 100644
--- a/codev/state/pir-1011_thread.md
+++ b/codev/state/pir-1011_thread.md
@@ -21,3 +21,9 @@ plan-approval approved. Implemented per plan:
 - `spawn-roles.test.ts`: 2 new tests in the skeleton-fallback block — (1) inlines protocol.md under the delimiter with a sentinel body, (2) builds without error and omits the heading when protocol.md is absent.
 
 Build ✓ (root `npm run build`), full suite ✓ (3260 passed, 13 pre-existing skips — none mine). Committed + pushed. At dev-approval gate.
+
+## Scope expansion (2026-06-08, architect-driven)
+
+Architect expanded #1011 twice: first to a framework-file class fix (A.1/A.2/A.3), then to a three-layer structure (Delivery / Cleanup / Enforcement). Plan rewritten accordingly. 5 plan-gate decisions locked (delimiter; Patch2=B explicit-embed; A.3=strip; missing-file=silent-skip+debug; doctor=warn-not-error skeleton-only). Patch 1 (Layer 1/A.1) already done + at dev-approval; Patch 2 + Layer 2 sweep + Layer 3 (doctor check + AGENTS/CLAUDE convention) still to implement.
+
+bugfix sub-decision RESOLVED → drop its dead pointer, embed nothing. Evidence: bugfix builder-relevant guidance (300-LOC/escalation/regression/Fixes#) already in its phase prompts (investigate/fix/pr); the 548-line codev/ protocol.md is mostly architect-facing + partly stale (manual merge flow, deprecated projectlist) and absent from the skeleton. That doc-hygiene gap filed separately as **#1013** (area/protocols), kept out of #1011's plumbing scope.

From 282bca0f4db9ef79daa68f4082cd58ce852fcd0f Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 14:10:46 +1000
Subject: [PATCH 12/14] [PIR #1011] Layer 2 sweep + Patch 2 embeds + Layer 3
 (convention + doctor audit)

- Layer 2: drop protocol.md pointer from all 9 builder-prompts; fix roles/builder.md
  cat example; strip A.3 workflow-reference line from spir/protocol.md (both trees)
- Patch 2 (A.2): drop redundant plan-template pointers (spir/aspir); embed notes.md /
  findings.md into experiment/spike protocol.md under drift-guarded sentinels (both trees)
- Layer 3: 'Framework files: never shell-fetch by literal path' convention in
  AGENTS.md + CLAUDE.md; lib/framework-ref-audit.ts + doctor() section (warn, skeleton-only)
- Tests: new framework-ref-audit + skeleton-sweep guards; update Spec 746 baselines and
  bugfix-619 assertion for the swept builder-prompts
---
 AGENTS.md                                     |  10 ++
 CLAUDE.md                                     |  10 ++
 .../protocols/air/builder-prompt.md           |   2 +-
 .../protocols/aspir/builder-prompt.md         |   3 +-
 .../protocols/aspir/prompts/plan.md           |   1 -
 .../protocols/bugfix/builder-prompt.md        |   2 +-
 .../protocols/experiment/builder-prompt.md    |   2 +-
 .../protocols/experiment/protocol.md          | 106 +++++++++++++++-
 .../protocols/maintain/builder-prompt.md      |   2 +-
 .../protocols/pir/builder-prompt.md           |   5 +-
 .../protocols/research/builder-prompt.md      |   2 +-
 .../protocols/spike/builder-prompt.md         |   2 +-
 codev-skeleton/protocols/spike/protocol.md    |  76 +++++++++++-
 .../protocols/spir/builder-prompt.md          |   3 +-
 codev-skeleton/protocols/spir/prompts/plan.md |   1 -
 codev-skeleton/protocols/spir/protocol.md     |   1 -
 codev-skeleton/roles/builder.md               |   4 +-
 codev/protocols/air/builder-prompt.md         |   2 +-
 codev/protocols/aspir/builder-prompt.md       |   3 +-
 codev/protocols/aspir/prompts/plan.md         |   1 -
 codev/protocols/bugfix/builder-prompt.md      |   2 +-
 codev/protocols/experiment/builder-prompt.md  |   2 +-
 codev/protocols/experiment/protocol.md        | 106 +++++++++++++++-
 codev/protocols/maintain/builder-prompt.md    |   2 +-
 codev/protocols/pir/builder-prompt.md         |   5 +-
 codev/protocols/research/builder-prompt.md    |   2 +-
 codev/protocols/spike/builder-prompt.md       |   2 +-
 codev/protocols/spike/protocol.md             |  76 +++++++++++-
 codev/protocols/spir/builder-prompt.md        |   3 +-
 codev/protocols/spir/prompts/plan.md          |   1 -
 codev/protocols/spir/protocol.md              |   1 -
 codev/roles/builder.md                        |   4 +-
 codev/state/pir-1011_thread.md                |  12 ++
 .../src/__tests__/framework-ref-audit.test.ts | 113 ++++++++++++++++++
 .../__tests__/bugfix-619-aspir-prompt.test.ts |  10 +-
 .../baselines/air-builder-prompt.md.baseline  |   2 +-
 .../aspir-builder-prompt.md.baseline          |   3 +-
 .../baselines/spir-builder-prompt.md.baseline |   3 +-
 packages/codev/src/commands/doctor.ts         |  27 +++++
 packages/codev/src/lib/framework-ref-audit.ts |  76 ++++++++++++
 40 files changed, 643 insertions(+), 47 deletions(-)
 create mode 100644 packages/codev/src/__tests__/framework-ref-audit.test.ts
 create mode 100644 packages/codev/src/lib/framework-ref-audit.ts

diff --git a/AGENTS.md b/AGENTS.md
index b7b8bda03..d5ca94599 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,6 +88,16 @@ 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: never shell-fetch them by literal path
+
+Framework files (protocol docs, role docs, and the framework resources under `codev/resources/` such as `workflow-reference.md`, `risk-triage.md`, and `commands/`) ship in the package skeleton and resolve through the four-tier lookup above. They are **not guaranteed to exist on disk** in a user project, so:
+
+- **Never instruct a shell read of a framework file by literal path** — no `cat codev/protocols/<x>/protocol.md`, no `cp codev/protocols/<x>/templates/<f>`. Shell commands bypass the resolver and fail in fresh installs. Builders receive framework content through resolver-backed channels instead: `protocol.md` is inlined into the spawn prompt, and per-phase prompts plus their templates arrive via porch (`porch next`) or embedded directly in the prompt.
+- **Documentation may still mention a `codev/...` framework path** for orientation (e.g. the protocol list above) — that is fine; it resolves via the skeleton and stays callable from the CLI. The rule is about *fetching*, not *referencing*.
+- `codev/resources/arch.md` and `codev/resources/lessons-learned.md` are **user-project files** (you read and write them), not framework files — referencing them by path is correct.
+
+`codev doctor` audits the skeleton for shell-fetch violations of this rule.
+
 ### 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:
diff --git a/CLAUDE.md b/CLAUDE.md
index b7b8bda03..d5ca94599 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -88,6 +88,16 @@ 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: never shell-fetch them by literal path
+
+Framework files (protocol docs, role docs, and the framework resources under `codev/resources/` such as `workflow-reference.md`, `risk-triage.md`, and `commands/`) ship in the package skeleton and resolve through the four-tier lookup above. They are **not guaranteed to exist on disk** in a user project, so:
+
+- **Never instruct a shell read of a framework file by literal path** — no `cat codev/protocols/<x>/protocol.md`, no `cp codev/protocols/<x>/templates/<f>`. Shell commands bypass the resolver and fail in fresh installs. Builders receive framework content through resolver-backed channels instead: `protocol.md` is inlined into the spawn prompt, and per-phase prompts plus their templates arrive via porch (`porch next`) or embedded directly in the prompt.
+- **Documentation may still mention a `codev/...` framework path** for orientation (e.g. the protocol list above) — that is fine; it resolves via the skeleton and stays callable from the CLI. The rule is about *fetching*, not *referencing*.
+- `codev/resources/arch.md` and `codev/resources/lessons-learned.md` are **user-project files** (you read and write them), not framework files — referencing them by path is correct.
+
+`codev doctor` audits the skeleton for shell-fetch violations of this rule.
+
 ### 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:
diff --git a/codev-skeleton/protocols/air/builder-prompt.md b/codev-skeleton/protocols/air/builder-prompt.md
index 963d5e5fe..ed71fa32c 100644
--- a/codev-skeleton/protocols/air/builder-prompt.md
+++ b/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.
 
 ## Baked Decisions
 
diff --git a/codev-skeleton/protocols/aspir/builder-prompt.md b/codev-skeleton/protocols/aspir/builder-prompt.md
index 4af70ce4f..52adeb2ae 100644
--- a/codev-skeleton/protocols/aspir/builder-prompt.md
+++ b/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.
 
 ## Baked Decisions
 
diff --git a/codev-skeleton/protocols/aspir/prompts/plan.md b/codev-skeleton/protocols/aspir/prompts/plan.md
index 3549654c5..c20cbd1dc 100644
--- a/codev-skeleton/protocols/aspir/prompts/plan.md
+++ b/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
 
diff --git a/codev-skeleton/protocols/bugfix/builder-prompt.md b/codev-skeleton/protocols/bugfix/builder-prompt.md
index 3f56828bb..8d140e037 100644
--- a/codev-skeleton/protocols/bugfix/builder-prompt.md
+++ b/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.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
diff --git a/codev-skeleton/protocols/experiment/builder-prompt.md b/codev-skeleton/protocols/experiment/builder-prompt.md
index 23f378975..c9c9a5453 100644
--- a/codev-skeleton/protocols/experiment/builder-prompt.md
+++ b/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.
 
 ## EXPERIMENT Overview
 The EXPERIMENT protocol ensures disciplined experimentation:
diff --git a/codev-skeleton/protocols/experiment/protocol.md b/codev-skeleton/protocols/experiment/protocol.md
index 5dd71b271..acb820d75 100644
--- a/codev-skeleton/protocols/experiment/protocol.md
+++ b/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   # populate from the "## Template: notes.md" section at the end of this protocol
 ```
 
 Or ask your AI assistant: "Create a new experiment for [goal]"
@@ -222,3 +222,107 @@ Determine if Redis caching improves API response times for repeated queries.
 ## Next Steps
 Create SPIR spec for production caching implementation.
 ```
+
+## Template: notes.md
+
+> Embedded copy of the notes.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+
+<!-- BEGIN EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
+# Experiment ####: Name
+
+**Status**: In Progress | Complete | Disproved | Aborted
+
+**Date**: YYYY-MM-DD
+
+## Goal
+
+What are you trying to learn or test? Be specific about:
+- The question you're answering
+- The hypothesis you're testing
+- Success criteria (how will you know if it worked?)
+
+## Effort
+
+**Approximate time spent**: [e.g., "4 hours"]
+
+*(Optional: Break down into setup, coding, analysis if helpful)*
+
+## Approach
+
+Brief description of the approach being tested:
+- Key technique or method
+- Why this approach was chosen
+- Any alternatives considered
+
+## Environment & Reproduction
+
+**How to run**:
+```bash
+# Command to reproduce results
+python experiment.py --input data/input/sample.json
+```
+
+**Dependencies** (if different from main project):
+- List any additional packages required
+- Or reference: `pip install -r requirements.txt`
+
+**Environment notes**:
+- Python version, key library versions if relevant
+- Any seeds or configuration needed for reproducibility
+
+## Code
+
+List your experiment files:
+- [`experiment.py`](experiment.py) - Brief description
+- [Other files as needed]
+
+## Results
+
+### Summary
+
+One-paragraph summary of key findings.
+
+### Key Findings
+
+1. **Finding one**: Description and significance
+2. **Finding two**: Description and significance
+3. **Finding three**: Description and significance
+
+### Metrics
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Metric 1 | Value | Context |
+| Metric 2 | Value | Context |
+
+### Output Files
+
+- `data/output/results.csv` - Raw results data
+- `data/output/chart.png` - Visualization of findings
+
+## What Worked
+
+- List things that went well
+- Approaches that proved effective
+- Useful discoveries
+
+## What Didn't Work
+
+- Failed approaches (and why)
+- Dead ends encountered
+- Surprising obstacles
+
+## Next Steps
+
+Based on these findings:
+
+1. **Immediate**: What should happen right after this experiment?
+2. **Follow-up experiments**: What new questions emerged?
+3. **Production path**: If validated, what's needed for production? (SPIR spec?)
+
+## References
+
+- Links to relevant documentation
+- Related experiments
+- External resources consulted
+<!-- END EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
diff --git a/codev-skeleton/protocols/maintain/builder-prompt.md b/codev-skeleton/protocols/maintain/builder-prompt.md
index 72394e849..03d2589ff 100644
--- a/codev-skeleton/protocols/maintain/builder-prompt.md
+++ b/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.
 
 ## MAINTAIN Overview
 
diff --git a/codev-skeleton/protocols/pir/builder-prompt.md b/codev-skeleton/protocols/pir/builder-prompt.md
index 0edd1d992..c75dea8de 100644
--- a/codev-skeleton/protocols/pir/builder-prompt.md
+++ b/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.
 
 PIR has three phases:
 1. **plan** (gated by `plan-approval`) — write `codev/plans/{{artifact_name}}.md`, await human review
@@ -87,6 +86,6 @@ 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
diff --git a/codev-skeleton/protocols/research/builder-prompt.md b/codev-skeleton/protocols/research/builder-prompt.md
index ae501326e..ee13cbc69 100644
--- a/codev-skeleton/protocols/research/builder-prompt.md
+++ b/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.
 
 ## RESEARCH Overview
 
diff --git a/codev-skeleton/protocols/spike/builder-prompt.md b/codev-skeleton/protocols/spike/builder-prompt.md
index 8d8a97dfb..dec10de9b 100644
--- a/codev-skeleton/protocols/spike/builder-prompt.md
+++ b/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.
 
 {{#if task}}
 ## Spike Question
diff --git a/codev-skeleton/protocols/spike/protocol.md b/codev-skeleton/protocols/spike/protocol.md
index b8c1ec0f6..a0be3c6af 100644
--- a/codev-skeleton/protocols/spike/protocol.md
+++ b/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 in the "## Template: findings.md" section at the end of this protocol
 - Provide a clear feasibility verdict
 - Commit and notify the architect
 
@@ -120,3 +120,77 @@ 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
+
+> Embedded copy of the findings.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+
+<!-- BEGIN EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
+# Spike: [Title]
+
+**Date**: YYYY-MM-DD
+
+**Verdict**: Feasible | Not Feasible | Feasible with Caveats
+
+## Question
+
+What technical question was being investigated? Be specific:
+- What are you trying to determine?
+- What prompted this investigation?
+- What decision depends on the answer?
+
+## Research Summary
+
+What was explored during the research phase:
+- Documentation read
+- Existing code examined
+- Prior art found
+- Key constraints identified
+
+## Approaches Tried
+
+What was built or tested during the iterate phase:
+
+### Approach 1: [Name]
+- **What**: Brief description of what was tried
+- **Result**: What happened
+- **Verdict**: Worked / Didn't work / Partially worked
+
+### Approach 2: [Name]
+*(Add more approaches as needed, or remove if research alone answered the question)*
+
+## Constraints Discovered
+
+Technical limitations, dependencies, and gotchas found during the investigation:
+- [Constraint 1]
+- [Constraint 2]
+
+## Recommended Approach
+
+*(If feasible)* How should full implementation proceed?
+- Recommended library/technique/pattern
+- Key architectural decisions
+- Things to watch out for
+
+*(If not feasible)* Why not, and what alternatives exist?
+
+## Effort Estimate
+
+Rough sizing for a full SPIR project: **Small** | **Medium** | **Large**
+
+- Small: < 300 LOC, 1-2 files, straightforward
+- Medium: 300-1000 LOC, multiple files, some complexity
+- Large: 1000+ LOC, architectural changes, significant complexity
+
+## Next Steps
+
+- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"]
+- [ ] [Or: "Do not pursue — blocked by X"]
+- [ ] [Or: "Investigate Y further before deciding"]
+
+## References
+
+- [Link to relevant documentation]
+- [Link to relevant code/commits]
+- [Link to external resources consulted]
+<!-- END EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
diff --git a/codev-skeleton/protocols/spir/builder-prompt.md b/codev-skeleton/protocols/spir/builder-prompt.md
index 149c531e5..7c69272af 100644
--- a/codev-skeleton/protocols/spir/builder-prompt.md
+++ b/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.
 
 ## Baked Decisions
 
diff --git a/codev-skeleton/protocols/spir/prompts/plan.md b/codev-skeleton/protocols/spir/prompts/plan.md
index 3549654c5..c20cbd1dc 100644
--- a/codev-skeleton/protocols/spir/prompts/plan.md
+++ b/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
 
diff --git a/codev-skeleton/protocols/spir/protocol.md b/codev-skeleton/protocols/spir/protocol.md
index 188c2bda1..c531ef5e8 100644
--- a/codev-skeleton/protocols/spir/protocol.md
+++ b/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
 
diff --git a/codev-skeleton/roles/builder.md b/codev-skeleton/roles/builder.md
index aa01346ec..4f49ded80 100644
--- a/codev-skeleton/roles/builder.md
+++ b/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
 ```
diff --git a/codev/protocols/air/builder-prompt.md b/codev/protocols/air/builder-prompt.md
index 963d5e5fe..ed71fa32c 100644
--- a/codev/protocols/air/builder-prompt.md
+++ b/codev/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.
 
 ## Baked Decisions
 
diff --git a/codev/protocols/aspir/builder-prompt.md b/codev/protocols/aspir/builder-prompt.md
index 475721098..1e912b1f0 100644
--- a/codev/protocols/aspir/builder-prompt.md
+++ b/codev/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.
 
 ## Baked Decisions
 
diff --git a/codev/protocols/aspir/prompts/plan.md b/codev/protocols/aspir/prompts/plan.md
index 3549654c5..c20cbd1dc 100644
--- a/codev/protocols/aspir/prompts/plan.md
+++ b/codev/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
 
diff --git a/codev/protocols/bugfix/builder-prompt.md b/codev/protocols/bugfix/builder-prompt.md
index ef6834110..0f0f59ef2 100644
--- a/codev/protocols/bugfix/builder-prompt.md
+++ b/codev/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.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
diff --git a/codev/protocols/experiment/builder-prompt.md b/codev/protocols/experiment/builder-prompt.md
index 23f378975..c9c9a5453 100644
--- a/codev/protocols/experiment/builder-prompt.md
+++ b/codev/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.
 
 ## EXPERIMENT Overview
 The EXPERIMENT protocol ensures disciplined experimentation:
diff --git a/codev/protocols/experiment/protocol.md b/codev/protocols/experiment/protocol.md
index 7bac432a5..3f3c1c66c 100644
--- a/codev/protocols/experiment/protocol.md
+++ b/codev/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   # populate from the "## Template: notes.md" section at the end of this protocol
 ```
 
 Or ask your AI assistant: "Create a new experiment for [goal]"
@@ -227,3 +227,107 @@ Determine if Redis caching improves API response times for repeated queries.
 ## Next Steps
 Create SPIR spec for production caching implementation.
 ```
+
+## Template: notes.md
+
+> Embedded copy of the notes.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+
+<!-- BEGIN EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
+# Experiment ####: Name
+
+**Status**: In Progress | Complete | Disproved | Aborted
+
+**Date**: YYYY-MM-DD
+
+## Goal
+
+What are you trying to learn or test? Be specific about:
+- The question you're answering
+- The hypothesis you're testing
+- Success criteria (how will you know if it worked?)
+
+## Effort
+
+**Approximate time spent**: [e.g., "4 hours"]
+
+*(Optional: Break down into setup, coding, analysis if helpful)*
+
+## Approach
+
+Brief description of the approach being tested:
+- Key technique or method
+- Why this approach was chosen
+- Any alternatives considered
+
+## Environment & Reproduction
+
+**How to run**:
+```bash
+# Command to reproduce results
+python experiment.py --input data/input/sample.json
+```
+
+**Dependencies** (if different from main project):
+- List any additional packages required
+- Or reference: `pip install -r requirements.txt`
+
+**Environment notes**:
+- Python version, key library versions if relevant
+- Any seeds or configuration needed for reproducibility
+
+## Code
+
+List your experiment files:
+- [`experiment.py`](experiment.py) - Brief description
+- [Other files as needed]
+
+## Results
+
+### Summary
+
+One-paragraph summary of key findings.
+
+### Key Findings
+
+1. **Finding one**: Description and significance
+2. **Finding two**: Description and significance
+3. **Finding three**: Description and significance
+
+### Metrics
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Metric 1 | Value | Context |
+| Metric 2 | Value | Context |
+
+### Output Files
+
+- `data/output/results.csv` - Raw results data
+- `data/output/chart.png` - Visualization of findings
+
+## What Worked
+
+- List things that went well
+- Approaches that proved effective
+- Useful discoveries
+
+## What Didn't Work
+
+- Failed approaches (and why)
+- Dead ends encountered
+- Surprising obstacles
+
+## Next Steps
+
+Based on these findings:
+
+1. **Immediate**: What should happen right after this experiment?
+2. **Follow-up experiments**: What new questions emerged?
+3. **Production path**: If validated, what's needed for production? (SPIR spec?)
+
+## References
+
+- Links to relevant documentation
+- Related experiments
+- External resources consulted
+<!-- END EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
diff --git a/codev/protocols/maintain/builder-prompt.md b/codev/protocols/maintain/builder-prompt.md
index 72394e849..03d2589ff 100644
--- a/codev/protocols/maintain/builder-prompt.md
+++ b/codev/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.
 
 ## MAINTAIN Overview
 
diff --git a/codev/protocols/pir/builder-prompt.md b/codev/protocols/pir/builder-prompt.md
index 0edd1d992..c75dea8de 100644
--- a/codev/protocols/pir/builder-prompt.md
+++ b/codev/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.
 
 PIR has three phases:
 1. **plan** (gated by `plan-approval`) — write `codev/plans/{{artifact_name}}.md`, await human review
@@ -87,6 +86,6 @@ 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
diff --git a/codev/protocols/research/builder-prompt.md b/codev/protocols/research/builder-prompt.md
index ae501326e..ee13cbc69 100644
--- a/codev/protocols/research/builder-prompt.md
+++ b/codev/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.
 
 ## RESEARCH Overview
 
diff --git a/codev/protocols/spike/builder-prompt.md b/codev/protocols/spike/builder-prompt.md
index 8d8a97dfb..dec10de9b 100644
--- a/codev/protocols/spike/builder-prompt.md
+++ b/codev/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.
 
 {{#if task}}
 ## Spike Question
diff --git a/codev/protocols/spike/protocol.md b/codev/protocols/spike/protocol.md
index e874252df..b3b4b55b2 100644
--- a/codev/protocols/spike/protocol.md
+++ b/codev/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 in the "## Template: findings.md" section at the end of this protocol
 - Provide a clear feasibility verdict
 - Commit and notify the architect
 
@@ -120,3 +120,77 @@ 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
+
+> Embedded copy of the findings.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+
+<!-- BEGIN EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
+# Spike: [Title]
+
+**Date**: YYYY-MM-DD
+
+**Verdict**: Feasible | Not Feasible | Feasible with Caveats
+
+## Question
+
+What technical question was being investigated? Be specific:
+- What are you trying to determine?
+- What prompted this investigation?
+- What decision depends on the answer?
+
+## Research Summary
+
+What was explored during the research phase:
+- Documentation read
+- Existing code examined
+- Prior art found
+- Key constraints identified
+
+## Approaches Tried
+
+What was built or tested during the iterate phase:
+
+### Approach 1: [Name]
+- **What**: Brief description of what was tried
+- **Result**: What happened
+- **Verdict**: Worked / Didn't work / Partially worked
+
+### Approach 2: [Name]
+*(Add more approaches as needed, or remove if research alone answered the question)*
+
+## Constraints Discovered
+
+Technical limitations, dependencies, and gotchas found during the investigation:
+- [Constraint 1]
+- [Constraint 2]
+
+## Recommended Approach
+
+*(If feasible)* How should full implementation proceed?
+- Recommended library/technique/pattern
+- Key architectural decisions
+- Things to watch out for
+
+*(If not feasible)* Why not, and what alternatives exist?
+
+## Effort Estimate
+
+Rough sizing for a full SPIR project: **Small** | **Medium** | **Large**
+
+- Small: < 300 LOC, 1-2 files, straightforward
+- Medium: 300-1000 LOC, multiple files, some complexity
+- Large: 1000+ LOC, architectural changes, significant complexity
+
+## Next Steps
+
+- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"]
+- [ ] [Or: "Do not pursue — blocked by X"]
+- [ ] [Or: "Investigate Y further before deciding"]
+
+## References
+
+- [Link to relevant documentation]
+- [Link to relevant code/commits]
+- [Link to external resources consulted]
+<!-- END EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
diff --git a/codev/protocols/spir/builder-prompt.md b/codev/protocols/spir/builder-prompt.md
index 0c1a6647d..d176663a2 100644
--- a/codev/protocols/spir/builder-prompt.md
+++ b/codev/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.
 
 ## Baked Decisions
 
diff --git a/codev/protocols/spir/prompts/plan.md b/codev/protocols/spir/prompts/plan.md
index 3549654c5..c20cbd1dc 100644
--- a/codev/protocols/spir/prompts/plan.md
+++ b/codev/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
 
diff --git a/codev/protocols/spir/protocol.md b/codev/protocols/spir/protocol.md
index 9cf392379..73e34d4e1 100644
--- a/codev/protocols/spir/protocol.md
+++ b/codev/protocols/spir/protocol.md
@@ -1,6 +1,5 @@
 # SPIR Protocol
 
-> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
 
 ## Prerequisites
 
diff --git a/codev/roles/builder.md b/codev/roles/builder.md
index aa01346ec..4f49ded80 100644
--- a/codev/roles/builder.md
+++ b/codev/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
 ```
diff --git a/codev/state/pir-1011_thread.md b/codev/state/pir-1011_thread.md
index 513b45461..0e61b9a67 100644
--- a/codev/state/pir-1011_thread.md
+++ b/codev/state/pir-1011_thread.md
@@ -27,3 +27,15 @@ Build ✓ (root `npm run build`), full suite ✓ (3260 passed, 13 pre-existing s
 Architect expanded #1011 twice: first to a framework-file class fix (A.1/A.2/A.3), then to a three-layer structure (Delivery / Cleanup / Enforcement). Plan rewritten accordingly. 5 plan-gate decisions locked (delimiter; Patch2=B explicit-embed; A.3=strip; missing-file=silent-skip+debug; doctor=warn-not-error skeleton-only). Patch 1 (Layer 1/A.1) already done + at dev-approval; Patch 2 + Layer 2 sweep + Layer 3 (doctor check + AGENTS/CLAUDE convention) still to implement.
 
 bugfix sub-decision RESOLVED → drop its dead pointer, embed nothing. Evidence: bugfix builder-relevant guidance (300-LOC/escalation/regression/Fixes#) already in its phase prompts (investigate/fix/pr); the 548-line codev/ protocol.md is mostly architect-facing + partly stale (manual merge flow, deprecated projectlist) and absent from the skeleton. That doc-hygiene gap filed separately as **#1013** (area/protocols), kept out of #1011's plumbing scope.
+
+## Three-layer implementation complete (2026-06-08)
+
+- **Layer 1**: Patch 1 (protocol.md inline at spawn) already done. Patch 2 (A.2) = explicit-embed: dropped redundant template pointers in spir/aspir plan prompts; embedded notes.md/findings.md into experiment/spike protocol.md under `## Template:` + `BEGIN/END EMBEDDED TEMPLATE` sentinels (drift-guarded).
+- **Layer 2**: swept the protocol.md pointer from all 9 builder-prompts (path-free `Follow the X protocol.`), fixed roles/builder.md cat example, stripped A.3 workflow-reference line from spir/protocol.md. Both trees.
+- **Layer 3**: added the "Framework files: never shell-fetch by literal path" convention to root AGENTS.md + CLAUDE.md; added `lib/framework-ref-audit.ts` + a `doctor()` section (warn-not-error, skeleton-only).
+
+**Key finding that reshaped Layer 3**: the skeleton has ~60 legitimate `codev/...` mentions (user files arch.md/lessons-learned.md; the documented protocol list in CLAUDE/AGENTS templates; cross-refs). A blanket grep would be a noise cannon and contradict documented convention. So the doctor check is deliberately NARROW: only shell-fetch verbs (cat/cp/...) reading `codev/(protocols|roles)/...`. resources/ excluded (mixed framework+user). Documented this scope in the lib + convention. **Flag for architect: the doctor check guards the shell-fetch regression specifically, not the backtick-instruction form (which can't be flagged without false-positiving the legit protocol list).**
+
+Also found + left out-of-scope: `codev/protocols/release/protocol.md:43` cats maintain/protocol.md (architect-run, codev/-only, not in skeleton). And relative-path template refs inside protocol.md (spir:215/301, experiment:90) — relative, informational.
+
+Two pre-existing tests updated (legit staleness from the sweep): baked-decisions.test.ts baselines (3 fixtures swept to match) + bugfix-619 assertion (now asserts no protocol.md path at all, preserving #619 intent). Build ✓, full suite ✓ (3270 passed, 13 pre-existing skips). Still at dev-approval gate.
diff --git a/packages/codev/src/__tests__/framework-ref-audit.test.ts b/packages/codev/src/__tests__/framework-ref-audit.test.ts
new file mode 100644
index 000000000..7f16fd941
--- /dev/null
+++ b/packages/codev/src/__tests__/framework-ref-audit.test.ts
@@ -0,0 +1,113 @@
+/**
+ * Tests for issue #1011 — framework-file delivery via resolver-aware channels.
+ *
+ * Two concerns:
+ *  1. The `auditFrameworkRefs` lib (Layer 3 regression guard) flags shell-fetch
+ *     violations and ignores legitimate references.
+ *  2. The skeleton sweep + template embeds (Layers 1/2 / Patch 2) actually
+ *     landed: builder-prompts no longer point at protocol.md, the cat example
+ *     and workflow-reference pointer are gone, the redundant plan-template
+ *     pointers are dropped, and the embedded templates byte-match canonical.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve, join } from 'node:path';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { auditFrameworkRefs } from '../lib/framework-ref-audit.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// src/__tests__ → repo root is four levels up.
+const REPO_ROOT = resolve(__dirname, '../../../..');
+const SKELETON = join(REPO_ROOT, 'codev-skeleton');
+
+describe('auditFrameworkRefs (issue #1011 Layer 3)', () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'fw-ref-audit-'));
+    mkdirSync(join(dir, 'protocols', 'demo'), { recursive: true });
+    mkdirSync(join(dir, 'roles'), { recursive: true });
+    mkdirSync(join(dir, 'resources'), { recursive: true });
+  });
+
+  it('flags a shell cat of a framework file by literal path', () => {
+    writeFileSync(join(dir, 'protocols', 'demo', 'protocol.md'),
+      '# Demo\n\ncat codev/protocols/demo/protocol.md\n');
+    const findings = auditFrameworkRefs(dir);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].file).toContain('protocol.md');
+    expect(findings[0].line).toBe(3);
+  });
+
+  it('flags a shell cp of a framework template by literal path', () => {
+    writeFileSync(join(dir, 'protocols', 'demo', 'protocol.md'),
+      'cp codev/protocols/demo/templates/notes.md notes.md\n');
+    expect(auditFrameworkRefs(dir)).toHaveLength(1);
+  });
+
+  it('does NOT flag documentation references or user-file paths', () => {
+    writeFileSync(join(dir, 'protocols', 'demo', 'protocol.md'),
+      [
+        'See `codev/protocols/demo/protocol.md` for details.',          // backtick doc ref
+        'Update `codev/resources/arch.md` after the change.',           // user file
+        'git add codev/resources/lessons-learned.md',                   // user file write
+        'Follow the DEMO protocol.',                                    // swept form
+      ].join('\n') + '\n');
+    expect(auditFrameworkRefs(dir)).toHaveLength(0);
+  });
+
+  it('does NOT scan codev/resources (mixed framework + user files)', () => {
+    writeFileSync(join(dir, 'resources', 'guide.md'),
+      'cat codev/resources/workflow-reference.md\n');
+    expect(auditFrameworkRefs(dir)).toHaveLength(0);
+  });
+
+  it('the real swept skeleton is clean (no shell-fetch violations)', () => {
+    if (!existsSync(SKELETON)) return; // resilient if layout shifts
+    expect(auditFrameworkRefs(SKELETON)).toEqual([]);
+  });
+});
+
+describe('skeleton sweep + embeds (issue #1011 Layers 1/2, Patch 2)', () => {
+  const protocols = ['air', 'aspir', 'bugfix', 'experiment', 'maintain', 'pir', 'research', 'spike', 'spir'];
+
+  it('no builder-prompt.md references protocol.md by path', () => {
+    for (const p of protocols) {
+      const f = join(SKELETON, 'protocols', p, 'builder-prompt.md');
+      if (!existsSync(f)) continue;
+      expect(readFileSync(f, 'utf-8')).not.toMatch(/protocol\.md/);
+    }
+  });
+
+  it('roles/builder.md no longer cats the protocol by path', () => {
+    const f = join(SKELETON, 'roles', 'builder.md');
+    expect(readFileSync(f, 'utf-8')).not.toMatch(/cat codev\/protocols\//);
+  });
+
+  it('spir/protocol.md no longer points at workflow-reference.md (A.3)', () => {
+    const f = join(SKELETON, 'protocols', 'spir', 'protocol.md');
+    expect(readFileSync(f, 'utf-8')).not.toMatch(/workflow-reference\.md/);
+  });
+
+  it('spir/aspir plan prompts drop the redundant template pointer but keep Plan Structure', () => {
+    for (const p of ['spir', 'aspir']) {
+      const md = readFileSync(join(SKELETON, 'protocols', p, 'prompts', 'plan.md'), 'utf-8');
+      expect(md).not.toMatch(/codev\/protocols\/spir\/templates\/plan\.md/);
+      expect(md).toContain('### Plan Structure');
+    }
+  });
+
+  it('experiment/spike embed the canonical template verbatim (drift guard)', () => {
+    const cases = [
+      { protocol: 'experiment', tmpl: 'notes.md' },
+      { protocol: 'spike', tmpl: 'findings.md' },
+    ];
+    for (const { protocol, tmpl } of cases) {
+      const md = readFileSync(join(SKELETON, 'protocols', protocol, 'protocol.md'), 'utf-8');
+      const canonical = readFileSync(join(SKELETON, 'protocols', protocol, 'templates', tmpl), 'utf-8');
+      expect(md).toContain('## Template: ' + tmpl);
+      // The full canonical template must be present verbatim — drift fails here.
+      expect(md).toContain(canonical.trimEnd());
+    }
+  });
+});
diff --git a/packages/codev/src/agent-farm/__tests__/bugfix-619-aspir-prompt.test.ts b/packages/codev/src/agent-farm/__tests__/bugfix-619-aspir-prompt.test.ts
index a0e07c221..63fc0cead 100644
--- a/packages/codev/src/agent-farm/__tests__/bugfix-619-aspir-prompt.test.ts
+++ b/packages/codev/src/agent-farm/__tests__/bugfix-619-aspir-prompt.test.ts
@@ -19,10 +19,16 @@ describe('ASPIR builder-prompt protocol reference', () => {
     '../../../../../codev-skeleton/protocols/aspir/builder-prompt.md',
   );
 
-  it('references aspir/protocol.md, not spir/protocol.md', () => {
+  it('does not reference any protocol.md by literal path (#1011 sweep; never spir per #619)', () => {
+    // #619 originally required the ASPIR prompt to reference aspir/protocol.md
+    // rather than spir/protocol.md. #1011 (Layer 2) swept the literal protocol.md
+    // pointer out of every builder-prompt entirely — protocol.md is now inlined
+    // at spawn. So the #619 intent ("never point at spir's protocol.md") is now
+    // satisfied by referencing no protocol.md path at all.
     const content = fs.readFileSync(skeletonPrompt, 'utf-8');
     expect(content).not.toContain('codev/protocols/spir/protocol.md');
-    expect(content).toContain('codev/protocols/aspir/protocol.md');
+    expect(content).not.toContain('codev/protocols/aspir/protocol.md');
+    expect(content).not.toMatch(/protocol\.md/);
   });
 
   it('says "ASPIR protocol", not "SPIR protocol"', () => {
diff --git a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline
index 8a44aede1..a9af8cc21 100644
--- a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline
+++ b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline
@@ -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.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
diff --git a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline
index 2715ed877..4e54e453f 100644
--- a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline
+++ b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline
@@ -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.
 
 {{#if spec}}
 ## Spec
diff --git a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline
index c905b4696..1931e53c1 100644
--- a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline
+++ b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline
@@ -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.
 
 {{#if spec}}
 ## Spec
diff --git a/packages/codev/src/commands/doctor.ts b/packages/codev/src/commands/doctor.ts
index 968d742de..fb8f43b09 100644
--- a/packages/codev/src/commands/doctor.ts
+++ b/packages/codev/src/commands/doctor.ts
@@ -13,6 +13,8 @@ import { query as claudeQuery } from '@anthropic-ai/claude-agent-sdk';
 import { executeForgeCommandSync, loadForgeConfig, validateForgeConfig, resolveAllConcepts, type ConceptResolution } from '../lib/forge.js';
 import { detectHarnessFromCommand } from '../agent-farm/utils/harness.js';
 import { auditPrGates, formatPrGateWarning } from '../lib/pr-gate-audit.js';
+import { auditFrameworkRefs, formatFrameworkRefFinding } from '../lib/framework-ref-audit.js';
+import { getSkeletonDir } from '../lib/skeleton.js';
 import { resolveAgyBin, AGY_OAUTH_MARKERS } from './consult/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -702,6 +704,31 @@ export async function doctor(): Promise<number> {
 
   console.log('');
 
+  // Framework-file reference audit (#1011): the skeleton must not instruct
+  // shell reads of framework docs by literal path — those bypass the resolver
+  // and fail in fresh installs. Warn-not-error; scans the skeleton only.
+  console.log(chalk.bold('Framework File References') + ' (resolver-safe delivery)');
+  console.log('');
+  try {
+    const frameworkRefs = auditFrameworkRefs(getSkeletonDir());
+    if (frameworkRefs.length === 0) {
+      console.log(`  ${chalk.green('✓')} No literal-path shell reads of framework files`);
+    } else {
+      for (const finding of frameworkRefs) {
+        console.log(`  ${chalk.yellow('⚠')} ${formatFrameworkRefFinding(finding)}`);
+        warnings++;
+        warningDetails.push({
+          name: 'Framework refs',
+          issue: formatFrameworkRefFinding(finding),
+          recommendation: 'Deliver framework content via spawn/porch inline; see the "Framework files" convention in CLAUDE.md / AGENTS.md',
+        });
+      }
+    }
+  } catch {
+    console.log(`  ${chalk.dim('○')} skeleton not found — skipped`);
+  }
+  console.log('');
+
   // Check codev directory structure (only if we're in a codev project)
   const workspaceRoot = findWorkspaceRoot();
   if (workspaceRoot && existsSync(resolve(workspaceRoot, 'codev'))) {
diff --git a/packages/codev/src/lib/framework-ref-audit.ts b/packages/codev/src/lib/framework-ref-audit.ts
new file mode 100644
index 000000000..d81983a07
--- /dev/null
+++ b/packages/codev/src/lib/framework-ref-audit.ts
@@ -0,0 +1,76 @@
+/**
+ * Audit the package skeleton for resolver-bypassing shell reads of framework
+ * files by literal path (issue #1011, Layer 3 — regression guard).
+ *
+ * The bug class: a builder-side consumer instructs `cat`/`cp` of a framework
+ * doc by literal `codev/...` path. Shell commands bypass the four-tier resolver
+ * (`resolveCodevFile`), so the read fails in fresh installs where the file
+ * lives only in the embedded skeleton. Framework content is delivered to the
+ * builder via the spawn prompt and porch JSON instead — never fetched by shell.
+ *
+ * Scope is deliberately NARROW to avoid false positives (the skeleton is full
+ * of legitimate `codev/...` mentions):
+ *   - Only shell-fetch verbs (cat/cp/less/more/head/tail/source) reading a
+ *     `codev/protocols/...` or `codev/roles/...` path are flagged.
+ *   - `codev/resources/` is NOT scanned: it mixes framework docs with
+ *     user-evolved files (`arch.md`, `lessons-learned.md`) that builders and
+ *     architects reference and write by path legitimately.
+ *   - Plain documentation references (backtick mentions, "see codev/…") are
+ *     NOT flagged. The rule is about *fetching*, not *referencing* — the
+ *     protocol list in CLAUDE.md/AGENTS.md, for example, is intentional.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export interface FrameworkRefFinding {
+  /** Path relative to the scanned skeleton dir. */
+  file: string;
+  line: number;
+  /** The offending line, trimmed. */
+  text: string;
+}
+
+/** Framework subdirectories whose docs ship in the skeleton and resolve via the resolver. */
+const FRAMEWORK_DIRS = ['protocols', 'roles'] as const;
+
+/**
+ * A shell command that reads/copies a framework file by literal `codev/` path.
+ * Matches e.g. `cat codev/protocols/spir/protocol.md`, `cp codev/roles/builder.md x`.
+ */
+const SHELL_FETCH_RE =
+  /(?:^|[\s|;&(])(?:cat|cp|less|more|head|tail|source)\s+codev\/(?:protocols|roles)\/\S+\.md/;
+
+function collectMarkdown(dir: string, out: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) collectMarkdown(full, out);
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+  }
+}
+
+/**
+ * Scan `<skeletonDir>/{protocols,roles}` for shell-fetch-by-literal-path
+ * violations. Returns one finding per offending line.
+ */
+export function auditFrameworkRefs(skeletonDir: string): FrameworkRefFinding[] {
+  const findings: FrameworkRefFinding[] = [];
+  for (const sub of FRAMEWORK_DIRS) {
+    const base = join(skeletonDir, sub);
+    if (!existsSync(base)) continue;
+    const files: string[] = [];
+    collectMarkdown(base, files);
+    for (const file of files) {
+      const lines = readFileSync(file, 'utf-8').split('\n');
+      lines.forEach((text, i) => {
+        if (SHELL_FETCH_RE.test(text)) {
+          findings.push({ file: relative(skeletonDir, file), line: i + 1, text: text.trim() });
+        }
+      });
+    }
+  }
+  return findings;
+}
+
+export function formatFrameworkRefFinding(f: FrameworkRefFinding): string {
+  return `${f.file}:${f.line} shell-fetches a framework file by literal path: ${f.text}`;
+}

From 4cfa872c81489b3a63159958ae770e06fb7a867e Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 14:36:32 +1000
Subject: [PATCH 13/14] [PIR #1011] Rework delivery: fresh-at-spawn placeholder
 substitution

Per dev-approval feedback, replace the static embed/append (stale duplicate) with
fresh-at-delivery placeholders:
- spawn-roles.ts: resolveIncludes() ({{> path}}, recursive) + resolveProtocolReference();
  buildPromptFromTemplate fills {{protocol_reference}} from protocol.md read fresh at spawn
- builder-prompts: restore 'Read and internalize...'; reference + {{protocol_reference}}
  placeholder under {{#if}} (bugfix renders cleanly with neither)
- experiment/spike protocol.md: {{> ...templates...}} include instead of committed copy
- tests: placeholder + include resolution; drift test asserts include-present/no-embed;
  re-sweep Spec 746 baselines to the new ## Protocol line
---
 .../protocols/air/builder-prompt.md           |  10 +-
 .../protocols/aspir/builder-prompt.md         |  10 +-
 .../protocols/bugfix/builder-prompt.md        |  10 +-
 .../protocols/experiment/builder-prompt.md    |  10 +-
 .../protocols/experiment/protocol.md          | 104 +-----------------
 .../protocols/maintain/builder-prompt.md      |  10 +-
 .../protocols/pir/builder-prompt.md           |  10 +-
 .../protocols/research/builder-prompt.md      |  10 +-
 .../protocols/spike/builder-prompt.md         |  10 +-
 codev-skeleton/protocols/spike/protocol.md    |  74 +------------
 .../protocols/spir/builder-prompt.md          |  10 +-
 .../1011-agent-farm-inline-protocol-md-.md    |  54 ++++-----
 codev/protocols/air/builder-prompt.md         |  10 +-
 codev/protocols/aspir/builder-prompt.md       |  10 +-
 codev/protocols/bugfix/builder-prompt.md      |  10 +-
 codev/protocols/experiment/builder-prompt.md  |  10 +-
 codev/protocols/experiment/protocol.md        | 104 +-----------------
 codev/protocols/maintain/builder-prompt.md    |  10 +-
 codev/protocols/pir/builder-prompt.md         |  10 +-
 codev/protocols/research/builder-prompt.md    |  10 +-
 codev/protocols/spike/builder-prompt.md       |  10 +-
 codev/protocols/spike/protocol.md             |  74 +------------
 codev/protocols/spir/builder-prompt.md        |  10 +-
 codev/state/pir-1011_thread.md                |  12 ++
 .../src/__tests__/framework-ref-audit.test.ts |  13 ++-
 .../baselines/air-builder-prompt.md.baseline  |   2 +-
 .../aspir-builder-prompt.md.baseline          |   2 +-
 .../baselines/spir-builder-prompt.md.baseline |   2 +-
 .../agent-farm/__tests__/spawn-roles.test.ts  |  39 ++++++-
 .../src/agent-farm/commands/spawn-roles.ts    |  65 +++++++----
 30 files changed, 306 insertions(+), 419 deletions(-)

diff --git a/codev-skeleton/protocols/air/builder-prompt.md b/codev-skeleton/protocols/air/builder-prompt.md
index ed71fa32c..4e786b07e 100644
--- a/codev-skeleton/protocols/air/builder-prompt.md
+++ b/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.
+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}}
diff --git a/codev-skeleton/protocols/aspir/builder-prompt.md b/codev-skeleton/protocols/aspir/builder-prompt.md
index 52adeb2ae..049149c53 100644
--- a/codev-skeleton/protocols/aspir/builder-prompt.md
+++ b/codev-skeleton/protocols/aspir/builder-prompt.md
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the ASPIR protocol.
+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
 
@@ -110,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}}
diff --git a/codev-skeleton/protocols/bugfix/builder-prompt.md b/codev-skeleton/protocols/bugfix/builder-prompt.md
index 8d140e037..011c749a8 100644
--- a/codev-skeleton/protocols/bugfix/builder-prompt.md
+++ b/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.
+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}}
diff --git a/codev-skeleton/protocols/experiment/builder-prompt.md b/codev-skeleton/protocols/experiment/builder-prompt.md
index c9c9a5453..2a8d86923 100644
--- a/codev-skeleton/protocols/experiment/builder-prompt.md
+++ b/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.
+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}}
diff --git a/codev-skeleton/protocols/experiment/protocol.md b/codev-skeleton/protocols/experiment/protocol.md
index acb820d75..ded112f73 100644
--- a/codev-skeleton/protocols/experiment/protocol.md
+++ b/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
-touch notes.md   # populate from the "## Template: notes.md" section at the end of this protocol
+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]"
@@ -225,104 +225,6 @@ Create SPIR spec for production caching implementation.
 
 ## Template: notes.md
 
-> Embedded copy of the notes.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+Create `notes.md` with the following content:
 
-<!-- BEGIN EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
-# Experiment ####: Name
-
-**Status**: In Progress | Complete | Disproved | Aborted
-
-**Date**: YYYY-MM-DD
-
-## Goal
-
-What are you trying to learn or test? Be specific about:
-- The question you're answering
-- The hypothesis you're testing
-- Success criteria (how will you know if it worked?)
-
-## Effort
-
-**Approximate time spent**: [e.g., "4 hours"]
-
-*(Optional: Break down into setup, coding, analysis if helpful)*
-
-## Approach
-
-Brief description of the approach being tested:
-- Key technique or method
-- Why this approach was chosen
-- Any alternatives considered
-
-## Environment & Reproduction
-
-**How to run**:
-```bash
-# Command to reproduce results
-python experiment.py --input data/input/sample.json
-```
-
-**Dependencies** (if different from main project):
-- List any additional packages required
-- Or reference: `pip install -r requirements.txt`
-
-**Environment notes**:
-- Python version, key library versions if relevant
-- Any seeds or configuration needed for reproducibility
-
-## Code
-
-List your experiment files:
-- [`experiment.py`](experiment.py) - Brief description
-- [Other files as needed]
-
-## Results
-
-### Summary
-
-One-paragraph summary of key findings.
-
-### Key Findings
-
-1. **Finding one**: Description and significance
-2. **Finding two**: Description and significance
-3. **Finding three**: Description and significance
-
-### Metrics
-
-| Metric | Value | Notes |
-|--------|-------|-------|
-| Metric 1 | Value | Context |
-| Metric 2 | Value | Context |
-
-### Output Files
-
-- `data/output/results.csv` - Raw results data
-- `data/output/chart.png` - Visualization of findings
-
-## What Worked
-
-- List things that went well
-- Approaches that proved effective
-- Useful discoveries
-
-## What Didn't Work
-
-- Failed approaches (and why)
-- Dead ends encountered
-- Surprising obstacles
-
-## Next Steps
-
-Based on these findings:
-
-1. **Immediate**: What should happen right after this experiment?
-2. **Follow-up experiments**: What new questions emerged?
-3. **Production path**: If validated, what's needed for production? (SPIR spec?)
-
-## References
-
-- Links to relevant documentation
-- Related experiments
-- External resources consulted
-<!-- END EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
+{{> protocols/experiment/templates/notes.md}}
diff --git a/codev-skeleton/protocols/maintain/builder-prompt.md b/codev-skeleton/protocols/maintain/builder-prompt.md
index 03d2589ff..0eff31647 100644
--- a/codev-skeleton/protocols/maintain/builder-prompt.md
+++ b/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.
+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}}
diff --git a/codev-skeleton/protocols/pir/builder-prompt.md b/codev-skeleton/protocols/pir/builder-prompt.md
index c75dea8de..bbc6ae307 100644
--- a/codev-skeleton/protocols/pir/builder-prompt.md
+++ b/codev-skeleton/protocols/pir/builder-prompt.md
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the PIR protocol.
+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
@@ -89,3 +89,11 @@ If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch
 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}}
diff --git a/codev-skeleton/protocols/research/builder-prompt.md b/codev-skeleton/protocols/research/builder-prompt.md
index ee13cbc69..c01220055 100644
--- a/codev-skeleton/protocols/research/builder-prompt.md
+++ b/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.
+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}}
diff --git a/codev-skeleton/protocols/spike/builder-prompt.md b/codev-skeleton/protocols/spike/builder-prompt.md
index dec10de9b..67ea3a0e8 100644
--- a/codev-skeleton/protocols/spike/builder-prompt.md
+++ b/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.
+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}}
diff --git a/codev-skeleton/protocols/spike/protocol.md b/codev-skeleton/protocols/spike/protocol.md
index a0be3c6af..764a0bea6 100644
--- a/codev-skeleton/protocols/spike/protocol.md
+++ b/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 embedded template in the "## Template: findings.md" section at the end of this protocol
+- Use the embedded template at the end of this protocol
 - Provide a clear feasibility verdict
 - Commit and notify the architect
 
@@ -123,74 +123,6 @@ When a spike finds something is not feasible:
 
 ## Template: findings.md
 
-> Embedded copy of the findings.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+Write the findings document using the following template:
 
-<!-- BEGIN EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
-# Spike: [Title]
-
-**Date**: YYYY-MM-DD
-
-**Verdict**: Feasible | Not Feasible | Feasible with Caveats
-
-## Question
-
-What technical question was being investigated? Be specific:
-- What are you trying to determine?
-- What prompted this investigation?
-- What decision depends on the answer?
-
-## Research Summary
-
-What was explored during the research phase:
-- Documentation read
-- Existing code examined
-- Prior art found
-- Key constraints identified
-
-## Approaches Tried
-
-What was built or tested during the iterate phase:
-
-### Approach 1: [Name]
-- **What**: Brief description of what was tried
-- **Result**: What happened
-- **Verdict**: Worked / Didn't work / Partially worked
-
-### Approach 2: [Name]
-*(Add more approaches as needed, or remove if research alone answered the question)*
-
-## Constraints Discovered
-
-Technical limitations, dependencies, and gotchas found during the investigation:
-- [Constraint 1]
-- [Constraint 2]
-
-## Recommended Approach
-
-*(If feasible)* How should full implementation proceed?
-- Recommended library/technique/pattern
-- Key architectural decisions
-- Things to watch out for
-
-*(If not feasible)* Why not, and what alternatives exist?
-
-## Effort Estimate
-
-Rough sizing for a full SPIR project: **Small** | **Medium** | **Large**
-
-- Small: < 300 LOC, 1-2 files, straightforward
-- Medium: 300-1000 LOC, multiple files, some complexity
-- Large: 1000+ LOC, architectural changes, significant complexity
-
-## Next Steps
-
-- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"]
-- [ ] [Or: "Do not pursue — blocked by X"]
-- [ ] [Or: "Investigate Y further before deciding"]
-
-## References
-
-- [Link to relevant documentation]
-- [Link to relevant code/commits]
-- [Link to external resources consulted]
-<!-- END EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
+{{> protocols/spike/templates/findings.md}}
diff --git a/codev-skeleton/protocols/spir/builder-prompt.md b/codev-skeleton/protocols/spir/builder-prompt.md
index 7c69272af..d8d264320 100644
--- a/codev-skeleton/protocols/spir/builder-prompt.md
+++ b/codev-skeleton/protocols/spir/builder-prompt.md
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIR protocol.
+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
 
@@ -111,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}}
diff --git a/codev/plans/1011-agent-farm-inline-protocol-md-.md b/codev/plans/1011-agent-farm-inline-protocol-md-.md
index 8a2d0b27e..13c22858e 100644
--- a/codev/plans/1011-agent-farm-inline-protocol-md-.md
+++ b/codev/plans/1011-agent-farm-inline-protocol-md-.md
@@ -32,26 +32,26 @@ when the file lives only in the embedded skeleton (fresh post-618 installs). The
 
 ## Locked Decisions (the 5 plan-gate decisions)
 
-**1 — Delimiter / heading format.**
-- Patch 1 (protocol.md): `\n\n---\n\n## Protocol Reference (full text)\n\n<contents>` (done).
-- Patch 2 embeds (experiment/spike): a `## Template` section near the reworded instruction,
-  with drift-anchor sentinels that use the **skeleton-relative** path (no `codev/` prefix, so the
-  Layer 3 doctor grep does not self-flag them):
-  ```
-  ## Template
-  > Embedded copy of the <name> template — delivered inline; recreate the target file from this.
-  <!-- BEGIN EMBEDDED TEMPLATE: protocols/<name>/templates/<file> -->
-  <template contents>
-  <!-- END EMBEDDED TEMPLATE: protocols/<name>/templates/<file> -->
-  ```
-
-**2 — Patch 2 mechanism: Option B (explicit-embed). [agree, strengthened]**
-Sub-handled by reference kind (finding #1): drop the redundant pointer in `spir`/`aspir`
-plan prompts (no embed — prompt already self-contained); embed `notes.md`/`findings.md` into
-`experiment`/`spike` `protocol.md`. Rationale beyond the architect's: auto-detect (A) would
-inline the 184-line canonical plan template *on top of* the existing `### Plan Structure`,
-delivering two conflicting layouts. B is correct, not just simpler; and cheaper than feared
-(~164 embedded lines, the big template dropped not duplicated).
+**1 — Delivery: fresh-at-delivery placeholder substitution (NOT a committed copy).**
+*(Revised at the dev-approval gate: the earlier static-embed committed a duplicate that would go
+stale; the reviewer rejected it.)*
+- protocol.md: the builder-prompt `## Protocol` section keeps "Follow the X protocol. Read and
+  internalize the protocol before starting any work." and, under `{{#if protocol_reference}}`,
+  references the full text below. A `{{protocol_reference}}` placeholder near the end of the
+  prompt is filled **fresh at spawn** by reading `protocol.md` through the resolver, so nothing
+  is committed into `builder-prompt.md` (no stale copy). `{{#if}}` makes bugfix (no protocol.md)
+  render cleanly with neither the reference sentence nor the section.
+- Templates (experiment/spike): the `## Template:` section in `protocol.md` carries a
+  `{{> protocols/<name>/templates/<file>}}` include directive, resolved fresh (recursively, while
+  building `{{protocol_reference}}`). The canonical `templates/*.md` stays single-source.
+
+**2 — A.2 mechanism: fresh-at-delivery include placeholder. [revised from explicit-embed]**
+Sub-handled by reference kind (finding #1): drop the redundant pointer in `spir`/`aspir` plan
+prompts (already self-contained via `### Plan Structure`); in `experiment`/`spike` `protocol.md`
+reword the cp/use-template step to point at the `## Template:` section, which holds a `{{> ...}}`
+include resolved fresh at delivery. Auto-detect (blanket scan) is still rejected — it would
+double-deliver a conflicting plan layout for spir/aspir. The include directive is explicit (the
+author marks exactly what to inline) so it keeps that discrimination without committing a copy.
 
 **3 — A.3 disposition: Option 2 (strip). [agree]**
 Remove the `> Quick Reference: See codev/resources/workflow-reference.md …` line from
@@ -138,8 +138,11 @@ sub-decision above. Doc hygiene tracked in #1013.)
 
 ## Risks & Alternatives Considered
 
-- **Drift:** embedded `notes.md`/`findings.md` vs canonical. Mitigation: unit test asserts the
-  `BEGIN/END EMBEDDED TEMPLATE` block byte-matches the canonical file. Drift fails CI.
+- **Drift:** eliminated by design — templates and protocol.md are delivered via fresh-at-spawn
+  placeholder substitution (`{{protocol_reference}}` / `{{> ...}}`), so no duplicate copy is
+  committed to drift. A test asserts the include placeholder is present and no static embed
+  remains. (Pre-existing, out-of-scope: `experiment/protocol.md` already has a `## notes.md
+  Template` section quoting part of `notes.md` via a relative ref — noted, not touched.)
 - **Doctor false positives:** scoping the grep to absolute `codev/…` paths (decision 5) keeps it
   aligned with the sweep; relative refs intentionally not matched.
 - **Auto-detect (Patch 2 = A):** rejected — double-delivers a conflicting plan layout (finding #1).
@@ -150,10 +153,11 @@ sub-decision above. Doc hygiene tracked in #1013.)
 ## Test Plan
 
 **Automated (`npm test` → `@cluesmith/codev`):**
-- Patch 1 (exist): protocol.md inlined under delimiter; omitted-without-error when absent.
+- Delivery (new): `buildPromptFromTemplate` fills `{{protocol_reference}}` from protocol.md fresh;
+  omits cleanly when absent; resolves `{{> ...}}` template includes recursively.
 - A.2 guard (new): `spir`/`aspir` `plan.md` no longer reference the template path and still carry
-  `### Plan Structure`; `experiment`/`spike` `protocol.md` embed-block byte-matches the canonical
-  template (drift guard).
+  `### Plan Structure`; `experiment`/`spike` `protocol.md` carry the `{{> ...}}` include and no
+  static embed.
 - Layer 2 guard (new): no `builder-prompt.md` references `protocol.md`; `roles/builder.md` has no
   `cat codev/protocols/…`; `spir/protocol.md` has no `workflow-reference.md`.
 - Layer 3 doctor (new, in `doctor.test.ts`): clean skeleton → check `ok`; a fixture with a
diff --git a/codev/protocols/air/builder-prompt.md b/codev/protocols/air/builder-prompt.md
index ed71fa32c..4e786b07e 100644
--- a/codev/protocols/air/builder-prompt.md
+++ b/codev/protocols/air/builder-prompt.md
@@ -24,7 +24,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the AIR protocol.
+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}}
diff --git a/codev/protocols/aspir/builder-prompt.md b/codev/protocols/aspir/builder-prompt.md
index 1e912b1f0..44214aa32 100644
--- a/codev/protocols/aspir/builder-prompt.md
+++ b/codev/protocols/aspir/builder-prompt.md
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the ASPIR protocol.
+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
 
@@ -88,3 +88,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}}
diff --git a/codev/protocols/bugfix/builder-prompt.md b/codev/protocols/bugfix/builder-prompt.md
index 0f0f59ef2..d2cf0a01c 100644
--- a/codev/protocols/bugfix/builder-prompt.md
+++ b/codev/protocols/bugfix/builder-prompt.md
@@ -25,7 +25,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the BUGFIX protocol.
+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}}
diff --git a/codev/protocols/experiment/builder-prompt.md b/codev/protocols/experiment/builder-prompt.md
index c9c9a5453..2a8d86923 100644
--- a/codev/protocols/experiment/builder-prompt.md
+++ b/codev/protocols/experiment/builder-prompt.md
@@ -24,7 +24,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the EXPERIMENT protocol.
+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}}
diff --git a/codev/protocols/experiment/protocol.md b/codev/protocols/experiment/protocol.md
index 3f3c1c66c..b97dfb09a 100644
--- a/codev/protocols/experiment/protocol.md
+++ b/codev/protocols/experiment/protocol.md
@@ -37,7 +37,7 @@ mkdir -p experiments/1_experiment_name
 cd experiments/1_experiment_name
 
 # Initialize notes.md from template
-touch notes.md   # populate from the "## Template: notes.md" section at the end of this protocol
+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]"
@@ -230,104 +230,6 @@ Create SPIR spec for production caching implementation.
 
 ## Template: notes.md
 
-> Embedded copy of the notes.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+Create `notes.md` with the following content:
 
-<!-- BEGIN EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
-# Experiment ####: Name
-
-**Status**: In Progress | Complete | Disproved | Aborted
-
-**Date**: YYYY-MM-DD
-
-## Goal
-
-What are you trying to learn or test? Be specific about:
-- The question you're answering
-- The hypothesis you're testing
-- Success criteria (how will you know if it worked?)
-
-## Effort
-
-**Approximate time spent**: [e.g., "4 hours"]
-
-*(Optional: Break down into setup, coding, analysis if helpful)*
-
-## Approach
-
-Brief description of the approach being tested:
-- Key technique or method
-- Why this approach was chosen
-- Any alternatives considered
-
-## Environment & Reproduction
-
-**How to run**:
-```bash
-# Command to reproduce results
-python experiment.py --input data/input/sample.json
-```
-
-**Dependencies** (if different from main project):
-- List any additional packages required
-- Or reference: `pip install -r requirements.txt`
-
-**Environment notes**:
-- Python version, key library versions if relevant
-- Any seeds or configuration needed for reproducibility
-
-## Code
-
-List your experiment files:
-- [`experiment.py`](experiment.py) - Brief description
-- [Other files as needed]
-
-## Results
-
-### Summary
-
-One-paragraph summary of key findings.
-
-### Key Findings
-
-1. **Finding one**: Description and significance
-2. **Finding two**: Description and significance
-3. **Finding three**: Description and significance
-
-### Metrics
-
-| Metric | Value | Notes |
-|--------|-------|-------|
-| Metric 1 | Value | Context |
-| Metric 2 | Value | Context |
-
-### Output Files
-
-- `data/output/results.csv` - Raw results data
-- `data/output/chart.png` - Visualization of findings
-
-## What Worked
-
-- List things that went well
-- Approaches that proved effective
-- Useful discoveries
-
-## What Didn't Work
-
-- Failed approaches (and why)
-- Dead ends encountered
-- Surprising obstacles
-
-## Next Steps
-
-Based on these findings:
-
-1. **Immediate**: What should happen right after this experiment?
-2. **Follow-up experiments**: What new questions emerged?
-3. **Production path**: If validated, what's needed for production? (SPIR spec?)
-
-## References
-
-- Links to relevant documentation
-- Related experiments
-- External resources consulted
-<!-- END EMBEDDED TEMPLATE: protocols/experiment/templates/notes.md -->
+{{> protocols/experiment/templates/notes.md}}
diff --git a/codev/protocols/maintain/builder-prompt.md b/codev/protocols/maintain/builder-prompt.md
index 03d2589ff..0eff31647 100644
--- a/codev/protocols/maintain/builder-prompt.md
+++ b/codev/protocols/maintain/builder-prompt.md
@@ -23,7 +23,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the MAINTAIN protocol.
+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}}
diff --git a/codev/protocols/pir/builder-prompt.md b/codev/protocols/pir/builder-prompt.md
index c75dea8de..bbc6ae307 100644
--- a/codev/protocols/pir/builder-prompt.md
+++ b/codev/protocols/pir/builder-prompt.md
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the PIR protocol.
+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
@@ -89,3 +89,11 @@ If your Claude session crashes mid-flow, Tower's `while true` loop will relaunch
 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}}
diff --git a/codev/protocols/research/builder-prompt.md b/codev/protocols/research/builder-prompt.md
index ee13cbc69..c01220055 100644
--- a/codev/protocols/research/builder-prompt.md
+++ b/codev/protocols/research/builder-prompt.md
@@ -24,7 +24,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the RESEARCH protocol.
+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}}
diff --git a/codev/protocols/spike/builder-prompt.md b/codev/protocols/spike/builder-prompt.md
index dec10de9b..67ea3a0e8 100644
--- a/codev/protocols/spike/builder-prompt.md
+++ b/codev/protocols/spike/builder-prompt.md
@@ -11,7 +11,7 @@ You are running in SOFT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIKE protocol.
+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}}
diff --git a/codev/protocols/spike/protocol.md b/codev/protocols/spike/protocol.md
index b3b4b55b2..9b121d4cc 100644
--- a/codev/protocols/spike/protocol.md
+++ b/codev/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 embedded template in the "## Template: findings.md" section at the end of this protocol
+- Use the embedded template at the end of this protocol
 - Provide a clear feasibility verdict
 - Commit and notify the architect
 
@@ -123,74 +123,6 @@ When a spike finds something is not feasible:
 
 ## Template: findings.md
 
-> Embedded copy of the findings.md template, delivered inline so you do not need to fetch a file. Recreate the target file from the content between the markers below.
+Write the findings document using the following template:
 
-<!-- BEGIN EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
-# Spike: [Title]
-
-**Date**: YYYY-MM-DD
-
-**Verdict**: Feasible | Not Feasible | Feasible with Caveats
-
-## Question
-
-What technical question was being investigated? Be specific:
-- What are you trying to determine?
-- What prompted this investigation?
-- What decision depends on the answer?
-
-## Research Summary
-
-What was explored during the research phase:
-- Documentation read
-- Existing code examined
-- Prior art found
-- Key constraints identified
-
-## Approaches Tried
-
-What was built or tested during the iterate phase:
-
-### Approach 1: [Name]
-- **What**: Brief description of what was tried
-- **Result**: What happened
-- **Verdict**: Worked / Didn't work / Partially worked
-
-### Approach 2: [Name]
-*(Add more approaches as needed, or remove if research alone answered the question)*
-
-## Constraints Discovered
-
-Technical limitations, dependencies, and gotchas found during the investigation:
-- [Constraint 1]
-- [Constraint 2]
-
-## Recommended Approach
-
-*(If feasible)* How should full implementation proceed?
-- Recommended library/technique/pattern
-- Key architectural decisions
-- Things to watch out for
-
-*(If not feasible)* Why not, and what alternatives exist?
-
-## Effort Estimate
-
-Rough sizing for a full SPIR project: **Small** | **Medium** | **Large**
-
-- Small: < 300 LOC, 1-2 files, straightforward
-- Medium: 300-1000 LOC, multiple files, some complexity
-- Large: 1000+ LOC, architectural changes, significant complexity
-
-## Next Steps
-
-- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"]
-- [ ] [Or: "Do not pursue — blocked by X"]
-- [ ] [Or: "Investigate Y further before deciding"]
-
-## References
-
-- [Link to relevant documentation]
-- [Link to relevant code/commits]
-- [Link to external resources consulted]
-<!-- END EMBEDDED TEMPLATE: protocols/spike/templates/findings.md -->
+{{> protocols/spike/templates/findings.md}}
diff --git a/codev/protocols/spir/builder-prompt.md b/codev/protocols/spir/builder-prompt.md
index d176663a2..5ced4019d 100644
--- a/codev/protocols/spir/builder-prompt.md
+++ b/codev/protocols/spir/builder-prompt.md
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIR protocol.
+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
 
@@ -88,3 +88,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}}
diff --git a/codev/state/pir-1011_thread.md b/codev/state/pir-1011_thread.md
index 0e61b9a67..aeaf719ea 100644
--- a/codev/state/pir-1011_thread.md
+++ b/codev/state/pir-1011_thread.md
@@ -39,3 +39,15 @@ bugfix sub-decision RESOLVED → drop its dead pointer, embed nothing. Evidence:
 Also found + left out-of-scope: `codev/protocols/release/protocol.md:43` cats maintain/protocol.md (architect-run, codev/-only, not in skeleton). And relative-path template refs inside protocol.md (spir:215/301, experiment:90) — relative, informational.
 
 Two pre-existing tests updated (legit staleness from the sweep): baked-decisions.test.ts baselines (3 fixtures swept to match) + bugfix-619 assertion (now asserts no protocol.md path at all, preserving #619 intent). Build ✓, full suite ✓ (3270 passed, 13 pre-existing skips). Still at dev-approval gate.
+
+## Reworked at dev-approval gate: static embed/append → fresh-at-delivery placeholders (2026-06-08)
+
+Reviewer feedback: (a) "Follow the X protocol." is too terse + don't drop "Read and internalize..."; want a reference + a literal placeholder that's replaced; (b) embedding notes.md/findings.md inline causes staleness.
+
+Reworked the whole delivery mechanism:
+- spawn-roles.ts: removed the append; added `resolveIncludes()` (recursive `{{> path}}` resolution) + `resolveProtocolReference()`; buildPromptFromTemplate now sets a `{{protocol_reference}}` context var (protocol.md read FRESH at spawn, with its `{{> ...}}` template includes resolved). No committed copy anywhere → no staleness.
+- builder-prompts (9, both trees): `## Protocol` restored to "Follow the X protocol. Read and internalize the protocol before starting any work.{{#if protocol_reference}} ...included below...{{/if}}" + appended `{{#if protocol_reference}} ## Protocol Reference (full text) {{protocol_reference}}{{/if}}`.
+- experiment/spike protocol.md: replaced my static embed with `{{> protocols/<name>/templates/<file>}}` include (resolved fresh). Found + left a PRE-EXISTING out-of-scope partial copy of notes.md in experiment's `## notes.md Template` section (relative ref).
+- Tests: spawn-roles placeholder + include tests; framework-ref-audit drift test now asserts include-present + no static embed; baked-decisions baselines re-swept to the new `## Protocol` line.
+
+Build ✓, full suite ✓ (3271 passed, 13 skips). Still at dev-approval gate.
diff --git a/packages/codev/src/__tests__/framework-ref-audit.test.ts b/packages/codev/src/__tests__/framework-ref-audit.test.ts
index 7f16fd941..5bd65a8a1 100644
--- a/packages/codev/src/__tests__/framework-ref-audit.test.ts
+++ b/packages/codev/src/__tests__/framework-ref-audit.test.ts
@@ -97,17 +97,20 @@ describe('skeleton sweep + embeds (issue #1011 Layers 1/2, Patch 2)', () => {
     }
   });
 
-  it('experiment/spike embed the canonical template verbatim (drift guard)', () => {
+  it('experiment/spike reference templates via fresh-at-delivery include, not a static embed', () => {
     const cases = [
       { protocol: 'experiment', tmpl: 'notes.md' },
       { protocol: 'spike', tmpl: 'findings.md' },
     ];
     for (const { protocol, tmpl } of cases) {
       const md = readFileSync(join(SKELETON, 'protocols', protocol, 'protocol.md'), 'utf-8');
-      const canonical = readFileSync(join(SKELETON, 'protocols', protocol, 'templates', tmpl), 'utf-8');
-      expect(md).toContain('## Template: ' + tmpl);
-      // The full canonical template must be present verbatim — drift fails here.
-      expect(md).toContain(canonical.trimEnd());
+      // Uses the include placeholder, so the canonical template stays single-source
+      // and is read fresh at spawn — it cannot drift.
+      expect(md).toContain(`{{> protocols/${protocol}/templates/${tmpl}}}`);
+      // The static embed (BEGIN/END markers) is gone — that was the drift risk.
+      expect(md).not.toContain('EMBEDDED TEMPLATE');
+      // The canonical template still exists for the include to resolve against.
+      expect(existsSync(join(SKELETON, 'protocols', protocol, 'templates', tmpl))).toBe(true);
     }
   });
 });
diff --git a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline
index a9af8cc21..9cc3822fe 100644
--- a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline
+++ b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/air-builder-prompt.md.baseline
@@ -24,7 +24,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the AIR protocol.
+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}}
 
 {{#if issue}}
 ## Issue #{{issue.number}}
diff --git a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline
index 4e54e453f..c0a563ce0 100644
--- a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline
+++ b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/aspir-builder-prompt.md.baseline
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the ASPIR protocol.
+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}}
 
 {{#if spec}}
 ## Spec
diff --git a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline
index 1931e53c1..aeb21ce37 100644
--- a/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline
+++ b/packages/codev/src/agent-farm/__tests__/fixtures/baselines/spir-builder-prompt.md.baseline
@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIR protocol.
+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}}
 
 {{#if spec}}
 ## Spec
diff --git a/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts b/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts
index 2fbba9d70..00faaa5fb 100644
--- a/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts
+++ b/packages/codev/src/agent-farm/__tests__/spawn-roles.test.ts
@@ -319,7 +319,10 @@ describe('spawn-roles', () => {
       );
       fs.writeFileSync(
         path.join(skeletonRoot, 'protocols', 'spir', 'builder-prompt.md'),
-        '# {{protocol_name}} prompt for {{input_description}}',
+        // #1011: the {{protocol_reference}} placeholder is filled fresh at spawn
+        // from protocol.md (and its {{> ...}} includes); {{#if}} guards it.
+        '# {{protocol_name}} prompt for {{input_description}}\n' +
+          '{{#if protocol_reference}}\n## Protocol Reference (full text)\n{{protocol_reference}}{{/if}}\n',
       );
       fs.mkdirSync(path.join(skeletonRoot, 'protocols', 'bugfix'), { recursive: true });
       fs.writeFileSync(
@@ -363,7 +366,7 @@ describe('spawn-roles', () => {
       expect(prompt).toContain('SPIR prompt for a v3 feature');
     });
 
-    it('inlines protocol.md content under a Protocol Reference delimiter (issue #1011)', async () => {
+    it('fills {{protocol_reference}} with protocol.md content fresh at delivery (issue #1011)', async () => {
       const fs = await import('node:fs');
       const path = await import('node:path');
       fs.writeFileSync(
@@ -382,11 +385,41 @@ describe('spawn-roles', () => {
 
       // Still carries the rendered builder-prompt template...
       expect(prompt).toContain('SPIR prompt for a v3 feature');
-      // ...plus the inlined protocol meta-doc under a clear delimiter heading.
+      // ...plus the protocol meta-doc, substituted into the {{protocol_reference}}
+      // placeholder under the template's delimiter heading (read fresh, not committed).
       expect(prompt).toContain('## Protocol Reference (full text)');
       expect(prompt).toContain('META_DOC_SENTINEL: gate semantics and when-to-use guidance.');
     });
 
+    it('resolves {{> ...}} template includes inside protocol.md fresh at delivery (issue #1011)', async () => {
+      const fs = await import('node:fs');
+      const path = await import('node:path');
+      // protocol.md references a template via an include directive rather than a
+      // committed copy — the resolver reads the template fresh, so it can't drift.
+      fs.mkdirSync(path.join(skeletonRoot, 'protocols', 'spir', 'templates'), { recursive: true });
+      fs.writeFileSync(
+        path.join(skeletonRoot, 'protocols', 'spir', 'templates', 'plan.md'),
+        'TEMPLATE_SENTINEL: the canonical plan template body.',
+      );
+      fs.writeFileSync(
+        path.join(skeletonRoot, 'protocols', 'spir', 'protocol.md'),
+        '# SPIR Protocol\n\nUse the template below:\n\n{{> protocols/spir/templates/plan.md}}\n',
+      );
+
+      const ctx: TemplateContext = {
+        protocol_name: 'SPIR',
+        mode: 'strict',
+        mode_soft: false,
+        mode_strict: true,
+        input_description: 'a v3 feature',
+      };
+      const prompt = buildPromptFromTemplate(makeConfig(), 'spir', ctx);
+
+      // The include directive is gone (resolved), replaced by the template body.
+      expect(prompt).not.toContain('{{> protocols/spir/templates/plan.md}}');
+      expect(prompt).toContain('TEMPLATE_SENTINEL: the canonical plan template body.');
+    });
+
     it('builds the prompt without error and omits the reference when protocol.md is absent (issue #1011)', () => {
       // The skeleton-fallback beforeEach creates spir/ with no protocol.md.
       const ctx: TemplateContext = {
diff --git a/packages/codev/src/agent-farm/commands/spawn-roles.ts b/packages/codev/src/agent-farm/commands/spawn-roles.ts
index f434fcad0..3484d5bcc 100644
--- a/packages/codev/src/agent-farm/commands/spawn-roles.ts
+++ b/packages/codev/src/agent-farm/commands/spawn-roles.ts
@@ -45,6 +45,7 @@ export interface TemplateContext {
   task_text?: string;
   spec_missing?: boolean;
   existing_branch?: string;  // Spec 609: when --branch is used, the name of the existing branch
+  protocol_reference?: string;  // #1011: protocol.md text, resolved fresh at spawn and inlined via the {{protocol_reference}} placeholder
 }
 
 /**
@@ -104,31 +105,50 @@ function loadBuilderPromptTemplate(config: Config, protocolName: string): string
   if (!templatePath) {
     return null;
   }
-  let template = readFileSync(templatePath, 'utf-8');
-
-  // Inline protocol.md so the builder has the protocol meta-doc in its initial
-  // context instead of fetching it. Post-Spec-618 fresh installs don't copy
-  // protocol files locally; the resolver finds protocol.md in the embedded
-  // skeleton (tier 4), but the builder-prompt's literal `cat codev/protocols/...`
-  // instruction can't — it would hit an empty path and waste turns hunting.
-  // Delivering it inline at spawn means the builder never runs a shell command
-  // that bypasses the resolver, and the meta-doc is in early conversation
-  // context for the whole session (read once, never re-shipped per phase).
+  return readFileSync(templatePath, 'utf-8');
+}
+
+/**
+ * Resolve `{{> <skeleton-relative-path>}}` include directives by reading the
+ * referenced framework file fresh through the resolver and substituting its
+ * content in place (recursively, so an included file may itself include).
+ *
+ * This is how framework files are delivered to the builder without committing
+ * a duplicated copy anywhere: the canonical file (e.g. a protocol's template)
+ * stays the single source of truth and is read at spawn time, so it can never
+ * go stale. Unresolvable includes collapse to empty (the file genuinely isn't
+ * shipped — e.g. an optional template), never an error.
+ */
+function resolveIncludes(content: string, config: Config, depth = 0): string {
+  if (depth > 5) return content; // cycle / runaway guard
+  return content.replace(/\{\{>\s*([^}\s]+)\s*\}\}/g, (_match, relPath: string) => {
+    const resolved = resolveCodevFile(relPath, config.workspaceRoot);
+    if (!resolved) {
+      logger.debug(`Include not resolved: ${relPath} (skipped)`);
+      return '';
+    }
+    return resolveIncludes(readFileSync(resolved, 'utf-8'), config, depth + 1);
+  });
+}
+
+/**
+ * Compute the protocol meta-doc text to inline into the spawn prompt via the
+ * `{{protocol_reference}}` placeholder. Reads `protocol.md` fresh through the
+ * resolver (tier 4 reaches the embedded skeleton in fresh installs) and
+ * resolves any `{{> ...}}` template includes inside it. Returns '' when the
+ * protocol ships no `protocol.md` (e.g. bugfix) — the builder-prompt's
+ * `{{#if protocol_reference}}` guard then renders cleanly with no reference.
+ */
+function resolveProtocolReference(config: Config, protocolName: string): string {
   const protocolDocPath = resolveCodevFile(
     `protocols/${protocolName}/protocol.md`,
     config.workspaceRoot,
   );
-  if (protocolDocPath) {
-    template += `\n\n---\n\n## Protocol Reference (full text)\n\n` +
-      readFileSync(protocolDocPath, 'utf-8');
-  } else {
-    // Missing protocol.md is not fatal here: validateProtocol() runs earlier in
-    // the spawn flow and already aborts if both protocol.json and protocol.md
-    // are absent. Reaching this point means the json exists; spawn proceeds
-    // without the inline reference rather than failing.
-    logger.debug(`No protocol.md found for ${protocolName}; spawning without inlined reference`);
+  if (!protocolDocPath) {
+    logger.debug(`No protocol.md for ${protocolName}; spawning without inlined reference`);
+    return '';
   }
-  return template;
+  return resolveIncludes(readFileSync(protocolDocPath, 'utf-8'), config);
 }
 
 /**
@@ -187,7 +207,10 @@ export function buildPromptFromTemplate(
   const template = loadBuilderPromptTemplate(config, protocolName);
   if (template) {
     logger.info(`Using template: protocols/${protocolName}/builder-prompt.md`);
-    return renderTemplate(template, context);
+    // Deliver the protocol meta-doc (and any templates it includes) fresh at
+    // spawn via the {{protocol_reference}} placeholder — never a committed copy.
+    const protocol_reference = resolveProtocolReference(config, protocolName);
+    return renderTemplate(template, { ...context, protocol_reference });
   }
   // Fallback: no template found, return a basic prompt
   logger.debug(`No template found for ${protocolName}, using inline prompt`);

From 15345f54677560b765f08674126eddc62c800361 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Mon, 8 Jun 2026 14:43:31 +1000
Subject: [PATCH 14/14] [PIR #1011] Tighten framework-files convention note
 (accuracy + scope)

Per dev-approval feedback: the blanket 'never shell-fetch a framework file by
literal path' overreached (role docs can be tier-2 overridden into the workspace)
and was advisory-not-load-bearing (the doctor check is the mechanical guard).
Scope it to builder-facing prompts/role-docs, acknowledge the override, drop the
absolute framing.
---
 AGENTS.md | 10 ++++------
 CLAUDE.md | 10 ++++------
 2 files changed, 8 insertions(+), 12 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d5ca94599..d63df37e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,15 +88,13 @@ 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: never shell-fetch them by literal path
+### Framework files in prompts: deliver, don't shell-fetch
 
-Framework files (protocol docs, role docs, and the framework resources under `codev/resources/` such as `workflow-reference.md`, `risk-triage.md`, and `commands/`) ship in the package skeleton and resolve through the four-tier lookup above. They are **not guaranteed to exist on disk** in a user project, so:
+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.
 
-- **Never instruct a shell read of a framework file by literal path** — no `cat codev/protocols/<x>/protocol.md`, no `cp codev/protocols/<x>/templates/<f>`. Shell commands bypass the resolver and fail in fresh installs. Builders receive framework content through resolver-backed channels instead: `protocol.md` is inlined into the spawn prompt, and per-phase prompts plus their templates arrive via porch (`porch next`) or embedded directly in the prompt.
-- **Documentation may still mention a `codev/...` framework path** for orientation (e.g. the protocol list above) — that is fine; it resolves via the skeleton and stays callable from the CLI. The rule is about *fetching*, not *referencing*.
-- `codev/resources/arch.md` and `codev/resources/lessons-learned.md` are **user-project files** (you read and write them), not framework files — referencing them by path is correct.
+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 shell-fetch violations of this rule.
+`codev doctor` audits the skeleton for this.
 
 ### Protocol Verification (When You Don't Recognize a Protocol Name)
 
diff --git a/CLAUDE.md b/CLAUDE.md
index d5ca94599..d63df37e2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -88,15 +88,13 @@ 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: never shell-fetch them by literal path
+### Framework files in prompts: deliver, don't shell-fetch
 
-Framework files (protocol docs, role docs, and the framework resources under `codev/resources/` such as `workflow-reference.md`, `risk-triage.md`, and `commands/`) ship in the package skeleton and resolve through the four-tier lookup above. They are **not guaranteed to exist on disk** in a user project, so:
+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.
 
-- **Never instruct a shell read of a framework file by literal path** — no `cat codev/protocols/<x>/protocol.md`, no `cp codev/protocols/<x>/templates/<f>`. Shell commands bypass the resolver and fail in fresh installs. Builders receive framework content through resolver-backed channels instead: `protocol.md` is inlined into the spawn prompt, and per-phase prompts plus their templates arrive via porch (`porch next`) or embedded directly in the prompt.
-- **Documentation may still mention a `codev/...` framework path** for orientation (e.g. the protocol list above) — that is fine; it resolves via the skeleton and stays callable from the CLI. The rule is about *fetching*, not *referencing*.
-- `codev/resources/arch.md` and `codev/resources/lessons-learned.md` are **user-project files** (you read and write them), not framework files — referencing them by path is correct.
+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 shell-fetch violations of this rule.
+`codev doctor` audits the skeleton for this.
 
 ### Protocol Verification (When You Don't Recognize a Protocol Name)