Conformance

An implementation claims conformance in one of three roles. Each is cumulative: a Writer is also a Reader, and a Manager is also a Writer.

Parses a tree and answers questions about it. Never writes. The bar for a status line, a dashboard, or a CI check.

Creates and modifies tasks while preserving every invariant. The bar for an agent that manages its own work.

Writer, plus the full lifecycle: claims, validation, repair, archival. The bar for a tool other tools defer to.

An implementation SHOULD state its role and the convention version it targets, for example: "conforms to .tasks v1 (Writer)".

Reader

A Reader MUST:

Discover the project by walking upward for .tasks/, nearest wins, no merging.
Enumerate live tasks as <phase>/<id>.md, exactly one directory deep, ignoring .archive/, .locks/, non-.md files, and files at the root of .tasks/.
Parse frontmatter without coercing timestamp-shaped scalars into dates.
Tolerate unrecognized frontmatter keys.
Derive a live task's phase from its containing directory, and an archived task's from its frontmatter.
Load config.yml when present, apply every default when absent, and reject unknown top-level keys.
Resolve roles through configuration rather than assuming any status name.
Resolve dependencies per dependency resolution, including judging an external reference against that project's done role.
Treat every unsatisfied or unresolvable state as blocking.
Compute readiness from current state, never from a stored field.
Report a malformed task file rather than skipping it silently.
Refuse to operate on a tree whose version it does not support.

A Reader MUST NOT:

A Writer MUST additionally:

Write every file atomically, via a temporary file and a rename.
Emit frontmatter in canonical form.
Set created once, and updated on every mutation.
Enforce id uniqueness across live and archived tasks.
Keep the filename <id>.md in step with the id field.
Create a phase directory on demand when placing a task into it.
Validate a status transition against the configured rules before applying it.
Set and clear claimed_by and claimed_at together, and clear both whenever a task leaves the claimed role.
Perform a phase change as write-destination-then-remove-source.
Refuse a dependency that is a self-reference, points at a nonexistent local task, or would create a local cycle.
Leave the task body untouched apart from surrounding whitespace normalization.

A Writer MUST NOT:

A Manager MUST additionally:

Serialize state-dependent mutation under an exclusive per-task lock in .locks/, re-reading the task inside the lock before deciding, with a documented staleness threshold.
Implement claiming as a single operation that checks the transition, checks dependencies, and records identity and time together.
Provide claiming from any status that can legally reach the claimed role — not only from ready — so that completed work can be reopened.
Detect at least the conditions listed under validation, at the severities given there.
Confine automatic repair to filename mismatch, phase drift, and regenerating _index.md.
Archive by default when deleting, preserving the originating phase in frontmatter, and refuse by default to delete a task that live tasks depend on.

A Manager that exposes a command line MUST also satisfy the CLI contract in full.

An implementation is free to differ on all of the following, and doing so does not affect conformance:

Area	Notes
Human-readable output	Entirely unspecified. Tables, colors, and layout are yours.
Command names and flags	Only the JSON shapes and exit codes are contract, not the surface that produces them.
`_index.md` content	Whether to generate it at all, and in what form.
Body scaffolding	The headings a new task starts with.
Identity resolution	How `claimed_by` is determined when not supplied.
Lock staleness threshold	Must exist and be documented; the value is yours.
Storage of derived views	Caches are fine, provided the files remain authoritative and a cache is never consulted in place of them.