Changelog - Actions Specifications
v0.7.0 — 2026-11-09
Publishes the notes-in-the-sidecar contract approved by Darrion at 96e1c76 (a date-only migrated log entry gets midnight UTC), with the predecessor-reference fix already on main. All eight schema $ids name https://clearhead.dev/schemas/v0.7.0/<name>.schema.json. Core adoption follows separately.
Added
Notes: one append-only log for any entity, in the sidecar. notes.<uuid> in the charter sidecar holds {at, by, text} notes for a charter, Action or Habit; jot is the single append verb; appends are serialized; doctor --fix relocates a moved entity’s notes and keeps an orphan’s. Approved by Darrion 2026-11-09 (docs/action-notes-proposal.md).
Changed
The charter log moves to the sidecar. charters.md Log is now the charter’s notes; the ## Log section is legacy, read but never appended, and migrated by tool.
Fixed
Predecessors never resolve by name. W007, W008 and W009 now follow Reference Syntax: a < resolves by full UUID, short UUID, alias or path, across the workspace, and an ambiguous match at the strongest tier does not resolve. E009 uses the same resolution. Their examples and wording had treated action names as references (Darrion, 2026-11-08: “alias is more clear… i think for right now we can keep with the simple version and see if it bites”).
v0.6.0 — 2026-11-07
Publishes the template-recurrence and ancestor-dependency contracts approved by Darrion at 139f0c9. All eight schema $ids name https://clearhead.dev/schemas/v0.6.0/<name>.schema.json; their structures are unchanged. These are specification contracts: Core adoption and implementation follow in separately reviewed increments. No grammar syntax changed, so no companion grammar release is required.
Changed
E002 covers recurrence in any template. R: on a line of a named template (templates/<name>.actions) is now an error, as it already was on a Habit’s inline child, and generating from such a template is refused. R: in other ordinary .actions stays a warning (Darrion, 2026-11-07: “that is a filter to make sure templates dont use recurrence”).
Added
E009: an Action may not depend on its ancestors. A < that resolves to the line’s parent or any ancestor, including a Habit above its template steps, is a lint error, and stamping refuses such a step (Darrion, 2026-11-07: “subactions shouldnt depend on parents anyways … the dependency is implicit”).
v0.5.0 — 2026-11-03
Published jointly with tree-sitter-actions v0.11.0 after Darrion approved Habit source 2d812ec and independent Claude machine-contract review. All schema $ids name https://clearhead.dev/schemas/v0.5.0/<name>.schema.json. Core adoption and platform pins follow separately.
Added
Native Habits and recurrence (Decisions 56–57). R: follows the complete planned block; <charter>.habits.actions owns Habit roots and their template children. Habits have native UUIDs and Action state values. Every arrived slot materializes independently, missed slots remain open, and active/archived history suppresses duplicates. Completed and cancelled Habits stop generation; all open states generate, with no pause capability.
Deterministic identity and calendar format. VEVENT projections preserve native/transport identity separation. DATE, floating and zoned slots have canonical string keys; UUIDv5 occurrence and template-step recipes converge across devices. Kind changes preserve the approved native identities, including reusing the Habit UUID when recurring-to-one-off has no open occurrence. UID replacement requires explicit linking, never automatic identity merging.
Executable contracts. Habit JSON/sidecar schemas, application SHACL, CCO mappings and conformance fixtures cover state, lineage, canonical slots and cross-zone fold/gap examples. Independent review corrections align closed-date and slot validation with approved prose. Existing individual-close and root-tree archival contracts from v0.4.0 remain intact.
Changed
Syntax, workspace file roles, ontology entity roles and process outcomes are separated. ICS specifies format and deterministic identity rather than implementation mechanics. Linting, observability and configuration describe Habit scope and lifecycle; obsolete upcoming-actions discovery is removed. Approved formatting fixtures remain the shared oracle.
v0.4.0 — 2026-11-02
A minor release: the specifications as of this entry, including the dated entry below down to v0.3.0. Closing an action becomes a state change in place, archive and unarchive move whole root trees, and transactions gain reopen-action (platform Decisions 58 and 59). Schema $ids are https://clearhead.dev/schemas/v0.4.0/<name>.schema.json.
2026-11-02
Added
Reopen one action in place (schemas/transaction_request.schema.json, examples/transactions/, explanations/data_workflows.md; platform Decisions 58 and 59). reopen-action sets the named closed action to not_started and clears completed_at. It is active-file only: an archived action must first be unarchived as part of its root tree. The archived refusal carries the target id, the root to unarchive, and the original query; the archived rejection example illustrates it.
Changed
Closing is a state change; archival is a separate root-tree operation (workspace.md, linting.md, transaction schemas and examples, explanations/data_workflows.md; platform Decisions 58 and 59, approved 2026-11-02). Complete and cancel stamp only the named action’s state and completion date in place, without closing descendants, detaching parent links, or moving lines. Closed lines in the active file are ordinary records. Only archive and unarchive transfer action lines between active and completed files, always a whole root tree; archive requires every line to be closed, and either operation refuses a child target and names its root. Parent links inside archived trees are kept. W002 reports a closed parent with an open child rather than forbidding closure; its cancelled-child example is removed because it has no open child. W002 and W003 remain warnings. Complete and cancel receipts replace children with required open_children, the canonical ids left open beneath the named action (empty when none). Reopen receipts carry neither field; only delete retains the descendant children count. update-action refuses a closed target altogether, including non-state edits, and continues to reject terminal state values. This specifies the contract for a later release; Core adoption follows separately.
W003’s example shows only what it flags (linting.md). Its [x] Parent case is removed: W003 reports an open parent, and that parent is closed.
v0.3.0 — 2026-10-13
A minor release: the specifications as of this entry, including every dated entry below down to v0.2.1. It adds Habits to the application graph as a draft (platform Decision 56), specifying the recurring plans v0.2.x left open. Schema $ids are https://clearhead.dev/schemas/v0.3.0/<name>.schema.json.
2026-10-13
Added
Habits in the application graph (ontology.md, draft; platform Decision 56). A charter’s recurring VEVENT is published as an app:Habit with its rule, template and first slot; each occurrence points to its Habit with app:occurrenceOf and names its slot with app:slot. The CCO graph reads a Habit as an action specification with continuant-part occurrences. This replaces the unspecified Recurrence and Recurring plans sections. Fixture coverage is still pending.
Changed
The formatter writes LF line endings (formatting.md 3.2.0). Formatting makes a file regular, so a CRLF file comes back as LF; edits that do not reformat a file, such as stamping a charter ID, keep its line endings. Anyone who wants CRLF can turn formatting off.
The union default graph is a set (ontology.md, Union Default Graph). A triple asserted in several workspace graphs, such as a shared context’s label, matches once in a query without a GRAPH clause. Until now the section said only “union”, and the reference evaluator, using its store’s union mode, returned each cross-workspace row once per workspace that shared a node. The default implementation copies every quad into the default graph when it builds the store.
2026-10-08
Added
A missing additional workspace is skipped, never created (configuration.md, Error Handling). An additional_workspaces entry that does not exist is skipped by every verb with a warning naming it, and doctor reports it. Until now the general “missing directories: create automatically” rule would have recreated a stale path, and implementations differed by verb: reads skipped it silently while delete action failed.
v0.2.1 — 2026-10-06
A patch release: the specification is MIT-licensed. Its contract is unchanged from v0.2.0; schema $ids are https://clearhead.dev/schemas/v0.2.1/<name>.schema.json.
2026-10-06
Changed
The whole specification is MIT-licensed (LICENSE, README.md). Until now only the folded-in ontology carried a license; its MIT license moves to the root and covers everything, prose, schemas, shapes and examples alike, so anyone may implement or build on it, commercially or not. The ontology imports keep their own licenses, credited in the README: CCO, BSD 3-Clause; IAO, CC BY 4.0.
v0.2.0 — 2026-10-04
The second release: the specifications as of this entry, including every dated entry below down to v0.1.0. It is the first published at clearhead.dev (platform Decision 49): schema $ids are https://clearhead.dev/schemas/v0.2.0/<name>.schema.json, and the application vocabulary is https://clearhead.dev/vocab/app/v1#.
2026-10-04
Changed
Identifiers move to clearhead.dev (platform Decision 49). app: is https://clearhead.dev/vocab/app/v1#; the shapes, the ontology’s own IRIs and the example data follow. The context namespace UUID is unchanged: it is a constant, and moving it would rename every context node. The CCO graph’s vocabulary rule rejects terms from either domain, with a new invalid example for an app: term.
The ontology lives here (ontology/; platform Decision 50). The former ontology repository’s V5 content (the header, imports, examples, competency queries and verify rules), its domain.md, DECISIONS.md and license are folded in with their history, beside the mapping. make -C ontology test is its ROBOT gate, run by the platform’s pinned gate; the specification stays inert data.
app:plannedFrom, the planned start’s instant (ontology.md, schemas/app.shapes.ttl, ontology/unmapped.ttl, the graph fixture; platform Decision 53). A derived xsd:dateTime in the viewer’s zone, so queries compare @ as they compare the window, never the written start. Every action with app:plannedStart has it. Its meaning is app:plannedStart’s, so the mapping lists it as unmapped.
Index rows locate an action from the data root (schemas/index_query_result.schema.json; platform Decision 53). charter_root becomes data_root, the workspace’s absolute data root, and source_file is the application graph’s app:file, relative to it (charters/next.actions), so a row and the graph use one path convention. Consumers join data_root and source_file as before. scheduled_at and due_date are as written (app:plannedStart, app:due): a date stays a date. The views filter and sort on the instants app:plannedFrom and app:lateFrom, the effective deadline.
A time is kept as written and resolves as RFC 5545 resolves a local time (action_file_format.md; platform Decision 52). A time without an offset is local to the viewer and written back without one; a written offset is kept. A local time that occurs twice is its first occurrence, and one that does not occur is read with the offset before the gap.
2026-10-03
Added
The mapping from the application vocabulary to CCO (ontology/mapping/*.rq, ontology/unmapped.ttl; platform Decisions 45, 49 and 50). One SPARQL CONSTRUCT per structure; mapping the fixture’s expected-app.ttl yields expected.ttl, and every application term is read by a query or listed in unmapped.ttl with why. The mapping reads effective terms (app:waitsOn, app:notBefore, app:lateFrom), so an inherited wait or window bound is a condition of the child, and each fact is one condition.
Changed
@ takes a range; duration is derived (action_file_format.md, linting.md, ics_schedule_spec.md, ontology.md, schemas/actions.schema.json, schemas/app.shapes.ttl, the mapping; platform Decision 51). @ is a planned start or an ISO 8601 start/end block, half-open, read as a calendar reads one. A date covers its day and a time is an instant, in @ and : alike: written precision no longer matters for times, so :…T17:00 is late from 17:00, not 17:01. Duration is the block’s length, never written: D is read for migration and formatted as a block, durationMinutes leaves the JSON schema, a transaction’s scheduled_at takes @’s value and its duration is gone, and app:durationMinutes is derived. The application graph renames app:start to app:plannedStart and adds app:plannedEnd. E001 is retired, E008 also catches an empty block, and W015 compares the block with the window. Calendar sync carries the block and nothing else: a VEVENT’s DTSTART/DTEND, a VTODO’s DTSTART/DURATION. The window is not synchronized, and a VTODO’s DUE is no longer written or read.
The CCO graph (ontology.md, schemas/graph.shapes.ttl, the graph fixture). Helper nodes are blank nodes; entities keep their IRIs (Decision 49). A window bound’s condition carries the text not before or late from with its effective instant, so the two are told apart by structure rather than by IRI. @ is intent: a Prescriptive ICE that is part of the action, its planned time on a bearer, not a condition and not an act. A metric’s description is carried as dcterms:description.
Removed
A metric’s review_date (objectives.md, schemas/app.shapes.ttl, ontology.md). Reviewing a metric is work: an action, recurring or with a due date, in a charter that serves the objective.
2026-10-02
Changed
: is the window; @ is intent (action_file_format.md, process.md, ontology.md, linting.md, schemas/actions.schema.json, schemas/app.shapes.ttl; platform Decision 48). : takes a deadline or an ISO 8601 interval start/end, a lower bound and a deadline; @ is when the Action is planned and no longer bounds anything or is inherited. A bound covers its written precision, so :…T17:00 is late from 17:01, and the window is half-open. The application graph gains app:availableFrom, the written lower bound; app:notBefore now derives from it instead of app:start. New lints: E008 Empty Window, W015 Planned Outside the Window. Files that used @ to mean “not before” should move that date into :.
v0.1.0 — 2026-09-30
The first release: the specifications as of this entry, including every dated entry below. Releases are described in the README.
Changed
Schema identity names a release, not a branch (schemas/*.json, README.md). Every schema’s $id is now https://raw.githubusercontent.com/ClearHeadToDo-Devs/specifications/v0.1.0/schemas/<name>.schema.json. Six ids named the master branch, so a schema’s identity moved with every commit; actions and charters used github.com/.../schemas/... URLs that did not resolve. Documents that declared a master URL as their $schema should declare the release they follow.
2026-09-26
Changed
The root next.actions is the default capture target (workspace.md, configuration.md, process.md, schemas/config.schema.json). default_file now defaults to next.actions, resolved relative to the workspace’s charters/ directory; the old text said data_dir, which no implementation followed. charters/inbox.actions loses its special status and, where it still exists, is an ordinary child charter named inbox. This finishes the unified workspace root: the root already owned next.actions as its action anchor, but capture still defaulted to the inbox, so choosing between the two files was a decision users had to make on every capture.
2026-09-25
Changed
Charters without a declared state are always New (charters.md, workspace.md). A Charter with no document, the root without charters/README.md included, is New like every newly created Charter; the root no longer loads as Active when its README is missing. New is the planning state: activation is always an explicit, requested transition, and no operation that creates or edits a Charter’s document may change its state as a side effect. clearhead init writes the root as New. Because engagement requires every ancestor to be Active, a workspace is not engaged until its root is activated, so implementations should report a New Charter that owns open actions.
2026-07-18
Removed
Query Output Specification (query_output.md) — relocated out of the shared spec set. Query output has a single producer (clearhead-graphd), so its contract is that tool’s public interface, not cross-implementation law that this repo exists to hold. The move:
- Semantic principles (identity, query-form-follows-shape, ordering, the stateless-producer seam, aggregates) →
clearhead-graphd/docs/query_contract.md, alongside the existing field-level export contract. - CLI presentation (shape×destination;
read→native,query→structured) →clearhead-cli/docs/UI.md.
The core reframe carried across: “one payload, every consumer” became “one semantic payload” — graphd never forks its bytes; lighter presentations are downstream projections a client derives, not the engine serving different masters.
2026-07-05
Added
Query Output Specification v1.0.0 (query_output.md)
- Defines the single JSON-LD output contract for query/view results: one payload for all consumers (clients and integration partners); simple clients read
@graphand ignore@context. No per-consumer serialization. - Canonical identity is semantic
@id, exported to simple clients as compactedid; that identity is what mutation verbs target. - Query form follows data shape —
SELECTfor ordered lists/trees,CONSTRUCTfor networks — while serialization stays JSON-LD either way. - Ordering carried both as
@grapharray position and as sort-key node properties. - Establishes the stateless-producer + verbs-by-identity seam; client widgets (quickfix, DOT) are explicitly client concerns.
2026-01-24
Refactor: move older specifications to archive
Moved a few specifications to Archive folder as we move to an RDF-centric approach:
- sql_schema: no need as RDF does more work
- json_schema: superseded by ontology
- event logging specification as this is now handled by the sync specification
2026-01-18
Changed
Formatting Specification v2.1.0 (formatting.md)
- Breaking: Reduced scope to vertical spacing only (newlines between actions)
- Removed horizontal spacing enforcement - format is whitespace-insensitive by design
- Removed indentation enforcement - depth markers define hierarchy, not whitespace
- Formatter now implemented as Topiary query in
tree-sitter-actions/.topiary/ - No configuration options - formatter does one thing (newlines)
- Dramatically simplified specification
Formatting Specification v2.0.0 (formatting.md)
- Removed list style - single format only
- Removed metadata ordering from formatter scope
Rationale
The .actions format was designed to be whitespace-insensitive: [x]Task$Desc and [x] Task $ Desc are semantically equivalent. Fighting against this with a formatter that enforces specific spacing was adding complexity without clear benefit.
Similarly, hierarchy is defined by depth markers (>, >>, etc.), not by indentation. Enforcing indentation is cosmetic, not semantic.
By reducing the formatter to just “ensure newlines between actions,” we:
- Embrace the format’s whitespace-insensitive design
- Enable simple Topiary implementation (50 lines of queries)
- Move formatting upstream to tree-sitter-actions where it belongs
- Eliminate ~200 lines of Rust formatter code from clearhead-cli
Removed
specifications/examples/formatting/list/- List style test examples removed- Horizontal spacing rules from formatter scope
- Indentation enforcement from formatter scope
indent_widthandindent_styleconfiguration options
2026-01-03
Changed
Formatting Specification v1.1.0 (formatting_specification.md)
- Expanded scope: Formatter now enforces ALL spacing (horizontal + vertical)
- Removed caveats about “recommends but doesn’t enforce horizontal spacing”
- Clarified that spec defines target behavior; implementations work toward conformance
- Updated philosophy to emphasize zero-configuration automatic formatting
- Design principle #5 changed from “Pragmatic scope” to “Zero-configuration”
Linting Specification v1.1.0 (linting_specification.md)
- Breaking change: Removed spacing rules (S001-S004)
- Spacing is now handled entirely by the formatter
- Linter focuses exclusively on semantic correctness, temporal logic, and style preferences
- Reduced from 32 rules to 28 rules (11 errors, 4 warnings, 13 info)
- Updated philosophy section to clarify formatter vs linter boundary
- Renumbered categories: Semantic (1) → Temporal (2) → Style (3) → Content (4)
Rationale
The original design had formatters handling vertical spacing and linters handling horizontal spacing due to tree-sitter grammar limitations. This created an awkward separation where:
- Formatter: vertical layout only
- Linter: horizontal spacing + semantics
New design has clean separation based on user intent:
- Formatter (automatic, opinionated): ALL presentation (horizontal + vertical spacing)
- Linter (configurable, optional): Semantic correctness only
This means formatters must work around grammar limitations (e.g., by serializing from IR with proper spacing rather than trying to edit AST).
Implementation Status (as of 2026-01-03)
clearhead-cli (Rust implementation):
- ✅ Horizontal spacing implemented in
format_as_actions_basic() - ✅ Spec-compliant formatter working
- ⚠️ Topiary disabled (was stripping spacing)
- ⚠️ LSP still using old Topiary path
See clearhead-cli/CHANGELOG.md for detailed implementation notes.