pal-e-docs

Milestone: Knowledge Architecture

milestone-2026-03-16-knowledge-architecture Doc

active milestone
Project

Milestone: Knowledge Architecture

Evolve pal-e-docs from a flat knowledge system to a tiered, milestone-organized platform. Milestones become the structural boundary for plans — one active milestone per project, one plan per milestone. Completed milestones automatically tier their children out of hot queries, solving the unbounded token growth problem. Gapped integer positions eliminate cascading shifts on block/note inserts.

Success Criteria

  • milestone is a first-class note_type with lifecycle statuses
  • Plans require a milestone parent (convention-enforced, not hook-enforced yet)
  • list_notes defaults to excluding notes under completed milestones
  • Session injection token cost drops by ~50% for mature projects
  • Block/note inserts no longer require position cascading
  • Doc drift from pal-e-agency Phase 12 consolidated-agent work is cleaned up

Context

Discovered 2026-03-16 during pal-e-agency audit. Token cost analysis: list_notes(project="pal-e-agency") returns 84K chars (~21K tokens). Plan sprawl: plan-pal-e-docs has 26 phases, plan-wkq has 19 phases. Doc drift: 6 specialized agent notes marked active in docs but consolidated to 5-agent model in code (4 configs in claude-custom). Root cause: no structural boundary for completed work, no mechanism to cool finished knowledge out of hot queries.

Plan

plan-knowledge-architecture
  • plan-pal-e-docs — predecessor plan (still active for F11, F13)
  • convention-block-first-access — prerequisite pattern that makes large plans manageable
  • convention-memory-scope — memory = behavioral, pal-e-docs = state