From 8534c0b131cceda8a923b6c352a088d1d885e974 Mon Sep 17 00:00:00 2001
From: M Waleed Kadous <waleedk@gmail.com>
Date: Mon, 29 Jun 2026 10:42:36 -0700
Subject: [PATCH 1/6] chore(porch): 1119 init air

---
 .../status.yaml                                    | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 codev/projects/1119-replace-hot-context-managed-bl/status.yaml

diff --git a/codev/projects/1119-replace-hot-context-managed-bl/status.yaml b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
new file mode 100644
index 000000000..538a7c6b8
--- /dev/null
+++ b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
@@ -0,0 +1,14 @@
+id: '1119'
+title: replace-hot-context-managed-bl
+protocol: air
+phase: implement
+plan_phases: []
+current_plan_phase: null
+gates:
+  pr:
+    status: pending
+iteration: 1
+build_complete: false
+history: []
+started_at: '2026-06-29T17:42:36.679Z'
+updated_at: '2026-06-29T17:42:36.681Z'

From 237532ee205df07d42174239ef0f4f706316a70a Mon Sep 17 00:00:00 2001
From: M Waleed Kadous <waleedk@gmail.com>
Date: Mon, 29 Jun 2026 10:55:12 -0700
Subject: [PATCH 2/6] chore(porch): 1119 pr phase-transition

---
 .../projects/1119-replace-hot-context-managed-bl/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1119-replace-hot-context-managed-bl/status.yaml b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
index 538a7c6b8..a6bbfcab5 100644
--- a/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
+++ b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
@@ -1,7 +1,7 @@
 id: '1119'
 title: replace-hot-context-managed-bl
 protocol: air
-phase: implement
+phase: pr
 plan_phases: []
 current_plan_phase: null
 gates:
@@ -11,4 +11,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T17:42:36.679Z'
-updated_at: '2026-06-29T17:42:36.681Z'
+updated_at: '2026-06-29T17:55:12.209Z'

