Skip to content

feat(api,mcp,frontend): metadata-only list payloads, opt-in REST flags; 10k description cap - #188

Merged
ck3mp3r merged 17 commits into
mainfrom
feature/list-payload-trim
Nov 7, 2026
Merged

ck3mp3r merged 17 commits into
mainfrom
feature/list-payload-trim

Conversation

@ck3mp3r

@ck3mp3r ck3mp3r commented Nov 7, 2026

Copy link
Copy Markdown
Owner

Summary

  • MCP list tools (task_list, skills_list, note_list, task_list_list) are metadata-only: no opt-in params, no content, even in search results. Agent-facing context can no longer be polluted by list content.
  • REST list endpoints default to metadata-only with opt-in flags (include_description, include_content, include_notes); REST q-search keeps full content.
  • Frontend: all 14 list consumers audited (research note 5fd65a9d) — 7 explicit flag pushes (api/mod.rs:315 include_description for kanban previews; notes pages/panes/print/stacks include_content); ungated-field consumers stay flag-free; by-id fetches remain the deep-content path.
  • Task descriptions capped at 10,000 chars write-time (create/update) with friendly validation errors; existing rows stay readable/transitionable/restorable; no migration.

Why (agent-usability rationale)

  • Description is 67% of every list item (780 vs 261 chars measured on the dev DB).
  • MCP pages 9k → 3.1k chars; REST unpaginated 35k → 12k; worst-case spec-heavy lists 140k → 40k — directly defeating MAX_LIMIT(20) context protection.
  • One task_list_list call in this project's own session pulled 20k+ chars of unread notes.
  • Two-audience split: agents get bounded two-step reads (list → single by-id fetch) with predictable spend; humans get scan-with-content via REST opt-ins.

Breaking changes

  • MCP: include_content param REMOVED from task_list/skills_list/note_list (metadata-only responses; content via get-by-id tools).
  • REST: /notes and /skills lists no longer return content unconditionally (opt-in); /task-lists omits notes by default (include_notes).
  • Task descriptions >10k rejected on create/update (schema CHECK 20251231170000 already capped rows since consolidation; the app-level check supplies friendly errors).

DB methods

  • TaskRepository::list_metadata_only (task.rs:361), SkillRepository::list_metadata_only (skill.rs:351).
  • is_skill_enabled is now record-name-based (reviewer-verified: the frontmatter-parse variant could not survive metadata-only).

Verification

  • Per-layer suites + workspace 815/815; clippy 0 warnings; fmt clean.
  • Leak-hunting tests: a content-leaking search fails the suite.
  • Live dev-server verification of the v2 contract on all six surfaces.
  • Residual human browser walkthrough of kanban/notes/skills XHRs.

Notes

  • 4 earliest commits unsigned (1Password agent failure era; re-sign via git rebase --exec 'git commit --amend --no-edit -S' 1a76afc if desired — a squash merge makes signatures moot).
  • Consumer-audit matrix: research note 5fd65a9d.
  • c5t tasks: 78ffc6da + 6 subtasks + hotfixes 7159f38d/5f741a35 + cancelled 534b8ee8.

Task list payloads carry unbounded descriptions, so the list path needs a variant that never reads the description column. Mirrors NoteRepository::list_metadata_only: same filters, ordering, and counts, with description omitted from both SQL branches and rows mapped inline.
Task list pages carried full developer specs, up to 15k chars per 10-item page. task_list now mirrors note_list: query keeps full search results, include_content=true returns full list rows, and the default lists metadata only through TaskRepository::list_metadata_only.
GET /api/v1/task-lists/{list_id}/tasks returned all 45 live tasks with full specs, about 35k chars. The handler now defaults to metadata-only rows through TaskRepository::list_metadata_only; include_description=true restores full rows and q search keeps descriptions. TaskResponse and single-entity endpoints are unchanged.
The REST task list now omits descriptions by default, but Kanban cards render a 100-char markdown preview from list data. list_for_task_list appends include_description=true so all five call sites keep their previews without a signature change.
Skill listings embed the full SKILL.md body, so the list path needs a variant that never reads the content column. Mirrors the notes and tasks metadata-only lists: identical filters, DISTINCT/JOIN handling, ordering, and counts, with a dedicated row mapper that sets content to an empty string.
Skill listings embedded full SKILL.md bodies, several at 10k+ chars. skills_list now mirrors note_list and task_list: query keeps full search results, include_content=true returns full rows, and the default lists metadata only through SkillRepository::list_metadata_only.
GET /api/v1/skills returned every SKILL.md body. List rows now blank the content unless include_content=true, after the enabled flag is computed from the stored content, so enabled stays correct. Search keeps full content; single-entity GET is unchanged.
The include_content opt-in is removed from task_list and skill_list. Plain lists use the metadata-only repository methods, searches still run FTS for selection, and both paths project descriptions/content to their metadata placeholders at the response layer. Get-by-id tools keep full content.
The include_description and include_content query params are removed from the task and skill list endpoints. Lists use the metadata-only repository methods, FTS still selects rows for search, and both paths blank the blob at the response layer. is_skill_enabled now checks the cache directory by record name, so enabled survives blanking without parsing content.
note_list drops include_content. Plain lists use the metadata-only repository method, searches still run FTS for selection, and both paths blank content at the response layer. note_get and note_read keep full content.
GET /api/v1/notes now lists metadata-only rows and projects search results to the same shape, with no opt-in parameter. The empty-q early return and the response envelope are unchanged; single-entity note endpoints keep full content.
RULING v2: REST lists default to metadata-only but accept include_description/include_content for full rows, and search returns full content again. The name-based is_skill_enabled refactor stays. MCP keeps its flag-free metadata-only contract.
MCP task_list_list now returns notes null on plain and search results with no flag, per the metadata-only MCP contract. REST GET /api/v1/task-lists defaults to notes null but accepts include_notes=true for full notes on both the list and q-search routes; single-entity responses keep notes.
GET /api/v1/notes regains the opt-in flag with the v2 contract: default lists are metadata-only, include_content=true returns full rows, and a non-empty q searches with full content. The q-empty early return and single-entity handlers are unchanged.
Task descriptions were unbounded at the application layer: validate_task
checked only title and priority, so create and update accepted arbitrarily
large payloads while notes already reject content above a hard maximum.
Tasks now follow the same policy with a single 10,000-character cap.

The check lives in validate_task, which already runs on create and update,
so no new call sites are added. Over-limit descriptions now fail with
DbError::Validation (MCP: invalid_params validation_error) instead of a raw
SQLite CHECK error. Rows seeded before the cap keep working for reads,
listing, transitions, and restores; only new or edited over-limit
descriptions are rejected.
The REST notes list now defaults to metadata-only, so the notes and project-notes pages rendered cards without bodies. Both QueryBuilder chains append include_content=true; note detail and skills fetches are unchanged.
The project-detail notes tab, the note-stack sidebar (initial and load-more) and the print subnote loop all render content from list data, so each fetch now appends include_content=true. The has-subnotes probe stays metadata-only and by-id fetches are untouched.
@ck3mp3r
ck3mp3r merged commit 4644cb6 into main Nov 7, 2026
2 checks passed
@ck3mp3r
ck3mp3r deleted the feature/list-payload-trim branch November 7, 2026 10:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant