217 lines
8.9 KiB
Markdown
217 lines
8.9 KiB
Markdown
# 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:
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
- [x] Add `DONE_TAG` with the value `done`.
|
||
- [x] Add normalized `doneTag` fields to `KanbanConfig` and `MatrixConfig`.
|
||
- [x] Parse `done-tag` in both view blocks with a default of `done`.
|
||
- [x] Warn when `done-tag` and `in-progress-tag` are identical.
|
||
- [x] Add parser tests for defaults, custom tags, normalization, empty values,
|
||
unknown-option handling, and identical-tag warnings.
|
||
|
||
### Phase 2 — Shared completion model
|
||
|
||
- [x] Allow an ordinary `KanbanCard` to be completed from the configured tag.
|
||
- [x] Keep `isTodo: false`, `completedTime: 0`, and `isRecurring: false`.
|
||
- [x] Preserve native to-do completion regardless of `done-tag`.
|
||
- [x] Test ordinary-note, native-to-do, custom-tag, and both-tags precedence.
|
||
|
||
### Phase 3 — Kanban behavior
|
||
|
||
- [x] Bucket completed ordinary notes into Done before checking in-progress.
|
||
- [x] Keep all completed note cards regardless of `done-window`.
|
||
- [x] Preserve the existing to-do done-window behavior.
|
||
- [x] Sort completed notes and to-dos together with the configured Done sorter.
|
||
- [x] Cover single and SLICE10 notebook-grouped layouts with exact card totals.
|
||
|
||
### Phase 4 — Matrix behavior
|
||
|
||
- [x] Exclude completed ordinary notes before Skeleton/Eisenhower bucketing.
|
||
- [x] Prove `done` wins over in-progress, urgent, and important tags.
|
||
- [x] Preserve native completed-to-do exclusion.
|
||
- [x] Cover single and SLICE10 notebook-grouped layouts without double-counting.
|
||
|
||
### Phase 5 — Rendering and payload regression
|
||
|
||
- [x] Confirm completed note cards retain the 📄 glyph and completed styling.
|
||
- [x] Confirm no new payload branch is needed beyond the normalized card fields.
|
||
- [x] Confirm SLICE8 independent batching and SLICE10 grouped rendering remain
|
||
unchanged.
|
||
|
||
### Phase 6 — Documentation and automated verification
|
||
|
||
- [x] Document `done-tag`, precedence, note-only semantics, matrix exclusion,
|
||
and the done-window exception in README.md and SPEC.md.
|
||
- [x] Add an unreleased CHANGELOG entry.
|
||
- [x] Run focused parser/builder/kanban/matrix tests (103 passed).
|
||
- [x] Run the complete Jest suite (240 tests), TypeScript, JavaScript syntax, whitespace,
|
||
and prohibited-reference checks.
|
||
- [x] Build the production JPL.
|
||
|
||
### Phase 7 — Manual Joplin acceptance
|
||
|
||
- [x] Note with `done` only appears in Kanban Done.
|
||
- [x] Note with both `done` and `in-progress` appears only in Done.
|
||
- [x] Removing `done` returns the note to In Progress or Backlog as appropriate.
|
||
- [x] Custom `done-tag` works independently in kanban and matrix blocks.
|
||
- [x] Completed notes are excluded from both matrix modes.
|
||
- [x] Incomplete to-dos tagged `done` remain governed by native completion.
|
||
- [x] `done-window` filters native to-dos but not completed ordinary notes.
|
||
- [x] Glyph, styling, sorting, navigation, warnings, statistics, batching, and
|
||
child-notebook grouping do not regress.
|
||
- [x] 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.
|