tasknotes-spec 0.2.0

package/00-overview.md

@@ -0,0 +1,172 @@
+# 0. Overview
+
+## 0.0 About tasknotes
+
+**TaskNotes** is an [Obsidian](https://obsidian.md) plugin that stores tasks as individual markdown files with YAML frontmatter in a user's vault. Each task is a first-class file: readable and editable with any text editor, version-controllable, and searchable without special tooling.
+
+A minimal task file looks like this:
+
+```markdown
+---
+title: Buy groceries
+status: open
+priority: normal
+due: 2026-02-21
+tags: [task]
+dateCreated: 2026-02-20T11:15:00Z
+dateModified: 2026-02-20T11:15:00Z
+---
+
+Buy fruit and cleaning supplies.
+```
+
+Tasks are identified within the vault by a configurable detection method — by default, by the presence of a specific tag (e.g. `#task` in body or frontmatter). The plugin stores its configuration in `.obsidian/plugins/tasknotes/data.json` within the vault root.
+
+**This specification** was derived from the behavior of the tasknotes plugin and is intended to serve as a stable, testable contract for:
+
+- CLI tools and scripts that process task files outside Obsidian,
+- any application that wants to interoperate with a tasknotes vault.
+
+The spec is deliberately language-agnostic. It does not require any particular runtime, and the executable conformance suite (in `conformance/`) can be driven by an adapter written in any language.
+
+The tasknotes plugin is the primary reference for how this spec was derived, but **the specification is normative** — where the spec and the plugin behavior differ, the spec defines the intended behavior. Known deviations are disclosed via conformance claims (§7.5).
+
+## 0.1 Status and authority
+
+This document is part of `tasknotes-spec` version `0.2.0-draft`.
+
+This specification is normative for implementations that claim conformance.
+No single implementation is normative; implementations are expected to conform to the specification.
+
+## 0.2 Motivation
+
+TaskNotes-style systems store tasks as markdown files with YAML frontmatter. This model has practical advantages:
+
+- Task records are plain files that can be inspected and edited without proprietary tooling.
+- Data remains portable across environments.
+- Files are suitable for version control and collaboration workflows.
+
+As soon as more than one tool reads and writes the same task files, implicit assumptions become an interoperability risk. In practice, these risks appear in three areas:
+
+1. Field semantics and naming drift.
+2. Date and timezone interpretation differences.
+3. Recurring-task state transitions that are handled differently by different clients.
+
+When these rules are not explicit, users can get inconsistent results from equivalent operations. A shared specification reduces that risk by making behavior testable and versioned.
+
+## 0.3 Objectives
+
+This specification defines a stable contract for:
+
+- Representing task records in markdown frontmatter.
+- Mapping storage keys to canonical semantic roles.
+- Defining effective collection configuration via provider model (for example `tasknotes.yaml` and/or TaskNotes `data.json`).
+- Interpreting date and datetime values consistently.
+- Applying recurrence, per-instance completion/skip behavior, and optional materialized occurrence notes.
+- Managing time tracking sessions and `time_entries` lifecycle behavior.
+- Parsing and resolving links consistently across task fields.
+- Defining dependency and reminder behavior.
+- Optionally applying deterministic create-time templating behavior.
+- Executing write operations with predictable side-effects.
+- Validating task records and reporting issues.
+
+## 0.4 Non-objectives
+
+This specification does not standardize:
+
+- UI layout, styling, command palettes, or interaction design.
+- Internal caching architecture or rendering pipelines.
+- Transport protocols (HTTP, IPC, etc.) except where they affect persisted task semantics.
+- Rich template-language features beyond the portable create-time templating contract in §5/§7/§9.
+
+## 0.5 Scope
+
+This specification is standalone. It does not require conformance to any other specification.
+
+Implementations MAY internally reuse other libraries or specifications, but conformance claims under `tasknotes-spec` are evaluated only against this document.
+Templating is optional and profile-gated; implementations that do not claim the templating profile remain conformant without template support.
+References to TaskNotes plugin behavior, Obsidian behavior, or external specifications are informative context only unless this specification explicitly marks a requirement as normative.
+
+## 0.6 Design principles
+
+### 0.6.1 File-first persistence
+
+Task state is represented in user-visible files. Derived indexes and caches are non-canonical.
+
+### 0.6.2 Deterministic semantics
+
+Equivalent inputs MUST produce equivalent persisted outputs under the same configuration and active runtime timezone.
+
+### 0.6.3 Explicit mapping
+
+Semantic roles are canonical. Storage key names are configurable and therefore must be mapped explicitly.
+
+### 0.6.4 Backward evolution
+
+The specification supports migration from legacy keys and historical behaviors through explicit compatibility rules.
+
+## 0.7 Conformance
+
+Conformance is profile-based (see §7). A minimal implementation can conform to a narrow profile while remaining interoperable for core operations.
+
+## 0.8 Normative language
+
+The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as described in RFC 2119.
+
+## 0.9 Example collection
+
+A default tasknotes vault looks like this:
+
+```text
+MyVault/
+├── TaskNotes/
+│   ├── Tasks/
+│   │   ├── buy-groceries.md    ← task file (title-derived filename by default)
+│   │   └── weekly-review.md
+│   └── Archive/                ← archive folder (if moveArchivedTasks=true)
+├── .obsidian/
+│   └── plugins/
+│       └── tasknotes/
+│           └── data.json       ← plugin settings (primary config provider)
+└── tasknotes.yaml              ← optional spec-level config (secondary provider)
+```
+
+Task files are identified by the `#task` tag by default (configurable). The full default collection state is described in §9.21.
+
+Configuration provider semantics and effective configuration rules are defined in §9. An implementation MAY use either provider, both, or additional providers, based on its documented precedence policy.
+
+A task file example (using default field mapping):
+
+```markdown
+---
+title: Buy groceries
+status: open
+priority: normal
+due: 2026-02-21
+tags: [task, errands]
+contexts: ["town"]
+dateCreated: 2026-02-20T11:15:00Z
+dateModified: 2026-02-20T11:15:00Z
+---
+
+Buy fruit and cleaning supplies.
+```
+
+## 0.10 Versioning policy
+
+This specification uses semantic versioning.
+
+- A **major** version introduces breaking semantic changes.
+- A **minor** version introduces additive behavior or optional features.
+- A **patch** version clarifies wording or fixes non-breaking defects.
+
+Implementations MUST reject unsupported major versions when strict mode is enabled.
+
+## 0.11 Change governance
+
+Specification changes SHOULD be accompanied by:
+
+- a motivation statement,
+- precise normative edits,
+- migration notes when behavior changes,
+- updated examples.

package/01-terminology.md

@@ -0,0 +1,156 @@
+# 1. Terminology
+
+This section defines terms used normatively in this specification.
+
+## 1.1 Collection
+
+A **collection** is a filesystem scope within which task files are discovered and managed under a single TaskNotes configuration.
+
+## 1.2 Task file
+
+A **task file** is a markdown file identified as a task record by collection rules.
+
+## 1.3 Frontmatter
+
+**Frontmatter** is the YAML block at the start of a markdown file delimited by `---` markers.
+
+## 1.4 Task record
+
+A **task record** is the semantic task object obtained from parsing a task file frontmatter (plus optional derived metadata).
+
+## 1.5 Semantic role
+
+A **semantic role** is a canonical meaning defined by this specification, independent of storage key names.
+
+Examples: `title`, `status`, `date_created`, `complete_instances`.
+
+## 1.6 Storage key
+
+A **storage key** is the YAML property name used in frontmatter.
+
+Examples: `dateCreated`, `date_created`, `completedDate`.
+
+## 1.7 Field mapping
+
+**Field mapping** is the configuration that maps semantic roles to storage keys for reads and writes.
+
+## 1.8 Alias
+
+An **alias** is a non-canonical storage key accepted for compatibility during reads.
+
+## 1.9 Canonical write key
+
+The **canonical write key** is the configured storage key that conforming writers use for persisted output.
+
+## 1.10 Date value
+
+A **date value** represents a calendar day with no time-of-day and no timezone.
+
+Canonical form: `YYYY-MM-DD`.
+
+## 1.11 Datetime value
+
+A **datetime value** represents an instant in time.
+
+Canonical form: ISO 8601 UTC with trailing `Z`.
+
+## 1.12 Target date
+
+A **target date** is the calendar date to which a recurrence instance operation applies (for example complete instance on 2026-02-20).
+
+## 1.13 Recurrence rule
+
+A **recurrence rule** is a tasknotes recurrence string stored in the recurrence semantic role.
+It uses RFC 5545 RRULE-style parameters inside a single semicolon-delimited field value and MAY include an explicit inline `DTSTART` prefix segment as defined in §4.3.
+
+## 1.14 Recurrence anchor
+
+**Recurrence anchor** defines how next-instance progression is computed. Allowed values:
+
+- `scheduled`
+- `completion`
+
+## 1.15 Complete instances
+
+**Complete instances** is the set/list of target dates marked completed for a recurring task.
+
+## 1.16 Skipped instances
+
+**Skipped instances** is the set/list of target dates marked skipped for a recurring task.
+
+## 1.17 Materialized occurrence note
+
+A **materialized occurrence note** is a task file created for one target date of a recurring parent task.
+It stores user-authored per-occurrence content and, when supported by the implementation, owns the authoritative task state for that occurrence date.
+
+## 1.18 Recurrence parent
+
+A **recurrence parent** is the recurring task record referenced by a materialized occurrence note.
+The reference is stored in semantic role `recurrence_parent` and resolved as a link according to §11.
+
+## 1.19 Occurrence materialization
+
+**Occurrence materialization** is the creation and reconciliation of materialized occurrence notes from a recurring parent task according to §4.18 and §5.20.
+
+## 1.20 Effective status
+
+**Effective status** is the status presented for a given date context after applying recurrence instance state.
+
+## 1.21 Completed-status list
+
+The **completed-status list** is the configured ordered list of status values treated as completed for non-recurring completion semantics.
+When a single value must be chosen deterministically, the first list entry is used unless explicit operation input overrides it.
+
+## 1.22 Idempotent operation
+
+An operation is **idempotent** if applying it multiple times with the same input produces the same persisted state as applying it once.
+
+## 1.23 Unknown field
+
+An **unknown field** is a frontmatter property not mapped to a semantic role in current configuration.
+
+## 1.24 Validation issue
+
+A **validation issue** is a structured report containing at least:
+
+- machine-readable code,
+- severity,
+- optional path/field context,
+- human-readable message.
+
+## 1.25 Strict validation mode
+
+**Strict validation mode** is a mode where invalid required semantics are treated as hard errors and write operations fail.
+
+## 1.26 Legacy compatibility mode
+
+**Legacy compatibility mode** is a mode where specific historical behaviors or aliases are accepted for migration but are not canonical for new writes.
+
+## 1.27 Configuration provider
+
+A **configuration provider** is an adapter that loads configuration from a source (for example `tasknotes.yaml` or `.obsidian/plugins/tasknotes/data.json`) and normalizes it to the schema in §9.
+
+## 1.28 Effective configuration
+
+The **effective configuration** is the final resolved configuration after applying provider precedence and fallback rules.
+
+## 1.29 Template file
+
+A **template file** is a markdown document used at create time to generate frontmatter and/or body content through variable expansion.
+When templating is enabled, template behavior is defined by §5.3.5 and §9.14.
+
+## 1.30 Template expansion
+
+**Template expansion** is deterministic replacement of template variables with create-time task data and runtime date/time values, followed by template merge rules.
+
+## 1.31 Time entry
+
+A **time entry** is a structured record in `time_entries` containing `startTime`, optional `endTime`, and optional `description`.
+
+## 1.32 Active time entry
+
+An **active time entry** is a time entry with `startTime` present and `endTime` absent.
+
+## 1.33 Time tracking management
+
+**Time tracking management** is the set of operations that start, stop, edit, and remove `time_entries`, including completion-triggered auto-stop behavior when configured.

package/02-model-and-mapping.md

@@ -0,0 +1,288 @@
+# 2. Model and Field Mapping
+
+## 2.1 Task record model
+
+A task record consists of:
+
+- frontmatter object (structured fields),
+- markdown body (freeform text),
+- file metadata (path, created/modified time) where available.
+
+Frontmatter is normative for task semantics. Body content is non-normative except where an implementation exposes body search or body-derived features.
+
+## 2.2 Required semantic roles
+
+Conforming implementations MUST support these semantic roles:
+
+| Semantic role | Type | Required |
+|---|---|---|
+| `title` | string | support required (value required via configured title source, see §2.2.2) |
+| `status` | string/enum | yes |
+| `completed_date` | date | support required (conditionally required, see §2.2.1) |
+| `date_created` | datetime | yes |
+| `date_modified` | datetime | yes |
+
+If storage omits a role marked `yes`, validation MUST report an error (see §6).
+For operation-required roles, validation and operation rules in §5 and §6 apply.
+
+### 2.2.1 Conditional requiredness (`completed_date`)
+
+`completed_date` support is mandatory, but presence is conditional:
+
+- For non-recurring tasks with `status` in configured `status.completed_values`, `completed_date` MUST be present.
+- For non-recurring tasks with non-completed status, `completed_date` MAY be absent.
+- For recurring tasks, `completed_date` is not required by recurrence completion semantics and MAY be absent.
+
+Validators MUST apply this conditional rule and MUST NOT treat `completed_date` as unconditionally required.
+
+### 2.2.2 Conditional requiredness (`title`)
+
+Semantic `title` is always required, with deterministic read resolution and storage-mode-dependent read/write behavior:
+
+- Readers MUST resolve semantic title using storage-mode-aware precedence (§9.13):
+  1. when `title.storage=frontmatter`: mapped `title` key when present and non-empty, then file basename fallback;
+  2. when `title.storage=filename`: file basename first, then mapped `title` fallback when basename is unavailable.
+- If mapped title and filename-derived title both exist and differ, the source authoritative for active `title.storage` MUST win and implementations SHOULD emit `title_source_conflict`.
+- When `title.storage=filename`, implementations MAY keep mapped `title` as a synchronized compatibility mirror, but filename-derived title remains authoritative.
+- Title storage mode controls canonical writes (§9.13): `frontmatter` favors mapped-key writes; `filename` favors filename-derived title with rename-on-title-change behavior.
+
+Validators MUST enforce semantic title presence using the active title-resolution policy (§9.13), not frontmatter key presence alone.
+
+## 2.3 Common semantic roles
+
+Implementations conforming beyond minimal scope SHOULD support:
+
+| Semantic role | Type | Notes |
+|---|---|---|
+| `id` | string | stable task identity token; see §2.6.5 |
+| `priority` | string/enum | configurable values |
+| `due` | date or datetime | see §3 |
+| `scheduled` | date or datetime | see §3 |
+| `tags` | list<string> | free tags |
+| `contexts` | list<string> | commonly prefixed with `@` |
+| `projects` | list<link-or-string> | project references, see §11 |
+| `time_estimate` | integer >= 0 | minutes |
+| `time_entries` | list<object> | see §2.6 |
+| `recurrence` | string | tasknotes recurrence string; see §4 |
+| `recurrence_anchor` | enum | `scheduled` or `completion` |
+| `complete_instances` | list<date> | recurring completion state |
+| `skipped_instances` | list<date> | recurring skip state |
+| `recurrence_parent` | link-or-string | parent recurring task reference for materialized occurrence notes; see §4.18 |
+| `occurrence_date` | date | target date represented by a materialized occurrence note |
+| `occurrence_materialization` | enum | parent task materialization mode: `manual`, `on_completion`, or `rolling` |
+| `occurrence_next_trigger` | enum | parent task next-note trigger: `completion` or `completion_or_skip` |
+| `occurrence_template` | link-or-string | optional template used when creating materialized occurrence notes |
+| `occurrence_past_horizon` | duration | optional rolling materialization lookbehind bound |
+| `occurrence_future_horizon` | duration | optional rolling materialization lookahead bound |
+| `blocked_by` | list<object> | dependency records, see §10 and §11 |
+| `reminders` | list<object> | reminder records, see §10 |
+
+Optional extended roles are defined in §7 profiles.
+
+## 2.4 Field mapping requirements
+
+### 2.4.1 Mapping presence
+
+An implementation MUST have an effective mapping from each supported semantic role to a canonical write key.
+Mapping configuration is defined in §9.
+If semantic role `id` is supported, it MUST also have a canonical write key.
+
+### 2.4.2 Read behavior
+
+Readers MUST:
+
+1. Read the canonical mapped key if present.
+2. Support configured aliases where enabled.
+3. Resolve conflicts deterministically when canonical and alias keys coexist.
+4. When canonical and alias keys both exist for the same semantic role, canonical key value MUST win.
+5. When canonical key wins over alias, validator/loader SHOULD emit warning `alias_conflict_ignored`.
+
+### 2.4.3 Write behavior
+
+Writers MUST:
+
+- write only canonical keys,
+- avoid introducing alias keys in new writes,
+- preserve unknown fields unless the operation explicitly opts into normalization.
+
+## 2.5 Legacy alias compatibility
+
+Implementations SHOULD accept these aliases on read for interoperability:
+
+| Semantic role | Canonical example | Alias examples |
+|---|---|---|
+| `recurrence_anchor` | `recurrence_anchor` | `recurrenceAnchor` |
+| `complete_instances` | `complete_instances` | `completeInstances` |
+| `skipped_instances` | `skipped_instances` | `skippedInstances` |
+| `recurrence_parent` | `recurrence_parent` | `recurrenceParent` |
+| `occurrence_date` | `occurrence_date` | `occurrenceDate` |
+| `occurrence_materialization` | `occurrence_materialization` | `occurrenceMaterialization` |
+| `occurrence_next_trigger` | `occurrence_next_trigger` | `occurrenceNextTrigger` |
+| `occurrence_template` | `occurrence_template` | `occurrenceTemplate` |
+| `occurrence_past_horizon` | `occurrence_past_horizon` | `occurrencePastHorizon` |
+| `occurrence_future_horizon` | `occurrence_future_horizon` | `occurrenceFutureHorizon` |
+| `date_created` | `dateCreated` | `date_created` |
+| `date_modified` | `dateModified` | `date_modified` |
+| `completed_date` | `completedDate` | `completed_date` |
+| `time_entries` | `timeEntries` | `time_entries` |
+| `time_estimate` | `timeEstimate` | `time_estimate` |
+| `blocked_by` | `blockedBy` | `blocked_by` |
+
+This table is compatibility guidance, not a requirement to choose camelCase or snake_case as canonical.
+
+## 2.6 Structured role schemas
+
+### 2.6.1 time_entries
+
+`time_entries` items MUST be objects with:
+
+- `startTime` datetime (required)
+- `endTime` datetime (optional)
+- `description` string (optional)
+
+Additional constraints:
+
+- a task MUST NOT contain more than one active time entry (entry with `startTime` and no `endTime`) at commit time.
+- an entry with missing `endTime` is interpreted as an active/running session.
+- an implementation MAY accept `duration` on read for backward compatibility, but canonical duration is derived from start/end and SHOULD NOT be persisted on canonical writes.
+
+Nested key names in `time_entries` are fixed by this specification and are not independently configurable in `mapping`.
+
+### 2.6.2 projects
+
+`projects` SHOULD be represented as links when link semantics are supported, but plain strings MAY be accepted.
+When interpreted as links, parsing and resolution MUST follow §11.
+
+### 2.6.3 blocked_by
+
+`blocked_by` items MUST be objects with:
+
+- `uid` link-or-string task reference (required)
+- `reltype` enum (required; default allowed by §10 when omitted)
+- `gap` ISO 8601 duration string (optional)
+
+Detailed semantics are defined in §10. `uid` parsing and resolution MUST follow §11.
+
+### 2.6.4 reminders
+
+`reminders` items MUST be objects with:
+
+- `id` string (required)
+- `type` enum `absolute|relative` (required)
+- relative-only fields: `relatedTo`, `offset`
+- absolute-only fields: `absoluteTime`
+- `description` string (optional)
+
+Detailed semantics are defined in §10.
+
+### 2.6.5 id (stable task identity)
+
+When semantic role `id` is present:
+
+- value MUST be a non-empty string.
+- value MUST be treated as stable identity metadata and MUST NOT be rewritten by rename, move, or title-change operations.
+- readers and link resolution MAY use it as an identity lookup key (see §11.4 Step 3).
+- implementations SHOULD keep `id` unique within a collection; duplicate IDs SHOULD produce a validation issue.
+
+### 2.6.6 Materialized occurrence roles
+
+The roles in this subsection are required only for implementations claiming profile `materialized-occurrences` (§7.3.4).
+
+Parent recurring task roles:
+
+- `occurrence_materialization`: enum `manual|on_completion|rolling`; controls when occurrence notes are created (§4.18.5).
+- `occurrence_next_trigger`: enum `completion|completion_or_skip`; controls whether skip/cancel transitions advance creation of the next occurrence note (§4.18.6).
+- `occurrence_template`: link-or-string reference to a template file used when creating occurrence notes. Link parsing/resolution follows §11 when supported.
+- `occurrence_past_horizon` and `occurrence_future_horizon`: ISO 8601 durations used by rolling materialization (§4.18.7).
+
+Materialized occurrence note roles:
+
+- `recurrence_parent`: link-or-string reference to the parent recurring task. Wikilinks are the default interoperable representation in Obsidian-oriented collections.
+- `occurrence_date`: date value identifying the target date this occurrence note represents.
+
+Implementations claiming `materialized-occurrences` MUST treat `recurrence_parent` and `occurrence_date` together as the occurrence identity key.
+Within a resolved parent task, at most one materialized occurrence note SHOULD exist for each `occurrence_date`; duplicate notes MUST be reported when detected (§6.4).
+
+Materialized occurrence notes MAY also use normal task roles such as `status`, `completed_date`, `scheduled`, `due`, `time_entries`, `reminders`, `contexts`, `projects`, and body content.
+For dates where a materialized occurrence note exists, its own task state is authoritative as defined in §4.18.3.
+
+## 2.7 Unknown fields
+
+Unknown frontmatter keys MUST be preserved by default during updates, complete/uncomplete, skip/unskip, dependency mutations, reminder mutations, and archive operations.
+
+Unknown fields MAY be removed only when:
+
+- explicit normalization/migration is requested, or
+- strict schema replacement is explicitly requested.
+
+## 2.8 Example mapping
+
+Example effective mapping:
+
+```yaml
+mapping:
+  id: id
+  title: title
+  status: status
+  date_created: dateCreated
+  date_modified: dateModified
+  completed_date: completedDate
+  recurrence: recurrence
+  recurrence_anchor: recurrence_anchor
+  complete_instances: complete_instances
+  skipped_instances: skipped_instances
+  recurrence_parent: recurrence_parent
+  occurrence_date: occurrence_date
+  occurrence_materialization: occurrence_materialization
+  occurrence_next_trigger: occurrence_next_trigger
+  occurrence_template: occurrence_template
+  occurrence_past_horizon: occurrence_past_horizon
+  occurrence_future_horizon: occurrence_future_horizon
+  time_estimate: timeEstimate
+  time_entries: timeEntries
+  blocked_by: blockedBy
+  reminders: reminders
+```
+
+## 2.9 Example task record
+
+```markdown
+---
+id: task-2026-01-10-weekly-review
+title: Weekly review
+status: open
+priority: high
+scheduled: 2026-02-20
+recurrence: FREQ=WEEKLY;BYDAY=FR
+recurrence_anchor: scheduled
+complete_instances: [2026-02-13]
+skipped_instances: []
+blockedBy:
+  - uid: "[[prepare-metrics]]"
+    reltype: FINISHTOSTART
+    gap: P1D
+reminders:
+  - id: rem_day_before
+    type: relative
+    relatedTo: due
+    offset: -P1D
+  - id: rem_start
+    type: absolute
+    absoluteTime: 2026-02-20T09:00:00Z
+dateCreated: 2026-01-10T09:30:00Z
+dateModified: 2026-02-20T08:02:11Z
+---
+
+Review completed work and plan next week.
+```
+
+## 2.10 Deterministic load example
+
+Given frontmatter:
+
+```yaml
+recurrence_anchor: scheduled
+recurrenceAnchor: completion
+```
+
+If canonical key is `recurrence_anchor`, a conforming loader using canonical-precedence policy MUST resolve semantic `recurrence_anchor` as `scheduled` and SHOULD emit a compatibility warning.