tasknotes-spec 0.2.0

package/10-dependencies-and-reminders.md

@@ -0,0 +1,266 @@
+# 10. Dependencies and Reminders
+
+## 10.1 Purpose
+
+This section defines canonical semantics for task dependencies (`blocked_by`) and task reminders (`reminders`).
+
+## 10.2 Dependencies (`blocked_by`)
+
+### 10.2.1 Data shape
+
+`blocked_by` MUST be a list of dependency entries.
+
+Each entry MUST be an object with:
+
+- `uid` (required): reference to a blocking task (link or string)
+- `reltype` (required): one of
+  - `FINISHTOSTART`
+  - `STARTTOSTART`
+  - `FINISHTOFINISH`
+  - `STARTTOFINISH`
+- `gap` (optional): ISO 8601 duration string
+
+If `reltype` is omitted on read in compatibility mode, implementations MAY treat it as `FINISHTOSTART` and SHOULD emit a warning.
+
+### 10.2.2 UID normalization
+
+Implementations SHOULD normalize `uid` values to a canonical reference representation on write.
+
+If link formats are supported, both wikilink and markdown-link forms MAY be read. Canonical write form MUST be documented.
+Link parsing and resolution MUST follow §11.
+
+### 10.2.3 Dependency uniqueness
+
+Within a task, dependency entries are keyed by normalized `uid`.
+
+Policy is configuration-driven and MUST be deterministic:
+
+- when `dependencies.enforce_unique_uid=true` (default), duplicate normalized `uid` values MUST NOT be accepted as canonical persisted state:
+  - strict mode: duplicates MUST fail validation/write with `duplicate_dependency_uid`;
+  - permissive mode: implementations MAY either fail or normalize to one entry, but MUST emit `duplicate_dependency_uid`.
+- when `dependencies.enforce_unique_uid=false`, duplicates MAY be preserved as compatibility behavior.
+
+The active policy MUST be documented in conformance claims.
+
+### 10.2.4 Self-dependency
+
+A task MUST NOT depend on itself.
+
+Self-dependency is a validation error.
+
+### 10.2.5 Blocking semantics (v0.1)
+
+For v0.1, blocking evaluation MUST be status-presence based:
+
+1. A task is blocked if it has at least one unresolved dependency.
+2. A dependency on a resolvable task is unresolved when the referenced task is not in a completed status.
+3. Completed status MUST be determined from configured `status.completed_values`.
+4. For recurring referenced tasks in v0.1, unresolved/resolved evaluation MUST use base `status` only; `complete_instances`/`skipped_instances` are not consulted.
+5. When a referenced task is missing/unresolvable, whether that missing target contributes to blocked-state evaluation MUST follow `dependencies.treat_missing_target_as_blocked` (§9.11, default `true`).
+
+For v0.1, `reltype` and `gap` are preserved and validated but MUST NOT change the unresolved/resolved decision.
+
+### 10.2.6 Missing referenced task
+
+When `uid` cannot be resolved:
+
+- implementations SHOULD emit `unresolved_dependency_target`.
+- blocked-state contribution for this missing target MUST follow `dependencies.treat_missing_target_as_blocked` (§9.11).
+- issue severity SHOULD follow `dependencies.unresolved_target_severity` (default: `warning`).
+- for `blocked_by.uid`, this dependency-specific severity policy MUST take precedence over `links.unresolved_default_severity`.
+- parse failures that produce `invalid_link_format` and containment violations that produce `path_traversal` remain error-severity conditions from §11.
+- if `dependencies.require_resolved_uid_on_write=true`, add/update MUST fail with error.
+
+### 10.2.7 Cycles
+
+Implementations MUST reject direct self-cycles.
+
+Detection of multi-hop dependency cycles is RECOMMENDED but not required for `core-lite` or `recurrence` profiles.
+
+### 10.2.8 Reverse relation field
+
+Some implementations maintain reverse relationships (for example `blocking`). Such fields are derived and non-canonical in this spec unless explicitly mapped.
+
+If maintained, reverse updates SHOULD remain consistent with `blocked_by` edits.
+
+### 10.2.9 Dependency operation semantics
+
+#### Add dependency
+
+Add dependency MUST:
+
+- validate entry shape,
+- handle duplicates by policy (preserve, normalize, or reject),
+- preserve unrelated dependency entries,
+- update `date_modified` on change.
+
+#### Remove dependency
+
+Remove dependency MUST remove by normalized `uid` and be idempotent.
+
+#### Replace dependencies
+
+Replace behavior MUST be explicit operation mode (not default for patch update).
+
+### 10.2.10 Dependency examples
+
+Example entry:
+
+```yaml
+blockedBy:
+  - uid: "[[prepare-metrics]]"
+    reltype: FINISHTOSTART
+    gap: PT4H
+```
+
+Example unresolved dependency (target missing):
+
+```yaml
+blockedBy:
+  - uid: "[[non-existent-task]]"
+    reltype: FINISHTOSTART
+```
+
+## 10.3 Reminders (`reminders`)
+
+### 10.3.1 Data shape
+
+`reminders` MUST be a list of reminder entries.
+
+Each reminder MUST include:
+
+- `id` (required): unique string within the task
+- `type` (required): `absolute` or `relative`
+
+Optional field:
+
+- `description` string
+
+Type-specific fields:
+
+- `absolute`: requires `absoluteTime` datetime
+- `relative`: requires `relatedTo` (`due` or `scheduled`) and `offset` (ISO 8601 duration)
+
+### 10.3.2 Reminder uniqueness
+
+Reminder `id` values MUST be unique within the task.
+
+If duplicates occur:
+
+- strict mode: MUST raise `duplicate_reminder_id`.
+- permissive mode: MAY normalize deterministically and emit warning.
+
+### 10.3.3 Relative reminder base
+
+`relatedTo` MUST reference semantic role `due` or `scheduled`.
+
+If the referenced role is absent, the reminder is unresolved.
+
+### 10.3.4 Trigger instant computation
+
+Trigger instant MUST be computed as follows:
+
+1. If `type=absolute`, trigger = `absoluteTime` instant.
+2. If `type=relative`,
+   - resolve base field from `relatedTo`,
+   - if base is datetime: use that instant,
+   - if base is date: convert to local datetime at configured `reminders.date_only_anchor_time`,
+   - trigger = base + `offset`.
+
+If `reminders.date_only_anchor_time` is not configured, implementations MUST use `00:00` local time.
+
+### 10.3.5 Offset semantics
+
+`offset` MUST be a valid ISO 8601 duration with optional sign.
+
+- negative offset = before base
+- positive offset = after base
+- zero offset = at base instant
+
+### 10.3.6 Invalid mixed fields
+
+Entries with incompatible field combinations MUST fail validation in strict mode.
+
+Examples:
+
+- `type=absolute` with `relatedTo` and no `absoluteTime`
+- `type=relative` with `absoluteTime` and missing `offset`
+
+### 10.3.7 Reminder ordering
+
+When computing reminder schedules, implementations MUST sort by trigger instant ascending.
+
+For identical trigger instants, implementations MUST use stable tie-break ordering by `id` ascending.
+
+### 10.3.8 Reminder operation semantics
+
+#### Add reminder
+
+Add reminder MUST validate shape and unique `id`, then update `date_modified`.
+
+If `id` is omitted by caller and implementation supports auto-ID generation, generated IDs MUST be unique within the task.
+
+#### Update reminder
+
+Update reminder MUST address reminders by `id` and be patch-by-default.
+
+#### Remove reminder
+
+Remove reminder by `id` MUST be idempotent.
+
+### 10.3.9 Default reminders
+
+If `defaults.reminders` is configured (see §9):
+
+- create without explicit reminders MUST apply defaults.
+- create with explicit reminders MUST follow `reminders.apply_defaults_when_explicit` (§9.15):
+  - `false` (default): explicit reminders replace defaults.
+  - `true`: explicit reminders are merged with defaults.
+
+Deterministic merge rules when `apply_defaults_when_explicit=true`:
+
+1. Start with explicit reminders in caller order.
+2. Append each default reminder whose `id` is not already present.
+3. If explicit and default reminders share an `id`, explicit reminder MUST win.
+
+### 10.3.10 Reminder examples
+
+Relative reminder:
+
+```yaml
+reminders:
+  - id: due_minus_15m
+    type: relative
+    relatedTo: due
+    offset: -PT15M
+```
+
+Absolute reminder:
+
+```yaml
+reminders:
+  - id: call_now
+    type: absolute
+    absoluteTime: 2026-02-20T09:00:00Z
+```
+
+### 10.3.11 Reminder resolution error handling
+
+If relative reminder base is unavailable (`relatedTo=due` but no `due` field):
+
+- strict mode: validation error `unresolvable_reminder_base`.
+- permissive mode: warning and reminder excluded from trigger computation.
+
+## 10.4 Interactions
+
+### 10.4.1 Rename interaction
+
+If implementation supports rename/reference updates, dependency `uid` references SHOULD be updated consistently with other link references.
+
+### 10.4.2 Completion interaction
+
+Changing task completion state does not automatically remove dependencies or reminders unless explicitly configured.
+
+### 10.4.3 Archive interaction
+
+Archive operations MAY suppress reminder delivery in runtime systems, but archive MUST NOT silently delete reminder records from persisted frontmatter unless explicitly requested.

