Skip to content

feat: add start_work/finish_work lifecycle for page notes #83

@viv

Description

@viv

Summary

Add status lifecycle support for page notes so agents can claim and address them through the same start_work/finish_work MCP workflow used for annotations.

Problem

Page notes currently have no status field and are excluded from the start_work/finish_work workflow. When a reviewer adds a page note like "restructure the hero section" or "navigation feels cluttered", an agent can see it via list_annotations but has no way to signal that it's working on it or mark it as addressed. The reviewer gets no feedback on whether their page-level feedback has been acted on.

Proposal

  • Add status lifecycle to page notes: open → in_progress → addressed (matching annotations)
  • Allow start_work to accept a page note ID — sets status to in_progress and returns full detail
  • Allow finish_work to accept a page note ID — sets status to addressed, optionally with a reply message
  • Add status badges and Accept/Reopen actions to page notes in the panel UI (matching annotation behaviour)
  • Update list_annotations to include page note status in the response and respect the status filter parameter

Key Constraints

  • Backward compatibility — existing page notes without a status field should default to open (same pattern used for annotations)
  • Schema change — page notes will need inProgressAt, addressedAt, status, and replies fields added to the type definition
  • REST API — the PATCH endpoint for page notes currently only accepts note updates; it will need to accept status changes and replies too
  • MCP tools — start_work and finish_work currently validate against annotation IDs only; they need to check page notes as well

Complexity

Medium — touches types, storage, MCP tools, REST API, and panel UI, but each change follows existing annotation patterns closely.

Related

  • The MCP workflow (list → start → finish) is documented in CLAUDE.md and the README
  • Page notes are already returned by list_annotations but lack lifecycle fields

Tasks

  • Engineering plan must be created as a markdown document
  • Engineering plan must be maintained and kept up to date
  • The spec document (`docs/spec/specification.md`) must be updated to reflect the new behaviour
  • Extend `src/shared/types.ts` — add status, inProgressAt, addressedAt, and replies fields to PageNote type
  • Update `src/server/storage.ts` — handle new page note fields with backward-compatible defaults
  • Update REST API (`src/server/middleware.ts`) — PATCH endpoint for page notes must accept status changes and replies
  • Update MCP tools — start_work and finish_work must accept page note IDs
  • Update list_annotations — page note status filtering
  • Update panel UI (`src/client/ui/panel.ts`) — status badges, Accept/Reopen actions for page notes
  • Unit tests for page note status transitions in storage
  • Unit tests for MCP tool changes (start_work/finish_work with page note IDs)
  • Unit tests for REST API page note PATCH with status and replies
  • Unit tests for panel rendering of page note status
  • Scenario tests or acceptance tests must be updated to handle the new feature
  • An independent review must be carried out and a markdown report added to the repo
  • The findings of the independent code review must be assessed and addressed, keeping the review report up to date
  • All commits must follow the style already established by the repo (conventional commits, no authored-by tagline)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions