joplin-plugin-gtd-calendar/SLICE11.md

SLICE 11 — Complete ordinary notes with a done tag

State-saving rule: update this file after every completed task and whenever work pauses. Keep automated validation and manual Joplin acceptance separate.

Status

COMPLETE. Phases 1–6 are implemented and fully validated. The user confirmed all Phase 7 manual Joplin acceptance tests pass on 2026-07-28. The production JPL is built and inspected.

Goal

Give ordinary notes containing a gtd block a natural completion state without turning them into native Joplin to-dos. Completion follows the same tag-driven progression already used by kanban:

no workflow tag -> Backlog
in-progress     -> In Progress
done            -> Done

If an ordinary note carries both in-progress and done, Done wins.

Confirmed behavior

• Only ordinary notes that already opt in through a found gtd block are affected. A done tag does not opt a plain note into a view.
• The default completion tag is done.
• For ordinary notes, done takes priority over in-progress during kanban bucketing.
• Existing native to-do completion remains authoritative for Joplin to-dos.
• The feature must preserve SLICE8 batching, SLICE9 mixed cards, and SLICE10 exact-owner notebook grouping.

Confirmed design decisions

1. Configuration

Recommendation: add done-tag: to both gtd-kanban and gtd-matrix, defaulting to done, just as in-progress-tag: defaults to in-progress. Normalize tag names case-insensitively.

Warn when done-tag and in-progress-tag are identical because the workflow would collapse directly to Done. Do not silently choose a different tag.

2. Which item types the tag affects

Recommendation: done-tag changes completion only for ordinary notes. Native to-dos continue to use todo_completed; an incomplete to-do tagged done remains incomplete. This avoids two competing completion authorities for Joplin to-dos.

3. Kanban done-window

Ordinary notes have no native completion timestamp. Their updated_time is not a reliable substitute because any later edit would make an old completion look recent.

Recommendation: completed ordinary notes are not filtered by done-window; all opted-in notes carrying done-tag appear in Done. done-window continues to apply only to native completed to-dos. Document this explicitly.

Alternative if an unbounded Done column is unacceptable: add a completion date to the gtd block in a later slice. Do not infer it from updated_time.

4. Matrix behavior

Recommendation: exclude done ordinary notes from both Skeleton and Eisenhower matrices, matching the existing exclusion of completed to-dos. A prioritization view should contain only unfinished work.

The exclusion happens before quadrant bucketing. Thus done also wins over in-progress, urgent, and important tags.

5. Calendar behavior

Recommendation for this slice: leave calendars unchanged. A completed ordinary note remains a scheduled/unscheduled calendar item and does not gain strikethrough solely from done-tag.

Calendar completion styling can be considered separately because calendars may serve as historical records, while kanban and matrix are workflow views.

6. Card representation and styling

Completed ordinary-note cards keep the 📄 fallback glyph and use the existing completed title styling in kanban Done. They do not use a checked-checkbox glyph and never become recurring.

The shared card model may represent completed: true with isTodo: false. completedTime remains 0 for notes because no completion timestamp exists.

7. Removing or changing tags

• Removing done from a note makes it unfinished again.
• If in-progress remains, the note returns to In Progress.
• If neither workflow tag remains, it returns to Backlog.
• No tag is automatically added or removed; the plugin remains read-only.

Precedence table

Item	Native completion	done tag	in-progress tag	Kanban result	Matrix result
Ordinary opted-in note	n/a	yes	either	Done	Excluded
Ordinary opted-in note	n/a	no	yes	In Progress	Existing mode rules
Ordinary opted-in note	n/a	no	no	Backlog	Existing mode rules
Ordinary note without gtd	n/a	any	any	Excluded	Excluded
Completed to-do	yes	any	any	Done, subject to done-window	Excluded
Incomplete to-do	no	yes	yes/no	Existing in-progress rule	Existing mode rules

Architecture

