pal-e-docs

Plan: Knowledge Architecture

plan-2026-03-16-knowledge-architecture Plan

active plan
Project

Plan: Knowledge Architecture

Vision

Milestones become the structural boundary for plans. One active milestone per project, one plan per milestone. Completed milestones tier their children out of hot queries. Gapped positions eliminate cascading shifts. Projects scale indefinitely without degrading session performance.

Projects & Repos Touched

Project Repo What changes
pal-e-docs pal-e-docs NoteType enum, VALID_STATUSES, list_notes tiering, position logic
pal-e-docs pal-e-docs-sdk SDK methods for milestone + tier params
pal-e-docs pal-e-docs-mcp MCP tools for milestone + tier params
pal-e-agency claude-custom Session injection hook updates
pal-e-agency — Template + convention notes (docs only)

Context

Discovered during pal-e-agency audit on 2026-03-16. Token cost analysis showed list_notes returning 84K chars (~21K tokens) for pal-e-agency. Plan sprawl: plan-pal-e-docs at 26 phases, plan-wkq at 19 phases. Doc drift: 6 specialized agent notes active in docs but consolidated to 5-agent model in code. Root cause: no structural boundary for completed work. Milestones existed decoratively on project pages but had no note_type, no lifecycle, no hierarchy enforcement.

Previous Plan

plan-pal-e-docs — Interactive Knowledge Platform. Still active for F11 (Design System) and F13 (Context Intelligence). This plan does not replace it — it covers new scope that plan-pal-e-docs was never designed for. Once F11 and F13 complete, plan-pal-e-docs will be marked completed.

Depends On

  • pal-e-docs semantic search (LIVE) — vectors enable cold-tier discoverability after notes leave hot queries
  • Block-first access pattern (LIVE) — makes large plans manageable even before tiering

Decisions Made

  • Convention-first, enforce later. Milestone hierarchy is a convention before it's a hook. Manual enforcement until pattern is proven.
  • Pragmatic for history, clean going forward. Completed plans stay flat. New work uses milestone parents.
  • Don't reparent in-flight work. F11 and F13 finish under plan-pal-e-docs. New work goes under new milestones.
  • Gapped integers, not floats. Position spacing of 1000. Periodic rebalance when gaps collapse. No float precision issues.
  • Tiering derived from milestone status, not a separate column. Completed milestone → children are cold. No new DB column needed initially.
  • Dogfood before generalizing. pal-e-docs uses milestones first. Other projects adopt after the pattern is proven.

Phases

See child phase notes: list_notes(parent_slug="plan-2026-03-16-knowledge-architecture")

Key Files

File What
<code>pal-e-docs/src/pal_e_docs/routes/notes.py</code> NoteType enum, VALID_STATUSES, list_notes filtering
<code>pal-e-docs/src/pal_e_docs/models.py</code> Note.position, Block.position
<code>pal-e-docs/src/pal_e_docs/routes/blocks.py</code> Block position/insert logic
<code>claude-custom/hooks/session-start-context.sh</code> Session injection — milestone-aware filtering
<code>pal-e-docs-sdk/src/pal_e_docs_sdk/notes.py</code> SDK list_notes tier param
<code>pal-e-docs-mcp/src/pal_e_docs_mcp/tools/notes.py</code> MCP list_notes tier param

Verification

  • list_notes(project="pal-e-agency") returns ~60 notes instead of ~131 (cold-tier excluded by default)
  • Session startup token injection drops by ~50% for mature projects
  • Block insert between positions 19000 and 20000 requires zero cascading shifts
  • agent-spawn-conventions and agent-workflow agree on agent count and model
  • New project creation starts with Milestone 1, not a bare plan

Epilogue

Phase 3 QA nits (PR #189):
  • Stale docstring in parser.py lines 33/38 — still references "0-based ordering" and "paragraph-3" examples. Should say "gapped" and "paragraph-1000".
  • _seed_note_with_blocks in test_blocks_api.py — add comment clarifying intentional use of legacy sequential positions for backward compat testing.
Phase 4 QA nits (PR #191):
  • Missing note_type + cold composition test (e.g., list_notes(note_type=phase) with mix of cold/warm phases).
  • Inaccurate _seed_notes docstring — says it returns a dict but returns None.
  • resolved status not in COLD_STATUSES — consider adding if the status is used in practice.
  • milestone-2026-03-16-knowledge-architecture — parent milestone
  • plan-pal-e-docs — predecessor plan (still active for F11, F13)
  • plan-pal-e-agency — agency plan whose Phase 12 doc drift motivated this work