pal-e-docs

Phase 7e: Compiled Page Architecture

phase-postgres-7e-compiled-pages Phase

Project
Goal: Make blocks the canonical source of truth and optimize session injection to use block-level tools instead of full note reads. Estimated ~90% token reduction at session startup.
Owner: Dev agent (7e-1, 7e-2), Betty Sue (7e-3)
Repos: pal-e-docs (7e-1, 7e-1a, 7e-2), claude-custom (7e-3)
Depends on: Phase 7d (block API must exist) — COMPLETED
Parent phase: Phase 7 (Block-Structured Content Model)
Status: COMPLETED — all sub-phases done.

Sub-Phases

# Sub-Phase Repo Status Deliverable
7e-1 Source-of-Truth Cutover pal-e-docs <strong>COMPLETED</strong> Blocks canonical — note writes parse to blocks first, then recompile. PR #110.
7e-1a QA Nits Cleanup pal-e-docs <strong>COMPLETED</strong> Redundant assignment fix, test helper hygiene. PR #114.
7e-2 Compiled Page API pal-e-docs <strong>COMPLETED</strong> <code>GET /notes/{slug}/compiled</code> endpoint. PR #113. SDK + MCP follow-on deferred.
7e-3 Session Injection + Block-First Convention claude-custom + pal-e-docs <strong>COMPLETED</strong> Hook injects plan TOCs (PR #68). Convention note, agent personalities, SOP updated. 91% token reduction measured.

What Was Delivered

  • 7e-1: Extracted recompile() and parse_and_store_blocks() into shared blocks/sync.py. create_note() and update_note() now parse to blocks first, then recompile. 14 new tests, 503 total passing. PR #110.
  • 7e-1a: QA nits — redundant html_content assignment, test helper session hygiene, detached ORM fix. PR #114.
  • 7e-2: GET /notes/{slug}/compiled endpoint with CompiledPageOut schema (slug, title, html, toc_json, content_hash, block_count, compiled_at). 8 new tests. PR #113.
  • 7e-3: Block-first established as platform convention:

Measured Results

Scenario Before After Savings
Session startup (6 plans) ~11,640 tokens ~1,032 tokens <strong>91.1%</strong>
Read one plan section ~2,360 tokens (full note) ~200 tokens (one section) <strong>~92%</strong>
Update one plan section ~2,360 tokens (full note round-trip) ~100 tokens (block update) <strong>~96%</strong>

Lessons Learned

  • Merged ≠ deployed ≠ data consistent. 7e-1 fixed future writes but couldn't retroactively fix notes created between the 7c backfill and deployment. 58 notes had no blocks. Re-backfill was essential before 7e-3 could work.
  • Test before shipping infrastructure changes. Testing the TOC endpoint revealed 2 of 6 plans had empty TOCs. Would have shipped broken hook without testing.
  • Convention shifts need more than code. 7e-3 started as "change the hook" but became 4 deliverables: convention note, agent personalities, SOP, hook. The pattern must be encoded everywhere agents get their instructions.
  • convention-block-first-access — the convention established by 7e-3
  • decision-7e3-block-first-access — decision record with rationale
  • phase-postgres-7d-api-mcp-tools — block API (prerequisite, COMPLETED)
  • phase-postgres-8-mcp-optimization — SDK + MCP tools (prerequisite, COMPLETED)
  • benchmark-phase7-block-baseline — baseline token measurements
  • plan-2026-03-01-pal-e-sprints-frontend — sprint frontend consumes compiled pages (7e-2 SDK/MCP deferred until then)