From 9e6379a2056be19175518923174d0da5da108752 Mon Sep 17 00:00:00 2001
From: M Waleed Kadous <waleedk@gmail.com>
Date: Mon, 29 Jun 2026 10:55:58 -0700
Subject: [PATCH 3/6] [AIR #1119] Replace hot-context managed block with
 @import lines

Replace the materialized verbatim copy of arch-critical.md +
lessons-critical.md in CLAUDE.md / AGENTS.md with Claude Code @import
lines, so the hot files are the single source of truth and the
committed block can no longer drift from them.

- managed-block.ts: renderHotContextBlock emits two @import lines
  (@codev/resources/{arch,lessons}-critical.md) instead of inlining
  content. Markers + intro + generated-do-not-edit comment kept, so an
  existing adopter's old inlined block auto-migrates to the @import form
  on next codev init/update via the idempotent upsert.
- Emit predicate is a literal fs.existsSync at codev/resources/<file>,
  NOT the four-tier resolver: an @import is a concrete on-disk path, so a
  skeleton-only (tier-4) fallback would produce a dangling import.
- Porch injection is unchanged: readHotTierFiles still inlines live hot
  content for phase prompts (the model never expands @import); that path
  is already DRY-safe (reads source live).
- Regenerated both root docs + all four source template docs; root
  CLAUDE.md and AGENTS.md stay byte-identical.
- Tests: assert the @import lines (not inlined content), add an
  adopter-migration case, and assert content edits no longer churn the
  block. Full suite green.
---
 AGENTS.md                                     | 70 ++--------------
 CLAUDE.md                                     | 70 ++--------------
 codev-skeleton/templates/AGENTS.md            | 16 ++++
 codev-skeleton/templates/CLAUDE.md            | 16 ++++
 codev/state/air-1119_thread.md                | 52 ++++++++++++
 codev/templates/AGENTS.md                     | 16 ++++
 codev/templates/CLAUDE.md                     | 16 ++++
 .../hot-tier-materialization.test.ts          |  6 ++
 .../codev/src/__tests__/managed-block.test.ts | 81 ++++++++++++++-----
 packages/codev/src/lib/managed-block.ts       | 40 +++++++--
 10 files changed, 228 insertions(+), 155 deletions(-)
 create mode 100644 codev/state/air-1119_thread.md

diff --git a/AGENTS.md b/AGENTS.md
index e91188b86..c48b754f4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,77 +2,17 @@
 
 <!-- BEGIN CODEV HOT CONTEXT (generated — do not edit) -->
 
-<!-- Generated from codev/resources/{arch,lessons}-critical.md. Regenerated by
-     `codev init` / `codev update`. Do not edit here — edit the hot files. -->
+<!-- Generated by `codev init` / `codev update` from the hot files
+     (codev/resources/{arch,lessons}-critical.md). Do not edit here — edit the hot
+     files. The @import lines below are expanded into context at session launch. -->
 
 # Always-On Engineering Context (hot tier)
 
 Curated, always-on guidance — consult before deciding. Use each "consult when…"
 map to open the full arch.md / lessons-learned.md when relevant.
 
-# arch-critical.md — Always-On System-Shape Facts (HOT tier)
-
-<!-- HOT tier: capped facts + a bounded map of arch.md. Always injected into every porch
-phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 facts, <=12 map topics, <=35 lines.
-To add a fact, DEMOTE a weaker one into arch.md (displacement). MAINTAIN polices the cap
-and keeps the map in sync with arch.md's top-level sections. See codev/resources/arch.md. -->
-
-## Critical facts (consult before deciding)
-- Framework files resolve at RUNTIME via the four-tier chain (.codev/ → codev/ → cache → skeleton); they are NOT copied into projects. Don't wire features to "scaffold copies it."
-- Governance docs are two-tier (Spec 987): HOT arch-critical.md/lessons-critical.md are capped + always-injected; COLD arch.md/lessons-learned.md are reference. Route new facts/lessons by tier; never grow a hot file past its cap (demote to cold).
-- Two trees: codev/ = our instance, codev-skeleton/ = the template shipped to adopters. Mirror every framework change in BOTH.
-- CLAUDE.md and AGENTS.md MUST stay byte-identical (same content, two tool ecosystems).
-- Porch is a pure planner: it emits task JSON, Claude Code executes. Never hand-edit status.yaml.
-- State lives in .agent-farm/state.db + ~/.agent-farm/global.db (single source of truth); one Tower on port 4100. Never modify state by hand.
-- Worktrees in .builders/ are Agent-Farm-managed — never delete manually (use afx cleanup); run afx from the main workspace root only.
-- Forge concept commands abstract the VCS provider — add a dedicated concept; don't bolt env flags onto a shared one.
-- Two human gates (spec-approval, plan-approval) plus the pr gate; only humans transition conceived→specified and committed→integrated.
-- Never `git add -A` / `.` / `--all` — stage files explicitly.
-
-## Map of arch.md (consult when…)
-- Invariants & Constraints — touching state, ports, worktrees, or anything "MUST remain true."
-- Installation Architecture — touching init/adopt/update or the four-tier resolver.
-- Agent Farm Internals — changing spawn, Tower, terminals, or inter-agent messaging.
-- Repository Dual Nature — before editing any framework file (codev/ vs skeleton).
-- Core Components — locating where logic lives or wiring a new module.
-- Key Design Decisions — before reversing a design choice (the "why").
-- System-Wide Patterns — adding cross-cutting behavior.
-- Integration Points — crossing a subsystem or process boundary.
-- Monorepo Structure — adding a package or build wiring.
-- Technology Stack — choosing or upgrading a dependency.
-- VS Code Extension — changing sidebar views, commands, or keybindings.
-- Glossary — when a term is unfamiliar.
-
-# lessons-critical.md — Always-On Engineering Wisdom (HOT tier)
-
-<!-- HOT tier: capped lessons + a bounded map of lessons-learned.md. Always injected into
-every porch phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 lessons, <=12 map topics,
-<=35 lines. To add a lesson, DEMOTE a weaker one into lessons-learned.md (displacement).
-MAINTAIN polices the cap and keeps the map in sync with lessons-learned.md's sections. -->
-
-## Critical lessons (consult before deciding)
-- Trust the protocol — never skip CMAP/consultation; it catches security, design, and protocol issues solo review misses.
-- Check for existing work (PRs, git history) before building from scratch.
-- "It compiled" / "tests pass" is not "it works" — verify the real user path end-to-end before calling it done.
-- Model permissions as roles/capabilities, not booleans — booleans don't extend.
-- Single source of truth beats distributed state — consolidate duplicates rather than syncing them.
-- After any rename or framework change, grep the whole repo across BOTH codev/ and codev-skeleton/ before claiming "all fixed."
-- When stuck (2 failed hypotheses or ~30 min), get an outside model's perspective instead of guessing.
-- When guessing fails, build a minimal repro — captured raw data beats speculation.
-- "Who calls this in production?" grep before changing a long-lived API — vestigial code survives.
-- Verify reviewer/plan claims against the actual file before acting — summaries are evidence, not ground truth.
-
-## Map of lessons-learned.md (consult when…)
-- Critical — before any high-blast-radius change.
-- Security — handling input, auth, paths, or HTML/shell.
-- Architecture — choosing a design or abstraction.
-- Process — planning phases or scoping work.
-- Testing — writing tests or picking a harness.
-- UI/UX — changing views, status indicators, or accessibility.
-- Documentation — editing docs or the skeleton.
-- 3-Way Reviews — interpreting CMAP feedback.
-- Protocol Orchestration — touching porch, state, or gates.
-- Debugging and Root Cause Analysis — stuck on a bug.
+@codev/resources/arch-critical.md
+@codev/resources/lessons-critical.md
 
 <!-- END CODEV HOT CONTEXT -->
 
diff --git a/CLAUDE.md b/CLAUDE.md
index e91188b86..c48b754f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,77 +2,17 @@
 
 <!-- BEGIN CODEV HOT CONTEXT (generated — do not edit) -->
 
-<!-- Generated from codev/resources/{arch,lessons}-critical.md. Regenerated by
-     `codev init` / `codev update`. Do not edit here — edit the hot files. -->
+<!-- Generated by `codev init` / `codev update` from the hot files
+     (codev/resources/{arch,lessons}-critical.md). Do not edit here — edit the hot
+     files. The @import lines below are expanded into context at session launch. -->
 
 # Always-On Engineering Context (hot tier)
 
 Curated, always-on guidance — consult before deciding. Use each "consult when…"
 map to open the full arch.md / lessons-learned.md when relevant.
 
-# arch-critical.md — Always-On System-Shape Facts (HOT tier)
-
-<!-- HOT tier: capped facts + a bounded map of arch.md. Always injected into every porch
-phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 facts, <=12 map topics, <=35 lines.
-To add a fact, DEMOTE a weaker one into arch.md (displacement). MAINTAIN polices the cap
-and keeps the map in sync with arch.md's top-level sections. See codev/resources/arch.md. -->
-
-## Critical facts (consult before deciding)
-- Framework files resolve at RUNTIME via the four-tier chain (.codev/ → codev/ → cache → skeleton); they are NOT copied into projects. Don't wire features to "scaffold copies it."
-- Governance docs are two-tier (Spec 987): HOT arch-critical.md/lessons-critical.md are capped + always-injected; COLD arch.md/lessons-learned.md are reference. Route new facts/lessons by tier; never grow a hot file past its cap (demote to cold).
-- Two trees: codev/ = our instance, codev-skeleton/ = the template shipped to adopters. Mirror every framework change in BOTH.
-- CLAUDE.md and AGENTS.md MUST stay byte-identical (same content, two tool ecosystems).
-- Porch is a pure planner: it emits task JSON, Claude Code executes. Never hand-edit status.yaml.
-- State lives in .agent-farm/state.db + ~/.agent-farm/global.db (single source of truth); one Tower on port 4100. Never modify state by hand.
-- Worktrees in .builders/ are Agent-Farm-managed — never delete manually (use afx cleanup); run afx from the main workspace root only.
-- Forge concept commands abstract the VCS provider — add a dedicated concept; don't bolt env flags onto a shared one.
-- Two human gates (spec-approval, plan-approval) plus the pr gate; only humans transition conceived→specified and committed→integrated.
-- Never `git add -A` / `.` / `--all` — stage files explicitly.
-
-## Map of arch.md (consult when…)
-- Invariants & Constraints — touching state, ports, worktrees, or anything "MUST remain true."
-- Installation Architecture — touching init/adopt/update or the four-tier resolver.
-- Agent Farm Internals — changing spawn, Tower, terminals, or inter-agent messaging.
-- Repository Dual Nature — before editing any framework file (codev/ vs skeleton).
-- Core Components — locating where logic lives or wiring a new module.
-- Key Design Decisions — before reversing a design choice (the "why").
-- System-Wide Patterns — adding cross-cutting behavior.
-- Integration Points — crossing a subsystem or process boundary.
-- Monorepo Structure — adding a package or build wiring.
-- Technology Stack — choosing or upgrading a dependency.
-- VS Code Extension — changing sidebar views, commands, or keybindings.
-- Glossary — when a term is unfamiliar.
-
-# lessons-critical.md — Always-On Engineering Wisdom (HOT tier)
-
-<!-- HOT tier: capped lessons + a bounded map of lessons-learned.md. Always injected into
-every porch phase prompt and into CLAUDE.md/AGENTS.md. CAP: <=10 lessons, <=12 map topics,
-<=35 lines. To add a lesson, DEMOTE a weaker one into lessons-learned.md (displacement).
-MAINTAIN polices the cap and keeps the map in sync with lessons-learned.md's sections. -->
-
-## Critical lessons (consult before deciding)
-- Trust the protocol — never skip CMAP/consultation; it catches security, design, and protocol issues solo review misses.
-- Check for existing work (PRs, git history) before building from scratch.
-- "It compiled" / "tests pass" is not "it works" — verify the real user path end-to-end before calling it done.
-- Model permissions as roles/capabilities, not booleans — booleans don't extend.
-- Single source of truth beats distributed state — consolidate duplicates rather than syncing them.
-- After any rename or framework change, grep the whole repo across BOTH codev/ and codev-skeleton/ before claiming "all fixed."
-- When stuck (2 failed hypotheses or ~30 min), get an outside model's perspective instead of guessing.
-- When guessing fails, build a minimal repro — captured raw data beats speculation.
-- "Who calls this in production?" grep before changing a long-lived API — vestigial code survives.
-- Verify reviewer/plan claims against the actual file before acting — summaries are evidence, not ground truth.
-
-## Map of lessons-learned.md (consult when…)
-- Critical — before any high-blast-radius change.
-- Security — handling input, auth, paths, or HTML/shell.
-- Architecture — choosing a design or abstraction.
-- Process — planning phases or scoping work.
-- Testing — writing tests or picking a harness.
-- UI/UX — changing views, status indicators, or accessibility.
-- Documentation — editing docs or the skeleton.
-- 3-Way Reviews — interpreting CMAP feedback.
-- Protocol Orchestration — touching porch, state, or gates.
-- Debugging and Root Cause Analysis — stuck on a bug.
+@codev/resources/arch-critical.md
+@codev/resources/lessons-critical.md
 
 <!-- END CODEV HOT CONTEXT -->
 
diff --git a/codev-skeleton/templates/AGENTS.md b/codev-skeleton/templates/AGENTS.md
index 463c1bc93..35d705ccf 100644
--- a/codev-skeleton/templates/AGENTS.md
+++ b/codev-skeleton/templates/AGENTS.md
@@ -1,5 +1,21 @@
 # {{PROJECT_NAME}} - AI Agent Instructions
 
+<!-- BEGIN CODEV HOT CONTEXT (generated — do not edit) -->
+
+<!-- Generated by `codev init` / `codev update` from the hot files
+     (codev/resources/{arch,lessons}-critical.md). Do not edit here — edit the hot
+     files. The @import lines below are expanded into context at session launch. -->
+
+# Always-On Engineering Context (hot tier)
+
+Curated, always-on guidance — consult before deciding. Use each "consult when…"
+map to open the full arch.md / lessons-learned.md when relevant.
+
+@codev/resources/arch-critical.md
+@codev/resources/lessons-critical.md
+
+<!-- END CODEV HOT CONTEXT -->
+
 > **Note**: This file follows the [AGENTS.md standard](https://agents.md/) for cross-tool compatibility with Cursor, GitHub Copilot, and other AI coding assistants. A Claude Code-specific version is maintained in `CLAUDE.md`.
 
 ## Project Overview
diff --git a/codev-skeleton/templates/CLAUDE.md b/codev-skeleton/templates/CLAUDE.md
index 19f545b1e..07e5fc4a1 100644
--- a/codev-skeleton/templates/CLAUDE.md
+++ b/codev-skeleton/templates/CLAUDE.md
@@ -1,5 +1,21 @@
 # {{PROJECT_NAME}} - Claude Code Instructions
 
+<!-- BEGIN CODEV HOT CONTEXT (generated — do not edit) -->
+
+<!-- Generated by `codev init` / `codev update` from the hot files
+     (codev/resources/{arch,lessons}-critical.md). Do not edit here — edit the hot
+     files. The @import lines below are expanded into context at session launch. -->
+
+# Always-On Engineering Context (hot tier)
+
+Curated, always-on guidance — consult before deciding. Use each "consult when…"
+map to open the full arch.md / lessons-learned.md when relevant.
+
+@codev/resources/arch-critical.md
+@codev/resources/lessons-critical.md
+
+<!-- END CODEV HOT CONTEXT -->
+
 ## Project Overview
 
 This project uses **Codev** for AI-assisted development.
diff --git a/codev/state/air-1119_thread.md b/codev/state/air-1119_thread.md
new file mode 100644
index 000000000..a3c05eb08
--- /dev/null
+++ b/codev/state/air-1119_thread.md
@@ -0,0 +1,52 @@
+# air-1119 — Replace hot-context managed block with @import lines
+
+Issue #1119 (AIR, strict mode). Replace the materialized hot-context managed block
+in CLAUDE.md/AGENTS.md with Claude Code `@import` lines → single source of truth,
+no drift footgun.
+
+## Phase: Implement
+
+### Findings from recon
+- `renderHotContextBlock` (lib/managed-block.ts) is the only thing to change for the
+  block content. It currently calls `readHotTierFiles` and inlines verbatim content.
+- `readHotTierFiles` is ALSO used by porch's `buildHotTierContext` (prompts.ts) which
+  must keep inlining live content (model never expands @import). So I leave
+  `readHotTierFiles` untouched; `renderHotContextBlock` stops calling it and instead
+  emits `@import` lines per-file-that-resolves.
+- `packages/codev/skeleton/` is a BUILD ARTIFACT (gitignored; `cp -r ../../codev-skeleton
+  skeleton` at build). So I edit the 4 SOURCE template docs:
+  `codev-skeleton/templates/{CLAUDE,AGENTS}.md` + `codev/templates/{CLAUDE,AGENTS}.md`.
+  The two `packages/codev/skeleton/templates/*` come for free at build.
+- DISCREPANCY vs issue text: the template docs currently carry NO hot block at all
+  (no markers, no inlined content) — the block is injected at `codev init` time via
+  `syncHotContextBlock`. The issue's "three copies" is source + root CLAUDE.md + root
+  AGENTS.md. Acceptance still asks the six templates to carry the @import lines inside
+  markers, so I add the (idempotent, drift-free) @import block to the 4 source templates
+  after their first H1, matching `renderHotContextBlock`'s exact output so init's sync
+  is a no-op on them.
+- Resolution check: `renderHotContextBlock` emits a line iff `resolveCodevFile` finds the
+  hot file (same notion as the rest of the system); import path is fixed `@codev/resources/X`.
+
+### Plan
+1. managed-block.ts: new renderHotContextBlock emitting @import lines (+ HOT_IMPORTS const).
+2. Regenerate root CLAUDE.md/AGENTS.md via the real syncHotContextBlock (build first).
+3. Add matching @import block to the 4 source template docs.
+4. Update tests: managed-block.test.ts, hot-tier-materialization.test.ts (assert @import,
+   not inlined content; add adopter-migration case). governance-sweep marker checks stay.
+5. Full suite green; CLAUDE.md ≡ AGENTS.md byte-identical.
+
+## Progress
+- managed-block.ts: renderHotContextBlock now emits @import lines.
+- IMPORTANT subtlety caught by a test: the emit predicate must be a LITERAL
+  fs.existsSync at `codev/resources/<file>`, NOT resolveCodevFile (four-tier).
+  resolveCodevFile falls back to the package skeleton (tier 4), so it returns
+  non-null even when codev/resources/ is empty → would emit a DANGLING @import.
+  readHotTierFiles (porch inline path) keeps four-tier on purpose — different
+  mechanism (inline live content, skeleton fallback is legit there).
+- Regenerated 2 root docs + 4 source templates via the REAL syncHotContextBlock/
+  upsertHotContextBlock code path (scratchpad regen.mjs against built dist).
+- Root CLAUDE.md ≡ AGENTS.md byte-identical ✓; no inlined hot content ✓;
+  all 6 docs carry the 2 @import lines inside markers ✓.
+- copy-skeleton re-run so the gitignored build artifact reflects template edits.
+- Hot-tier tests (19) green. Full suite running.
+- Diff: 9 tracked files (~172 ins / 155 del, well under 300 LOC).
diff --git a/codev/templates/AGENTS.md b/codev/templates/AGENTS.md
index a4bed4faa..b39ec5397 100644
--- a/codev/templates/AGENTS.md
+++ b/codev/templates/AGENTS.md
@@ -1,5 +1,21 @@
 # {{PROJECT_NAME}} - AI Agent Instructions
 
+<!-- BEGIN CODEV HOT CONTEXT (generated — do not edit) -->
+
+<!-- Generated by `codev init` / `codev update` from the hot files
+     (codev/resources/{arch,lessons}-critical.md). Do not edit here — edit the hot
+     files. The @import lines below are expanded into context at session launch. -->
+
+# Always-On Engineering Context (hot tier)
+
+Curated, always-on guidance — consult before deciding. Use each "consult when…"
+map to open the full arch.md / lessons-learned.md when relevant.
+
+@codev/resources/arch-critical.md
+@codev/resources/lessons-critical.md
+
+<!-- END CODEV HOT CONTEXT -->
+
 > **Note**: This file follows the [AGENTS.md standard](https://agents.md/) for cross-tool compatibility with Cursor, GitHub Copilot, and other AI coding assistants. A Claude Code-specific version is maintained in `CLAUDE.md`.
 
 ## Project Overview
diff --git a/codev/templates/CLAUDE.md b/codev/templates/CLAUDE.md
index 882510178..f263b0b56 100644
--- a/codev/templates/CLAUDE.md
+++ b/codev/templates/CLAUDE.md
@@ -1,5 +1,21 @@
 # {{PROJECT_NAME}} - Claude Code Instructions
 
+<!-- BEGIN CODEV HOT CONTEXT (generated — do not edit) -->
+
+<!-- Generated by `codev init` / `codev update` from the hot files
+     (codev/resources/{arch,lessons}-critical.md). Do not edit here — edit the hot
+     files. The @import lines below are expanded into context at session launch. -->
+
+# Always-On Engineering Context (hot tier)
+
+Curated, always-on guidance — consult before deciding. Use each "consult when…"
+map to open the full arch.md / lessons-learned.md when relevant.
+
+@codev/resources/arch-critical.md
+@codev/resources/lessons-critical.md
+
+<!-- END CODEV HOT CONTEXT -->
+
 ## Project Overview
 
 This project uses **Codev** for AI-assisted development.
diff --git a/packages/codev/src/__tests__/hot-tier-materialization.test.ts b/packages/codev/src/__tests__/hot-tier-materialization.test.ts
index 29c5ee55c..851b8fd40 100644
--- a/packages/codev/src/__tests__/hot-tier-materialization.test.ts
+++ b/packages/codev/src/__tests__/hot-tier-materialization.test.ts
@@ -95,5 +95,11 @@ describe('Spec 987 — codev update materializes hot files + injects the block',
     expect(claude).toContain(HOT_BLOCK_BEGIN);
     expect(claude).toContain('KEEP_USER_CONTENT');
     expect(claude).toBe(agents);
+
+    // #1119: the block carries @import lines, not a verbatim copy of the hot files.
+    expect(claude).toContain('@codev/resources/arch-critical.md');
+    expect(claude).toContain('@codev/resources/lessons-critical.md');
+    // The hot files' own structural marker would only appear if content were inlined.
+    expect(claude).not.toContain('<!-- HOT tier:');
   });
 });
