# 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.