tasknotes-spec 0.2.0

package/06-validation.md

@@ -0,0 +1,267 @@
+# 6. Validation
+
+## 6.1 Purpose
+
+Validation ensures persisted task records conform to this specification and collection configuration.
+
+## 6.2 Validation phases
+
+Implementations SHOULD validate in these phases:
+
+1. Parse validation (YAML/frontmatter structure)
+2. Schema validation (types and role constraints)
+3. Semantic validation (cross-field invariants)
+
+## 6.3 Validation modes
+
+Conforming implementations MUST support:
+
+- `strict`: errors block writes.
+
+Implementations MAY additionally support:
+
+- `permissive`: writes may continue with warnings.
+
+Current mode MUST be discoverable.
+
+## 6.4 Required checks
+
+A conforming validator MUST implement checks required by the claimed profile(s):
+
+| Check ID | Requirement | Required for |
+|---|---|---|
+| 1 | Unconditionally required semantic roles are present (`status`, `date_created`, `date_modified`). | `core-lite` and above |
+| 1a | `completed_date` conditional requiredness is enforced per §2.2.1. | `core-lite` and above |
+| 1b | `title` resolves via active title policy (§2.2.2 and §9.13): storage-mode-aware precedence and fallback. | `core-lite` and above |
+| 2 | Field values match role type requirements. | `core-lite` and above |
+| 3 | Temporal values conform to §3. | `core-lite` and above |
+| 4 | Recurrence values conform to §4 (including tasknotes recurrence-string syntax and anchor-seed resolution rules). | `recurrence` and above |
+| 5 | Per-instance lists contain valid dates with no overlap. | `recurrence` and above |
+| 6 | `date_modified` is not earlier than `date_created` when both exist. | `core-lite` and above |
+| 7 | `time_estimate` is non-negative when present. | any profile that supports `time_estimate` |
+| 8 | `time_entries` entries include required `startTime`, ranges are valid when `endTime` exists, and at most one active entry exists per task. | any profile that supports `time_entries` |
+| 9 | `blocked_by` entries conform to §10.2 (shape, enum, duplicates, self-reference). | `extended` |
+| 10 | `reminders` entries conform to §10.3 (shape, type-specific fields, unique ids). | `extended` |
+| 11 | relative reminders have resolvable base fields or produce configured error/warning behavior. | `extended` |
+| 12 | link-bearing fields (`projects`, `blocked_by.uid`) conform to §11 parsing/resolution and traversal safety. | `extended` |
+| 13 | templating configuration is valid when provided (`templating` schema and enums). | `templating` |
+| 14 | create-time template failures obey configured failure mode (`error` vs fallback). | `templating` |
+| 15 | semantic `id` (when present) is a non-empty string; duplicate collection-level IDs SHOULD be reported when detectable. | any profile that supports semantic `id` |
+| 16 | materialized occurrence notes contain valid `recurrence_parent` and `occurrence_date` roles. | `materialized-occurrences` |
+| 17 | no duplicate materialized occurrence notes exist for the same resolved `(recurrence_parent, occurrence_date)` pair. | `materialized-occurrences` |
+| 18 | materialization policy values and rolling horizons conform to §4.18 and §9.17. | `materialized-occurrences` |
+
+## 6.5 Unknown field policy
+
+Unknown fields:
+
+- MUST NOT fail validation by default unless collection is configured for strict schema closure.
+- SHOULD generate informational warnings when strict schema closure is desired but not enabled.
+
+## 6.6 Issue structure
+
+Validation issues MUST include:
+
+- `code` (machine-readable)
+- `severity` (`error`, `warning`, or `info`)
+- `message` (human-readable)
+
+Issues SHOULD include:
+
+- `field` or path
+- `expected` and `actual` details where useful
+
+## 6.7 Recommended issue codes
+
+| Code | Severity (default) | Meaning |
+|---|---|---|
+| `missing_required` | error | required role missing |
+| `invalid_type` | error | value type mismatch |
+| `invalid_enum_value` | error | value not in configured set |
+| `invalid_date_value` | error | malformed or impossible date |
+| `invalid_datetime_value` | error | malformed datetime |
+| `invalid_recurrence_rule` | error | recurrence not valid tasknotes recurrence syntax |
+| `missing_recurrence_seed` | error | recurrence has no resolvable seed/start date |
+| `invalid_recurrence_anchor` | error | anchor not allowed |
+| `instance_state_overlap` | error | same date in complete and skipped lists |
+| `invalid_time_range` | error | end before start in time entry |
+| `missing_time_entry_start` | error | time entry is missing required startTime |
+| `multiple_active_time_entries` | error | more than one active time entry exists in one task |
+| `invalid_dependency_entry` | error | dependency object missing required fields |
+| `invalid_dependency_reltype` | error | dependency reltype not allowed |
+| `invalid_dependency_gap` | error | dependency gap not valid ISO 8601 duration |
+| `duplicate_dependency_uid` | error in strict mode when `dependencies.enforce_unique_uid=true`; warning otherwise by policy | repeated dependency uid in task |
+| `self_dependency` | error | task depends on itself |
+| `unresolved_dependency_target` | warning | dependency target not resolvable |
+| `invalid_reminder_entry` | error | reminder object missing required fields |
+| `duplicate_reminder_id` | error | repeated reminder id in task |
+| `invalid_reminder_type` | error | reminder type not allowed |
+| `invalid_reminder_offset` | error | relative reminder offset not valid duration |
+| `invalid_reminder_related_to` | error | relatedTo must be due or scheduled |
+| `invalid_reminder_absolute_time` | error | absoluteTime invalid datetime |
+| `unresolvable_reminder_base` | error | relative reminder base field missing/unusable |
+| `invalid_link_format` | error | link value cannot be parsed as supported format |
+| `ambiguous_link` | warning | link resolves to multiple candidates |
+| `path_traversal` | error | resolved path escapes collection root |
+| `unresolved_link_target` | warning | link target cannot be resolved |
+| `invalid_task_id` | error | semantic `id` is empty or invalid type |
+| `duplicate_task_id` | warning | duplicate semantic `id` detected in collection scope |
+| `alias_conflict_ignored` | warning | alias key ignored due to canonical conflict |
+| `unresolvable_title` | error | title cannot be resolved from title resolution policy |
+| `title_source_conflict` | warning | mapped title and filename title differ; active title-storage policy selected authoritative source |
+| `template_missing` | warning | configured template file cannot be read/found |
+| `template_parse_failed` | warning | template frontmatter/body parsing or expansion failed |
+| `missing_recurrence_parent` | error | materialized occurrence note omits recurrence_parent |
+| `invalid_recurrence_parent` | warning | occurrence note parent reference cannot be resolved or does not reference a recurring task |
+| `missing_occurrence_date` | error | materialized occurrence note omits occurrence_date |
+| `duplicate_occurrence_note` | warning | more than one materialized occurrence note exists for the same parent/date |
+| `occurrence_state_conflict` | warning | materialized occurrence state disagrees with parent instance lists |
+| `materialization_target_not_generated` | warning | occurrence date is not generated by current parent recurrence rule |
+| `missing_skipped_status` | error | skip of materialized occurrence requires configured skipped status |
+| `next_occurrence_materialization_failed` | warning | triggering operation succeeded but next occurrence note could not be created |
+| `orphan_occurrence_note` | warning | materialized occurrence note has no resolvable recurring parent or parent state references a deleted occurrence note |
+| `unknown_field` | info | unmapped field encountered |
+
+Implementations MAY extend this code set but SHOULD preserve existing meanings.
+
+## 6.8 Write-time validation behavior
+
+In strict mode, mutating operations MUST fail if any error-severity issue is present after applying intended changes.
+
+Warnings SHOULD NOT block writes unless explicitly configured.
+
+Datetime/date acceptance and rejection in validation MUST follow the normative matrix in §3.4.4.
+
+## 6.9 Validation examples
+
+### 6.9.1 Missing required role
+
+Input:
+
+```yaml
+title: Plan workshop
+status: open
+dateCreated: 2026-02-20T09:00:00Z
+```
+
+Issue:
+
+```yaml
+code: missing_required
+severity: error
+field: dateModified
+message: Required field 'dateModified' is missing.
+```
+
+### 6.9.2 Invalid recurrence anchor
+
+Input:
+
+```yaml
+recurrence: FREQ=DAILY
+recurrenceAnchor: due
+```
+
+Issue:
+
+```yaml
+code: invalid_recurrence_anchor
+severity: error
+field: recurrenceAnchor
+message: recurrence anchor must be 'scheduled' or 'completion'.
+```
+
+### 6.9.3 Overlap in instance state
+
+Input:
+
+```yaml
+completeInstances: [2026-02-20]
+skippedInstances: [2026-02-20]
+```
+
+Issue:
+
+```yaml
+code: instance_state_overlap
+severity: error
+message: same date exists in complete and skipped instance lists.
+```
+
+### 6.9.4 Invalid dependency reltype
+
+Input:
+
+```yaml
+blockedBy:
+  - uid: "[[task-a]]"
+    reltype: BLOCKS
+```
+
+Issue:
+
+```yaml
+code: invalid_dependency_reltype
+severity: error
+field: blockedBy[0].reltype
+message: reltype must be one of FINISHTOSTART, STARTTOSTART, FINISHTOFINISH, STARTTOFINISH.
+```
+
+### 6.9.5 Unresolvable reminder base
+
+Input:
+
+```yaml
+reminders:
+  - id: due_minus_1d
+    type: relative
+    relatedTo: due
+    offset: -P1D
+```
+
+Issue when `due` missing:
+
+```yaml
+code: unresolvable_reminder_base
+severity: error
+field: reminders[0]
+message: relative reminder references due but no due value exists.
+```
+
+### 6.9.6 Unknown field in permissive mode
+
+Input:
+
+```yaml
+title: Plan workshop
+status: open
+vendorPriority: p1
+```
+
+Issue example:
+
+```yaml
+code: unknown_field
+severity: info
+field: vendorPriority
+message: field is not mapped to a known semantic role.
+```
+
+### 6.9.7 Multiple active time entries
+
+Input:
+
+```yaml
+timeEntries:
+  - startTime: 2026-02-20T10:00:00Z
+  - startTime: 2026-02-20T11:00:00Z
+```
+
+Issue:
+
+```yaml
+code: multiple_active_time_entries
+severity: error
+field: timeEntries
+message: task contains more than one active time entry.
+```

package/07-conformance.md

@@ -0,0 +1,292 @@
+# 7. Conformance
+
+## 7.1 Purpose
+
+This section defines conformance profiles and claim requirements for implementations.
+
+## 7.2 Conformance principles
+
+An implementation MUST NOT claim conformance to a profile unless all required capabilities of that profile are implemented.
+
+Implementations MAY implement additional behavior beyond a profile, but extra behavior MUST NOT violate profile requirements.
+
+## 7.3 Profile model
+
+Profiles are cumulative unless explicitly marked otherwise.
+
+### 7.3.1 Profile: `core-lite`
+
+Required capabilities:
+
+- task identification and loading
+- semantic-role mapping and canonical writes (§2)
+- required role support (`title`, `status`, `completed_date`, `date_created`, `date_modified`)
+- create, update, delete operations (§5)
+- non-recurring complete/uncomplete (§5)
+- temporal parsing/canonical serialization basics (§3)
+- strict validation mode support (§6.3)
+- validation core checks (§6.4 items 1,1a,1b,2,3,6)
+
+### 7.3.2 Profile: `recurrence`
+
+Additional required capabilities:
+
+- tasknotes recurrence-string parsing/validation, including RRULE parameter syntax and inline `DTSTART` handling
+- recurrence anchor semantics, including seed precedence and completion-anchor progression
+- complete/uncomplete instance
+- skip/unskip instance
+- instance-list invariants and effective state resolution
+- validation checks for recurrence and instance overlap
+
+### 7.3.3 Profile: `templating` (non-cumulative extension)
+
+This profile is not cumulative; it MAY be claimed alongside `core-lite`, `recurrence`, `materialized-occurrences`, and/or `extended`.
+`templating` MUST NOT be claimed alone.
+
+Required capabilities:
+
+- create-time template processing semantics per §5.3.5
+- `templating` configuration support per §9.14
+- deterministic template/frontmatter/body merge behavior
+- deterministic failure-mode behavior for template read/parse failures
+- support for portable double-brace template variables defined in §5.3.5
+
+### 7.3.4 Profile: `materialized-occurrences` (non-cumulative extension)
+
+This profile is not cumulative; it MUST be claimed alongside `recurrence`.
+It MAY be claimed alongside `extended` and/or `templating`, but it does not require either.
+
+Required capabilities:
+
+- materialized occurrence roles and identity semantics (§2.6.6)
+- recurrence materialization semantics (§4.18)
+- materialize/complete/skip/uncomplete/unskip materialized occurrence operations (§5.20)
+- `occurrences` configuration defaults (§9.17)
+- parent-reference link parsing/resolution for `recurrence_parent` (§11), without requiring full `extended`
+- validation checks for materialized occurrence identity, duplicates, and state conflicts (§6.4 items 16-18)
+
+Claiming `materialized-occurrences` also has required capability-token implications:
+
+- `meta.claim.capabilities` MUST include `materialized-occurrences`.
+- `meta.claim.profiles` MUST also include `recurrence`.
+- Omitting either token while claiming `materialized-occurrences` is a non-conformant claim.
+
+### 7.3.5 Profile: `extended`
+
+Additional required capabilities:
+
+- dependency schema support (`blocked_by`)
+- reminder schema support (`reminders`)
+- link parsing/resolution semantics for link-bearing fields (§11)
+- time-tracking management semantics for `time_entries` (§5.19), including per-task active-session constraints
+- dependency operations and validation per §10.2
+- reminder operations and validation per §10.3
+
+If `extended` is claimed, all of the above baseline capabilities MUST conform to documented semantics.
+
+Claiming `extended` also has required capability-token implications:
+
+- `meta.claim.capabilities` MUST include `dependencies`, `reminders`, `links`, and `time-tracking`.
+- Omitting any of these tokens while claiming `extended` is a non-conformant claim (even if capability-gated fixtures are skipped by a runner).
+
+Optional capability extensions within `extended`:
+
+- `rename` capability: reference-aware rename behavior (including dependency UID references)
+- `archive` capability: archive semantics (§5.12)
+- `batch` capability: batch operations with per-item outcomes (§5.15)
+- `concurrency` capability: write-conflict detection semantics (§5.16)
+- `dry-run` capability: dry-run semantics (§5.17)
+
+When an optional capability token is claimed, corresponding behavior MUST conform to documented semantics.
+
+## 7.4 Conformance claim format
+
+A conformance claim MUST include:
+
+- implementation name and version,
+- `tasknotes-spec` version,
+- claimed profile list,
+- validation mode support (`strict` required; `permissive` optional),
+- known deviations,
+- compatibility mode status (if any),
+- configuration provider status (active provider chain, precedence policy, and fallback state).
+
+Example:
+
+```text
+Implementation: example-task-cli v1.4.0
+Spec: tasknotes-spec 0.2.0-draft
+Profiles: core-lite, recurrence, templating
+Validation modes: strict, permissive
+Known deviations: none
+Compatibility mode: disabled
+Configuration providers: tasknotes_plugin_data_json > built_in_defaults
+Configuration fallback: none
+```
+
+## 7.5 Deviation disclosure
+
+Any known deviation from normative text MUST be explicitly disclosed in conformance output/documentation.
+
+A deviation entry SHOULD include:
+
+- affected section,
+- deviation summary,
+- impact,
+- planned resolution version.
+
+## 7.6 Feature detection
+
+Implementations SHOULD expose machine-readable capability metadata, including:
+
+- profiles
+- effective runtime timezone
+- active configuration providers and precedence chain
+- enabled compatibility modes
+- configurable status sets
+- supported mapping aliases
+- templating support flags and effective templating failure mode
+- dependency and reminder support flags
+- time-tracking support flags, including active-session policy and auto-stop-on-complete behavior
+- materialized occurrence support flags, including materialization mode, next trigger, and rolling bounds
+
+## 7.7 Strictness disclosure
+
+Conformance requires `strict` validation mode support (§6.3).
+
+Conformance claims MUST indicate whether `permissive` mode is also supported.
+
+## 7.8 Example profile matrix
+
+| Capability | core-lite | recurrence | templating | materialized-occurrences | extended |
+|---|---:|---:|---:|---:|---:|
+| create/update/delete | required | required | companion-profile required | companion-profile required | required |
+| non-recurring complete | required | required | companion-profile required | companion-profile required | required |
+| recurring instance complete/skip | - | required | optional | required via companion `recurrence` claim | required |
+| materialize occurrence notes (§4.18, §5.20) | - | - | optional | required | optional |
+| recurrence parent link resolution | - | - | optional | required for `recurrence_parent` only | required |
+| template expansion/merge (§5.3.5) | - | - | required | optional | optional |
+| double-brace portable variable support | - | - | required | optional | optional |
+| recurrence-string validation | - | required | optional | required via companion `recurrence` claim | required |
+| link parsing/resolution (§11) | - | - | optional | required for `recurrence_parent` only | required |
+| dependency schema and ops | - | - | optional | optional | required |
+| reminder schema and ops | - | - | optional | optional | required |
+| time tracking start/stop/edit semantics (§5.19) | - | - | optional | optional | required |
+| rename updates dependency/project links | - | - | optional | optional | optional via `rename` capability |
+| archive semantics (§5.12) | - | - | optional | optional | optional via `archive` capability |
+| batch per-item outcomes (§5.15) | - | - | optional | optional | optional via `batch` capability |
+| write-conflict detection (§5.16) | - | - | optional | optional | optional via `concurrency` capability |
+| dry-run reporting (§5.17) | - | - | optional | optional | optional via `dry-run` capability |
+
+## 7.9 Executable fixture suite
+
+This specification includes an executable fixture suite in `conformance/`.
+
+- language-neutral fixtures are stored in `conformance/fixtures/*.json`
+- section/profile/operation coverage is tracked in `conformance/manifest.json`
+- coverage guard tests MUST enforce both section representation and minimum-depth thresholds for key sections/operations.
+- adapters execute fixture operations per `conformance/docs/ADAPTER_CONTRACT.md`
+- runners MUST execute fixtures only when both conditions hold:
+  - fixture `profile` is satisfied by claimed adapter profiles under cumulative profile rules (§7.3),
+  - all fixture `requires` capability tokens are present.
+
+Fixture expectations MUST be profile-modular: they MUST NOT assume capability values or profile memberships beyond what the fixture's own `profile`/`requires` gating guarantees.
+Fixtures for optional extension capabilities (`rename`, `archive`, `batch`, `concurrency`, `dry-run`) MUST be capability-gated via `requires` and MUST NOT rely on `extended` profile membership alone.
+
+Conformance claims SHOULD report fixture pass/fail results against the claimed profiles.
+
+## 7.10 Meta operations
+
+The following operations are part of the conformance interface and MUST be supported by any adapter that participates in the conformance suite, regardless of claimed profile. These meta operations MUST be callable without requiring any capability token.
+
+### `meta.claim`
+
+Returns the adapter's self-reported metadata.
+
+Input: `{}` (empty object)
+
+Output:
+```json
+{
+  "ok": true,
+  "result": {
+    "implementation": "my-tool",
+    "version": "1.0.0",
+    "spec_version": "0.2.0-draft",
+    "validation_modes": ["strict"],
+    "profiles": ["core-lite", "recurrence"],
+    "capabilities": ["dependencies", "links"]
+  }
+}
+```
+
+Fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `implementation` | string | yes | Human-readable implementation name |
+| `version` | string | yes | Implementation version string |
+| `spec_version` | string | yes | `tasknotes-spec` version targeted by this adapter |
+| `validation_modes` | string[] | yes | Supported validation modes; MUST include `strict` |
+| `profiles` | string[] | yes | Claimed conformance profiles; valid values: `core-lite`, `recurrence`, `extended`, `templating`, `materialized-occurrences` |
+| `capabilities` | string[] | yes | Optional capability tokens; known tokens listed in §7.11 |
+
+`profiles` lists explicitly claimed profiles. Cumulative profile expansion is applied by runners for fixture selection (§7.3, §7.9), but does not change literal membership semantics of `meta.has_profile`.
+
+Profile-token consistency rules:
+
+- If `profiles` contains `extended`, `capabilities` MUST include `dependencies`, `reminders`, `links`, and `time-tracking`.
+- If `profiles` contains `templating`, `capabilities` MUST include `templating`.
+- If `profiles` contains `materialized-occurrences`, `profiles` MUST also contain `recurrence` and `capabilities` MUST include `materialized-occurrences`.
+- Runners and fixture suites SHOULD validate these claim-consistency rules directly from `meta.claim`, not only by capability-gating feature fixtures.
+
+### `meta.has_capability`
+
+Tests whether the adapter claims a specific capability.
+
+Input:
+```json
+{ "capability": "dependencies" }
+```
+
+Output:
+```json
+{ "ok": true, "result": { "value": true } }
+```
+
+`result.value` MUST be `true` if the capability is in the `capabilities` array returned by `meta.claim`, and `false` otherwise.
+
+### `meta.has_profile`
+
+Tests whether the adapter claims a specific conformance profile.
+
+Input:
+```json
+{ "profile": "recurrence" }
+```
+
+Output:
+```json
+{ "ok": true, "result": { "value": true } }
+```
+
+`result.value` MUST be `true` if the profile is in the `profiles` array returned by `meta.claim`, and `false` otherwise.
+
+## 7.11 Known capability tokens
+
+The following capability tokens are defined by this specification. Implementations MAY define additional tokens.
+
+| Token | Required by profile | Meaning |
+|---|---|---|
+| `dependencies` | `extended` | Supports `blocked_by`, dependency operations, and dependency validation |
+| `reminders` | `extended` | Supports `reminders`, reminder operations, and reminder validation |
+| `links` | `extended` | Supports link parsing and resolution (§11) |
+| `time-tracking` | `extended` | Supports time-tracking management operations (§5.19) |
+| `materialized-occurrences` | `materialized-occurrences` | Supports recurrence materialization and materialized occurrence operations (§4.18, §5.20) |
+| `rename` | optional extension under `extended` | Supports file rename with reference updates |
+| `archive` | optional extension under `extended` | Supports archive semantics (§5.12) |
+| `batch` | optional extension under `extended` | Supports batch operations with per-item outcomes (§5.15) |
+| `concurrency` | optional extension under `extended` | Supports write-conflict detection (§5.16) |
+| `dry-run` | optional extension under `extended` | Supports dry-run mode (§5.17) |
+| `migration` | — | Supports migration operations (§8) |
+| `templating` | `templating` | Supports create-time templating (§5.3.5) |