diff --git a/packages/codev/src/__tests__/managed-block.test.ts b/packages/codev/src/__tests__/managed-block.test.ts
index ea67f409f..04a651711 100644
--- a/packages/codev/src/__tests__/managed-block.test.ts
+++ b/packages/codev/src/__tests__/managed-block.test.ts
@@ -65,7 +65,7 @@ describe('Spec 987 — managed block (pure upsert logic)', () => {
   });
 });
 
-describe('Spec 987 — managed block (render + sync into root docs)', () => {
+describe('Spec 987 / #1119 — managed block (render + sync into root docs)', () => {
   let tmp: string;
 
   beforeEach(() => {
@@ -75,13 +75,29 @@ describe('Spec 987 — managed block (render + sync into root docs)', () => {
     fs.rmSync(tmp, { recursive: true, force: true });
   });
 
-  it('renders a marker-delimited block carrying both hot files', () => {
+  it('renders a marker-delimited block of @import lines, not inlined hot content', () => {
     seedHotFiles(tmp);
     const block = renderHotContextBlock(tmp);
     expect(block.startsWith(HOT_BLOCK_BEGIN)).toBe(true);
     expect(block.trimEnd().endsWith(HOT_BLOCK_END)).toBe(true);
-    expect(block).toContain('ARCH_HOT_MARKER');
-    expect(block).toContain('LESSONS_HOT_MARKER');
+    // #1119: the block points at the on-disk hot files (single source of truth) …
+    expect(block).toContain('@codev/resources/arch-critical.md');
+    expect(block).toContain('@codev/resources/lessons-critical.md');
+    // … and never copies their verbatim content in (that was the drift footgun).
+    expect(block).not.toContain('ARCH_HOT_MARKER');
+    expect(block).not.toContain('LESSONS_HOT_MARKER');
+  });
+
+  it('emits an @import only for a hot file that resolves; returns "" when neither does', () => {
+    // Neither hot file present → no block, callers leave the doc untouched.
+    expect(renderHotContextBlock(tmp)).toBe('');
+
+    // Only arch-critical present → only its import line is emitted.
+    fs.mkdirSync(path.join(tmp, 'codev', 'resources'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'codev', 'resources', 'arch-critical.md'), '# arch\n');
+    const block = renderHotContextBlock(tmp);
+    expect(block).toContain('@codev/resources/arch-critical.md');
+    expect(block).not.toContain('@codev/resources/lessons-critical.md');
   });
 
   it('injects an identical block into both CLAUDE.md and AGENTS.md; skips missing docs', () => {
@@ -94,8 +110,8 @@ describe('Spec 987 — managed block (render + sync into root docs)', () => {
 
     const claude = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8');
     const agents = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8');
-    // Both carry the block and remain byte-identical (the CLAUDE.md ≡ AGENTS.md invariant).
-    expect(claude).toContain('ARCH_HOT_MARKER');
+    // Both carry the @import block and remain byte-identical (the CLAUDE.md ≡ AGENTS.md invariant).
+    expect(claude).toContain('@codev/resources/arch-critical.md');
     expect(claude).toContain('project instructions');
     expect(claude).toBe(agents);
 
@@ -105,22 +121,51 @@ describe('Spec 987 — managed block (render + sync into root docs)', () => {
     expect(syncHotContextBlock(tmp)).toEqual(['CLAUDE.md']);
   });
 
-  it('refreshes the block when a hot file changes, preserving user edits outside it', () => {
-    seedHotFiles(tmp, 'ARCH_V1');
+  it('is idempotent — editing hot-file content does not churn the block (the DRY win)', () => {
+    seedHotFiles(tmp);
     fs.writeFileSync(path.join(tmp, 'CLAUDE.md'), '# Codev\n\nKEEP_ME_ABOVE\n\n## More\nKEEP_ME_BELOW');
-    syncHotContextBlock(tmp);
+    expect(syncHotContextBlock(tmp)).toEqual(['CLAUDE.md']);
+    const after1 = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8');
+
+    // The block is @import lines, so changing hot-file CONTENT cannot stale it: a
+    // re-sync is a no-op. This is exactly the drift footgun the old inlined block had.
+    fs.writeFileSync(path.join(tmp, 'codev', 'resources', 'arch-critical.md'), '# arch\n\nTOTALLY_DIFFERENT\n');
+    expect(syncHotContextBlock(tmp)).toEqual([]);
+    const after2 = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8');
+
+    expect(after2).toBe(after1);
+    expect(after2).toContain('KEEP_ME_ABOVE');
+    expect(after2).toContain('KEEP_ME_BELOW');
+    expect(after2).toContain('@codev/resources/arch-critical.md');
+    // Still exactly one block.
+    expect(after2.split(HOT_BLOCK_BEGIN).length - 1).toBe(1);
+  });
 
-    // Edit the hot file and re-sync.
-    fs.writeFileSync(path.join(tmp, 'codev', 'resources', 'arch-critical.md'), '# arch\n\nARCH_V2\n');
-    const changed = syncHotContextBlock(tmp);
-    expect(changed).toEqual(['CLAUDE.md']);
+  it('migrates an existing adopter\'s old inlined block to the @import form', () => {
+    seedHotFiles(tmp);
+    // An existing adopter whose committed block still inlines verbatim hot content.
+    const oldInlined = [
+      HOT_BLOCK_BEGIN,
+      '',
+      '# Always-On Engineering Context (hot tier)',
+      '',
+      'ARCH_HOT_MARKER',
+      'LESSONS_HOT_MARKER',
+      '',
+      HOT_BLOCK_END,
+    ].join('\n');
+    fs.writeFileSync(path.join(tmp, 'CLAUDE.md'), `# Codev\n\n${oldInlined}\n\nUSER_TAIL`);
+
+    // The idempotent upsert replaces the stale inlined block in place on next sync.
+    expect(syncHotContextBlock(tmp)).toEqual(['CLAUDE.md']);
 
     const claude = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8');
-    expect(claude).toContain('ARCH_V2');
-    expect(claude).not.toContain('ARCH_V1');
-    expect(claude).toContain('KEEP_ME_ABOVE');
-    expect(claude).toContain('KEEP_ME_BELOW');
-    // Still exactly one block.
+    expect(claude).not.toContain('ARCH_HOT_MARKER');
+    expect(claude).not.toContain('LESSONS_HOT_MARKER');
+    expect(claude).toContain('@codev/resources/arch-critical.md');
+    expect(claude).toContain('@codev/resources/lessons-critical.md');
+    expect(claude).toContain('USER_TAIL');
+    // Exactly one block (migrated in place, not duplicated).
     expect(claude.split(HOT_BLOCK_BEGIN).length - 1).toBe(1);
   });
 });
diff --git a/packages/codev/src/lib/managed-block.ts b/packages/codev/src/lib/managed-block.ts
index 7ac7d3668..9831a987d 100644
--- a/packages/codev/src/lib/managed-block.ts
+++ b/packages/codev/src/lib/managed-block.ts
@@ -40,24 +40,50 @@ export function readHotTierFiles(workspaceRoot: string): string[] {
 }
 
 /**
- * Render the full managed block (markers + intro + hot content), or '' if no hot
- * files resolve (in which case callers leave the doc untouched).
+ * Hot files surfaced into the interactive root docs as Claude Code `@import` lines.
+ * `diskRelPath` is the literal on-disk location (relative to the importing doc's dir
+ * = workspace root); `importLine` is the `@`-prefixed path Claude Code expands into
+ * context at session launch. `copyHotTierDefaults` materializes each file at
+ * codev/resources/ on init/adopt/update, so the import target is present there.
+ *
+ * The emit predicate is a literal existence check at `diskRelPath`, NOT the four-tier
+ * resolver: an `@import` is a concrete path Claude Code reads from disk relative to
+ * the doc, so a skeleton-only (tier-4) fallback would produce a dangling import that
+ * never resolves. We emit a line only when the file truly sits at codev/resources/.
+ */
+const HOT_IMPORTS: ReadonlyArray<{ diskRelPath: string; importLine: string }> = [
+  { diskRelPath: 'codev/resources/arch-critical.md', importLine: '@codev/resources/arch-critical.md' },
+  { diskRelPath: 'codev/resources/lessons-critical.md', importLine: '@codev/resources/lessons-critical.md' },
+];
+
+/**
+ * Render the managed block (markers + intro + `@import` lines), or '' if neither
+ * hot file is present (in which case callers leave the doc untouched).
+ *
+ * Spec 987 originally inlined a verbatim copy of the hot files here; #1119 replaced
+ * that with Claude Code `@import` lines so the hot files stay the single source of
+ * truth — no copy to drift. Claude Code expands `@path` imports into context at
+ * session launch (always-on, transcluded — not lazy), giving the same guarantee as
+ * inlining minus the drift footgun. A line is emitted only if its hot file is on disk.
  */
 export function renderHotContextBlock(workspaceRoot: string): string {
-  const parts = readHotTierFiles(workspaceRoot);
-  if (parts.length === 0) return '';
+  const imports = HOT_IMPORTS
+    .filter((h) => fs.existsSync(path.join(workspaceRoot, h.diskRelPath)))
+    .map((h) => h.importLine);
+  if (imports.length === 0) return '';
   return [
     HOT_BLOCK_BEGIN,
     '',
-    '<!-- Generated from codev/resources/{arch,lessons}-critical.md. Regenerated by',
-    '     `codev init` / `codev update`. Do not edit here — edit the hot files. -->',
+    '<!-- Generated by `codev init` / `codev update` from the hot files',
+    '     (codev/resources/{arch,lessons}-critical.md). Do not edit here — edit the hot',
+    '     files. The @import lines below are expanded into context at session launch. -->',
     '',
     '# Always-On Engineering Context (hot tier)',
     '',
     'Curated, always-on guidance — consult before deciding. Use each "consult when…"',
     'map to open the full arch.md / lessons-learned.md when relevant.',
     '',
-    parts.join('\n\n'),
+    ...imports,
     '',
     HOT_BLOCK_END,
   ].join('\n');

From c0227aa4f9fb545d95db8e20b2ff7dba0e8ca2b6 Mon Sep 17 00:00:00 2001
From: M Waleed Kadous <waleedk@gmail.com>
Date: Mon, 29 Jun 2026 10:58:05 -0700
Subject: [PATCH 4/6] chore(porch): 1119 pr gate-requested

---
 .../projects/1119-replace-hot-context-managed-bl/status.yaml  | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1119-replace-hot-context-managed-bl/status.yaml b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
index a6bbfcab5..ef5e0691c 100644
--- a/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
+++ b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
@@ -7,8 +7,10 @@ current_plan_phase: null
 gates:
   pr:
     status: pending
+    requested_at: '2026-06-29T17:58:05.897Z'
 iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T17:42:36.679Z'
-updated_at: '2026-06-29T17:55:12.209Z'
+updated_at: '2026-06-29T17:58:05.898Z'
+pr_ready_for_human: true

From 89f1962a606b192bed53bb89d55f77558ca7bf09 Mon Sep 17 00:00:00 2001
From: M Waleed Kadous <waleedk@gmail.com>
Date: Mon, 29 Jun 2026 10:58:43 -0700
Subject: [PATCH 5/6] [AIR #1119] Update thread: PR #1120 opened, pr gate
 requested

---
 codev/state/air-1119_thread.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/codev/state/air-1119_thread.md b/codev/state/air-1119_thread.md
index a3c05eb08..9c761642b 100644
--- a/codev/state/air-1119_thread.md
+++ b/codev/state/air-1119_thread.md
@@ -50,3 +50,9 @@ no drift footgun.
 - copy-skeleton re-run so the gitignored build artifact reflects template edits.
 - Hot-tier tests (19) green. Full suite running.
 - Diff: 9 tracked files (~172 ins / 155 del, well under 300 LOC).
+
+## Phase: PR
+- Committed (9e6379a2), pushed builder/air-1119.
+- PR #1120 opened with AIR review in the body.
+- porch check: pr_exists + e2e_tests green. porch done → GATE: pr requested.
+- WAITING for human approval at the `pr` gate. Will not call porch approve (human-only).

From 0ef263a0b98de61286015986a08d6faf4d6b105c Mon Sep 17 00:00:00 2001
From: M Waleed Kadous <waleedk@gmail.com>
Date: Mon, 29 Jun 2026 13:42:45 -0700
Subject: [PATCH 6/6] chore(porch): 1119 pr gate-approved

---
 .../1119-replace-hot-context-managed-bl/status.yaml        | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/codev/projects/1119-replace-hot-context-managed-bl/status.yaml b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
index ef5e0691c..367bf0700 100644
--- a/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
+++ b/codev/projects/1119-replace-hot-context-managed-bl/status.yaml
@@ -6,11 +6,12 @@ plan_phases: []
 current_plan_phase: null
 gates:
   pr:
-    status: pending
+    status: approved
     requested_at: '2026-06-29T17:58:05.897Z'
+    approved_at: '2026-06-29T20:42:45.091Z'
 iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T17:42:36.679Z'
-updated_at: '2026-06-29T17:58:05.898Z'
-pr_ready_for_human: true
+updated_at: '2026-06-29T20:42:45.092Z'
+pr_ready_for_human: false