pal-e-docs

Phase 4: Knowledge Tiering — list_notes Default Exclusion

phase-2026-03-16-4-knowledge-tiering Phase

phase
Project

Phase 4: Knowledge Tiering — list_notes Default Exclusion

Goal: Make list_notes stop returning completed/historical notes by default. Cold exclusion via status-based filtering.
Owner: Dev agent
Repo: forgejo_admin/pal-e-docs, forgejo_admin/pal-e-docs-sdk, forgejo_admin/pal-e-docs-mcp
Depends on: Phase 2 (milestone note type — completed)

Scope

Tiering Rules (status-based, first pass)

Tier Rule Default in list_notes
<strong>Hot/Warm</strong> Notes with status NOT in cold set, or NULL status Included
<strong>Cold</strong> Status in {completed, done, deprecated, deferred, archived} Excluded (include_cold=true to opt in)

Edge Cases

  • Explicit status=completed param bypasses cold exclusion (caller clearly wants cold notes)
  • NULL status → not cold (included by default)
  • Search endpoints (semantic_search, search_notes) unaffected

Deliverables

Backend (COMPLETED)

  • PR #191 on pal-e-docs — merged 2026-03-17
  • COLD_STATUSES frozenset in routes/notes.py
  • include_cold Query param on GET /notes (default false)
  • Smart override: explicit status= bypasses cold filter
  • NULL status handled via or_ clause
  • 6 new tests, 638 total passing
  • Forgejo issue #190 (closed)

SDK (COMPLETED)

  • PR #33 on pal-e-docs-sdk — merged 2026-03-17
  • include_cold: bool = False param on list_notes()
  • 3 new tests
  • Forgejo issue #32 (closed)

MCP (COMPLETED)

  • PR #44 on pal-e-docs-mcp — merged 2026-03-17
  • include_cold Field param on list_notes tool with descriptive help text
  • 4 new tests
  • Forgejo issue #43 (closed)

Deferred Scope

  • Parent-chain CTE (notes under completed milestones) — stretch goal for subphase
  • include_frozen param — not needed yet (archived notes are rare)
  • Session injection hook changes — default behavior already correct

QA Nits (non-blocking)

  • PR #191: Missing note_type + cold composition test; inaccurate _seed_notes docstring; resolved status not in COLD_STATUSES
  • PR #33: Bool omission pattern differs from None-based convention (functionally correct)
  • PR #44: Zero nits
  • plan-2026-03-16-knowledge-architecture — parent plan
  • phase-2026-03-16-2-milestone-note-type — prerequisite (completed)
  • convention-block-first-access — complementary access optimization