eligible note + normalized tag titles
        |
        v
buildKanbanCard
  to-do -> completion from todo_completed
  note   -> completion from configured done-tag
        |
        +-- kanban: completed wins -> Done
        |             note: no done-window filtering
        |             to-do: existing done-window filtering
        |
        +-- matrix: completed -> exclude before quadrant bucketing

Because done-tag is configurable per view, card construction may need either a completion-tag argument or a small view-specific completion step after the shared builder. Prefer one explicit data path shared by kanban and matrix; do not hide the configured tag in a global constant lookup.

Implementation plan

Phase 1 — Configuration and types

• Add DONE_TAG with the value done.
• Add normalized doneTag fields to KanbanConfig and MatrixConfig.
• Parse done-tag in both view blocks with a default of done.
• Warn when done-tag and in-progress-tag are identical.
• Add parser tests for defaults, custom tags, normalization, empty values, unknown-option handling, and identical-tag warnings.

Phase 2 — Shared completion model

• Allow an ordinary KanbanCard to be completed from the configured tag.
• Keep isTodo: false, completedTime: 0, and isRecurring: false.
• Preserve native to-do completion regardless of done-tag.
• Test ordinary-note, native-to-do, custom-tag, and both-tags precedence.

Phase 3 — Kanban behavior

• Bucket completed ordinary notes into Done before checking in-progress.
• Keep all completed note cards regardless of done-window.
• Preserve the existing to-do done-window behavior.
• Sort completed notes and to-dos together with the configured Done sorter.
• Cover single and SLICE10 notebook-grouped layouts with exact card totals.

Phase 4 — Matrix behavior

• Exclude completed ordinary notes before Skeleton/Eisenhower bucketing.
• Prove done wins over in-progress, urgent, and important tags.
• Preserve native completed-to-do exclusion.
• Cover single and SLICE10 notebook-grouped layouts without double-counting.

Phase 5 — Rendering and payload regression

• Confirm completed note cards retain the 📄 glyph and completed styling.
• Confirm no new payload branch is needed beyond the normalized card fields.
• Confirm SLICE8 independent batching and SLICE10 grouped rendering remain unchanged.

Phase 6 — Documentation and automated verification

• Document done-tag, precedence, note-only semantics, matrix exclusion, and the done-window exception in README.md and SPEC.md.
• Add an unreleased CHANGELOG entry.
• Run focused parser/builder/kanban/matrix tests (103 passed).
• Run the complete Jest suite (240 tests), TypeScript, JavaScript syntax, whitespace, and prohibited-reference checks.
• Build the production JPL.

Phase 7 — Manual Joplin acceptance

• Note with done only appears in Kanban Done.
• Note with both done and in-progress appears only in Done.
• Removing done returns the note to In Progress or Backlog as appropriate.
• Custom done-tag works independently in kanban and matrix blocks.
• Completed notes are excluded from both matrix modes.
• Incomplete to-dos tagged done remain governed by native completion.
• done-window filters native to-dos but not completed ordinary notes.
• Glyph, styling, sorting, navigation, warnings, statistics, batching, and child-notebook grouping do not regress.
• Record explicit user sign-off separately from automated checks.

Out of scope

• Mutating tags from a rendered card.
• Automatically removing in-progress when done is added.
• Inferring a completion time from updated_time.
• Adding a completion date to the gtd block.
• Changing calendar completion styling.
• Treating done as an opt-in for ordinary notes without a gtd block.

Acceptance criteria

• An opted-in ordinary note carrying the configured done tag is complete.
• Done wins over in-progress and every matrix axis tag.
• Native to-do completion behavior is unchanged.
• Done-window semantics are explicit and deterministic without fabricated dates.
• Single and grouped views retain correct ownership, totals, sorting, warnings, batching, styling, and navigation.
• Automated validation, production packaging, and explicit manual acceptance all pass and are recorded separately.