<!-- SPDX-FileCopyrightText: 2026 FocusFlow contributors -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# Backlog Notes and Freeform Tags Metadata

## Status

Deferred from UI Plan 2 on 2026-07-07.

For the current Backlog board implementation, notes and freeform tags are
read-only presentation placeholders. Do not expand the current UI Plan 2 scope
to add persisted task notes or general-purpose tags.

## Why this is deferred

The drawer mockup includes notes and tag chips, but the current V1 `Task` domain
model only has narrow `BacklogTag` flags such as `wishlist`. It does not yet
have general freeform notes or user-defined task tags.

Adding those fields correctly is not a local widget change. It is a real V1
metadata and persistence feature with schema, migration, command, and test
impact.

## Work left for the future feature

When this feature is resumed, decide the exact product behavior first:

1. Whether notes are plain text only or support lightweight formatting later.
2. Whether tags are task-local strings or reusable global tag records.
3. Maximum note length.
4. Maximum tag count per task.
5. Maximum tag label length.
6. Case and duplicate handling for tags.
7. Whether tag edits are allowed in quick capture, the Backlog drawer, or both.
8. Whether existing imports/exports should include notes and tags immediately.

Expected implementation areas:

1. Add `String? notes` and either `Set<String> tags` or a small validated tag
   value object to `Task`.
2. Update `Task.quickCapture`, `Task.copyWith`, and domain invariant tests.
3. Add validation and normalization for blank notes, blank tags, duplicate tags,
   and safe payload limits.
4. Extend task document fields and `TaskDocumentMapping`.
5. Update document mapping, migration, and persistence field coverage tests.
6. Update repository conformance expectations so notes/tags round-trip through
   every adapter.
7. Add SQLite Drift task columns or a normalized tag table, depending on the
   chosen tag model.
8. Bump or migrate SQLite schema as required and add migration tests for old
   databases.
9. Regenerate Drift code.
10. Update SQLite application and repository task row mappers.
11. Extend quick-capture/create/update command surfaces if users can write notes
   or tags.
12. Update readable export/import behavior if these fields are part of user data
   portability.

## Current UI Plan 2 handling

For UI Plan 2, the Backlog board and drawer may display placeholder or derived
read-only tag text where useful, but Flutter must not pretend those values are
persisted editable task metadata. Editing controls should remain disabled,
hidden, or clearly non-editing until the future metadata feature lands.