package/11-links.md

@@ -0,0 +1,373 @@
+# 11. Links
+
+## 11.1 Purpose
+
+This section defines link syntax, parsing, resolution, and write-format semantics for link-bearing task fields — primarily `projects` and `blocked_by.uid`.
+Alignment with Obsidian and other ecosystems is informative context only; normative conformance is defined entirely by this section.
+
+Applicability:
+
+- Implementations claiming profile `extended` (§7.3.5) MUST conform to this section for supported link-bearing roles.
+- Implementations claiming profile `materialized-occurrences` (§7.3.4) MUST conform to this section for `recurrence_parent` links, but are not required to support unrelated extended link-bearing roles solely because of that profile.
+- Implementations that claim neither `extended` nor `materialized-occurrences` MAY treat link-shaped strings as opaque data and are not required to implement §11 behavior.
+
+---
+
+## 11.2 Link formats
+
+Implementations that conform to §11 (see §11.1 applicability) MUST support three link formats.
+
+### 11.2.1 Wikilinks
+
+```
+[[target]]
+[[target|alias]]
+[[target#anchor]]
+[[target#anchor|alias]]
+[[folder/target]]
+[[./relative]]
+[[../parent/target]]
+```
+
+**Components:**
+- **target**: The file being linked to (without extension by default)
+- **alias**: Display text; does not affect resolution
+- **anchor**: A heading or block reference within the target
+- **path**: May be absolute (from collection root) or relative (from current file)
+
+Examples in frontmatter:
+
+```yaml
+projects:
+  - "[[home-project]]"
+  - "[[projects/alpha|Alpha Project]]"
+blockedBy:
+  - uid: "[[prepare-metrics]]"
+    reltype: FINISHTOSTART
+```
+
+### 11.2.2 Markdown links
+
+```
+[text](path.md)
+[text](./relative.md)
+[text](../other/file.md)
+[text](path.md#anchor)
+```
+
+The text portion is treated as an alias and does not affect resolution.
+
+Markdown links in frontmatter require the `obsidian-frontmatter-markdown-links` Obsidian plugin. Implementations MUST NOT write markdown-format links by default unless `links.use_markdown_format=true` is configured (§11.7).
+
+### 11.2.3 Bare paths
+
+```
+./sibling.md
+../other/file.md
+folder/file.md
+```
+
+Bare paths follow the same resolution rules as markdown links (relative to containing file's directory unless starting with `/`).
+
+---
+
+## 11.3 Link parsing
+
+When a link value is read, implementations MUST parse it into a structured representation:
+
+| Component | Type | Description |
+|---|---|---|
+| `raw` | string | Original string value exactly as written |
+| `target` | string | File path or identifier (without anchor or alias) |
+| `alias` | string? | Display text if provided, otherwise null |
+| `anchor` | string? | Heading or block reference if provided, otherwise null |
+| `format` | enum | One of: `wikilink`, `markdown`, `path` |
+| `is_relative` | boolean | Whether target begins with `./` or `../` |
+
+Parsing examples:
+
+| Input | target | alias | anchor | format | is_relative |
+|---|---|---|---|---|---|
+| `[[task-001]]` | `task-001` | null | null | wikilink | false |
+| `[[task-001\|My Task]]` | `task-001` | `My Task` | null | wikilink | false |
+| `[[docs/api#auth]]` | `docs/api` | null | `auth` | wikilink | false |
+| `[[./sibling]]` | `./sibling` | null | null | wikilink | true |
+| `[Link](file.md)` | `file.md` | `Link` | null | markdown | false |
+| `./other.md` | `./other.md` | null | null | path | true |
+
+---
+
+## 11.4 Resolution algorithm
+
+Resolution transforms a parsed link into an absolute path (relative to collection root) pointing to the target file.
+
+Given a parsed link and the path of the source file containing it:
+
+### Step 1: Parse the link into components (target, format, is_relative)
+
+### Step 2: Route by format
+
+**If format is `markdown` or `path`:**
+- If target starts with `/`, resolve from collection root (strip the leading `/`)
+- Otherwise, resolve relative to the source file's directory (standard markdown behavior)
+- Example: link `[Docs](docs/api.md)` in `notes/meeting.md` resolves to `notes/docs/api.md`
+
+**If format is `wikilink`:**
+- If target starts with `./` or `../`, resolve relative to the source file's directory
+- If target starts with `/`, resolve from collection root (strip the leading `/`)
+- If target contains `/` (and is not relative), resolve from collection root
+  - Example: `[[docs/api]]` resolves to `docs/api`
+- If simple name (no `/`, no `./` or `../`): proceed to Step 3
+
+### Step 3: Simple-name resolution (wikilinks only)
+
+For simple wikilink names (no path separator):
+
+1. **Define the search scope:**
+   - For `blocked_by.uid`: scope to files matching `task_detection` (task files only)
+   - For `projects`: scope to all markdown files in the collection unless narrowed by explicit configuration
+
+2. **ID match pass:** search scoped files for semantic role `id` (§2.6.5) equal to the name.
+   - Implementations MAY treat literal frontmatter key `id` as compatibility input when semantic mapping for `id` is unavailable.
+   - Equality MUST be exact string equality.
+   - If exactly one match: resolve to that file
+   - If multiple matches: fail with `ambiguous_link`
+
+3. **Filename match pass:** if no ID match, search scoped markdown files by filename (without extension).
+4. Implementations MUST deduplicate normalized candidate paths before final selection.
+5. If exactly one filename candidate remains after normalization and extension handling, resolve to that file.
+6. If multiple filename candidates remain, resolve to `null` and emit `ambiguous_link`. Callers SHOULD use a path-qualified or relative target to disambiguate.
+
+### Step 4: Extension handling
+
+If the target has no extension, implementations SHOULD try configured extensions in order.
+
+Default extension order: `[".md"]`.
+
+Example: `[[readme]]` tries `readme.md`, `readme.mdx`, etc.
+
+### Step 5: Path traversal check
+
+After resolution and normalization, if the resolved path would escape the collection root, abort with `path_traversal`. See §11.5.
+
+### Step 6: Return result
+
+- The normalized collection-relative path if found
+- `null` if no matching file exists
+
+### Resolution examples
+
+Given collection structure:
+```
+/
+├── TaskNotes/
+│   ├── Tasks/
+│   │   ├── task-001.md
+│   │   └── subtasks/
+│   │       └── task-002.md
+├── notes/
+│   └── meeting.md
+└── projects/
+    └── alpha.md
+```
+
+Resolution from `TaskNotes/Tasks/subtasks/task-002.md`:
+
+| Link value | Resolved path | Notes |
+|---|---|---|
+| `[[task-001]]` | `TaskNotes/Tasks/task-001.md` | Simple-name search |
+| `[[../task-001]]` | `TaskNotes/Tasks/task-001.md` | Relative wikilink |
+| `[[./task-003]]` | `TaskNotes/Tasks/subtasks/task-003.md` | Relative (may not exist) |
+| `[[notes/meeting]]` | `notes/meeting.md` | Absolute from root |
+| `[[alpha]]` | `projects/alpha.md` | Simple-name search (projects scope) |
+| `[link](../task-001.md)` | `TaskNotes/Tasks/task-001.md` | Markdown, relative |
+| `../task-001.md` | `TaskNotes/Tasks/task-001.md` | Bare path, relative |
+
+---
+
+## 11.5 Path sandboxing
+
+Link resolution MUST NOT produce paths outside the collection root.
+
+**Rules:**
+- After resolving relative paths (applying `../` segments), the resulting path MUST be within the collection root directory
+- If resolution would escape the collection root, the link MUST resolve to `null` and implementations MUST emit a `path_traversal` error
+- This applies to all link formats: wikilinks, markdown links, and bare paths
+- Implementations MUST normalize paths (resolve `.` and `..` segments) before checking containment
+
+**Examples** (collection rooted at `/home/user/MyVault/`):
+
+| Link | From file | Result |
+|---|---|---|
+| `[[../../../etc/passwd]]` | `TaskNotes/Tasks/task.md` | `null` + `path_traversal` |
+| `[[../../secrets/key]]` | `deep/nested/file.md` | `null` + `path_traversal` |
+| `[[../task-001]]` | `TaskNotes/Tasks/subtasks/t.md` | Resolves normally |
+
+---
+
+## 11.6 Canonical write format
+
+When creating new link values or changing a link target, implementations MUST use a deterministic canonical form.
+
+### Default (wikilink format)
+
+By default (`links.use_markdown_format=false`), the canonical write format is a **simple wikilink**:
+
+```yaml
+blockedBy:
+  - uid: "[[task-001]]"
+    reltype: FINISHTOSTART
+projects:
+  - "[[projects/alpha]]"
+```
+
+Rules:
+- Use the filename without extension as the target when the file can be identified by simple-name resolution within the appropriate scope.
+- Use a path-qualified target (`folder/name`) when the simple name would be ambiguous.
+- Do NOT include the alias component in dependency `uid` writes.
+- Do NOT include the anchor component in dependency `uid` writes.
+- Preserve the alias component in `projects` entries when the alias was provided by the user.
+
+### Markdown link format (`links.use_markdown_format=true`)
+
+When `links.use_markdown_format=true` is configured (requires the `obsidian-frontmatter-markdown-links` Obsidian plugin), the canonical write format for link-bearing fields is a **markdown link** using the collection-relative path:
+
+```yaml
+blockedBy:
+  - uid: "[task-001](TaskNotes/Tasks/task-001.md)"
+    reltype: FINISHTOSTART
+```
+
+### Round-trip preservation
+
+When writing an existing link field and the resolved target is unchanged, implementations MUST preserve the original format when possible:
+- If the user wrote `[[task-001|My Task]]`, preserve alias for `projects` entries.
+- If the user wrote a relative path, preserve relativity when possible.
+- For `blocked_by.uid`, alias and anchor components MUST still be removed on canonical writes.
+- If preservation is not possible (for example unresolved/ambiguous reconstruction), implementations MUST fall back to canonical write rules in this section.
+
+---
+
+## 11.7 Configuration
+
+`links` configuration keys (see §9.12):
+
+```yaml
+links:
+  extensions: [".md"]                  # Extension trial order for extensionless targets
+  use_markdown_format: false           # Write markdown links instead of wikilinks
+  unresolved_default_severity: warning # "warning" or "error"
+  update_references_on_rename: true    # Update link targets when files are renamed
+```
+
+Rules:
+- `extensions` MUST be a non-empty list when present
+- `unresolved_default_severity` MUST be `"warning"` or `"error"`
+- `update_references_on_rename=true` enables rename-time link rewrite behavior (§11.9)
+- `use_markdown_format=true` requires the `obsidian-frontmatter-markdown-links` plugin in Obsidian deployments
+
+---
+
+## 11.8 Role-specific rules
+
+### 11.8.1 `projects`
+
+`projects` entries SHOULD be interpreted with this section's parsing/resolution rules.
+
+If a `projects` entry is a plain string (not a wikilink or markdown link), implementations SHOULD treat it as a bare filename or path and attempt resolution.
+
+If unresolved:
+- `links.unresolved_default_severity=error`: validation error
+- otherwise: SHOULD emit `unresolved_link_target` warning
+
+### 11.8.2 `blocked_by.uid`
+
+`blocked_by.uid` values MUST use this section's parsing/resolution rules.
+
+For dependency semantics, unresolved `uid` handling follows §10.2.6.
+For unresolved-target severity, `dependencies.unresolved_target_severity` controls and takes precedence over `links.unresolved_default_severity`.
+
+The canonical write form for `uid` values is specified in §11.6.
+
+---
+
+## 11.9 Rename and reference updates
+
+If an implementation supports reference updates on rename (i.e. claims the `rename` capability):
+
+1. It MUST update resolvable references in `blocked_by.uid` and `projects` link fields.
+2. It SHOULD update links in body content.
+3. It SHOULD preserve the original link format when possible.
+4. It MUST preserve alias and anchor components where valid for the target field. For `blocked_by.uid`, alias and anchor are non-canonical and MUST be removed on write (§11.6).
+5. It MUST report unresolved or ambiguous rewrite cases.
+
+If reference updates are not supported, this limitation MUST be disclosed in conformance claims.
+
+---
+
+## 11.10 Validation
+
+Link validation issues:
+
+| Code | Severity | Trigger |
+|---|---|---|
+| `invalid_link_format` | error | Link value cannot be parsed as any supported format |
+| `ambiguous_link` | warning | Simple-name resolution found multiple candidates after normalization |
+| `unresolved_link_target` | warning | Link target cannot be resolved to an existing file |
+| `path_traversal` | error | Resolved path escapes collection root |
+
+`unresolved_link_target` severity may be promoted to error via `links.unresolved_default_severity=error`.
+For `blocked_by.uid`, use `unresolved_dependency_target` severity policy from §10.2.6 instead of `unresolved_link_target`.
+
+---
+
+## 11.11 Examples
+
+### Dependency with wikilink (default)
+
+```yaml
+---
+title: Implement API
+status: open
+tags: [task]
+blockedBy:
+  - uid: "[[design-api]]"
+    reltype: FINISHTOSTART
+  - uid: "[[projects/infra/setup-server]]"
+    reltype: FINISHTOSTART
+    gap: P1D
+projects:
+  - "[[projects/alpha]]"
+dateCreated: 2026-02-20T10:00:00Z
+dateModified: 2026-02-20T10:00:00Z
+---
+```
+
+### Dependency with markdown links (`links.use_markdown_format=true`)
+
+```yaml
+---
+title: Implement API
+status: open
+tags: [task]
+blockedBy:
+  - uid: "[design-api](TaskNotes/Tasks/design-api.md)"
+    reltype: FINISHTOSTART
+---
+```
+
+### Relative links from nested task
+
+```yaml
+# TaskNotes/Tasks/subtasks/task-002.md
+---
+title: Sub-task
+status: open
+tags: [task]
+blockedBy:
+  - uid: "[[../task-001]]"    # resolves to TaskNotes/Tasks/task-001.md
+    reltype: FINISHTOSTART
+projects:
+  - "[[projects/alpha]]"      # resolves from collection root
+---
+```

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.2.0-draft - 2026-05-31
+
+- add optional `materialized-occurrences` profile for recurrence occurrence notes, on-completion materialization, and occurrence-state reconciliation
+
+## 0.1.0-draft - 2026-02-20
+
+Initial standalone draft of `tasknotes-spec` including:
+
+- motivation, scope, and normative conventions
+- terminology
+- task model and field mapping
+- temporal semantics
+- recurrence semantics
+- operation semantics
+- validation model
+- conformance profiles
+- compatibility and migration policy
+- collection configuration schema and provider model (`tasknotes.yaml`, TaskNotes `data.json`)
+- full dependency (`blocked_by`) semantics
+- full reminder (`reminders`) semantics
+- explicit time-tracking management semantics (`time_entries` lifecycle, start/stop/edit/remove, and completion-triggered auto-stop configuration)
+- explicit links chapter and link-resolution rules for projects/dependencies
+- optional `templating` conformance profile with create-time template expansion/merge semantics